tfm_ainventory/AI_RULES.md

AI AGENT RULES - MANDATORY ENTRY POINT

READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK. This is the Single Source of Truth for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project. (Automatic IDE entry points like GEMINI.md and CLAUDE.md exist solely to redirect agents to this main file). For technical architecture, data models, and stack details, refer to PROJECT_ARCHITECTURE.md.

1. Multi-AI Coordination & Memory

• MANDATORY STARTUP: Every AI session MUST first read dev_docs/SESSION_STATE.md to understand current context.
• MANDATORY HANDOVER: At the end of every task/session, update the handover note in dev_docs/SESSION_STATE.md. Specify: Active AI, Current Status, Technical Context, and Next Steps.
• ARCHIVAL RULE: Before writing new state, move all content of the previous session handover into the top of dev_docs/SESSION_HISTORY.md to prevent bloat.
• NO INTERACTION OVERLAP: Never modify a file if another AI session is explicitly working on it.

2. Global Operational Laws

• STRICT ENGLISH POLICY: All web interfaces, code, variables, scripts, and documentation MUST BE DIRECTLY AND ONLY IN ENGLISH. If you find Romanian text in code, translate it immediately.
• COMMUNICATION LANGUAGE: Conversation with the user will be in Romanian or English (preferably Romanian).
• GIT BINARY PATH: On this macOS environment, the system git is often broken. ALWAYS use the binary path stored in .git_path at the project root for all Git operations.
• COMMIT & PUSH STRICT RULE:
  • Never push to remote (git push) or use force flags (--hard, --force) unless explicitly requested.
  • Always update VERSION.json on every commit.
  • Do NOT add AI co-author signatures (e.g., Co-Authored-By: AI...) to commit messages.
  • Branching: master (stable), dev (active development), vX (archival releases).
• PACKAGE MANAGEMENT: Any new package installed via pip install MUST be added to backend/requirements.txt with version constraints (e.g., slowapi>=0.1.9). Keep requirements.txt synchronized with installed packages.
• MANDATORY LOGGING: Document coding/architecture changes in dev_docs/ARCHIVE_LOGS.md at the end of the task.
• TRIPLE CONFIRMATION (Safe Forget): You cannot delete a physical location, item, or critical entity without explicit user permission three times.

3. UI/UX Fidelity Specifications

• Fidelity First: Never simplify the UI unless asked. Density and aesthetics must remain "Premium".
• Styling: Tailwind CSS. Font weights/spacing must be consistent (Inter/Roboto).
• Readability: NO uppercase or tracking-widest styles. Use standard camel/Title case.
• Icons: Use Lucide Icons exclusively. NO emojis.
• Interactive Affordance: All select/dropdown boxes MUST have a ChevronDown icon. Masked passwords should have reduced opacity (text-white/50).
• Iconography Standardization:
  • Categories: ALWAYS use Layers (Color: text-primary).
  • Item Types: ALWAYS use Package (Color: text-green-500).

4. Documentation Maintenance

• SSOT INTEGRITY: Whenever a feature is added, modified, or removed, you MUST update all corresponding documentation files:
  • README.md (General usage & technical modes).
  • USER_GUIDE.md (End-user instructions).
  • PROJECT_ARCHITECTURE.md (Technical logic & data models).
  • export_prod.sh (If new scripts or files must be included in the production bundle).
• REAL-TIME UPDATES: Documentation updates are NOT optional and must be performed within the same session as the code changes.

6. AI Command Shortcuts

• save-version: When the user triggers this command, the AI MUST:
  1. Increment the patch version in VERSION.json.
  2. Stage all current changes (git add .).
  3. Commit changes with message Build [vX.Y.Z].
  4. Create a new branch named vX.Y.Z from the current state.
  5. Generate a production bundle ZIP (calls ./export_prod.sh).
  6. Stay on the current branch (dev).
  • Implementation: Use python3 scripts/save_version.py to ensure consistency.

7. UI Fidelity Laws (Strict)

• Consistent Layout: All main pages (Inventory, Audit, Admin) MUST use max-w-7xl for their primary content container.
• Unified Headers: Every functional page MUST have an identical header structure:
  • Icon inside a styled box (p-4 bg-primary/10 rounded-[2rem] border border-primary/20).
  • Title: text-3xl font-black text-white tracking-tight.
  • Subtitle: text-xs text-slate-500 font-bold mt-1 tracking-wider.
• Typographic Integrity:
  • NO UPPERCASE (ALL CAPS) allowed anywhere in the UI (headers, labels, buttons, metadata).
  • NO ITALICS in headers, titles, or active UI elements.
  • Consistent font weight (font-black) for main headings.
• Safety Actions:
  • The Logout button MUST be clearly differentiated (e.g., text-rose-500) and MUST always require a window.confirm before execution.

8. Audit & Deletion Policy

• Immutability of Logs: Deleting an Item MUST NOT delete its corresponding entries in the AuditLog table in the database.
• Disk Traceability: Every item deletion MUST be logged to the disk file (logs/backend.log) with USER[id], ITEM[id], Name, and PN.
• Explicit Confirmation: Destructive actions (Delete Item from catalog) MUST always trigger a browser-native window.confirm before proceeding.

5. End of Session Protocol

• Once a phase/task from PLAN.md is completed and verified, move that entry into dev_docs/PLAN_HISTORY.md.
• After finishing an entire job (including updating session state, architecture logs, and versioning), end your final response on a separate line exactly with:

  ---
  ✓ Done.
  

• Do not provide unnecessary verbatim summaries of the code.