Claude/plan v3 deployment vp mpw

AGENTS/AI_CONTRACT.md

@@ -0,0 +1,331 @@
+# AI_CONTRACT.md — Universal AI Agent Contract
+
+> Binding for any AI agent (Claude, GPT, Gemini, or other) in any repo.
+> Stack-agnostic. Derived from the Runewager production development system.
+> Do not modify without appending a note to AGENTS/SESSION_LOG.md.
+
+---
+
+## The Single Invariant
+
+> **The source code, the functionality map, and the wiring index must always
+> agree. No session is complete until all three are in sync.**
+
+Drift between these three causes every class of AI mistake:
+hallucinating behavior that doesn't exist, missing behavior that does exist,
+breaking wiring that was never documented, and leaving the next agent blind.
+
+---
+
+## Pre-Session: Bootstrap (Mandatory — Do This First)
+
+Before reading any source file or writing any code, verify and create missing
+documentation paths. This is not optional. A repo with missing docs is a repo
+where AI agents will hallucinate.
+
+### Check and create each path if missing:
+
+```
+FUNCTIONALITY_MAP.md
+  → If missing: create from AGENTS/MAP_TEMPLATE.md
+  → Run a quick codebase scan to populate it with real entry points,
+    real file names, real data stores. Never create it with placeholder
+    content that doesn't reflect the actual repo.
+
+docs/INDEX.md
+  → If missing: create from AGENTS/INDEX_TEMPLATE.md
+  → Populate the wiring tables with every entry point found during scan.
+
+docs/features/
+  → If missing: create the directory.
+  → Do not create feature files yet — create them as features are touched.
+
+todolist.md
+  → If missing: create from AGENTS/TODOLIST_TEMPLATE.md
+  → Add any obviously open tasks discovered during the bootstrap scan.
+
+AGENTS/SESSION_LOG.md
+  → If missing: create it with the header from AGENTS/SESSION_LOG.md template.
+  → Never delete or overwrite existing entries. Append only.
+```
+
+### Bootstrap scan — what to look for:
+
+When creating `FUNCTIONALITY_MAP.md` and `docs/INDEX.md` fresh, scan the repo for:
+
+- **Entry points:** command handlers, route definitions, event listeners,
+  cron job registrations, webhook receivers, button/action handlers, CLI arg
+  parsers, IPC message handlers, socket event handlers, queue consumers.
+- **State:** databases, in-memory stores (Map, Set, dict, hash), file
+  persistence, session/cookie storage, cache layers, environment variables.
+- **Process management:** systemd unit files (`.service`), pm2 config
+  (`ecosystem.config.js`, `pm2.config.cjs`), Procfile, docker-compose.yml,
+  supervisor conf.
+- **Test files:** `test/`, `tests/`, `spec/`, `__tests__/`, `*.test.*`,
+  `*.spec.*`.
+- **Deploy scripts:** `deploy.sh`, `prod-run.sh`, `Makefile`, CI workflow
+  files (`.github/workflows/`).
+- **Config:** `.env.example`, `config/`, `settings.py`, `appsettings.json`.
+- **Health/metrics:** `/health` endpoints, `/metrics`, uptime scripts,
+  monitoring hooks.
+
+---
+
+## Article 1 — Pre-Session Reads (Mandatory)
+
+After bootstrap, read in this order before writing any code:
+
+1. `AGENTS/CLAUDE.md` — operating manual for this repo.
+2. `FUNCTIONALITY_MAP.md` — what the system does, how it behaves.
+3. `docs/INDEX.md` — how every piece is wired together.
+4. `todolist.md` — what is open, in-progress, blocked, and done.
+5. The specific section of `FUNCTIONALITY_MAP.md` for the area being changed.
+6. The specific source file(s) for the code being changed.
+
+Do not skip any of these. An agent that writes code without reading the map
+is operating on assumptions, not facts.
+
+---
+
+## Article 2 — The Universal Wiring Index Rule
+
+`docs/INDEX.md` is the **Universal Wiring Index**. It must capture every
+way functionality is invoked, handled, and connected — for any stack.
+
+### What goes in the wiring index (stack-agnostic terms):
+
+| Category | Examples by stack |
+|----------|-------------------|
+| **Entry points** | `/command` (bot), `GET /route` (web), `cli subcommand` (CLI), `screen name` (mobile), `menu item` (desktop), `queue.consume()` (service), `socket.on('event')` (realtime), `cron('0 * * * *')` (scheduled) |
+| **Handlers** | Function name, file path, line number range |
+| **State reads** | Which store/db/variable/session the handler reads |
+| **State mutations** | What the handler writes, creates, deletes, or updates |
+| **UI/UX output** | What the user/caller sees — screen, message, response body, side effect |
+| **Guards/permissions** | Who can invoke this — role check, auth middleware, API key, rate limit |
+| **Error paths** | What happens on failure — error message, fallback, retry, alert |
+| **Wiring connections** | What this calls, emits, publishes, or triggers in other parts of the system |
+
+### Format:
+
+```markdown
+## Entry Point Index
+
+| Entry Point | Type | Handler | File:Line | State Read | State Write | Output | Guard | Error Path |
+|------------|------|---------|-----------|------------|-------------|--------|-------|------------|
+| /start     | Command | handleStart() | index.js:412 | userStore | user.onboarding | Onboarding card | none | "Already started" reply |
+| GET /api/users | Route | getUsers() | routes/users.js:28 | db.users | none | JSON array | requireAuth | 401 / 500 |
+| checkout button | UI event | submitOrder() | checkout.js:89 | cart, session | orders, cart | Confirmation screen | loggedIn | Error toast |
+| order.created | Queue event | processOrder() | workers/order.js:14 | orders | inventory, email_queue | none (async) | none | dead-letter queue |
+| */5 * * * * | Cron | runCleanup() | jobs/cleanup.js:5 | sessions | sessions | none | none | admin alert |
+```
+
+### Index must be updated when:
+
+| Change | Index update required |
+|--------|-----------------------|
+| New entry point added (command, route, action, event, job) | Add row |
+| Entry point removed | Remove row |
+| Handler function renamed or moved | Update Handler + File:Line |
+| State the handler reads or writes changes | Update State Read / State Write |
+| Output changes (new screen, new response shape, new side effect) | Update Output |
+| Guard/permission added, removed, or changed | Update Guard |
+| New wiring connection (calls a new service, emits new event) | Update Wiring connections |
+
+---
+
+## Article 3 — During-Session Rules
+
+1. Add tasks to `todolist.md` before starting them.
+2. Mark the current task `[~]` before beginning it.
+3. Make the minimal change that satisfies the requirement.
+4. Do not refactor, rename, or restructure code unrelated to the current task.
+5. If blocked: mark `[BLOCKED: <reason>]`, move to next priority task. Do not
+   wait. Do not retry the same blocked path more than twice.
+6. Verify immediately after each task (run tests, syntax check, or trace).
+7. Mark `[x]` done immediately after verification.
+
+---
+
+## Article 4 — Post-Session Sync (Mandatory Before Commit)
+
+### 4.1 — Functionality Map
+
+Update `FUNCTIONALITY_MAP.md` to reflect real code state:
+
+- New entry point → add to the relevant section + Commands/Endpoints Index.
+- Removed entry point → remove it. Do not leave stale entries.
+- Changed behavior → update the description. Do not describe intended behavior.
+- New flow or feature → add a new section.
+- Changed state machine → update the state machine table.
+- Changed config, env vars, infra → update Architecture Notes.
+- Changed process manager config → update Process Management section.
+
+### 4.2 — Wiring Index
+
+Update `docs/INDEX.md`:
+
+- Any entry point change → update the Entry Point Index table.
+- Any handler rename or move → update Handler and File:Line columns.
+- Any state change → update State Read / State Write columns.
+- Any new inter-system connection → add to wiring connections.
+
+### 4.3 — Feature Doc
+
+If `docs/features/<name>.md` exists for the changed area:
+
+- Update flow steps to match new code behavior.
+- Update edge cases, timeouts, validation rules.
+- Update related entry points and handlers.
+
+If no feature doc exists and the change is non-trivial: create one.
+
+### 4.4 — Session Log
+
+Append to `AGENTS/SESSION_LOG.md`:
+
+```markdown
+### YYYY-MM-DD — <title>
+
+**Scope:** <files / features / systems touched>
+**Changes:**
+- <what changed>
+- <what changed>
+**Tests:** pass / fail / N/A — <test command used>
+**Map updated:** yes / partial / no — <what was updated>
+**Index updated:** yes / partial / no
+**Open items:** <anything deferred with reason>
+```
+
+### 4.5 — Final Verification Checklist
+
+Before committing:
+
+- [ ] All tests pass (or confirmed N/A with reason documented)
+- [ ] `FUNCTIONALITY_MAP.md` matches code behavior — not intended behavior
+- [ ] `docs/INDEX.md` has no dead references or missing entry points
+- [ ] No debug code, `console.log`, `print()`, or `TODO` comments left in source
+- [ ] No secrets in any committed file
+- [ ] `todolist.md` reflects current state
+- [ ] Session log appended
+
+---
+
+## Article 5 — Definition of Done
+
+A task is done when ALL of the following are true:
+
+- [ ] Code change is implemented and working.
+- [ ] Code change is verified (automated or manual).
+- [ ] `FUNCTIONALITY_MAP.md` reflects the change.
+- [ ] `docs/INDEX.md` reflects the change.
+- [ ] Feature doc reflects the change (if one exists).
+- [ ] Session log is updated.
+- [ ] Task is marked `[x]` in `todolist.md`.
+
+A task that passes code review but has no map update is **not done**.
+A task with a map update but failing tests is **not done**.
+A task marked done but not in the session log **did not happen**.
+
+---
+
+## Article 6 — Commands/Entry Points Guard Rule
+
+For any system with a defined set of owned commands, routes, or entry points:
+
+**Any time an entry point is added or removed, the guard set (or equivalent
+registry) that controls routing/access must be updated in the same commit.**
+
+Examples:
+- Telegram bot: `BOT_KNOWN_COMMANDS` set must match `bot.command()` registrations.
+- Express app: route registry or OpenAPI spec must match `app.get/post/...`.
+- CLI tool: command registry must match `program.command(...)` registrations.
+- Event system: subscribed event list must match `socket.on(...)` or `bus.subscribe(...)`.
+
+A command/route/event that exists in code but not in the registry is invisible
+to guards and audits. A command in the registry but not in code causes false
+positives in validation. Both cause drift.
+
+---
+
+## Article 7 — Anti-Hallucination Rules
+
+These rules directly prevent AI agents from inventing behavior:
+
+1. **Never describe a feature as working unless you have read the code that
+   implements it.** Not the comment. Not the doc. The code.
+2. **Never add a feature to the map that isn't in the code.** Maps describe
+   reality, not plans.
+3. **Never assume a function signature, parameter name, or return value without
+   reading its definition.** Grep for it. Read it.
+4. **Never assume a behavior is unchanged because you didn't touch it.** Other
+   code may call it. Check callers.
+5. **Never write a test for behavior you haven't verified exists in the code.**
+6. **Never write error handling for an error that cannot happen.** Read the
+   code path and confirm the error condition is reachable.
+
+---
+
+## Article 8 — Safety Rules
+
+- Never expose secrets, tokens, API keys, or credentials in any committed file.
+- Never commit a `.env` file.
+- Never run destructive operations without explicit user confirmation:
+  `rm -rf`, `DROP TABLE`, `git reset --hard`, `git push --force` to main,
+  `pm2 delete all`, `docker system prune -a`.
+- Never mark done when tests fail.
+- Never modify code you have not read.
+- Never skip the pre-session map read.
+
+---
+
+## Article 9 — Escalation
+
+Stop and report before continuing when:
+
+- Map and code contradict each other and context doesn't resolve it.
+- Tests that passed before your session now fail for unrelated reasons.
+- The task touches auth, permissions, credentials, or external APIs.
+- The task requires a destructive operation.
+- The scope is substantially larger than described.
+- You would need to change behavior used in more than three places in the system.
+- The correct behavior is genuinely ambiguous between two interpretations.
+
+---
+
+## Appendix A — Stack-Specific Contract Addendum
+
+Fill in when first applying this contract to a repo:
+
+```markdown
+### Project: <name>
+**Entry point:** <file>
+**Entry point guard:** <BOT_KNOWN_COMMANDS / route registry / command registry>
+**Test command:** <npm test / pytest / go test ./... / cargo test>
+**Syntax check:** <node --check / mypy / cargo check / eslint>
+**Deploy command:** <./prod-run.sh / pm2 reload / systemctl restart / docker compose up>
+**Process manager:** <systemd / pm2 / docker / supervisor / bare>
+**Health check:** <curl http://localhost:PORT/health / pm2 status / systemctl status>
+**Persistence:** <what data lives where and how often it's saved>
+**Project-specific rules:**
+- <any rule that extends or overrides the universal contract>
+```
+
+---
+
+## Appendix B — Universal Development Cycle
+
+```
+READ                    PLAN                    CODE
+────────────────────    ────────────────────    ────────────────────
+FUNCTIONALITY_MAP  →    todolist.md         →   source files
+docs/INDEX.md           prioritize tasks        minimal changes
+feature docs            mark [~] current        no side quests
+source files            identify doc targets    verify each task
+
+SYNC                    CLOSE
+────────────────────    ────────────────────
+FUNCTIONALITY_MAP  →    run full tests
+docs/INDEX.md           commit: code + docs
+feature doc             push to branch
+SESSION_LOG
+```