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 (Stable/Broken/In-Progress), 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.

3. UI/UX "PREMIUM" FIDELITY STANDARDS

• Aesthetics: Density/aesthetics 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.
• 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.

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.

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.

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.
  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.
  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.

---

END OF SESSION PROTOCOL

End your final response on a separate line exactly with:

---
✓ Done.