tfm_ainventory/AI_RULES.md

AI AGENT RULES - MANDATORY SSOT ENTRY POINT

READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK. This is the Single Source of Truth for ALL AI agents. Refer to PROJECT_ARCHITECTURE.md for technical logic.

---

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, 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.
• 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 must remain "Premium". Use Tailwind CSS. NO simplification.
• Typography Rules:
  • 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).
• Iconography: Use Lucide Icons exclusively.

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. 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: Update ALL documentation with explanations of current changes.
  1. Increment VERSION.json.
  2. Git add/commit (Build [vX.Y.Z]).
  3. Create snapshot branch.
  4. Merge into master.
  5. Run ./export_prod.sh. (Command: python3 scripts/save_version.py).

---

Status: ACTIVE