chore: major codebase cleanup and documentation consolidation
This commit is contained in:
94
AI_RULES.md
94
AI_RULES.md
@@ -8,84 +8,54 @@ This is the **Single Source of Truth** for ALL AI agents. Refer to [PROJECT_ARCH
|
||||
## 1. AI MEMORY, TRACEABILITY & HANDOVER
|
||||
- **MANDATORY STARTUP**: Read `dev_docs/SESSION_STATE.md` immediately at session start.
|
||||
- **PLAN RETIREMENT**: Mark a completed "Master Plan" as `[COMPLETED]` in the file itself. Move technical details to `dev_docs/ARCHIVE_LOGS.md` and `PLAN.md` entries to `dev_docs/PLAN_HISTORY.md`.
|
||||
- **STRICT HANDOVER**: Update `dev_docs/SESSION_STATE.md` at the end of every task with: **Active AI**, **Current Status** (Stable/Broken/In-Progress), **Context**, and **Next Steps**.
|
||||
- **STRICT HANDOVER**: Update `dev_docs/SESSION_STATE.md` at the end of every task with: **Active AI**, **Current Status**, **Context**, and **Next Steps**.
|
||||
- **SESSION ARCHIVE**: Move previous handover content to `dev_docs/SESSION_HISTORY.md` before writing new state.
|
||||
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it.
|
||||
- **CONCISE COMMUNICATION**: Be concise! Do not explain a thousand details unless they are absolutely necessary.
|
||||
|
||||
## 2. ENGINEERING & OPERATIONAL LAWS
|
||||
- **ENGLISH ONLY**: Interfaces, code, variables, and docs MUST be in English. Translate any Romanian text found in code immediately. (User conversation: Romanian/English).
|
||||
- **GIT PROTOCOL**: Use `git` command from system PATH for all operations. On Linux, this is provided by the git package manager. Git operations use the fallback mechanism in `.git_path` file for cross-platform compatibility. Never push or use `--force` unless explicitly asked. Branching: `master` (stable), `dev` (active), `vX` (archive).
|
||||
- **VERSIONING**: Update `VERSION.json` on every commit. Use `scripts/save_version.py` for automated releases.
|
||||
- **DEPENDENCIES**: Update `backend/requirements.txt` with version constraints for every new pip package.
|
||||
- **SSOT INTEGRITY**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `PROJECT_ARCHITECTURE.md`, and `export_prod.sh`.
|
||||
- **ENGLISH ONLY**: Interfaces, code, variables, and docs MUST be in English. Translate any Romanian text found in code immediately.
|
||||
- **GIT PROTOCOL**: Use system `git`. Never push or use `--force` unless explicitly asked.
|
||||
- **VERSIONING**: Update `VERSION.json` on every commit using `scripts/save_version.py`.
|
||||
- **SSOT INTEGRITY**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `PROJECT_ARCHITECTURE.md`, `DEPLOYMENT.md`, and `dev_docs/PLAN.md`.
|
||||
- **CODE QUALITY**: Files under 300 lines, complexity < 10, strict Single Responsibility Principle.
|
||||
|
||||
## 3. UI/UX "PREMIUM" FIDELITY STANDARDS
|
||||
- **Aesthetics**: Density/aesthetics must remain "Premium". Use Tailwind CSS. NO simplification.
|
||||
- **Aesthetics**: Density must remain "Premium". Use Tailwind CSS. NO simplification.
|
||||
- **Typography Rules**:
|
||||
- **NO UPPERCASE** or **NO ITALICS** in headers, labels, buttons, or metadata.
|
||||
- **NO `tracking-widest`**. Use standard camel/Title case.
|
||||
- **NO BOLD FONTS**: Use `font-normal` throughout (no `font-black`, `font-bold`, or `font-semibold`). Text hierarchy maintained through font-size and color differences.
|
||||
- **NO UPPERCASE** or **NO ITALICS** in any UI context (headers, labels, buttons).
|
||||
- **NO BOLD FONTS**: Use `font-normal` throughout. Hierarchy via size and color only.
|
||||
- **NO `tracking-widest`**.
|
||||
- **Layout**: Main pages MUST use `max-w-7xl`.
|
||||
- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-normal`) + Subtitle (`text-xs text-slate-500`).
|
||||
- **Iconography**: Use **Lucide Icons** exclusively (NO emojis).
|
||||
- **Categories**: `Layers` (text-primary).
|
||||
- **Item Types**: `Package` (text-green-500).
|
||||
- **Affordance**: Dropdowns MUST have a `ChevronDown`. Passwords: `text-white/50`. Logout MUST be `text-rose-500`.
|
||||
- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-normal`).
|
||||
- **Iconography**: Use **Lucide Icons** exclusively.
|
||||
|
||||
## 4. DATA INTEGRITY & AUDIT POLICY
|
||||
- **RESTRICTED ACTIONS**: `DELETE /items/` and Admin settings require `auth.get_current_admin`.
|
||||
- **AUDIT IMMUTABILITY**: Deleting an `Item` MUST NOT delete its `AuditLog` entries.
|
||||
- **TRACEABILITY**: Log deletions to `logs/backend.log` with `USER[id]`, `ITEM[id]`, `Name`, `PN`.
|
||||
- **CONFIRMATION**:
|
||||
- **Triple Confirmation**: Deleting critical entities (Locations/Items) requires user confirmation 3 times.
|
||||
- **Native Alerts**: Use `window.confirm` for all destructive UI actions and Logout.
|
||||
## 4. REFACTORING & TESTING STRATEGY (MANDATORY)
|
||||
- **TEST-FIRST**: All tests must be written and passing BEFORE refactoring any code.
|
||||
- **ZERO REGRESSION**: 100% of existing tests must pass post-refactor.
|
||||
- **GATING**:
|
||||
- **Backend**: Pytest coverage target 85%+ (`backend/tests/`).
|
||||
- **Frontend**: Vitest coverage target 80%+ (`frontend/tests/`).
|
||||
- **E2E**: Critical workflows in Playwright (`frontend/e2e/`).
|
||||
- **MODULARITY**: Break monolithic files into focused modules (<300 lines). Extract logic into hooks/services.
|
||||
|
||||
## 5. MANDATORY AUTHENTICATION SECURITY POLICY
|
||||
|
||||
**CRITICAL**: Authentication is NEVER disabled. Not in development, not in production, not in any environment.
|
||||
|
||||
- **NO AUTH BYPASS**: Never implement auth bypass, debug mode to skip auth, or dev-only auth disabling.
|
||||
- **NO HARDCODED CREDENTIALS**: Credentials must be initialized through proper database migrations or admin setup scripts.
|
||||
- **NO WEAK DEFAULTS**: No default usernames like "admin/admin" in production deployments.
|
||||
- **LOGIN ALWAYS REQUIRED**: Every API endpoint must require valid JWT token via `auth.get_current_user`.
|
||||
- **CREDENTIAL MANAGEMENT**: Use proper password hashing (passlib with pbkdf2_sha256), never plain text.
|
||||
- **IF AUTH BREAKS**: Debug by:
|
||||
1. Verifying database contains users
|
||||
2. Testing password hashing in isolation
|
||||
3. Checking session/transaction isolation
|
||||
4. Reviewing logs for SQL errors
|
||||
5. **NEVER skip authentication** - always fix the root cause
|
||||
- **DOCUMENTATION**: Auth configuration must be clearly documented in `STANDALONE_DEPLOYMENT.md` with proper setup steps.
|
||||
|
||||
This rule supersedes any convenience or testing shortcuts. Security is non-negotiable.
|
||||
## 5. DATA INTEGRITY & SECURITY POLICY
|
||||
- **RESTRICTED ACTIONS**: Destructive actions (DELETE) require Admin role.
|
||||
- **AUDIT IMMUTABILITY**: Deleting an item MUST NOT delete its audit log.
|
||||
- **NO AUTH BYPASS**: Authentication is NEVER disabled in any environment.
|
||||
- **TRIPLE CONFIRMATION**: Deleting critical entities requires 3 confirmations.
|
||||
- **NATIVE ALERTS**: Use `window.confirm` for destructive UI actions.
|
||||
- **CREDENTIALS**: initialized via migrations/scripts. NEVER hardcoded or logged.
|
||||
|
||||
## 6. AI COMMAND SHORTCUTS
|
||||
- **`save-version`**:
|
||||
0. **MANDATORY**: Verify and update ALL documentation (`.md` files: README, USER_GUIDE, ARCHITECTURE, etc.) with explanations of all current changes.
|
||||
0. **MANDATORY**: Update ALL documentation with explanations of current changes.
|
||||
1. Increment `VERSION.json`.
|
||||
2. Git add/commit (`Build [vX.Y.Z]`).
|
||||
3. Create branch `vX.Y.Z` (Snapshot).
|
||||
4. Automatic Sync: Merge changes into `master` branch to keep it up-to-date.
|
||||
3. Create snapshot branch.
|
||||
4. Merge into `master`.
|
||||
5. Run `./export_prod.sh`.
|
||||
(Always use `python3 scripts/save_version.py`).
|
||||
|
||||
## 6. Implementation Completion
|
||||
- All code modifications MUST be committed in git before the task is considered finished. `VERSION.json` must be updated on EACH commit.
|
||||
- **MANDATORY GIT RULE:** Never push to remote unless explicitly requested by the user. Only commit locally with proper messages. Always assume the user will handle all `git push` operations. If a task requires pushing, ask for explicit permission first.
|
||||
- **MANDATORY GIT RULE**: NO AI is allowed to write in git commits that it is the author or co-author (e.g., DO NOT add texts like `Co-Authored-By: AI...`). Commits should only contain technical messages.
|
||||
- After finishing an entire job, end your final response on a separate line exactly with:
|
||||
```
|
||||
---
|
||||
✓ Done.
|
||||
```
|
||||
- Do not provide unnecessary summaries of the code.
|
||||
(Command: `python3 scripts/save_version.py`).
|
||||
|
||||
---
|
||||
|
||||
## END OF SESSION PROTOCOL
|
||||
End your final response on a separate line exactly with:
|
||||
```
|
||||
---
|
||||
✓ Done.
|
||||
```
|
||||
**Status**: ACTIVE
|
||||
|
||||
Reference in New Issue
Block a user