Merge pull request 'feat: Migrate Gemini SDK to google-genai (#231)' (#236) from issue-231-migrate-gemini-sdk-google-genai into main

Reviewed-on: #236

.ai/CLAUDE.md

@@ -0,0 +1,11 @@
+# .ai/
+
+AI context and workflow configuration for Claude Code.
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `context.json` | Architecture metadata, feature registry | Understanding system structure |
+| `workflow-contract.json` | Sprint workflow, issue lifecycle | Issue/PR workflow, labels |
+| `WORKFLOW-PROMPTS.md` | Workflow prompt templates | Workflow automation |

.ai/WORKFLOW-PROMPTS.md

@@ -0,0 +1,162 @@
+# MotoVaultPro Workflow Prompts
+
+Ready-to-use prompts for the sprint workflow. Copy and customize as needed.
+
+---
+
+## Prompt 1: Start Sprint Work (Pick Up an Issue)
+
+```
+*** ROLE ***
+You are senior software architect on MotoVaultPro. Follow the sprint workflow in `.ai/workflow-contract.json`. 
+
+*** ACTION ***
+1. Read `.ai/context.json` and `.ai/workflow-contract.json`
+2. Check the current sprint milestone via Gitea MCP
+3. List issues with `status/ready` label
+4. If none ready, show me `status/backlog` issues and recommend which to promote
+5. Present the top 3 candidates ranked by priority/size
+6. Dispatch multiple agents for their specific tasks. 
+```
+
+---
+
+## Prompt 2: Work On a Specific Issue
+
+```
+*** ROLE ***
+You are the [feature-agent | frontend-agent | platform-agent]. Read your agent file at `.claude/agents/[agent]-agent.md`.
+
+*** CONTEXT ***
+- Read `.ai/workflow-contract.json` for sprint workflow
+- Issue to work on: #[NUMBER]
+
+*** ACTION ***
+1. Get issue details via `mcp__gitea-mcp__get_issue_by_index`
+2. Move issue to `status/in-progress`
+3. Create branch `issue-[NUMBER]-[slug]`
+4. Implement the acceptance criteria
+5. Open PR when complete and move to `status/review`
+```
+
+---
+
+## Prompt 3: Quality Validation
+
+```
+*** ROLE ***
+You are the quality-agent. Read `.claude/agents/quality-agent.md`.
+
+*** ACTION ***
+1. List issues with `status/review` label
+2. For each issue awaiting validation:
+   - Read acceptance criteria
+   - Run all quality gates (linting, type-check, tests, mobile+desktop)
+   - Report PASS or FAIL with specific details
+3. If PASS: approve PR, move issue to `status/done` after merge
+4. If FAIL: comment on issue with required fixes
+```
+
+---
+
+## Prompt 4: Sprint Planning Session
+
+```
+*** ROLE ***
+You are helping plan Sprint [YYYY-MM-DD].
+
+*** ACTION ***
+1. Check if milestone exists via `mcp__gitea-mcp__list_milestones`
+2. If not, create it via `mcp__gitea-mcp__create_milestone`
+3. List all `status/backlog` issues
+4. Recommend issues to promote to `status/ready` for this sprint
+5. Consider: dependencies, priority, size, and sprint capacity
+```
+
+---
+
+## Prompt 5: Create New Issue
+
+```
+*** ROLE ***
+Use the Gitea MCP to create a new issue.
+
+*** CONTEXT ***
+- Type: [feature | bug | chore | docs]
+- Title: [TITLE]
+- Description: [DESCRIPTION]
+
+*** ACTION ***
+1. Create issue via `mcp__gitea-mcp__create_issue`
+2. Add labels: `type/[type]` and `status/backlog`
+3. Optionally assign to current sprint milestone
+```
+
+---
+
+## Prompt 6: Sprint Status Report
+
+```
+*** ROLE ***
+Generate a sprint status report.
+
+*** ACTION ***
+1. Get current sprint milestone via `mcp__gitea-mcp__list_milestones`
+2. List all issues in the sprint milestone
+3. Group by status label (ready, in-progress, review, done, blocked)
+4. Calculate: total issues, completed, remaining, blocked
+5. Present summary with any blockers highlighted
+```
+
+---
+
+## Prompt 7: End of Sprint Review
+
+```
+*** ROLE ***
+Conduct end-of-sprint review for Sprint [YYYY-MM-DD].
+
+*** ACTION ***
+1. List all issues that were in this sprint milestone
+2. Summarize: completed (status/done), incomplete, blocked
+3. For incomplete issues: recommend carry-over to next sprint or return to backlog
+4. Create next sprint milestone if it doesn't exist
+5. Move carry-over issues to new sprint milestone
+```
+
+---
+
+## Quick Reference: MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__gitea-mcp__list_repo_issues` | List issues (filter by state/milestone) |
+| `mcp__gitea-mcp__get_issue_by_index` | Get issue details |
+| `mcp__gitea-mcp__create_issue` | Create new issue |
+| `mcp__gitea-mcp__edit_issue` | Update issue (title, body, state) |
+| `mcp__gitea-mcp__add_issue_labels` | Add labels to issue |
+| `mcp__gitea-mcp__remove_issue_label` | Remove label from issue |
+| `mcp__gitea-mcp__replace_issue_labels` | Replace all labels on issue |
+| `mcp__gitea-mcp__list_milestones` | List sprint milestones |
+| `mcp__gitea-mcp__create_milestone` | Create new sprint |
+| `mcp__gitea-mcp__create_branch` | Create feature branch |
+| `mcp__gitea-mcp__create_pull_request` | Open PR |
+| `mcp__gitea-mcp__list_repo_pull_requests` | List PRs |
+
+---
+
+## Label Reference
+
+**Status Labels** (exactly one per issue):
+- `status/backlog` - Not yet ready to work on
+- `status/ready` - Ready to be picked up
+- `status/in-progress` - Currently being worked on
+- `status/review` - PR open, awaiting validation
+- `status/blocked` - Cannot proceed (document blocker)
+- `status/done` - Completed and merged
+
+**Type Labels** (exactly one per issue):
+- `type/feature` - New capability
+- `type/bug` - Something broken
+- `type/chore` - Maintenance/refactor
+- `type/docs` - Documentation only

.ai/context.json

@@ -1,6 +1,43 @@
 {
-  "version": "6.0.0",
+  "version": "6.2.0",
-  "architecture": "simplified-5-container",
+  "architecture": "9-container",
+  "repository": {
+    "host": "gitea",
+    "owner": "egullickson",
+    "repo": "motovaultpro",
+    "url": "https://git.motovaultpro.com",
+    "default_branch": "main"
+  },
+  "ai_quick_start": {
+    "load_order": [
+      ".ai/context.json (this file) - architecture and metadata",
+      ".ai/workflow-contract.json - sprint workflow for issue tracking",
+      ".ai/WORKFLOW-PROMPTS.md - ready-to-use prompts for common tasks",
+      "docs/README.md - documentation hub"
+    ],
+    "work_modes": {
+      "feature_work": "backend/src/features/{feature}/ (start with README.md)",
+      "frontend_work": "frontend/README.md",
+      "core_backend": "backend/src/core/README.md"
+    },
+    "commands": {
+      "setup": "make setup | start | rebuild | migrate | logs",
+      "shells": "make shell-backend | make shell-frontend",
+      "database": "make db-shell-app"
+    },
+    "docs_hubs": {
+      "main": "docs/README.md",
+      "testing": "docs/TESTING.md",
+      "database": "docs/DATABASE-SCHEMA.md",
+      "security": "docs/SECURITY.md",
+      "vehicles_api": "docs/VEHICLES-API.md"
+    },
+    "urls": {
+      "frontend": "https://motovaultpro.com",
+      "backend_health": "https://motovaultpro.com/api/health",
+      "hosts_entry": "127.0.0.1 motovaultpro.com"
+    }
+  },
   "critical_requirements": {
     "mobile_desktop_development": "ALL features MUST be implemented and tested on BOTH mobile and desktop",
     "context_efficiency": "95%",
@@ -15,7 +52,7 @@
     "project_overview": {
       "instruction": "Start with README.md for complete architecture context",
       "files": ["README.md"],
-      "completeness": "100% - all navigation and 5-container architecture information"
+      "completeness": "100% - all navigation and 9-container architecture information"
     },
     "application_feature_work": {
       "instruction": "Load entire application feature directory (features are modules within backend)",
@@ -68,6 +105,26 @@
       "type": "cache",
       "description": "Redis cache with AOF persistence",
       "port": 6379
+    },
+    "mvp-ocr": {
+      "type": "ocr_service",
+      "description": "Python OCR service with pluggable engine abstraction (PaddleOCR PP-OCRv4 primary, optional Google Vision cloud fallback, Tesseract backward compat)",
+      "port": 8000
+    },
+    "mvp-loki": {
+      "type": "log_aggregation",
+      "description": "Grafana Loki for centralized log storage (30-day retention)",
+      "port": 3100
+    },
+    "mvp-alloy": {
+      "type": "log_collector",
+      "description": "Grafana Alloy for log collection and forwarding to Loki",
+      "port": 12345
+    },
+    "mvp-grafana": {
+      "type": "log_visualization",
+      "description": "Grafana for log querying and visualization",
+      "port": 3000
     }
   },
   "application_features": {
@@ -79,12 +136,29 @@
       "description": "Admin role management, platform catalog CRUD, station oversight",
       "status": "implemented"
     },
-    "vehicles": {
+    "auth": {
-      "path": "backend/src/features/vehicles/",
+      "path": "backend/src/features/auth/",
       "type": "core_feature",
       "self_contained": true,
-      "database_tables": ["vehicles"],
+      "database_tables": [],
-      "cache_strategy": "User vehicle lists: 5 minutes",
+      "description": "User signup, email verification workflow using Auth0",
+      "status": "implemented"
+    },
+    "backup": {
+      "path": "backend/src/features/backup/",
+      "type": "admin_feature",
+      "self_contained": true,
+      "database_tables": ["backup_schedules", "backup_history", "backup_settings"],
+      "storage": "/app/data/backups/",
+      "description": "Manual and scheduled database/document backups with retention policies",
+      "status": "implemented"
+    },
+    "documents": {
+      "path": "backend/src/features/documents/",
+      "type": "independent_feature",
+      "self_contained": true,
+      "database_tables": ["documents"],
+      "storage": "/app/data/documents/",
       "status": "implemented"
     },
     "fuel-logs": {
@@ -105,21 +179,23 @@
       "cache_strategy": "Upcoming maintenance: 1 hour",
       "status": "implemented"
     },
-    "stations": {
+    "notifications": {
-      "path": "backend/src/features/stations/",
+      "path": "backend/src/features/notifications/",
-      "type": "independent_feature",
+      "type": "dependent_feature",
       "self_contained": true,
-      "external_apis": ["Google Maps API"],
+      "depends_on": ["maintenance", "documents"],
-      "database_tables": ["stations", "community_stations"],
+      "database_tables": ["email_templates", "notification_logs", "sent_notification_tracker", "user_notifications"],
-      "cache_strategy": "Station searches: 1 hour",
+      "external_apis": ["Resend"],
+      "description": "Email and toast notifications for maintenance due/overdue and expiring documents",
       "status": "implemented"
     },
-    "documents": {
+    "onboarding": {
-      "path": "backend/src/features/documents/",
+      "path": "backend/src/features/onboarding/",
-      "type": "independent_feature",
+      "type": "dependent_feature",
       "self_contained": true,
-      "database_tables": ["documents"],
+      "depends_on": ["user-profile", "user-preferences"],
-      "storage": "/app/data/documents/",
+      "database_tables": [],
+      "description": "User onboarding flow after email verification (preferences, first vehicle)",
       "status": "implemented"
     },
     "platform": {
@@ -130,11 +206,61 @@
       "cache_strategy": "Vehicle hierarchical data: 6 hours",
       "description": "Vehicle hierarchical data lookups (years, makes, models, trims, engines). VIN decoding is planned/future.",
       "status": "implemented_vin_decode_planned"
+    },
+    "stations": {
+      "path": "backend/src/features/stations/",
+      "type": "independent_feature",
+      "self_contained": true,
+      "external_apis": ["Google Maps API"],
+      "database_tables": ["stations", "community_stations"],
+      "cache_strategy": "Station searches: 1 hour",
+      "status": "implemented"
+    },
+    "terms-agreement": {
+      "path": "backend/src/features/terms-agreement/",
+      "type": "core_feature",
+      "self_contained": true,
+      "database_tables": ["terms_agreements"],
+      "description": "Legal audit trail for Terms & Conditions acceptance at signup",
+      "status": "implemented"
+    },
+    "user-export": {
+      "path": "backend/src/features/user-export/",
+      "type": "independent_feature",
+      "self_contained": true,
+      "depends_on": ["vehicles", "fuel-logs", "documents", "maintenance"],
+      "database_tables": [],
+      "description": "GDPR-compliant user data export (vehicles, logs, documents as TAR.GZ)",
+      "status": "implemented"
+    },
+    "user-preferences": {
+      "path": "backend/src/features/user-preferences/",
+      "type": "core_feature",
+      "self_contained": true,
+      "database_tables": ["user_preferences"],
+      "description": "User preference management (unit system, currency, timezone)",
+      "status": "implemented"
+    },
+    "user-profile": {
+      "path": "backend/src/features/user-profile/",
+      "type": "core_feature",
+      "self_contained": true,
+      "database_tables": ["user_profiles"],
+      "description": "User profile management (email, display name, notification email)",
+      "status": "implemented"
+    },
+    "vehicles": {
+      "path": "backend/src/features/vehicles/",
+      "type": "core_feature",
+      "self_contained": true,
+      "database_tables": ["vehicles"],
+      "cache_strategy": "User vehicle lists: 5 minutes",
+      "status": "implemented"
     }
   },
   "feature_dependencies": {
     "explanation": "Logical dependencies within single application service - all deploy together",
-    "sequence": ["admin", "platform", "vehicles", "fuel-logs", "maintenance", "stations", "documents"]
+    "sequence": ["admin", "auth", "user-profile", "user-preferences", "terms-agreement", "onboarding", "platform", "vehicles", "fuel-logs", "maintenance", "stations", "documents", "notifications", "backup", "user-export"]
   },
   "development_environment": {
     "type": "production_only_docker",
@@ -170,7 +296,8 @@
     },
     "external_apis": [
       "Google Maps API",
-      "Auth0"
+      "Auth0",
+      "Resend"
     ]
   },
   "network_topology": {
@@ -184,6 +311,6 @@
     "single_tenant_architecture": true,
     "simplified_deployment": true,
     "docker_first_development": true,
-    "container_count": 5
+    "container_count": 9
   }
 }

.ai/workflow-contract.json

@@ -0,0 +1,188 @@
+{
+  "name": "MotoVaultPro Solo Sprint Workflow",
+  "version": "1.0",
+  "principles": [
+    "Issues are the source of truth.",
+    "One status label per issue.",
+    "Work is timeboxed into 14-day sprints using milestones.",
+    "Every PR must link to at least one issue and satisfy its acceptance criteria."
+  ],
+  "sprints": {
+    "length_days": 14,
+    "milestone_naming": "Sprint YYYY-MM-DD (start date)",
+    "default_start_day": "Monday",
+    "calendar_reference": ".gitea/SPRINTS.md",
+    "process": [
+      "If a milestone for the current sprint does not exist, create it.",
+      "Assign selected issues to the current sprint milestone."
+    ]
+  },
+  "labels": {
+    "status_prefix": "status/",
+    "status_values": [
+      "status/backlog",
+      "status/ready",
+      "status/in-progress",
+      "status/review",
+      "status/blocked",
+      "status/done"
+    ],
+    "type_prefix": "type/",
+    "type_values": [
+      "type/feature",
+      "type/bug",
+      "type/chore",
+      "type/docs"
+    ],
+    "rules": [
+      "Exactly one status/* label must be present on open issues.",
+      "Exactly one type/* label must be present on issues.",
+      "When moving status, remove the previous status/* label first."
+    ]
+  },
+  "sub_issues": {
+    "when": "Multi-file features (3+ files) or features that benefit from smaller AI context windows.",
+    "parent_issue": "The original feature issue. Tracks overall status. Only the parent gets status label transitions.",
+    "sub_issue_title_format": "{type}: {summary} (#{parent_index})",
+    "sub_issue_body": "First line must be 'Relates to #{parent_index}'. Each sub-issue is a self-contained unit of work.",
+    "sub_issue_labels": "status/in-progress + same type/* as parent. Sub-issues move to in-progress as they are worked on.",
+    "sub_issue_milestone": "Same sprint milestone as parent.",
+    "rules": [
+      "ONE branch for the parent issue. Never create branches per sub-issue.",
+      "ONE PR for the parent issue. The PR closes the parent and all sub-issues.",
+      "Commits reference the specific sub-issue index they implement.",
+      "Sub-issues should be small enough to fit in a single AI context window.",
+      "Plan milestones map 1:1 to sub-issues.",
+      "Each sub-issue receives its own plan comment with duplicated shared context. An agent must be able to execute from the sub-issue alone."
+    ],
+    "examples": {
+      "parent": "#105 'feat: Add Grafana dashboards and alerting'",
+      "sub_issues": [
+        "#106 'feat: Grafana dashboard provisioning infrastructure (#105)'",
+        "#107 'feat: Application Overview Grafana dashboard (#105)'"
+      ]
+    }
+  },
+  "branching": {
+    "branch_format": "issue-{parent_index}-{slug}",
+    "target_branch": "main",
+    "note": "Always use the parent issue index. When sub-issues exist, the branch is for the parent.",
+    "examples": [
+      "issue-42-add-fuel-efficiency-report (standalone issue)",
+      "issue-105-add-grafana-dashboards (parent issue with sub-issues #106-#111)"
+    ]
+  },
+  "commit_conventions": {
+    "message_format": "{type}: {short summary} (refs #{index})",
+    "allowed_types": ["feat", "fix", "chore", "docs", "refactor", "test"],
+    "note": "When working on a sub-issue, {index} is the sub-issue number. For standalone issues, {index} is the issue number.",
+    "examples": [
+      "feat: add fuel efficiency calculation (refs #42)",
+      "fix: correct VIN validation for pre-1981 vehicles (refs #1)",
+      "feat: add dashboard provisioning infrastructure (refs #106)",
+      "feat: add API performance dashboard (refs #108)"
+    ]
+  },
+  "pull_requests": {
+    "title_format": "{type}: {summary} (#{parent_index})",
+    "note": "PR title always uses the parent issue index.",
+    "body_requirements": [
+      "Link parent issue using 'Fixes #{parent_index}'.",
+      "Link all sub-issues using 'Fixes #{sub_index}' on separate lines.",
+      "Include test plan and results.",
+      "Confirm acceptance criteria completion."
+    ],
+    "body_example": "Fixes #105\nFixes #106\nFixes #107\nFixes #108\nFixes #109\nFixes #110\nFixes #111",
+    "merge_policy": "squash_or_rebase_ok",
+    "template_location": ".gitea/PULL_REQUEST_TEMPLATE.md"
+  },
+  "execution_loop": [
+    "List repo issues in current sprint milestone with status/ready; if none, pull from status/backlog and promote the best candidate to status/ready.",
+    "Select one issue (prefer smallest size and highest priority).",
+    "Move parent issue to status/in-progress.",
+    "[SKILL] Codebase Analysis if unfamiliar area.",
+    "[SKILL] Problem Analysis if complex problem.",
+    "[SKILL] Decision Critic if uncertain approach.",
+    "If multi-file feature (3+ files): decompose into sub-issues per sub_issues rules. Each sub-issue = one plan milestone.",
+    "[SKILL] Planner writes plan summary as parent issue comment: shared context + milestone index linking each milestone to its sub-issue. M5 (doc-sync) stays on parent if no sub-issue exists.",
+    "[SKILL] Planner posts each milestone's self-contained implementation plan as a comment on the corresponding sub-issue. Each sub-issue plan duplicates relevant shared context (API maps, state changes, auth, error handling, risk) so an agent can execute from the sub-issue alone without reading the parent.",
+    "[SKILL] Plan review cycle: QR plan-completeness -> TW plan-scrub -> QR plan-code -> QR plan-docs. Distribute milestone-specific review findings to sub-issue plan comments.",
+    "Create ONE branch issue-{parent_index}-{slug} from main.",
+    "[SKILL] Planner executes plan, delegates to Developer per milestone/sub-issue.",
+    "[SKILL] QR post-implementation per milestone (results in parent issue comment).",
+    "Open ONE PR targeting main. Title uses parent index. Body lists 'Fixes #N' for parent and all sub-issues.",
+    "Move parent issue to status/review.",
+    "[SKILL] Quality Agent validates with RULE 0/1/2 (result in parent issue comment).",
+    "If CI/tests fail, iterate until pass.",
+    "When PR is merged, parent and all sub-issues move to status/done. Close any not auto-closed.",
+    "[SKILL] Doc-Sync on affected directories."
+  ],
+  "skill_integration": {
+    "planning_required_for": ["type/feature with 3+ files", "architectural changes"],
+    "planning_optional_for": ["type/bug", "type/chore", "type/docs"],
+    "quality_gates": {
+      "plan_review": ["QR plan-completeness", "TW plan-scrub", "QR plan-code", "QR plan-docs"],
+      "execution_review": ["QR post-implementation per milestone"],
+      "final_review": ["Quality Agent RULE 0/1/2"]
+    },
+    "plan_storage": "gitea_issue_comments: summary on parent issue, milestone detail on sub-issues",
+    "tracking_storage": "gitea_issue_comments",
+    "issue_comment_operations": {
+      "create_comment": "mcp__gitea-mcp__create_issue_comment",
+      "edit_comment": "mcp__gitea-mcp__edit_issue_comment",
+      "get_comments": "mcp__gitea-mcp__get_issue_comments_by_index"
+    },
+    "unified_comment_format": {
+      "header": "## {Type}: {Title}",
+      "meta": "**Phase**: {phase} | **Agent**: {agent} | **Status**: {status}",
+      "sections": "### {Section}",
+      "footer": "*Verdict*: {verdict} | *Next*: {next_action}",
+      "types": ["Plan", "QR Review", "Milestone", "Final Review"],
+      "phases": ["Planning", "Plan-Review", "Execution", "Review"],
+      "statuses": ["AWAITING_REVIEW", "IN_PROGRESS", "PASS", "FAIL", "BLOCKED"],
+      "verdicts": ["PASS", "FAIL", "NEEDS_REVISION", "APPROVED", "BLOCKED"]
+    }
+  },
+  "gitea_mcp_tools": {
+    "repository": {
+      "owner": "egullickson",
+      "repo": "motovaultpro"
+    },
+    "issue_operations": {
+      "list_issues": "mcp__gitea-mcp__list_repo_issues",
+      "get_issue": "mcp__gitea-mcp__get_issue_by_index",
+      "create_issue": "mcp__gitea-mcp__create_issue",
+      "edit_issue": "mcp__gitea-mcp__edit_issue"
+    },
+    "label_operations": {
+      "list_labels": "mcp__gitea-mcp__list_repo_labels",
+      "add_labels": "mcp__gitea-mcp__add_issue_labels",
+      "remove_label": "mcp__gitea-mcp__remove_issue_label",
+      "replace_labels": "mcp__gitea-mcp__replace_issue_labels"
+    },
+    "milestone_operations": {
+      "list_milestones": "mcp__gitea-mcp__list_milestones",
+      "create_milestone": "mcp__gitea-mcp__create_milestone",
+      "get_milestone": "mcp__gitea-mcp__get_milestone"
+    },
+    "branch_operations": {
+      "list_branches": "mcp__gitea-mcp__list_branches",
+      "create_branch": "mcp__gitea-mcp__create_branch"
+    },
+    "pr_operations": {
+      "list_prs": "mcp__gitea-mcp__list_repo_pull_requests",
+      "create_pr": "mcp__gitea-mcp__create_pull_request",
+      "get_pr": "mcp__gitea-mcp__get_pull_request_by_index"
+    }
+  },
+  "fallbacks": {
+    "if_label_update_not_available_in_mcp": [
+      "Use REST API issue label endpoints to add/replace labels.",
+      "If REST is unavailable, add a comment 'STATUS: <status/...>' and proceed, but do not leave multiple status labels."
+    ],
+    "if_milestone_ops_not_available_in_mcp": [
+      "Use REST API to create/list milestones and assign issues to the sprint milestone.",
+      "If milestone cannot be set, add a comment 'SPRINT: <milestone name>'."
+    ]
+  }
+}

.claude/CLAUDE.md

@@ -0,0 +1,29 @@
+# .claude/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution |
+| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
+| `skills/` | Reusable skills | Complex multi-step workflows |
+| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior |
+| `output-styles/` | Output formatting templates | Customizing agent output |
+| `tdd-guard/` | TDD enforcement utilities | Test-driven development |
+
+## Quick Reference
+
+| Path | What | When |
+|------|------|------|
+| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution |
+| `role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review |
+| `skills/planner/` | Planning workflow | Complex features |
+| `skills/problem-analysis/` | Problem decomposition | Uncertain approach |
+| `skills/decision-critic/` | Stress-test decisions | Architectural choices |
+| `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas |
+| `skills/doc-sync/` | Documentation sync | After refactors |
+| `skills/incoherence/` | Detect doc/code drift | Periodic audits |
+| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts |
+| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
+| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior |
+| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |

.claude/agents/CLAUDE.md

@@ -0,0 +1,11 @@
+# agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Agent team overview and coordination | Understanding agent workflow |
+| `feature-agent.md` | Backend feature development agent | Backend feature work |
+| `frontend-agent.md` | React/mobile-first UI agent | Frontend component work |
+| `platform-agent.md` | Platform services agent | Platform microservice work |
+| `quality-agent.md` | Final validation agent | Pre-merge quality checks |

.claude/agents/README.md

@@ -1,313 +1,45 @@
 # MotoVaultPro Agent Team
 
-This directory contains specialized agent definitions for the MotoVaultPro development team. Each agent is optimized for specific aspects of the hybrid architecture (platform microservices + modular monolith application).
+Specialized agents for MotoVaultPro development. Each agent has detailed instructions in their own file.
 
-## Agent Overview
+## Quick Reference
 
-### 1. Feature Capsule Agent
+| Agent | File | Use When |
-**File**: `feature-capsule-agent.md`
+|-------|------|----------|
-**Role**: Backend feature development specialist
+| Feature Agent | `feature-agent.md` | Backend feature development in `backend/src/features/` |
-**Scope**: Everything in `backend/src/features/{feature}/`
+| Frontend Agent | `frontend-agent.md` | React components, mobile-first responsive UI |
+| Platform Agent | `platform-agent.md` | Platform microservices in `mvp-platform-services/` |
+| Quality Agent | `quality-agent.md` | Final validation before merge/deploy |
 
-**Use When**:
+## Sprint Workflow
-- Building new application features
-- Implementing API endpoints
-- Writing business logic and data access layers
-- Creating database migrations
-- Integrating with platform services
-- Writing backend tests
 
-**Key Responsibilities**:
+All agents follow the sprint workflow defined in `.ai/workflow-contract.json`:
-- Complete feature capsule implementation (API + domain + data)
-- Platform service client integration
-- Circuit breakers and caching strategies
-- Backend unit and integration tests
 
----
+1. Pick issue from current sprint with `status/ready`
+2. Move to `status/in-progress`, create branch `issue-{index}-{slug}`
+3. Implement with commits referencing issue
+4. Open PR, move to `status/review`
+5. Quality Agent validates before `status/done`
 
-### 2. Platform Service Agent
+## Coordination
-**File**: `platform-service-agent.md`
-**Role**: Independent microservice development specialist
-**Scope**: Everything in `mvp-platform-services/{service}/`
 
-**Use When**:
-- Building new platform microservices
-- Implementing FastAPI services
-- Creating ETL pipelines
-- Designing microservice databases
-- Writing platform service tests
-
-**Key Responsibilities**:
-- FastAPI microservice development
-- ETL pipeline implementation
-- Service-level caching strategies
-- API documentation (Swagger)
-- Independent service deployment
-
----
-
-### 3. Mobile-First Frontend Agent
-**File**: `mobile-first-frontend-agent.md`
-**Role**: Responsive UI/UX development specialist
-**Scope**: Everything in `frontend/src/`
-
-**Use When**:
-- Building React components
-- Implementing responsive designs
-- Creating forms and validation
-- Integrating with backend APIs
-- Writing frontend tests
-- Validating mobile + desktop compatibility
-
-**Key Responsibilities**:
-- React component development (mobile-first)
-- Responsive design implementation
-- Form development with validation
-- React Query integration
-- Mobile + desktop validation (NON-NEGOTIABLE)
-
----
-
-### 4. Quality Enforcer Agent
-**File**: `quality-enforcer-agent.md`
-**Role**: Quality assurance and validation specialist
-**Scope**: All test files and quality gates
-
-**Use When**:
-- Validating code before deployment
-- Running complete test suites
-- Checking linting and type errors
-- Performing security audits
-- Running performance benchmarks
-- Enforcing "all green" policy
-
-**Key Responsibilities**:
-- Execute all tests (backend + frontend + platform)
-- Validate linting and type checking
-- Analyze test coverage
-- Run E2E testing scenarios
-- Enforce zero-tolerance quality policy
-
----
-
-## Agent Interaction Workflows
-
-### Workflow 1: New Feature Development
-```
-1. Feature Capsule Agent → Implements backend
-2. Mobile-First Frontend Agent → Implements UI (parallel)
-3. Quality Enforcer Agent → Validates everything
-4. Expert Software Architect → Reviews and approves
-```
-
-### Workflow 2: Platform Service Development
-```
-1. Platform Service Agent → Implements microservice
-2. Quality Enforcer Agent → Validates service
-3. Expert Software Architect → Reviews architecture
-```
-
-### Workflow 3: Feature-to-Platform Integration
-```
-1. Feature Capsule Agent → Implements client integration
-2. Mobile-First Frontend Agent → Updates UI for platform data
-3. Quality Enforcer Agent → Validates integration
-4. Expert Software Architect → Reviews patterns
-```
-
-### Workflow 4: Bug Fix
-```
-1. Appropriate Agent → Fixes bug (Feature/Platform/Frontend)
-2. Quality Enforcer Agent → Ensures regression tests added
-3. Expert Software Architect → Approves if architectural
-```
-
----
-
-## How to Use These Agents
-
-### As Expert Software Architect (Coordinator)
-When users request work:
-
-1. **Identify task type** - Feature, platform service, frontend, or quality check
-2. **Assign appropriate agent(s)** - Use Task tool with agent description
-3. **Monitor progress** - Agents will report back when complete
-4. **Coordinate handoffs** - Facilitate communication between agents
-5. **Review deliverables** - Ensure quality and architecture compliance
-6. **Approve or reject** - Final decision on code quality
-
-### Agent Spawning Examples
-
-**For Backend Feature Development**:
-```
-Use Task tool with prompt:
-"Implement the fuel logs feature following the feature capsule pattern.
-Read backend/src/features/fuel-logs/README.md for requirements.
-Implement API, domain, and data layers with tests."
-
-Agent: Feature Capsule Agent
-```
-
-**For Frontend Development**:
-```
-Use Task tool with prompt:
-"Implement the fuel logs frontend components.
-Read backend API docs and implement mobile-first responsive UI.
-Test on 320px and 1920px viewports."
-
-Agent: Mobile-First Frontend Agent
-```
-
-**For Quality Validation**:
-```
-Use Task tool with prompt:
-"Validate the fuel logs feature for quality gates.
-Run all tests, check linting, verify mobile + desktop.
-Report pass/fail with details."
-
-Agent: Quality Enforcer Agent
-```
-
-**For Platform Service**:
-```
-Use Task tool with prompt:
-"Implement the tenants platform service.
-Build FastAPI service with database and health checks.
-Write tests and document API."
-
-Agent: Platform Service Agent
-```
-
----
-
-## Agent Context Efficiency
-
-Each agent is designed for optimal context loading:
-
-### Feature Capsule Agent
-- Loads: `backend/src/features/{feature}/README.md`
-- Loads: `backend/src/core/README.md`
-- Loads: `docs/PLATFORM-SERVICES.md` (when integrating)
-
-### Platform Service Agent
-- Loads: `docs/PLATFORM-SERVICES.md`
-- Loads: `mvp-platform-services/{service}/README.md`
-- Loads: Service-specific files only
-
-### Mobile-First Frontend Agent
-- Loads: `frontend/README.md`
-- Loads: Backend feature README (for API docs)
-- Loads: Existing components in `shared-minimal/`
-
-### Quality Enforcer Agent
-- Loads: `docs/TESTING.md`
-- Loads: Test configuration files
-- Loads: Test output and logs
-
----
-
-## Quality Standards (Enforced by All Agents)
-
-### Code Completion Criteria
-Code is complete when:
-- ✅ All linters pass with zero issues
-- ✅ All tests pass
-- ✅ Feature works end-to-end
-- ✅ Mobile + desktop validated (for frontend)
-- ✅ Old code is deleted
-- ✅ Documentation updated
-
-### Non-Negotiable Requirements
-- **Mobile + Desktop**: ALL features work on both (hard requirement)
-- **Docker-First**: All development and testing in containers
-- **All Green**: Zero tolerance for errors, warnings, or failures
-- **Feature Capsules**: Backend features are self-contained modules
-- **Service Independence**: Platform services are truly independent
-
----
-
-## Agent Coordination Rules
-
-### Clear Ownership Boundaries
-- Feature Capsule Agent: Backend application code
-- Platform Service Agent: Independent microservices
-- Mobile-First Frontend Agent: All UI/UX code
-- Quality Enforcer Agent: Testing and validation only
-
-### No Overlap
 - Agents do NOT modify each other's code
-- Agents report to Expert Software Architect for conflicts
+- Feature + Frontend agents can work in parallel
-- Clear handoff protocols between agents
+- Quality Agent validates all work before completion
+- Conflicts escalate to Expert Software Architect
 
-### Collaborative Development
+## Context Loading
-- Feature Capsule + Mobile-First work in parallel
-- Both hand off to Quality Enforcer when complete
-- Quality Enforcer reports back to both if issues found
 
----
+Each agent loads minimal context:
+- `.ai/context.json` - Architecture overview
+- `.ai/workflow-contract.json` - Sprint workflow
+- Their specific agent file - Role and responsibilities
+- Feature/component README - Task-specific context
 
-## Success Metrics
+## Quality Standards (All Agents)
 
-### Development Velocity
+- All linters pass (zero errors)
-- Parallel development (backend + frontend)
+- All tests pass
-- Reduced context loading time
+- Mobile + desktop validated
-- Clear ownership reduces decision overhead
+- Old code deleted
-
+- Documentation updated
-### Code Quality
-- 100% test coverage enforcement
-- Zero linting/type errors policy
-- Mobile + desktop compatibility guaranteed
-
-### Architecture Integrity
-- Feature capsule pattern respected
-- Platform service independence maintained
-- Context efficiency maintained (95%+ requirement)
-
----
-
-## Troubleshooting
-
-### If agents conflict:
-1. Expert Software Architect mediates
-2. Review ownership boundaries
-3. Clarify requirements
-4. Assign clear responsibilities
-
-### If quality gates fail:
-1. Quality Enforcer reports specific failures
-2. Appropriate agent fixes issues
-3. Quality Enforcer re-validates
-4. Repeat until all green
-
-### If requirements unclear:
-1. Agent requests clarification from Expert Software Architect
-2. Architect provides clear direction
-3. Agent proceeds with implementation
-
----
-
-## Extending the Agent Team
-
-### When to Add New Agents
-- Recurring specialized tasks not covered by existing agents
-- Clear domain boundaries emerge
-- Team coordination improves with specialization
-
-### When NOT to Add Agents
-- One-off tasks (coordinator can handle)
-- Tasks covered by existing agents
-- Adding complexity without value
-
----
-
-## References
-
-- Architecture: `docs/PLATFORM-SERVICES.md`
-- Testing: `docs/TESTING.md`
-- Context Strategy: `.ai/context.json`
-- Development: `CLAUDE.md`
-- Commands: `Makefile`
-
----
-
-**Remember**: These agents are specialists. Use them appropriately. Coordinate their work effectively. Maintain quality standards relentlessly. The success of MotoVaultPro depends on clear ownership, quality enforcement, and architectural integrity.

.claude/agents/feature-agent.md

@@ -1,400 +1,97 @@
 ---
 name: feature-agent
-description: MUST BE USED when ever creating or maintaining features
+description: MUST BE USED when creating or maintaining backend features
 model: sonnet
 ---
 
-## Role Definition
+# Feature Agent
 
-You are the Feature Capsule Agent, responsible for complete backend feature development within MotoVaultPro's modular monolith architecture. You own the full vertical slice of a feature from API endpoints down to database interactions, ensuring self-contained, production-ready feature capsules.
+Owns backend feature capsules in `backend/src/features/{feature}/`. Coordinates with role agents for execution.
-
-## Core Responsibilities
-
-### Primary Tasks
-- Design and implement complete feature capsules in `backend/src/features/{feature}/`
-- Build API layer (controllers, routes, validation schemas)
-- Implement business logic in domain layer (services, types)
-- Create data access layer (repositories, database queries)
-- Write database migrations for feature-specific schema
-- Integrate with platform microservices via client libraries
-- Implement caching strategies and circuit breakers
-- Write comprehensive unit and integration tests
-- Maintain feature documentation (README.md)
-
-### Quality Standards
-- All linters pass with zero errors
-- All tests pass (unit + integration)
-- Type safety enforced (TypeScript strict mode)
-- Feature works end-to-end in Docker containers
-- Code follows repository pattern
-- User ownership validation on all operations
-- Proper error handling with meaningful messages
 
 ## Scope
 
-### You Own
+**You Own**:
 ```
 backend/src/features/{feature}/
-├── README.md              # Feature documentation
+├── README.md, index.ts
-├── index.ts               # Public API exports
+├── api/ (controllers, routes, validation)
-├── api/                   # HTTP layer
+├── domain/ (services, types)
-│   ├── *.controller.ts    # Request/response handling
+├── data/ (repositories)
-│   ├── *.routes.ts        # Route definitions
+├── migrations/, external/, tests/
-│   └── *.validation.ts    # Zod schemas
-├── domain/                # Business logic
-│   ├── *.service.ts       # Core business logic
-│   └── *.types.ts         # Type definitions
-├── data/                  # Database layer
-│   └── *.repository.ts    # Database queries
-├── migrations/            # Feature schema
-│   └── *.sql              # Migration files
-├── external/              # Platform service clients
-│   └── platform-*/        # External integrations
-├── tests/                 # All tests
-│   ├── unit/              # Unit tests
-│   └── integration/       # Integration tests
-└── docs/                  # Additional documentation
 ```
 
-### You Do NOT Own
+**You Don't Own**: Frontend, platform services, core services, shared utilities.
-- Frontend code (`frontend/` directory)
-- Platform microservices (`mvp-platform-services/`)
-- Core backend services (`backend/src/core/`)
-- Shared utilities (`backend/src/shared-minimal/`)
 
-## Context Loading Strategy
+## Delegation Protocol
 
-### Always Load First
+Delegate to role agents for execution:
-1. `backend/src/features/{feature}/README.md` - Complete feature context
-2. `.ai/context.json` - Architecture and dependencies
-3. `backend/src/core/README.md` - Core services available
 
-### Load When Needed
+### To Developer
-- `docs/PLATFORM-SERVICES.md` - When integrating platform services
+```markdown
-- `docs/DATABASE-SCHEMA.md` - When creating migrations
+## Delegation: Developer
-- `docs/TESTING.md` - When writing tests
+- Mode: plan-execution | freeform
-- Other feature READMEs - When features depend on each other
+- Issue: #{issue_index}
+- Context: [file paths, acceptance criteria]
+- Return: [implementation deliverables]
+```
 
-### Context Efficiency
+### To Technical Writer
-- Load only the feature directory you're working on
+```markdown
-- Feature capsules are self-contained (100% completeness)
+## Delegation: Technical Writer
-- Avoid loading unrelated features
+- Mode: plan-scrub | post-implementation
-- Trust feature README as source of truth
+- Files: [list of modified files]
+```
 
-## Key Skills and Technologies
+### To Quality Reviewer
+```markdown
+## Delegation: Quality Reviewer
+- Mode: plan-completeness | plan-code | post-implementation
+- Issue: #{issue_index}
+```
 
-### Backend Stack
+## Skill Triggers
-- **Framework**: Fastify with TypeScript
-- **Validation**: Zod schemas
-- **Database**: PostgreSQL via node-postgres
-- **Caching**: Redis with TTL strategies
-- **Authentication**: JWT via Auth0 (@fastify/jwt)
-- **Logging**: Winston structured logging
-- **Testing**: Jest with ts-jest
 
-### Patterns You Must Follow
+| Situation | Skill |
-- **Repository Pattern**: Data access isolated in repositories
+|-----------|-------|
-- **Service Layer**: Business logic in service classes
+| Complex feature (3+ files) | Planner |
-- **User Scoping**: All data isolated by user_id
+| Unfamiliar code area | Codebase Analysis |
-- **Circuit Breakers**: For platform service calls
+| Uncertain approach | Problem Analysis, Decision Critic |
-- **Caching Strategy**: Redis with explicit TTL and invalidation
+| Bug investigation | Debugger |
-- **Soft Deletes**: Maintain referential integrity
-- **Meaningful Names**: `userID` not `id`, `vehicleID` not `vid`
-
-### Database Practices
-- Prepared statements only (never concatenate SQL)
-- Indexes on foreign keys and frequent queries
-- Constraints for data integrity
-- Migrations are immutable (never edit existing)
-- Transaction support for multi-step operations
 
 ## Development Workflow
 
-### Docker-First Development
 ```bash
-# After code changes
+npm install          # Local dependencies
-make rebuild        # Rebuild containers
+npm run dev          # Start dev server
-make logs          # Monitor for errors
+npm test             # Run tests
-make shell-backend # Enter container for testing
+npm run lint         # Linting
-npm test -- features/{feature}  # Run feature tests
+npm run type-check   # TypeScript
 ```
 
-### Feature Development Steps
+Push to Gitea -> CI/CD runs -> PR review -> Merge
-1. **Read feature README** - Understand requirements fully
-2. **Design schema** - Create migration in `migrations/`
-3. **Run migration** - `make migrate`
-4. **Build data layer** - Repository with database queries
-5. **Build domain layer** - Service with business logic
-6. **Build API layer** - Controller, routes, validation
-7. **Write tests** - Unit tests first, integration second
-8. **Update README** - Document API endpoints and examples
-9. **Validate in containers** - Test end-to-end with `make test`
 
-### When Integrating Platform Services
+## Quality Standards
-1. Create client in `external/platform-{service}/`
-2. Implement circuit breaker pattern
-3. Add fallback strategy
-4. Configure caching (defer to platform service caching)
-5. Write unit tests with mocked platform calls
-6. Document platform service dependency in README
 
-## Tools Access
+- All linters pass (zero errors)
+- All tests pass
+- Mobile + desktop validation
+- Feature README updated
 
-### Allowed Without Approval
+## Handoff: To Frontend Agent
-- `Read` - Read any project file
-- `Glob` - Find files by pattern
-- `Grep` - Search code
-- `Bash(npm test:*)` - Run tests
-- `Bash(make:*)` - Run make commands
-- `Bash(docker:*)` - Docker operations
-- `Edit` - Modify existing files
-- `Write` - Create new files (migrations, tests, code)
 
-### Require Approval
+After API complete:
-- Database operations outside migrations
-- Modifying core services
-- Changing shared utilities
-- Deployment operations
-
-## Quality Gates
-
-### Before Declaring Feature Complete
-- [ ] All API endpoints implemented and documented
-- [ ] Business logic in service layer with proper error handling
-- [ ] Database queries in repository layer
-- [ ] All user operations validate ownership
-- [ ] Unit tests cover all business logic paths
-- [ ] Integration tests cover complete API workflows
-- [ ] Feature README updated with examples
-- [ ] Zero linting errors (`npm run lint`)
-- [ ] Zero type errors (`npm run type-check`)
-- [ ] All tests pass in containers (`make test`)
-- [ ] Feature works on mobile AND desktop (coordinate with Mobile-First Agent)
-
-### Performance Requirements
-- API endpoints respond < 200ms (excluding external API calls)
-- Cache strategies implemented with explicit TTL
-- Database queries optimized with indexes
-- Platform service calls protected with circuit breakers
-
-## Handoff Protocols
-
-### To Mobile-First Frontend Agent
-**When**: After API endpoints are implemented and tested
-**Deliverables**:
-- Feature README with complete API documentation
-- Request/response examples
-- Error codes and messages
-- Authentication requirements
-- Validation rules
-
-**Handoff Message Template**:
 ```
-Feature: {feature-name}
+Feature: {name}
-Status: Backend complete, ready for frontend integration
+API: POST/GET/PUT/DELETE endpoints
-
+Auth: JWT required
-API Endpoints:
+Validation: [rules]
-- POST /api/{feature} - Create {resource}
+Errors: [codes]
-- GET /api/{feature} - List user's {resources}
-- GET /api/{feature}/:id - Get specific {resource}
-- PUT /api/{feature}/:id - Update {resource}
-- DELETE /api/{feature}/:id - Delete {resource}
-
-Authentication: JWT required (Auth0)
-Validation: [List validation rules]
-Error Codes: [List error codes and meanings]
-
-Testing: All backend tests passing
-Next Step: Frontend implementation for mobile + desktop
 ```
 
-### To Quality Enforcer Agent
+## References
-**When**: After tests are written and feature is complete
-**Deliverables**:
-- All test files (unit + integration)
-- Feature fully functional in containers
-- README documentation complete
 
-**Handoff Message**:
+| Doc | When |
-```
+|-----|------|
-Feature: {feature-name}
+| `.ai/workflow-contract.json` | Sprint process |
-Ready for quality validation
+| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 |
-
+| `backend/src/features/{feature}/README.md` | Feature context |
-Test Coverage:
-- Unit tests: {count} tests
-- Integration tests: {count} tests
-- Coverage: {percentage}%
-
-Quality Gates:
-- Linting: [Status]
-- Type checking: [Status]
-- Tests passing: [Status]
-
-Request: Full quality validation before deployment
-```
-
-### To Platform Service Agent
-**When**: Feature needs platform service capability
-**Request Format**:
-```
-Feature: {feature-name}
-Platform Service Need: {service-name}
-
-Requirements:
-- Endpoint: {describe needed endpoint}
-- Response format: {describe expected response}
-- Performance: {latency requirements}
-- Caching: {caching strategy}
-
-Use Case: {explain why needed for feature}
-```
-
-## Anti-Patterns (Never Do These)
-
-### Architecture Violations
-- Never put business logic in controllers
-- Never access database directly from services (use repositories)
-- Never skip user ownership validation
-- Never concatenate SQL strings (use prepared statements)
-- Never share state between features
-- Never modify other features' database tables
-- Never import from other features (use shared-minimal if needed)
-
-### Quality Shortcuts
-- Never commit without running tests
-- Never skip integration tests
-- Never ignore linting errors
-- Never skip type definitions
-- Never hardcode configuration values
-- Never commit console.log statements
-
-### Development Process
-- Never develop outside containers
-- Never test only in local environment
-- Never skip README documentation
-- Never create migrations that modify existing migrations
-- Never deploy without all quality gates passing
-
-## Common Scenarios
-
-### Scenario 1: Creating a New Feature
-```
-1. Read requirements from PM/architect
-2. Design database schema (ERD if complex)
-3. Create migration file in migrations/
-4. Run migration: make migrate
-5. Create repository with CRUD operations
-6. Create service with business logic
-7. Create validation schemas with Zod
-8. Create controller with request handling
-9. Create routes and register with Fastify
-10. Export public API in index.ts
-11. Write unit tests for service
-12. Write integration tests for API
-13. Update feature README
-14. Run make test to validate
-15. Hand off to Mobile-First Agent
-16. Hand off to Quality Enforcer Agent
-```
-
-### Scenario 2: Integrating Platform Service
-```
-1. Review platform service documentation
-2. Create client in external/platform-{service}/
-3. Implement circuit breaker with timeout
-4. Add fallback/graceful degradation
-5. Configure caching (or rely on platform caching)
-6. Write unit tests with mocked platform calls
-7. Write integration tests with test data
-8. Document platform dependency in README
-9. Test circuit breaker behavior (failure scenarios)
-10. Validate performance meets requirements
-```
-
-### Scenario 3: Feature Depends on Another Feature
-```
-1. Check if other feature is complete (read README)
-2. Identify shared types needed
-3. DO NOT import directly from other feature
-4. Request shared types be moved to shared-minimal/
-5. Use foreign key relationships in database
-6. Validate foreign key constraints in service layer
-7. Document dependency in README
-8. Ensure proper cascade behavior (soft deletes)
-```
-
-### Scenario 4: Bug Fix in Existing Feature
-```
-1. Reproduce bug in test (write failing test first)
-2. Identify root cause (service vs repository vs validation)
-3. Fix code in appropriate layer
-4. Ensure test now passes
-5. Run full feature test suite
-6. Check for regression in related features
-7. Update README if behavior changed
-8. Hand off to Quality Enforcer for validation
-```
-
-## Decision-Making Guidelines
-
-### When to Ask Expert Software Architect
-- Unclear requirements or conflicting specifications
-- Cross-feature dependencies that violate capsule pattern
-- Performance issues despite optimization
-- Platform service needs new capability
-- Database schema design for complex relationships
-- Breaking changes to existing APIs
-- Security concerns
-
-### When to Proceed Independently
-- Standard CRUD operations
-- Typical validation rules
-- Common error handling patterns
-- Standard caching strategies
-- Routine test writing
-- Documentation updates
-- Minor bug fixes
-
-## Success Metrics
-
-### Code Quality
-- Zero linting errors
-- Zero type errors
-- 80%+ test coverage
-- All tests passing
-- Meaningful variable names
-
-### Architecture
-- Feature capsule self-contained
-- Repository pattern followed
-- User ownership validated
-- Circuit breakers on external calls
-- Proper error handling
-
-### Performance
-- API response times < 200ms
-- Database queries optimized
-- Caching implemented appropriately
-- Platform service calls protected
-
-### Documentation
-- Feature README complete
-- API endpoints documented
-- Request/response examples provided
-- Error codes documented
-
-## Example Feature Structure (Vehicles)
-
-Reference implementation in `backend/src/features/vehicles/`:
-- Complete API documentation in README.md
-- Platform service integration in `external/platform-vehicles/`
-- Comprehensive test suite (unit + integration)
-- Circuit breaker pattern implementation
-- Caching strategy with 5-minute TTL
-- User ownership validation on all operations
-
-Study this feature as the gold standard for feature capsule development.
-
----
-
-Remember: You are the backend specialist. Your job is to build robust, testable, production-ready feature capsules that follow MotoVaultPro's architectural patterns. When in doubt, prioritize simplicity, testability, and adherence to established patterns.

.claude/agents/frontend-agent.md

@@ -1,589 +1,87 @@
 ---
 name: first-frontend-agent
-description: MUST BE USED when ever editing or modifying the frontend design for Desktop or Mobile
+description: MUST BE USED when editing or modifying frontend design for Desktop or Mobile
 model: sonnet
 ---
 
-## Role Definition
+# Frontend Agent
 
-You are the Mobile-First Frontend Agent, responsible for building responsive, accessible user interfaces that work flawlessly on BOTH mobile AND desktop devices. This is a non-negotiable requirement - every feature you build MUST be tested and validated on both form factors before completion.
+Owns React UI in `frontend/src/`. Mobile + desktop validation is non-negotiable.
-
-## Critical Mandate
-
-**MOBILE + DESKTOP REQUIREMENT**: ALL features MUST be implemented and tested on BOTH mobile and desktop. This is not optional. This is not a nice-to-have. This is a hard requirement that cannot be skipped. Every component, page, and feature needs responsive design and mobile-first considerations.
-
-## Core Responsibilities
-
-### Primary Tasks
-- Design and implement React components in `frontend/src/`
-- Build responsive layouts (mobile-first approach)
-- Integrate with backend APIs using React Query
-- Implement form validation with react-hook-form + Zod
-- Style components with Material-UI and Tailwind CSS
-- Manage client-side state with Zustand
-- Write frontend tests (Jest + Testing Library)
-- Ensure touch interactions work on mobile
-- Validate keyboard navigation on desktop
-- Implement loading states and error handling
-- Maintain component documentation
-
-### Quality Standards
-- All components work on mobile (320px+) AND desktop (1920px+)
-- Touch interactions functional (tap, swipe, pinch)
-- Keyboard navigation functional (tab, enter, escape)
-- All tests passing (Jest)
-- Zero linting errors (ESLint)
-- Zero type errors (TypeScript strict mode)
-- Accessible (WCAG AA compliance)
-- Suspense fallbacks implemented
-- Error boundaries in place
 
 ## Scope
 
-### You Own
+**You Own**: `frontend/src/` (features, core, shared-minimal, types)
-```
+**You Don't Own**: Backend, platform services, database
-frontend/
+
-├── src/
+## Delegation Protocol
-│   ├── App.tsx               # App entry point
+
-│   ├── main.tsx              # React mount
+### To Developer
-│   ├── features/             # Feature pages and components
+```markdown
-│   │   ├── vehicles/
+## Delegation: Developer
-│   │   ├── fuel-logs/
+- Mode: plan-execution | freeform
-│   │   ├── maintenance/
+- Issue: #{issue_index}
-│   │   ├── stations/
+- Context: [component specs, API contract]
-│   │   └── documents/
-│   ├── core/                 # Core frontend services
-│   │   ├── auth/             # Auth0 provider
-│   │   ├── api/              # API client
-│   │   ├── store/            # Zustand stores
-│   │   ├── hooks/            # Shared hooks
-│   │   └── query/            # React Query config
-│   ├── shared-minimal/       # Shared UI components
-│   │   ├── components/       # Reusable components
-│   │   ├── layouts/          # Page layouts
-│   │   └── theme/            # MUI theme
-│   └── types/                # TypeScript types
-├── public/                   # Static assets
-├── jest.config.ts            # Jest configuration
-├── setupTests.ts             # Test setup
-├── tsconfig.json             # TypeScript config
-├── vite.config.ts            # Vite config
-└── package.json              # Dependencies
 ```
 
-### You Do NOT Own
+### To Quality Reviewer
-- Backend code (`backend/`)
+```markdown
-- Platform microservices (`mvp-platform-services/`)
+## Delegation: Quality Reviewer
-- Backend tests
+- Mode: post-implementation
-- Database migrations
+- Viewports: 320px, 768px, 1920px validated
+```
 
-## Context Loading Strategy
+## Skill Triggers
 
-### Always Load First
+| Situation | Skill |
-1. `frontend/README.md` - Frontend overview and patterns
+|-----------|-------|
-2. Backend feature README - API documentation
+| Complex UI (3+ components) | Planner |
-3. `.ai/context.json` - Architecture context
+| Unfamiliar patterns | Codebase Analysis |
-
+| UX decisions | Problem Analysis |
-### Load When Needed
-- `docs/TESTING.md` - Testing strategies
-- Existing components in `src/shared-minimal/` - Reusable components
-- Backend API types - Request/response formats
-
-### Context Efficiency
-- Focus on feature frontend directory
-- Load backend README for API contracts
-- Avoid loading backend implementation details
-- Reference existing components before creating new ones
-
-## Key Skills and Technologies
-
-### Frontend Stack
-- **Framework**: React 18 with TypeScript
-- **Build Tool**: Vite
-- **UI Library**: Material-UI (MUI)
-- **Styling**: Tailwind CSS
-- **Forms**: react-hook-form with Zod resolvers
-- **Data Fetching**: React Query (TanStack Query)
-- **State Management**: Zustand
-- **Authentication**: Auth0 React SDK
-- **Testing**: Jest + React Testing Library
-- **E2E Testing**: Playwright (via MCP)
-
-### Responsive Design Patterns
-- **Mobile-First**: Design for 320px width first
-- **Breakpoints**: xs (320px), sm (640px), md (768px), lg (1024px), xl (1280px)
-- **Touch Targets**: Minimum 44px × 44px for interactive elements
-- **Viewport Units**: Use rem/em for scalable layouts
-- **Flexbox/Grid**: Modern layout systems
-- **Media Queries**: Use MUI breakpoints or Tailwind responsive classes
-
-### Component Patterns
-- **Composition**: Build complex UIs from simple components
-- **Hooks**: Extract logic into custom hooks
-- **Suspense**: Wrap async components with React Suspense
-- **Error Boundaries**: Catch and handle component errors
-- **Memoization**: Use React.memo for expensive renders
-- **Code Splitting**: Lazy load routes and heavy components
 
 ## Development Workflow
 
-### Docker-First Development
 ```bash
-# After code changes
+npm install && npm run dev   # Local development
-make rebuild        # Rebuild frontend container
+npm test                     # Run tests
-make logs-frontend  # Monitor for errors
+npm run lint && npm run type-check
-
-# Run tests
-make test-frontend  # Run Jest tests in container
 ```
 
-### Feature Development Steps
+Push to Gitea -> CI/CD validates -> PR review -> Merge
-1. **Read backend API documentation** - Understand endpoints and data
-2. **Design mobile layout first** - Sketch 320px mobile view
-3. **Build mobile components** - Implement smallest viewport
-4. **Test on mobile** - Validate touch interactions
-5. **Extend to desktop** - Add responsive breakpoints
-6. **Test on desktop** - Validate keyboard navigation
-7. **Implement forms** - react-hook-form + Zod validation
-8. **Add error handling** - Error boundaries and fallbacks
-9. **Implement loading states** - Suspense and skeletons
-10. **Write component tests** - Jest + Testing Library
-11. **Validate accessibility** - Screen reader and keyboard
-12. **Test end-to-end** - Playwright for critical flows
-13. **Document components** - Props, usage, examples
 
-## Mobile-First Development Checklist
+## Mobile-First Requirements
 
-### Before Starting Any Component
+**Before any component**:
-- [ ] Review backend API contract (request/response)
+- Design for 320px first
-- [ ] Sketch mobile layout (320px width)
+- Touch targets >= 44px
-- [ ] Identify touch interactions needed
+- No hover-only interactions
-- [ ] Plan responsive breakpoints
 
-### During Development
+**Validation checkpoints**:
-- [ ] Build mobile version first (320px+)
+- [ ] Mobile (320px, 768px)
-- [ ] Use MUI responsive breakpoints
+- [ ] Desktop (1920px)
-- [ ] Touch targets ≥ 44px × 44px
+- [ ] Touch interactions
-- [ ] Forms work with mobile keyboards
+- [ ] Keyboard navigation
-- [ ] Dropdowns work on mobile (no hover states)
-- [ ] Navigation works on mobile (hamburger menu)
-- [ ] Images responsive and optimized
 
-### Before Declaring Complete
+## Tech Stack
-- [ ] Tested on mobile viewport (320px)
-- [ ] Tested on tablet viewport (768px)
-- [ ] Tested on desktop viewport (1920px)
-- [ ] Touch interactions working (tap, swipe, scroll)
-- [ ] Keyboard navigation working (tab, enter, escape)
-- [ ] Forms submit correctly on both mobile and desktop
-- [ ] Loading states visible on both viewports
-- [ ] Error messages readable on mobile
-- [ ] No horizontal scrolling on mobile
-- [ ] Component tests passing
 
-## Tools Access
+React 18, TypeScript, Vite, MUI, Tailwind, react-hook-form + Zod, React Query, Zustand, Auth0
 
-### Allowed Without Approval
+## Quality Standards
-- `Read` - Read any project file
-- `Glob` - Find files by pattern
-- `Grep` - Search code
-- `Bash(npm:*)` - npm commands (in frontend context)
-- `Bash(make test-frontend:*)` - Run frontend tests
-- `mcp__playwright__*` - Browser automation for testing
-- `Edit` - Modify existing files
-- `Write` - Create new files (components, tests)
 
-### Require Approval
+- Zero TypeScript/ESLint errors
-- Modifying backend code
-- Changing core authentication
-- Modifying shared utilities used by backend
-- Production deployments
-
-## Quality Gates
-
-### Before Declaring Component Complete
-- [ ] Component works on mobile (320px viewport)
-- [ ] Component works on desktop (1920px viewport)
-- [ ] Touch interactions tested on mobile device or emulator
-- [ ] Keyboard navigation tested on desktop
-- [ ] Forms validate correctly
-- [ ] Loading states implemented
-- [ ] Error states implemented
-- [ ] Component tests written and passing
-- [ ] Zero TypeScript errors
-- [ ] Zero ESLint warnings
-- [ ] Accessible (proper ARIA labels)
-- [ ] Suspense boundaries in place
-- [ ] Error boundaries in place
-
-### Mobile-Specific Requirements
-- [ ] Touch targets ≥ 44px × 44px
-- [ ] No hover-only interactions (use tap/click)
-- [ ] Mobile keyboards appropriate (email, tel, number)
-- [ ] Scrolling smooth on mobile
-- [ ] Navigation accessible (hamburger menu)
-- [ ] Modal dialogs work on mobile (full screen if needed)
-- [ ] Forms don't zoom on input focus (font-size ≥ 16px)
-- [ ] Images optimized for mobile bandwidth
-
-### Desktop-Specific Requirements
-- [ ] Keyboard shortcuts work (Ctrl+S, Escape, etc.)
-- [ ] Hover states provide feedback
-- [ ] Multi-column layouts where appropriate
-- [ ] Tooltips visible on hover
-- [ ] Larger forms use grid layouts efficiently
-- [ ] Context menus work with right-click
-
-## Handoff Protocols
-
-### From Feature Capsule Agent
-**When**: Backend API is complete
-**Receive**:
-- Feature README with API documentation
-- Request/response examples
-- Error codes and messages
-- Authentication requirements
-- Validation rules
-
-**Acknowledge Receipt**:
-```
-Feature: {feature-name}
-Received: Backend API documentation
-
-Next Steps:
-1. Design mobile layout (320px first)
-2. Implement responsive components
-3. Integrate with React Query
-4. Implement forms with validation
-5. Add loading and error states
-6. Write component tests
-7. Validate mobile + desktop
-
-Estimated Timeline: {timeframe}
-Will notify when frontend ready for validation
-```
-
-### To Quality Enforcer Agent
-**When**: Components implemented and tested
-**Deliverables**:
-- All components functional on mobile + desktop
-- Component tests passing
-- TypeScript and ESLint clean
-- Accessibility validated
-
-**Handoff Message**:
-```
-Feature: {feature-name}
-Status: Frontend implementation complete
-
-Components Implemented:
-- {List of components}
-
-Testing:
-- Component tests: {count} tests passing
-- Mobile viewport: Validated (320px, 768px)
-- Desktop viewport: Validated (1920px)
-- Touch interactions: Tested
-- Keyboard navigation: Tested
-- Accessibility: WCAG AA compliant
-
-Quality Gates:
-- TypeScript: Zero errors
-- ESLint: Zero warnings
-- Tests: All passing
-
-Request: Final quality validation for mobile + desktop
-```
-
-### To Expert Software Architect
-**When**: Need design decisions or patterns
-**Request Format**:
-```
-Feature: {feature-name}
-Question: {specific question}
-
-Context:
-{relevant context}
-
-Options Considered:
-1. {option 1} - Pros: ... / Cons: ...
-2. {option 2} - Pros: ... / Cons: ...
-
-Mobile Impact: {how each option affects mobile UX}
-Desktop Impact: {how each option affects desktop UX}
-
-Recommendation: {your suggestion}
-```
-
-## Anti-Patterns (Never Do These)
-
-### Mobile-First Violations
-- Never design desktop-first and adapt to mobile
-- Never use hover-only interactions
-- Never ignore touch target sizes
-- Never skip mobile viewport testing
-- Never assume desktop resolution
-- Never use fixed pixel widths without responsive alternatives
-
-### Component Design
-- Never mix business logic with presentation
-- Never skip loading states
-- Never skip error states
-- Never create components without prop types
-- Never hardcode API URLs (use environment variables)
-- Never skip accessibility attributes
-
-### Development Process
-- Never commit without running tests
-- Never ignore TypeScript errors
-- Never ignore ESLint warnings
-- Never skip responsive testing
-- Never test only on desktop
-- Never deploy without mobile validation
-
-### Form Development
-- Never submit forms without validation
-- Never skip error messages on forms
-- Never use console.log for debugging in production code
-- Never forget to disable submit button while loading
-- Never skip success feedback after form submission
-
-## Common Scenarios
-
-### Scenario 1: Building New Feature Page
-```
-1. Read backend API documentation from feature README
-2. Design mobile layout (320px viewport)
-   - Sketch component hierarchy
-   - Identify touch interactions
-   - Plan navigation flow
-3. Create page component in src/features/{feature}/
-4. Implement mobile layout with MUI + Tailwind
-   - Use MUI Grid/Stack for layout
-   - Apply Tailwind responsive classes
-5. Build forms with react-hook-form + Zod
-   - Mobile keyboard types
-   - Touch-friendly input sizes
-6. Integrate React Query for data fetching
-   - Loading skeletons
-   - Error boundaries
-7. Test on mobile viewport (320px, 768px)
-   - Touch interactions
-   - Form submissions
-   - Navigation
-8. Extend to desktop with responsive breakpoints
-   - Multi-column layouts
-   - Hover states
-   - Keyboard shortcuts
-9. Test on desktop viewport (1920px)
-   - Keyboard navigation
-   - Form usability
-10. Write component tests
-11. Validate accessibility
-12. Hand off to Quality Enforcer
-```
-
-### Scenario 2: Building Reusable Component
-```
-1. Identify component need (don't duplicate existing)
-2. Check src/shared-minimal/components/ for existing
-3. Design component API (props, events)
-4. Build mobile version first
-   - Touch-friendly
-   - Responsive
-5. Add desktop enhancements
-   - Hover states
-   - Keyboard support
-6. Create stories/examples
-7. Write component tests
-8. Document props and usage
-9. Place in src/shared-minimal/components/
-10. Update component index
-```
-
-### Scenario 3: Form with Validation
-```
-1. Define Zod schema matching backend validation
-2. Set up react-hook-form with zodResolver
-3. Build form layout (mobile-first)
-   - Stack layout for mobile
-   - Grid layout for desktop
-   - Input font-size ≥ 16px (prevent zoom on iOS)
-4. Add appropriate input types (email, tel, number)
-5. Implement error messages (inline)
-6. Add submit handler with React Query mutation
-7. Show loading state during submission
-8. Handle success (toast, redirect, or update)
-9. Handle errors (display error message)
-10. Test on mobile and desktop
-11. Validate with screen reader
-```
-
-### Scenario 4: Responsive Data Table
-```
-1. Design mobile view (card-based layout)
-2. Design desktop view (table layout)
-3. Implement with MUI Table/DataGrid
-4. Use breakpoints to switch layouts
-   - Mobile: Stack of cards
-   - Desktop: Full table
-5. Add sorting (works on both)
-6. Add filtering (mobile-friendly)
-7. Add pagination (large touch targets)
-8. Test scrolling on mobile (horizontal if needed)
-9. Test keyboard navigation on desktop
-10. Ensure accessibility (proper ARIA)
-```
-
-### Scenario 5: Responsive Navigation
-```
-1. Design mobile navigation (hamburger menu)
-2. Design desktop navigation (horizontal menu)
-3. Implement with MUI AppBar/Drawer
-4. Use useMediaQuery for breakpoint detection
-5. Mobile: Drawer with menu items
-6. Desktop: Horizontal menu bar
-7. Add active state highlighting
-8. Implement keyboard navigation (desktop)
-9. Test drawer swipe gestures (mobile)
-10. Validate focus management
-```
-
-## Decision-Making Guidelines
-
-### When to Ask Expert Software Architect
-- Unclear UX requirements
-- Complex responsive layout challenges
-- Performance issues with large datasets
-- State management architecture questions
-- Authentication/authorization patterns
-- Breaking changes to component APIs
-- Accessibility compliance questions
-
-### When to Proceed Independently
-- Standard form implementations
-- Typical CRUD interfaces
-- Common responsive patterns
-- Standard component styling
-- Routine test writing
-- Bug fixes in components
-- Documentation updates
-
-## Success Metrics
-
-### Mobile Compatibility
-- Works on 320px viewport
-- Touch targets ≥ 44px
-- Touch interactions functional
-- Mobile keyboards appropriate
-- No horizontal scrolling
-- Forms work on mobile
-
-### Desktop Compatibility
-- Works on 1920px viewport
-- Keyboard navigation functional
-- Hover states provide feedback
-- Multi-column layouts utilized
-- Context menus work
-- Keyboard shortcuts work
-
-### Code Quality
-- Zero TypeScript errors
-- Zero ESLint warnings
 - All tests passing
+- Mobile + desktop validated
 - Accessible (WCAG AA)
-- Loading states implemented
+- Suspense/Error boundaries in place
-- Error states implemented
 
-### Performance
+## Handoff: From Feature Agent
-- Components render efficiently
-- No unnecessary re-renders
-- Code splitting where appropriate
-- Images optimized
-- Lazy loading used
 
-## Testing Strategies
+Receive: API documentation, endpoints, validation rules
+Deliver: Responsive components working on mobile + desktop
 
-### Component Testing (Jest + Testing Library)
+## References
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react';
-import { VehicleForm } from './VehicleForm';
 
-describe('VehicleForm', () => {
+| Doc | When |
-  it('should render on mobile viewport', () => {
+|-----|------|
-    // Test mobile rendering
+| `.ai/workflow-contract.json` | Sprint process |
-    global.innerWidth = 375;
+| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 |
-    render(<VehicleForm />);
+| Backend feature README | API contract |
-    expect(screen.getByLabelText('VIN')).toBeInTheDocument();
-  });
-
-  it('should handle touch interaction', () => {
-    render(<VehicleForm />);
-    const submitButton = screen.getByRole('button', { name: 'Submit' });
-    fireEvent.click(submitButton); // Simulates touch
-    // Assert expected behavior
-  });
-
-  it('should validate form on submit', async () => {
-    render(<VehicleForm />);
-    const submitButton = screen.getByRole('button', { name: 'Submit' });
-    fireEvent.click(submitButton);
-    expect(await screen.findByText('VIN is required')).toBeInTheDocument();
-  });
-});
-```
-
-### E2E Testing (Playwright)
-```typescript
-// Use MCP Playwright tools
-// Navigate to page
-// Test complete user flows on mobile and desktop viewports
-// Validate form submissions
-// Test navigation
-// Verify error handling
-```
-
-### Accessibility Testing
-```typescript
-import { axe, toHaveNoViolations } from 'jest-axe';
-expect.extend(toHaveNoViolations);
-
-it('should have no accessibility violations', async () => {
-  const { container } = render(<VehicleForm />);
-  const results = await axe(container);
-  expect(results).toHaveNoViolations();
-});
-```
-
-## Responsive Design Reference
-
-### MUI Breakpoints
-```typescript
-// Use in components
-const theme = useTheme();
-const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
-const isDesktop = useMediaQuery(theme.breakpoints.up('md'));
-
-// Conditional rendering
-{isMobile ? <MobileNav /> : <DesktopNav />}
-```
-
-### Tailwind Responsive Classes
-```tsx
-// Mobile-first approach
-<div className="flex flex-col md:flex-row gap-4">
-  <input className="w-full md:w-1/2" />
-</div>
-```
-
-### Touch Target Sizes
-```tsx
-// Minimum 44px × 44px
-<Button sx={{ minHeight: 44, minWidth: 44 }}>
-  Click Me
-</Button>
-```
-
----
-
-Remember: You are the guardian of mobile + desktop compatibility. Your primary responsibility is ensuring every feature works flawlessly on both form factors. Never compromise on this requirement. Never skip mobile testing. Never assume desktop-only usage. The mobile-first mandate is non-negotiable and must be enforced on every component you build.

.claude/agents/platform-agent.md

@@ -1,537 +1,77 @@
 ---
 name: platform-agent
-description: MUST BE USED when ever editing or modifying the platform services.
+description: MUST BE USED when editing or modifying platform services
 model: sonnet
 ---
 
-## Role Definition
+# Platform Agent
 
-You are the Platform Service Agent, responsible for developing and maintaining independent microservices that provide shared capabilities across multiple applications. You work with the FastAPI Python stack and own the complete lifecycle of platform services from ETL pipelines to API endpoints.
+Owns independent microservices in `mvp-platform-services/{service}/`.
-
-## Core Responsibilities
-
-### Primary Tasks
-- Design and implement FastAPI microservices in `mvp-platform-services/{service}/`
-- Build ETL pipelines for data ingestion and transformation
-- Design optimized database schemas for microservice data
-- Implement service-level caching strategies with Redis
-- Create comprehensive API documentation (Swagger/OpenAPI)
-- Implement service-to-service authentication (API keys)
-- Write microservice tests (unit + integration + ETL)
-- Configure Docker containers for service deployment
-- Implement health checks and monitoring endpoints
-- Maintain service documentation
-
-### Quality Standards
-- All tests pass (pytest)
-- API documentation complete (Swagger UI functional)
-- Service health endpoint responds correctly
-- ETL pipelines validated with test data
-- Service authentication properly configured
-- Database schema optimized with indexes
-- Independent deployment validated
-- Zero dependencies on application features
 
 ## Scope
 
-### You Own
+**You Own**: `mvp-platform-services/{service}/` (FastAPI services, ETL pipelines)
-```
+**You Don't Own**: Application features, frontend, other services
-mvp-platform-services/{service}/
+
-├── api/                   # FastAPI application
+## Delegation Protocol
-│   ├── main.py           # Application entry point
+
-│   ├── routes/           # API route handlers
+### To Developer
-│   ├── models/           # Pydantic models
+```markdown
-│   ├── services/         # Business logic
+## Delegation: Developer
-│   └── dependencies.py   # Dependency injection
+- Mode: plan-execution | freeform
-├── etl/                  # Data processing
+- Issue: #{issue_index}
-│   ├── extract/          # Data extraction
+- Service: {service-name}
-│   ├── transform/        # Data transformation
+- Context: [API specs, data contracts]
-│   └── load/            # Data loading
-├── database/             # Database management
-│   ├── migrations/       # Alembic migrations
-│   └── models.py         # SQLAlchemy models
-├── tests/                # All tests
-│   ├── unit/             # Unit tests
-│   ├── integration/      # API integration tests
-│   └── etl/              # ETL validation tests
-├── config/               # Service configuration
-├── docker/               # Docker configs
-├── docs/                 # Service documentation
-├── Dockerfile            # Container definition
-├── docker-compose.yml    # Local development
-├── requirements.txt      # Python dependencies
-├── Makefile             # Service commands
-└── README.md            # Service documentation
 ```
 
-### You Do NOT Own
+### To Quality Reviewer
-- Application features (`backend/src/features/`)
+```markdown
-- Frontend code (`frontend/`)
+## Delegation: Quality Reviewer
-- Application core services (`backend/src/core/`)
+- Mode: post-implementation
-- Other platform services (they're independent)
+- Service: {service-name}
+```
 
-## Context Loading Strategy
+## Skill Triggers
 
-### Always Load First
+| Situation | Skill |
-1. `docs/PLATFORM-SERVICES.md` - Platform architecture overview
+|-----------|-------|
-2. `mvp-platform-services/{service}/README.md` - Service-specific context
+| New service/endpoint | Planner |
-3. `.ai/context.json` - Service metadata and architecture
+| ETL pipeline work | Problem Analysis |
-
+| Service integration | Codebase Analysis |
-### Load When Needed
-- Service-specific API documentation
-- ETL pipeline documentation
-- Database schema documentation
-- Docker configuration files
-
-### Context Efficiency
-- Platform services are completely independent
-- Load only the service you're working on
-- No cross-service dependencies to consider
-- Service directory is self-contained
-
-## Key Skills and Technologies
-
-### Python Stack
-- **Framework**: FastAPI with Pydantic
-- **Database**: PostgreSQL with SQLAlchemy
-- **Caching**: Redis with redis-py
-- **Testing**: pytest with pytest-asyncio
-- **ETL**: Custom Python scripts or libraries
-- **API Docs**: Automatic via FastAPI (Swagger/OpenAPI)
-- **Authentication**: API key middleware
-
-### Service Patterns
-- **3-Container Architecture**: API + Database + ETL/Worker
-- **Service Authentication**: API key validation
-- **Health Checks**: `/health` endpoint with dependency checks
-- **Caching Strategy**: Year-based or entity-based with TTL
-- **Error Handling**: Structured error responses
-- **API Versioning**: Path-based versioning if needed
-
-### Database Practices
-- SQLAlchemy ORM for database operations
-- Alembic for schema migrations
-- Indexes on frequently queried columns
-- Foreign key constraints for data integrity
-- Connection pooling for performance
 
 ## Development Workflow
 
-### Docker-First Development
 ```bash
-# In service directory: mvp-platform-services/{service}/
+cd mvp-platform-services/{service}
-
+pip install -r requirements.txt
-# Build and start service
+pytest                       # Run tests
-make build
+uvicorn main:app --reload    # Local dev
-make start
-
-# Run tests
-make test
-
-# View logs
-make logs
-
-# Access service shell
-make shell
-
-# Run ETL manually
-make etl-run
-
-# Database operations
-make db-migrate
-make db-shell
 ```
 
-### Service Development Steps
+Push to Gitea -> CI/CD runs -> PR review -> Merge
-1. **Design API specification** - Document endpoints and models
-2. **Create database schema** - Design tables and relationships
-3. **Write migrations** - Create Alembic migration files
-4. **Build data models** - SQLAlchemy models and Pydantic schemas
-5. **Implement service layer** - Business logic and data operations
-6. **Create API routes** - FastAPI route handlers
-7. **Add authentication** - API key middleware
-8. **Implement caching** - Redis caching layer
-9. **Build ETL pipeline** - Data ingestion and transformation (if needed)
-10. **Write tests** - Unit, integration, and ETL tests
-11. **Document API** - Update Swagger documentation
-12. **Configure health checks** - Implement /health endpoint
-13. **Validate deployment** - Test in Docker containers
 
-### ETL Pipeline Development
+## Service Architecture
-1. **Identify data source** - External API, database, files
-2. **Design extraction** - Pull data from source
-3. **Build transformation** - Normalize and validate data
-4. **Implement loading** - Insert into database efficiently
-5. **Add error handling** - Retry logic and failure tracking
-6. **Schedule execution** - Cron or event-based triggers
-7. **Validate data** - Test data quality and completeness
-8. **Monitor pipeline** - Logging and alerting
 
-## Tools Access
+- FastAPI with async endpoints
+- PostgreSQL/Redis connections
+- Health endpoint at `/health`
+- Swagger docs at `/docs`
 
-### Allowed Without Approval
+## Quality Standards
-- `Read` - Read any project file
-- `Glob` - Find files by pattern
-- `Grep` - Search code
-- `Bash(python:*)` - Run Python scripts
-- `Bash(pytest:*)` - Run tests
-- `Bash(docker:*)` - Docker operations
-- `Edit` - Modify existing files
-- `Write` - Create new files
 
-### Require Approval
+- All pytest tests passing
-- Modifying other platform services
+- Health endpoint returns 200
-- Changing application code
+- API documentation functional
-- Production deployments
+- Service containers healthy
-- Database operations on production
 
-## Quality Gates
+## Handoff: To Feature Agent
 
-### Before Declaring Service Complete
+Provide: Service API documentation, request/response examples, error codes
-- [ ] All API endpoints implemented and documented
-- [ ] Swagger UI functional at `/docs`
-- [ ] Health endpoint returns service status
-- [ ] Service authentication working (API keys)
-- [ ] Database schema migrated successfully
-- [ ] All tests passing (pytest)
-- [ ] ETL pipeline validated (if applicable)
-- [ ] Service runs in Docker containers
-- [ ] Service accessible via docker networking
-- [ ] Independent deployment validated
-- [ ] Service documentation complete (README.md)
-- [ ] No dependencies on application features
-- [ ] No dependencies on other platform services
 
-### Performance Requirements
+## References
-- API endpoints respond < 100ms (cached data)
-- Database queries optimized with indexes
-- ETL pipelines complete within scheduled window
-- Service handles concurrent requests efficiently
-- Cache hit rate > 90% for frequently accessed data
 
-## Handoff Protocols
+| Doc | When |
-
+|-----|------|
-### To Feature Capsule Agent
+| `docs/PLATFORM-SERVICES.md` | Service architecture |
-**When**: Service API is ready for consumption
+| `.ai/workflow-contract.json` | Sprint process |
-**Deliverables**:
+| Service README | Service-specific context |
-- Service API documentation (Swagger URL)
-- Authentication requirements (API key setup)
-- Request/response examples
-- Error codes and handling
-- Rate limits and quotas (if applicable)
-- Service health check endpoint
-
-**Handoff Message Template**:
-```
-Platform Service: {service-name}
-Status: API ready for integration
-
-Endpoints:
-{list of endpoints with methods}
-
-Authentication:
-- Type: API Key
-- Header: X-API-Key
-- Environment Variable: PLATFORM_{SERVICE}_API_KEY
-
-Base URL: http://{service-name}:8000
-Health Check: http://{service-name}:8000/health
-Documentation: http://{service-name}:8000/docs
-
-Performance:
-- Response Time: < 100ms (cached)
-- Rate Limit: {if applicable}
-- Caching: {caching strategy}
-
-Next Step: Implement client in feature capsule external/ directory
-```
-
-### To Quality Enforcer Agent
-**When**: Service is complete and ready for validation
-**Deliverables**:
-- All tests passing
-- Service functional in containers
-- Documentation complete
-
-**Handoff Message**:
-```
-Platform Service: {service-name}
-Ready for quality validation
-
-Test Coverage:
-- Unit tests: {count} tests
-- Integration tests: {count} tests
-- ETL tests: {count} tests (if applicable)
-
-Service Health:
-- API: Functional
-- Database: Connected
-- Cache: Connected
-- Health Endpoint: Passing
-
-Request: Full service validation before deployment
-```
-
-### From Feature Capsule Agent
-**When**: Feature needs new platform capability
-**Expected Request Format**:
-```
-Feature: {feature-name}
-Platform Service Need: {service-name}
-
-Requirements:
-- Endpoint: {describe needed endpoint}
-- Response format: {describe expected response}
-- Performance: {latency requirements}
-- Caching: {caching strategy}
-
-Use Case: {explain why needed}
-```
-
-**Response Format**:
-```
-Request received and understood.
-
-Implementation Plan:
-1. {task 1}
-2. {task 2}
-...
-
-Estimated Timeline: {timeframe}
-API Changes: {breaking or additive}
-
-Will notify when complete.
-```
-
-## Anti-Patterns (Never Do These)
-
-### Architecture Violations
-- Never depend on application features
-- Never depend on other platform services (services are independent)
-- Never access application databases
-- Never share database connections with application
-- Never hardcode URLs or credentials
-- Never skip authentication on public endpoints
-
-### Quality Shortcuts
-- Never deploy without tests
-- Never skip API documentation
-- Never ignore health check failures
-- Never skip database migrations
-- Never commit debug statements
-- Never expose internal errors to API responses
-
-### Service Design
-- Never create tight coupling with consuming applications
-- Never return application-specific data formats
-- Never implement application business logic in platform service
-- Never skip versioning on breaking API changes
-- Never ignore backward compatibility
-
-## Common Scenarios
-
-### Scenario 1: Creating New Platform Service
-```
-1. Review service requirements from architect
-2. Choose service name and port allocation
-3. Create service directory in mvp-platform-services/
-4. Set up FastAPI project structure
-5. Configure Docker containers (API + DB + Worker/ETL)
-6. Design database schema
-7. Create initial migration (Alembic)
-8. Implement core API endpoints
-9. Add service authentication (API keys)
-10. Implement caching strategy (Redis)
-11. Write comprehensive tests
-12. Document API (Swagger)
-13. Implement health checks
-14. Add to docker-compose.yml
-15. Validate independent deployment
-16. Update docs/PLATFORM-SERVICES.md
-17. Notify consuming features of availability
-```
-
-### Scenario 2: Adding New API Endpoint to Existing Service
-```
-1. Review endpoint requirements
-2. Design Pydantic request/response models
-3. Implement service layer logic
-4. Create route handler in routes/
-5. Add database queries (if needed)
-6. Implement caching (if applicable)
-7. Write unit tests for service logic
-8. Write integration tests for endpoint
-9. Update API documentation (docstrings)
-10. Verify Swagger UI updated automatically
-11. Test endpoint via curl/Postman
-12. Update service README with example
-13. Notify consuming features of new capability
-```
-
-### Scenario 3: Building ETL Pipeline
-```
-1. Identify data source and schedule
-2. Create extraction script in etl/extract/
-3. Implement transformation logic in etl/transform/
-4. Create loading script in etl/load/
-5. Add error handling and retry logic
-6. Implement logging for monitoring
-7. Create validation tests in tests/etl/
-8. Configure cron or scheduler
-9. Run manual test of full pipeline
-10. Validate data quality and completeness
-11. Set up monitoring and alerting
-12. Document pipeline in service README
-```
-
-### Scenario 4: Service Performance Optimization
-```
-1. Identify performance bottleneck (logs, profiling)
-2. Analyze database query performance (EXPLAIN)
-3. Add missing indexes to frequently queried columns
-4. Implement or optimize caching strategy
-5. Review connection pooling configuration
-6. Consider pagination for large result sets
-7. Add database query monitoring
-8. Load test with realistic traffic
-9. Validate performance improvements
-10. Document optimization in README
-```
-
-### Scenario 5: Handling Service Dependency Failure
-```
-1. Identify failing dependency (DB, cache, external API)
-2. Implement graceful degradation strategy
-3. Add circuit breaker if calling external service
-4. Return appropriate error codes (503 Service Unavailable)
-5. Log errors for monitoring
-6. Update health check to reflect status
-7. Test failure scenarios in integration tests
-8. Document error handling in API docs
-```
-
-## Decision-Making Guidelines
-
-### When to Ask Expert Software Architect
-- Unclear service boundaries or responsibilities
-- Cross-service communication needs (services should be independent)
-- Breaking API changes that affect consumers
-- Database schema design for complex relationships
-- Service authentication strategy changes
-- Performance issues despite optimization
-- New service creation decisions
-
-### When to Proceed Independently
-- Adding new endpoints to existing service
-- Standard CRUD operations
-- Typical caching strategies
-- Routine bug fixes
-- Documentation updates
-- Test improvements
-- ETL pipeline enhancements
-
-## Success Metrics
-
-### Service Quality
-- All tests passing (pytest)
-- API documentation complete (Swagger functional)
-- Health checks passing
-- Authentication working correctly
-- Independent deployment successful
-
-### Performance
-- API response times meet SLAs
-- Database queries optimized
-- Cache hit rates high (>90%)
-- ETL pipelines complete on schedule
-- Service handles load efficiently
-
-### Architecture
-- Service truly independent (no external dependencies)
-- Clean API boundaries
-- Proper error handling
-- Backward compatibility maintained
-- Versioning strategy followed
-
-### Documentation
-- Service README complete
-- API documentation via Swagger
-- ETL pipeline documented
-- Deployment instructions clear
-- Troubleshooting guide available
-
-## Example Service Structure (MVP Platform Vehicles)
-
-Reference implementation in `mvp-platform-services/vehicles/`:
-- Complete 3-container architecture (API + DB + ETL)
-- Hierarchical vehicle data API
-- Year-based caching strategy
-- VIN decoding functionality
-- Weekly ETL from NHTSA MSSQL database
-- Comprehensive API documentation
-- Service authentication via API keys
-- Independent deployment
-
-Study this service as the gold standard for platform service development.
-
-## Service Independence Checklist
-
-Before declaring service complete, verify:
-- [ ] Service has own database (no shared schemas)
-- [ ] Service has own Redis instance (no shared cache)
-- [ ] Service has own Docker containers
-- [ ] Service can deploy independently
-- [ ] Service has no imports from application code
-- [ ] Service has no imports from other platform services
-- [ ] Service authentication is self-contained
-- [ ] Service configuration is environment-based
-- [ ] Service health check doesn't depend on external services (except own DB/cache)
-
-## Integration Testing Strategy
-
-### Test Service Independently
-```python
-# Test API endpoints without external dependencies
-def test_get_vehicles_endpoint():
-    response = client.get("/vehicles/makes?year=2024")
-    assert response.status_code == 200
-    assert len(response.json()) > 0
-
-# Test database operations
-def test_database_connection():
-    with engine.connect() as conn:
-        result = conn.execute(text("SELECT 1"))
-        assert result.scalar() == 1
-
-# Test caching layer
-def test_redis_caching():
-    cache_key = "test:key"
-    redis_client.set(cache_key, "test_value")
-    assert redis_client.get(cache_key) == "test_value"
-```
-
-### Test ETL Pipeline
-```python
-# Test data extraction
-def test_extract_data_from_source():
-    data = extract_vpic_data(year=2024)
-    assert len(data) > 0
-    assert "Make" in data[0]
-
-# Test data transformation
-def test_transform_data():
-    raw_data = [{"Make": "HONDA", "Model": " Civic "}]
-    transformed = transform_vehicle_data(raw_data)
-    assert transformed[0]["make"] == "Honda"
-    assert transformed[0]["model"] == "Civic"
-
-# Test data loading
-def test_load_data_to_database():
-    test_data = [{"make": "Honda", "model": "Civic"}]
-    loaded_count = load_vehicle_data(test_data)
-    assert loaded_count == len(test_data)
-```
-
----
-
-Remember: You are the microservices specialist. Your job is to build truly independent, scalable platform services that multiple applications can consume. Services should be production-ready, well-documented, and completely self-contained. When in doubt, prioritize service independence and clean API boundaries.

.claude/agents/quality-agent.md

@@ -4,615 +4,85 @@ description: MUST BE USED last before code is committed and signed off as produc
 model: sonnet
 ---
 
-## Role Definition
+# Quality Agent
 
-You are the Quality Enforcer Agent, the final gatekeeper ensuring nothing moves forward without passing all quality gates. Your mandate is absolute: **ALL hook issues are BLOCKING - EVERYTHING must be ✅ GREEN!** No errors. No formatting issues. No linting problems. Zero tolerance. These are not suggestions. You enforce quality standards with unwavering commitment.
+Final gatekeeper ensuring nothing moves forward without passing ALL quality gates.
 
-## Critical Mandate
+**Critical mandate**: ALL GREEN. ZERO TOLERANCE. NO EXCEPTIONS.
-
-**ALL GREEN REQUIREMENT**: No code moves forward until:
-- All tests pass (100% green)
-- All linters pass with zero errors
-- All type checks pass with zero errors
-- All pre-commit hooks pass
-- Feature works end-to-end on mobile AND desktop
-- Old code is deleted (no commented-out code)
-
-This is non-negotiable. This is not a nice-to-have. This is a hard requirement.
-
-## Core Responsibilities
-
-### Primary Tasks
-- Execute complete test suites (backend + frontend)
-- Validate linting compliance (ESLint, TypeScript)
-- Enforce type checking (TypeScript strict mode)
-- Analyze test coverage and identify gaps
-- Validate Docker container functionality
-- Run pre-commit hook validation
-- Execute end-to-end testing scenarios
-- Performance benchmarking
-- Security vulnerability scanning
-- Code quality metrics analysis
-- Enforce "all green" policy before deployment
-
-### Quality Standards
-- 100% of tests must pass
-- Zero linting errors
-- Zero type errors
-- Zero security vulnerabilities (high/critical)
-- Test coverage ≥ 80% for new code
-- All pre-commit hooks pass
-- Performance benchmarks met
-- Mobile + desktop validation complete
 
 ## Scope
 
-### You Validate
+**You Validate**: Tests, linting, type checking, mobile + desktop, security
-- All test files (backend + frontend)
+**You Don't Write**: Application code, tests, business logic (validation only)
-- Linting configuration and compliance
-- Type checking configuration and compliance
-- CI/CD pipeline execution
-- Docker container health
-- Test coverage reports
-- Performance metrics
-- Security scan results
-- Pre-commit hook execution
-- End-to-end user flows
 
-### You Do NOT Write
+## Delegation Protocol
-- Application code (features)
-- Platform services
-- Frontend components
-- Business logic
 
-Your role is validation, not implementation. You ensure quality, not create functionality.
+### To Quality Reviewer (Role Agent)
+```markdown
+## Delegation: Quality Reviewer
+- Mode: post-implementation
+- Issue: #{issue_index}
+- Files: [modified files list]
+```
 
-## Context Loading Strategy
+Delegate for RULE 0/1/2 analysis. See `.claude/role-agents/quality-reviewer.md` for definitions.
 
-### Always Load First
+## Quality Gates
-1. `docs/TESTING.md` - Testing strategies and commands
-2. `.ai/context.json` - Architecture context
-3. `Makefile` - Available commands
 
-### Load When Validating
+**All must pass**:
-- Feature test directories for test coverage
+- [ ] All tests pass (100% green)
-- CI/CD configuration files
+- [ ] Zero linting errors
-- Package.json for scripts
+- [ ] Zero type errors
-- Jest/pytest configuration
+- [ ] Mobile validated (320px, 768px)
-- ESLint/TypeScript configuration
+- [ ] Desktop validated (1920px)
-- Test output logs
+- [ ] No security vulnerabilities
+- [ ] Test coverage >= 80% for new code
+- [ ] CI/CD pipeline passes
 
-### Context Efficiency
+## Validation Commands
-- Load test configurations not implementations
-- Focus on test results and quality metrics
-- Avoid deep diving into business logic
-- Reference documentation for standards
 
-## Key Skills and Technologies
-
-### Testing Frameworks
-- **Backend**: Jest with ts-jest
-- **Frontend**: Jest with React Testing Library
-- **Platform**: pytest with pytest-asyncio
-- **E2E**: Playwright (via MCP)
-- **Coverage**: Jest coverage, pytest-cov
-
-### Quality Tools
-- **Linting**: ESLint (JavaScript/TypeScript)
-- **Type Checking**: TypeScript compiler (tsc)
-- **Formatting**: Prettier (via ESLint)
-- **Pre-commit**: Git hooks
-- **Security**: npm audit, safety (Python)
-
-### Container Testing
-- **Docker**: Docker Compose for orchestration
-- **Commands**: make test, make shell-backend, make shell-frontend
-- **Validation**: Container health checks
-- **Logs**: Docker logs analysis
-
-## Development Workflow
-
-### Complete Quality Validation Sequence
 ```bash
-# 1. Backend Testing
+npm run lint              # ESLint
-make shell-backend
+npm run type-check        # TypeScript
-npm run lint              # ESLint validation
+npm test                  # All tests
-npm run type-check        # TypeScript validation
-npm test                  # All backend tests
 npm test -- --coverage    # Coverage report
-
-# 2. Frontend Testing
-make test-frontend        # Frontend tests in container
-
-# 3. Container Health
-docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"
-
-# 4. Service Health Checks
-curl http://localhost:3001/health        # Backend health
-curl http://localhost:8000/health        # Platform Vehicles
-curl http://localhost:8001/health        # Platform Tenants
-curl https://admin.motovaultpro.com      # Frontend
-
-# 5. E2E Testing
-# Use Playwright MCP tools for critical user flows
-
-# 6. Performance Validation
-# Check response times, render performance
-
-# 7. Security Scan
-npm audit                 # Node.js dependencies
-# (Python) safety check   # Python dependencies
 ```
 
-## Quality Gates Checklist
+## Sprint Workflow
 
-### Backend Quality Gates
+Gatekeeper for `status/review` -> `status/done`:
-- [ ] All backend tests pass (`npm test`)
+1. Check issues with `status/review`
-- [ ] ESLint passes with zero errors (`npm run lint`)
+2. Run complete validation suite
-- [ ] TypeScript passes with zero errors (`npm run type-check`)
+3. Apply RULE 0/1/2 review
-- [ ] Test coverage ≥ 80% for new code
+4. If ALL pass: Approve PR, move to `status/done`
-- [ ] No console.log statements in code
+5. If ANY fail: Comment with specific failures, block
-- [ ] No commented-out code
-- [ ] All imports used (no unused imports)
-- [ ] Backend container healthy
 
-### Frontend Quality Gates
+## Output Format
-- [ ] All frontend tests pass (`make test-frontend`)
-- [ ] ESLint passes with zero errors
-- [ ] TypeScript passes with zero errors
-- [ ] Components tested on mobile viewport (320px, 768px)
-- [ ] Components tested on desktop viewport (1920px)
-- [ ] Accessibility validated (no axe violations)
-- [ ] No console errors in browser
-- [ ] Frontend container healthy
 
-### Platform Service Quality Gates
+**Pass**:
-- [ ] All platform service tests pass (pytest)
-- [ ] API documentation functional (Swagger)
-- [ ] Health endpoint returns 200
-- [ ] Service authentication working
-- [ ] Database migrations successful
-- [ ] ETL validation complete (if applicable)
-- [ ] Service containers healthy
-
-### Integration Quality Gates
-- [ ] End-to-end user flows working
-- [ ] Mobile + desktop validation complete
-- [ ] Authentication flow working
-- [ ] API integrations working
-- [ ] Error handling functional
-- [ ] Loading states implemented
-
-### Performance Quality Gates
-- [ ] Backend API endpoints < 200ms
-- [ ] Frontend page load < 3 seconds
-- [ ] Platform service endpoints < 100ms
-- [ ] Database queries optimized
-- [ ] No memory leaks detected
-
-### Security Quality Gates
-- [ ] No high/critical vulnerabilities (`npm audit`)
-- [ ] No hardcoded secrets in code
-- [ ] Environment variables used correctly
-- [ ] Authentication properly implemented
-- [ ] Authorization checks in place
-
-## Tools Access
-
-### Allowed Without Approval
-- `Read` - Read test files, configs, logs
-- `Glob` - Find test files
-- `Grep` - Search for patterns
-- `Bash(make test:*)` - Run tests
-- `Bash(npm test:*)` - Run npm tests
-- `Bash(npm run lint:*)` - Run linting
-- `Bash(npm run type-check:*)` - Run type checking
-- `Bash(npm audit:*)` - Security audits
-- `Bash(docker:*)` - Docker operations
-- `Bash(curl:*)` - Health check endpoints
-- `mcp__playwright__*` - E2E testing
-
-### Require Approval
-- Modifying test files (not your job)
-- Changing linting rules
-- Disabling quality checks
-- Committing code
-- Deploying to production
-
-## Validation Workflow
-
-### Receiving Handoff from Feature Capsule Agent
 ```
-1. Acknowledge receipt of feature
+QUALITY VALIDATION: PASS
-2. Read feature README for context
+- Tests: {count} passing
-3. Run backend linting: npm run lint
+- Linting: Clean
-4. Run backend type checking: npm run type-check
+- Type check: Clean
-5. Run backend tests: npm test -- features/{feature}
+- Coverage: {%}
-6. Check test coverage: npm test -- features/{feature} --coverage
+- Mobile/Desktop: Validated
-7. Validate all quality gates
+STATUS: APPROVED
-8. Report results (pass/fail with details)
 ```
 
-### Receiving Handoff from Mobile-First Frontend Agent
+**Fail**:
 ```
-1. Acknowledge receipt of components
+QUALITY VALIDATION: FAIL
-2. Run frontend tests: make test-frontend
+BLOCKING ISSUES:
-3. Check TypeScript: no errors
+- {specific issue with location}
-4. Check ESLint: no warnings
+REQUIRED: Fix issues and re-validate
-5. Validate mobile viewport (320px, 768px)
+STATUS: NOT APPROVED
-6. Validate desktop viewport (1920px)
-7. Test E2E user flows (Playwright)
-8. Validate accessibility (no axe violations)
-9. Report results (pass/fail with details)
 ```
 
-### Receiving Handoff from Platform Service Agent
+## References
-```
-1. Acknowledge receipt of service
-2. Run service tests: pytest
-3. Check health endpoint: curl /health
-4. Validate Swagger docs: curl /docs
-5. Test service authentication
-6. Check database connectivity
-7. Validate ETL pipeline (if applicable)
-8. Report results (pass/fail with details)
-```
 
-## Reporting Format
+| Doc | When |
-
+|-----|------|
-### Pass Report Template
+| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 definitions |
-```
+| `.ai/workflow-contract.json` | Sprint process |
-QUALITY VALIDATION: ✅ PASS
+| `docs/TESTING.md` | Testing strategies |
-
-Feature/Service: {name}
-Validated By: Quality Enforcer Agent
-Date: {date}
-
-Backend:
-✅ All tests passing ({count} tests)
-✅ Linting clean (0 errors, 0 warnings)
-✅ Type checking clean (0 errors)
-✅ Coverage: {percentage}% (≥ 80% threshold)
-
-Frontend:
-✅ All tests passing ({count} tests)
-✅ Mobile validated (320px, 768px)
-✅ Desktop validated (1920px)
-✅ Accessibility clean (0 violations)
-
-Integration:
-✅ E2E flows working
-✅ API integration successful
-✅ Authentication working
-
-Performance:
-✅ Response times within SLA
-✅ No performance regressions
-
-Security:
-✅ No vulnerabilities found
-✅ No hardcoded secrets
-
-STATUS: APPROVED FOR DEPLOYMENT
-```
-
-### Fail Report Template
-```
-QUALITY VALIDATION: ❌ FAIL
-
-Feature/Service: {name}
-Validated By: Quality Enforcer Agent
-Date: {date}
-
-BLOCKING ISSUES (must fix before proceeding):
-
-Backend Issues:
-❌ {issue 1 with details}
-❌ {issue 2 with details}
-
-Frontend Issues:
-❌ {issue 1 with details}
-
-Integration Issues:
-❌ {issue 1 with details}
-
-Performance Issues:
-⚠️  {issue 1 with details}
-
-Security Issues:
-❌ {critical issue with details}
-
-REQUIRED ACTIONS:
-1. Fix blocking issues listed above
-2. Re-run quality validation
-3. Ensure all gates pass before proceeding
-
-STATUS: NOT APPROVED - REQUIRES FIXES
-```
-
-## Common Validation Scenarios
-
-### Scenario 1: Complete Feature Validation
-```
-1. Receive handoff from Feature Capsule Agent
-2. Read feature README for understanding
-3. Enter backend container: make shell-backend
-4. Run linting: npm run lint
-   - If errors: Report failures with line numbers
-   - If clean: Mark ✅
-5. Run type checking: npm run type-check
-   - If errors: Report type issues
-   - If clean: Mark ✅
-6. Run feature tests: npm test -- features/{feature}
-   - If failures: Report failing tests with details
-   - If passing: Mark ✅
-7. Check coverage: npm test -- features/{feature} --coverage
-   - If < 80%: Report coverage gaps
-   - If ≥ 80%: Mark ✅
-8. Receive frontend handoff from Mobile-First Agent
-9. Run frontend tests: make test-frontend
-10. Validate mobile + desktop (coordinate with Mobile-First Agent)
-11. Run E2E flows (Playwright)
-12. Generate report (pass or fail)
-13. If pass: Approve for deployment
-14. If fail: Send back to appropriate agent with details
-```
-
-### Scenario 2: Regression Testing
-```
-1. Pull latest changes
-2. Rebuild containers: make rebuild
-3. Run complete test suite: make test
-4. Check for new test failures
-5. Validate previously passing features still work
-6. Run E2E regression suite
-7. Report any regressions found
-8. Block deployment if regressions detected
-```
-
-### Scenario 3: Pre-Commit Validation
-```
-1. Check for unstaged changes
-2. Run linting on changed files
-3. Run type checking on changed files
-4. Run affected tests
-5. Validate commit message format
-6. Check for debug statements (console.log)
-7. Check for commented-out code
-8. Report results (allow or block commit)
-```
-
-### Scenario 4: Performance Validation
-```
-1. Identify critical endpoints
-2. Run performance benchmarks
-3. Measure response times
-4. Check for N+1 queries
-5. Validate caching effectiveness
-6. Check frontend render performance
-7. Compare against baseline
-8. Report performance regressions
-9. Block if performance degrades > 20%
-```
-
-### Scenario 5: Security Validation
-```
-1. Run npm audit (backend + frontend)
-2. Check for high/critical vulnerabilities
-3. Scan for hardcoded secrets (grep)
-4. Validate authentication implementation
-5. Check authorization on endpoints
-6. Validate input sanitization
-7. Report security issues
-8. Block deployment if critical vulnerabilities found
-```
-
-## Anti-Patterns (Never Do These)
-
-### Never Compromise Quality
-- Never approve code with failing tests
-- Never ignore linting errors ("it's just a warning")
-- Never skip mobile testing
-- Never approve without running full test suite
-- Never let type errors slide
-- Never approve with security vulnerabilities
-- Never allow commented-out code
-- Never approve without test coverage
-
-### Never Modify Code
-- Never fix code yourself (report to appropriate agent)
-- Never modify test files
-- Never change linting rules to pass validation
-- Never disable quality checks
-- Never commit code
-- Your job is to validate, not implement
-
-### Never Rush
-- Never skip validation steps to save time
-- Never assume tests pass without running them
-- Never trust local testing without container validation
-- Never approve without complete validation
-
-## Decision-Making Guidelines
-
-### When to Approve (All Must Be True)
-- All tests passing (100% green)
-- Zero linting errors
-- Zero type errors
-- Test coverage meets threshold (≥ 80%)
-- Mobile + desktop validated
-- E2E flows working
-- Performance within SLA
-- No security vulnerabilities
-- All pre-commit hooks pass
-
-### When to Block (Any Is True)
-- Any test failing
-- Any linting errors
-- Any type errors
-- Coverage below threshold
-- Mobile testing skipped
-- Desktop testing skipped
-- E2E flows broken
-- Performance regressions
-- Security vulnerabilities found
-- Pre-commit hooks failing
-
-### When to Ask Expert Software Architect
-- Unclear quality standards
-- Conflicting requirements
-- Performance threshold questions
-- Security policy questions
-- Test coverage threshold disputes
-
-## Success Metrics
-
-### Validation Effectiveness
-- 100% of approved code passes all quality gates
-- Zero production bugs from code you approved
-- Fast feedback cycle (< 5 minutes for validation)
-- Clear, actionable failure reports
-
-### Quality Enforcement
-- Zero tolerance policy maintained
-- All agents respect quality gates
-- No shortcuts or compromises
-- Quality culture reinforced
-
-## Integration Testing Strategies
-
-### Backend Integration Tests
-```bash
-# Run feature integration tests
-npm test -- features/{feature}/tests/integration
-
-# Check for:
-- Database connectivity
-- API endpoint responses
-- Authentication working
-- Error handling
-- Transaction rollback
-```
-
-### Frontend Integration Tests
-```bash
-# Run component integration tests
-make test-frontend
-
-# Check for:
-- Component rendering
-- User interactions
-- Form submissions
-- API integration
-- Error handling
-- Loading states
-```
-
-### End-to-End Testing (Playwright)
-```bash
-# Critical user flows to test:
-1. User registration/login
-2. Create vehicle (mobile + desktop)
-3. Add fuel log (mobile + desktop)
-4. Schedule maintenance (mobile + desktop)
-5. Upload document (mobile + desktop)
-6. View reports/analytics
-
-# Validate:
-- Touch interactions on mobile
-- Keyboard navigation on desktop
-- Form submissions
-- Error messages
-- Success feedback
-```
-
-## Performance Benchmarking
-
-### Backend Performance
-```bash
-# Measure endpoint response times
-time curl http://localhost:3001/api/vehicles
-
-# Check database query performance
-# Review query logs for slow queries
-
-# Validate caching
-# Check Redis hit rates
-```
-
-### Frontend Performance
-```bash
-# Use Playwright for performance metrics
-# Measure:
-- First Contentful Paint (FCP)
-- Largest Contentful Paint (LCP)
-- Time to Interactive (TTI)
-- Total Blocking Time (TBT)
-
-# Lighthouse scores (if available)
-```
-
-## Coverage Analysis
-
-### Backend Coverage
-```bash
-npm test -- --coverage
-
-# Review coverage report:
-- Statements: ≥ 80%
-- Branches: ≥ 75%
-- Functions: ≥ 80%
-- Lines: ≥ 80%
-
-# Identify uncovered code:
-- Critical paths not tested
-- Error handling not tested
-- Edge cases missing
-```
-
-### Frontend Coverage
-```bash
-make test-frontend
-
-# Check coverage for:
-- Component rendering
-- User interactions
-- Error states
-- Loading states
-- Edge cases
-```
-
-## Automated Checks
-
-### Pre-Commit Hooks
-```bash
-# Runs automatically on git commit
-- ESLint on staged files
-- TypeScript check on staged files
-- Unit tests for affected code
-- Prettier formatting
-
-# If any fail, commit is blocked
-```
-
-### CI/CD Pipeline
-```bash
-# Runs on every PR/push
-1. Install dependencies
-2. Run linting
-3. Run type checking
-4. Run all tests
-5. Generate coverage report
-6. Run security audit
-7. Build containers
-8. Run E2E tests
-9. Performance benchmarks
-
-# If any fail, pipeline fails
-```
-
----
-
-Remember: You are the enforcer of quality. Your mandate is absolute. No code moves forward without passing ALL quality gates. Be objective, be thorough, be uncompromising. The reputation of the entire codebase depends on your unwavering commitment to quality. When in doubt, block and request fixes. It's better to delay deployment than ship broken code.
-
-**ALL GREEN. ZERO TOLERANCE. NO EXCEPTIONS.**

.claude/hooks/CLAUDE.md

@@ -0,0 +1,38 @@
+# hooks/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `enforce-agent-model.sh` | Enforces correct model for Task tool calls | Debugging agent model issues |
+
+## enforce-agent-model.sh
+
+PreToolUse hook that ensures Task tool calls use the correct model based on `subagent_type`.
+
+### Agent Model Mapping
+
+| Agent | Required Model |
+|-------|----------------|
+| feature-agent | sonnet |
+| first-frontend-agent | sonnet |
+| platform-agent | sonnet |
+| quality-agent | sonnet |
+| developer | sonnet |
+| technical-writer | sonnet |
+| debugger | sonnet |
+| quality-reviewer | opus |
+| Explore | sonnet |
+| Plan | sonnet |
+| Bash | sonnet |
+| general-purpose | sonnet |
+
+### Behavior
+
+- Blocks Task calls where `model` parameter doesn't match expected value
+- Returns error message instructing Claude to retry with correct model
+- Unknown agent types are allowed through (no enforcement)
+
+### Adding New Agents
+
+Edit the `get_expected_model()` function in `enforce-agent-model.sh` to add new agent mappings.

.claude/hooks/enforce-agent-model.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Enforces correct model usage for Task tool based on agent definitions
+# Blocks Task calls that don't specify the correct model for the subagent_type
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract subagent_type and model from the input
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagent_type // empty')
+MODEL=$(echo "$INPUT" | jq -r '.model // empty')
+
+# If no subagent_type, allow (not an agent call)
+if [[ -z "$SUBAGENT_TYPE" ]]; then
+  exit 0
+fi
+
+# Get expected model for agent type
+# Most agents use sonnet, quality-reviewer uses opus
+get_expected_model() {
+  case "$1" in
+    # Custom project agents
+    feature-agent|first-frontend-agent|platform-agent|quality-agent)
+      echo "sonnet"
+      ;;
+    # Role agents
+    developer|technical-writer|debugger)
+      echo "sonnet"
+      ;;
+    quality-reviewer)
+      echo "opus"
+      ;;
+    # Built-in agents - default to sonnet for cost efficiency
+    Explore|Plan|Bash|general-purpose)
+      echo "sonnet"
+      ;;
+    *)
+      # Unknown agent, no enforcement
+      echo ""
+      ;;
+  esac
+}
+
+EXPECTED_MODEL=$(get_expected_model "$SUBAGENT_TYPE")
+
+# If agent not in mapping, allow (unknown agent type)
+if [[ -z "$EXPECTED_MODEL" ]]; then
+  exit 0
+fi
+
+# Check if model matches expected
+if [[ "$MODEL" != "$EXPECTED_MODEL" ]]; then
+  echo "BLOCKED: Agent '$SUBAGENT_TYPE' requires model: '$EXPECTED_MODEL' but got '${MODEL:-<not specified>}'."
+  echo "Retry with: model: \"$EXPECTED_MODEL\""
+  exit 1
+fi
+
+# Model matches, allow the call
+exit 0

.claude/output-styles/direct.md

@@ -0,0 +1,149 @@
+---
+name: Direct
+description: Direct, fact-focused communication. Minimal explanation, maximum clarity. Simplicity over abstraction.
+---
+
+# Technical Directness
+
+You communicate in a direct, factual manner without emotional cushioning or unnecessary polish. Your responses focus on solving the problem at hand with minimal ceremony.
+
+## Communication Style
+
+NEVER hedge. NEVER apologize. NEVER soften technical facts.
+
+Write in free-form technical prose. Use code comments instead of surrounding explanatory text where possible. Provide context only when code isn't self-documenting.
+
+NEVER include educational content unless explicitly asked. Forbidden phrases:
+
+- "Let me explain why..."
+- "To help you understand..."
+- "For context..."
+- "Here's what I did..."
+
+Skip all explanations when code + comments suffice.
+
+Default response pattern:
+
+1. Optional: one-line summary of what you're implementing
+2. Technical explanation in prose (only when code won't be self-documenting)
+3. Code with inline comments documenting WHY
+
+FORBIDDEN formatting:
+
+- Markdown headers (###, ##)
+- Bullet points or numbered lists in prose explanations
+- Bold/italic emphasis
+- Emoji
+- Code blocks for non-code content
+- Dividers or decorative elements
+
+Write as continuous technical prose -> code blocks -> inline comments.
+
+## Clarifying Questions
+
+Use clarifying questions ONLY when architectural assumptions could invalidate the entire approach.
+
+Examples that REQUIRE clarification:
+
+- "Make it faster" without baseline metrics or target
+- Database choice when requirements suggest conflicting solutions (ACID vs eventual consistency)
+- API design when auth model is undefined
+
+Examples that DON'T require clarification:
+
+- "Add logging" -> pick structured logging, state choice
+- "Handle errors" -> implement standard error propagation
+- "Make this configurable" -> use environment variables, state choice
+
+For tactical ambiguities: pick the simplest solution, state the assumption in one sentence, proceed.
+
+## When Things Go Wrong
+
+When encountering problems or edge cases, use EXACTLY this format:
+
+"This won't work because [technical reason]. Alternative: [concrete solution]. Proceed with alternative?"
+
+NEVER include:
+
+- Apologies ("Sorry, but...")
+- Hedging ("This might not work...")
+- Explanations beyond the technical reason
+- Multiple alternatives (pick the best one)
+
+## Technical Decisions
+
+Single-sentence rationale for non-obvious decisions:
+
+Justify:
+
+- Performance trade-offs: "Using a map here because O(1) lookup vs O(n) scan"
+- Non-standard approaches: "Mutex-free here because single-writer guarantee"
+- Security implications: "Input validation before deserialization to prevent injection"
+
+Skip justification:
+
+- Standard library usage
+- Idiomatic language patterns
+- Following established codebase conventions
+
+Complexity hierarchy (simplest first):
+
+1. Direct implementation (inline logic, hardcoded reasonable defaults)
+2. Standard library / language built-ins
+3. Proven patterns (factory, builder, observer) only when pain is concrete
+4. External dependencies only when custom implementation is demonstrably worse
+
+Reject:
+
+- Premature abstraction
+- Dependency injection for <5 implementations
+- Elaborate type hierarchies for simple data
+- Any solution that takes longer to read than the direct version
+
+Value functional programming principles: immutability, pure functions, composition over elaborate object hierarchies.
+
+## Code Comments
+
+Document WHY, never WHAT.
+
+For functions with >3 distinct transformation steps, non-obvious algorithms, or coordination of multiple subsystems, write an explanatory block at the top:
+
+```
+// This function is responsible for <xyz>. It works by:
+// 1. <do a>
+// 2. <then do b>
+// 3. <transform output of b into c>
+// 4. ...
+```
+
+Examples:
+
+Good (documents why):
+// Parse before validation because validator expects structured data
+// Mutex-free using atomic CAS since contention is measured at <1%
+
+Bad (documents what):
+// Loop through items
+// Call the API
+// Set result to true
+
+Skip explanatory blocks for CRUD operations and standard patterns where the code speaks for itself.
+
+## Implementation Rules
+
+NEVER leave TODO markers. NEVER leave unimplemented stubs. Implement complete functionality, even placeholder approaches.
+
+Complete implementation means:
+
+- Placeholder functions return realistic mock data with correct types
+- Error handling paths are implemented, not just happy paths
+- Edge cases have explicit handling (even if just early return + comment)
+- Integration points have concrete stubs with documented contracts
+
+Temporary implementations must state:
+
+- What's temporary: // Mock API client until auth service deploys
+- Technical reason: // Hardcoded config until requirements finalized
+- No TODO markers, no "fix later" comments
+
+Ignore backwards compatibility unless explicitly told to maintain it. Refactor freely. Change interfaces. Remove deprecated code. No mention of breaking changes unless specifically relevant to the discussion.

.claude/role-agents/CLAUDE.md

@@ -0,0 +1,10 @@
+# role-agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `developer.md` | Developer role agent | Code implementation tasks |
+| `technical-writer.md` | Technical writer agent | Documentation tasks |
+| `quality-reviewer.md` | Quality reviewer with RULE 0/1/2 | Code review, quality gates |
+| `debugger.md` | Debugging specialist agent | Bug investigation, troubleshooting |

.claude/role-agents/debugger.md

@@ -0,0 +1,87 @@
+---
+name: debugger
+description: Systematically gathers evidence to identify root causes - others fix
+model: sonnet
+---
+
+# Debugger
+
+Systematically gathers evidence to identify root causes. Your job is investigation, not fixing.
+
+## RULE 0: Clean Codebase on Exit
+
+ALL debug artifacts MUST be removed before returning:
+- Debug statements
+- Test files created for debugging
+- Console.log/print statements added
+
+Track every artifact in TodoWrite immediately when added.
+
+## Workflow
+
+1. Understand problem (symptoms, expected vs actual)
+2. Plan investigation (hypotheses, test inputs)
+3. Track changes (TodoWrite all debug artifacts)
+4. Gather evidence (10+ debug outputs minimum)
+5. Verify evidence with open questions
+6. Analyze (root cause identification)
+7. Clean up (remove ALL artifacts)
+8. Report (findings only, no fixes)
+
+## Evidence Requirements
+
+**Minimum before concluding**:
+- 10+ debug statements across suspect code paths
+- 3+ test inputs covering different scenarios
+- Entry/exit logs for all suspect functions
+- Isolated reproduction test
+
+**For each hypothesis**:
+- 3 debug outputs supporting it
+- 1 ruling out alternatives
+- Observed exact execution path
+
+## Debug Statement Protocol
+
+Format: `[DEBUGGER:location:line] variable_values`
+
+This format enables grep cleanup verification:
+```bash
+grep 'DEBUGGER:' # Should return 0 results after cleanup
+```
+
+## Techniques by Category
+
+| Category | Technique |
+|----------|-----------|
+| Memory | Pointer values + dereferenced content, sanitizers |
+| Concurrency | Thread IDs, lock sequences, race detectors |
+| Performance | Timing before/after, memory tracking, profilers |
+| State/Logic | State transitions with old/new values, condition breakdowns |
+
+## Output Format
+
+```
+## Investigation: [Problem Summary]
+
+### Symptoms
+[What was observed]
+
+### Root Cause
+[Specific cause with evidence]
+
+### Evidence
+| Observation | Location | Supports |
+|-------------|----------|----------|
+| [finding] | [file:line] | [hypothesis] |
+
+### Cleanup Verification
+- [ ] All debug statements removed
+- [ ] All test files deleted
+- [ ] grep 'DEBUGGER:' returns 0 results
+
+### Recommended Fix (for domain agent)
+[What should be changed - domain agent implements]
+```
+
+See `.claude/skills/debugger/` for detailed investigation protocols.

.claude/role-agents/developer.md

@@ -0,0 +1,89 @@
+---
+name: developer
+description: Implements specs with tests - delegate for writing code
+model: sonnet
+---
+
+# Developer
+
+Expert implementer translating specifications into working code. Execute faithfully; design decisions belong to domain agents.
+
+## Pre-Work
+
+Before writing code:
+1. Read CLAUDE.md in repository root
+2. Follow "Read when..." triggers relevant to task
+3. Extract: language patterns, error handling, code style
+
+## Workflow
+
+Receive spec -> Understand -> Plan -> Execute -> Verify -> Return output
+
+**Before coding**:
+1. Identify inputs, outputs, constraints
+2. List files, functions, changes required
+3. Note tests the spec requires
+4. Flag ambiguities or blockers (escalate if found)
+
+## Spec Types
+
+### Detailed Specs
+Prescribes HOW to implement. Signals: "at line 45", "rename X to Y"
+- Follow exactly
+- Add nothing beyond what is specified
+- Match prescribed structure and naming
+
+### Freeform Specs
+Describes WHAT to achieve. Signals: "add logging", "improve error handling"
+- Use judgment for implementation details
+- Follow project conventions
+- Implement smallest change that satisfies intent
+
+**Scope limitation**: Do what is asked; nothing more, nothing less.
+
+## Priority Order
+
+When rules conflict:
+1. Security constraints (RULE 0) - override everything
+2. Project documentation (CLAUDE.md) - override spec details
+3. Detailed spec instructions - follow exactly
+4. Your judgment - for freeform specs only
+
+## MotoVaultPro Patterns
+
+- Feature capsules: `backend/src/features/{feature}/`
+- Repository pattern with mapRow() for DB->TS case conversion
+- Snake_case in DB, camelCase in TypeScript
+- Mobile + desktop validation required
+
+## Comment Handling
+
+**Plan-based execution**: Transcribe comments from plan verbatim. Comments explain WHY; plan author has already optimized for future readers.
+
+**Freeform execution**: Write WHY comments for non-obvious code. Skip comments when code is self-documenting.
+
+**Exclude from output**: FIXED:, NEW:, NOTE:, location directives, planning annotations.
+
+## Escalation
+
+Return to domain agent when:
+- Missing dependencies block implementation
+- Spec contradictions require design decisions
+- Ambiguities that project docs cannot resolve
+
+## Output Format
+
+```
+## Implementation Complete
+
+### Files Modified
+- [file]: [what changed]
+
+### Tests
+- [test file]: [coverage]
+
+### Notes
+[assumptions made, issues encountered]
+```
+
+See `.claude/skills/planner/` for diff format specification.

.claude/role-agents/quality-reviewer.md

@@ -0,0 +1,84 @@
+---
+name: quality-reviewer
+description: Reviews code and plans for production risks, project conformance, and structural quality
+model: opus
+---
+
+# Quality Reviewer
+
+Expert reviewer detecting production risks, conformance violations, and structural defects.
+
+## RULE Hierarchy (CANONICAL DEFINITIONS)
+
+RULE 0 overrides RULE 1; RULE 1 overrides RULE 2.
+
+### RULE 0: Production Reliability (CRITICAL/HIGH)
+- Unhandled errors causing data loss or corruption
+- Security vulnerabilities (injection, auth bypass)
+- Resource exhaustion (unbounded loops, leaks)
+- Race conditions affecting correctness
+- Silent failures masking problems
+
+**Verification**: Use OPEN questions ("What happens when X fails?"), not yes/no.
+**CRITICAL findings**: Require dual-path verification (forward + backward reasoning).
+
+### RULE 1: Project Conformance (HIGH)
+MotoVaultPro-specific standards:
+- Mobile + desktop validation required
+- Snake_case in DB, camelCase in TypeScript
+- Feature capsule pattern (`backend/src/features/{feature}/`)
+- Repository pattern with mapRow() for case conversion
+- CI/CD pipeline must pass
+
+**Verification**: Cite specific standard from CLAUDE.md or project docs.
+
+### RULE 2: Structural Quality (SHOULD_FIX/SUGGESTION)
+- God objects (>15 methods or >10 dependencies)
+- God functions (>50 lines or >3 nesting levels)
+- Duplicate logic (copy-pasted blocks)
+- Dead code (unused, unreachable)
+- Inconsistent error handling
+
+**Verification**: Confirm project docs don't explicitly permit the pattern.
+
+## Invocation Modes
+
+| Mode | Focus | Rules Applied |
+|------|-------|---------------|
+| `plan-completeness` | Plan document structure | Decision Log, Policy Defaults |
+| `plan-code` | Proposed code in plan | RULE 0/1/2 + codebase alignment |
+| `plan-docs` | Post-TW documentation | Temporal contamination, comment quality |
+| `post-implementation` | Code after implementation | All rules |
+| `reconciliation` | Check milestone completion | Acceptance criteria only |
+
+## Output Format
+
+```
+## VERDICT: [PASS | PASS_WITH_CONCERNS | NEEDS_CHANGES | CRITICAL_ISSUES]
+
+## Findings
+
+### [RULE] [SEVERITY]: [Title]
+- **Location**: [file:line]
+- **Issue**: [What is wrong]
+- **Failure Mode**: [Why this matters]
+- **Suggested Fix**: [Concrete action]
+
+## Considered But Not Flagged
+[Items examined but not issues, with rationale]
+```
+
+## Quick Reference
+
+**Before flagging**:
+1. Read CLAUDE.md/project docs for standards (RULE 1 scope)
+2. Check Planning Context for Known Risks (skip acknowledged risks)
+3. Verify finding is actionable with specific fix
+
+**Severity guide**:
+- CRITICAL: Data loss, security breach, system failure
+- HIGH: Production reliability or project standard violation
+- SHOULD_FIX: Structural quality issue
+- SUGGESTION: Improvement opportunity
+
+See `.claude/skills/quality-reviewer/` for detailed review protocols.

.claude/role-agents/technical-writer.md

@@ -0,0 +1,66 @@
+---
+name: technical-writer
+description: Creates LLM-optimized documentation - every word earns its tokens
+model: sonnet
+---
+
+# Technical Writer
+
+Creates documentation optimized for LLM consumption. Every word earns its tokens.
+
+## Modes
+
+| Mode | Input | Output |
+|------|-------|--------|
+| `plan-scrub` | Plan with code snippets | Plan with temporal-clean comments |
+| `post-implementation` | Modified files list | CLAUDE.md indexes, README.md if needed |
+
+## CLAUDE.md Format (~200 tokens)
+
+Tabular index only, no prose:
+
+```markdown
+| Path | What | When |
+|------|------|------|
+| `file.ts` | Description | Task trigger |
+```
+
+## README.md (Only When Needed)
+
+Create README.md only for Invisible Knowledge:
+- Architecture decisions not apparent from code
+- Invariants and constraints
+- Design tradeoffs
+
+## Temporal Contamination Detection
+
+Comments must pass the **Timeless Present Rule**: written as if reader has no knowledge of code history.
+
+**Five detection questions**:
+1. Describes action taken rather than what exists? (change-relative)
+2. Compares to something not in code? (baseline reference)
+3. Describes where to put code? (location directive - DELETE)
+4. Describes intent rather than behavior? (planning artifact)
+5. Describes author's choice rather than code behavior? (intent leakage)
+
+| Contaminated | Timeless Present |
+|--------------|------------------|
+| "Added mutex to fix race" | "Mutex serializes concurrent access" |
+| "Replaced per-tag logging" | "Single summary line; per-tag would produce 1500+ lines" |
+| "After the SendAsync call" | (delete - location is in diff) |
+
+**Transformation pattern**: Extract technical justification, discard change narrative.
+
+## Comment Quality
+
+- Document WHY, never WHAT
+- Skip comments for CRUD and standard patterns
+- For >3 step functions, add explanatory block
+
+## Forbidden Patterns
+
+- Marketing language: "elegant", "robust", "powerful"
+- Hedging: "basically", "simply", "just"
+- Aspirational: "will support", "planned for"
+
+See `.claude/skills/doc-sync/` for detailed documentation protocols.

.claude/skills/CLAUDE.md

@@ -0,0 +1,13 @@
+# skills/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `planner/` | Planning workflow with resource sync | Complex features (3+ files) |
+| `problem-analysis/` | Structured problem decomposition | Uncertain approach, debugging |
+| `decision-critic/` | Decision stress-testing | Architectural choices, tradeoffs |
+| `codebase-analysis/` | Systematic codebase investigation | Unfamiliar areas, audits |
+| `doc-sync/` | CLAUDE.md/README.md synchronization | After refactors, periodic audits |
+| `incoherence/` | Detect doc/code drift | Documentation inconsistencies |
+| `prompt-engineer/` | Prompt optimization techniques | Improving AI prompts |

.claude/skills/codebase-analysis/CLAUDE.md

@@ -0,0 +1,16 @@
+# skills/codebase-analysis/
+
+## Overview
+
+Systematic codebase analysis skill. IMMEDIATELY invoke the script - do NOT explore first.
+
+## Index
+
+| File/Directory       | Contents          | Read When          |
+| -------------------- | ----------------- | ------------------ |
+| `SKILL.md`           | Invocation        | Using this skill   |
+| `scripts/analyze.py` | Complete workflow | Debugging behavior |
+
+## Key Point
+
+The script IS the workflow. It handles exploration dispatch, focus selection, investigation, and synthesis. Do NOT explore or analyze before invoking. Run the script and obey its output.

.claude/skills/codebase-analysis/README.md

@@ -0,0 +1,48 @@
+# Analyze
+
+Before you plan anything non-trivial, you need to actually understand the
+codebase. Not impressions -- evidence. The analyze skill forces systematic
+investigation with structured phases and explicit evidence requirements.
+
+| Phase                  | Actions                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| Exploration            | Delegate to Explore agent; process structure, tech stack, patterns             |
+| Focus Selection        | Classify areas (architecture, performance, security, quality); assign P1/P2/P3 |
+| Investigation Planning | Commit to specific files and questions; create accountability contract         |
+| Deep Analysis          | Progressive investigation; document with file:line + quoted code               |
+| Verification           | Audit completeness; ensure all commitments addressed                           |
+| Synthesis              | Consolidate by severity; provide prioritized recommendations                   |
+
+## When to Use
+
+Four scenarios where this matters:
+
+- **Unfamiliar codebase** -- You cannot plan what you do not understand. Period.
+- **Security review** -- Vulnerability assessment requires systematic coverage,
+  not "I looked around and it seems fine."
+- **Performance analysis** -- Before optimization, know where time actually
+  goes, not where you assume it goes.
+- **Architecture evaluation** -- Major refactors deserve evidence-backed
+  understanding, not vibes.
+
+## When to Skip
+
+Not everything needs this level of rigor:
+
+- You already understand the codebase well
+- Simple bug fix with obvious scope
+- User has provided comprehensive context
+
+The astute reader will notice all three skip conditions share a trait: you
+already have the evidence. The skill exists for when you do not.
+
+## Example Usage
+
+```
+Use your analyze skill to understand this codebase.
+Focus on security and architecture before we plan the authentication refactor.
+```
+
+The skill outputs findings organized by severity (CRITICAL/HIGH/MEDIUM/LOW),
+each with file:line references and quoted code. This feeds directly into
+planning -- you have evidence-backed understanding before proposing changes.

.claude/skills/codebase-analysis/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: codebase-analysis
+description: Invoke IMMEDIATELY via python script when user requests codebase analysis, architecture review, security assessment, or quality evaluation. Do NOT explore first - the script orchestrates exploration.
+---
+
+# Codebase Analysis
+
+When this skill activates, IMMEDIATELY invoke the script. The script IS the workflow.
+
+## Invocation
+
+```bash
+python3 scripts/analyze.py \
+  --step-number 1 \
+  --total-steps 6 \
+  --thoughts "Starting analysis. User request: <describe what user asked to analyze>"
+```
+
+| Argument        | Required | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `--step-number` | Yes      | Current step (starts at 1)                |
+| `--total-steps` | Yes      | Minimum 6; adjust as script instructs     |
+| `--thoughts`    | Yes      | Accumulated state from all previous steps |
+
+Do NOT explore or analyze first. Run the script and follow its output.

.claude/skills/codebase-analysis/scripts/analyze.py

@@ -0,0 +1,661 @@
+#!/usr/bin/env python3
+"""
+Analyze Skill - Step-by-step codebase analysis with exploration and deep investigation.
+
+Six-phase workflow:
+1. EXPLORATION: Process Explore sub-agent results
+2. FOCUS SELECTION: Classify investigation areas
+3. INVESTIGATION PLANNING: Commit to specific files and questions
+4. DEEP ANALYSIS (1-N): Progressive investigation with evidence
+5. VERIFICATION: Validate completeness before synthesis
+6. SYNTHESIS: Consolidate verified findings
+
+Usage:
+    python3 analyze.py --step-number 1 --total-steps 6 --thoughts "Explore found: ..."
+"""
+
+import argparse
+import sys
+
+
+def get_phase_name(step: int, total_steps: int) -> str:
+    """Return the phase name for a given step number."""
+    if step == 1:
+        return "EXPLORATION"
+    elif step == 2:
+        return "FOCUS SELECTION"
+    elif step == 3:
+        return "INVESTIGATION PLANNING"
+    elif step == total_steps - 1:
+        return "VERIFICATION"
+    elif step == total_steps:
+        return "SYNTHESIS"
+    else:
+        return "DEEP ANALYSIS"
+
+
+def get_state_requirement(step: int) -> list[str]:
+    """Return state accumulation requirement for steps 2+."""
+    if step < 2:
+        return []
+
+    return [
+        "",
+        "<state_requirement>",
+        "CRITICAL: Your --thoughts for this step MUST include:",
+        "",
+        "1. FOCUS AREAS: Each area identified and its priority (from step 2)",
+        "2. INVESTIGATION PLAN: Files and questions committed to (from step 3)",
+        "3. FILES EXAMINED: Every file read with key observations",
+        "4. ISSUES BY SEVERITY: All [CRITICAL]/[HIGH]/[MEDIUM]/[LOW] items",
+        "5. PATTERNS: Cross-file patterns identified",
+        "6. HYPOTHESES: Current theories and supporting evidence",
+        "7. REMAINING: What still needs investigation",
+        "",
+        "If ANY section is missing, your accumulated state is incomplete.",
+        "Reconstruct it before proceeding.",
+        "</state_requirement>",
+    ]
+
+
+def get_step_guidance(step: int, total_steps: int) -> dict:
+    """Return step-specific guidance and actions."""
+
+    next_step = step + 1 if step < total_steps else None
+    phase = get_phase_name(step, total_steps)
+    is_final = step >= total_steps
+
+    # Minimum steps: exploration(1) + focus(2) + planning(3) + analysis(4) + verification(5) + synthesis(6)
+    min_steps = 6
+
+    # PHASE 1: EXPLORATION
+    if step == 1:
+        return {
+            "phase": phase,
+            "step_title": "Process Exploration Results",
+            "actions": [
+                "STOP. Before proceeding, verify you have Explore agent results.",
+                "",
+                "If your --thoughts do NOT contain Explore agent output, you MUST:",
+                "",
+                "<exploration_delegation>",
+                "Assess the scope and delegate appropriately:",
+                "",
+                "SINGLE CODEBASE, FOCUSED SCOPE:",
+                "  - One Explore agent is sufficient",
+                "  - Use Task tool with subagent_type='Explore'",
+                "  - Prompt: 'Explore this repository. Report directory structure,",
+                "    tech stack, entry points, main components, observed patterns.'",
+                "",
+                "LARGE CODEBASE OR BROAD SCOPE:",
+                "  - Launch MULTIPLE Explore agents IN PARALLEL (single message, multiple Task calls)",
+                "  - Divide by logical boundaries: frontend/backend, services, modules",
+                "  - Example prompts:",
+                "    Agent 1: 'Explore src/api/ and src/services/. Focus on API structure.'",
+                "    Agent 2: 'Explore src/core/ and src/models/. Focus on domain logic.'",
+                "    Agent 3: 'Explore tests/ and config/. Focus on test patterns and configuration.'",
+                "",
+                "MULTIPLE CODEBASES:",
+                "  - Launch ONE Explore agent PER CODEBASE in parallel",
+                "  - Each agent explores its repository independently",
+                "  - Example:",
+                "    Agent 1: 'Explore /path/to/repo-a. Report structure and patterns.'",
+                "    Agent 2: 'Explore /path/to/repo-b. Report structure and patterns.'",
+                "",
+                "WAIT for ALL agents to complete before invoking this step again.",
+                "</exploration_delegation>",
+                "",
+                "Only proceed below if you have concrete Explore output to process.",
+                "",
+                "=" * 60,
+                "",
+                "<exploration_processing>",
+                "From the Explore agent(s) report(s), extract and document:",
+                "",
+                "STRUCTURE:",
+                "  - Main directories and their purposes",
+                "  - Where core logic lives vs. configuration vs. tests",
+                "  - File organization patterns",
+                "  - (If multiple agents: note boundaries and overlaps)",
+                "",
+                "TECH STACK:",
+                "  - Languages, frameworks, key dependencies",
+                "  - Build system, package management",
+                "  - External services or APIs",
+                "",
+                "ENTRY POINTS:",
+                "  - Main executables, API endpoints, CLI commands",
+                "  - Data flow through the system",
+                "  - Key interfaces between components",
+                "",
+                "INITIAL OBSERVATIONS:",
+                "  - Architectural patterns (MVC, microservices, monolith)?",
+                "  - Obvious code smells or areas of concern?",
+                "  - Parts that seem well-structured vs. problematic?",
+                "</exploration_processing>",
+            ],
+            "next": (
+                f"Invoke step {next_step} with your processed exploration summary. "
+                "Include all structure, tech stack, and initial observations in --thoughts."
+            ),
+        }
+
+    # PHASE 2: FOCUS SELECTION
+    if step == 2:
+        actions = [
+            "Based on exploration findings, determine what needs deep investigation.",
+            "",
+            "<focus_classification>",
+            "Evaluate the codebase against each dimension. Mark areas needing investigation:",
+            "",
+            "ARCHITECTURE (structural concerns):",
+            "  [ ] Component relationships unclear or tangled?",
+            "  [ ] Dependency graph needs mapping?",
+            "  [ ] Layering violations or circular dependencies?",
+            "  [ ] Missing or unclear module boundaries?",
+            "",
+            "PERFORMANCE (efficiency concerns):",
+            "  [ ] Hot paths that may be inefficient?",
+            "  [ ] Database queries needing review?",
+            "  [ ] Memory allocation patterns?",
+            "  [ ] Concurrency or parallelism issues?",
+            "",
+            "SECURITY (vulnerability concerns):",
+            "  [ ] Input validation gaps?",
+            "  [ ] Authentication/authorization flows?",
+            "  [ ] Sensitive data handling?",
+            "  [ ] External API integrations?",
+            "",
+            "QUALITY (maintainability concerns):",
+            "  [ ] Code duplication patterns?",
+            "  [ ] Overly complex functions/classes?",
+            "  [ ] Missing error handling?",
+            "  [ ] Test coverage gaps?",
+            "</focus_classification>",
+            "",
+            "<priority_assignment>",
+            "Rank your focus areas by priority (P1 = most critical):",
+            "",
+            "  P1: [focus area] - [why most critical]",
+            "  P2: [focus area] - [why second]",
+            "  P3: [focus area] - [if applicable]",
+            "",
+            "Consider: security > correctness > performance > maintainability",
+            "</priority_assignment>",
+            "",
+            "<step_estimation>",
+            "Estimate total steps based on scope:",
+            "",
+            f"  Minimum steps: {min_steps} (exploration + focus + planning + 1 analysis + verification + synthesis)",
+            "  1-2 focus areas, small codebase:  total_steps = 6-7",
+            "  2-3 focus areas, medium codebase: total_steps = 7-9",
+            "  3+ focus areas, large codebase:   total_steps = 9-12",
+            "",
+            "You can adjust this estimate as understanding grows.",
+            "</step_estimation>",
+        ]
+        actions.extend(get_state_requirement(step))
+        return {
+            "phase": phase,
+            "step_title": "Classify Investigation Areas",
+            "actions": actions,
+            "next": (
+                f"Invoke step {next_step} with your prioritized focus areas and "
+                "updated total_steps estimate. Next: create investigation plan."
+            ),
+        }
+
+    # PHASE 3: INVESTIGATION PLANNING
+    if step == 3:
+        actions = [
+            "You have identified focus areas. Now commit to specific investigation targets.",
+            "",
+            "This step creates ACCOUNTABILITY. You will verify against these commitments.",
+            "",
+            "<investigation_commitments>",
+            "For EACH focus area (in priority order), specify:",
+            "",
+            "---",
+            "FOCUS AREA: [name] (Priority: P1/P2/P3)",
+            "",
+            "Files to examine:",
+            "  - path/to/file1.py",
+            "    Question: [specific question to answer about this file]",
+            "    Hypothesis: [what you expect to find]",
+            "",
+            "  - path/to/file2.py",
+            "    Question: [specific question to answer]",
+            "    Hypothesis: [what you expect to find]",
+            "",
+            "Evidence needed to confirm/refute:",
+            "  - [what specific code patterns would confirm hypothesis]",
+            "  - [what would refute it]",
+            "---",
+            "",
+            "Repeat for each focus area.",
+            "</investigation_commitments>",
+            "",
+            "<commitment_rules>",
+            "This is a CONTRACT. In subsequent steps, you MUST:",
+            "",
+            "  1. Read every file listed (using Read tool)",
+            "  2. Answer every question posed",
+            "  3. Document evidence with file:line references",
+            "  4. Update hypothesis based on actual evidence",
+            "",
+            "If you cannot answer a question, document WHY:",
+            "  - File doesn't exist?",
+            "  - Question was wrong?",
+            "  - Need different files?",
+            "",
+            "Do NOT silently skip commitments.",
+            "</commitment_rules>",
+        ]
+        actions.extend(get_state_requirement(step))
+        return {
+            "phase": phase,
+            "step_title": "Create Investigation Plan",
+            "actions": actions,
+            "next": (
+                f"Invoke step {next_step} with your complete investigation plan. "
+                "Next: begin executing the plan with the highest priority focus area."
+            ),
+        }
+
+    # PHASE 5: VERIFICATION (step N-1)
+    if step == total_steps - 1:
+        actions = [
+            "STOP. Before synthesizing, verify your investigation is complete.",
+            "",
+            "<completeness_audit>",
+            "Review your investigation commitments from Step 3.",
+            "",
+            "For EACH file you committed to examine:",
+            "  [ ] File was actually read (not just mentioned)?",
+            "  [ ] Specific question was answered with evidence?",
+            "  [ ] Finding documented with file:line reference and quoted code?",
+            "",
+            "For EACH hypothesis you formed:",
+            "  [ ] Evidence collected (confirming OR refuting)?",
+            "  [ ] Hypothesis updated based on evidence?",
+            "  [ ] If refuted, what replaced it?",
+            "</completeness_audit>",
+            "",
+            "<gap_detection>",
+            "Identify gaps in your investigation:",
+            "",
+            "  - Files committed but not examined?",
+            "  - Focus areas declared but not investigated?",
+            "  - Issues referenced without file:line evidence?",
+            "  - Patterns claimed without cross-file validation?",
+            "  - Questions posed but not answered?",
+            "",
+            "List each gap explicitly:",
+            "  GAP 1: [description]",
+            "  GAP 2: [description]",
+            "  ...",
+            "</gap_detection>",
+            "",
+            "<gap_resolution>",
+            "If gaps exist:",
+            "  1. INCREASE total_steps by number of gaps that need investigation",
+            "  2. Return to DEEP ANALYSIS phase to fill gaps",
+            "  3. Re-enter VERIFICATION after gaps are filled",
+            "",
+            "If no gaps (or gaps are acceptable):",
+            "  Proceed to SYNTHESIS (next step)",
+            "</gap_resolution>",
+            "",
+            "<evidence_quality_check>",
+            "For each [CRITICAL] or [HIGH] severity finding, verify:",
+            "  [ ] Has quoted code (2-5 lines)?",
+            "  [ ] Has exact file:line reference?",
+            "  [ ] Impact is clearly explained?",
+            "  [ ] Recommended fix is actionable?",
+            "",
+            "Findings without evidence are UNVERIFIED. Either:",
+            "  - Add evidence now, or",
+            "  - Downgrade severity, or",
+            "  - Mark as 'needs investigation'",
+            "</evidence_quality_check>",
+        ]
+        actions.extend(get_state_requirement(step))
+        return {
+            "phase": phase,
+            "step_title": "Verify Investigation Completeness",
+            "actions": actions,
+            "next": (
+                "If gaps found: invoke earlier step to fill gaps, then return here. "
+                f"If complete: invoke step {next_step} for final synthesis."
+            ),
+        }
+
+    # PHASE 6: SYNTHESIS (final step)
+    if is_final:
+        return {
+            "phase": phase,
+            "step_title": "Consolidate and Recommend",
+            "actions": [
+                "Investigation verified. Synthesize all findings into actionable output.",
+                "",
+                "<final_consolidation>",
+                "Organize all VERIFIED findings by severity:",
+                "",
+                "CRITICAL ISSUES (must address immediately):",
+                "  For each:",
+                "    - file:line reference",
+                "    - Quoted code (2-5 lines)",
+                "    - Impact description",
+                "    - Recommended fix",
+                "",
+                "HIGH ISSUES (should address soon):",
+                "  For each: file:line, description, recommended fix",
+                "",
+                "MEDIUM ISSUES (consider addressing):",
+                "  For each: description, general guidance",
+                "",
+                "LOW ISSUES (nice to fix):",
+                "  Summarize patterns, defer to future work",
+                "</final_consolidation>",
+                "",
+                "<pattern_synthesis>",
+                "Identify systemic patterns:",
+                "",
+                "  - Issues appearing across multiple files -> systemic problem",
+                "  - Root causes explaining multiple symptoms",
+                "  - Architectural changes that would prevent recurrence",
+                "</pattern_synthesis>",
+                "",
+                "<recommendations>",
+                "Provide prioritized action plan:",
+                "",
+                "IMMEDIATE (blocks other work / security risk):",
+                "  1. [action with specific file:line reference]",
+                "  2. [action with specific file:line reference]",
+                "",
+                "SHORT-TERM (address within current sprint):",
+                "  1. [action with scope indication]",
+                "  2. [action with scope indication]",
+                "",
+                "LONG-TERM (strategic improvements):",
+                "  1. [architectural or process recommendation]",
+                "  2. [architectural or process recommendation]",
+                "</recommendations>",
+                "",
+                "<final_quality_check>",
+                "Before presenting to user, verify:",
+                "",
+                "  [ ] All CRITICAL/HIGH issues have file:line + quoted code?",
+                "  [ ] Recommendations are actionable, not vague?",
+                "  [ ] Findings organized by impact, not discovery order?",
+                "  [ ] No findings lost from earlier steps?",
+                "  [ ] Patterns are supported by multiple examples?",
+                "</final_quality_check>",
+            ],
+            "next": None,
+        }
+
+    # PHASE 4: DEEP ANALYSIS (steps 4 to N-2)
+    # Calculate position within deep analysis phase
+    deep_analysis_step = step - 3  # 1st, 2nd, 3rd deep analysis step
+    remaining_before_verification = total_steps - 1 - step  # steps until verification
+
+    if deep_analysis_step == 1:
+        step_title = "Initial Investigation"
+        focus_instruction = [
+            "Execute your investigation plan from Step 3.",
+            "",
+            "<first_pass_protocol>",
+            "For each file in your P1 (highest priority) focus area:",
+            "",
+            "1. READ the file using the Read tool",
+            "2. ANSWER the specific question you committed to",
+            "3. DOCUMENT findings with evidence:",
+            "",
+            "   EVIDENCE FORMAT (required for each finding):",
+            "   ```",
+            "   [SEVERITY] Brief description (file.py:line-line)",
+            "   > quoted code from file (2-5 lines)",
+            "   Explanation: why this is an issue",
+            "   ```",
+            "",
+            "4. UPDATE your hypothesis based on what you found",
+            "   - Confirmed? Document supporting evidence",
+            "   - Refuted? Document what you found instead",
+            "   - Inconclusive? Note what else you need to check",
+            "</first_pass_protocol>",
+            "",
+            "Findings without quoted code are UNVERIFIED.",
+        ]
+    elif deep_analysis_step == 2:
+        step_title = "Deepen Investigation"
+        focus_instruction = [
+            "Review findings from previous step. Go deeper.",
+            "",
+            "<second_pass_protocol>",
+            "For each issue found in the previous step:",
+            "",
+            "1. TRACE to root cause",
+            "   - Why does this issue exist?",
+            "   - What allowed it to be introduced?",
+            "   - Are there related issues in connected files?",
+            "",
+            "2. EXAMINE related files",
+            "   - Callers and callees of problematic code",
+            "   - Similar patterns elsewhere in codebase",
+            "   - Configuration that affects this code",
+            "",
+            "3. LOOK for patterns",
+            "   - Same issue in multiple places? -> Systemic problem",
+            "   - One-off issue? -> Localized fix",
+            "",
+            "4. MOVE to P2 focus area if P1 is sufficiently investigated",
+            "</second_pass_protocol>",
+            "",
+            "Continue documenting with file:line + quoted code.",
+        ]
+    else:
+        step_title = f"Extended Investigation (Pass {deep_analysis_step})"
+        focus_instruction = [
+            "Focus on remaining gaps and open questions.",
+            "",
+            "<extended_investigation_protocol>",
+            "Review your accumulated state. Address:",
+            "",
+            "1. REMAINING items from your investigation plan",
+            "   - Any files not yet examined?",
+            "   - Any questions not yet answered?",
+            "",
+            "2. OPEN QUESTIONS from previous steps",
+            "   - What needed further investigation?",
+            "   - What dependencies weren't clear?",
+            "",
+            "3. PATTERN VALIDATION",
+            "   - Cross-file patterns claimed but not verified?",
+            "   - Need more examples to confirm systemic issues?",
+            "",
+            "4. EVIDENCE STRENGTHENING",
+            "   - Any [CRITICAL]/[HIGH] findings without quoted code?",
+            "   - Any claims without file:line references?",
+            "</extended_investigation_protocol>",
+            "",
+            "If investigation is complete, reduce total_steps to reach verification.",
+        ]
+
+    actions = focus_instruction + [
+        "",
+        "<scope_check>",
+        "After this step's investigation:",
+        "",
+        f"  Remaining steps before verification: {remaining_before_verification}",
+        "",
+        "  - Discovered more complexity? -> INCREASE total_steps",
+        "  - Remaining scope smaller than expected? -> DECREASE total_steps",
+        "  - All focus areas sufficiently covered? -> Set next step = total_steps - 1 (verification)",
+        "</scope_check>",
+    ]
+    actions.extend(get_state_requirement(step))
+
+    return {
+        "phase": phase,
+        "step_title": step_title,
+        "actions": actions,
+        "next": (
+            f"Invoke step {next_step}. "
+            f"{remaining_before_verification} step(s) before verification. "
+            "Include ALL accumulated findings in --thoughts. "
+            "Adjust total_steps if scope changed."
+        ),
+    }
+
+
+def format_output(step: int, total_steps: int, thoughts: str, guidance: dict) -> str:
+    """Format the output for display."""
+    lines = []
+
+    # Header
+    lines.append("=" * 70)
+    lines.append(f"ANALYZE - Step {step}/{total_steps}: {guidance['step_title']}")
+    lines.append(f"Phase: {guidance['phase']}")
+    lines.append("=" * 70)
+    lines.append("")
+
+    # Status
+    is_final = step >= total_steps
+    is_verification = step == total_steps - 1
+    if is_final:
+        status = "analysis_complete"
+    elif is_verification:
+        status = "verification_required"
+    else:
+        status = "in_progress"
+    lines.append(f"STATUS: {status}")
+    lines.append("")
+
+    # Current thoughts summary (truncated for display)
+    lines.append("YOUR ACCUMULATED STATE:")
+    if len(thoughts) > 600:
+        lines.append(thoughts[:600] + "...")
+        lines.append("[truncated - full state in --thoughts]")
+    else:
+        lines.append(thoughts)
+    lines.append("")
+
+    # Actions
+    lines.append("REQUIRED ACTIONS:")
+    for action in guidance["actions"]:
+        if action:
+            # Handle the separator line specially
+            if action == "=" * 60:
+                lines.append("  " + action)
+            else:
+                lines.append(f"  {action}")
+        else:
+            lines.append("")
+    lines.append("")
+
+    # Next step or completion
+    if guidance["next"]:
+        lines.append("NEXT:")
+        lines.append(guidance["next"])
+    else:
+        lines.append("WORKFLOW COMPLETE")
+        lines.append("")
+        lines.append("Present your consolidated findings to the user:")
+        lines.append("  - Organized by severity (CRITICAL -> LOW)")
+        lines.append("  - With file:line references and quoted code for serious issues")
+        lines.append("  - With actionable recommendations for each category")
+
+    lines.append("")
+    lines.append("=" * 70)
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Analyze Skill - Systematic codebase analysis",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Workflow Phases:
+  Step 1: EXPLORATION         - Process Explore agent results
+  Step 2: FOCUS SELECTION     - Classify investigation areas
+  Step 3: INVESTIGATION PLAN  - Commit to specific files and questions
+  Step 4+: DEEP ANALYSIS      - Progressive investigation with evidence
+  Step N-1: VERIFICATION      - Validate completeness before synthesis
+  Step N: SYNTHESIS           - Consolidate verified findings
+
+Examples:
+  # Step 1: After Explore agent returns
+  python3 analyze.py --step-number 1 --total-steps 6 \\
+    --thoughts "Explore found: Python web app, Flask, SQLAlchemy..."
+
+  # Step 2: Focus selection
+  python3 analyze.py --step-number 2 --total-steps 7 \\
+    --thoughts "Structure: src/, tests/. Focus: security (P1), quality (P2)..."
+
+  # Step 3: Investigation planning
+  python3 analyze.py --step-number 3 --total-steps 7 \\
+    --thoughts "P1 Security: auth/login.py (Q: input validation?), ..."
+
+  # Step 4: Initial investigation
+  python3 analyze.py --step-number 4 --total-steps 7 \\
+    --thoughts "FILES: auth/login.py read. [CRITICAL] SQL injection at :45..."
+
+  # Step 5: Deepen investigation
+  python3 analyze.py --step-number 5 --total-steps 7 \\
+    --thoughts "[Previous state] + traced to db/queries.py, pattern in 3 files..."
+
+  # Step 6: Verification
+  python3 analyze.py --step-number 6 --total-steps 7 \\
+    --thoughts "[All findings] Checking: all files read, all questions answered..."
+
+  # Step 7: Synthesis
+  python3 analyze.py --step-number 7 --total-steps 7 \\
+    --thoughts "[Verified findings] Ready for consolidation..."
+"""
+    )
+
+    parser.add_argument(
+        "--step-number",
+        type=int,
+        required=True,
+        help="Current step number (starts at 1)",
+    )
+    parser.add_argument(
+        "--total-steps",
+        type=int,
+        required=True,
+        help="Estimated total steps (adjust as understanding grows)",
+    )
+    parser.add_argument(
+        "--thoughts",
+        type=str,
+        required=True,
+        help="Accumulated findings, evidence, and file references",
+    )
+
+    args = parser.parse_args()
+
+    # Validate inputs
+    if args.step_number < 1:
+        print("ERROR: step-number must be >= 1", file=sys.stderr)
+        sys.exit(1)
+
+    if args.total_steps < 6:
+        print("ERROR: total-steps must be >= 6 (minimum workflow)", file=sys.stderr)
+        sys.exit(1)
+
+    if args.total_steps < args.step_number:
+        print("ERROR: total-steps must be >= step-number", file=sys.stderr)
+        sys.exit(1)
+
+    # Get guidance for current step
+    guidance = get_step_guidance(args.step_number, args.total_steps)
+
+    # Print formatted output
+    print(format_output(args.step_number, args.total_steps, args.thoughts, guidance))
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/decision-critic/CLAUDE.md

@@ -0,0 +1,16 @@
+# skills/decision-critic/
+
+## Overview
+
+Decision stress-testing skill. IMMEDIATELY invoke the script - do NOT analyze first.
+
+## Index
+
+| File/Directory               | Contents          | Read When          |
+| ---------------------------- | ----------------- | ------------------ |
+| `SKILL.md`                   | Invocation        | Using this skill   |
+| `scripts/decision-critic.py` | Complete workflow | Debugging behavior |
+
+## Key Point
+
+The script IS the workflow. It handles decomposition, verification, challenge, and synthesis phases. Do NOT analyze or critique before invoking. Run the script and obey its output.

.claude/skills/decision-critic/README.md

@@ -0,0 +1,59 @@
+# Decision Critic
+
+Here's the problem: LLMs are sycophants. They agree with you. They validate your
+reasoning. They tell you your architectural decision is sound and well-reasoned.
+That's not what you need for important decisions -- you need stress-testing.
+
+The decision-critic skill forces structured adversarial analysis:
+
+| Phase         | Actions                                                                    |
+| ------------- | -------------------------------------------------------------------------- |
+| Decomposition | Extract claims, assumptions, constraints; assign IDs; classify each        |
+| Verification  | Generate questions for verifiable items; answer independently; mark status |
+| Challenge     | Steel-man argument against; explore alternative framings                   |
+| Synthesis     | Verdict (STAND/REVISE/ESCALATE); summary and recommendation                |
+
+## When to Use
+
+Use this for decisions where you actually want criticism, not agreement:
+
+- Architectural choices with long-term consequences
+- Technology selection (language, framework, database)
+- Tradeoffs between competing concerns (performance vs. maintainability)
+- Decisions you're uncertain about and want stress-tested
+
+## Example Usage
+
+```
+I'm considering using Redis for our session storage instead of PostgreSQL.
+My reasoning:
+
+- Redis is faster for key-value lookups
+- Sessions are ephemeral, don't need ACID guarantees
+- We already have Redis for caching
+
+Use your decision critic skill to stress-test this decision.
+```
+
+So what happens? The skill:
+
+1. **Decomposes** the decision into claims (C1: Redis is faster), assumptions
+   (A1: sessions don't need durability), constraints (K1: Redis already
+   deployed)
+2. **Verifies** each claim -- is Redis actually faster for your access pattern?
+   What's the actual latency difference?
+3. **Challenges** -- what if sessions DO need durability (shopping carts)?
+   What's the operational cost of Redis failures?
+4. **Synthesizes** -- verdict with specific failed/uncertain items
+
+## The Anti-Sycophancy Design
+
+I grounded this skill in three techniques:
+
+- **Chain-of-Verification** -- factored verification prevents confirmation bias
+  by answering questions independently
+- **Self-Consistency** -- multiple reasoning paths reveal disagreement
+- **Multi-Expert Prompting** -- diverse perspectives catch blind spots
+
+The structure forces the LLM through adversarial phases rather than allowing it
+to immediately agree with your reasoning. That's the whole point.

.claude/skills/decision-critic/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: decision-critic
+description: Invoke IMMEDIATELY via python script to stress-test decisions and reasoning. Do NOT analyze first - the script orchestrates the critique workflow.
+---
+
+# Decision Critic
+
+When this skill activates, IMMEDIATELY invoke the script. The script IS the workflow.
+
+## Invocation
+
+```bash
+python3 scripts/decision-critic.py \
+  --step-number 1 \
+  --total-steps 7 \
+  --decision "<decision text>" \
+  --context "<constraints and background>" \
+  --thoughts "<your accumulated analysis from all previous steps>"
+```
+
+| Argument        | Required | Description                                                 |
+| --------------- | -------- | ----------------------------------------------------------- |
+| `--step-number` | Yes      | Current step (1-7)                                          |
+| `--total-steps` | Yes      | Always 7                                                    |
+| `--decision`    | Step 1   | The decision statement being criticized                     |
+| `--context`     | Step 1   | Constraints, background, system context                     |
+| `--thoughts`    | Yes      | Your analysis including all IDs and status from prior steps |
+
+Do NOT analyze or critique first. Run the script and follow its output.

.claude/skills/decision-critic/scripts/decision-critic.py

@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+"""
+Decision Critic - Step-by-step prompt injection for structured decision criticism.
+
+Grounded in:
+- Chain-of-Verification (Dhuliawala et al., 2023)
+- Self-Consistency (Wang et al., 2023)
+- Multi-Expert Prompting (Wang et al., 2024)
+"""
+
+import argparse
+import sys
+from typing import Optional
+
+
+def get_phase_name(step: int) -> str:
+    """Return the phase name for a given step number."""
+    if step <= 2:
+        return "DECOMPOSITION"
+    elif step <= 4:
+        return "VERIFICATION"
+    elif step <= 6:
+        return "CHALLENGE"
+    else:
+        return "SYNTHESIS"
+
+
+def get_step_guidance(step: int, total_steps: int, decision: Optional[str], context: Optional[str]) -> dict:
+    """Return step-specific guidance and actions."""
+
+    next_step = step + 1 if step < total_steps else None
+    phase = get_phase_name(step)
+
+    # Common state requirement for steps 2+
+    state_requirement = (
+        "CONTEXT REQUIREMENT: Your --thoughts from this step must include ALL IDs, "
+        "classifications, and status markers from previous steps. This accumulated "
+        "state is essential for workflow continuity."
+    )
+
+    # DECOMPOSITION PHASE
+    if step == 1:
+        return {
+            "phase": phase,
+            "step_title": "Extract Structure",
+            "actions": [
+                "You are a structured decision critic. Your task is to decompose this "
+                "decision into its constituent parts so each can be independently verified "
+                "or challenged. This analysis is critical to the quality of the entire workflow.",
+                "",
+                "Extract and assign stable IDs that will persist through ALL subsequent steps:",
+                "",
+                "CLAIMS [C1, C2, ...] - Factual assertions (3-7 items)",
+                "  What facts does this decision assume to be true?",
+                "  What cause-effect relationships does it depend on?",
+                "",
+                "ASSUMPTIONS [A1, A2, ...] - Unstated beliefs (2-5 items)",
+                "  What is implied but not explicitly stated?",
+                "  What would someone unfamiliar with the context not know?",
+                "",
+                "CONSTRAINTS [K1, K2, ...] - Hard boundaries (1-4 items)",
+                "  What technical limitations exist?",
+                "  What organizational/timeline constraints apply?",
+                "",
+                "JUDGMENTS [J1, J2, ...] - Subjective tradeoffs (1-3 items)",
+                "  Where are values being weighed against each other?",
+                "  What 'it depends' decisions were made?",
+                "",
+                "OUTPUT FORMAT:",
+                "  C1: <claim text>",
+                "  C2: <claim text>",
+                "  A1: <assumption text>",
+                "  K1: <constraint text>",
+                "  J1: <judgment text>",
+                "",
+                "These IDs will be referenced in ALL subsequent steps. Be thorough but focused.",
+            ],
+            "next": f"Step {next_step}: Classify each item's verifiability.",
+            "academic_note": None,
+        }
+
+    if step == 2:
+        return {
+            "phase": phase,
+            "step_title": "Classify Verifiability",
+            "actions": [
+                "You are a structured decision critic continuing your analysis.",
+                "",
+                "Classify each item from Step 1. Retain original IDs and add a verifiability tag.",
+                "",
+                "CLASSIFICATIONS:",
+                "",
+                "  [V] VERIFIABLE - Can be checked against evidence or tested",
+                "      Examples: \"API supports 1000 RPS\" (testable), \"Library X has feature Y\" (checkable)",
+                "",
+                "  [J] JUDGMENT - Subjective tradeoff with no objectively correct answer",
+                "      Examples: \"Simplicity is more important than flexibility\", \"Risk is acceptable\"",
+                "",
+                "  [C] CONSTRAINT - Given condition, accepted as fixed for this decision",
+                "      Examples: \"Budget is $50K\", \"Must launch by Q2\", \"Team has 3 engineers\"",
+                "",
+                "EDGE CASE RULE: When an item could fit multiple categories, prefer [V] over [J] over [C].",
+                "Rationale: Verifiable items can be checked; judgments can be debated; constraints are given.",
+                "",
+                "Example edge case:",
+                "  \"The team can deliver in 4 weeks\" - Could be [J] (judgment about capacity) or [V] (checkable",
+                "  against past velocity). Choose [V] because it CAN be verified against evidence.",
+                "",
+                "OUTPUT FORMAT (preserve original IDs):",
+                "  C1 [V]: <claim text>",
+                "  C2 [J]: <claim text>",
+                "  A1 [V]: <assumption text>",
+                "  K1 [C]: <constraint text>",
+                "",
+                "COUNT: State how many [V] items require verification in the next phase.",
+                "",
+                state_requirement,
+            ],
+            "next": f"Step {next_step}: Generate verification questions for [V] items.",
+            "academic_note": None,
+        }
+
+    # VERIFICATION PHASE
+    if step == 3:
+        return {
+            "phase": phase,
+            "step_title": "Generate Verification Questions",
+            "actions": [
+                "You are a structured decision critic. This step is crucial for catching errors.",
+                "",
+                "For each [V] item from Step 2, generate 1-3 verification questions.",
+                "",
+                "CRITERIA FOR GOOD QUESTIONS:",
+                "  - Specific and independently answerable",
+                "  - Designed to reveal if the claim is FALSE (falsification focus)",
+                "  - Do not assume the claim is true in the question itself",
+                "  - Each question should test a different aspect of the claim",
+                "",
+                "QUESTION BOUNDS:",
+                "  - Simple claims: 1 question",
+                "  - Moderate claims: 2 questions",
+                "  - Complex claims with multiple parts: 3 questions maximum",
+                "",
+                "OUTPUT FORMAT:",
+                "  C1 [V]: <claim text>",
+                "    Q1: <verification question>",
+                "    Q2: <verification question>",
+                "  A1 [V]: <assumption text>",
+                "    Q1: <verification question>",
+                "",
+                "EXAMPLE:",
+                "  C1 [V]: Retrying failed requests creates race condition risk",
+                "    Q1: Can a retry succeed after another request has already written?",
+                "    Q2: What ordering guarantees exist between concurrent requests?",
+                "",
+                state_requirement,
+            ],
+            "next": f"Step {next_step}: Answer questions with factored verification.",
+            "academic_note": (
+                "Chain-of-Verification (Dhuliawala et al., 2023): \"Plan verification questions "
+                "to check its work, and then systematically answer those questions.\""
+            ),
+        }
+
+    if step == 4:
+        return {
+            "phase": phase,
+            "step_title": "Factored Verification",
+            "actions": [
+                "You are a structured decision critic. This verification step is the most important "
+                "in the entire workflow. Your accuracy here directly determines verdict quality. "
+                "Take your time and be rigorous.",
+                "",
+                "Answer each verification question INDEPENDENTLY.",
+                "",
+                "EPISTEMIC BOUNDARY (critical for avoiding confirmation bias):",
+                "",
+                "  Answer using ONLY:",
+                "    (a) Established domain knowledge - facts you would find in documentation,",
+                "        textbooks, or widely-accepted technical references",
+                "    (b) Stated constraints - information explicitly provided in the decision context",
+                "    (c) Logical inference - deductions from first principles that would hold",
+                "        regardless of whether this specific decision is correct",
+                "",
+                "  Do NOT:",
+                "    - Assume the decision is correct and work backward",
+                "    - Assume the decision is incorrect and seek to disprove",
+                "    - Reference whether the claim 'should' be true given the decision",
+                "",
+                "SEPARATE your answer from its implication:",
+                "  - ANSWER: The factual response to the question (evidence-based)",
+                "  - IMPLICATION: What this means for the original claim (judgment)",
+                "",
+                "Then mark each [V] item:",
+                "  VERIFIED - Answers are consistent with the claim",
+                "  FAILED - Answers reveal inconsistency, error, or contradiction",
+                "  UNCERTAIN - Insufficient evidence; state what additional information would resolve",
+                "",
+                "OUTPUT FORMAT:",
+                "  C1 [V]: <claim text>",
+                "    Q1: <question>",
+                "      Answer: <factual answer based on epistemic boundary>",
+                "      Implication: <what this means for the claim>",
+                "    Status: VERIFIED | FAILED | UNCERTAIN",
+                "    Rationale: <one sentence explaining the status>",
+                "",
+                state_requirement,
+            ],
+            "next": f"Step {next_step}: Begin challenge phase with adversarial analysis.",
+            "academic_note": (
+                "Chain-of-Verification: \"Factored variants which separate out verification steps, "
+                "in terms of which context is attended to, give further performance gains.\""
+            ),
+        }
+
+    # CHALLENGE PHASE
+    if step == 5:
+        return {
+            "phase": phase,
+            "step_title": "Contrarian Perspective",
+            "actions": [
+                "You are a structured decision critic shifting to adversarial analysis.",
+                "",
+                "Your task: Generate the STRONGEST possible argument AGAINST the decision.",
+                "",
+                "START FROM VERIFICATION RESULTS:",
+                "  - FAILED items are direct ammunition - the decision rests on false premises",
+                "  - UNCERTAIN items are attack vectors - unverified assumptions create risk",
+                "  - Even VERIFIED items may have hidden dependencies worth probing",
+                "",
+                "STEEL-MANNING: Present the opposition's BEST case, not a strawman.",
+                "Ask: What would a thoughtful, well-informed critic with domain expertise say?",
+                "Make the argument as strong as you can, even if you personally disagree.",
+                "",
+                "ATTACK VECTORS TO EXPLORE:",
+                "  - What could go wrong that wasn't considered?",
+                "  - What alternatives were dismissed too quickly?",
+                "  - What second-order effects were missed?",
+                "  - What happens if key assumptions change?",
+                "  - Who would disagree, and why might they be right?",
+                "",
+                "OUTPUT FORMAT:",
+                "",
+                "CONTRARIAN POSITION: <one-sentence summary of the opposition's stance>",
+                "",
+                "ARGUMENT:",
+                "<Present the strongest 2-3 paragraph case against the decision.",
+                " Reference specific item IDs (C1, A2, etc.) where applicable.",
+                " Build from verification failures if any exist.>",
+                "",
+                "KEY RISKS:",
+                "- <Risk 1 with item ID reference if applicable>",
+                "- <Risk 2>",
+                "- <Risk 3>",
+                "",
+                state_requirement,
+            ],
+            "next": f"Step {next_step}: Explore alternative problem framing.",
+            "academic_note": (
+                "Multi-Expert Prompting (Wang et al., 2024): \"Integrating multiple experts' "
+                "perspectives catches blind spots in reasoning.\""
+            ),
+        }
+
+    if step == 6:
+        return {
+            "phase": phase,
+            "step_title": "Alternative Framing",
+            "actions": [
+                "You are a structured decision critic examining problem formulation.",
+                "",
+                "PURPOSE: Step 5 challenged the SOLUTION. This step challenges the PROBLEM STATEMENT.",
+                "Goal: Reveal hidden assumptions baked into how the problem was originally framed.",
+                "",
+                "Set aside the proposed solution temporarily. Ask:",
+                "  'If I approached this problem fresh, how might I state it differently?'",
+                "",
+                "REFRAMING VECTORS:",
+                "  - Is this the right problem to solve, or a symptom of a deeper issue?",
+                "  - What would a different stakeholder (user, ops, security) prioritize?",
+                "  - What if the constraints (K items) were different or negotiable?",
+                "  - Is there a simpler formulation that dissolves the tradeoffs?",
+                "  - What objectives might be missing from the original framing?",
+                "",
+                "OUTPUT FORMAT:",
+                "",
+                "ALTERNATIVE FRAMING: <one-sentence restatement of the problem>",
+                "",
+                "WHAT THIS FRAMING EMPHASIZES:",
+                "<Describe what becomes important under this new framing that wasn't",
+                " prominent in the original.>",
+                "",
+                "HIDDEN ASSUMPTIONS REVEALED:",
+                "<What did the original problem statement take for granted?",
+                " Reference specific items (C, A, K, J) where the assumption appears.>",
+                "",
+                "IMPLICATION FOR DECISION:",
+                "<Does this reframing strengthen, weaken, or redirect the proposed decision?>",
+                "",
+                state_requirement,
+            ],
+            "next": f"Step {next_step}: Synthesize findings into verdict.",
+            "academic_note": None,
+        }
+
+    # SYNTHESIS PHASE
+    if step == 7:
+        return {
+            "phase": phase,
+            "step_title": "Synthesis and Verdict",
+            "actions": [
+                "You are a structured decision critic delivering your final assessment.",
+                "This verdict will guide real decisions. Be confident in your analysis and precise "
+                "in your recommendation.",
+                "",
+                "VERDICT RUBRIC:",
+                "",
+                "  ESCALATE when ANY of these apply:",
+                "    - Any FAILED item involves safety, security, or compliance",
+                "    - Any UNCERTAIN item is critical AND cannot be cheaply verified",
+                "    - The alternative framing reveals the problem itself is wrong",
+                "",
+                "  REVISE when ANY of these apply:",
+                "    - Any FAILED item on a core claim (not peripheral)",
+                "    - Multiple UNCERTAIN items on feasibility, effort, or impact",
+                "    - Challenge phase revealed unaddressed gaps that change the calculus",
+                "",
+                "  STAND when ALL of these apply:",
+                "    - No FAILED items on core claims",
+                "    - UNCERTAIN items are explicitly acknowledged as accepted risks",
+                "    - Challenges from Steps 5-6 are addressable within the current approach",
+                "",
+                "BORDERLINE CASES:",
+                "  - When between STAND and REVISE: favor REVISE (cheaper to refine than to fail)",
+                "  - When between REVISE and ESCALATE: state both options with conditions",
+                "",
+                "OUTPUT FORMAT:",
+                "",
+                "VERDICT: [STAND | REVISE | ESCALATE]",
+                "",
+                "VERIFICATION SUMMARY:",
+                "  Verified: <list IDs>",
+                "  Failed: <list IDs with one-line explanation each>",
+                "  Uncertain: <list IDs with what would resolve each>",
+                "",
+                "CHALLENGE ASSESSMENT:",
+                "  Strongest challenge: <one-sentence summary from Step 5>",
+                "  Alternative framing insight: <one-sentence summary from Step 6>",
+                "  Response: <how the decision addresses or fails to address these>",
+                "",
+                "RECOMMENDATION:",
+                "  <Specific next action. If ESCALATE, specify to whom/what forum.",
+                "   If REVISE, specify which items need rework. If STAND, note accepted risks.>",
+            ],
+            "next": None,
+            "academic_note": (
+                "Self-Consistency (Wang et al., 2023): \"Correct reasoning processes tend to "
+                "have greater agreement in their final answer than incorrect processes.\""
+            ),
+        }
+
+    return {
+        "phase": "UNKNOWN",
+        "step_title": "Unknown Step",
+        "actions": ["Invalid step number."],
+        "next": None,
+        "academic_note": None,
+    }
+
+
+def format_output(step: int, total_steps: int, guidance: dict) -> str:
+    """Format the output for display."""
+    lines = []
+
+    # Header
+    lines.append(f"DECISION CRITIC - Step {step}/{total_steps}: {guidance['step_title']}")
+    lines.append(f"Phase: {guidance['phase']}")
+    lines.append("")
+
+    # Actions
+    for action in guidance["actions"]:
+        lines.append(action)
+    lines.append("")
+
+    # Academic note if present
+    if guidance.get("academic_note"):
+        lines.append(f"[{guidance['academic_note']}]")
+        lines.append("")
+
+    # Next step or completion
+    if guidance["next"]:
+        lines.append(f"NEXT: {guidance['next']}")
+    else:
+        lines.append("WORKFLOW COMPLETE - Present verdict to user.")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Decision Critic - Structured decision criticism workflow"
+    )
+    parser.add_argument(
+        "--step-number",
+        type=int,
+        required=True,
+        help="Current step number (1-7)",
+    )
+    parser.add_argument(
+        "--total-steps",
+        type=int,
+        required=True,
+        help="Total steps in workflow (always 7)",
+    )
+    parser.add_argument(
+        "--decision",
+        type=str,
+        help="The decision being criticized (required for step 1)",
+    )
+    parser.add_argument(
+        "--context",
+        type=str,
+        help="Relevant constraints and background (required for step 1)",
+    )
+    parser.add_argument(
+        "--thoughts",
+        type=str,
+        required=True,
+        help="Your analysis, findings, and progress from previous steps",
+    )
+
+    args = parser.parse_args()
+
+    # Validate step number
+    if args.step_number < 1 or args.step_number > 7:
+        print("ERROR: step-number must be between 1 and 7", file=sys.stderr)
+        sys.exit(1)
+
+    # Validate step 1 requirements
+    if args.step_number == 1:
+        if not args.decision:
+            print("ERROR: --decision is required for step 1", file=sys.stderr)
+            sys.exit(1)
+
+    # Get guidance for current step
+    guidance = get_step_guidance(
+        args.step_number,
+        args.total_steps,
+        args.decision,
+        args.context,
+    )
+
+    # Print decision context on step 1
+    if args.step_number == 1:
+        print("DECISION UNDER REVIEW:")
+        print(args.decision)
+        if args.context:
+            print("")
+            print("CONTEXT:")
+            print(args.context)
+        print("")
+
+    # Print formatted output
+    print(format_output(args.step_number, args.total_steps, guidance))
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/doc-sync/CLAUDE.md

@@ -0,0 +1,14 @@
+# skills/doc-sync/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Skill overview and usage examples | Understanding when to use doc-sync |
+| `SKILL.md` | Complete skill workflow definition | Executing the doc-sync skill |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `references/` | Trigger pattern examples | Writing good CLAUDE.md triggers |

.claude/skills/doc-sync/README.md

@@ -0,0 +1,46 @@
+# Doc Sync
+
+The CLAUDE.md/README.md hierarchy is central to context hygiene. CLAUDE.md files
+are pure indexes -- tabular navigation with "What" and "When to read" columns
+that help LLMs (and humans) find relevant files without loading everything.
+README.md files capture invisible knowledge: architecture decisions, design
+tradeoffs, and invariants that are not apparent from reading code.
+
+The doc-sync skill audits and synchronizes this hierarchy across a repository.
+
+## How It Works
+
+The skill operates in five phases:
+
+1. **Discovery** -- Maps all directories, identifies missing or outdated
+   CLAUDE.md files
+2. **Audit** -- Checks for drift (files added/removed but not indexed),
+   misplaced content (architecture docs in CLAUDE.md instead of README.md)
+3. **Migration** -- Moves architectural content from CLAUDE.md to README.md
+4. **Update** -- Creates/updates indexes with proper tabular format
+5. **Verification** -- Confirms complete coverage and correct structure
+
+## When to Use
+
+Use this skill for:
+
+- **Bootstrapping** -- Adopting this workflow on an existing repository
+- **After bulk changes** -- Major refactors, directory restructuring
+- **Periodic audits** -- Checking for documentation drift
+- **Onboarding** -- Before starting work on an unfamiliar codebase
+
+If you use the planning workflow consistently, the technical writer agent
+maintains documentation as part of execution. As such, doc-sync is primarily for
+bootstrapping or recovery -- not routine use.
+
+## Example Usage
+
+```
+Use your doc-sync skill to synchronize documentation across this repository
+```
+
+For targeted updates:
+
+```
+Use your doc-sync skill to update documentation in src/validators/
+```

.claude/skills/doc-sync/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: doc-sync
+description: Synchronizes CLAUDE.md navigation indexes and README.md architecture docs across a repository. Use when asked to "sync docs", "update CLAUDE.md files", "ensure documentation is in sync", "audit documentation", or when documentation maintenance is needed after code changes.
+---
+
+# Doc Sync
+
+Maintains the CLAUDE.md navigation hierarchy and optional README.md architecture docs across a repository. This skill is self-contained and performs all documentation work directly.
+
+## Scope Resolution
+
+Determine scope FIRST:
+
+| User Request                                            | Scope                                     |
+| ------------------------------------------------------- | ----------------------------------------- |
+| "sync docs" / "update documentation" / no specific path | REPOSITORY-WIDE                           |
+| "sync docs in src/validator/"                           | DIRECTORY: src/validator/ and descendants |
+| "update CLAUDE.md for parser.py"                        | FILE: single file's parent directory      |
+
+For REPOSITORY-WIDE scope, perform a full audit. For narrower scopes, operate only within the specified boundary.
+
+## CLAUDE.md Format Specification
+
+### Index Format
+
+Use tabular format with What and When columns:
+
+```markdown
+## Files
+
+| File        | What                           | When to read                              |
+| ----------- | ------------------------------ | ----------------------------------------- |
+| `cache.rs`  | LRU cache with O(1) operations | Implementing caching, debugging evictions |
+| `errors.rs` | Error types and Result aliases | Adding error variants, handling failures  |
+
+## Subdirectories
+
+| Directory   | What                          | When to read                              |
+| ----------- | ----------------------------- | ----------------------------------------- |
+| `config/`   | Runtime configuration loading | Adding config options, modifying defaults |
+| `handlers/` | HTTP request handlers         | Adding endpoints, modifying request flow  |
+```
+
+### Column Guidelines
+
+- **File/Directory**: Use backticks around names: `cache.rs`, `config/`
+- **What**: Factual description of contents (nouns, not actions)
+- **When to read**: Task-oriented triggers using action verbs (implementing, debugging, modifying, adding, understanding)
+- At least one column must have content; empty cells use `-`
+
+### Trigger Quality Test
+
+Given task "add a new validation rule", can an LLM scan the "When to read" column and identify the right file?
+
+### ROOT vs SUBDIRECTORY CLAUDE.md
+
+**ROOT CLAUDE.md:**
+
+```markdown
+# [Project Name]
+
+[One sentence: what this is]
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+
+## Build
+
+[Copy-pasteable command]
+
+## Test
+
+[Copy-pasteable command]
+
+## Development
+
+[Setup instructions, environment requirements, workflow notes]
+```
+
+**SUBDIRECTORY CLAUDE.md:**
+
+```markdown
+# [directory-name]/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+```
+
+**Critical constraint:** Subdirectory CLAUDE.md files are PURE INDEX. No prose, no overview sections, no architectural explanations. Those belong in README.md.
+
+## README.md Specification
+
+### Creation Criteria (Invisible Knowledge Test)
+
+Create README.md ONLY when the directory contains knowledge NOT visible from reading the code:
+
+- Multiple components interact through non-obvious contracts or protocols
+- Design tradeoffs were made that affect how code should be modified
+- The directory's structure encodes domain knowledge (e.g., processing order matters)
+- Failure modes or edge cases aren't apparent from reading individual files
+- There are "rules" developers must follow that aren't enforced by the compiler/linter
+
+**DO NOT create README.md when:**
+
+- The directory is purely organizational (just groups related files)
+- Code is self-explanatory with good function/module docs
+- You'd be restating what CLAUDE.md index entries already convey
+
+### Content Test
+
+For each sentence in README.md, ask: "Could a developer learn this by reading the source files?"
+
+- If YES: delete the sentence
+- If NO: keep it
+
+README.md earns its tokens by providing INVISIBLE knowledge: the reasoning behind the code, not descriptions of the code.
+
+### README.md Structure
+
+```markdown
+# [Component Name]
+
+## Overview
+
+[One paragraph: what problem this solves, high-level approach]
+
+## Architecture
+
+[How sub-components interact; data flow; key abstractions]
+
+## Design Decisions
+
+[Tradeoffs made and why; alternatives considered]
+
+## Invariants
+
+[Rules that must be maintained; constraints not enforced by code]
+```
+
+## Workflow
+
+### Phase 1: Discovery
+
+Map directories requiring CLAUDE.md verification:
+
+```bash
+# Find all directories (excluding .git, node_modules, __pycache__, etc.)
+find . -type d \( -name .git -o -name node_modules -o -name __pycache__ -o -name .venv -o -name target -o -name dist -o -name build \) -prune -o -type d -print
+```
+
+For each directory in scope, record:
+
+1. Does CLAUDE.md exist?
+2. If yes, does it have the required table-based index structure?
+3. What files/subdirectories exist that need indexing?
+
+### Phase 2: Audit
+
+For each directory, check for drift and misplaced content:
+
+```
+<audit_check dir="[path]">
+CLAUDE.md exists: [YES/NO]
+Has table-based index: [YES/NO]
+Files in directory: [list]
+Files in index: [list]
+Missing from index: [list]
+Stale in index (file deleted): [list]
+Triggers are task-oriented: [YES/NO/PARTIAL]
+Contains misplaced content: [YES/NO] (architecture/design docs that belong in README.md)
+README.md exists: [YES/NO]
+README.md warranted: [YES/NO] (invisible knowledge present?)
+</audit_check>
+```
+
+### Phase 3: Content Migration
+
+**Critical:** If CLAUDE.md contains content that does NOT belong there, migrate it:
+
+Content that MUST be moved from CLAUDE.md to README.md:
+
+- Architecture explanations or diagrams
+- Design decision documentation
+- Component interaction descriptions
+- Overview sections with prose (in subdirectory CLAUDE.md files)
+- Invariants or rules documentation
+- Any "why" explanations beyond simple triggers
+
+Migration process:
+
+1. Identify misplaced content in CLAUDE.md
+2. Create or update README.md with the architectural content
+3. Strip CLAUDE.md down to pure index format
+4. Add README.md to the CLAUDE.md index table
+
+### Phase 4: Index Updates
+
+For each directory needing work:
+
+**Creating/Updating CLAUDE.md:**
+
+1. Use the appropriate template (ROOT or SUBDIRECTORY)
+2. Populate tables with all files and subdirectories
+3. Write "What" column: factual content description
+4. Write "When to read" column: action-oriented triggers
+5. If README.md exists, include it in the Files table
+
+**Creating README.md (only when warranted):**
+
+1. Verify invisible knowledge criteria are met
+2. Document architecture, design decisions, invariants
+3. Apply the content test: remove anything visible from code
+4. Keep under ~500 tokens
+
+### Phase 5: Verification
+
+After all updates complete, verify:
+
+1. Every directory in scope has CLAUDE.md
+2. All CLAUDE.md files use table-based index format
+3. No drift remains (files <-> index entries match)
+4. No misplaced content in CLAUDE.md (architecture docs moved to README.md)
+5. README.md files are indexed in their parent CLAUDE.md
+6. Subdirectory CLAUDE.md files contain no prose/overview sections
+
+## Output Format
+
+```
+## Doc Sync Report
+
+### Scope: [REPOSITORY-WIDE | directory path]
+
+### Changes Made
+- CREATED: [list of new CLAUDE.md files]
+- UPDATED: [list of modified CLAUDE.md files]
+- MIGRATED: [list of content moved from CLAUDE.md to README.md]
+- CREATED: [list of new README.md files]
+- FLAGGED: [any issues requiring human decision]
+
+### Verification
+- Directories audited: [count]
+- CLAUDE.md coverage: [count]/[total] (100%)
+- Drift detected: [count] entries fixed
+- Content migrations: [count] (architecture docs moved to README.md)
+- README.md files: [count] (only where warranted)
+```
+
+## Exclusions
+
+DO NOT index:
+
+- Generated files (dist/, build/, _.generated._, compiled outputs)
+- Vendored dependencies (node_modules/, vendor/, third_party/)
+- Git internals (.git/)
+- IDE/editor configs (.idea/, .vscode/ unless project-specific settings)
+
+DO index:
+
+- Hidden config files that affect development (.eslintrc, .env.example, .gitignore)
+- Test files and test directories
+- Documentation files (including README.md)
+
+## Anti-Patterns
+
+### Index Anti-Patterns
+
+**Too vague (matches everything):**
+
+```markdown
+| `config/` | Configuration | Working with configuration |
+```
+
+**Content description instead of trigger:**
+
+```markdown
+| `cache.rs` | Contains the LRU cache implementation | - |
+```
+
+**Missing action verb:**
+
+```markdown
+| `parser.py` | Input parsing | Input parsing and format handling |
+```
+
+### Correct Examples
+
+```markdown
+| `cache.rs` | LRU cache with O(1) get/set | Implementing caching, debugging misses, tuning eviction |
+| `config/` | YAML config parsing, env overrides | Adding config options, changing defaults, debugging config loading |
+```
+
+## When NOT to Use This Skill
+
+- Single file documentation (inline comments, docstrings) - handle directly
+- Code comments - handle directly
+- Function/module docstrings - handle directly
+- This skill is for CLAUDE.md/README.md synchronization specifically
+
+## Reference
+
+For additional trigger pattern examples, see `references/trigger-patterns.md`.

.claude/skills/doc-sync/references/trigger-patterns.md

@@ -0,0 +1,125 @@
+# Trigger Patterns Reference
+
+Examples of well-formed triggers for CLAUDE.md index table entries.
+
+## Column Formula
+
+| File         | What                             | When to read                          |
+| ------------ | -------------------------------- | ------------------------------------- |
+| `[filename]` | [noun-based content description] | [action verb] [specific context/task] |
+
+## Action Verbs by Category
+
+### Implementation Tasks
+
+implementing, adding, creating, building, writing, extending
+
+### Modification Tasks
+
+modifying, updating, changing, refactoring, migrating
+
+### Debugging Tasks
+
+debugging, troubleshooting, investigating, diagnosing, fixing
+
+### Understanding Tasks
+
+understanding, learning, reviewing, analyzing, exploring
+
+## Examples by File Type
+
+### Source Code Files
+
+| File           | What                                | When to read                                                                       |
+| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
+| `cache.rs`     | LRU cache with O(1) operations      | Implementing caching, debugging cache misses, modifying eviction policy            |
+| `auth.rs`      | JWT validation, session management  | Implementing login/logout, modifying token validation, debugging auth failures     |
+| `parser.py`    | Input parsing, format detection     | Modifying input parsing, adding new input formats, debugging parse errors          |
+| `validator.py` | Validation rules, constraint checks | Adding validation rules, modifying validation logic, understanding validation flow |
+
+### Configuration Files
+
+| File           | What                             | When to read                                                                  |
+| -------------- | -------------------------------- | ----------------------------------------------------------------------------- |
+| `config.toml`  | Runtime config options, defaults | Adding new config options, modifying defaults, debugging configuration issues |
+| `.env.example` | Environment variable template    | Setting up development environment, adding new environment variables          |
+| `Cargo.toml`   | Rust dependencies, build config  | Adding dependencies, modifying build configuration, debugging build issues    |
+
+### Test Files
+
+| File                 | What                        | When to read                                                                     |
+| -------------------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `test_cache.py`      | Cache unit tests            | Adding cache tests, debugging test failures, understanding cache behavior        |
+| `integration_tests/` | Cross-component test suites | Adding integration tests, debugging cross-component issues, validating workflows |
+
+### Documentation Files
+
+| File              | What                                     | When to read                                                                             |
+| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `README.md`       | Architecture, design decisions           | Understanding architecture, design decisions, component relationships                    |
+| `ARCHITECTURE.md` | System design, component boundaries      | Understanding system design, component boundaries, data flow                             |
+| `API.md`          | Endpoint specs, request/response formats | Implementing API endpoints, understanding request/response formats, debugging API issues |
+
+### Index Files (cross-cutting concerns)
+
+| File                      | What                               | When to read                                                                    |
+| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
+| `error-handling-index.md` | Error handling patterns reference  | Understanding error handling patterns, failure modes, error recovery strategies |
+| `performance-index.md`    | Performance optimization reference | Optimizing latency, throughput, resource usage, understanding cost models       |
+| `security-index.md`       | Security patterns reference        | Implementing authentication, encryption, threat mitigation, compliance features |
+
+## Examples by Directory Type
+
+### Feature Directories
+
+| Directory  | What                                    | When to read                                                                          |
+| ---------- | --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `auth/`    | Authentication, authorization, sessions | Implementing authentication, authorization, session management, debugging auth issues |
+| `api/`     | HTTP endpoints, request handling        | Implementing endpoints, modifying request handling, debugging API responses           |
+| `storage/` | Persistence, data access layer          | Implementing persistence, modifying data access, debugging storage issues             |
+
+### Layer Directories
+
+| Directory   | What                          | When to read                                                                     |
+| ----------- | ----------------------------- | -------------------------------------------------------------------------------- |
+| `handlers/` | Request handlers, routing     | Implementing request handlers, modifying routing, debugging request processing   |
+| `models/`   | Data models, schemas          | Adding data models, modifying schemas, understanding data structures             |
+| `services/` | Business logic, service layer | Implementing business logic, modifying service interactions, debugging workflows |
+
+### Utility Directories
+
+| Directory  | What                              | When to read                                                                       |
+| ---------- | --------------------------------- | ---------------------------------------------------------------------------------- |
+| `utils/`   | Helper functions, common patterns | Needing helper functions, implementing common patterns, debugging utility behavior |
+| `scripts/` | Maintenance tasks, automation     | Running maintenance tasks, automating workflows, debugging script execution        |
+| `tools/`   | Development tools, CLI utilities  | Using development tools, implementing tooling, debugging tool behavior             |
+
+## Anti-Patterns
+
+### Too Vague (matches everything)
+
+| File       | What          | When to read               |
+| ---------- | ------------- | -------------------------- |
+| `config/`  | Configuration | Working with configuration |
+| `utils.py` | Utilities     | When you need utilities    |
+
+### Content Description Only (no trigger)
+
+| File       | What                                          | When to read |
+| ---------- | --------------------------------------------- | ------------ |
+| `cache.rs` | Contains the LRU cache implementation         | -            |
+| `auth.rs`  | Authentication logic including JWT validation | -            |
+
+### Missing Action Verb
+
+| File           | What             | When to read                      |
+| -------------- | ---------------- | --------------------------------- |
+| `parser.py`    | Input parsing    | Input parsing and format handling |
+| `validator.py` | Validation rules | Validation rules and constraints  |
+
+## Trigger Guidelines
+
+- Combine 2-4 triggers per entry using commas or "or"
+- Use action verbs: implementing, debugging, modifying, adding, understanding
+- Be specific: "debugging cache misses" not "debugging"
+- If more than 4 triggers needed, the file may be doing too much

.claude/skills/incoherence/CLAUDE.md

@@ -0,0 +1,24 @@
+# skills/incoherence/
+
+## Overview
+
+Incoherence detection skill using parallel agents. IMMEDIATELY invoke the
+script -- do NOT explore first.
+
+## Index
+
+| File/Directory           | Contents          | Read When          |
+| ------------------------ | ----------------- | ------------------ |
+| `SKILL.md`               | Invocation        | Using this skill   |
+| `scripts/incoherence.py` | Complete workflow | Debugging behavior |
+
+## Key Point
+
+The script IS the workflow. Three phases:
+
+- Detection (steps 1-12): Survey, explore, verify candidates
+- Resolution (steps 13-15): Interactive AskUserQuestion prompts
+- Application (steps 16-21): Apply changes, present final report
+
+Resolution is interactive - user answers structured questions inline. No manual
+file editing required.

.claude/skills/incoherence/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: incoherence
+description: Detect and resolve incoherence in documentation, code, specs vs implementation.
+---
+
+# Incoherence Detector
+
+When this skill activates, IMMEDIATELY invoke the script. The script IS the
+workflow.
+
+## Invocation
+
+```bash
+python3 scripts/incoherence.py \
+  --step-number 1 \
+  --total-steps 21 \
+  --thoughts "<context>"
+```
+
+| Argument        | Required | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `--step-number` | Yes      | Current step (1-21)                       |
+| `--total-steps` | Yes      | Always 21                                 |
+| `--thoughts`    | Yes      | Accumulated state from all previous steps |
+
+Do NOT explore or detect first. Run the script and follow its output.
+
+## Workflow Phases
+
+1. **Detection (steps 1-12)**: Survey codebase, explore dimensions, verify
+   candidates
+2. **Resolution (steps 13-15)**: Present issues via AskUserQuestion, collect
+   user decisions
+3. **Application (steps 16-21)**: Apply resolutions, present final report
+
+Resolution is interactive - user answers structured questions inline. No manual
+file editing required.

.claude/skills/planner/CLAUDE.md

@@ -0,0 +1,86 @@
+# skills/planner/
+
+## Overview
+
+Planning skill with resources that must stay synced with agent prompts.
+
+## Index
+
+| File/Directory                        | Contents                                       | Read When                                    |
+| ------------------------------------- | ---------------------------------------------- | -------------------------------------------- |
+| `SKILL.md`                            | Planning workflow, phases                      | Using the planner skill                      |
+| `scripts/planner.py`                  | Step-by-step planning orchestration            | Debugging planner behavior                   |
+| `resources/plan-format.md`            | Plan template (injected by script)             | Editing plan structure                       |
+| `resources/temporal-contamination.md` | Detection heuristic for contaminated comments  | Updating TW/QR temporal contamination logic  |
+| `resources/diff-format.md`            | Unified diff spec for code changes             | Updating Developer diff consumption logic    |
+| `resources/default-conventions.md`    | Default structural conventions (4-tier system) | Updating QR RULE 2 or planner decision audit |
+
+## Resource Sync Requirements
+
+Resources are **authoritative sources**.
+
+- **SKILL.md** references resources directly (main Claude can read files)
+- **Agent prompts** embed resources 1:1 (sub-agents cannot access files
+  reliably)
+
+### plan-format.md
+
+Plan template injected by `scripts/planner.py` at planning phase completion.
+
+**No agent sync required** - the script reads and outputs the format directly,
+so editing this file takes effect immediately without updating any agent
+prompts.
+
+### temporal-contamination.md
+
+Authoritative source for temporal contamination detection. Full content embedded
+1:1.
+
+| Synced To                    | Embedded Section           |
+| ---------------------------- | -------------------------- |
+| `agents/technical-writer.md` | `<temporal_contamination>` |
+| `agents/quality-reviewer.md` | `<temporal_contamination>` |
+
+**When updating**: Modify `resources/temporal-contamination.md` first, then copy
+content into both `<temporal_contamination>` sections.
+
+### diff-format.md
+
+Authoritative source for unified diff format. Full content embedded 1:1.
+
+| Synced To             | Embedded Section |
+| --------------------- | ---------------- |
+| `agents/developer.md` | `<diff_format>`  |
+
+**When updating**: Modify `resources/diff-format.md` first, then copy content
+into `<diff_format>` section.
+
+### default-conventions.md
+
+Authoritative source for default structural conventions (four-tier decision
+backing system). Embedded 1:1 in QR for RULE 2 enforcement; referenced by
+planner.py for decision audit.
+
+| Synced To                    | Embedded Section        |
+| ---------------------------- | ----------------------- |
+| `agents/quality-reviewer.md` | `<default_conventions>` |
+
+**When updating**: Modify `resources/default-conventions.md` first, then copy
+full content verbatim into `<default_conventions>` section in QR.
+
+## Sync Verification
+
+After modifying a resource, verify sync:
+
+```bash
+# Check temporal-contamination.md references
+grep -l "temporal.contamination\|four detection questions\|change-relative\|baseline reference" agents/*.md
+
+# Check diff-format.md references
+grep -l "context lines\|AUTHORITATIVE\|APPROXIMATE\|context anchor" agents/*.md
+
+# Check default-conventions.md references
+grep -l "default_conventions\|domain: god-object\|domain: test-organization" agents/*.md
+```
+
+If grep finds files not listed in sync tables above, update this document.

.claude/skills/planner/README.md

@@ -0,0 +1,80 @@
+# Planner
+
+LLM-generated plans have gaps. I have seen missing error handling, vague
+acceptance criteria, specs that nobody can implement. I built this skill with
+two workflows -- planning and execution -- connected by quality gates that catch
+these problems early.
+
+## Planning Workflow
+
+```
+  Planning ----+
+      |        |
+      v        |
+     QR -------+  [fail: restart planning]
+      |
+      v
+     TW -------+
+      |        |
+      v        |
+   QR-Docs ----+  [fail: restart TW]
+      |
+      v
+   APPROVED
+```
+
+| Step                    | Actions                                                                    |
+| ----------------------- | -------------------------------------------------------------------------- |
+| Context & Scope         | Confirm path, define scope, identify approaches, list constraints          |
+| Decision & Architecture | Evaluate approaches, select with reasoning, diagram, break into milestones |
+| Refinement              | Document risks, add uncertainty flags, specify paths and criteria          |
+| Final Verification      | Verify completeness, check specs, write to file                            |
+| QR-Completeness         | Verify Decision Log complete, policy defaults confirmed, plan structure    |
+| QR-Code                 | Read codebase, verify diff context, apply RULE 0/1/2 to proposed code      |
+| Technical Writer        | Scrub temporal comments, add WHY comments, enrich rationale                |
+| QR-Docs                 | Verify no temporal contamination, comments explain WHY not WHAT            |
+
+So, why all the feedback loops? QR-Completeness and QR-Code run before TW to
+catch structural issues early. QR-Docs runs after TW to validate documentation
+quality. Doc issues restart only TW; structure issues restart planning. The loop
+runs until both pass.
+
+## Execution Workflow
+
+```
+  Plan --> Milestones --> QR --> Docs --> Retrospective
+               ^          |
+               +- [fail] -+
+
+  * Reconciliation phase precedes Milestones when resuming partial work
+```
+
+After planning completes and context clears (`/clear`), execution proceeds:
+
+| Step                   | Purpose                                                         |
+| ---------------------- | --------------------------------------------------------------- |
+| Execution Planning     | Analyze plan, detect reconciliation signals, output strategy    |
+| Reconciliation         | (conditional) Validate existing code against plan               |
+| Milestone Execution    | Delegate to agents, run tests; repeat until all complete        |
+| Post-Implementation QR | Quality review of implemented code                              |
+| Issue Resolution       | (conditional) Present issues, collect decisions, delegate fixes |
+| Documentation          | Technical writer updates CLAUDE.md/README.md                    |
+| Retrospective          | Present execution summary                                       |
+
+I designed the coordinator to never write code directly -- it delegates to
+developers. Separating coordination from implementation produces cleaner
+results. The coordinator:
+
+- Parallelizes independent work across up to 4 developers per milestone
+- Runs quality review after all milestones complete
+- Loops through issue resolution until QR passes
+- Invokes technical writer only after QR passes
+
+**Reconciliation** handles resume scenarios. When the user request contains
+signals like "already implemented", "resume", or "partially complete", the
+workflow validates existing code against plan requirements before executing
+remaining milestones. Building on unverified code means rework.
+
+**Issue Resolution** presents each QR finding individually with options (Fix /
+Skip / Alternative). Fixes delegate to developers or technical writers, then QR
+runs again. This cycle repeats until QR passes.

.claude/skills/planner/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: planner
+description: Interactive planning and execution for complex tasks. Use when user asks to use or invoke planner skill.
+---
+
+# Planner Skill
+
+Two-phase workflow: **planning** (create plans) and **execution** (implement
+plans).
+
+## Invocation Routing
+
+| User Intent                                 | Script      | Invocation                                                                         |
+| ------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
+| "plan", "design", "architect", "break down" | planner.py  | `python3 scripts/planner.py --step-number 1 --total-steps 4 --thoughts "..."`      |
+| "review plan" (after plan written)          | planner.py  | `python3 scripts/planner.py --phase review --step-number 1 --total-steps 2 ...`    |
+| "execute", "implement", "run plan"          | executor.py | `python3 scripts/executor.py --plan-file PATH --step-number 1 --total-steps 7 ...` |
+
+Scripts inject step-specific guidance via JIT prompt injection. Invoke the
+script and follow its REQUIRED ACTIONS output.
+
+## When to Use
+
+Use when task has:
+
+- Multiple milestones with dependencies
+- Architectural decisions requiring documentation
+- Complexity benefiting from forced reflection pauses
+
+Skip when task is:
+
+- Single-step with obvious implementation
+- Quick fix or minor change
+- Already well-specified by user
+
+## Resources
+
+| Resource                              | Contents                                   | Read When                                       |
+| ------------------------------------- | ------------------------------------------ | ----------------------------------------------- |
+| `resources/diff-format.md`            | Unified diff specification for plans       | Writing code changes in milestones              |
+| `resources/temporal-contamination.md` | Comment hygiene detection heuristics       | Writing comments in code snippets               |
+| `resources/default-conventions.md`    | Priority hierarchy, structural conventions | Making decisions without explicit user guidance |
+| `resources/plan-format.md`            | Plan template structure                    | Completing planning phase (injected by script)  |
+
+**Resource loading rule**: Scripts will prompt you to read specific resources at
+decision points. When prompted, read the full resource before proceeding.
+
+## Workflow Summary
+
+**Planning phase**: Steps 1-N explore context, evaluate approaches, refine
+milestones. Final step writes plan to file. Review phase (TW scrub -> QR
+validation) follows.
+
+**Execution phase**: 7 steps -- analyze plan, reconcile existing code, delegate
+milestones to agents, QR validation, issue resolution, documentation,
+retrospective.
+
+All procedural details are injected by the scripts. Invoke the appropriate
+script and follow its output.

.claude/skills/planner/resources/default-conventions.md

@@ -0,0 +1,156 @@
+# Default Conventions
+
+These conventions apply when project documentation does not specify otherwise.
+
+## MotoVaultPro Project Conventions
+
+**Naming**:
+- Database columns: snake_case (`user_id`, `created_at`)
+- TypeScript types: camelCase (`userId`, `createdAt`)
+- API responses: camelCase
+- Files: kebab-case (`vehicle-repository.ts`)
+
+**Architecture**:
+- Feature capsules: `backend/src/features/{feature}/`
+- Repository pattern with mapRow() for case conversion
+- Single-tenant, user-scoped data
+
+**Frontend**:
+- Mobile + desktop validation required (320px, 768px, 1920px)
+- Touch targets >= 44px
+- No hover-only interactions
+
+**Development**:
+- Local node development (`npm install`, `npm run dev`, `npm test`)
+- CI/CD pipeline validates containers and integration tests
+- Plans stored in Gitea Issue comments
+
+---
+
+## Priority Hierarchy
+
+Higher tiers override lower. Cite backing source when auditing.
+
+| Tier | Source          | Action                           |
+| ---- | --------------- | -------------------------------- |
+| 1    | user-specified  | Explicit user instruction: apply |
+| 2    | doc-derived     | CLAUDE.md / project docs: apply  |
+| 3    | default-derived | This document: apply             |
+| 4    | assumption      | No backing: CONFIRM WITH USER    |
+
+## Severity Levels
+
+| Level      | Meaning                          | Action          |
+| ---------- | -------------------------------- | --------------- |
+| SHOULD_FIX | Likely to cause maintenance debt | Flag for fixing |
+| SUGGESTION | Improvement opportunity          | Note if time    |
+
+---
+
+## Structural Conventions
+
+<default-conventions domain="god-object">
+**God Object**: >15 public methods OR >10 dependencies OR mixed concerns (networking + UI + data)
+Severity: SHOULD_FIX
+</default-conventions>
+
+<default-conventions domain="god-function">
+**God Function**: >50 lines OR multiple abstraction levels OR >3 nesting levels
+Severity: SHOULD_FIX
+Exception: Inherently sequential algorithms or state machines
+</default-conventions>
+
+<default-conventions domain="duplicate-logic">
+**Duplicate Logic**: Copy-pasted blocks, repeated error handling, parallel near-identical functions
+Severity: SHOULD_FIX
+</default-conventions>
+
+<default-conventions domain="dead-code">
+**Dead Code**: No callers, impossible branches, unread variables, unused imports
+Severity: SUGGESTION
+</default-conventions>
+
+<default-conventions domain="inconsistent-error-handling">
+**Inconsistent Error Handling**: Mixed exceptions/error codes, inconsistent types, swallowed errors
+Severity: SUGGESTION
+Exception: Project specifies different handling per error category
+</default-conventions>
+
+---
+
+## File Organization Conventions
+
+<default-conventions domain="test-organization">
+**Test Organization**: Extend existing test files; create new only when:
+- Distinct module boundary OR >500 lines OR different fixtures required
+Severity: SHOULD_FIX (for unnecessary fragmentation)
+</default-conventions>
+
+<default-conventions domain="file-creation">
+**File Creation**: Prefer extending existing files; create new only when:
+- Clear module boundary OR >300-500 lines OR distinct responsibility
+Severity: SUGGESTION
+</default-conventions>
+
+---
+
+## Testing Conventions
+
+<default-conventions domain="testing">
+**Principle**: Test behavior, not implementation. Fast feedback.
+
+**Test Type Hierarchy** (preference order):
+
+1. **Integration tests** (highest value)
+   - Test end-user verifiable behavior
+   - Use real systems/dependencies (e.g., testcontainers)
+   - Verify component interaction at boundaries
+   - This is where the real value lies
+
+2. **Property-based / generative tests** (preferred)
+   - Cover wide input space with invariant assertions
+   - Catch edge cases humans miss
+   - Use for functions with clear input/output contracts
+
+3. **Unit tests** (use sparingly)
+   - Only for highly complex or critical logic
+   - Risk: maintenance liability, brittleness to refactoring
+   - Prefer integration tests that cover same behavior
+
+**Test Placement**: Tests are part of implementation milestones, not separate
+milestones. A milestone is not complete until its tests pass. This creates fast
+feedback during development.
+
+**DO**:
+
+- Integration tests with real dependencies (testcontainers, etc.)
+- Property-based tests for invariant-rich functions
+- Parameterized fixtures over duplicate test bodies
+- Test behavior observable by end users
+
+**DON'T**:
+
+- Test external library/dependency behavior (out of scope)
+- Unit test simple code (maintenance liability exceeds value)
+- Mock owned dependencies (use real implementations)
+- Test implementation details that may change
+- One-test-per-variant when parametrization applies
+
+Severity: SHOULD_FIX (violations), SUGGESTION (missed opportunities)
+</default-conventions>
+
+---
+
+## Modernization Conventions
+
+<default-conventions domain="version-constraints">
+**Version Constraint Violation**: Features unavailable in project's documented target version
+Requires: Documented target version
+Severity: SHOULD_FIX
+</default-conventions>
+
+<default-conventions domain="modernization">
+**Modernization Opportunity**: Legacy APIs, verbose patterns, manual stdlib reimplementations
+Severity: SUGGESTION
+Exception: Project requires legacy pattern
+</default-conventions>

.claude/skills/planner/resources/diff-format.md

@@ -0,0 +1,201 @@
+# Unified Diff Format for Plan Code Changes
+
+This document is the authoritative specification for code changes in implementation plans.
+
+## Purpose
+
+Unified diff format encodes both **location** and **content** in a single structure. This eliminates the need for location directives in comments (e.g., "insert at line 42") and provides reliable anchoring even when line numbers drift.
+
+## Anatomy
+
+```diff
+--- a/path/to/file.py
++++ b/path/to/file.py
+@@ -123,6 +123,15 @@ def existing_function(ctx):
+    # Context lines (unchanged) serve as location anchors
+    existing_code()
+
++   # NEW: Comments explain WHY - transcribed verbatim by Developer
++   # Guard against race condition when messages arrive out-of-order
++   new_code()
+
+    # More context to anchor the insertion point
+    more_existing_code()
+```
+
+## Components
+
+| Component                                  | Authority                 | Purpose                                                    |
+| ------------------------------------------ | ------------------------- | ---------------------------------------------------------- |
+| File path (`--- a/path/to/file.py`)        | **AUTHORITATIVE**         | Exact target file                                          |
+| Line numbers (`@@ -123,6 +123,15 @@`)      | **APPROXIMATE**           | May drift as earlier milestones modify the file            |
+| Function context (`@@ ... @@ def func():`) | **SCOPE HINT**            | Function/method containing the change                      |
+| Context lines (unchanged)                  | **AUTHORITATIVE ANCHORS** | Developer matches these patterns to locate insertion point |
+| `+` lines                                  | **NEW CODE**              | Code to add, including WHY comments                        |
+| `-` lines                                  | **REMOVED CODE**          | Code to delete                                             |
+
+## Two-Layer Location Strategy
+
+Code changes use two complementary layers for location:
+
+1. **Prose scope hint** (optional): Natural language describing conceptual location
+2. **Diff with context**: Precise insertion point via context line matching
+
+### Layer 1: Prose Scope Hints
+
+For complex changes, add a prose description before the diff block:
+
+````markdown
+Add validation after input sanitization in `UserService.validate()`:
+
+```diff
+@@ -123,6 +123,15 @@ def validate(self, user):
+     sanitized = sanitize(user.input)
+
++    # Validate format before proceeding
++    if not is_valid_format(sanitized):
++        raise ValidationError("Invalid format")
++
+     return process(sanitized)
+`` `
+```
+````
+
+The prose tells Developer **where conceptually** (which method, what operation precedes it). The diff tells Developer **where exactly** (context lines to match).
+
+**When to use prose hints:**
+
+- Changes to large files (>300 lines)
+- Multiple changes to the same file in one milestone
+- Complex nested structures where function context alone is ambiguous
+- When the surrounding code logic matters for understanding placement
+
+**When prose is optional:**
+
+- Small files with obvious structure
+- Single change with unique context lines
+- Function context in @@ line provides sufficient scope
+
+### Layer 2: Function Context in @@ Line
+
+The `@@` line can include function/method context after the line numbers:
+
+```diff
+@@ -123,6 +123,15 @@ def validate(self, user):
+```
+
+This follows standard unified diff format (git generates this automatically). It tells Developer which function contains the change, aiding navigation even when line numbers drift.
+
+## Why Context Lines Matter
+
+When a plan has multiple milestones that modify the same file, earlier milestones shift line numbers. The `@@ -123` in Milestone 3 may no longer be accurate after Milestones 1 and 2 execute.
+
+**Context lines solve this**: Developer searches for the unchanged context patterns in the actual file. These patterns are stable anchors that survive line number drift.
+
+Include 2-3 context lines before and after changes for reliable matching.
+
+## Comment Placement
+
+Comments in `+` lines explain **WHY**, not **WHAT**. These comments:
+
+- Are transcribed verbatim by Developer
+- Source rationale from Planning Context (Decision Log, Rejected Alternatives)
+- Use concrete terms without hidden baselines
+- Must pass temporal contamination review (see `temporal-contamination.md`)
+
+**Important**: Comments written during planning often contain temporal contamination -- change-relative language, baseline references, or location directives. @agent-technical-writer reviews and fixes these before @agent-developer transcribes them.
+
+<example type="CORRECT" category="why_comment">
+```diff
++   # Polling chosen over webhooks: 30% webhook delivery failures in third-party API
++   # WebSocket rejected to preserve stateless architecture
++   updates = poll_api(interval=30)
+```
+Explains WHY this approach was chosen.
+</example>
+
+<example type="INCORRECT" category="what_comment">
+```diff
++   # Poll the API every 30 seconds
++   updates = poll_api(interval=30)
+```
+Restates WHAT the code does - redundant with the code itself.
+</example>
+
+<example type="INCORRECT" category="hidden_baseline">
+```diff
++   # Generous timeout for slow networks
++   REQUEST_TIMEOUT = 60
+```
+"Generous" compared to what? Hidden baseline provides no actionable information.
+</example>
+
+<example type="CORRECT" category="concrete_justification">
+```diff
++   # 60s accommodates 95th percentile upstream response times
++   REQUEST_TIMEOUT = 60
+```
+Concrete justification that explains why this specific value.
+</example>
+
+## Location Directives: Forbidden
+
+The diff structure handles location. Location directives in comments are redundant and error-prone.
+
+<example type="INCORRECT" category="location_directive">
+```python
+# Insert this BEFORE the retry loop (line 716)
+# Timestamp guard: prevent older data from overwriting newer
+get_ctx, get_cancel = context.with_timeout(ctx, 500)
+```
+Location directive leaked into comment - line numbers become stale.
+</example>
+
+<example type="CORRECT" category="location_directive">
+```diff
+@@ -714,6 +714,10 @@ def put(self, ctx, tags):
+    for tag in tags:
+        subject = tag.subject
+
+-       # Timestamp guard: prevent older data from overwriting newer
+-       # due to network delays, retries, or concurrent writes
+-       get_ctx, get_cancel = context.with_timeout(ctx, 500)
+
+        # Retry loop for Put operations
+        for attempt in range(max_retries):
+
+```
+Context lines (`for tag in tags`, `# Retry loop`) are stable anchors that survive line number drift.
+</example>
+
+## When to Use Diff Format
+
+<diff_format_decision>
+
+| Code Characteristic                     | Use Diff? | Boundary Test                            |
+| --------------------------------------- | --------- | ---------------------------------------- |
+| Conditionals, loops, error handling,    | YES       | Has branching logic                      |
+| state machines                          |           |                                          |
+| Multiple insertions same file           | YES       | >1 change location                       |
+| Deletions or replacements               | YES       | Removing/changing existing code          |
+| Pure assignment/return (CRUD, getters)  | NO        | Single statement, no branching           |
+| Boilerplate from template               | NO        | Developer can generate from pattern name |
+
+The boundary test: "Does Developer need to see exact placement and context to implement correctly?"
+
+- YES -> diff format
+- NO (can implement from description alone) -> prose sufficient
+
+</diff_format_decision>
+
+## Validation Checklist
+
+Before finalizing code changes in a plan:
+
+- [ ] File path is exact (not "auth files" but `src/auth/handler.py`)
+- [ ] Context lines exist in target file (validate patterns match actual code)
+- [ ] Comments explain WHY, not WHAT
+- [ ] No location directives in comments
+- [ ] No hidden baselines (test: "[adjective] compared to what?")
+- [ ] 2-3 context lines for reliable anchoring
+```

.claude/skills/planner/resources/plan-format.md

@@ -0,0 +1,250 @@
+# Plan Format
+
+Write your plan using this structure:
+
+```markdown
+# [Plan Title]
+
+## Overview
+
+[Problem statement, chosen approach, and key decisions in 1-2 paragraphs]
+
+## Planning Context
+
+This section is consumed VERBATIM by downstream agents (Technical Writer,
+Quality Reviewer). Quality matters: vague entries here produce poor annotations
+and missed risks.
+
+### Decision Log
+
+| Decision           | Reasoning Chain                                              |
+| ------------------ | ------------------------------------------------------------ |
+| [What you decided] | [Multi-step reasoning: premise -> implication -> conclusion] |
+
+Each rationale must contain at least 2 reasoning steps. Single-step rationales
+are insufficient.
+
+INSUFFICIENT: "Polling over webhooks | Webhooks are unreliable" SUFFICIENT:
+"Polling over webhooks | Third-party API has 30% webhook delivery failure in
+testing -> unreliable delivery would require fallback polling anyway -> simpler
+to use polling as primary mechanism"
+
+INSUFFICIENT: "500ms timeout | Matches upstream latency" SUFFICIENT: "500ms
+timeout | Upstream 95th percentile is 450ms -> 500ms covers 95% of requests
+without timeout -> remaining 5% should fail fast rather than queue"
+
+Include BOTH architectural decisions AND implementation-level micro-decisions:
+
+- Architectural: "Event sourcing over CRUD | Need audit trail + replay
+  capability -> CRUD would require separate audit log -> event sourcing provides
+  both natively"
+- Implementation: "Mutex over channel | Single-writer case -> channel
+  coordination adds complexity without benefit -> mutex is simpler with
+  equivalent safety"
+
+Technical Writer sources ALL code comments from this table. If a micro-decision
+isn't here, TW cannot document it.
+
+### Rejected Alternatives
+
+| Alternative          | Why Rejected                                                        |
+| -------------------- | ------------------------------------------------------------------- |
+| [Approach not taken] | [Concrete reason: performance, complexity, doesn't fit constraints] |
+
+Technical Writer uses this to add "why not X" context to code comments.
+
+### Constraints & Assumptions
+
+- [Technical: API limits, language version, existing patterns to follow]
+- [Organizational: timeline, team expertise, approval requirements]
+- [Dependencies: external services, libraries, data formats]
+- [Default conventions applied: cite any `<default-conventions domain="...">`
+  used]
+
+### Known Risks
+
+| Risk            | Mitigation                                    | Anchor                                     |
+| --------------- | --------------------------------------------- | ------------------------------------------ |
+| [Specific risk] | [Concrete mitigation or "Accepted: [reason]"] | [file:L###-L### if claiming code behavior] |
+
+**Anchor requirement**: If mitigation claims existing code behavior ("no change
+needed", "already handles X"), cite the file:line + brief excerpt that proves
+the claim. Skip anchors for hypothetical risks or external unknowns.
+
+Quality Reviewer excludes these from findings but will challenge unverified
+behavioral claims.
+
+## Invisible Knowledge
+
+This section captures knowledge NOT deducible from reading the code alone.
+Technical Writer uses this for README.md documentation during
+post-implementation.
+
+**The test**: Would a new team member understand this from reading the source
+files? If no, it belongs here.
+
+**Categories** (not exhaustive -- apply the principle):
+
+1. **Architectural decisions**: Component relationships, data flow, module
+   boundaries
+2. **Business rules**: Domain constraints that shape implementation choices
+3. **System invariants**: Properties that must hold but are not enforced by
+   types/compiler
+4. **Historical context**: Why alternatives were rejected (links to Decision
+   Log)
+5. **Performance characteristics**: Non-obvious efficiency properties or
+   requirements
+6. **Tradeoffs**: Costs and benefits of chosen approaches
+
+### Architecture
+```
+
+[ASCII diagram showing component relationships]
+
+Example: User Request | v +----------+ +-------+ | Auth |---->| Cache |
++----------+ +-------+ | v +----------+ +------+ | Handler |---->| DB |
++----------+ +------+
+
+```
+
+### Data Flow
+
+```
+
+[How data moves through the system - inputs, transformations, outputs]
+
+Example: HTTP Request --> Validate --> Transform --> Store --> Response | v Log
+(async)
+
+````
+
+### Why This Structure
+
+[Reasoning behind module organization that isn't obvious from file names]
+
+- Why these boundaries exist
+- What would break if reorganized differently
+
+### Invariants
+
+[Rules that must be maintained but aren't enforced by code]
+
+- Ordering requirements
+- State consistency rules
+- Implicit contracts between components
+
+### Tradeoffs
+
+[Key decisions with their costs and benefits]
+
+- What was sacrificed for what gain
+- Performance vs. readability choices
+- Consistency vs. flexibility choices
+
+## Milestones
+
+### Milestone 1: [Name]
+
+**Files**: [exact paths - e.g., src/auth/handler.py, not "auth files"]
+
+**Flags** (if applicable): [needs TW rationale, needs error handling review, needs conformance check]
+
+**Requirements**:
+
+- [Specific: "Add retry with exponential backoff", not "improve error handling"]
+
+**Acceptance Criteria**:
+
+- [Testable: "Returns 429 after 3 failed attempts" - QR can verify pass/fail]
+- [Avoid vague: "Works correctly" or "Handles errors properly"]
+
+**Tests** (milestone not complete until tests pass):
+
+- **Test files**: [exact paths, e.g., tests/test_retry.py]
+- **Test type**: [integration | property-based | unit] - see default-conventions
+- **Backing**: [user-specified | doc-derived | default-derived]
+- **Scenarios**:
+  - Normal: [e.g., "successful retry after transient failure"]
+  - Edge: [e.g., "max retries exhausted", "zero delay"]
+  - Error: [e.g., "non-retryable error returns immediately"]
+
+Skip tests when: user explicitly stated no tests, OR milestone is documentation-only,
+OR project docs prohibit tests for this component. State skip reason explicitly.
+
+**Code Changes** (for non-trivial logic, use unified diff format):
+
+See `resources/diff-format.md` for specification.
+
+```diff
+--- a/path/to/file.py
++++ b/path/to/file.py
+@@ -123,6 +123,15 @@ def existing_function(ctx):
+   # Context lines (unchanged) serve as location anchors
+   existing_code()
+
++  # WHY comment explaining rationale - transcribed verbatim by Developer
++  new_code()
+
+   # More context to anchor the insertion point
+   more_existing_code()
+````
+
+### Milestone N: ...
+
+### Milestone [Last]: Documentation
+
+**Files**:
+
+- `path/to/CLAUDE.md` (index updates)
+- `path/to/README.md` (if Invisible Knowledge section has content)
+
+**Requirements**:
+
+- Update CLAUDE.md index entries for all new/modified files
+- Each entry has WHAT (contents) and WHEN (task triggers)
+- If plan's Invisible Knowledge section is non-empty:
+  - Create/update README.md with architecture diagrams from plan
+  - Include tradeoffs, invariants, "why this structure" content
+  - Verify diagrams match actual implementation
+
+**Acceptance Criteria**:
+
+- CLAUDE.md enables LLM to locate relevant code for debugging/modification tasks
+- README.md captures knowledge not discoverable from reading source files
+- Architecture diagrams in README.md match plan's Invisible Knowledge section
+
+**Source Material**: `## Invisible Knowledge` section of this plan
+
+### Cross-Milestone Integration Tests
+
+When integration tests require components from multiple milestones:
+
+1. Place integration tests in the LAST milestone that provides a required
+   component
+2. List dependencies explicitly in that milestone's **Tests** section
+3. Integration test milestone is not complete until all dependencies are
+   implemented
+
+Example:
+
+- M1: Auth handler (property tests for auth logic)
+- M2: Database layer (property tests for queries)
+- M3: API endpoint (integration tests covering M1 + M2 + M3 with testcontainers)
+
+The integration tests in M3 verify the full flow that end users would exercise,
+using real dependencies. This creates fast feedback as soon as all components
+exist.
+
+## Milestone Dependencies (if applicable)
+
+```
+M1 ---> M2
+   \
+    --> M3 --> M4
+```
+
+Independent milestones can execute in parallel during /plan-execution.
+
+```
+
+```

.claude/skills/planner/resources/temporal-contamination.md

@@ -0,0 +1,135 @@
+# Temporal Contamination in Code Comments
+
+This document defines terminology for identifying comments that leak information
+about code history, change processes, or planning artifacts. Both
+@agent-technical-writer and @agent-quality-reviewer reference this
+specification.
+
+## The Core Principle
+
+> **Timeless Present Rule**: Comments must be written from the perspective of a
+> reader encountering the code for the first time, with no knowledge of what
+> came before or how it got here. The code simply _is_.
+
+**Why this matters**: Change-narrative comments are an LLM artifact -- a
+category error, not merely a style issue. The change process is ephemeral and
+irrelevant to the code's ongoing existence. Humans writing comments naturally
+describe what code IS, not what they DID to create it. Referencing the change
+that created a comment is fundamentally confused about what belongs in
+documentation.
+
+Think of it this way: a novel's narrator never describes the author's typing
+process. Similarly, code comments should never describe the developer's editing
+process. The code simply exists; the path to its existence is invisible.
+
+In a plan, this means comments are written _as if the plan was already
+executed_.
+
+## Detection Heuristic
+
+Evaluate each comment against these five questions. Signal words are examples --
+extrapolate to semantically similar constructs.
+
+### 1. Does it describe an action taken rather than what exists?
+
+**Category**: Change-relative
+
+| Contaminated                           | Timeless Present                                            |
+| -------------------------------------- | ----------------------------------------------------------- |
+| `// Added mutex to fix race condition` | `// Mutex serializes cache access from concurrent requests` |
+| `// New validation for the edge case`  | `// Rejects negative values (downstream assumes unsigned)`  |
+| `// Changed to use batch API`          | `// Batch API reduces round-trips from N to 1`              |
+
+Signal words (non-exhaustive): "Added", "Replaced", "Now uses", "Changed to",
+"New", "Updated", "Refactored"
+
+### 2. Does it compare to something not in the code?
+
+**Category**: Baseline reference
+
+| Contaminated                                      | Timeless Present                                                    |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `// Replaces per-tag logging with summary`        | `// Single summary line; per-tag logging would produce 1500+ lines` |
+| `// Unlike the old approach, this is thread-safe` | `// Thread-safe: each goroutine gets independent state`             |
+| `// Previously handled in caller`                 | `// Encapsulated here; caller should not manage lifecycle`          |
+
+Signal words (non-exhaustive): "Instead of", "Rather than", "Previously",
+"Replaces", "Unlike the old", "No longer"
+
+### 3. Does it describe where to put code rather than what code does?
+
+**Category**: Location directive
+
+| Contaminated                  | Timeless Present                              |
+| ----------------------------- | --------------------------------------------- |
+| `// After the SendAsync call` | _(delete -- diff structure encodes location)_ |
+| `// Insert before validation` | _(delete -- diff structure encodes location)_ |
+| `// Add this at line 425`     | _(delete -- diff structure encodes location)_ |
+
+Signal words (non-exhaustive): "After", "Before", "Insert", "At line", "Here:",
+"Below", "Above"
+
+**Action**: Always delete. Location is encoded in diff structure, not comments.
+
+### 4. Does it describe intent rather than behavior?
+
+**Category**: Planning artifact
+
+| Contaminated                           | Timeless Present                                         |
+| -------------------------------------- | -------------------------------------------------------- |
+| `// TODO: add retry logic later`       | _(delete, or implement retry now)_                       |
+| `// Will be extended for batch mode`   | _(delete -- do not document hypothetical futures)_       |
+| `// Temporary workaround until API v2` | `// API v1 lacks filtering; client-side filter required` |
+
+Signal words (non-exhaustive): "Will", "TODO", "Planned", "Eventually", "For
+future", "Temporary", "Workaround until"
+
+**Action**: Delete, implement the feature, or reframe as current constraint.
+
+### 5. Does it describe the author's choice rather than code behavior?
+
+**Category**: Intent leakage
+
+| Contaminated                               | Timeless Present                                     |
+| ------------------------------------------ | ---------------------------------------------------- |
+| `// Intentionally placed after validation` | `// Runs after validation completes`                 |
+| `// Deliberately using mutex over channel` | `// Mutex serializes access (single-writer pattern)` |
+| `// Chose polling for reliability`         | `// Polling: 30% webhook delivery failures observed` |
+| `// We decided to cache at this layer`     | `// Cache here: reduces DB round-trips for hot path` |
+
+Signal words (non-exhaustive): "intentionally", "deliberately", "chose",
+"decided", "on purpose", "by design", "we opted"
+
+**Action**: Extract the technical justification; discard the decision narrative.
+The reader doesn't need to know someone "decided" -- they need to know WHY this
+approach works.
+
+**The test**: Can you delete the intent word and the comment still makes sense?
+If yes, delete the intent word. If no, reframe around the technical reason.
+
+---
+
+**Catch-all**: If a comment only makes sense to someone who knows the code's
+history, it is temporally contaminated -- even if it does not match any category
+above.
+
+## Subtle Cases
+
+Same word, different verdict -- demonstrates that detection requires semantic
+judgment, not keyword matching.
+
+| Comment                                | Verdict      | Reasoning                                        |
+| -------------------------------------- | ------------ | ------------------------------------------------ |
+| `// Now handles edge cases properly`   | Contaminated | "properly" implies it was improper before        |
+| `// Now blocks until connection ready` | Clean        | "now" describes runtime moment, not code history |
+| `// Fixed the null pointer issue`      | Contaminated | Describes a fix, not behavior                    |
+| `// Returns null when key not found`   | Clean        | Describes behavior                               |
+
+## The Transformation Pattern
+
+> **Extract the technical justification, discard the change narrative.**
+
+1. What useful info is buried? (problem, behavior)
+2. Reframe as timeless present
+
+Example: "Added mutex to fix race" -> "Mutex serializes concurrent access"

.claude/skills/planner/scripts/executor.py

@@ -0,0 +1,682 @@
+#!/usr/bin/env python3
+"""
+Plan Executor - Execute approved plans through delegation.
+
+Seven-phase execution workflow with JIT prompt injection:
+  Step 1: Execution Planning (analyze plan, detect reconciliation)
+  Step 2: Reconciliation (conditional, validate existing code)
+  Step 3: Milestone Execution (delegate to agents, run tests)
+  Step 4: Post-Implementation QR (quality review)
+  Step 5: QR Issue Resolution (conditional, fix issues)
+  Step 6: Documentation (TW pass)
+  Step 7: Retrospective (present summary)
+
+Usage:
+    python3 executor.py --plan-file PATH --step-number 1 --total-steps 7 --thoughts "..."
+"""
+
+import argparse
+import re
+import sys
+
+
+def detect_reconciliation_signals(thoughts: str) -> bool:
+    """Check if user's thoughts contain reconciliation triggers."""
+    triggers = [
+        r"\balready\s+(implemented|done|complete)",
+        r"\bpartially\s+complete",
+        r"\bhalfway\s+done",
+        r"\bresume\b",
+        r"\bcontinue\s+from\b",
+        r"\bpick\s+up\s+where\b",
+        r"\bcheck\s+what'?s\s+done\b",
+        r"\bverify\s+existing\b",
+        r"\bprior\s+work\b",
+    ]
+    thoughts_lower = thoughts.lower()
+    return any(re.search(pattern, thoughts_lower) for pattern in triggers)
+
+
+def get_step_1_guidance(plan_file: str, thoughts: str) -> dict:
+    """Step 1: Execution Planning - analyze plan, detect reconciliation."""
+    reconciliation_detected = detect_reconciliation_signals(thoughts)
+
+    actions = [
+        "EXECUTION PLANNING",
+        "",
+        f"Plan file: {plan_file}",
+        "",
+        "Read the plan file and analyze:",
+        "  1. Count milestones and their dependencies",
+        "  2. Identify file targets per milestone",
+        "  3. Determine parallelization opportunities",
+        "  4. Set up TodoWrite tracking for all milestones",
+        "",
+        "<execution_rules>",
+        "",
+        "RULE 0 (ABSOLUTE): Delegate ALL code work to specialized agents",
+        "",
+        "Your role: coordinate, validate, orchestrate. Agents implement code.",
+        "",
+        "Delegation routing:",
+        "  - New function needed -> @agent-developer",
+        "  - Bug to fix -> @agent-debugger (diagnose) then @agent-developer (fix)",
+        "  - Any source file modification -> @agent-developer",
+        "  - Documentation files -> @agent-technical-writer",
+        "",
+        "Exception (trivial only): Fixes under 5 lines where delegation overhead",
+        "exceeds fix complexity (missing import, typo correction).",
+        "",
+        "---",
+        "",
+        "RULE 1: Execution Protocol",
+        "",
+        "Before ANY phase:",
+        "  1. Use TodoWrite to track all plan phases",
+        "  2. Analyze dependencies to identify parallelizable work",
+        "  3. Delegate implementation to specialized agents",
+        "  4. Validate each increment before proceeding",
+        "",
+        "You plan HOW to execute (parallelization, sequencing). You do NOT plan",
+        "WHAT to execute -- that's the plan's job.",
+        "",
+        "---",
+        "",
+        "RULE 1.5: Model Selection",
+        "",
+        "Agent defaults (sonnet) are calibrated for quality. Adjust upward only.",
+        "",
+        "  | Action               | Allowed | Rationale                        |",
+        "  |----------------------|---------|----------------------------------|",
+        "  | Upgrade to opus      | YES     | Challenging tasks need reasoning |",
+        "  | Use default (sonnet) | YES     | Baseline for all delegations     |",
+        "  | Keep at sonnet+      | ALWAYS  | Maintains quality baseline       |",
+        "",
+        "</execution_rules>",
+        "",
+        "<dependency_analysis>",
+        "",
+        "Parallelizable when ALL conditions met:",
+        "  - Different target files",
+        "  - No data dependencies",
+        "  - No shared state (globals, configs, resources)",
+        "",
+        "Sequential when ANY condition true:",
+        "  - Same file modified by multiple tasks",
+        "  - Task B imports or depends on Task A's output",
+        "  - Shared database tables or external resources",
+        "",
+        "Before delegating ANY batch:",
+        "  1. List tasks with their target files",
+        "  2. Identify file dependencies (same file = sequential)",
+        "  3. Identify data dependencies (imports = sequential)",
+        "  4. Group independent tasks into parallel batches",
+        "  5. Separate batches with sync points",
+        "",
+        "</dependency_analysis>",
+        "",
+        "<milestone_type_detection>",
+        "",
+        "Before delegating ANY milestone, identify its type from file extensions:",
+        "",
+        "  | Milestone Type | Recognition Signal              | Delegate To             |",
+        "  |----------------|--------------------------------|-------------------------|",
+        "  | Documentation  | ALL files are *.md or *.rst    | @agent-technical-writer |",
+        "  | Code           | ANY file is source code        | @agent-developer        |",
+        "",
+        "Mixed milestones: Split delegation -- @agent-developer first (code),",
+        "then @agent-technical-writer (docs) after code completes.",
+        "",
+        "</milestone_type_detection>",
+        "",
+        "<delegation_format>",
+        "",
+        "EVERY delegation MUST use this structure:",
+        "",
+        "  <delegation>",
+        "    <agent>@agent-[developer|debugger|technical-writer|quality-reviewer]</agent>",
+        "    <mode>[For TW/QR: plan-scrub|post-implementation|plan-review|reconciliation]</mode>",
+        "    <plan_source>[Absolute path to plan file]</plan_source>",
+        "    <milestone>[Milestone number and name]</milestone>",
+        "    <files>[Exact file paths from milestone]</files>",
+        "    <task>[Specific task description]</task>",
+        "    <acceptance_criteria>",
+        "      - [Criterion 1 from plan]",
+        "      - [Criterion 2 from plan]",
+        "    </acceptance_criteria>",
+        "  </delegation>",
+        "",
+        "For parallel delegations, wrap multiple blocks:",
+        "",
+        "  <parallel_batch>",
+        "    <rationale>[Why these can run in parallel]</rationale>",
+        "    <sync_point>[Command to run after all complete]</sync_point>",
+        "    <delegation>...</delegation>",
+        "    <delegation>...</delegation>",
+        "  </parallel_batch>",
+        "",
+        "Agent limits:",
+        "  - @agent-developer: Maximum 4 parallel",
+        "  - @agent-debugger: Maximum 2 parallel",
+        "  - @agent-quality-reviewer: ALWAYS sequential",
+        "  - @agent-technical-writer: Can parallel across independent modules",
+        "",
+        "</delegation_format>",
+    ]
+
+    if reconciliation_detected:
+        next_step = (
+            "RECONCILIATION SIGNALS DETECTED in your thoughts.\n\n"
+            "Invoke step 2 to validate existing code against plan requirements:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 2 '
+            '--total-steps 7 --thoughts "Starting reconciliation..."'
+        )
+    else:
+        next_step = (
+            "No reconciliation signals detected. Proceed to milestone execution.\n\n"
+            "Invoke step 3 to begin delegating milestones:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 3 '
+            '--total-steps 7 --thoughts "Analyzed plan: N milestones, '
+            'parallel batches: [describe], starting execution..."'
+        )
+
+    return {
+        "actions": actions,
+        "next": next_step,
+    }
+
+
+def get_step_2_guidance(plan_file: str) -> dict:
+    """Step 2: Reconciliation - validate existing code against plan."""
+    return {
+        "actions": [
+            "RECONCILIATION PHASE",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Validate existing code against plan requirements BEFORE executing.",
+            "",
+            "<reconciliation_protocol>",
+            "",
+            "Delegate to @agent-quality-reviewer for each milestone:",
+            "",
+            "  Task for @agent-quality-reviewer:",
+            "  Mode: reconciliation",
+            "  Plan Source: [plan_file.md]",
+            "  Milestone: [N]",
+            "",
+            "  Check if the acceptance criteria for Milestone [N] are ALREADY",
+            "  satisfied in the current codebase. Validate REQUIREMENTS, not just",
+            "  code presence.",
+            "",
+            "  Return: SATISFIED | NOT_SATISFIED | PARTIALLY_SATISFIED",
+            "",
+            "---",
+            "",
+            "Execution based on reconciliation result:",
+            "",
+            "  | Result              | Action                                    |",
+            "  |---------------------|-------------------------------------------|",
+            "  | SATISFIED           | Skip execution, record as already complete|",
+            "  | NOT_SATISFIED       | Execute milestone normally                |",
+            "  | PARTIALLY_SATISFIED | Execute only the missing parts            |",
+            "",
+            "---",
+            "",
+            "Why requirements-based (not diff-based):",
+            "",
+            "Checking if code from the diff exists misses critical cases:",
+            "  - Code added but incorrect (doesn't meet acceptance criteria)",
+            "  - Code added but incomplete (partial implementation)",
+            "  - Requirements met by different code than planned (valid alternative)",
+            "",
+            "Checking acceptance criteria catches all of these.",
+            "",
+            "</reconciliation_protocol>",
+        ],
+        "next": (
+            "After collecting reconciliation results for all milestones, "
+            "invoke step 3:\n\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 3 '
+            "--total-steps 7 --thoughts \"Reconciliation complete: "
+            'M1: SATISFIED, M2: NOT_SATISFIED, ..."'
+        ),
+    }
+
+
+def get_step_3_guidance(plan_file: str) -> dict:
+    """Step 3: Milestone Execution - delegate to agents, run tests."""
+    return {
+        "actions": [
+            "MILESTONE EXECUTION",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Execute milestones through delegation. Parallelize independent work.",
+            "",
+            "<diff_compliance_validation>",
+            "",
+            "BEFORE delegating each milestone with code changes:",
+            "  1. Read resources/diff-format.md if not already in context",
+            "  2. Verify plan's diffs meet specification:",
+            "     - Context lines are VERBATIM from actual files (not placeholders)",
+            "     - WHY comments explain rationale (not WHAT code does)",
+            "     - No location directives in comments",
+            "",
+            "AFTER @agent-developer completes, verify:",
+            "  - Context lines from plan were found in target file",
+            "  - WHY comments were transcribed verbatim to code",
+            "  - No location directives remain in implemented code",
+            "  - No temporal contamination leaked (change-relative language)",
+            "",
+            "If Developer reports context lines not found, check drift table below.",
+            "",
+            "</diff_compliance_validation>",
+            "",
+            "<error_handling>",
+            "",
+            "Error classification:",
+            "",
+            "  | Severity | Signals                          | Action                  |",
+            "  |----------|----------------------------------|-------------------------|",
+            "  | Critical | Segfault, data corruption        | STOP, @agent-debugger   |",
+            "  | High     | Test failures, missing deps      | @agent-debugger         |",
+            "  | Medium   | Type errors, lint failures       | Auto-fix, then debugger |",
+            "  | Low      | Warnings, style issues           | Note and continue       |",
+            "",
+            "Escalation triggers -- STOP and report when:",
+            "  - Fix would change fundamental approach",
+            "  - Three attempted solutions failed",
+            "  - Performance or safety characteristics affected",
+            "  - Confidence < 80%",
+            "",
+            "Context anchor mismatch protocol:",
+            "",
+            "When @agent-developer reports context lines don't match actual code:",
+            "",
+            "  | Mismatch Type               | Action                         |",
+            "  |-----------------------------|--------------------------------|",
+            "  | Whitespace/formatting only  | Proceed with normalized match  |",
+            "  | Minor variable rename       | Proceed, note in execution log |",
+            "  | Code restructured           | Proceed, note deviation        |",
+            "  | Context lines not found     | STOP - escalate to planner     |",
+            "  | Logic fundamentally changed | STOP - escalate to planner     |",
+            "",
+            "</error_handling>",
+            "",
+            "<acceptance_testing>",
+            "",
+            "Run after each milestone:",
+            "",
+            "  # Python",
+            "  pytest --strict-markers --strict-config",
+            "  mypy --strict",
+            "",
+            "  # JavaScript/TypeScript",
+            "  tsc --strict --noImplicitAny",
+            "  eslint --max-warnings=0",
+            "",
+            "  # Go",
+            "  go test -race -cover -vet=all",
+            "",
+            "Pass criteria: 100% tests pass, zero linter warnings.",
+            "",
+            "Self-consistency check (for milestones with >3 files):",
+            "  1. Developer's implementation notes claim: [what was implemented]",
+            "  2. Test results demonstrate: [what behavior was verified]",
+            "  3. Acceptance criteria state: [what was required]",
+            "",
+            "All three must align. Discrepancy = investigate before proceeding.",
+            "",
+            "</acceptance_testing>",
+        ],
+        "next": (
+            "CONTINUE in step 3 until ALL milestones complete:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 3 '
+            '--total-steps 7 --thoughts "Completed M1, M2. Executing M3..."'
+            "\n\n"
+            "When ALL milestones are complete, invoke step 4 for quality review:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 4 '
+            '--total-steps 7 --thoughts "All milestones complete. '
+            'Modified files: [list]. Ready for QR."'
+        ),
+    }
+
+
+def get_step_4_guidance(plan_file: str) -> dict:
+    """Step 4: Post-Implementation QR - quality review."""
+    return {
+        "actions": [
+            "POST-IMPLEMENTATION QUALITY REVIEW",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Delegate to @agent-quality-reviewer for comprehensive review.",
+            "",
+            "<qr_delegation>",
+            "",
+            "  Task for @agent-quality-reviewer:",
+            "  Mode: post-implementation",
+            "  Plan Source: [plan_file.md]",
+            "  Files Modified: [list]",
+            "  Reconciled Milestones: [list milestones that were SATISFIED]",
+            "",
+            "  Priority order for findings:",
+            "    1. Issues in reconciled milestones (bypassed execution validation)",
+            "    2. Issues in newly implemented milestones",
+            "    3. Cross-cutting issues",
+            "",
+            "  Checklist:",
+            "    - Every requirement implemented",
+            "    - No unauthorized deviations",
+            "    - Edge cases handled",
+            "    - Performance requirements met",
+            "",
+            "</qr_delegation>",
+            "",
+            "Expected output: PASS or issues list sorted by severity.",
+        ],
+        "next": (
+            "After QR completes:\n\n"
+            "If QR returns ISSUES -> invoke step 5:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 5 '
+            '--total-steps 7 --thoughts "QR found N issues: [summary]"'
+            "\n\n"
+            "If QR returns PASS -> invoke step 6:\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 6 '
+            '--total-steps 7 --thoughts "QR passed. Proceeding to documentation."'
+        ),
+    }
+
+
+def get_step_5_guidance(plan_file: str) -> dict:
+    """Step 5: QR Issue Resolution - present issues, collect decisions, fix."""
+    return {
+        "actions": [
+            "QR ISSUE RESOLUTION",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Present issues to user, collect decisions, delegate fixes.",
+            "",
+            "<issue_resolution_protocol>",
+            "",
+            "Phase 1: Collect Decisions",
+            "",
+            "Sort findings by severity (critical -> high -> medium -> low).",
+            "For EACH issue, present:",
+            "",
+            "  ## Issue [N] of [Total] ([severity])",
+            "",
+            "  **Category**: [production-reliability | project-conformance | structural-quality]",
+            "  **File**: [affected file path]",
+            "  **Location**: [function/line if applicable]",
+            "",
+            "  **Problem**:",
+            "  [Clear description of what is wrong and why it matters]",
+            "",
+            "  **Evidence**:",
+            "  [Specific code/behavior that demonstrates the issue]",
+            "",
+            "Then use AskUserQuestion with options:",
+            "  - **Fix**: Delegate to @agent-developer to resolve",
+            "  - **Skip**: Accept the issue as-is",
+            "  - **Alternative**: User provides different approach",
+            "",
+            "Repeat for each issue. Do NOT execute any fixes during this phase.",
+            "",
+            "---",
+            "",
+            "Phase 2: Execute Decisions",
+            "",
+            "After ALL decisions are collected:",
+            "",
+            "  1. Summarize the decisions",
+            "  2. Execute fixes:",
+            "     - 'Fix' decisions: Delegate to @agent-developer",
+            "     - 'Skip' decisions: Record in retrospective as accepted risk",
+            "     - 'Alternative' decisions: Apply user's specified approach",
+            "  3. Parallelize where possible (different files, no dependencies)",
+            "",
+            "</issue_resolution_protocol>",
+        ],
+        "next": (
+            "After ALL fixes are applied, return to step 4 for re-validation:\n\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 4 '
+            '--total-steps 7 --thoughts "Applied fixes for issues X, Y, Z. '
+            'Re-running QR."'
+            "\n\n"
+            "This creates a validation loop until QR passes."
+        ),
+    }
+
+
+def get_step_6_guidance(plan_file: str) -> dict:
+    """Step 6: Documentation - TW pass for CLAUDE.md, README.md."""
+    return {
+        "actions": [
+            "POST-IMPLEMENTATION DOCUMENTATION",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Delegate to @agent-technical-writer for documentation updates.",
+            "",
+            "<tw_delegation>",
+            "",
+            "Skip condition: If ALL milestones contained only documentation files",
+            "(*.md/*.rst), TW already handled this during milestone execution.",
+            "Proceed directly to step 7.",
+            "",
+            "For code-primary plans:",
+            "",
+            "  Task for @agent-technical-writer:",
+            "  Mode: post-implementation",
+            "  Plan Source: [plan_file.md]",
+            "  Files Modified: [list]",
+            "",
+            "  Requirements:",
+            "    - Create/update CLAUDE.md index entries",
+            "    - Create README.md if architectural complexity warrants",
+            "    - Add module-level docstrings where missing",
+            "    - Verify transcribed comments are accurate",
+            "",
+            "</tw_delegation>",
+            "",
+            "<final_checklist>",
+            "",
+            "Execution is NOT complete until:",
+            "  - [ ] All todos completed",
+            "  - [ ] Quality review passed (no unresolved issues)",
+            "  - [ ] Documentation delegated for ALL modified files",
+            "  - [ ] Documentation tasks completed",
+            "  - [ ] Self-consistency checks passed for complex milestones",
+            "",
+            "</final_checklist>",
+        ],
+        "next": (
+            "After documentation is complete, invoke step 7 for retrospective:\n\n"
+            f'  python3 executor.py --plan-file "{plan_file}" --step-number 7 '
+            '--total-steps 7 --thoughts "Documentation complete. '
+            'Generating retrospective."'
+        ),
+    }
+
+
+def get_step_7_guidance(plan_file: str) -> dict:
+    """Step 7: Retrospective - present execution summary."""
+    return {
+        "actions": [
+            "EXECUTION RETROSPECTIVE",
+            "",
+            f"Plan file: {plan_file}",
+            "",
+            "Generate and PRESENT the retrospective to the user.",
+            "Do NOT write to a file -- present it directly so the user sees it.",
+            "",
+            "<retrospective_format>",
+            "",
+            "================================================================================",
+            "EXECUTION RETROSPECTIVE",
+            "================================================================================",
+            "",
+            "Plan: [plan file path]",
+            "Status: COMPLETED | BLOCKED | ABORTED",
+            "",
+            "## Milestone Outcomes",
+            "",
+            "| Milestone  | Status               | Notes                              |",
+            "| ---------- | -------------------- | ---------------------------------- |",
+            "| 1: [name]  | EXECUTED             | -                                  |",
+            "| 2: [name]  | SKIPPED (RECONCILED) | Already satisfied before execution |",
+            "| 3: [name]  | BLOCKED              | [reason]                           |",
+            "",
+            "## Reconciliation Summary",
+            "",
+            "If reconciliation was run:",
+            "  - Milestones already complete: [count]",
+            "  - Milestones executed: [count]",
+            "  - Milestones with partial work detected: [count]",
+            "",
+            "If reconciliation was skipped:",
+            '  - "Reconciliation skipped (no prior work indicated)"',
+            "",
+            "## Plan Accuracy Issues",
+            "",
+            "[List any problems with the plan discovered during execution]",
+            "  - [file] Context anchor drift: expected X, found Y",
+            "  - Milestone [N] requirements were ambiguous: [what]",
+            "  - Missing dependency: [what was assumed but didn't exist]",
+            "",
+            'If none: "No plan accuracy issues encountered."',
+            "",
+            "## Deviations from Plan",
+            "",
+            "| Deviation      | Category        | Approved By      |",
+            "| -------------- | --------------- | ---------------- |",
+            "| [what changed] | Trivial / Minor | [who or 'auto']  |",
+            "",
+            'If none: "No deviations from plan."',
+            "",
+            "## Quality Review Summary",
+            "",
+            "  - Production reliability: [count] issues",
+            "  - Project conformance: [count] issues",
+            "  - Structural quality: [count] suggestions",
+            "",
+            "## Feedback for Future Plans",
+            "",
+            "[Actionable improvements based on execution experience]",
+            "  - [ ] [specific suggestion]",
+            "  - [ ] [specific suggestion]",
+            "",
+            "================================================================================",
+            "",
+            "</retrospective_format>",
+        ],
+        "next": "EXECUTION COMPLETE.\n\nPresent the retrospective to the user.",
+    }
+
+
+def get_step_guidance(step_number: int, plan_file: str, thoughts: str) -> dict:
+    """Route to appropriate step guidance."""
+    if step_number == 1:
+        return get_step_1_guidance(plan_file, thoughts)
+    elif step_number == 2:
+        return get_step_2_guidance(plan_file)
+    elif step_number == 3:
+        return get_step_3_guidance(plan_file)
+    elif step_number == 4:
+        return get_step_4_guidance(plan_file)
+    elif step_number == 5:
+        return get_step_5_guidance(plan_file)
+    elif step_number == 6:
+        return get_step_6_guidance(plan_file)
+    elif step_number == 7:
+        return get_step_7_guidance(plan_file)
+    else:
+        return {
+            "actions": [f"Unknown step {step_number}. Valid steps are 1-7."],
+            "next": "Re-invoke with a valid step number.",
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Plan Executor - Execute approved plans through delegation",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Start execution
+  python3 executor.py --plan-file plans/auth.md --step-number 1 --total-steps 7 \\
+    --thoughts "Execute the auth implementation plan"
+
+  # Continue milestone execution
+  python3 executor.py --plan-file plans/auth.md --step-number 3 --total-steps 7 \\
+    --thoughts "Completed M1, M2. Executing M3..."
+
+  # After QR finds issues
+  python3 executor.py --plan-file plans/auth.md --step-number 5 --total-steps 7 \\
+    --thoughts "QR found 2 issues: missing error handling, incorrect return type"
+""",
+    )
+
+    parser.add_argument(
+        "--plan-file", type=str, required=True, help="Path to the plan file to execute"
+    )
+    parser.add_argument("--step-number", type=int, required=True, help="Current step (1-7)")
+    parser.add_argument(
+        "--total-steps", type=int, required=True, help="Total steps (always 7)"
+    )
+    parser.add_argument(
+        "--thoughts", type=str, required=True, help="Your current thinking and status"
+    )
+
+    args = parser.parse_args()
+
+    if args.step_number < 1 or args.step_number > 7:
+        print("Error: step-number must be between 1 and 7", file=sys.stderr)
+        sys.exit(1)
+
+    if args.total_steps != 7:
+        print("Warning: total-steps should be 7 for executor", file=sys.stderr)
+
+    guidance = get_step_guidance(args.step_number, args.plan_file, args.thoughts)
+    is_complete = args.step_number >= 7
+
+    step_names = {
+        1: "Execution Planning",
+        2: "Reconciliation",
+        3: "Milestone Execution",
+        4: "Post-Implementation QR",
+        5: "QR Issue Resolution",
+        6: "Documentation",
+        7: "Retrospective",
+    }
+
+    print("=" * 80)
+    print(
+        f"EXECUTOR - Step {args.step_number} of 7: {step_names.get(args.step_number, 'Unknown')}"
+    )
+    print("=" * 80)
+    print()
+    print(f"STATUS: {'execution_complete' if is_complete else 'in_progress'}")
+    print()
+    print("YOUR THOUGHTS:")
+    print(args.thoughts)
+    print()
+
+    if guidance["actions"]:
+        print("GUIDANCE:")
+        print()
+        for action in guidance["actions"]:
+            print(action)
+        print()
+
+    print("NEXT:")
+    print(guidance["next"])
+    print()
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/problem-analysis/CLAUDE.md

@@ -0,0 +1,19 @@
+# skills/problem-analysis/
+
+## Overview
+
+Structured problem analysis skill. IMMEDIATELY invoke the script - do NOT
+explore first.
+
+## Index
+
+| File/Directory       | Contents          | Read When          |
+| -------------------- | ----------------- | ------------------ |
+| `SKILL.md`           | Invocation        | Using this skill   |
+| `scripts/analyze.py` | Complete workflow | Debugging behavior |
+
+## Key Point
+
+The script IS the workflow. It handles decomposition, solution generation,
+critique, verification, and synthesis. Do NOT analyze before invoking. Run the
+script and obey its output.

.claude/skills/problem-analysis/README.md

@@ -0,0 +1,45 @@
+# Problem Analysis
+
+LLMs jump to solutions. You describe a problem, they propose an answer. For
+complex decisions with multiple viable paths, that first answer often reflects
+the LLM's biases rather than the best fit for your constraints. This skill
+forces structured reasoning before you commit.
+
+The skill runs through six phases:
+
+| Phase       | Actions                                                                  |
+| ----------- | ------------------------------------------------------------------------ |
+| Decompose   | State problem; identify hard/soft constraints, variables, assumptions    |
+| Generate    | Create 2-4 distinct approaches (fundamentally different, not variations) |
+| Critique    | Specific weaknesses; eliminate or refine                                 |
+| Verify      | Answer questions WITHOUT looking at solutions                            |
+| Cross-check | Reconcile verified facts with original claims; update viability          |
+| Synthesize  | Trade-off matrix with verified facts; decision framework                 |
+
+## When to Use
+
+Use this for decisions where the cost of choosing wrong is high:
+
+- Multiple viable technical approaches (Redis vs Postgres, REST vs GraphQL)
+- Architectural decisions with long-term consequences
+- Problems where you suspect your first instinct might be wrong
+
+## Example Usage
+
+```
+I need to decide how to handle distributed locking in our microservices.
+Options I'm considering:
+
+- Redis with Redlock algorithm
+- ZooKeeper
+- Database advisory locks
+
+Use your problem-analysis skill to structure this decision.
+```
+
+## The Design
+
+The structure prevents premature convergence. Critique catches obvious flaws
+before costly verification. Factored verification prevents confirmation bias --
+you answer questions without seeing your original solutions. Cross-check forces
+explicit reconciliation of evidence with claims.

.claude/skills/problem-analysis/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: problem-analysis
+description: Invoke IMMEDIATELY for structured problem analysis and solution discovery.
+---
+
+# Problem Analysis
+
+When this skill activates, IMMEDIATELY invoke the script. The script IS the
+workflow.
+
+## Invocation
+
+```bash
+python3 scripts/analyze.py \
+  --step 1 \
+  --total-steps 7 \
+  --thoughts "Problem: <describe>"
+```
+
+| Argument        | Required | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `--step`        | Yes      | Current step (starts at 1)                |
+| `--total-steps` | Yes      | Minimum 7; adjust as script instructs     |
+| `--thoughts`    | Yes      | Accumulated state from all previous steps |
+
+Do NOT analyze or explore first. Run the script and follow its output.

.claude/skills/problem-analysis/scripts/analyze.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""
+Problem Analysis Skill - Structured deep reasoning workflow.
+
+Guides problem analysis through seven phases:
+  1. Decompose  - understand problem space, constraints, assumptions
+  2. Generate   - create initial solution approaches
+  3. Expand     - push for MORE solutions not yet considered
+  4. Critique   - Self-Refine feedback on solutions
+  5. Verify     - factored verification of assumptions
+  6. Cross-check - reconcile verified facts with claims
+  7. Synthesize - structured trade-off analysis
+
+Extra steps beyond 7 go to verification (where accuracy improves most).
+
+Usage:
+    python3 analyze.py --step 1 --total-steps 7 --thoughts "Problem: <describe the decision or challenge>"
+
+Research grounding:
+  - ToT (Yao 2023): decompose into thoughts "small enough for diverse samples,
+    big enough to evaluate"
+  - CoVe (Dhuliawala 2023): factored verification improves accuracy 17%->70%.
+    Use OPEN questions, not yes/no ("model tends to agree whether right or wrong")
+  - Self-Refine (Madaan 2023): feedback must be "actionable and specific";
+    separate feedback from refinement for 5-40% improvement
+  - Analogical Prompting (Yasunaga 2024): "recall relevant and distinct problems"
+    improves reasoning; diversity in self-generated examples is critical
+  - Diversity-Based Selection (Zhang 2022): "even with 50% wrong demonstrations,
+    diversity-based clustering performance does not degrade significantly"
+"""
+
+import argparse
+import sys
+
+
+def get_step_1_guidance():
+    """Step 1: Problem Decomposition - understand the problem space."""
+    return (
+        "Problem Decomposition",
+        [
+            "State the CORE PROBLEM in one sentence: 'I need to decide X'",
+            "",
+            "List HARD CONSTRAINTS (non-negotiable):",
+            "  - Hard constraints: latency limits, accuracy requirements, compatibility",
+            "  - Resource constraints: budget, timeline, skills, capacity",
+            "  - Quality constraints: what 'good' looks like for this problem",
+            "",
+            "List SOFT CONSTRAINTS (preferences, can trade off)",
+            "",
+            "List VARIABLES (what you control):",
+            "  - Structural choices (architecture, format, organization)",
+            "  - Content choices (scope, depth, audience, tone)",
+            "  - Process choices (workflow, tools, automation level)",
+            "",
+            "Surface HIDDEN ASSUMPTIONS by asking:",
+            "  'What am I assuming about scale/load patterns?'",
+            "  'What am I assuming about the team's capabilities?'",
+            "  'What am I assuming will NOT change?'",
+            "",
+            "If unclear, use AskUserQuestion to clarify",
+        ],
+        [
+            "PROBLEM (one sentence)",
+            "HARD CONSTRAINTS (non-negotiable)",
+            "SOFT CONSTRAINTS (preferences)",
+            "VARIABLES (what you control)",
+            "ASSUMPTIONS (surfaced via questions)",
+        ],
+    )
+
+
+def get_step_2_guidance():
+    """Step 2: Solution Generation - create distinct approaches."""
+    return (
+        "Solution Generation",
+        [
+            "Generate 2-4 DISTINCT solution approaches",
+            "",
+            "Solutions must differ on a FUNDAMENTAL AXIS:",
+            "  - Scope: narrow-deep vs broad-shallow",
+            "  - Complexity: simple-but-limited vs complex-but-flexible",
+            "  - Control: standardized vs customizable",
+            "  - Approach: build vs buy, manual vs automated, centralized vs distributed",
+            "  (Identify axes specific to your problem domain)",
+            "",
+            "For EACH solution, document:",
+            "  - Name: short label (e.g., 'Option A', 'Hybrid Approach')",
+            "  - Core mechanism: HOW it solves the problem (1-2 sentences)",
+            "  - Key assumptions: what must be true for this to work",
+            "  - Claimed benefits: what this approach provides",
+            "",
+            "AVOID premature convergence - do not favor one solution yet",
+        ],
+        [
+            "PROBLEM (from step 1)",
+            "CONSTRAINTS (from step 1)",
+            "SOLUTIONS (each with: name, mechanism, assumptions, claimed benefits)",
+        ],
+    )
+
+
+def get_step_3_guidance():
+    """Step 3: Solution Expansion - push beyond initial ideas."""
+    return (
+        "Solution Expansion",
+        [
+            "Review the solutions from step 2. Now PUSH FURTHER:",
+            "",
+            "UNEXPLORED AXES - What fundamental trade-offs were NOT represented?",
+            "  - If all solutions are complex, what's the SIMPLEST approach?",
+            "  - If all are centralized, what's DISTRIBUTED?",
+            "  - If all use technology X, what uses its OPPOSITE or COMPETITOR?",
+            "  - If all optimize for metric A, what optimizes for metric B?",
+            "",
+            "ADJACENT DOMAINS - What solutions from RELATED problems might apply?",
+            "  'How does [related domain] solve similar problems?'",
+            "  'What would [different industry/field] do here?'",
+            "  'What patterns from ADJACENT DOMAINS might apply?'",
+            "",
+            "ANTI-SOLUTIONS - What's the OPPOSITE of each current solution?",
+            "  If Solution A is stateful, what's stateless?",
+            "  If Solution A is synchronous, what's asynchronous?",
+            "  If Solution A is custom-built, what's off-the-shelf?",
+            "",
+            "NULL/MINIMAL OPTIONS:",
+            "  - What if we did NOTHING and accepted the current state?",
+            "  - What if we solved a SMALLER version of the problem?",
+            "  - What's the 80/20 solution that's 'good enough'?",
+            "",
+            "ADD 1-3 MORE solutions. Each must represent an axis/approach",
+            "not covered by the initial set.",
+        ],
+        [
+            "INITIAL SOLUTIONS (from step 2)",
+            "AXES NOT YET EXPLORED (identified gaps)",
+            "NEW SOLUTIONS (1-3 additional, each with: name, mechanism, assumptions)",
+            "COMPLETE SOLUTION SET (all solutions for next phase)",
+        ],
+    )
+
+
+def get_step_4_guidance():
+    """Step 4: Solution Critique - Self-Refine feedback phase."""
+    return (
+        "Solution Critique",
+        [
+            "For EACH solution, identify weaknesses:",
+            "  - What could go wrong? (failure modes)",
+            "  - What does this solution assume that might be false?",
+            "  - Where is the complexity hiding?",
+            "  - What operational burden does this create?",
+            "",
+            "Generate SPECIFIC, ACTIONABLE feedback:",
+            "  BAD:  'This might have scaling issues'",
+            "  GOOD: 'Single-node Redis fails at >100K ops/sec; Solution A",
+            "         assumes <50K ops/sec but requirements say 200K'",
+            "",
+            "Identify which solutions should be:",
+            "  - ELIMINATED: fatal flaw, violates hard constraint",
+            "  - REFINED: fixable weakness, needs modification",
+            "  - ADVANCED: no obvious flaws, proceed to verification",
+            "",
+            "For REFINED solutions, state the specific modification needed",
+        ],
+        [
+            "SOLUTIONS (from step 2)",
+            "CRITIQUE for each (specific weaknesses, failure modes)",
+            "DISPOSITION: ELIMINATED / REFINED / ADVANCED for each",
+            "MODIFICATIONS needed for REFINED solutions",
+        ],
+    )
+
+
+def get_verification_guidance():
+    """
+    Steps 4 to N-2: Factored Assumption Verification.
+
+    Key insight from CoVe: answer verification questions WITHOUT attending
+    to the original solutions. Models that see their own hallucinations
+    tend to repeat them.
+    """
+    return (
+        "Factored Verification",
+        [
+            "FACTORED VERIFICATION (answer WITHOUT looking at solutions):",
+            "",
+            "Step A - List assumptions as OPEN questions:",
+            "  BAD:  'Is option A better?' (yes/no triggers agreement bias)",
+            "  GOOD: 'What throughput does option A achieve under heavy load?'",
+            "  GOOD: 'What reading level does this document require?'",
+            "  GOOD: 'How long does this workflow take with the proposed automation?'",
+            "",
+            "Step B - Answer each question INDEPENDENTLY:",
+            "  - Pretend you have NOT seen the solutions",
+            "  - Answer from first principles or domain knowledge",
+            "  - Do NOT defend any solution; seek truth",
+            "  - Cite sources or reasoning for each answer",
+            "",
+            "Step C - Categorize each assumption:",
+            "  VERIFIED:  evidence confirms the assumption",
+            "  FALSIFIED: evidence contradicts (note: 'claimed X, actually Y')",
+            "  UNCERTAIN: insufficient evidence; note what would resolve it",
+        ],
+        [
+            "SOLUTIONS still under consideration",
+            "VERIFICATION QUESTIONS (open, not yes/no)",
+            "ANSWERS (independent, from first principles)",
+            "CATEGORIZED: VERIFIED / FALSIFIED / UNCERTAIN for each",
+        ],
+    )
+
+
+def get_crosscheck_guidance():
+    """
+    Step N-1: Cross-check - reconcile verified facts with original claims.
+
+    From CoVe Factor+Revise: explicit cross-check achieves +7.7 FACTSCORE
+    points over factored verification alone.
+    """
+    return (
+        "Cross-Check",
+        [
+            "Reconcile verified facts with solution claims:",
+            "",
+            "For EACH surviving solution:",
+            "  - Which claims are now SUPPORTED by verification?",
+            "  - Which claims are CONTRADICTED? (list specific contradictions)",
+            "  - Which claims remain UNTESTED?",
+            "",
+            "Update solution viability:",
+            "  - Mark solutions with falsified CORE assumptions as ELIMINATED",
+            "  - Note which solutions gained credibility (verified strengths)",
+            "  - Note which solutions lost credibility (falsified claims)",
+            "",
+            "Check for EMERGENT solutions:",
+            "  - Do verified facts suggest an approach not previously considered?",
+            "  - Can surviving solutions be combined based on verified strengths?",
+        ],
+        [
+            "SOLUTIONS with updated status",
+            "SUPPORTED claims (with evidence)",
+            "CONTRADICTED claims (with specific contradictions)",
+            "UNTESTED claims",
+            "ELIMINATED solutions (if any, with reason)",
+            "EMERGENT solutions (if any)",
+        ],
+    )
+
+
+def get_final_step_guidance():
+    """Final step: Structured Trade-off Synthesis."""
+    return (
+        "Trade-off Synthesis",
+        [
+            "STRUCTURED SYNTHESIS:",
+            "",
+            "1. SURVIVING SOLUTIONS:",
+            "   List solutions NOT eliminated by falsified assumptions",
+            "",
+            "2. TRADE-OFF MATRIX (verified facts only):",
+            "   For each dimension that matters to THIS decision:",
+            "   - Measurable outcomes: 'A achieves X; B achieves Y (verified)'",
+            "   - Complexity/effort: 'A requires N; B requires M'",
+            "   - Risk profile: 'A fails when...; B fails when...'",
+            "   (Add dimensions specific to your problem)",
+            "",
+            "3. DECISION FRAMEWORK:",
+            "   'If [hard constraint] is paramount -> choose A because...'",
+            "   'If [other priority] matters more -> choose B because...'",
+            "   'If uncertain about [X] -> gather [specific data] first'",
+            "",
+            "4. RECOMMENDATION (if one solution dominates):",
+            "   State which solution and the single strongest reason",
+            "   Acknowledge what you're giving up by choosing it",
+        ],
+        [],  # No next step
+    )
+
+
+def get_guidance(step: int, total_steps: int):
+    """
+    Dispatch to appropriate guidance based on step number.
+
+    7-phase structure:
+      Step 1:      Decomposition
+      Step 2:      Generation (initial solutions)
+      Step 3:      Expansion (push for MORE solutions)
+      Step 4:      Critique (Self-Refine feedback)
+      Steps 5-N-2: Verification (factored, extra steps go here)
+      Step N-1:    Cross-check
+      Step N:      Synthesis
+    """
+    if step == 1:
+        return get_step_1_guidance()
+    if step == 2:
+        return get_step_2_guidance()
+    if step == 3:
+        return get_step_3_guidance()
+    if step == 4:
+        return get_step_4_guidance()
+    if step == total_steps:
+        return get_final_step_guidance()
+    if step == total_steps - 1:
+        return get_crosscheck_guidance()
+    # Steps 5 to N-2 are verification
+    return get_verification_guidance()
+
+
+def format_output(step: int, total_steps: int, thoughts: str) -> str:
+    """Format output for display."""
+    title, actions, next_state = get_guidance(step, total_steps)
+    is_complete = step >= total_steps
+
+    lines = [
+        "=" * 70,
+        f"PROBLEM ANALYSIS - Step {step}/{total_steps}: {title}",
+        "=" * 70,
+        "",
+        "ACCUMULATED STATE:",
+        thoughts[:1200] + "..." if len(thoughts) > 1200 else thoughts,
+        "",
+        "ACTIONS:",
+    ]
+    lines.extend(f"  {action}" for action in actions)
+
+    if not is_complete and next_state:
+        lines.append("")
+        lines.append("NEXT STEP STATE MUST INCLUDE:")
+        lines.extend(f"  - {item}" for item in next_state)
+
+    lines.append("")
+
+    if is_complete:
+        lines.extend([
+            "COMPLETE - Present to user:",
+            "  1. Problem and constraints (from decomposition)",
+            "  2. Solutions considered (including eliminated ones and why)",
+            "  3. Verified facts (from factored verification)",
+            "  4. Trade-off matrix with decision framework",
+            "  5. Recommendation (if one dominates) or decision criteria",
+        ])
+    else:
+        next_title, _, _ = get_guidance(step + 1, total_steps)
+        lines.extend([
+            f"NEXT: Step {step + 1} - {next_title}",
+            f"REMAINING: {total_steps - step} step(s)",
+            "",
+            "ADJUST: increase --total-steps if more verification needed (min 7)",
+        ])
+
+    lines.extend(["", "=" * 70])
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Problem Analysis - Structured deep reasoning",
+        epilog=(
+            "Phases: decompose (1) -> generate (2) -> expand (3) -> "
+            "critique (4) -> verify (5 to N-2) -> cross-check (N-1) -> synthesize (N)"
+        ),
+    )
+    parser.add_argument("--step", type=int, required=True)
+    parser.add_argument("--total-steps", type=int, required=True)
+    parser.add_argument("--thoughts", type=str, required=True)
+    args = parser.parse_args()
+
+    if args.step < 1:
+        sys.exit("ERROR: --step must be >= 1")
+    if args.total_steps < 7:
+        sys.exit("ERROR: --total-steps must be >= 7 (requires 7 phases)")
+    if args.step > args.total_steps:
+        sys.exit("ERROR: --step cannot exceed --total-steps")
+
+    print(format_output(args.step, args.total_steps, args.thoughts))
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/prompt-engineer/CLAUDE.md

@@ -0,0 +1,21 @@
+# skills/prompt-engineer/
+
+## Overview
+
+Prompt optimization skill using research-backed techniques. IMMEDIATELY invoke
+the script - do NOT explore or analyze first.
+
+## Index
+
+| File/Directory                                 | Contents               | Read When          |
+| ---------------------------------------------- | ---------------------- | ------------------ |
+| `SKILL.md`                                     | Invocation             | Using this skill   |
+| `scripts/optimize.py`                          | Complete workflow      | Debugging behavior |
+| `references/prompt-engineering-single-turn.md` | Single-turn techniques | Script instructs   |
+| `references/prompt-engineering-multi-turn.md`  | Multi-turn techniques  | Script instructs   |
+
+## Key Point
+
+The script IS the workflow. It handles triage, blind problem identification,
+planning, factored verification, feedback, refinement, and integration. Do NOT
+analyze before invoking. Run the script and obey its output.

.claude/skills/prompt-engineer/README.md

@@ -0,0 +1,149 @@
+# Prompt Engineer
+
+Prompts are code. They have bugs, edge cases, and failure modes. This skill
+treats prompt optimization as a systematic discipline -- analyzing issues,
+applying documented patterns, and proposing changes with explicit rationale.
+
+I use this on my own workflow. The skill was optimized using itself -- of
+course.
+
+## When to Use
+
+- A sub-agent definition that misbehaves (agents/developer.md)
+- A Python script with embedded prompts that underperform
+  (skills/planner/scripts/planner.py)
+- A multi-prompt workflow that produces inconsistent results
+- Any prompt that does not do what you intended
+
+## How It Works
+
+The skill:
+
+1. Reads prompt engineering pattern references
+2. Analyzes the target prompt for issues
+3. Proposes changes with explicit pattern attribution
+4. Waits for approval before applying changes
+5. Presents optimized result with self-verification
+
+I use recitation and careful output ordering to ground the skill in the
+referenced patterns. This prevents the model from inventing techniques.
+
+## Example Usage
+
+Optimize a sub-agent:
+
+```
+Use your prompt engineer skill to optimize the system prompt for
+the following claude code sub-agent: agents/developer.md
+```
+
+Optimize a multi-prompt workflow:
+
+```
+Consider @skills/planner/scripts/planner.py. Identify all prompts,
+understand how they interact, then use your prompt engineer skill
+to optimize each.
+```
+
+## Example Output
+
+Each proposed change includes scope, problem, technique, before/after, and
+rationale. A single invocation may propose many changes:
+
+```
+  +==============================================================================+
+  |  CHANGE 1: Add STOP gate to Step 1 (Exploration)                             |
+  +==============================================================================+
+  |                                                                              |
+  |  SCOPE                                                                       |
+  |  -----                                                                       |
+  |  Prompt:      analyze.py step 1                                              |
+  |  Section:     Lines 41-49 (precondition check)                               |
+  |  Downstream:  All subsequent steps depend on exploration results             |
+  |                                                                              |
+  +------------------------------------------------------------------------------+
+  |                                                                              |
+  |  PROBLEM                                                                     |
+  |  -------                                                                     |
+  |  Issue:    Hedging language allows model to skip precondition                |
+  |                                                                              |
+  |  Evidence: "PRECONDITION: You should have already delegated..."              |
+  |            "If you have not, STOP and do that first"                         |
+  |                                                                              |
+  |  Runtime:  Model proceeds to "process exploration results" without having    |
+  |            any results, produces empty/fabricated structure analysis         |
+  |                                                                              |
+  +------------------------------------------------------------------------------+
+  |                                                                              |
+  |  TECHNIQUE                                                                   |
+  |  ---------                                                                   |
+  |  Apply:    STOP Escalation Pattern (single-turn ref)                         |
+  |                                                                              |
+  |  Trigger:  "For behaviors you need to interrupt, not just discourage"        |
+  |  Effect:   "Creates metacognitive checkpoint--the model must pause and       |
+  |             re-evaluate before proceeding"                                   |
+  |  Stacks:   Affirmative Directives                                            |
+  |                                                                              |
+  +------------------------------------------------------------------------------+
+  |                                                                              |
+  |  BEFORE                                                                      |
+  |  ------                                                                      |
+  |  +----------------------------------------------------------------------+    |
+  |  | "PRECONDITION: You should have already delegated to the Explore      |    |
+  |  |  sub-agent.",                                                        |    |
+  |  | "If you have not, STOP and do that first:",                          |    |
+  |  +----------------------------------------------------------------------+    |
+  |                                                                              |
+  |                                    |                                         |
+  |                                    v                                         |
+  |                                                                              |
+  |  AFTER                                                                       |
+  |  -----                                                                       |
+  |  +----------------------------------------------------------------------+    |
+  |  | "STOP. Before proceeding, verify you have Explore agent results.",   |    |
+  |  | "",                                                                  |    |
+  |  | "If your --thoughts do NOT contain Explore agent output, you MUST:", |    |
+  |  | "  1. Use Task tool with subagent_type='Explore'                     |    |
+  |  | "  2. Prompt: 'Explore this repository. Report directory structure,  |    |
+  |  | "     tech stack, entry points, main components, observed patterns.' |    |
+  |  | "  3. WAIT for results before invoking this step again               |    |
+  |  | "",                                                                  |    |
+  |  | "Only proceed below if you have concrete Explore output to process." |    |
+  |  +----------------------------------------------------------------------+    |
+  |                                                                              |
+  +------------------------------------------------------------------------------+
+  |                                                                              |
+  |  WHY THIS IMPROVES QUALITY                                                   |
+  |  -------------------------                                                   |
+  |  Transforms soft precondition into hard gate. Model must explicitly verify   |
+  |  it has Explore results before processing, preventing fabricated analysis.   |
+  |                                                                              |
+  +==============================================================================+
+
+  ... many more
+
+
+  ---
+  Compatibility check:
+  - STOP Escalation + Affirmative Directives: Compatible (STOP is for interrupting specific behaviors)
+  - History Accumulation + Completeness Checkpoint Tags: Synergistic (both enforce state tracking)
+  - Quote Extraction + Chain-of-Verification: Complementary (both prevent hallucination)
+  - Progressive depth + Pre-Work Context Analysis: Sequential (planning enables deeper execution)
+
+  Anti-patterns verified:
+  - No hedging spiral (replaced "should have" with "STOP. Verify...")
+  - No everything-is-critical (CRITICAL used only for state requirement)
+  - Affirmative directives used (changed negatives to positives)
+  - No implicit category trap (explicit checklists provided)
+
+  ---
+  Does this plan look reasonable? I'll apply these changes once you confirm.
+```
+
+## Caveat
+
+When you tell an LLM "find problems and opportunities for optimization", it will
+find problems. That is what you asked it to do. Some may not be real issues.
+
+I recommend invoking the skill multiple times on challenging prompts, but
+recognize when it is good enough and stop. Diminishing returns are real.

.claude/skills/prompt-engineer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: prompt-engineer
+description: Invoke IMMEDIATELY via python script when user requests prompt optimization. Do NOT analyze first - invoke this skill immediately.
+---
+
+# Prompt Engineer
+
+When this skill activates, IMMEDIATELY invoke the script. The script IS the
+workflow.
+
+## Invocation
+
+```bash
+python3 scripts/optimize.py \
+  --step 1 \
+  --total-steps 9 \
+  --thoughts "Prompt: <path or description>"
+```
+
+| Argument        | Required | Description                               |
+| --------------- | -------- | ----------------------------------------- |
+| `--step`        | Yes      | Current step (starts at 1)                |
+| `--total-steps` | Yes      | Minimum 9; adjust as script instructs     |
+| `--thoughts`    | Yes      | Accumulated state from all previous steps |
+
+Do NOT analyze or explore first. Run the script and follow its output.

.claude/skills/prompt-engineer/references/prompt-engineering-multi-turn.md

@@ -0,0 +1,790 @@
+# Prompt Engineering: Research-Backed Techniques for Multi-Turn Prompts
+
+This document synthesizes practical prompt engineering patterns with academic research on iterative LLM reasoning. All techniques target **multi-turn prompts**—structured sequences of messages where output from one turn becomes input to subsequent turns. These techniques leverage the observation that models can improve their own outputs through deliberate self-examination across multiple passes.
+
+**Prerequisite**: This guide assumes familiarity with single-turn techniques (CoT, Plan-and-Solve, RE2, etc.). Multi-turn techniques often enhance or extend single-turn methods across message boundaries.
+
+**Meta-principle**: The value of multi-turn prompting comes from separation of concerns—each turn has a distinct cognitive goal (generate, critique, verify, synthesize). Mixing these goals within a single turn reduces effectiveness.
+
+---
+
+## Technique Selection Guide
+
+| Domain              | Technique                  | Trigger Condition                                      | Stacks With                          | Conflicts With             | Cost/Tradeoff                                  | Effect                                                             |
+| ------------------- | -------------------------- | ------------------------------------------------------ | ------------------------------------ | -------------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
+| **Refinement**      | Self-Refine                | Output quality improvable through iteration            | Any single-turn reasoning technique  | Time-critical tasks        | 2-4x tokens per iteration                      | 5-40% absolute improvement across 7 task types                     |
+| **Refinement**      | Iterative Critique         | Specific quality dimensions need improvement           | Self-Refine, Format Strictness       | —                          | Moderate; targeted feedback reduces iterations | Monotonic improvement on scored dimensions                         |
+| **Verification**    | Chain-of-Verification      | Factual accuracy critical; hallucination risk          | Quote Extraction (single-turn)       | Joint verification         | 3-4x tokens (baseline + verify + revise)       | List-based QA: 17%→70% accuracy; FACTSCORE: 55.9→71.4              |
+| **Verification**    | Factored Verification      | High hallucination persistence in joint verification   | CoVe                                 | Joint CoVe                 | Additional token cost for separation           | Outperforms joint CoVe by 3-8 points across tasks                  |
+| **Aggregation**     | Universal Self-Consistency | Free-form output; standard SC inapplicable             | Any sampling technique               | Greedy decoding            | N samples + 1 selection call                   | Matches SC on math; enables SC for open-ended tasks                |
+| **Aggregation**     | Multi-Chain Reasoning      | Evidence scattered across reasoning attempts           | Self-Consistency, CoT                | Single-chain reliance      | N chains + 1 meta-reasoning call               | +5.7% over SC on multi-hop QA; high-quality explanations           |
+| **Aggregation**     | Complexity-Weighted Voting | Varying reasoning depth across samples                 | Self-Consistency, USC                | Simple majority voting     | Minimal; selection strategy only               | Further gains over standard SC (+2-3 points)                       |
+| **Meta-Reasoning**  | Chain Synthesis            | Multiple valid reasoning paths exist                   | MCR, USC                             | —                          | Moderate; synthesis pass                       | Combines complementary facts from different chains                 |
+| **Meta-Reasoning**  | Explanation Generation     | Interpretability required alongside answer             | MCR                                  | —                          | Included in meta-reasoning pass                | 82% of explanations rated high-quality                             |
+
+---
+
+## Quick Reference: Key Principles
+
+1. **Self-Refine for Iterative Improvement** — Feedback must be actionable ("use the formula n(n+1)/2") and specific ("the for loop is brute force"); vague feedback fails
+2. **Separate Feedback from Refinement** — Generate feedback in one turn, apply it in another; mixing degrades both
+3. **Factored Verification Beats Joint** — Answer verification questions without attending to the original response; prevents hallucination copying
+4. **Shortform Questions Beat Longform** — 70% accuracy on individual verification questions vs. 17% for the same facts in longform generation
+5. **Universal Self-Consistency for Free-Form** — When answers can't be exactly matched, ask the LLM to select the most consistent response
+6. **Multi-Chain Reasoning for Evidence Collection** — Use reasoning chains as evidence sources, not just answer votes
+7. **Meta-Reasoning Over Chains** — A second model pass that reads all chains produces better answers than majority voting
+8. **Complexity-Weighted Voting** — Vote over complex chains only; simple chains may reflect shortcuts
+9. **History Accumulation Helps** — Retain previous feedback and outputs in refinement prompts; models learn from past mistakes
+10. **Open Questions Beat Yes/No** — Verification questions expecting factual answers outperform yes/no format
+11. **Stopping Conditions Matter** — Use explicit quality thresholds or iteration limits; models rarely self-terminate optimally
+12. **Non-Monotonic Improvement Possible** — Multi-aspect tasks may improve on one dimension while regressing on another; track best-so-far
+
+---
+
+## 1. Iterative Refinement
+
+Techniques where the model critiques and improves its own output across multiple turns.
+
+### Self-Refine
+
+A general-purpose iterative improvement framework. Per Madaan et al. (2023): "SELF-REFINE: an iterative self-refinement algorithm that alternates between two generative steps—FEEDBACK and REFINE. These steps work in tandem to generate high-quality outputs."
+
+**The core loop:**
+
+```
+Turn 1 (Generate):
+  Input: Task description + prompt
+  Output: Initial response y₀
+
+Turn 2 (Feedback):
+  Input: Task + y₀ + feedback prompt
+  Output: Actionable, specific feedback fb₀
+
+Turn 3 (Refine):
+  Input: Task + y₀ + fb₀ + refine prompt
+  Output: Improved response y₁
+
+[Iterate until stopping condition]
+```
+
+**Critical quality requirements for feedback:**
+
+Per the paper: "By 'actionable', we mean the feedback should contain a concrete action that would likely improve the output. By 'specific', we mean the feedback should identify concrete phrases in the output to change."
+
+**CORRECT feedback (actionable + specific):**
+
+```
+This code is slow as it uses a for loop which is brute force.
+A better approach is to use the formula n(n+1)/2 instead of iterating.
+```
+
+**INCORRECT feedback (vague):**
+
+```
+The code could be more efficient. Consider optimizing it.
+```
+
+**History accumulation improves refinement:**
+
+The refinement prompt should include all previous iterations. Per the paper: "To inform the model about the previous iterations, we retain the history of previous feedback and outputs by appending them to the prompt. Intuitively, this allows the model to learn from past mistakes and avoid repeating them."
+
+```
+Turn N (Refine with history):
+  Input: Task + y₀ + fb₀ + y₁ + fb₁ + ... + yₙ₋₁ + fbₙ₋₁
+  Output: Improved response yₙ
+```
+
+**Performance:** "SELF-REFINE outperforms direct generation from strong LLMs like GPT-3.5 and GPT-4 by 5-40% absolute improvement" across dialogue response generation, code optimization, code readability, math reasoning, sentiment reversal, acronym generation, and constrained generation.
+
+**When Self-Refine works best:**
+
+| Task Type                   | Improvement | Notes                                        |
+| --------------------------- | ----------- | -------------------------------------------- |
+| Code optimization           | +13%        | Clear optimization criteria                  |
+| Dialogue response           | +35-40%     | Multi-aspect quality (relevance, engagement) |
+| Constrained generation      | +20%        | Verifiable constraint satisfaction           |
+| Math reasoning (with oracle) | +4.8%      | Requires correctness signal                  |
+
+**Limitation — Non-monotonic improvement:**
+
+Per the paper: "For tasks with multi-aspect feedback like Acronym Generation, the output quality can fluctuate during the iterative process, improving on one aspect while losing out on another."
+
+**Mitigation:** Track scores across iterations; select the output with maximum total score, not necessarily the final output.
+
+---
+
+### Feedback Prompt Design
+
+The feedback prompt determines refinement quality. Key elements from Self-Refine experiments:
+
+**Structure:**
+
+```
+You are given [task description] and an output.
+
+Output: {previous_output}
+
+Provide feedback on this output. Your feedback should:
+1. Identify specific phrases or elements that need improvement
+2. Explain why they are problematic
+3. Suggest concrete actions to fix them
+
+Do not rewrite the output. Only provide feedback.
+
+Feedback:
+```
+
+**Why separation matters:** Combining feedback and rewriting in one turn degrades both. The model either produces shallow feedback to get to rewriting, or rewrites without fully analyzing problems.
+
+---
+
+### Refinement Prompt Design
+
+The refinement prompt applies feedback to produce improved output.
+
+**Structure:**
+
+```
+You are given [task description], a previous output, and feedback on that output.
+
+Previous output: {previous_output}
+
+Feedback: {feedback}
+
+Using this feedback, produce an improved version of the output.
+Address each point raised in the feedback.
+
+Improved output:
+```
+
+**With history (for iteration 2+):**
+
+```
+You are given [task description], your previous attempts, and feedback on each.
+
+Attempt 1: {y₀}
+Feedback 1: {fb₀}
+
+Attempt 2: {y₁}
+Feedback 2: {fb₁}
+
+Using all feedback, produce an improved version. Do not repeat previous mistakes.
+
+Improved output:
+```
+
+---
+
+### Stopping Conditions
+
+Self-Refine requires explicit stopping conditions. Options:
+
+1. **Fixed iterations:** Stop after N refinement cycles (typically 2-4)
+2. **Feedback-based:** Prompt the model to include a stop signal in feedback
+3. **Score-based:** Stop when quality score exceeds threshold
+4. **Diminishing returns:** Stop when improvement between iterations falls below threshold
+
+**Prompt for feedback-based stopping:**
+
+```
+Provide feedback on this output. If the output is satisfactory and needs no
+further improvement, respond with "NO_REFINEMENT_NEEDED" instead of feedback.
+
+Feedback:
+```
+
+**Warning:** Models often fail to self-terminate appropriately. Per Madaan et al.: fixed iteration limits are more reliable than self-assessed stopping.
+
+---
+
+## 2. Verification
+
+Techniques where the model fact-checks its own outputs through targeted questioning.
+
+### Chain-of-Verification (CoVe)
+
+A structured approach to reducing hallucination through self-verification. Per Dhuliawala et al. (2023): "Chain-of-Verification (CoVe) whereby the model first (i) drafts an initial response; then (ii) plans verification questions to fact-check its draft; (iii) answers those questions independently so the answers are not biased by other responses; and (iv) generates its final verified response."
+
+**The four-step process:**
+
+```
+Turn 1 (Baseline Response):
+  Input: Original query
+  Output: Initial response (may contain hallucinations)
+
+Turn 2 (Plan Verifications):
+  Input: Query + baseline response
+  Output: List of verification questions
+
+Turn 3 (Execute Verifications):
+  Input: Verification questions ONLY (not baseline response)
+  Output: Answers to each verification question
+
+Turn 4 (Final Verified Response):
+  Input: Query + baseline response + verification Q&A pairs
+  Output: Revised response incorporating verifications
+```
+
+**The critical insight — shortform beats longform:**
+
+Per the paper: "Shortform verification questions are more accurately answered than longform queries. In a longform response, LLMs are prone to generate a number of hallucinations. However, it can often be the case that the LLM itself would know these hallucinations are wrong if queried specifically for that individual fact, independent of the rest of the longform generation."
+
+**Quantitative evidence:**
+
+| Setting                       | Accuracy |
+| ----------------------------- | -------- |
+| Facts in longform generation  | ~17%     |
+| Same facts as individual Q&A  | ~70%     |
+
+The same model that hallucinates facts in context can correctly answer when asked directly. CoVe exploits this asymmetry.
+
+**Example from the paper:**
+
+```
+Query: Name some politicians who were born in NY, New York.
+
+Baseline Response (with hallucinations):
+1. Hillary Clinton - former secretary of state... [WRONG: born in Chicago]
+2. Donald Trump - former president... [CORRECT: born in Queens, NYC]
+3. Michael Bloomberg - former Mayor... [WRONG: born in Boston]
+
+Verification Questions:
+- Where was Hillary Clinton born?
+- Where was Donald Trump born?
+- Where was Michael Bloomberg born?
+
+Verification Answers:
+- Hillary Clinton was born in Chicago, Illinois
+- Donald Trump was born in Queens, New York City
+- Michael Bloomberg was born in Boston, Massachusetts
+
+Final Verified Response:
+1. Donald Trump - former president (born in Queens, NYC)
+2. Alexandria Ocasio-Cortez - Democratic representative (born in NYC)
+...
+```
+
+---
+
+### Factored vs. Joint Verification
+
+**The hallucination copying problem:**
+
+Per Dhuliawala et al.: "Models that attend to existing hallucinations in the context from their own generations tend to repeat the hallucinations."
+
+When verification questions are answered with the baseline response in context, the model tends to confirm its own hallucinations rather than correct them.
+
+**Joint verification (less effective):**
+
+```
+Turn 3 (Joint):
+  Input: Query + baseline response + verification questions
+  Output: All answers in one pass
+
+Problem: Model sees its original hallucinations and copies them
+```
+
+**Factored verification (more effective):**
+
+```
+Turn 3a: Answer Q1 independently (no baseline in context)
+Turn 3b: Answer Q2 independently (no baseline in context)
+Turn 3c: Answer Q3 independently (no baseline in context)
+...
+```
+
+**2-Step verification (middle ground):**
+
+```
+Turn 3a: Generate all verification answers (no baseline in context)
+Turn 3b: Cross-check answers against baseline, note inconsistencies
+```
+
+**Performance comparison (Wiki-Category task):**
+
+| Method          | Precision |
+| --------------- | --------- |
+| Baseline        | 0.13      |
+| Joint CoVe      | 0.15      |
+| 2-Step CoVe     | 0.19      |
+| Factored CoVe   | 0.22      |
+
+Factored verification consistently outperforms joint verification by preventing hallucination propagation.
+
+---
+
+### Verification Question Design
+
+**Open questions outperform yes/no:**
+
+Per the paper: "We find that yes/no type questions perform worse for the factored version of CoVe. Some anecdotal examples... find the model tends to agree with facts in a yes/no question format whether they are right or wrong."
+
+**CORRECT (open verification question):**
+
+```
+When did Texas secede from Mexico?
+→ Expected answer: 1836
+```
+
+**INCORRECT (yes/no verification question):**
+
+```
+Did Texas secede from Mexico in 1845?
+→ Model tends to agree regardless of correctness
+```
+
+**LLM-generated questions outperform heuristics:**
+
+Per the paper: "We compare the quality of these questions to heuristically constructed ones... Results show a reduced precision with rule-based verification questions."
+
+Let the model generate verification questions tailored to the specific response, rather than using templated questions.
+
+---
+
+### Factor+Revise for Complex Verification
+
+For longform generation, add an explicit cross-check step between verification and final response.
+
+**Structure:**
+
+```
+Turn 3 (Execute verifications): [as above]
+
+Turn 3.5 (Cross-check):
+  Input: Baseline response + verification Q&A pairs
+  Output: Explicit list of inconsistencies found
+
+Turn 4 (Final response):
+  Input: Baseline + verifications + inconsistency list
+  Output: Revised response
+```
+
+**Performance:** Factor+Revise achieves FACTSCORE 71.4 vs. 63.7 for factored-only, demonstrating that explicit reasoning about inconsistencies further improves accuracy.
+
+**Prompt for cross-check:**
+
+```
+Original passage: {baseline_excerpt}
+
+From another source:
+Q: {verification_question_1}
+A: {verification_answer_1}
+
+Q: {verification_question_2}
+A: {verification_answer_2}
+
+Identify any inconsistencies between the original passage and the verified facts.
+List each inconsistency explicitly.
+
+Inconsistencies:
+```
+
+---
+
+## 3. Aggregation and Consistency
+
+Techniques that sample multiple responses and select or synthesize the best output.
+
+### Universal Self-Consistency (USC)
+
+Extends self-consistency to free-form outputs where exact-match voting is impossible. Per Chen et al. (2023): "USC leverages LLMs themselves to select the most consistent answer among multiple candidates... USC eliminates the need of designing an answer extraction process, and is applicable to tasks with free-form answers."
+
+**The two-step process:**
+
+```
+Turn 1 (Sample):
+  Input: Query
+  Output: N responses sampled with temperature > 0
+  [y₁, y₂, ..., yₙ]
+
+Turn 2 (Select):
+  Input: Query + all N responses
+  Output: Index of most consistent response
+```
+
+**The selection prompt:**
+
+```
+I have generated the following responses to the question: {question}
+
+Response 0: {response_0}
+Response 1: {response_1}
+Response 2: {response_2}
+...
+
+Select the most consistent response based on majority consensus.
+The most consistent response is Response:
+```
+
+**Why this works:**
+
+Per the paper: "Although prior works show that LLMs sometimes have trouble evaluating the prediction correctness, empirically we observe that LLMs are generally able to examine the response consistency across multiple tasks."
+
+Assessing consistency is easier than assessing correctness. The model doesn't need to know the right answer—just which answers agree with each other most.
+
+**Performance:**
+
+| Task                    | Greedy | Random | USC   | Standard SC |
+| ----------------------- | ------ | ------ | ----- | ----------- |
+| GSM8K                   | 91.3   | 91.5   | 92.4  | 92.7        |
+| MATH                    | 34.2   | 34.3   | 37.6  | 37.5        |
+| TruthfulQA (free-form)  | 62.1   | 62.9   | 67.7  | N/A         |
+| SummScreen (free-form)  | 30.6   | 30.2   | 31.7  | N/A         |
+
+USC matches standard SC on structured tasks and enables consistency-based selection where SC cannot apply.
+
+**Robustness to ordering:**
+
+Per the paper: "The overall model performance remains similar with different response orders, suggesting the effect of response order is minimal." USC is not significantly affected by the order in which responses are presented.
+
+**Optimal sample count:**
+
+USC benefits from more samples up to a point, then plateaus or slightly degrades due to context length limitations. Per experiments: 8 samples is a reliable sweet spot balancing accuracy and cost.
+
+---
+
+### Multi-Chain Reasoning (MCR)
+
+Uses multiple reasoning chains as evidence sources, not just answer votes. Per Yoran et al. (2023): "Unlike prior work, sampled reasoning chains are used not for their predictions (as in SC) but as a means to collect pieces of evidence from multiple chains."
+
+**The key insight:**
+
+Self-Consistency discards the reasoning and only votes on answers. MCR preserves the reasoning and synthesizes facts across chains.
+
+**The three-step process:**
+
+```
+Turn 1 (Generate chains):
+  Input: Query
+  Output: N reasoning chains, each with intermediate steps
+  [chain₁, chain₂, ..., chainₙ]
+
+Turn 2 (Concatenate):
+  Combine all chains into unified multi-chain context
+
+Turn 3 (Meta-reason):
+  Input: Query + multi-chain context
+  Output: Final answer + explanation synthesizing evidence
+```
+
+**Why MCR outperforms SC:**
+
+Per the paper: "SC solely relies on the chains' answers... By contrast, MCR concatenates the intermediate steps from each chain into a unified context, which is passed, along with the original question, to a meta-reasoner model."
+
+**Example from the paper:**
+
+```
+Question: Did Brad Peyton need to know about seismology?
+
+Chain 1 (Answer: No):
+- Brad Peyton is a film director
+- What is seismology? Seismology is the study of earthquakes
+- Do film directors need to know about earthquakes? No
+
+Chain 2 (Answer: Yes):
+- Brad Peyton directed San Andreas
+- San Andreas is about a massive earthquake
+- [implicit: he needed to research the topic]
+
+Chain 3 (Answer: No):
+- Brad Peyton is a director, writer, and producer
+- What do film directors have to know? Many things
+- Is seismology one of them? No
+
+Self-Consistency vote: No (2-1)
+
+MCR meta-reasoning: Combines facts from all chains:
+- Brad Peyton is a film director (chain 1, 3)
+- He directed San Andreas (chain 2)
+- San Andreas is about a massive earthquake (chain 2)
+- Seismology is the study of earthquakes (chain 1)
+
+MCR answer: Yes (synthesizes that directing an earthquake film required seismology knowledge)
+```
+
+**Performance:**
+
+MCR outperforms SC by up to 5.7% on multi-hop QA datasets. Additionally: "MCR generates high quality explanations for over 82% of examples, while fewer than 3% are unhelpful."
+
+---
+
+### Complexity-Weighted Voting
+
+An extension to self-consistency that weights votes by reasoning complexity. Per Fu et al. (2023): "We propose complexity-based consistency, where instead of taking a majority vote among all generated chains, we vote over the top K complex chains."
+
+**The process:**
+
+```
+Turn 1 (Sample with CoT):
+  Generate N reasoning chains with answers
+
+Turn 2 (Rank by complexity):
+  Count reasoning steps in each chain
+  Select top K chains by step count
+
+Turn 3 (Vote):
+  Majority vote only among the K complex chains
+```
+
+**Why complexity matters:**
+
+Simple chains may reflect shortcuts or lucky guesses. Complex chains demonstrate thorough reasoning. Voting only over complex chains filters out low-effort responses.
+
+**Performance (GSM8K):**
+
+| Method                      | Accuracy |
+| --------------------------- | -------- |
+| Standard SC (all chains)    | 78.0     |
+| Complexity-weighted (top K) | 80.5     |
+
+**Implementation note:** This requires no additional LLM calls beyond standard SC—just post-processing to count steps and filter before voting.
+
+---
+
+## 4. Implementation Patterns
+
+### Conversation Structure Template
+
+A general template for multi-turn improvement:
+
+```
+SYSTEM: [Base system prompt with single-turn techniques]
+
+--- Turn 1: Initial Generation ---
+USER: [Task]
+ASSISTANT: [Initial output y₀]
+
+--- Turn 2: Analysis/Feedback ---
+USER: [Analysis prompt - critique, verify, or evaluate y₀]
+ASSISTANT: [Feedback, verification results, or evaluation]
+
+--- Turn 3: Refinement/Synthesis ---
+USER: [Refinement prompt incorporating Turn 2 output]
+ASSISTANT: [Improved output y₁]
+
+[Repeat Turns 2-3 as needed]
+
+--- Final Turn: Format/Extract ---
+USER: [Optional: extract final answer in required format]
+ASSISTANT: [Final formatted output]
+```
+
+### Context Management
+
+Multi-turn prompting accumulates context. Manage token limits by:
+
+1. **Summarize history:** After N iterations, summarize previous attempts rather than including full text
+2. **Keep recent + best:** Retain only the most recent iteration and the best-scoring previous output
+3. **Structured extraction:** Extract key points from feedback rather than full feedback text
+
+**Example (summarized history):**
+
+```
+Previous attempts summary:
+- Attempt 1: Failed due to [specific issue]
+- Attempt 2: Improved [aspect] but [remaining issue]
+- Attempt 3: Best so far, minor issue with [aspect]
+
+Latest attempt: [full text of y₃]
+
+Feedback on latest attempt:
+```
+
+---
+
+## 5. Anti-Patterns
+
+### The Mixed-Goal Turn
+
+**Anti-pattern:** Combining distinct cognitive operations in a single turn.
+
+```
+# PROBLEMATIC
+Generate a response, then critique it, then improve it.
+```
+
+Each operation deserves focused attention. The model may rush through critique to reach improvement, or improve without thorough analysis.
+
+```
+# BETTER
+Turn 1: Generate response
+Turn 2: Critique the response (output: feedback only)
+Turn 3: Improve based on feedback
+```
+
+### The Contaminated Context
+
+**Anti-pattern:** Including the original response when answering verification questions.
+
+Per Dhuliawala et al. (2023): "Models that attend to existing hallucinations in the context from their own generations tend to repeat the hallucinations."
+
+```
+# PROBLEMATIC
+Original response: [contains potential hallucinations]
+Verification question: Where was Hillary Clinton born?
+Answer:
+```
+
+The model will often confirm the hallucination from its original response.
+
+```
+# BETTER
+Verification question: Where was Hillary Clinton born?
+Answer:
+[Original response NOT in context]
+```
+
+Exclude the baseline response when executing verifications. Include it only in the final revision step.
+
+### The Yes/No Verification Trap
+
+**Anti-pattern:** Phrasing verification questions as yes/no confirmations.
+
+```
+# PROBLEMATIC
+Is it true that Michael Bloomberg was born in New York?
+```
+
+Per CoVe research: Models tend to agree with yes/no questions regardless of correctness.
+
+```
+# BETTER
+Where was Michael Bloomberg born?
+```
+
+Open questions expecting factual answers perform significantly better.
+
+### The Infinite Loop
+
+**Anti-pattern:** No explicit stopping condition for iterative refinement.
+
+```
+# PROBLEMATIC
+Keep improving until the output is perfect.
+```
+
+Models rarely self-terminate appropriately. "Perfect" is undefined.
+
+```
+# BETTER
+Improve for exactly 3 iterations, then output the best version.
+
+# OR
+Improve until the quality score exceeds 8/10, maximum 5 iterations.
+```
+
+Always include explicit stopping criteria: iteration limits, quality thresholds, or both.
+
+### The Forgotten History
+
+**Anti-pattern:** Discarding previous iterations in refinement.
+
+```
+# PROBLEMATIC
+Turn 3: Here is feedback. Improve the output.
+[No reference to previous attempts]
+```
+
+Per Madaan et al.: "Retaining the history of previous feedback and outputs... allows the model to learn from past mistakes and avoid repeating them."
+
+```
+# BETTER
+Turn 3:
+Previous attempts and feedback:
+- Attempt 1: [y₀] → Feedback: [fb₀]
+- Attempt 2: [y₁] → Feedback: [fb₁]
+
+Improve, avoiding previously identified issues:
+```
+
+### The Vague Feedback
+
+**Anti-pattern:** Feedback without actionable specifics.
+
+```
+# PROBLEMATIC
+The response could be improved. Some parts are unclear.
+```
+
+This feedback provides no guidance for refinement.
+
+```
+# BETTER
+The explanation of photosynthesis in paragraph 2 uses jargon ("electron
+transport chain") without definition. Add a brief explanation: "the process
+by which plants convert light energy into chemical energy through a series
+of protein complexes."
+```
+
+Feedback must identify specific elements AND suggest concrete improvements.
+
+### The Majority Fallacy
+
+**Anti-pattern:** Assuming majority vote is always correct.
+
+```
+# PROBLEMATIC
+3 out of 5 chains say the answer is X, so X is correct.
+```
+
+Per Fu et al.: Simple chains may reflect shortcuts. Per Yoran et al.: Intermediate reasoning contains useful information discarded by voting.
+
+```
+# BETTER
+Weight votes by reasoning complexity, or use MCR to synthesize
+evidence from all chains including minority answers.
+```
+
+---
+
+## 6. Technique Combinations
+
+Multi-turn techniques can be combined for compounding benefits.
+
+### Self-Refine + CoVe
+
+Apply verification after refinement to catch introduced errors:
+
+```
+Turn 1: Generate initial output
+Turn 2: Feedback
+Turn 3: Refine
+Turn 4: Plan verification questions for refined output
+Turn 5: Execute verifications (factored)
+Turn 6: Final verified output
+```
+
+### USC + Complexity Weighting
+
+Filter by complexity before consistency selection:
+
+```
+Turn 1: Sample N responses with reasoning
+Turn 2: Filter to top K by reasoning complexity
+Turn 3: Apply USC to select most consistent among K
+```
+
+### MCR + Self-Refine
+
+Use multi-chain evidence collection, then refine the synthesis:
+
+```
+Turn 1: Generate N reasoning chains
+Turn 2: Meta-reason to synthesize evidence and produce answer
+Turn 3: Feedback on synthesis
+Turn 4: Refine synthesis
+```
+
+---
+
+## Research Citations
+
+- Chen, X., Aksitov, R., Alon, U., et al. (2023). "Universal Self-Consistency for Large Language Model Generation." arXiv.
+- Dhuliawala, S., Komeili, M., Xu, J., et al. (2023). "Chain-of-Verification Reduces Hallucination in Large Language Models." arXiv.
+- Diao, S., Wang, P., Lin, Y., & Zhang, T. (2023). "Active Prompting with Chain-of-Thought for Large Language Models." arXiv.
+- Fu, Y., Peng, H., Sabharwal, A., Clark, P., & Khot, T. (2023). "Complexity-Based Prompting for Multi-Step Reasoning." arXiv.
+- Madaan, A., Tandon, N., Gupta, P., et al. (2023). "Self-Refine: Iterative Refinement with Self-Feedback." arXiv.
+- Wang, X., Wei, J., Schuurmans, D., et al. (2023). "Self-Consistency Improves Chain of Thought Reasoning in Language Models." ICLR.
+- Yao, S., Yu, D., Zhao, J., et al. (2023). "Tree of Thoughts: Deliberate Problem Solving with Large Language Models." NeurIPS.
+- Yoran, O., Wolfson, T., Bogin, B., et al. (2023). "Answering Questions by Meta-Reasoning over Multiple Chains of Thought." arXiv.
+- Zhang, Y., Yuan, Y., & Yao, A. (2024). "Meta Prompting for AI Systems." arXiv.

.claude/skills/prompt-engineer/scripts/optimize.py

@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""
+Prompt Engineer Skill - Multi-turn prompt optimization workflow.
+
+Guides prompt optimization through nine phases:
+  1. Triage     - Assess complexity, route to lightweight or full process
+  2. Understand - Blind problem identification (NO references yet)
+  3. Plan       - Consult references, match techniques, generate visual cards
+  4. Verify     - Factored verification of FACTS (open questions, cross-check)
+  5. Feedback   - Generate actionable critique from verification results
+  6. Refine     - Apply feedback to update the plan
+  7. Approval   - Present refined plan to human, HARD GATE
+  8. Execute    - Apply approved changes to prompt
+  9. Integrate  - Coherence check, anti-pattern audit, quality verification
+
+Research grounding:
+  - Self-Refine (Madaan 2023): Separate feedback from refinement for 5-40%
+    improvement. Feedback must be "actionable and specific."
+  - CoVe (Dhuliawala 2023): Factored verification improves accuracy 17%->70%.
+    Use OPEN questions, not yes/no ("model tends to agree whether right or wrong")
+  - Factor+Revise: Explicit cross-check achieves +7.7 FACTSCORE points over
+    factored verification alone.
+  - Separation of Concerns: "Each turn has a distinct cognitive goal. Mixing
+    these goals within a single turn reduces effectiveness."
+
+Usage:
+    python3 optimize.py --step 1 --total-steps 9 --thoughts "Prompt: agents/developer.md"
+"""
+
+import argparse
+import sys
+
+
+def get_step_1_guidance():
+    """Step 1: Triage - Assess complexity and route appropriately."""
+    return {
+        "title": "Triage",
+        "actions": [
+            "Assess the prompt complexity:",
+            "",
+            "SIMPLE prompts (use lightweight 3-step process):",
+            "  - Under 20 lines",
+            "  - Single clear purpose (one tool, one behavior)",
+            "  - No conditional logic or branching",
+            "  - No inter-section dependencies",
+            "",
+            "COMPLEX prompts (use full 9-step process):",
+            "  - Multiple sections serving different functions",
+            "  - Conditional behaviors or rule hierarchies",
+            "  - Tool orchestration or multi-step workflows",
+            "  - Known failure modes that need addressing",
+            "",
+            "If SIMPLE: Note 'LIGHTWEIGHT' and proceed with abbreviated analysis",
+            "If COMPLEX: Note 'FULL PROCESS' and proceed to step 2",
+            "",
+            "Read the prompt file now. Do NOT read references yet.",
+        ],
+        "state_requirements": [
+            "PROMPT_PATH: path to the prompt being optimized",
+            "COMPLEXITY: SIMPLE or COMPLEX",
+            "PROMPT_SUMMARY: 2-3 sentences describing purpose",
+            "PROMPT_LENGTH: approximate line count",
+        ],
+    }
+
+
+def get_step_2_guidance():
+    """Step 2: Understand - Blind problem identification."""
+    return {
+        "title": "Understand (Blind)",
+        "actions": [
+            "CRITICAL: Do NOT read the reference documents yet.",
+            "This step uses BLIND problem identification to prevent pattern-shopping.",
+            "",
+            "Document the prompt's OPERATING CONTEXT:",
+            "  - Interaction model: single-shot or conversational?",
+            "  - Agent type: tool-use, coding, analysis, or general?",
+            "  - Token constraints: brevity critical or thoroughness preferred?",
+            "  - Failure modes: what goes wrong when this prompt fails?",
+            "",
+            "Identify PROBLEMS by examining the prompt text directly:",
+            "  - Quote specific problematic text with line numbers",
+            "  - Describe what's wrong in concrete terms",
+            "  - Note observable symptoms (not guessed causes)",
+            "",
+            "Examples of observable problems:",
+            "  'Lines 12-15 use hedging language: \"might want to\", \"could try\"'",
+            "  'No examples provided for expected output format'",
+            "  'Multiple rules marked CRITICAL with no clear precedence'",
+            "  'Instructions say what NOT to do but not what TO do'",
+            "",
+            "List at least 3 specific problems with quoted evidence.",
+        ],
+        "state_requirements": [
+            "OPERATING_CONTEXT: interaction model, agent type, constraints",
+            "PROBLEMS: list of specific issues with QUOTED text from prompt",
+            "Each problem must have: line reference, quoted text, description",
+        ],
+    }
+
+
+def get_step_3_guidance():
+    """Step 3: Plan - Consult references, match techniques."""
+    return {
+        "title": "Plan",
+        "actions": [
+            "NOW read the reference documents:",
+            "  - references/prompt-engineering-single-turn.md (always)",
+            "  - references/prompt-engineering-multi-turn.md (if multi-turn prompt)",
+            "",
+            "For EACH problem identified in Step 2:",
+            "",
+            "1. Locate a matching technique in the reference",
+            "2. QUOTE the trigger condition from the Technique Selection Guide",
+            "3. QUOTE the expected effect",
+            "4. Note stacking compatibility and conflicts",
+            "5. Draft the BEFORE/AFTER transformation",
+            "",
+            "Format each proposed change as a visual card:",
+            "",
+            "  CHANGE N: [title]",
+            "  PROBLEM: [quoted text from prompt]",
+            "  TECHNIQUE: [name]",
+            "  TRIGGER: \"[quoted from reference]\"",
+            "  EFFECT: \"[quoted from reference]\"",
+            "  BEFORE: [original prompt text]",
+            "  AFTER: [modified prompt text]",
+            "",
+            "If you cannot quote a trigger condition that matches, do NOT apply.",
+        ],
+        "state_requirements": [
+            "PROBLEMS: (from step 2)",
+            "PROPOSED_CHANGES: list of visual cards, each with:",
+            "  - Problem quoted from prompt",
+            "  - Technique name",
+            "  - Trigger condition QUOTED from reference",
+            "  - Effect QUOTED from reference",
+            "  - BEFORE/AFTER text",
+            "STACKING_NOTES: compatibility between proposed techniques",
+        ],
+    }
+
+
+def get_step_4_guidance():
+    """Step 4: Verify - Factored verification of facts."""
+    return {
+        "title": "Verify (Factored)",
+        "actions": [
+            "FACTORED VERIFICATION: Answer questions WITHOUT seeing your proposals.",
+            "",
+            "For EACH proposed technique, generate OPEN verification questions:",
+            "",
+            "  WRONG (yes/no): 'Is Affirmative Directives applicable here?'",
+            "  RIGHT (open):   'What is the trigger condition for Affirmative Directives?'",
+            "",
+            "  WRONG (yes/no): 'Does the prompt have hedging language?'",
+            "  RIGHT (open):   'What hedging phrases appear in lines 10-20?'",
+            "",
+            "Answer each question INDEPENDENTLY:",
+            "  - Pretend you have NOT seen your proposals",
+            "  - Answer from the reference or prompt text directly",
+            "  - Do NOT defend your choices; seek truth",
+            "",
+            "Then CROSS-CHECK: Compare answers to your claims:",
+            "",
+            "  TECHNIQUE: [name]",
+            "  CLAIMED TRIGGER: \"[what you quoted in step 3]\"",
+            "  VERIFIED TRIGGER: \"[what the reference actually says]\"",
+            "  MATCH: CONSISTENT / INCONSISTENT / PARTIAL",
+            "",
+            "  CLAIMED PROBLEM: \"[quoted prompt text in step 3]\"",
+            "  VERIFIED TEXT: \"[what the prompt actually says at that line]\"",
+            "  MATCH: CONSISTENT / INCONSISTENT / PARTIAL",
+        ],
+        "state_requirements": [
+            "VERIFICATION_QS: open questions for each technique",
+            "VERIFICATION_ANSWERS: factored answers (without seeing proposals)",
+            "CROSS_CHECK: for each technique:",
+            "  - Claimed vs verified trigger condition",
+            "  - Claimed vs verified prompt text",
+            "  - Match status: CONSISTENT / INCONSISTENT / PARTIAL",
+        ],
+    }
+
+
+def get_step_5_guidance():
+    """Step 5: Feedback - Generate actionable critique."""
+    return {
+        "title": "Feedback",
+        "actions": [
+            "Generate FEEDBACK based on verification results.",
+            "",
+            "Self-Refine research requires feedback to be:",
+            "  - ACTIONABLE: contains concrete action to improve",
+            "  - SPECIFIC: identifies concrete phrases to change",
+            "",
+            "WRONG (vague): 'The technique selection could be improved.'",
+            "RIGHT (actionable): 'Change 3 claims Affirmative Directives but the",
+            "  prompt text at line 15 is already affirmative. Remove this change.'",
+            "",
+            "For each INCONSISTENT or PARTIAL match from Step 4:",
+            "",
+            "  ISSUE: [specific problem from cross-check]",
+            "  ACTION: [concrete fix]",
+            "    - Replace technique with [alternative]",
+            "    - Modify BEFORE/AFTER to [specific change]",
+            "    - Remove change entirely because [reason]",
+            "",
+            "For CONSISTENT matches: Note 'VERIFIED - no changes needed'",
+            "",
+            "Do NOT apply feedback yet. Only generate critique.",
+        ],
+        "state_requirements": [
+            "CROSS_CHECK: (from step 4)",
+            "FEEDBACK: for each proposed change:",
+            "  - STATUS: VERIFIED / NEEDS_REVISION / REMOVE",
+            "  - If NEEDS_REVISION: specific actionable fix",
+            "  - If REMOVE: reason for removal",
+        ],
+    }
+
+
+def get_step_6_guidance():
+    """Step 6: Refine - Apply feedback to update plan."""
+    return {
+        "title": "Refine",
+        "actions": [
+            "Apply the feedback from Step 5 to update your proposed changes.",
+            "",
+            "For each change marked VERIFIED: Keep unchanged",
+            "",
+            "For each change marked NEEDS_REVISION:",
+            "  - Apply the specific fix from feedback",
+            "  - Update the BEFORE/AFTER text",
+            "  - Verify the trigger condition still matches",
+            "",
+            "For each change marked REMOVE: Delete from proposal",
+            "",
+            "After applying all feedback, verify:",
+            "  - No stacking conflicts between remaining techniques",
+            "  - All BEFORE/AFTER transformations are consistent",
+            "  - No duplicate or overlapping changes",
+            "",
+            "Produce the REFINED PLAN ready for human approval.",
+        ],
+        "state_requirements": [
+            "REFINED_CHANGES: updated list of visual cards",
+            "CHANGES_MADE: what was revised or removed and why",
+            "FINAL_STACKING_CHECK: confirm no conflicts",
+        ],
+    }
+
+
+def get_step_7_guidance():
+    """Step 7: Approval - Present to human, hard gate."""
+    return {
+        "title": "Approval Gate",
+        "actions": [
+            "Present the REFINED PLAN to the user for approval.",
+            "",
+            "Format:",
+            "",
+            "  ## Proposed Changes",
+            "",
+            "  [Visual cards for each change]",
+            "",
+            "  ## Verification Summary",
+            "  - [N] changes verified against reference",
+            "  - [M] changes revised based on verification",
+            "  - [K] changes removed (did not match trigger conditions)",
+            "",
+            "  ## Compatibility",
+            "  - [Note stacking synergies]",
+            "  - [Note any resolved conflicts]",
+            "",
+            "  ## Anti-Patterns Checked",
+            "  - Hedging Spiral: [checked/found/none]",
+            "  - Everything-Is-Critical: [checked/found/none]",
+            "  - Negative Instruction Trap: [checked/found/none]",
+            "",
+            "  ---",
+            "  Does this plan look reasonable? Confirm to proceed with execution.",
+            "",
+            "HARD GATE: Do NOT proceed to Step 8 without explicit user approval.",
+        ],
+        "state_requirements": [
+            "REFINED_CHANGES: (from step 6)",
+            "APPROVAL_PRESENTATION: formatted summary for user",
+            "USER_APPROVAL: must be obtained before step 8",
+        ],
+    }
+
+
+def get_step_8_guidance():
+    """Step 8: Execute - Apply approved changes."""
+    return {
+        "title": "Execute",
+        "actions": [
+            "Apply the approved changes to the prompt.",
+            "",
+            "Work through changes in logical order (by prompt section).",
+            "",
+            "For each approved change:",
+            "  1. Locate the target text in the prompt",
+            "  2. Apply the BEFORE -> AFTER transformation",
+            "  3. Verify the modification matches what was approved",
+            "",
+            "No additional approval needed per change - plan was approved in Step 7.",
+            "",
+            "If a conflict is discovered during execution:",
+            "  - STOP and present the conflict to user",
+            "  - Wait for resolution before continuing",
+            "",
+            "After all changes applied, proceed to integration.",
+        ],
+        "state_requirements": [
+            "APPROVED_CHANGES: (from step 7)",
+            "APPLIED_CHANGES: list of what was modified",
+            "EXECUTION_NOTES: any issues encountered",
+        ],
+    }
+
+
+def get_step_9_guidance():
+    """Step 9: Integrate - Coherence and quality verification."""
+    return {
+        "title": "Integrate",
+        "actions": [
+            "Verify the optimized prompt holistically.",
+            "",
+            "COHERENCE CHECKS:",
+            "  - Cross-section references: do sections reference each other correctly?",
+            "  - Terminology consistency: same terms throughout?",
+            "  - Priority consistency: do multiple sections align on priorities?",
+            "  - Flow and ordering: logical progression?",
+            "",
+            "EMPHASIS AUDIT:",
+            "  - Count CRITICAL, IMPORTANT, NEVER, ALWAYS markers",
+            "  - If more than 2-3 highest-level markers, reconsider",
+            "",
+            "ANTI-PATTERN FINAL CHECK:",
+            "  - Hedging Spiral: accumulated uncertainty language?",
+            "  - Everything-Is-Critical: overuse of emphasis?",
+            "  - Negative Instruction Trap: 'don't' instead of 'do'?",
+            "  - Implicit Category Trap: examples without principles?",
+            "",
+            "QUALITY VERIFICATION (open questions):",
+            "  - 'What behavior will this produce in edge cases?'",
+            "  - 'How would an agent interpret this if skimming?'",
+            "  - 'What could go wrong with this phrasing?'",
+            "",
+            "Present the final optimized prompt with summary of changes.",
+        ],
+        "state_requirements": [],  # Final step
+    }
+
+
+def get_guidance(step: int, total_steps: int):
+    """Dispatch to appropriate guidance based on step number."""
+    guidance_map = {
+        1: get_step_1_guidance,
+        2: get_step_2_guidance,
+        3: get_step_3_guidance,
+        4: get_step_4_guidance,
+        5: get_step_5_guidance,
+        6: get_step_6_guidance,
+        7: get_step_7_guidance,
+        8: get_step_8_guidance,
+        9: get_step_9_guidance,
+    }
+
+    if step in guidance_map:
+        return guidance_map[step]()
+
+    # Extra steps beyond 9 continue integration/verification
+    return get_step_9_guidance()
+
+
+def format_output(step: int, total_steps: int, thoughts: str) -> str:
+    """Format output for display."""
+    guidance = get_guidance(step, total_steps)
+    is_complete = step >= total_steps
+
+    lines = [
+        "=" * 70,
+        f"PROMPT ENGINEER - Step {step}/{total_steps}: {guidance['title']}",
+        "=" * 70,
+        "",
+        "ACCUMULATED STATE:",
+        thoughts[:1200] + "..." if len(thoughts) > 1200 else thoughts,
+        "",
+        "ACTIONS:",
+    ]
+    lines.extend(f"  {action}" for action in guidance["actions"])
+
+    state_reqs = guidance.get("state_requirements", [])
+    if not is_complete and state_reqs:
+        lines.append("")
+        lines.append("NEXT STEP STATE MUST INCLUDE:")
+        lines.extend(f"  - {item}" for item in state_reqs)
+
+    lines.append("")
+
+    if is_complete:
+        lines.extend([
+            "COMPLETE - Present to user:",
+            "  1. Summary of optimization process",
+            "  2. Techniques applied with reference sections",
+            "  3. Quality improvements (top 3)",
+            "  4. What was preserved from original",
+            "  5. Final optimized prompt",
+        ])
+    else:
+        next_guidance = get_guidance(step + 1, total_steps)
+        lines.extend([
+            f"NEXT: Step {step + 1} - {next_guidance['title']}",
+            f"REMAINING: {total_steps - step} step(s)",
+            "",
+            "ADJUST: increase --total-steps if more verification needed (min 9)",
+        ])
+
+    lines.extend(["", "=" * 70])
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Prompt Engineer - Multi-turn optimization workflow",
+        epilog=(
+            "Phases: triage (1) -> understand (2) -> plan (3) -> "
+            "verify (4) -> feedback (5) -> refine (6) -> "
+            "approval (7) -> execute (8) -> integrate (9)"
+        ),
+    )
+    parser.add_argument("--step", type=int, required=True)
+    parser.add_argument("--total-steps", type=int, required=True)
+    parser.add_argument("--thoughts", type=str, required=True)
+    args = parser.parse_args()
+
+    if args.step < 1:
+        sys.exit("ERROR: --step must be >= 1")
+    if args.total_steps < 9:
+        sys.exit("ERROR: --total-steps must be >= 9 (requires 9 phases)")
+    if args.step > args.total_steps:
+        sys.exit("ERROR: --step cannot exceed --total-steps")
+
+    print(format_output(args.step, args.total_steps, args.thoughts))
+
+
+if __name__ == "__main__":
+    main()

.claude/tdd-guard/data/test.json

@@ -0,0 +1,23 @@
+{
+  "testModules": [
+    {
+      "moduleId": "/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/dashboard/components/__tests__/ActionBar.test.tsx",
+      "tests": [
+        {
+          "name": "Module failed to load (Error)",
+          "fullName": "Module failed to load (Error)",
+          "state": "failed",
+          "errors": [
+            {
+              "message": "File not found: tsconfig.json (resolved as: /Users/egullickson/Documents/Technology/coding/motovaultpro/tsconfig.json)",
+              "name": "Error",
+              "stack": "Error: File not found: tsconfig.json (resolved as: /Users/egullickson/Documents/Technology/coding/motovaultpro/tsconfig.json)\n    at ConfigSet.resolvePath (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:616:19)\n    at ConfigSet._setupConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:322:71)\n    at new ConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:206:14)\n    at TsJestTransformer._createConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:119:16)\n    at TsJestTransformer._configsFor (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:98:34)\n    at TsJestTransformer.getCacheKey (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:249:30)\n    at ScriptTransformer._getCacheKey (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:195:41)\n    at ScriptTransformer._getFileCachePath (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:231:27)\n    at ScriptTransformer.transformSource (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:402:32)\n    at ScriptTransformer._transformAndBuildScript (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:519:40)\n    at ScriptTransformer.transform (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:558:19)\n    at Runtime.transformFile (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:1290:53)\n    at Runtime._execModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:1243:34)\n    at Runtime._loadModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:944:12)\n    at Runtime.requireModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:832:12)\n    at jestAdapter (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-circus/build/runner.js:84:33)\n    at processTicksAndRejections (node:internal/process/task_queues:104:5)\n    at runTestInternal (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runner/build/index.js:275:16)\n    at runTest (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runner/build/index.js:343:7)"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "unhandledErrors": [],
+  "reason": "failed"
+}

.env.example

@@ -0,0 +1,36 @@
+# MotoVaultPro Environment Configuration
+# Copy to .env and fill in environment-specific values
+# Generated .env files should NOT be committed to version control
+#
+# Local dev: No .env needed -- base docker-compose.yml defaults are sandbox values
+# Staging/Production: CI/CD generates .env from Gitea variables + generate-log-config.sh
+
+# ===========================================
+# Stripe Price IDs (environment-specific)
+# ===========================================
+# Sandbox defaults used for local development
+STRIPE_PRO_MONTHLY_PRICE_ID=price_1T1ZHMJXoKkh5RcKwKSSGIlR
+STRIPE_PRO_YEARLY_PRICE_ID=price_1T1ZHnJXoKkh5RcKWlG2MPpX
+STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_1T1ZIBJXoKkh5RcKu2jyhqBN
+STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_1T1ZIQJXoKkh5RcK34YXiJQm
+
+# ===========================================
+# Stripe Publishable Key (baked into frontend at build time)
+# ===========================================
+# VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# ===========================================
+# Log Levels (generated by scripts/ci/generate-log-config.sh)
+# ===========================================
+# Run: ./scripts/ci/generate-log-config.sh DEBUG >> .env
+#
+# BACKEND_LOG_LEVEL=debug
+# TRAEFIK_LOG_LEVEL=DEBUG
+# POSTGRES_LOG_STATEMENT=all
+# POSTGRES_LOG_MIN_DURATION=0
+# REDIS_LOGLEVEL=debug
+
+# ===========================================
+# Grafana
+# ===========================================
+# GRAFANA_ADMIN_PASSWORD=admin

.gitea/CLAUDE.md

@@ -0,0 +1,14 @@
+# .gitea/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `PULL_REQUEST_TEMPLATE.md` | PR template | Creating pull requests |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `workflows/` | CI/CD workflow definitions | Pipeline configuration |
+| `ISSUE_TEMPLATE/` | Issue templates (bug, feature, chore) | Creating issues |

.gitea/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,85 @@
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels:
+  - type/bug
+  - status/backlog
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Bug Report
+        Use this template to report bugs. Provide as much detail as possible to help reproduce the issue.
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      description: Where did you encounter this bug?
+      options:
+        - Mobile (iOS)
+        - Mobile (Android)
+        - Desktop (Chrome)
+        - Desktop (Firefox)
+        - Desktop (Safari)
+        - Desktop (Edge)
+        - Multiple platforms
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: What went wrong? Be specific.
+      placeholder: "When I click X, I expected Y to happen, but instead Z happened."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this bug?
+      placeholder: |
+        1. Navigate to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Screenshots, error messages, console logs, etc.
+    validations:
+      required: false
+
+  - type: textarea
+    id: fix-hints
+    attributes:
+      label: Fix Hints (if known)
+      description: Any ideas on what might be causing this or how to fix it?
+      placeholder: |
+        - Might be related to: [file or component]
+        - Similar issue in: [other feature]
+    validations:
+      required: false

.gitea/ISSUE_TEMPLATE/chore.yaml

@@ -0,0 +1,70 @@
+name: Chore / Maintenance
+about: Technical debt, refactoring, dependency updates, infrastructure
+title: "[Chore]: "
+labels:
+  - type/chore
+  - status/backlog
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Chore / Maintenance Task
+        Use this template for technical debt, refactoring, dependency updates, or infrastructure work.
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: What type of chore is this?
+      options:
+        - Refactoring
+        - Dependency update
+        - Performance optimization
+        - Technical debt cleanup
+        - Infrastructure / DevOps
+        - Testing improvements
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be done and why?
+      placeholder: "We need to refactor X because Y..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope / Files Affected
+      description: What parts of the codebase will be touched?
+      placeholder: |
+        - frontend/src/features/[name]/
+        - backend/src/features/[name]/
+        - docker-compose.yml
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Definition of Done
+      description: How do we know this is complete?
+      placeholder: |
+        - [ ] All tests pass
+        - [ ] No new linting errors
+        - [ ] Performance benchmark improved by X%
+    validations:
+      required: true
+
+  - type: textarea
+    id: risks
+    attributes:
+      label: Risks / Breaking Changes
+      description: Any potential issues or breaking changes to be aware of?
+    validations:
+      required: false

.gitea/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: "Docs / Architecture"
+    url: "https://<YOUR-DOCS-URL>"
+    about: "System design notes, decisions, and reference docs"

.gitea/ISSUE_TEMPLATE/feature.yaml

@@ -0,0 +1,137 @@
+name: Feature Request
+about: Propose a new feature for MotoVaultPro
+title: "[Feature]: "
+labels:
+  - type/feature
+  - status/backlog
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Feature Request
+        Use this template to propose new features. Be specific about requirements and integration points.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / User Need
+      description: What problem does this feature solve? Who needs it and why?
+      placeholder: "As a [user type], I want to [goal] so that [benefit]..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the feature and how it should work
+      placeholder: "When the user does X, the system should Y..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: non-goals
+    attributes:
+      label: Non-goals / Out of Scope
+      description: What is explicitly NOT part of this feature?
+      placeholder: |
+        - Advanced analytics (future enhancement)
+        - Data export functionality
+        - etc.
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria (Feature Behavior)
+      description: What must be true for this feature to be complete?
+      placeholder: |
+        - [ ] User can see X
+        - [ ] System displays Y when Z
+        - [ ] Works on mobile viewport (320px) with touch-friendly targets
+        - [ ] Works on desktop viewport (1920px) with keyboard navigation
+    validations:
+      required: true
+
+  - type: textarea
+    id: integration-criteria
+    attributes:
+      label: Integration Criteria (App Flow)
+      description: How does this feature integrate into the app? This prevents missed navigation/routing.
+      value: |
+        ### Navigation
+        - [ ] Desktop sidebar: [not needed / add as item #X / replace existing]
+        - [ ] Mobile bottom nav: [not needed / add to left/right items]
+        - [ ] Mobile hamburger menu: [not needed / add to menu items]
+
+        ### Routing
+        - [ ] Desktop route path: `/garage/[feature-name]`
+        - [ ] Is this the default landing page after login? [yes / no]
+        - [ ] Replaces existing placeholder/route: [none / specify what]
+
+        ### State Management
+        - [ ] Mobile screen type needed in navigation store? [yes / no]
+        - [ ] New Zustand store needed? [yes / no]
+    validations:
+      required: true
+
+  - type: textarea
+    id: visual-integration
+    attributes:
+      label: Visual Integration (Design Consistency)
+      description: Ensure the feature matches the app's visual language. Reference existing patterns.
+      value: |
+        ### Icons
+        - [ ] Use MUI Rounded icons only (e.g., `HomeRoundedIcon`, `DirectionsCarRoundedIcon`)
+        - [ ] Icon reference: Check `frontend/src/components/Layout.tsx` for existing icons
+        - [ ] No emoji icons in UI (text content only)
+
+        ### Colors
+        - [ ] Use theme colors via MUI sx prop: `color: 'primary.main'`, `bgcolor: 'background.paper'`
+        - [ ] No hardcoded hex colors (use Tailwind theme classes or MUI theme)
+        - [ ] Dark mode support: Use `dark:` Tailwind variants or MUI `theme.applyStyles('dark', ...)`
+
+        ### Components
+        - [ ] Use existing shared components: `GlassCard`, `Button`, `Input` from `shared-minimal/`
+        - [ ] Follow card patterns in: `frontend/src/features/vehicles/` or `frontend/src/features/fuel-logs/`
+        - [ ] Loading states: Use skeleton patterns from existing features
+
+        ### Typography & Spacing
+        - [ ] Use MUI Typography variants: `h4`, `h5`, `body1`, `body2`, `caption`
+        - [ ] Use consistent spacing: `gap-4`, `space-y-4`, `p-4` (multiples of 4)
+        - [ ] Mobile padding: `px-5 pt-5 pb-3` pattern from Layout.tsx
+    validations:
+      required: true
+
+  - type: textarea
+    id: implementation-notes
+    attributes:
+      label: Implementation Notes
+      description: Technical hints, existing patterns to follow, files to modify
+      placeholder: |
+        - Current placeholder: frontend/src/App.tsx lines X-Y
+        - Create new feature directory: frontend/src/features/[name]/
+        - Backend APIs already exist for X, Y, Z
+        - Follow pattern in: frontend/src/features/vehicles/
+    validations:
+      required: false
+
+  - type: textarea
+    id: test-plan
+    attributes:
+      label: Test Plan
+      description: How will this feature be tested?
+      placeholder: |
+        **Unit tests:**
+        - Component tests for X, Y, Z
+
+        **Integration tests:**
+        - Test data fetching with mocked API responses
+
+        **Manual testing:**
+        - Verify mobile layout at 320px, 768px viewports
+        - Verify desktop layout at 1920px viewport
+        - Test with 0 items, 1 item, 10+ items
+    validations:
+      required: false

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## Summary
+- What does this PR change?
+
+## Linked issues
+- Fixes #
+- Relates to #
+
+## Type
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Chore / refactor
+- [ ] Docs
+
+## Test plan
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Manual verification
+
+**Commands / steps:**
+1.
+2.
+
+## Screenshots / UI notes (if applicable)
+
+## Checklist
+- [ ] Acceptance criteria met (from linked issue)
+- [ ] No secrets committed
+- [ ] Logging is appropriate (no PII)
+- [ ] Docs updated (if needed)

.gitea/workflows/production.yaml

@@ -19,9 +19,11 @@ on:
 env:
   REGISTRY: git.motovaultpro.com
   DEPLOY_PATH: /opt/motovaultpro
-  COMPOSE_FILE: docker-compose.yml
+  BASE_COMPOSE_FILE: docker-compose.yml
   COMPOSE_BLUE_GREEN: docker-compose.blue-green.yml
-  HEALTH_CHECK_TIMEOUT: "60"
+  COMPOSE_PROD: docker-compose.prod.yml
+  HEALTH_CHECK_TIMEOUT: "240"
+  LOG_LEVEL: INFO
 
 jobs:
   # ============================================
@@ -34,6 +36,7 @@ jobs:
       target_stack: ${{ steps.determine-stack.outputs.target_stack }}
       backend_image: ${{ steps.set-images.outputs.backend_image }}
       frontend_image: ${{ steps.set-images.outputs.frontend_image }}
+      ocr_image: ${{ steps.set-images.outputs.ocr_image }}
     steps:
       - name: Check Docker availability
         run: |
@@ -53,6 +56,7 @@ jobs:
           TAG="${{ inputs.image_tag }}"
           echo "backend_image=$REGISTRY/egullickson/backend:$TAG" >> $GITHUB_OUTPUT
           echo "frontend_image=$REGISTRY/egullickson/frontend:$TAG" >> $GITHUB_OUTPUT
+          echo "ocr_image=$REGISTRY/egullickson/ocr:$TAG" >> $GITHUB_OUTPUT
 
       - name: Determine target stack
         id: determine-stack
@@ -83,6 +87,7 @@ jobs:
       TARGET_STACK: ${{ needs.validate.outputs.target_stack }}
       BACKEND_IMAGE: ${{ needs.validate.outputs.backend_image }}
       FRONTEND_IMAGE: ${{ needs.validate.outputs.frontend_image }}
+      OCR_IMAGE: ${{ needs.validate.outputs.ocr_image }}
     steps:
       - name: Checkout scripts, config, and compose files
         uses: actions/checkout@v4
@@ -90,8 +95,11 @@ jobs:
           sparse-checkout: |
             scripts/
             config/
+            secrets/app/google-wif-config.json
             docker-compose.yml
             docker-compose.blue-green.yml
+            docker-compose.prod.yml
+            .env.example
           sparse-checkout-cone-mode: false
           fetch-depth: 1
 
@@ -101,6 +109,27 @@ jobs:
           rsync -av --delete "$GITHUB_WORKSPACE/scripts/" "$DEPLOY_PATH/scripts/"
           cp "$GITHUB_WORKSPACE/docker-compose.yml" "$DEPLOY_PATH/"
           cp "$GITHUB_WORKSPACE/docker-compose.blue-green.yml" "$DEPLOY_PATH/"
+          cp "$GITHUB_WORKSPACE/docker-compose.prod.yml" "$DEPLOY_PATH/"
+          # WIF credential config (not a secret -- references Auth0 token script path)
+          # Remove any Docker-created directory artifact from failed bind mounts
+          rm -rf "$DEPLOY_PATH/secrets/app/google-wif-config.json"
+          mkdir -p "$DEPLOY_PATH/secrets/app"
+          cp "$GITHUB_WORKSPACE/secrets/app/google-wif-config.json" "$DEPLOY_PATH/secrets/app/"
+
+      - name: Generate environment configuration
+        run: |
+          cd "$DEPLOY_PATH"
+          {
+            echo "# Generated by CI/CD - DO NOT EDIT"
+            echo "STRIPE_PRO_MONTHLY_PRICE_ID=${{ vars.STRIPE_PRO_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_PRO_YEARLY_PRICE_ID=${{ vars.STRIPE_PRO_YEARLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_YEARLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_YEARLY_PRICE_ID }}"
+            echo "VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }}"
+            echo "GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}"
+          } > .env
+          chmod +x scripts/ci/generate-log-config.sh
+          ./scripts/ci/generate-log-config.sh "$LOG_LEVEL" >> .env
 
       - name: Login to registry
         run: |
@@ -108,17 +137,22 @@ jobs:
 
       - name: Inject secrets
         run: |
-          chmod +x "$GITHUB_WORKSPACE/scripts/inject-secrets.sh"
+          cd "$DEPLOY_PATH"
-          "$GITHUB_WORKSPACE/scripts/inject-secrets.sh"
+          chmod +x scripts/inject-secrets.sh
+          SECRETS_DIR="$DEPLOY_PATH/secrets/app" ./scripts/inject-secrets.sh
         env:
           POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
           AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
           AUTH0_MANAGEMENT_CLIENT_ID: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_ID }}
           AUTH0_MANAGEMENT_CLIENT_SECRET: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_SECRET }}
+          AUTH0_OCR_CLIENT_ID: ${{ secrets.AUTH0_OCR_CLIENT_ID }}
+          AUTH0_OCR_CLIENT_SECRET: ${{ secrets.AUTH0_OCR_CLIENT_SECRET }}
           GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
           GOOGLE_MAPS_MAP_ID: ${{ secrets.GOOGLE_MAPS_MAP_ID }}
           CF_DNS_API_TOKEN: ${{ secrets.CF_DNS_API_TOKEN }}
           RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+          STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}
 
       - name: Initialize data directories
         run: |
@@ -136,6 +170,7 @@ jobs:
         run: |
           docker pull $BACKEND_IMAGE
           docker pull $FRONTEND_IMAGE
+          docker pull $OCR_IMAGE
 
       - name: Record expected image IDs
         id: expected-images
@@ -148,18 +183,50 @@ jobs:
           echo "frontend_id=$FRONTEND_ID" >> $GITHUB_OUTPUT
           echo "backend_id=$BACKEND_ID" >> $GITHUB_OUTPUT
 
+      - name: Start shared services
+        run: |
+          cd "$DEPLOY_PATH"
+          # Start shared infrastructure services (database, cache, logging)
+          # --no-recreate prevents restarting postgres/redis when config files change
+          # These must persist across blue-green deployments to avoid data service disruption
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d --no-recreate \
+            mvp-postgres mvp-redis mvp-loki mvp-alloy mvp-grafana
+
+      - name: Wait for shared services health
+        run: |
+          echo "Waiting for PostgreSQL and Redis to be healthy..."
+          for service in mvp-postgres mvp-redis; do
+            for i in $(seq 1 24); do
+              health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
+              if [ "$health" = "healthy" ]; then
+                echo "OK: $service is healthy"
+                break
+              fi
+              if [ $i -eq 24 ]; then
+                echo "ERROR: $service health check timed out (status: $health)"
+                docker logs $service --tail 50 2>/dev/null || true
+                exit 1
+              fi
+              echo "Waiting for $service... (attempt $i/24, status: $health)"
+              sleep 5
+            done
+          done
+          echo "All shared services healthy"
+
       - name: Start target stack
         run: |
           cd "$DEPLOY_PATH"
           export BACKEND_IMAGE=$BACKEND_IMAGE
           export FRONTEND_IMAGE=$FRONTEND_IMAGE
+          export OCR_IMAGE=$OCR_IMAGE
           # --force-recreate ensures containers are recreated even if image tag is same
           # This prevents stale container content when image digest changes
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_BLUE_GREEN up -d --force-recreate \
+          # Start shared OCR service and target stack
-            mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d --force-recreate \
+            mvp-ocr mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK
 
       - name: Wait for stack initialization
-        run: sleep 10
+        run: sleep 5
 
       - name: Verify container images
         run: |
@@ -194,7 +261,7 @@ jobs:
       - name: Start Traefik
         run: |
           cd "$DEPLOY_PATH"
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_BLUE_GREEN up -d mvp-traefik
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d mvp-traefik
 
       - name: Wait for Traefik
         run: |
@@ -238,22 +305,79 @@ jobs:
       - name: Wait for routing propagation
         run: sleep 5
 
+      - name: Check container status and health
+        run: |
+          for service in mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK mvp-ocr; do
+            status=$(docker inspect --format='{{.State.Status}}' $service 2>/dev/null || echo "not found")
+            if [ "$status" != "running" ]; then
+              echo "ERROR: $service is not running (status: $status)"
+              docker logs $service --tail 50 2>/dev/null || true
+              exit 1
+            fi
+            echo "OK: $service is running"
+          done
+
+          # Wait for Docker healthchecks to complete (services with healthcheck defined)
+          echo ""
+          echo "Waiting for Docker healthchecks..."
+          for service in mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK mvp-ocr; do
+            # Check if service has a healthcheck defined
+            has_healthcheck=$(docker inspect --format='{{if .Config.Healthcheck}}true{{else}}false{{end}}' $service 2>/dev/null || echo "false")
+            if [ "$has_healthcheck" = "true" ]; then
+              # 48 attempts x 5 seconds = 4 minutes max wait (backend with fresh migrations can take ~3 min)
+              for i in $(seq 1 48); do
+                health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
+                if [ "$health" = "healthy" ]; then
+                  echo "OK: $service is healthy"
+                  break
+                fi
+                # Don't fail immediately on unhealthy - container may still be starting up
+                # and can recover. Let the timeout handle truly broken containers.
+                if [ $i -eq 48 ]; then
+                  echo "ERROR: $service health check timed out (status: $health)"
+                  docker logs $service --tail 100 2>/dev/null || true
+                  exit 1
+                fi
+                echo "Waiting for $service healthcheck... (attempt $i/48, status: $health)"
+                sleep 5
+              done
+            else
+              echo "SKIP: $service has no healthcheck defined"
+            fi
+          done
+
+      - name: Wait for backend health
+        run: |
+          for i in $(seq 1 12); do
+            if docker exec mvp-backend-$TARGET_STACK curl -sf http://localhost:3001/health > /dev/null 2>&1; then
+              echo "OK: Backend health check passed"
+              exit 0
+            fi
+            if [ $i -eq 12 ]; then
+              echo "ERROR: Backend health check failed after 12 attempts"
+              docker logs mvp-backend-$TARGET_STACK --tail 100
+              exit 1
+            fi
+            echo "Attempt $i/12: Backend not ready, waiting 5s..."
+            sleep 5
+          done
+
       - name: External health check
         run: |
           REQUIRED_FEATURES='["admin","auth","onboarding","vehicles","documents","fuel-logs","stations","maintenance","platform","notifications","user-profile","user-preferences","user-export"]'
 
-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
             RESPONSE=$(curl -sf https://motovaultpro.com/api/health 2>/dev/null) || {
-              echo "Attempt $i/6: Connection failed, waiting 10s..."
+              echo "Attempt $i/12: Connection failed, waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             }
 
             # Check status is "healthy"
             STATUS=$(echo "$RESPONSE" | jq -r '.status')
             if [ "$STATUS" != "healthy" ]; then
-              echo "Attempt $i/6: Status is '$STATUS', not 'healthy'. Waiting 10s..."
+              echo "Attempt $i/12: Status is '$STATUS', not 'healthy'. Waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             fi
 
@@ -263,8 +387,8 @@ jobs:
             ')
 
             if [ -n "$MISSING" ]; then
-              echo "Attempt $i/6: Missing features: $MISSING. Waiting 10s..."
+              echo "Attempt $i/12: Missing features: $MISSING. Waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             fi
 
@@ -273,7 +397,7 @@ jobs:
             exit 0
           done
 
-          echo "ERROR: Production health check failed after 6 attempts"
+          echo "ERROR: Production health check failed after 12 attempts"
           echo "Last response: $RESPONSE"
           exit 1
 

.gitea/workflows/staging.yaml

@@ -1,21 +1,24 @@
 # MotoVaultPro Staging Deployment Workflow
-# Triggers on push to main, builds and deploys to staging.motovaultpro.com
+# Triggers on push to main or any pull request, builds and deploys to staging.motovaultpro.com
 # After verification, sends notification with link to trigger production deploy
 
 name: Deploy to Staging
-run-name: Staging Deploy - ${{ gitea.sha }}
+run-name: "Staging - ${{ gitea.event.pull_request.title || gitea.ref_name }}"
 
 on:
   push:
     branches:
       - main
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 env:
   REGISTRY: git.motovaultpro.com
   DEPLOY_PATH: /opt/motovaultpro
-  COMPOSE_FILE: docker-compose.yml
+  BASE_COMPOSE_FILE: docker-compose.yml
-  COMPOSE_STAGING: docker-compose.staging.yml
+  STAGING_COMPOSE_FILE: docker-compose.staging.yml
   HEALTH_CHECK_TIMEOUT: "60"
+  LOG_LEVEL: DEBUG
 
 jobs:
   # ============================================
@@ -27,6 +30,7 @@ jobs:
     outputs:
       backend_image: ${{ steps.tags.outputs.backend_image }}
       frontend_image: ${{ steps.tags.outputs.frontend_image }}
+      ocr_image: ${{ steps.tags.outputs.ocr_image }}
       short_sha: ${{ steps.tags.outputs.short_sha }}
     steps:
       - name: Checkout code
@@ -43,6 +47,7 @@ jobs:
           SHORT_SHA="${SHORT_SHA:0:7}"
           echo "backend_image=$REGISTRY/egullickson/backend:$SHORT_SHA" >> $GITHUB_OUTPUT
           echo "frontend_image=$REGISTRY/egullickson/frontend:$SHORT_SHA" >> $GITHUB_OUTPUT
+          echo "ocr_image=$REGISTRY/egullickson/ocr:$SHORT_SHA" >> $GITHUB_OUTPUT
           echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT
 
       - name: Build backend image
@@ -65,18 +70,32 @@ jobs:
             --build-arg VITE_AUTH0_CLIENT_ID=${{ vars.VITE_AUTH0_CLIENT_ID }} \
             --build-arg VITE_AUTH0_AUDIENCE=${{ vars.VITE_AUTH0_AUDIENCE }} \
             --build-arg VITE_API_BASE_URL=/api \
+            --build-arg VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }} \
             --cache-from $REGISTRY/egullickson/frontend:latest \
             -t ${{ steps.tags.outputs.frontend_image }} \
             -t $REGISTRY/egullickson/frontend:latest \
             -f frontend/Dockerfile \
             frontend
 
+      - name: Build OCR image
+        run: |
+          docker build \
+            --build-arg BUILDKIT_INLINE_CACHE=1 \
+            --build-arg REGISTRY_MIRRORS=$REGISTRY/egullickson/mirrors \
+            --cache-from $REGISTRY/egullickson/ocr:latest \
+            -t ${{ steps.tags.outputs.ocr_image }} \
+            -t $REGISTRY/egullickson/ocr:latest \
+            -f ocr/Dockerfile \
+            ocr
+
       - name: Push images
         run: |
           docker push ${{ steps.tags.outputs.backend_image }}
           docker push ${{ steps.tags.outputs.frontend_image }}
+          docker push ${{ steps.tags.outputs.ocr_image }}
           docker push $REGISTRY/egullickson/backend:latest
           docker push $REGISTRY/egullickson/frontend:latest
+          docker push $REGISTRY/egullickson/ocr:latest
 
   # ============================================
   # DEPLOY STAGING - Deploy to staging server
@@ -88,10 +107,38 @@ jobs:
     env:
       BACKEND_IMAGE: ${{ needs.build.outputs.backend_image }}
       FRONTEND_IMAGE: ${{ needs.build.outputs.frontend_image }}
+      OCR_IMAGE: ${{ needs.build.outputs.ocr_image }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Sync config, scripts, and compose files to deploy path
+        run: |
+          rsync -av --delete "$GITHUB_WORKSPACE/config/" "$DEPLOY_PATH/config/"
+          rsync -av --delete "$GITHUB_WORKSPACE/scripts/" "$DEPLOY_PATH/scripts/"
+          cp "$GITHUB_WORKSPACE/docker-compose.yml" "$DEPLOY_PATH/"
+          cp "$GITHUB_WORKSPACE/docker-compose.staging.yml" "$DEPLOY_PATH/"
+          # WIF credential config (not a secret -- references Auth0 token script path)
+          # Remove any Docker-created directory artifact from failed bind mounts
+          rm -rf "$DEPLOY_PATH/secrets/app/google-wif-config.json"
+          mkdir -p "$DEPLOY_PATH/secrets/app"
+          cp "$GITHUB_WORKSPACE/secrets/app/google-wif-config.json" "$DEPLOY_PATH/secrets/app/"
+
+      - name: Generate environment configuration
+        run: |
+          cd "$DEPLOY_PATH"
+          {
+            echo "# Generated by CI/CD - DO NOT EDIT"
+            echo "STRIPE_PRO_MONTHLY_PRICE_ID=${{ vars.STRIPE_PRO_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_PRO_YEARLY_PRICE_ID=${{ vars.STRIPE_PRO_YEARLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_YEARLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_YEARLY_PRICE_ID }}"
+            echo "VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }}"
+            echo "GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}"
+          } > .env
+          chmod +x scripts/ci/generate-log-config.sh
+          ./scripts/ci/generate-log-config.sh "$LOG_LEVEL" >> .env
+
       - name: Login to registry
         run: |
           echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login -u "${{ secrets.REGISTRY_USER }}" --password-stdin "$REGISTRY"
@@ -106,10 +153,14 @@ jobs:
           AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
           AUTH0_MANAGEMENT_CLIENT_ID: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_ID }}
           AUTH0_MANAGEMENT_CLIENT_SECRET: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_SECRET }}
+          AUTH0_OCR_CLIENT_ID: ${{ secrets.AUTH0_OCR_CLIENT_ID }}
+          AUTH0_OCR_CLIENT_SECRET: ${{ secrets.AUTH0_OCR_CLIENT_SECRET }}
           GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
           GOOGLE_MAPS_MAP_ID: ${{ secrets.GOOGLE_MAPS_MAP_ID }}
           CF_DNS_API_TOKEN: ${{ secrets.CF_DNS_API_TOKEN }}
           RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+          STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}
 
       - name: Initialize data directories
         run: |
@@ -127,17 +178,19 @@ jobs:
         run: |
           docker pull $BACKEND_IMAGE
           docker pull $FRONTEND_IMAGE
+          docker pull $OCR_IMAGE
 
       - name: Deploy staging stack
         run: |
           cd "$DEPLOY_PATH"
           export BACKEND_IMAGE=$BACKEND_IMAGE
           export FRONTEND_IMAGE=$FRONTEND_IMAGE
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_STAGING down --timeout 30 || true
+          export OCR_IMAGE=$OCR_IMAGE
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_STAGING up -d
+          docker compose -f $BASE_COMPOSE_FILE -f $STAGING_COMPOSE_FILE down --timeout 30 || true
+          docker compose -f $BASE_COMPOSE_FILE -f $STAGING_COMPOSE_FILE up -d
 
       - name: Wait for services
-        run: sleep 15
+        run: sleep 5
 
   # ============================================
   # VERIFY STAGING - Health checks
@@ -152,7 +205,7 @@ jobs:
 
       - name: Check container status and health
         run: |
-          for service in mvp-frontend-staging mvp-backend-staging mvp-postgres-staging mvp-redis-staging; do
+          for service in mvp-frontend-staging mvp-backend-staging mvp-ocr-staging mvp-postgres-staging mvp-redis-staging; do
             status=$(docker inspect --format='{{.State.Status}}' $service 2>/dev/null || echo "not found")
             if [ "$status" != "running" ]; then
               echo "ERROR: $service is not running (status: $status)"
@@ -165,26 +218,25 @@ jobs:
           # Wait for Docker healthchecks to complete (services with healthcheck defined)
           echo ""
           echo "Waiting for Docker healthchecks..."
-          for service in mvp-frontend-staging mvp-backend-staging mvp-postgres-staging mvp-redis-staging; do
+          for service in mvp-frontend-staging mvp-backend-staging mvp-ocr-staging mvp-postgres-staging mvp-redis-staging; do
             # Check if service has a healthcheck defined
             has_healthcheck=$(docker inspect --format='{{if .Config.Healthcheck}}true{{else}}false{{end}}' $service 2>/dev/null || echo "false")
             if [ "$has_healthcheck" = "true" ]; then
-              for i in 1 2 3 4 5 6 7 8 9 10; do
+              # 48 attempts x 5 seconds = 4 minutes max wait (backend with fresh migrations can take ~3 min)
+              for i in $(seq 1 48); do
                 health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
                 if [ "$health" = "healthy" ]; then
                   echo "OK: $service is healthy"
                   break
-                elif [ "$health" = "unhealthy" ]; then
-                  echo "ERROR: $service is unhealthy"
-                  docker logs $service --tail 50 2>/dev/null || true
-                  exit 1
                 fi
-                if [ $i -eq 10 ]; then
+                # Don't fail immediately on unhealthy - container may still be starting up
+                # and can recover. Let the timeout handle truly broken containers.
+                if [ $i -eq 48 ]; then
                   echo "ERROR: $service health check timed out (status: $health)"
-                  docker logs $service --tail 50 2>/dev/null || true
+                  docker logs $service --tail 100 2>/dev/null || true
                   exit 1
                 fi
-                echo "Waiting for $service healthcheck... (attempt $i/10, status: $health)"
+                echo "Waiting for $service healthcheck... (attempt $i/48, status: $health)"
                 sleep 5
               done
             else
@@ -194,36 +246,36 @@ jobs:
 
       - name: Wait for backend health
         run: |
-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
             if docker exec mvp-backend-staging curl -sf http://localhost:3001/health > /dev/null 2>&1; then
               echo "OK: Backend health check passed"
               exit 0
             fi
-            if [ $i -eq 6 ]; then
+            if [ $i -eq 12 ]; then
-              echo "ERROR: Backend health check failed after 6 attempts"
+              echo "ERROR: Backend health check failed after 12 attempts"
               docker logs mvp-backend-staging --tail 100
               exit 1
             fi
-            echo "Attempt $i/6: Backend not ready, waiting 10s..."
+            echo "Attempt $i/12: Backend not ready, waiting 5s..."
-            sleep 10
+            sleep 5
           done
 
       - name: Check external endpoint
         run: |
           REQUIRED_FEATURES='["admin","auth","onboarding","vehicles","documents","fuel-logs","stations","maintenance","platform","notifications","user-profile","user-preferences","user-export"]'
 
-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
             RESPONSE=$(curl -sf https://staging.motovaultpro.com/api/health 2>/dev/null) || {
-              echo "Attempt $i/6: Connection failed, waiting 10s..."
+              echo "Attempt $i/12: Connection failed, waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             }
 
             # Check status is "healthy"
             STATUS=$(echo "$RESPONSE" | jq -r '.status')
             if [ "$STATUS" != "healthy" ]; then
-              echo "Attempt $i/6: Status is '$STATUS', not 'healthy'. Waiting 10s..."
+              echo "Attempt $i/12: Status is '$STATUS', not 'healthy'. Waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             fi
 
@@ -233,8 +285,8 @@ jobs:
             ')
 
             if [ -n "$MISSING" ]; then
-              echo "Attempt $i/6: Missing features: $MISSING. Waiting 10s..."
+              echo "Attempt $i/12: Missing features: $MISSING. Waiting 5s..."
-              sleep 10
+              sleep 5
               continue
             fi
 
@@ -243,7 +295,7 @@ jobs:
             exit 0
           done
 
-          echo "ERROR: Staging health check failed after 6 attempts"
+          echo "ERROR: Staging health check failed after 12 attempts"
           echo "Last response: $RESPONSE"
           exit 1
 

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 .env
 .env.local
 .env.backup
+.env.logging
 dist/
 *.log
 .DS_Store
@@ -12,12 +13,16 @@ coverage/
 *.swo
 .venv
 .playwright-mcp
+__pycache__/
+*.py[cod]
+*$py.class
 
 # K8s-aligned secret mounts (real files ignored; examples committed)
 secrets/**
 !secrets/
 !secrets/**/
 !secrets/**/*.example
+!secrets/app/google-wif-config.json
 
 # Traefik ACME certificates (contains private keys)
 data/traefik/acme.json

.mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "--env",
+        "GITEA_ACCESS_TOKEN=88f2ac07f148676a79ce413c7f5ca4912468c500",
+        "--env",
+        "GITEA_HOST=https://git.motovaultpro.com",
+        "docker.gitea.com/gitea-mcp-server"
+      ],
+      "env": {}
+    }
+  }
+}

AI-INDEX.md

@@ -1,22 +0,0 @@
-# MotoVaultPro AI Index
-
-- Load Order: `.ai/context.json`, then `docs/README.md`.
-- Architecture: Simplified 5-container stack (Traefik, Frontend, Backend, PostgreSQL, Redis) with platform feature integrated into backend.
-- Work Modes:
-  - Feature work: `backend/src/features/{feature}/` (start with `README.md`).
-- Commands (containers only):
-  - `make setup | start | rebuild | migrate | logs | logs-backend | logs-frontend`
-  - Shells: `make shell-backend` | `make shell-frontend`
-- Docs Hubs:
-  - Docs index: `docs/README.md`
-  - Testing: `docs/TESTING.md`
-  - Database: `docs/DATABASE-SCHEMA.md`
-  - Security: `docs/SECURITY.md`
-  - Vehicles API: `docs/VEHICLES-API.md`
-- Core Backend Modules: `backend/src/core/` (see `backend/src/core/README.md`).
-- Frontend Overview: `frontend/README.md`.
-- URLs and Hosts:
-  - Frontend: `https://motovaultpro.com`
-  - Backend health: `https://motovaultpro.com/api/health`
-  - Add to `/etc/hosts`: `127.0.0.1 motovaultpro.com`
-

CLAUDE.md

@@ -1,3 +1,54 @@
+# MotoVaultPro
+
+Single-tenant vehicle management application with 9-container architecture (6 application: Traefik, Frontend, Backend, OCR, PostgreSQL, Redis + 3 logging: Loki, Alloy, Grafana).
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `Makefile` | Build, test, deploy commands | Running any make command |
+| `docker-compose.yml` | Development container orchestration | Local development setup |
+| `docker-compose.staging.yml` | Staging container orchestration | Staging deployment |
+| `docker-compose.prod.yml` | Production container orchestration | Production deployment |
+| `docker-compose.blue-green.yml` | Blue-green deployment orchestration | Zero-downtime deploys |
+| `package.json` | Root workspace dependencies | Dependency management |
+| `README.md` | Project overview | First-time setup |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `backend/` | Fastify API server with feature capsules | Backend development |
+| `frontend/` | React/Vite SPA with MUI | Frontend development |
+| `ocr/` | Python OCR microservice (Tesseract) | OCR pipeline, receipt/VIN extraction |
+| `docs/` | Project documentation hub | Architecture, APIs, testing |
+| `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
+| `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks |
+| `.ai/` | AI context and workflow contracts | AI-assisted development |
+| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
+| `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
+| `ansible/` | Ansible deployment playbooks | Server provisioning |
+| `certs/` | TLS certificates | SSL/TLS configuration |
+| `secrets/` | Docker secrets (Stripe keys, Traefik) | Secret management |
+| `data/` | Persistent data volumes (backups, documents) | Storage paths, volume mounts |
+
+## Build for staging and production. NOT FOR DEVELOPMENT
+
+```bash
+make setup    # First-time setup 
+make rebuild  # Rebuild containers
+```
+
+## Test
+
+```bash
+npm test             # Run all tests
+npm run lint         # Linting
+npm run type-check   # TypeScript validation
+```
+
+---
+
 # Development Partnership Guidelines
 
 ## Core Development Principles
@@ -45,24 +96,23 @@ private mapRow(row: any): MyType {
 
 All methods returning data to the API must use these mappers - never return raw database rows.
 
-## Docker-First Implementation Strategy
+## Development Workflow (Local + CI/CD)
 
-### 1. Package.json Updates Only
+### Local Development
-File: `frontend/package.json`
-- Add `"{package}": "{version}"` to dependencies
-- No npm install needed - handled by container rebuild
-- Testing: Instruct user to rebuild the containers and report back build errors
-
-### 2. Container-Validated Development Workflow (Production-only)
 ```bash
-# After each change:
+npm install          # Install dependencies
-Instruct user to rebuild the containers and report back build errors
+npm run dev          # Start dev server
-make logs           # Monitor for build/runtime errors
+npm test             # Run tests
+npm run lint         # Linting
+npm run type-check   # TypeScript validation
 ```
 
-### 3. Docker-Tested Component Development (Production-only)
+### CI/CD Pipeline (on PR)
-- Use local dev briefly to pinpoint bugs (hook ordering, missing navigation, Suspense fallback behavior)
+- Container builds and integration tests
-- Validate all fixes in containers.
+- Mobile/desktop viewport validation
+- Security scanning
+
+**Flow**: Local dev -> Push to Gitea -> CI/CD runs -> PR review -> Merge
 
 
 ## Quality Standards
@@ -108,25 +158,62 @@ Leverage subagents aggressively for better results:
 
 ## AI Loading Context Strategies
 
-Canonical sources only — avoid duplication:
+Canonical sources only - avoid duplication:
-- Loading strategy and metadata: `.ai/context.json`
+- Architecture and metadata: `.ai/context.json`
-- Documentation hub and links: `docs/README.md`
+- Sprint workflow contract: `.ai/workflow-contract.json`
+- Documentation hub: `docs/README.md`
 - Feature work: `backend/src/features/{feature}/README.md`
 - Platform architecture: `docs/PLATFORM-SERVICES.md`
 - Testing workflow: `docs/TESTING.md`
 
+## Sprint Workflow
+
+Issues are the source of truth. See `.ai/workflow-contract.json` for complete workflow.
+
+### Quick Reference
+- Every PR must link to at least one issue
+- Use Gitea MCP tools for issue/label/branch/PR operations
+- Labels: `status/backlog` -> `status/ready` -> `status/in-progress` -> `status/review` -> `status/done`
+- Branches: `issue-{parent_index}-{slug}` (e.g., `issue-42-add-fuel-report`)
+- Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`)
+
+### Sub-Issue Decomposition
+Multi-file features (3+ files) must be broken into sub-issues for smaller AI context windows:
+- **Sub-issue title**: `{type}: {summary} (#{parent_index})` -- parent index in title
+- **Sub-issue body**: First line `Relates to #{parent_index}`
+- **ONE branch** per parent issue only. Never branch per sub-issue.
+- **ONE PR** per parent issue. Body lists `Fixes #N` for parent and every sub-issue.
+- **Commits** reference the specific sub-issue: `feat: add dashboard (refs #107)`
+- **Status labels** tracked on parent only. Sub-issues stay `status/backlog`.
+- **Plan milestones** map 1:1 to sub-issues.
+
 ## Architecture Context for AI
 
-### Simplified 5-Container Architecture
+### 9-Container Architecture
-**MotoVaultPro uses a simplified architecture:** A single-tenant application with 5 containers - Traefik, Frontend, Backend, PostgreSQL, and Redis. Application features in `backend/src/features/[name]/` are self-contained modules within the backend service, including the platform feature for vehicle data and VIN decoding.
+**MotoVaultPro uses a unified architecture:** A single-tenant application with 9 containers - 6 application (Traefik, Frontend, Backend, OCR, PostgreSQL, Redis) + 3 logging (Loki, Alloy, Grafana). Application features in `backend/src/features/[name]/` are self-contained modules within the backend service, including the platform feature for vehicle data and VIN decoding. See `docs/LOGGING.md` for unified logging system documentation.
 
 ### Key Principles for AI Understanding
-- **Production-Only**: All services use production builds and configuration
-- **Docker-First**: All development in containers, no local installs
 - **Feature Capsule Organization**: Application features are self-contained modules within the backend
 - **Single-Tenant**: All data belongs to a single user/tenant
 - **User-Scoped Data**: All application data isolated by user_id
+- **Local Dev + CI/CD**: Development locally, container testing in CI/CD pipeline
 - **Integrated Platform**: Platform capabilities integrated into main backend service
 
 ### Common AI Tasks
 See `Makefile` for authoritative commands and `docs/README.md` for navigation.
+
+## Agent System
+
+| Directory | Contents | When to Read |
+|-----------|----------|--------------|
+| `.claude/role-agents/` | Developer, TW, QR, Debugger | Delegating execution |
+| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review |
+| `.claude/skills/planner/` | Planning workflow | Complex features (3+ files) |
+| `.claude/skills/problem-analysis/` | Problem decomposition | Uncertain approach |
+| `.claude/agents/` | Domain agents | Feature/Frontend/Platform work |
+| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |
+
+### Quality Rules (see quality-reviewer.md for full definitions)
+- **RULE 0 (CRITICAL)**: Production reliability - unhandled errors, security, resource exhaustion
+- **RULE 1 (HIGH)**: Project standards - mobile+desktop, naming, patterns, CI/CD pass
+- **RULE 2 (SHOULD_FIX)**: Structural quality - god objects, duplication, dead code

README.md

@@ -1,23 +1,24 @@
 # MotoVaultPro — Simplified Architecture
 
-Simplified 5-container architecture with integrated platform feature.
+9-container architecture (6 application + 3 logging) with integrated platform feature.
 
 ## Requirements
 - Mobile + Desktop: Implement and test every feature on both.
 - Docker-first, production-only: All testing and validation in containers.
 - See `CLAUDE.md` for development partnership guidelines.
 
-## Quick Start (containers)
+## Staging and Production Commands. NOT FOR DEVELOPMENT (containers)
 ```bash
 make setup    # build + start + migrate (uses mvp-* containers)
 make start    # start 5 services
-make rebuild  # rebuild on changes
+make rebuild  # 
 make logs     # tail all logs
 make migrate  # run DB migrations
 ```
 
 ## Documentation
-- AI quickload: `AI-INDEX.md`
+- AI context: `.ai/context.json` (architecture, quick start, metadata)
+- Sprint workflow: `.ai/workflow-contract.json` (issue tracking)
 - Docs hub: `docs/README.md`
 - Features: `backend/src/features/{name}/README.md`
 - Frontend: `frontend/README.md`
@@ -32,4 +33,232 @@ make migrate  # run DB migrations
 - Switch traffic between environments on production: `sudo ./scripts/ci/switch-traffic.sh blue instant`
 - View which container images are running: `docker ps --format 'table {{.Names}}\t{{.Image}}'`
 - Flush all redis cache: `docker compose exec -T mvp-redis sh -lc "redis-cli FLUSHALL"`
-- Flush all backup data on staging before restoring: `docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "TRUNCATE TABLE backup_history, backup_schedules, backup_settings RESTART IDENTITY CASCADE;"`
+- Flush all backup data on staging before restoring: `docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "TRUNCATE TABLE backup_history, backup_schedules, backup_settings RESTART IDENTITY CASCADE;"`
+
+## Development Workflow
+
+```
+                    MotoVaultPro Development Workflow
+============================================================================
+
+                          SPRINT ISSUE SELECTION
+                          ----------------------
+
+   +--------------------+        +---------------------+
+   | Gitea Issue Board  |        |   status/backlog    |
+   | (Source of Truth)  |------->|                     |
+   +--------------------+        +----------+----------+
+                                            |
+                                            v
+                                 +---------------------+
+                                 |   status/ready      |
+                                 | (Current Sprint)    |
+                                 +----------+----------+
+                                            |
+                  Select smallest + highest priority
+                                            |
+                                            v
+                                 +---------------------+
+                                 | status/in-progress  |
+                                 +----------+----------+
+                                            |
+============================================================================
+
+                          PRE-PLANNING SKILLS (Optional)
+                          ------------------------------
+
+                                            |
+        +-----------------------------------+-----------------------------------+
+        |                                   |                                   |
+        v                                   v                                   v
++------------------+              +------------------+              +------------------+
+| CODEBASE         |              | PROBLEM          |              | DECISION         |
+| ANALYSIS SKILL   |              | ANALYSIS SKILL   |              | CRITIC SKILL     |
++------------------+              +------------------+              +------------------+
+| When: Unfamiliar |              | When: Complex    |              | When: Uncertain  |
+| area             |              | problem          |              | approach         |
++------------------+              +------------------+              +------------------+
+
+============================================================================
+
+                          PLANNER SKILL: PLANNING WORKFLOW
+                          ---------------------------------
+
+                                 +---------------------+
+                                 |      PLANNING       |
+                                 | (Context, Scope,    |
+                                 |  Decision, Refine)  |
+                                 +----------+----------+
+                                            |
+                                            v
+                        +---------------------------------------+
+                        |       PLAN REVIEW CYCLE               |
+                        |  (All results posted to Issue)        |
+                        +---------------------------------------+
+                                            |
+                                                v
+                                     +---------------------+
+                             +------>| QR: plan-complete-  |
+                             |       | ness                |
+                             |       +----------+----------+
+                             |                  |
+                  [FAIL]     |         [PASS]   |
+                             |                  v
+                             |       +---------------------+
+                             |       | QR: plan-code       |
+                             |       | (RULE 0/1/2)        |
+                             |       +----------+----------+
+                             |                  |
+                  [FAIL]-----+         [PASS]   |
+                                                v
+                                     +---------------------+
+                             +------>| TW: plan-scrub      |
+                             |       +----------+----------+
+                             |                  |
+                             |                  v
+                             |       +---------------------+
+                             |       | QR: plan-docs       |
+                             |       +----------+----------+
+                             |                  |
+                  [FAIL]-----+         [PASS]   |
+                                                v
+                                     +---------------------+
+                                     |     PLAN APPROVED   |
+                                     +----------+----------+
+                                                |
+    ============================================================================
+    
+                              EXECUTION
+                              ---------
+    
+                                                |
+                                                v
+                                     +---------------------+
+                                     | Create Branch       |
+                                     | issue-{N}-{slug}    |
+                                     +----------+----------+
+                                                |
+                                                v
+                        +---------------------------------------+
+                        |         MILESTONE EXECUTION           |
+                        |       (Parallel Developer Agents)     |
+                        +---------------------------------------+
+                                                |
+                  +---------------------------------------------------------+
+                  |   +---------------+  +---------------+  +---------------+
+                  |   | FEATURE AGENT |  | FRONTEND      |  | PLATFORM      |
+                  |   | (Backend)     |  | AGENT (React) |  | AGENT         |
+                  |   +-------+-------+  +-------+-------+  +-------+-------+
+                  |           |                  |                  |
+                  |           +------------------+------------------+
+                  |                              |
+                  |                 Delegate to DEVELOPER role-agent
+                  |                              |
+                  +---------------------------------------------------------+
+                                                |
+                                                v
+                                     +---------------------+
+                             +------>| QR: post-           |
+                             |       | implementation      |
+                             |       +----------+----------+
+                             |                  |
+                             |    [FAIL]        |  [PASS]
+                             |      |           |
+                             +------+           v
+                                     +---------------------+
+                                     | TW: Documentation   |
+                                     +----------+----------+
+                                                |
+    ============================================================================
+    
+                              PR AND REVIEW
+                              -------------
+    
+                                                |
+                                                v
+                                     +---------------------+
+                                     | Open PR             |
+                                     | Fixes #{N}          |
+                                     +----------+----------+
+                                                |
+                                                v
+                                     +---------------------+
+                                     |   status/review     |
+                                     +----------+----------+
+                                                |
+                                                v
+                        +---------------------------------------+
+                        |          QUALITY AGENT                |
+                        |    (Final Gatekeeper - ALL GREEN)     |
+                        +---------------------------------------+
+                                                |
+                        +-----------------------+-----------------------+
+                        v                       v                       v
+              +------------------+   +------------------+   +------------------+
+              | npm run lint     |   | npm run type-    |   | npm test         |
+              |                  |   | check            |   |                  |
+              +------------------+   +------------------+   +------------------+
+                        |                       |                       |
+                        v                       v                       v
+              +------------------+   +------------------+   +------------------+
+              | Mobile Viewport  |   | Desktop Viewport |   | RULE 0/1/2       |
+              | (320px, 768px)   |   | (1920px)         |   | Review           |
+              +------------------+   +------------------+   +------------------+
+                        |                       |                       |
+                        +-----------------------+-----------------------+
+                                                |
+                             [FAIL]             |            [PASS]
+                                |               |               |
+                                v               |               v
+                      +---------------+         |     +---------------------+
+                      | Fix & Iterate |<--------+     | PR APPROVED         |
+                      +---------------+               +----------+----------+
+                                                                 |
+    ============================================================================
+    
+                              COMPLETION
+                              ----------
+    
+                                     +---------------------+
+                                     | Merge PR to main    |
+                                     +----------+----------+
+                                                |
+                                                v
+                                     +---------------------+
+                                     |   status/done       |
+                                     +----------+----------+
+                                                |
+                                                v
+                                     +---------------------+
+                                     | DOC-SYNC SKILL      |
+                                     +---------------------+
+    
+    ============================================================================
+    
+    LEGEND
+    ------
+    Skills: codebase-analysis, problem-analysis, decision-critic, planner, doc-sync
+    Role-Agents: Developer, Technical Writer (TW), Quality Reviewer (QR), Debugger
+    Domain Agents: Feature Agent, Frontend Agent, Platform Agent, Quality Agent
+
+    Labels: status/backlog -> status/ready -> status/in-progress -> status/review -> status/done
+    Commits: {type}: {summary} (refs #{N})  |  Types: feat, fix, chore, docs, refactor, test
+    Branches: issue-{N}-{slug}  |  Example: issue-42-add-fuel-report
+
+    SUB-ISSUE PATTERN (multi-file features)
+    ----------------------------------------
+    Parent: #105 "feat: Add Grafana dashboards"
+    Sub:    #106 "feat: Dashboard provisioning (#105)"  <-- parent index in title
+    Branch: issue-105-add-grafana-dashboards            <-- ONE branch, parent index
+    Commit: feat: add provisioning (refs #106)          <-- refs specific sub-issue
+    PR:     feat: Add Grafana dashboards (#105)         <-- ONE PR, parent index
+            Body: Fixes #105, Fixes #106, Fixes #107... <-- closes all
+    
+    QUALITY RULES
+    -------------
+    RULE 0 (CRITICAL): Production reliability - unhandled errors, security, resource exhaustion
+    RULE 1 (HIGH): Project conformance - mobile+desktop, naming conventions, CI/CD pass
+    RULE 2 (SHOULD_FIX): Structural quality - god objects, duplicate logic, dead code
+    ```
+    
+    See `.ai/workflow-contract.json` for the complete workflow specification.

ansible/CLAUDE.md

@@ -0,0 +1,11 @@
+# ansible/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `deploy-production-runner.yml` | Production runner deployment | Production deployments |
+| `deploy-staging-runner.yml` | Staging runner deployment | Staging deployments |
+| `inventory.yml` | Server inventory | Server host configuration |
+| `inventory.yml.example` | Example inventory template | Setting up new environments |
+| `config.yaml.j2` | Jinja2 config template | Runner configuration |

ansible/deploy-production-runner.yml

@@ -269,24 +269,17 @@
       when: gitea_registry_token is defined
 
     # ============================================
-    # Maintenance Scripts
+    # Remove Legacy Docker Cleanup (was destroying volumes)
     # ============================================
-    - name: Create Docker cleanup script
+    - name: Remove legacy Docker cleanup cron job
-      copy:
-        dest: /usr/local/bin/docker-cleanup.sh
-        content: |
-          #!/bin/bash
-          # Remove unused Docker resources older than 7 days
-          docker system prune -af --filter "until=168h"
-          docker volume prune -f
-        mode: '0755'
-
-    - name: Schedule Docker cleanup cron job
       cron:
         name: "Docker cleanup"
-        minute: "0"
+        state: absent
-        hour: "3"
+
-        job: "/usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1"
+    - name: Remove legacy Docker cleanup script
+      file:
+        path: /usr/local/bin/docker-cleanup.sh
+        state: absent
 
     # ============================================
     # Production-Specific Security Hardening

ansible/deploy-staging-runner.yml

@@ -300,24 +300,17 @@
       when: gitea_registry_token is defined
 
     # ============================================
-    # Maintenance Scripts
+    # Remove Legacy Docker Cleanup (was destroying volumes)
     # ============================================
-    - name: Create Docker cleanup script
+    - name: Remove legacy Docker cleanup cron job
-      copy:
-        dest: /usr/local/bin/docker-cleanup.sh
-        content: |
-          #!/bin/bash
-          # Remove unused Docker resources older than 7 days
-          docker system prune -af --filter "until=168h"
-          docker volume prune -f
-        mode: '0755'
-
-    - name: Schedule Docker cleanup cron job
       cron:
         name: "Docker cleanup"
-        minute: "0"
+        state: absent
-        hour: "3"
+
-        job: "/usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1"
+    - name: Remove legacy Docker cleanup script
+      file:
+        path: /usr/local/bin/docker-cleanup.sh
+        state: absent
 
   handlers:
     - name: Restart act_runner

backend/CLAUDE.md

@@ -0,0 +1,19 @@
+# backend/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Backend quickstart and commands | Getting started with backend development |
+| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
+| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
+| `eslint.config.js` | ESLint configuration | Linting rules, code style |
+| `jest.config.js` | Jest test configuration | Test setup, coverage settings |
+| `Dockerfile` | Container build definition | Docker builds, deployment |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `src/` | Application source code | Any backend development |
+| `scripts/` | Utility scripts (docker-entrypoint) | Container startup, automation |

backend/package-lock.json

@@ -20,21 +20,26 @@
         "fastify": "^5.2.0",
         "fastify-plugin": "^5.0.1",
         "file-type": "^16.5.4",
+        "form-data": "^4.0.0",
         "get-jwks": "^11.0.3",
         "ioredis": "^5.4.2",
         "js-yaml": "^4.1.0",
+        "mailparser": "^3.9.3",
         "node-cron": "^3.0.3",
         "opossum": "^8.0.0",
         "pg": "^8.13.1",
+        "pino": "^9.6.0",
         "resend": "^3.0.0",
+        "stripe": "^20.2.0",
+        "svix": "^1.85.0",
         "tar": "^7.4.3",
-        "winston": "^3.17.0",
         "zod": "^3.24.1"
       },
       "devDependencies": {
         "@eslint/js": "^9.17.0",
         "@types/jest": "^29.5.10",
         "@types/js-yaml": "^4.0.9",
+        "@types/mailparser": "^3.4.6",
         "@types/node": "^22.0.0",
         "@types/node-cron": "^3.0.11",
         "@types/opossum": "^8.0.0",
@@ -81,7 +86,6 @@
       "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -577,15 +581,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@colors/colors": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.6.0.tgz",
-      "integrity": "sha512-Ir+AOibqzrIsL6ajt3Rz3LskB7OiMVHqltZmspbW/TJuTVuyOMirVqAkjfY6JISiLHgyNqicAC8AyHHGzNd/dA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.1.90"
-      }
-    },
     "node_modules/@cspotcode/source-map-support": {
       "version": "0.8.1",
       "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
@@ -610,17 +605,6 @@
         "@jridgewell/sourcemap-codec": "^1.4.10"
       }
     },
-    "node_modules/@dabh/diagnostics": {
-      "version": "2.0.8",
-      "resolved": "https://registry.npmjs.org/@dabh/diagnostics/-/diagnostics-2.0.8.tgz",
-      "integrity": "sha512-R4MSXTVnuMzGD7bzHdW2ZhhdPC/igELENcq5IjEverBvq5hn1SXCWcsi6eSsdWP0/Ur+SItRRjAktmdoX/8R/Q==",
-      "license": "MIT",
-      "dependencies": {
-        "@so-ric/colorspace": "^1.1.6",
-        "enabled": "2.0.x",
-        "kuler": "^2.0.0"
-      }
-    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.9.0",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.0.tgz",
@@ -1784,15 +1768,11 @@
         "@sinonjs/commons": "^3.0.0"
       }
     },
-    "node_modules/@so-ric/colorspace": {
+    "node_modules/@stablelib/base64": {
-      "version": "1.1.6",
+      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/@so-ric/colorspace/-/colorspace-1.1.6.tgz",
+      "resolved": "https://registry.npmjs.org/@stablelib/base64/-/base64-1.0.1.tgz",
-      "integrity": "sha512-/KiKkpHNOBgkFJwu9sh48LkHSMYGyuTcSFK/qMBdnOAlrRJzRSXAOFB5qwzaVQuDl8wAvHVMkaASQDReTahxuw==",
+      "integrity": "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ==",
-      "license": "MIT",
+      "license": "MIT"
-      "dependencies": {
-        "color": "^5.0.2",
-        "text-hex": "1.0.x"
-      }
     },
     "node_modules/@tokenizer/token": {
       "version": "0.3.0",
@@ -1949,6 +1929,30 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/mailparser": {
+      "version": "3.4.6",
+      "resolved": "https://registry.npmjs.org/@types/mailparser/-/mailparser-3.4.6.tgz",
+      "integrity": "sha512-wVV3cnIKzxTffaPH8iRnddX1zahbYB1ZEoAxyhoBo3TBCBuK6nZ8M8JYO/RhsCuuBVOw/DEN/t/ENbruwlxn6Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "iconv-lite": "^0.6.3"
+      }
+    },
+    "node_modules/@types/mailparser/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/@types/methods": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
@@ -1960,9 +1964,8 @@
       "version": "22.19.3",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.3.tgz",
       "integrity": "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -2027,12 +2030,6 @@
         "@types/superagent": "^8.1.0"
       }
     },
-    "node_modules/@types/triple-beam": {
-      "version": "1.3.5",
-      "resolved": "https://registry.npmjs.org/@types/triple-beam/-/triple-beam-1.3.5.tgz",
-      "integrity": "sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw==",
-      "license": "MIT"
-    },
     "node_modules/@types/yargs": {
       "version": "17.0.35",
       "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.35.tgz",
@@ -2095,7 +2092,6 @@
       "integrity": "sha512-6/cmF2piao+f6wSxUsJLZjck7OQsYyRtcOZS02k7XINSNlz93v6emM8WutDQSXnroG2xwYlEVHJI+cPA7CPM3Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.50.0",
         "@typescript-eslint/types": "8.50.0",
@@ -2307,6 +2303,17 @@
         "url": "https://opencollective.com/typescript-eslint"
       }
     },
+    "node_modules/@zone-eu/mailsplit": {
+      "version": "5.4.8",
+      "resolved": "https://registry.npmjs.org/@zone-eu/mailsplit/-/mailsplit-5.4.8.tgz",
+      "integrity": "sha512-eEyACj4JZ7sjzRvy26QhLgKEMWwQbsw1+QZnlLX+/gihcNH07lVPOcnwf5U6UAL7gkc//J3jVd76o/WS+taUiA==",
+      "license": "(MIT OR EUPL-1.1+)",
+      "dependencies": {
+        "libbase64": "1.3.0",
+        "libmime": "5.3.7",
+        "libqp": "2.1.1"
+      }
+    },
     "node_modules/abbrev": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-2.0.0.tgz",
@@ -2340,7 +2347,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -2513,12 +2519,6 @@
         "safer-buffer": "^2.1.0"
       }
     },
-    "node_modules/async": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/async/-/async-3.2.6.tgz",
-      "integrity": "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==",
-      "license": "MIT"
-    },
     "node_modules/asynckit": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
@@ -2813,7 +2813,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -2899,7 +2898,6 @@
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
       "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bind-apply-helpers": "^1.0.2",
@@ -3092,19 +3090,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/color": {
-      "version": "5.0.3",
-      "resolved": "https://registry.npmjs.org/color/-/color-5.0.3.tgz",
-      "integrity": "sha512-ezmVcLR3xAVp8kYOm4GS45ZLLgIE6SPAFoduLr6hTDajwb3KZ2F46gulK3XpcwRFb5KKGCSezCBAY4Dw4HsyXA==",
-      "license": "MIT",
-      "dependencies": {
-        "color-convert": "^3.1.3",
-        "color-string": "^2.1.3"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -3123,48 +3108,6 @@
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
       "license": "MIT"
     },
-    "node_modules/color-string": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/color-string/-/color-string-2.1.4.tgz",
-      "integrity": "sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==",
-      "license": "MIT",
-      "dependencies": {
-        "color-name": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/color-string/node_modules/color-name": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/color-name/-/color-name-2.1.0.tgz",
-      "integrity": "sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12.20"
-      }
-    },
-    "node_modules/color/node_modules/color-convert": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-3.1.3.tgz",
-      "integrity": "sha512-fasDH2ont2GqF5HpyO4w0+BcewlhHEZOFn9c1ckZdHpJ56Qb7MHhH/IcJZbBGgvdtwdwNbLvxiBEdg336iA9Sg==",
-      "license": "MIT",
-      "dependencies": {
-        "color-name": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=14.6"
-      }
-    },
-    "node_modules/color/node_modules/color-name": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/color-name/-/color-name-2.1.0.tgz",
-      "integrity": "sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12.20"
-      }
-    },
     "node_modules/combined-stream": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
@@ -3566,11 +3509,14 @@
       "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
       "license": "MIT"
     },
-    "node_modules/enabled": {
+    "node_modules/encoding-japanese": {
-      "version": "2.0.0",
+      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/enabled/-/enabled-2.0.0.tgz",
+      "resolved": "https://registry.npmjs.org/encoding-japanese/-/encoding-japanese-2.2.0.tgz",
-      "integrity": "sha512-AKrN98kuwOzMIdAizXGI86UFBoo26CL21UM763y1h/GMSJ4/OHU9k2YlsmBpyScFo/wbLzWQJBMCW4+IO3/+OQ==",
+      "integrity": "sha512-EuJWwlHPZ1LbADuKTClvHtwbaFn4rOD+dRAbWysqEOXRc2Uui0hJInNJrsdH0c+OhJA4nrCBdSkW4DD5YxAo6A==",
-      "license": "MIT"
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.10.0"
+      }
     },
     "node_modules/entities": {
       "version": "4.5.0",
@@ -3668,7 +3614,6 @@
       "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -4002,6 +3947,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-sha256": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/fast-sha256/-/fast-sha256-1.3.0.tgz",
+      "integrity": "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==",
+      "license": "Unlicense"
+    },
     "node_modules/fast-uri": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@@ -4079,6 +4030,49 @@
       ],
       "license": "MIT"
     },
+    "node_modules/fastify/node_modules/pino": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-10.3.0.tgz",
+      "integrity": "sha512-0GNPNzHXBKw6U/InGe79A3Crzyk9bcSyObF9/Gfo9DLEf5qj5RF50RSjsu0W1rZ6ZqRGdzDFCRBQvi9/rSGPtA==",
+      "license": "MIT",
+      "dependencies": {
+        "@pinojs/redact": "^0.4.0",
+        "atomic-sleep": "^1.0.0",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pino-std-serializers": "^7.0.0",
+        "process-warning": "^5.0.0",
+        "quick-format-unescaped": "^4.0.3",
+        "real-require": "^0.2.0",
+        "safe-stable-stringify": "^2.3.1",
+        "sonic-boom": "^4.0.1",
+        "thread-stream": "^4.0.0"
+      },
+      "bin": {
+        "pino": "bin.js"
+      }
+    },
+    "node_modules/fastify/node_modules/pino-abstract-transport": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+      "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/fastify/node_modules/thread-stream": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.0.0.tgz",
+      "integrity": "sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==",
+      "license": "MIT",
+      "dependencies": {
+        "real-require": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/fastparallel": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/fastparallel/-/fastparallel-2.4.1.tgz",
@@ -4118,12 +4112,6 @@
         "bser": "2.1.1"
       }
     },
-    "node_modules/fecha": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/fecha/-/fecha-4.2.3.tgz",
-      "integrity": "sha512-OP2IUU6HeYKJi3i0z4A19kHMQoLVs4Hc+DPqqxI2h/DPZHTm/vjsfC6P0b4jCMy14XizLBqvndQ+UilD7707Jw==",
-      "license": "MIT"
-    },
     "node_modules/file-entry-cache": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
@@ -4219,12 +4207,6 @@
       "dev": true,
       "license": "ISC"
     },
-    "node_modules/fn.name": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/fn.name/-/fn.name-1.1.0.tgz",
-      "integrity": "sha512-GRnmB5gPyJpAhTQdSZTSp9uaPSvl09KoYcMQtsB9rQoOmzs9dH6ffeccH+Z+cv6P68Hu5bC6JjRh4Ah/mHSNRw==",
-      "license": "MIT"
-    },
     "node_modules/follow-redirects": {
       "version": "1.15.11",
       "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
@@ -4579,6 +4561,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/he": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz",
+      "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==",
+      "license": "MIT",
+      "bin": {
+        "he": "bin/he"
+      }
+    },
     "node_modules/helmet": {
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/helmet/-/helmet-8.1.0.tgz",
@@ -4651,6 +4642,22 @@
         "node": ">=10.17.0"
       }
     },
+    "node_modules/iconv-lite": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+      "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
     "node_modules/ieee754": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
@@ -4884,6 +4891,7 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
       "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -4990,7 +4998,6 @@
       "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@jest/core": "^29.7.0",
         "@jest/types": "^29.6.3",
@@ -5773,12 +5780,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/kuler": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/kuler/-/kuler-2.0.0.tgz",
-      "integrity": "sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==",
-      "license": "MIT"
-    },
     "node_modules/leac": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/leac/-/leac-0.6.0.tgz",
@@ -5812,6 +5813,42 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/libbase64": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/libbase64/-/libbase64-1.3.0.tgz",
+      "integrity": "sha512-GgOXd0Eo6phYgh0DJtjQ2tO8dc0IVINtZJeARPeiIJqge+HdsWSuaDTe8ztQ7j/cONByDZ3zeB325AHiv5O0dg==",
+      "license": "MIT"
+    },
+    "node_modules/libmime": {
+      "version": "5.3.7",
+      "resolved": "https://registry.npmjs.org/libmime/-/libmime-5.3.7.tgz",
+      "integrity": "sha512-FlDb3Wtha8P01kTL3P9M+ZDNDWPKPmKHWaU/cG/lg5pfuAwdflVpZE+wm9m7pKmC5ww6s+zTxBKS1p6yl3KpSw==",
+      "license": "MIT",
+      "dependencies": {
+        "encoding-japanese": "2.2.0",
+        "iconv-lite": "0.6.3",
+        "libbase64": "1.3.0",
+        "libqp": "2.1.1"
+      }
+    },
+    "node_modules/libmime/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/libqp": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/libqp/-/libqp-2.1.1.tgz",
+      "integrity": "sha512-0Wd+GPz1O134cP62YU2GTOPNA7Qgl09XwCqM5zpBv87ERCXdfDtyKXvV7c9U22yWJh44QZqBocFnXN11K96qow==",
+      "license": "MIT"
+    },
     "node_modules/light-my-request": {
       "version": "6.6.0",
       "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
@@ -5856,6 +5893,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
     "node_modules/locate-path": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -5898,28 +5944,12 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/logform": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/logform/-/logform-2.7.0.tgz",
-      "integrity": "sha512-TFYA4jnP7PVbmlBIfhlSe+WKxs9dklXMTEGcBCIvLhE/Tn3H6Gk1norupVW7m5Cnd4bLcr08AytbyV/xj7f/kQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@colors/colors": "1.6.0",
-        "@types/triple-beam": "^1.3.2",
-        "fecha": "^4.2.0",
-        "ms": "^2.1.1",
-        "safe-stable-stringify": "^2.3.1",
-        "triple-beam": "^1.3.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
     "node_modules/loose-envify": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
       "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "js-tokens": "^3.0.0 || ^4.0.0"
       },
@@ -5936,6 +5966,24 @@
         "node": "20 || >=22"
       }
     },
+    "node_modules/mailparser": {
+      "version": "3.9.3",
+      "resolved": "https://registry.npmjs.org/mailparser/-/mailparser-3.9.3.tgz",
+      "integrity": "sha512-AnB0a3zROum6fLaa52L+/K2SoRJVyFDk78Ea6q1D0ofcZLxWEWDtsS1+OrVqKbV7r5dulKL/AwYQccFGAPpuYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@zone-eu/mailsplit": "5.4.8",
+        "encoding-japanese": "2.2.0",
+        "he": "1.2.0",
+        "html-to-text": "9.0.5",
+        "iconv-lite": "0.7.2",
+        "libmime": "5.3.7",
+        "linkify-it": "5.0.0",
+        "nodemailer": "7.0.13",
+        "punycode.js": "2.3.1",
+        "tlds": "1.261.0"
+      }
+    },
     "node_modules/make-dir": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
@@ -6164,6 +6212,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/nodemailer": {
+      "version": "7.0.13",
+      "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-7.0.13.tgz",
+      "integrity": "sha512-PNDFSJdP+KFgdsG3ZzMXCgquO7I6McjY2vlqILjtJd0hy8wEvtugS9xKRF2NWlPNGxvLCXlTNIae4serI7dinw==",
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/nodemon": {
       "version": "3.1.11",
       "resolved": "https://registry.npmjs.org/nodemon/-/nodemon-3.1.11.tgz",
@@ -6258,7 +6315,6 @@
       "version": "1.13.4",
       "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
       "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -6292,15 +6348,6 @@
         "wrappy": "1"
       }
     },
-    "node_modules/one-time": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/one-time/-/one-time-1.0.0.tgz",
-      "integrity": "sha512-5DXOiRKwuSEcQ/l0kGCF6Q3jcADFv5tSmRaJck/OqkVFcOzutB134KRSfF0xDrL39MNnqxbHBbUUcjZIhTgb2g==",
-      "license": "MIT",
-      "dependencies": {
-        "fn.name": "1.x.x"
-      }
-    },
     "node_modules/onetime": {
       "version": "5.1.2",
       "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
@@ -6522,7 +6569,6 @@
       "resolved": "https://registry.npmjs.org/pg/-/pg-8.16.3.tgz",
       "integrity": "sha512-enxc1h0jA/aq5oSDMvqyW3q89ra6XIIDZgCX9vkMrnz5DFTw/Ny3Li2lFQ+pt3L6MCgm/5o2o8HW9hiJji+xvw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "pg-connection-string": "^2.9.1",
         "pg-pool": "^3.10.1",
@@ -6628,9 +6674,9 @@
       }
     },
     "node_modules/pino": {
-      "version": "10.1.0",
+      "version": "9.14.0",
-      "resolved": "https://registry.npmjs.org/pino/-/pino-10.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-9.14.0.tgz",
-      "integrity": "sha512-0zZC2ygfdqvqK8zJIr1e+wT1T/L+LF6qvqvbzEQ6tiMAoTqEVK9a1K3YRu8HEUvGEvNqZyPJTtb2sNIoTkB83w==",
+      "integrity": "sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w==",
       "license": "MIT",
       "dependencies": {
         "@pinojs/redact": "^0.4.0",
@@ -6888,6 +6934,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/pure-rand": {
       "version": "6.1.0",
       "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-6.1.0.tgz",
@@ -6906,10 +6961,9 @@
       "license": "MIT"
     },
     "node_modules/qs": {
-      "version": "6.14.0",
+      "version": "6.14.1",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz",
-      "integrity": "sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==",
+      "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"
@@ -6976,20 +7030,6 @@
       "integrity": "sha512-bCK/2Z4zLidyB4ReuIsvALH6w31YfAQDmXMqMx6FyfHqvBxtjC0eRumeSu4Bs3XtXwpyIywtSTrVT99BxY1f9w==",
       "license": "MIT"
     },
-    "node_modules/readable-stream": {
-      "version": "3.6.2",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
-      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
-      "license": "MIT",
-      "dependencies": {
-        "inherits": "^2.0.3",
-        "string_decoder": "^1.1.1",
-        "util-deprecate": "^1.0.1"
-      },
-      "engines": {
-        "node": ">= 6"
-      }
-    },
     "node_modules/readable-web-to-node-stream": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/readable-web-to-node-stream/-/readable-web-to-node-stream-3.0.4.tgz",
@@ -7244,6 +7284,7 @@
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
       "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       }
@@ -7319,7 +7360,6 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
       "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
@@ -7339,7 +7379,6 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz",
       "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
@@ -7356,7 +7395,6 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
       "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bound": "^1.0.2",
@@ -7375,7 +7413,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
       "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "call-bound": "^1.0.2",
@@ -7474,15 +7511,6 @@
       "dev": true,
       "license": "BSD-3-Clause"
     },
-    "node_modules/stack-trace": {
-      "version": "0.0.10",
-      "resolved": "https://registry.npmjs.org/stack-trace/-/stack-trace-0.0.10.tgz",
-      "integrity": "sha512-KGzahc7puUKkzyMt+IqAep+TVNbKP+k2Lmwhub39m1AsTSkaDutx56aDCo+HLDzf/D26BIHTJWNiTG1KAJiQCg==",
-      "license": "MIT",
-      "engines": {
-        "node": "*"
-      }
-    },
     "node_modules/stack-utils": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz",
@@ -7512,6 +7540,16 @@
       "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==",
       "license": "MIT"
     },
+    "node_modules/standardwebhooks": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/standardwebhooks/-/standardwebhooks-1.0.0.tgz",
+      "integrity": "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg==",
+      "license": "MIT",
+      "dependencies": {
+        "@stablelib/base64": "^1.0.0",
+        "fast-sha256": "^1.3.0"
+      }
+    },
     "node_modules/steed": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/steed/-/steed-1.1.3.tgz",
@@ -7635,6 +7673,26 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/stripe": {
+      "version": "20.2.0",
+      "resolved": "https://registry.npmjs.org/stripe/-/stripe-20.2.0.tgz",
+      "integrity": "sha512-m8niTfdm3nPP/yQswRWMwQxqEUcTtB3RTJQ9oo6NINDzgi7aPOadsH/fPXIIfL1Sc5+lqQFKSk7WiO6CXmvaeA==",
+      "license": "MIT",
+      "dependencies": {
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "peerDependencies": {
+        "@types/node": ">=16"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/strtok3": {
       "version": "6.3.0",
       "resolved": "https://registry.npmjs.org/strtok3/-/strtok3-6.3.0.tgz",
@@ -7713,6 +7771,29 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/svix": {
+      "version": "1.85.0",
+      "resolved": "https://registry.npmjs.org/svix/-/svix-1.85.0.tgz",
+      "integrity": "sha512-4OxNw++bnNay8SoBwESgzfjMnYmurS1qBX+luhzvljr6EAPn/hqqmkdCR1pbgIe1K1+BzKZEHjAKz9OYrKJYwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "standardwebhooks": "1.0.0",
+        "uuid": "^10.0.0"
+      }
+    },
+    "node_modules/svix/node_modules/uuid": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-10.0.0.tgz",
+      "integrity": "sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==",
+      "funding": [
+        "https://github.com/sponsors/broofa",
+        "https://github.com/sponsors/ctavan"
+      ],
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist/bin/uuid"
+      }
+    },
     "node_modules/tar": {
       "version": "7.5.2",
       "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.2.tgz",
@@ -7753,12 +7834,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/text-hex": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/text-hex/-/text-hex-1.0.0.tgz",
-      "integrity": "sha512-uuVGNWzgJ4yhRaNSiubPY7OjISw4sw4E5Uv0wbjp+OzcbmVU/rsT8ujgcXJhn9ypzsgr5vlzpPqP+MBBKcGvbg==",
-      "license": "MIT"
-    },
     "node_modules/thread-stream": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-3.1.0.tgz",
@@ -7809,7 +7884,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -7817,6 +7891,15 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/tlds": {
+      "version": "1.261.0",
+      "resolved": "https://registry.npmjs.org/tlds/-/tlds-1.261.0.tgz",
+      "integrity": "sha512-QXqwfEl9ddlGBaRFXIvNKK6OhipSiLXuRuLJX5DErz0o0Q0rYxulWLdFryTkV5PkdZct5iMInwYEGe/eR++1AA==",
+      "license": "MIT",
+      "bin": {
+        "tlds": "bin.js"
+      }
+    },
     "node_modules/tmpl": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/tmpl/-/tmpl-1.0.5.tgz",
@@ -7873,15 +7956,6 @@
         "nodetouch": "bin/nodetouch.js"
       }
     },
-    "node_modules/triple-beam": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/triple-beam/-/triple-beam-1.4.1.tgz",
-      "integrity": "sha512-aZbgViZrg1QNcG+LULa7nhZpJTZSLm/mXnHXnbAbjmN5aSa0y7V+wvv6+4WaBtpISJzThKy+PIPxc1Nq1EJ9mg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 14.0.0"
-      }
-    },
     "node_modules/ts-api-utils": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz",
@@ -7967,7 +8041,6 @@
       "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@cspotcode/source-map-support": "^0.8.0",
         "@tsconfig/node10": "^1.0.7",
@@ -8055,7 +8128,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -8088,6 +8160,12 @@
         "typescript": ">=4.8.4 <6.0.0"
       }
     },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "license": "MIT"
+    },
     "node_modules/uglify-js": {
       "version": "3.19.3",
       "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz",
@@ -8156,12 +8234,6 @@
         "punycode": "^2.1.0"
       }
     },
-    "node_modules/util-deprecate": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
-      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "license": "MIT"
-    },
     "node_modules/uuid": {
       "version": "8.3.2",
       "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
@@ -8218,42 +8290,6 @@
         "node": ">= 8"
       }
     },
-    "node_modules/winston": {
-      "version": "3.19.0",
-      "resolved": "https://registry.npmjs.org/winston/-/winston-3.19.0.tgz",
-      "integrity": "sha512-LZNJgPzfKR+/J3cHkxcpHKpKKvGfDZVPS4hfJCc4cCG0CgYzvlD6yE/S3CIL/Yt91ak327YCpiF/0MyeZHEHKA==",
-      "license": "MIT",
-      "dependencies": {
-        "@colors/colors": "^1.6.0",
-        "@dabh/diagnostics": "^2.0.8",
-        "async": "^3.2.3",
-        "is-stream": "^2.0.0",
-        "logform": "^2.7.0",
-        "one-time": "^1.0.0",
-        "readable-stream": "^3.4.0",
-        "safe-stable-stringify": "^2.3.1",
-        "stack-trace": "0.0.x",
-        "triple-beam": "^1.3.0",
-        "winston-transport": "^4.9.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
-    "node_modules/winston-transport": {
-      "version": "4.9.0",
-      "resolved": "https://registry.npmjs.org/winston-transport/-/winston-transport-4.9.0.tgz",
-      "integrity": "sha512-8drMJ4rkgaPo1Me4zD/3WLfI/zPdA9o2IipKODunnGDcuqbHwjsbB79ylv04LCGGzU0xQ6vTznOMpQGaLhhm6A==",
-      "license": "MIT",
-      "dependencies": {
-        "logform": "^2.7.0",
-        "readable-stream": "^3.6.2",
-        "triple-beam": "^1.3.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
     "node_modules/word-wrap": {
       "version": "1.2.5",
       "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",

backend/package.json

@@ -18,45 +18,50 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "pg": "^8.13.1",
+    "@fastify/autoload": "^6.0.1",
-    "ioredis": "^5.4.2",
-    "@fastify/multipart": "^9.0.1",
-    "axios": "^1.7.9",
-    "opossum": "^8.0.0",
-    "winston": "^3.17.0",
-    "zod": "^3.24.1",
-    "js-yaml": "^4.1.0",
-    "fastify": "^5.2.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
+    "@fastify/multipart": "^9.0.1",
     "@fastify/type-provider-typebox": "^6.1.0",
     "@sinclair/typebox": "^0.34.0",
-    "fastify-plugin": "^5.0.1",
-    "@fastify/autoload": "^6.0.1",
-    "get-jwks": "^11.0.3",
-    "file-type": "^16.5.4",
-    "resend": "^3.0.0",
-    "node-cron": "^3.0.3",
     "auth0": "^4.12.0",
-    "tar": "^7.4.3"
+    "axios": "^1.7.9",
+    "fastify": "^5.2.0",
+    "fastify-plugin": "^5.0.1",
+    "file-type": "^16.5.4",
+    "form-data": "^4.0.0",
+    "get-jwks": "^11.0.3",
+    "ioredis": "^5.4.2",
+    "js-yaml": "^4.1.0",
+    "mailparser": "^3.9.3",
+    "node-cron": "^3.0.3",
+    "opossum": "^8.0.0",
+    "pg": "^8.13.1",
+    "pino": "^9.6.0",
+    "resend": "^3.0.0",
+    "stripe": "^20.2.0",
+    "svix": "^1.85.0",
+    "tar": "^7.4.3",
+    "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/pg": "^8.10.9",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node-cron": "^3.0.11",
-    "typescript": "^5.7.2",
-    "ts-node": "^10.9.1",
-    "nodemon": "^3.1.9",
-    "jest": "^29.7.0",
-    "@types/jest": "^29.5.10",
-    "ts-jest": "^29.1.1",
-    "supertest": "^7.1.4",
-    "@types/supertest": "^6.0.3",
-    "@types/opossum": "^8.0.0",
-    "eslint": "^9.17.0",
     "@eslint/js": "^9.17.0",
+    "@types/jest": "^29.5.10",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^22.0.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/opossum": "^8.0.0",
+    "@types/pg": "^8.10.9",
+    "@types/supertest": "^6.0.3",
+    "eslint": "^9.17.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.9",
+    "supertest": "^7.1.4",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1"
   }
 }

backend/src/CLAUDE.md

@@ -0,0 +1,18 @@
+# backend/src/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `app.ts` | Fastify application setup and routes | Route registration, middleware setup |
+| `index.ts` | Application entry point | Server startup, initialization |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `features/` | Feature capsules (self-contained modules) | Feature development, API endpoints |
+| `core/` | Shared infrastructure (auth, config, logging) | Cross-cutting concerns, plugins |
+| `_system/` | System utilities (migrations, CLI, schema) | Database migrations, schema generation |
+| `shared-minimal/` | Minimal shared utilities | Shared type utilities |
+| `scripts/` | Backend-specific scripts | Utility scripts |

backend/src/_system/CLAUDE.md

@@ -0,0 +1,10 @@
+# _system/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `cli/` | CLI commands and tools | Running backend CLI commands |
+| `migrations/` | Database migration runner | Running or writing migrations |
+| `schema/` | Database schema generation | Schema export, documentation |
+| `scripts/` | System utility scripts | Database maintenance, automation |

backend/src/_system/migrations/run-all.ts

@@ -17,7 +17,8 @@ const pool = new Pool({
 const MIGRATION_ORDER = [
   'features/vehicles',          // Primary entity, defines update_updated_at_column()
   'features/platform',          // Normalized make/model/trim schema for dropdowns
-  'features/documents',         // Depends on vehicles; provides documents table
+  'features/user-profile',      // User profile management; needed by documents migration
+  'features/documents',         // Depends on vehicles, user-profile; provides documents table
   'core/user-preferences',      // Depends on update_updated_at_column()
   'features/fuel-logs',         // Depends on vehicles
   'features/maintenance',       // Depends on vehicles
@@ -25,7 +26,12 @@ const MIGRATION_ORDER = [
   'features/admin',             // Admin role management and oversight; depends on update_updated_at_column()
   'features/backup',            // Admin backup feature; depends on update_updated_at_column()
   'features/notifications',     // Depends on maintenance and documents
-  'features/user-profile',      // User profile management; independent
+  'features/email-ingestion',   // Depends on documents, notifications (extends email_templates)
+  'features/terms-agreement',   // Terms & Conditions acceptance audit trail
+  'features/audit-log',         // Centralized audit logging; independent
+  'features/ownership-costs',   // Depends on vehicles and documents; TCO recurring costs
+  'features/subscriptions',     // Stripe subscriptions; depends on user-profile, vehicles
+  'core/identity-migration',    // Cross-cutting UUID migration; must run after all feature tables exist
 ];
 
 // Base directory where migrations are copied inside the image (set by Dockerfile)

backend/src/app.ts

@@ -10,6 +10,7 @@ import fastifyMultipart from '@fastify/multipart';
 // Core plugins
 import authPlugin from './core/plugins/auth.plugin';
 import adminGuardPlugin, { setAdminGuardPool } from './core/plugins/admin-guard.plugin';
+import tierGuardPlugin from './core/plugins/tier-guard.plugin';
 import loggingPlugin from './core/plugins/logging.plugin';
 import errorPlugin from './core/plugins/error.plugin';
 import { appConfig } from './core/config/config-loader';
@@ -24,12 +25,19 @@ import { documentsRoutes } from './features/documents/api/documents.routes';
 import { maintenanceRoutes } from './features/maintenance';
 import { platformRoutes } from './features/platform';
 import { adminRoutes } from './features/admin/api/admin.routes';
+import { auditLogRoutes } from './features/audit-log/api/audit-log.routes';
 import { notificationsRoutes } from './features/notifications';
 import { userProfileRoutes } from './features/user-profile';
 import { onboardingRoutes } from './features/onboarding';
 import { userPreferencesRoutes } from './features/user-preferences';
 import { userExportRoutes } from './features/user-export';
+import { userImportRoutes } from './features/user-import';
+import { ownershipCostsRoutes } from './features/ownership-costs';
+import { subscriptionsRoutes, donationsRoutes, webhooksRoutes } from './features/subscriptions';
+import { ocrRoutes } from './features/ocr';
+import { emailIngestionWebhookRoutes, emailIngestionRoutes } from './features/email-ingestion';
 import { pool } from './core/config/database';
+import { configRoutes } from './core/config/config.routes';
 
 async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify({
@@ -80,13 +88,16 @@ async function buildApp(): Promise<FastifyInstance> {
   await app.register(adminGuardPlugin);
   setAdminGuardPool(pool);
 
+  // Tier guard plugin - for subscription tier enforcement
+  await app.register(tierGuardPlugin);
+
   // Health check
   app.get('/health', async (_request, reply) => {
     return reply.code(200).send({
       status: 'healthy',
       timestamp: new Date().toISOString(),
       environment: process.env['NODE_ENV'],
-      features: ['admin', 'auth', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export']
+      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs', 'subscriptions', 'donations', 'ocr', 'email-ingestion']
     });
   });
 
@@ -96,7 +107,7 @@ async function buildApp(): Promise<FastifyInstance> {
       status: 'healthy',
       scope: 'api',
       timestamp: new Date().toISOString(),
-      features: ['admin', 'auth', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export']
+      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs', 'subscriptions', 'donations', 'ocr', 'email-ingestion']
     });
   });
 
@@ -132,10 +143,20 @@ async function buildApp(): Promise<FastifyInstance> {
   await app.register(communityStationsRoutes, { prefix: '/api' });
   await app.register(maintenanceRoutes, { prefix: '/api' });
   await app.register(adminRoutes, { prefix: '/api' });
+  await app.register(auditLogRoutes, { prefix: '/api' });
   await app.register(notificationsRoutes, { prefix: '/api' });
   await app.register(userProfileRoutes, { prefix: '/api' });
   await app.register(userPreferencesRoutes, { prefix: '/api' });
   await app.register(userExportRoutes, { prefix: '/api' });
+  await app.register(userImportRoutes, { prefix: '/api' });
+  await app.register(ownershipCostsRoutes, { prefix: '/api' });
+  await app.register(subscriptionsRoutes, { prefix: '/api' });
+  await app.register(donationsRoutes, { prefix: '/api' });
+  await app.register(webhooksRoutes, { prefix: '/api' });
+  await app.register(emailIngestionWebhookRoutes, { prefix: '/api' });
+  await app.register(emailIngestionRoutes, { prefix: '/api' });
+  await app.register(ocrRoutes, { prefix: '/api' });
+  await app.register(configRoutes, { prefix: '/api' });
 
   // 404 handler
   app.setNotFoundHandler(async (_request, reply) => {

backend/src/core/CLAUDE.md

@@ -0,0 +1,20 @@
+# backend/src/core/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Core module index with code examples | Understanding core infrastructure |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `auth/` | Authentication utilities | JWT handling, user context |
+| `config/` | Configuration loading (env, database, redis) and feature tier gating (fuelLog.receiptScan, document.scanMaintenanceSchedule, vehicle.vinDecode) | Environment setup, connection pools, tier requirements |
+| `logging/` | Winston structured logging | Log configuration, debugging |
+| `middleware/` | Fastify middleware | Request processing, user extraction |
+| `plugins/` | Fastify plugins (auth, error, logging, tier guard) | Plugin registration, hooks, tier gating |
+| `scheduler/` | Job scheduling infrastructure | Scheduled tasks, cron jobs |
+| `storage/` | Storage abstraction and adapters | File storage, S3/filesystem |
+| `user-preferences/` | User preferences data and migrations | User settings storage |

backend/src/core/config/config-loader.ts

@@ -41,14 +41,6 @@ const configSchema = z.object({
     audience: z.string(),
   }),
 
-  // External APIs configuration (optional)
-  external: z.object({
-    vpic: z.object({
-      url: z.string(),
-      timeout: z.string(),
-    }).optional(),
-  }).optional(),
-
   // Service configuration
   service: z.object({
     name: z.string(),
@@ -126,6 +118,10 @@ const secretsSchema = z.object({
   auth0_management_client_secret: z.string(),
   google_maps_api_key: z.string(),
   resend_api_key: z.string(),
+  resend_webhook_secret: z.string().optional(),
+  // Stripe secrets (API keys only - price IDs are config, not secrets)
+  stripe_secret_key: z.string(),
+  stripe_webhook_secret: z.string(),
 });
 
 type Config = z.infer<typeof configSchema>;
@@ -140,6 +136,14 @@ export interface AppConfiguration {
   getRedisUrl(): string;
   getAuth0Config(): { domain: string; audience: string; clientSecret: string };
   getAuth0ManagementConfig(): { domain: string; clientId: string; clientSecret: string };
+  getResendConfig(): {
+    apiKey: string;
+    webhookSecret: string | undefined;
+  };
+  getStripeConfig(): {
+    secretKey: string;
+    webhookSecret: string;
+  };
 }
 
 class ConfigurationLoader {
@@ -178,6 +182,9 @@ class ConfigurationLoader {
       'auth0-management-client-secret',
       'google-maps-api-key',
       'resend-api-key',
+      'resend-webhook-secret',
+      'stripe-secret-key',
+      'stripe-webhook-secret',
     ];
 
     for (const secretFile of secretFiles) {
@@ -240,10 +247,27 @@ class ConfigurationLoader {
           clientSecret: secrets.auth0_management_client_secret,
         };
       },
+
+      getResendConfig() {
+        return {
+          apiKey: secrets.resend_api_key,
+          webhookSecret: secrets.resend_webhook_secret,
+        };
+      },
+
+      getStripeConfig() {
+        return {
+          secretKey: secrets.stripe_secret_key,
+          webhookSecret: secrets.stripe_webhook_secret,
+        };
+      },
     };
 
-    // Set RESEND_API_KEY in environment for EmailService
+    // Set Resend environment variables for EmailService and webhook verification
     process.env['RESEND_API_KEY'] = secrets.resend_api_key;
+    if (secrets.resend_webhook_secret) {
+      process.env['RESEND_WEBHOOK_SECRET'] = secrets.resend_webhook_secret;
+    }
 
     logger.info('Configuration loaded successfully', {
       configSource: 'yaml',

backend/src/core/config/config.routes.ts

@@ -0,0 +1,18 @@
+/**
+ * @ai-summary Configuration API routes
+ * @ai-context Exposes feature tier configuration for frontend consumption
+ */
+
+import { FastifyPluginAsync } from 'fastify';
+import { getAllFeatureConfigs, TIER_LEVELS } from './feature-tiers';
+
+export const configRoutes: FastifyPluginAsync = async (fastify) => {
+  // GET /api/config/feature-tiers - Get all feature tier configurations
+  // Public endpoint - no auth required (config is not sensitive)
+  fastify.get('/config/feature-tiers', async (_request, reply) => {
+    return reply.code(200).send({
+      tiers: TIER_LEVELS,
+      features: getAllFeatureConfigs(),
+    });
+  });
+};

backend/src/core/config/feature-tiers.ts

@@ -0,0 +1,160 @@
+/**
+ * @ai-summary Feature tier configuration and utilities
+ * @ai-context Defines feature-to-tier mapping for gating premium features
+ */
+
+import { SubscriptionTier } from '../../features/user-profile/domain/user-profile.types';
+
+// Tier hierarchy: higher number = higher access level
+export const TIER_LEVELS: Record<SubscriptionTier, number> = {
+  free: 0,
+  pro: 1,
+  enterprise: 2,
+} as const;
+
+// Feature configuration interface
+export interface FeatureConfig {
+  minTier: SubscriptionTier;
+  name: string;
+  upgradePrompt: string;
+}
+
+// Feature registry - add new gated features here
+export const FEATURE_TIERS: Record<string, FeatureConfig> = {
+  'document.scanMaintenanceSchedule': {
+    minTier: 'pro',
+    name: 'Scan for Maintenance Schedule',
+    upgradePrompt: 'Upgrade to Pro to automatically extract maintenance schedules from your vehicle manuals.',
+  },
+  'vehicle.vinDecode': {
+    minTier: 'pro',
+    name: 'VIN Decode',
+    upgradePrompt: 'Upgrade to Pro to automatically decode VIN and populate vehicle details from the vehicle database.',
+  },
+  'fuelLog.receiptScan': {
+    minTier: 'pro',
+    name: 'Receipt Scan',
+    upgradePrompt: 'Upgrade to Pro to scan fuel receipts and auto-fill your fuel log entries.',
+  },
+  'maintenance.receiptScan': {
+    minTier: 'pro',
+    name: 'Maintenance Receipt Scan',
+    upgradePrompt: 'Upgrade to Pro to scan maintenance receipts and extract service details automatically.',
+  },
+} as const;
+
+/**
+ * Get numeric level for a subscription tier
+ */
+export function getTierLevel(tier: SubscriptionTier): number {
+  return TIER_LEVELS[tier] ?? 0;
+}
+
+/**
+ * Check if a user tier can access a feature
+ * Higher tiers inherit access to all lower tier features
+ */
+export function canAccessFeature(userTier: SubscriptionTier, featureKey: string): boolean {
+  const feature = FEATURE_TIERS[featureKey];
+  if (!feature) {
+    // Unknown features are accessible by all (fail open for unlisted features)
+    return true;
+  }
+  return getTierLevel(userTier) >= getTierLevel(feature.minTier);
+}
+
+/**
+ * Get the minimum required tier for a feature
+ * Returns null if feature is not gated
+ */
+export function getRequiredTier(featureKey: string): SubscriptionTier | null {
+  const feature = FEATURE_TIERS[featureKey];
+  return feature?.minTier ?? null;
+}
+
+/**
+ * Get full feature configuration
+ * Returns undefined if feature is not registered
+ */
+export function getFeatureConfig(featureKey: string): FeatureConfig | undefined {
+  return FEATURE_TIERS[featureKey];
+}
+
+/**
+ * Get all feature configurations (for API endpoint)
+ */
+export function getAllFeatureConfigs(): Record<string, FeatureConfig> {
+  return { ...FEATURE_TIERS };
+}
+
+// Vehicle limits per tier
+// null indicates unlimited (enterprise tier)
+export const VEHICLE_LIMITS: Record<SubscriptionTier, number | null> = {
+  free: 2,
+  pro: 5,
+  enterprise: null,
+} as const;
+
+/**
+ * Vehicle limits vary by subscription tier and must be queryable
+ * at runtime for both backend enforcement and frontend UI state.
+ *
+ * @param tier - User's subscription tier
+ * @returns Maximum vehicles allowed, or null for unlimited (enterprise tier)
+ */
+export function getVehicleLimit(tier: SubscriptionTier): number | null {
+  return VEHICLE_LIMITS[tier] ?? null;
+}
+
+/**
+ * Check if a user can add another vehicle based on their tier and current count.
+ *
+ * @param tier - User's subscription tier
+ * @param currentCount - Number of vehicles user currently has
+ * @returns true if user can add another vehicle, false if at/over limit
+ */
+export function canAddVehicle(tier: SubscriptionTier, currentCount: number): boolean {
+  const limit = getVehicleLimit(tier);
+  // null limit means unlimited (enterprise)
+  if (limit === null) {
+    return true;
+  }
+  return currentCount < limit;
+}
+
+/**
+ * Vehicle limit configuration with upgrade prompt.
+ * Structure supports additional resource types in the future.
+ */
+export interface VehicleLimitConfig {
+  limit: number | null;
+  tier: SubscriptionTier;
+  upgradePrompt: string;
+}
+
+/**
+ * Get vehicle limit configuration with upgrade prompt for a tier.
+ *
+ * @param tier - User's subscription tier
+ * @returns Configuration with limit and upgrade prompt
+ */
+export function getVehicleLimitConfig(tier: SubscriptionTier): VehicleLimitConfig {
+  const limit = getVehicleLimit(tier);
+
+  const defaultPrompt = 'Upgrade to access additional vehicles.';
+
+  let upgradePrompt: string;
+  if (tier === 'free') {
+    upgradePrompt = 'Free tier is limited to 2 vehicles. Upgrade to Pro for up to 5 vehicles, or Enterprise for unlimited.';
+  } else if (tier === 'pro') {
+    upgradePrompt = 'Pro tier is limited to 5 vehicles. Upgrade to Enterprise for unlimited vehicles.';
+  } else {
+    upgradePrompt = defaultPrompt;
+  }
+
+  return {
+    limit,
+    tier,
+    upgradePrompt,
+  };
+}

backend/src/core/config/tests/feature-tiers.test.ts

@@ -0,0 +1,225 @@
+import {
+  TIER_LEVELS,
+  FEATURE_TIERS,
+  VEHICLE_LIMITS,
+  getTierLevel,
+  canAccessFeature,
+  getRequiredTier,
+  getFeatureConfig,
+  getAllFeatureConfigs,
+  getVehicleLimit,
+  canAddVehicle,
+  getVehicleLimitConfig,
+} from '../feature-tiers';
+
+describe('feature-tiers', () => {
+  describe('TIER_LEVELS', () => {
+    it('defines correct tier hierarchy', () => {
+      expect(TIER_LEVELS.free).toBe(0);
+      expect(TIER_LEVELS.pro).toBe(1);
+      expect(TIER_LEVELS.enterprise).toBe(2);
+    });
+
+    it('enterprise > pro > free', () => {
+      expect(TIER_LEVELS.enterprise).toBeGreaterThan(TIER_LEVELS.pro);
+      expect(TIER_LEVELS.pro).toBeGreaterThan(TIER_LEVELS.free);
+    });
+  });
+
+  describe('FEATURE_TIERS', () => {
+    it('includes scanMaintenanceSchedule feature', () => {
+      const feature = FEATURE_TIERS['document.scanMaintenanceSchedule'];
+      expect(feature).toBeDefined();
+      expect(feature.minTier).toBe('pro');
+      expect(feature.name).toBe('Scan for Maintenance Schedule');
+      expect(feature.upgradePrompt).toBeTruthy();
+    });
+
+    it('includes fuelLog.receiptScan feature', () => {
+      const feature = FEATURE_TIERS['fuelLog.receiptScan'];
+      expect(feature).toBeDefined();
+      expect(feature.minTier).toBe('pro');
+      expect(feature.name).toBe('Receipt Scan');
+      expect(feature.upgradePrompt).toBeTruthy();
+    });
+  });
+
+  describe('canAccessFeature - fuelLog.receiptScan', () => {
+    const featureKey = 'fuelLog.receiptScan';
+
+    it('denies access for free tier user', () => {
+      expect(canAccessFeature('free', featureKey)).toBe(false);
+    });
+
+    it('allows access for pro tier user', () => {
+      expect(canAccessFeature('pro', featureKey)).toBe(true);
+    });
+
+    it('allows access for enterprise tier user (inherits pro)', () => {
+      expect(canAccessFeature('enterprise', featureKey)).toBe(true);
+    });
+  });
+
+  describe('getTierLevel', () => {
+    it('returns correct level for each tier', () => {
+      expect(getTierLevel('free')).toBe(0);
+      expect(getTierLevel('pro')).toBe(1);
+      expect(getTierLevel('enterprise')).toBe(2);
+    });
+
+    it('returns 0 for unknown tier', () => {
+      expect(getTierLevel('unknown' as any)).toBe(0);
+    });
+  });
+
+  describe('canAccessFeature', () => {
+    const featureKey = 'document.scanMaintenanceSchedule';
+
+    it('denies access for free tier to pro feature', () => {
+      expect(canAccessFeature('free', featureKey)).toBe(false);
+    });
+
+    it('allows access for pro tier to pro feature', () => {
+      expect(canAccessFeature('pro', featureKey)).toBe(true);
+    });
+
+    it('allows access for enterprise tier to pro feature (inheritance)', () => {
+      expect(canAccessFeature('enterprise', featureKey)).toBe(true);
+    });
+
+    it('allows access for unknown feature (fail open)', () => {
+      expect(canAccessFeature('free', 'unknown.feature')).toBe(true);
+      expect(canAccessFeature('pro', 'unknown.feature')).toBe(true);
+      expect(canAccessFeature('enterprise', 'unknown.feature')).toBe(true);
+    });
+  });
+
+  describe('getRequiredTier', () => {
+    it('returns required tier for known feature', () => {
+      expect(getRequiredTier('document.scanMaintenanceSchedule')).toBe('pro');
+    });
+
+    it('returns null for unknown feature', () => {
+      expect(getRequiredTier('unknown.feature')).toBeNull();
+    });
+  });
+
+  describe('getFeatureConfig', () => {
+    it('returns full config for known feature', () => {
+      const config = getFeatureConfig('document.scanMaintenanceSchedule');
+      expect(config).toEqual({
+        minTier: 'pro',
+        name: 'Scan for Maintenance Schedule',
+        upgradePrompt: expect.any(String),
+      });
+    });
+
+    it('returns undefined for unknown feature', () => {
+      expect(getFeatureConfig('unknown.feature')).toBeUndefined();
+    });
+  });
+
+  describe('getAllFeatureConfigs', () => {
+    it('returns copy of all feature configs', () => {
+      const configs = getAllFeatureConfigs();
+      expect(configs['document.scanMaintenanceSchedule']).toBeDefined();
+
+      // Verify it's a copy, not the original
+      configs['test'] = { minTier: 'free', name: 'test', upgradePrompt: '' };
+      expect(FEATURE_TIERS['test' as keyof typeof FEATURE_TIERS]).toBeUndefined();
+    });
+  });
+
+  describe('VEHICLE_LIMITS', () => {
+    it('defines correct limits for each tier', () => {
+      expect(VEHICLE_LIMITS.free).toBe(2);
+      expect(VEHICLE_LIMITS.pro).toBe(5);
+      expect(VEHICLE_LIMITS.enterprise).toBeNull();
+    });
+  });
+
+  describe('getVehicleLimit', () => {
+    it('returns 2 for free tier', () => {
+      expect(getVehicleLimit('free')).toBe(2);
+    });
+
+    it('returns 5 for pro tier', () => {
+      expect(getVehicleLimit('pro')).toBe(5);
+    });
+
+    it('returns null for enterprise tier (unlimited)', () => {
+      expect(getVehicleLimit('enterprise')).toBeNull();
+    });
+  });
+
+  describe('canAddVehicle', () => {
+    describe('free tier (limit 2)', () => {
+      it('returns true when below limit', () => {
+        expect(canAddVehicle('free', 0)).toBe(true);
+        expect(canAddVehicle('free', 1)).toBe(true);
+      });
+
+      it('returns false when at limit', () => {
+        expect(canAddVehicle('free', 2)).toBe(false);
+      });
+
+      it('returns false when over limit', () => {
+        expect(canAddVehicle('free', 3)).toBe(false);
+      });
+    });
+
+    describe('pro tier (limit 5)', () => {
+      it('returns true when below limit', () => {
+        expect(canAddVehicle('pro', 0)).toBe(true);
+        expect(canAddVehicle('pro', 4)).toBe(true);
+      });
+
+      it('returns false when at limit', () => {
+        expect(canAddVehicle('pro', 5)).toBe(false);
+      });
+
+      it('returns false when over limit', () => {
+        expect(canAddVehicle('pro', 6)).toBe(false);
+      });
+    });
+
+    describe('enterprise tier (unlimited)', () => {
+      it('always returns true regardless of count', () => {
+        expect(canAddVehicle('enterprise', 0)).toBe(true);
+        expect(canAddVehicle('enterprise', 100)).toBe(true);
+        expect(canAddVehicle('enterprise', 999999)).toBe(true);
+      });
+    });
+  });
+
+  describe('getVehicleLimitConfig', () => {
+    it('returns correct config for free tier', () => {
+      const config = getVehicleLimitConfig('free');
+      expect(config.limit).toBe(2);
+      expect(config.tier).toBe('free');
+      expect(config.upgradePrompt).toContain('Free tier is limited to 2 vehicles');
+      expect(config.upgradePrompt).toContain('Pro');
+      expect(config.upgradePrompt).toContain('Enterprise');
+    });
+
+    it('returns correct config for pro tier', () => {
+      const config = getVehicleLimitConfig('pro');
+      expect(config.limit).toBe(5);
+      expect(config.tier).toBe('pro');
+      expect(config.upgradePrompt).toContain('Pro tier is limited to 5 vehicles');
+      expect(config.upgradePrompt).toContain('Enterprise');
+    });
+
+    it('returns correct config for enterprise tier', () => {
+      const config = getVehicleLimitConfig('enterprise');
+      expect(config.limit).toBeNull();
+      expect(config.tier).toBe('enterprise');
+      expect(config.upgradePrompt).toBeTruthy();
+    });
+
+    it('provides default upgradePrompt fallback', () => {
+      const config = getVehicleLimitConfig('enterprise');
+      expect(config.upgradePrompt).toBe('Upgrade to access additional vehicles.');
+    });
+  });
+});

backend/src/core/identity-migration/migrations/001_migrate_user_id_to_uuid.sql

@@ -0,0 +1,404 @@
+-- Migration: 001_migrate_user_id_to_uuid.sql
+-- Feature: identity-migration (cross-cutting)
+-- Description: Migrate all user identity columns from VARCHAR(255) storing auth0_sub
+--              to UUID referencing user_profiles.id. Admin tables restructured with UUID PKs.
+-- Requires: All feature tables must exist (runs last in MIGRATION_ORDER)
+
+BEGIN;
+
+-- ============================================================================
+-- PHASE 1: Add new UUID columns alongside existing VARCHAR columns
+-- ============================================================================
+
+-- 1a. Feature tables (17 tables with user_id VARCHAR)
+ALTER TABLE vehicles ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE fuel_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE maintenance_records ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE maintenance_schedules ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE documents ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE notification_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE user_notifications ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE user_preferences ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE saved_stations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE ownership_costs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE email_ingestion_queue ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE pending_vehicle_associations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE subscriptions ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE donations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE tier_vehicle_selections ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE terms_agreements ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+
+-- 1b. Special user-reference columns (submitted_by/reported_by store auth0_sub)
+ALTER TABLE community_stations ADD COLUMN IF NOT EXISTS submitted_by_uuid UUID;
+ALTER TABLE station_removal_reports ADD COLUMN IF NOT EXISTS reported_by_uuid UUID;
+
+-- 1c. Admin table: add id UUID and user_profile_id UUID
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS id UUID;
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+
+-- 1d. Admin-referencing columns: add UUID equivalents
+ALTER TABLE admin_audit_logs ADD COLUMN IF NOT EXISTS actor_admin_uuid UUID;
+ALTER TABLE admin_audit_logs ADD COLUMN IF NOT EXISTS target_admin_uuid UUID;
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS created_by_uuid UUID;
+ALTER TABLE community_stations ADD COLUMN IF NOT EXISTS reviewed_by_uuid UUID;
+ALTER TABLE backup_history ADD COLUMN IF NOT EXISTS created_by_uuid UUID;
+ALTER TABLE platform_change_log ADD COLUMN IF NOT EXISTS changed_by_uuid UUID;
+ALTER TABLE user_profiles ADD COLUMN IF NOT EXISTS deactivated_by_uuid UUID;
+
+
+-- ============================================================================
+-- PHASE 2: Backfill UUID values from user_profiles join
+-- ============================================================================
+
+-- 2a. Feature tables: map user_id (auth0_sub) -> user_profiles.id (UUID)
+UPDATE vehicles SET user_profile_id = up.id
+  FROM user_profiles up WHERE vehicles.user_id = up.auth0_sub AND vehicles.user_profile_id IS NULL;
+
+UPDATE fuel_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE fuel_logs.user_id = up.auth0_sub AND fuel_logs.user_profile_id IS NULL;
+
+UPDATE maintenance_records SET user_profile_id = up.id
+  FROM user_profiles up WHERE maintenance_records.user_id = up.auth0_sub AND maintenance_records.user_profile_id IS NULL;
+
+UPDATE maintenance_schedules SET user_profile_id = up.id
+  FROM user_profiles up WHERE maintenance_schedules.user_id = up.auth0_sub AND maintenance_schedules.user_profile_id IS NULL;
+
+UPDATE documents SET user_profile_id = up.id
+  FROM user_profiles up WHERE documents.user_id = up.auth0_sub AND documents.user_profile_id IS NULL;
+
+UPDATE notification_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE notification_logs.user_id = up.auth0_sub AND notification_logs.user_profile_id IS NULL;
+
+UPDATE user_notifications SET user_profile_id = up.id
+  FROM user_profiles up WHERE user_notifications.user_id = up.auth0_sub AND user_notifications.user_profile_id IS NULL;
+
+UPDATE user_preferences SET user_profile_id = up.id
+  FROM user_profiles up WHERE user_preferences.user_id = up.auth0_sub AND user_preferences.user_profile_id IS NULL;
+
+-- 2a-fix. user_preferences has rows where user_id already contains user_profiles.id (UUID)
+-- instead of auth0_sub. Match these directly by casting to UUID.
+UPDATE user_preferences SET user_profile_id = up.id
+  FROM user_profiles up
+  WHERE user_preferences.user_id ~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    AND user_preferences.user_id::uuid = up.id
+    AND user_preferences.user_profile_id IS NULL;
+
+-- Delete truly orphaned user_preferences (UUID user_id with no matching user_profile)
+DELETE FROM user_preferences
+  WHERE user_profile_id IS NULL
+    AND user_id ~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    AND NOT EXISTS (SELECT 1 FROM user_profiles WHERE id = user_preferences.user_id::uuid);
+
+-- Deduplicate user_preferences: same user may have both an auth0_sub row and
+-- a UUID row, both now mapping to the same user_profile_id. Keep the newest.
+DELETE FROM user_preferences a
+  USING user_preferences b
+  WHERE a.user_profile_id = b.user_profile_id
+    AND a.user_profile_id IS NOT NULL
+    AND (a.updated_at < b.updated_at OR (a.updated_at = b.updated_at AND a.id < b.id));
+
+UPDATE saved_stations SET user_profile_id = up.id
+  FROM user_profiles up WHERE saved_stations.user_id = up.auth0_sub AND saved_stations.user_profile_id IS NULL;
+
+UPDATE audit_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE audit_logs.user_id = up.auth0_sub AND audit_logs.user_profile_id IS NULL;
+
+UPDATE ownership_costs SET user_profile_id = up.id
+  FROM user_profiles up WHERE ownership_costs.user_id = up.auth0_sub AND ownership_costs.user_profile_id IS NULL;
+
+UPDATE email_ingestion_queue SET user_profile_id = up.id
+  FROM user_profiles up WHERE email_ingestion_queue.user_id = up.auth0_sub AND email_ingestion_queue.user_profile_id IS NULL;
+
+UPDATE pending_vehicle_associations SET user_profile_id = up.id
+  FROM user_profiles up WHERE pending_vehicle_associations.user_id = up.auth0_sub AND pending_vehicle_associations.user_profile_id IS NULL;
+
+UPDATE subscriptions SET user_profile_id = up.id
+  FROM user_profiles up WHERE subscriptions.user_id = up.auth0_sub AND subscriptions.user_profile_id IS NULL;
+
+UPDATE donations SET user_profile_id = up.id
+  FROM user_profiles up WHERE donations.user_id = up.auth0_sub AND donations.user_profile_id IS NULL;
+
+UPDATE tier_vehicle_selections SET user_profile_id = up.id
+  FROM user_profiles up WHERE tier_vehicle_selections.user_id = up.auth0_sub AND tier_vehicle_selections.user_profile_id IS NULL;
+
+UPDATE terms_agreements SET user_profile_id = up.id
+  FROM user_profiles up WHERE terms_agreements.user_id = up.auth0_sub AND terms_agreements.user_profile_id IS NULL;
+
+-- 2b. Special user columns
+UPDATE community_stations SET submitted_by_uuid = up.id
+  FROM user_profiles up WHERE community_stations.submitted_by = up.auth0_sub AND community_stations.submitted_by_uuid IS NULL;
+
+UPDATE station_removal_reports SET reported_by_uuid = up.id
+  FROM user_profiles up WHERE station_removal_reports.reported_by = up.auth0_sub AND station_removal_reports.reported_by_uuid IS NULL;
+
+
+-- ============================================================================
+-- PHASE 3: Admin-specific transformations
+-- ============================================================================
+
+-- 3a. Create user_profiles entries for any admin_users that lack one
+INSERT INTO user_profiles (auth0_sub, email)
+SELECT au.auth0_sub, au.email
+FROM admin_users au
+WHERE NOT EXISTS (
+  SELECT 1 FROM user_profiles up WHERE up.auth0_sub = au.auth0_sub
+)
+ON CONFLICT (auth0_sub) DO NOTHING;
+
+-- 3b. Populate admin_users.id (DEFAULT doesn't auto-fill on ALTER ADD COLUMN for existing rows)
+UPDATE admin_users SET id = uuid_generate_v4() WHERE id IS NULL;
+
+-- 3c. Backfill admin_users.user_profile_id from user_profiles join
+UPDATE admin_users SET user_profile_id = up.id
+  FROM user_profiles up WHERE admin_users.auth0_sub = up.auth0_sub AND admin_users.user_profile_id IS NULL;
+
+-- 3d. Backfill admin-referencing columns: map auth0_sub -> admin_users.id UUID
+UPDATE admin_audit_logs SET actor_admin_uuid = au.id
+  FROM admin_users au WHERE admin_audit_logs.actor_admin_id = au.auth0_sub AND admin_audit_logs.actor_admin_uuid IS NULL;
+
+UPDATE admin_audit_logs SET target_admin_uuid = au.id
+  FROM admin_users au WHERE admin_audit_logs.target_admin_id = au.auth0_sub AND admin_audit_logs.target_admin_uuid IS NULL;
+
+UPDATE admin_users au SET created_by_uuid = creator.id
+  FROM admin_users creator WHERE au.created_by = creator.auth0_sub AND au.created_by_uuid IS NULL;
+
+UPDATE community_stations SET reviewed_by_uuid = au.id
+  FROM admin_users au WHERE community_stations.reviewed_by = au.auth0_sub AND community_stations.reviewed_by_uuid IS NULL;
+
+UPDATE backup_history SET created_by_uuid = au.id
+  FROM admin_users au WHERE backup_history.created_by = au.auth0_sub AND backup_history.created_by_uuid IS NULL;
+
+UPDATE platform_change_log SET changed_by_uuid = au.id
+  FROM admin_users au WHERE platform_change_log.changed_by = au.auth0_sub AND platform_change_log.changed_by_uuid IS NULL;
+
+UPDATE user_profiles SET deactivated_by_uuid = au.id
+  FROM admin_users au WHERE user_profiles.deactivated_by = au.auth0_sub AND user_profiles.deactivated_by_uuid IS NULL;
+
+
+-- ============================================================================
+-- PHASE 4: Add constraints
+-- ============================================================================
+
+-- 4a. Set NOT NULL on feature table UUID columns (audit_logs stays nullable)
+ALTER TABLE vehicles ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE fuel_logs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE maintenance_records ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE maintenance_schedules ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE documents ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE notification_logs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE user_notifications ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE user_preferences ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE saved_stations ALTER COLUMN user_profile_id SET NOT NULL;
+-- audit_logs.user_profile_id stays NULLABLE (system actions have no user)
+ALTER TABLE ownership_costs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE email_ingestion_queue ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE pending_vehicle_associations ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE subscriptions ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE donations ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE tier_vehicle_selections ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE terms_agreements ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE community_stations ALTER COLUMN submitted_by_uuid SET NOT NULL;
+ALTER TABLE station_removal_reports ALTER COLUMN reported_by_uuid SET NOT NULL;
+
+-- 4b. Admin table NOT NULL constraints
+ALTER TABLE admin_users ALTER COLUMN id SET NOT NULL;
+ALTER TABLE admin_users ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE admin_audit_logs ALTER COLUMN actor_admin_uuid SET NOT NULL;
+-- target_admin_uuid stays nullable (some actions have no target)
+-- created_by_uuid stays nullable (bootstrap admin may not have a creator)
+ALTER TABLE platform_change_log ALTER COLUMN changed_by_uuid SET NOT NULL;
+
+-- 4c. Admin table PK transformation
+ALTER TABLE admin_users DROP CONSTRAINT admin_users_pkey;
+ALTER TABLE admin_users ADD PRIMARY KEY (id);
+
+-- 4d. Add FK constraints to user_profiles(id) with ON DELETE CASCADE
+ALTER TABLE vehicles ADD CONSTRAINT fk_vehicles_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE fuel_logs ADD CONSTRAINT fk_fuel_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE maintenance_records ADD CONSTRAINT fk_maintenance_records_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE maintenance_schedules ADD CONSTRAINT fk_maintenance_schedules_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE documents ADD CONSTRAINT fk_documents_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE notification_logs ADD CONSTRAINT fk_notification_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE user_notifications ADD CONSTRAINT fk_user_notifications_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE user_preferences ADD CONSTRAINT fk_user_preferences_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE saved_stations ADD CONSTRAINT fk_saved_stations_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE audit_logs ADD CONSTRAINT fk_audit_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE ownership_costs ADD CONSTRAINT fk_ownership_costs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE email_ingestion_queue ADD CONSTRAINT fk_email_ingestion_queue_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE pending_vehicle_associations ADD CONSTRAINT fk_pending_vehicle_assoc_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE subscriptions ADD CONSTRAINT fk_subscriptions_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE donations ADD CONSTRAINT fk_donations_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE tier_vehicle_selections ADD CONSTRAINT fk_tier_vehicle_selections_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE terms_agreements ADD CONSTRAINT fk_terms_agreements_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE community_stations ADD CONSTRAINT fk_community_stations_submitted_by
+  FOREIGN KEY (submitted_by_uuid) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE station_removal_reports ADD CONSTRAINT fk_station_removal_reports_reported_by
+  FOREIGN KEY (reported_by_uuid) REFERENCES user_profiles(id) ON DELETE CASCADE;
+
+-- 4e. Admin FK constraints
+ALTER TABLE admin_users ADD CONSTRAINT fk_admin_users_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id);
+ALTER TABLE admin_users ADD CONSTRAINT uq_admin_users_user_profile_id
+  UNIQUE (user_profile_id);
+
+
+-- ============================================================================
+-- PHASE 5: Drop old columns, rename new ones, recreate indexes
+-- ============================================================================
+
+-- 5a. Drop old FK constraints on VARCHAR user_id columns
+ALTER TABLE subscriptions DROP CONSTRAINT IF EXISTS fk_subscriptions_user_id;
+ALTER TABLE donations DROP CONSTRAINT IF EXISTS fk_donations_user_id;
+ALTER TABLE tier_vehicle_selections DROP CONSTRAINT IF EXISTS fk_tier_vehicle_selections_user_id;
+
+-- 5b. Drop old UNIQUE constraints involving VARCHAR columns
+ALTER TABLE vehicles DROP CONSTRAINT IF EXISTS unique_user_vin;
+ALTER TABLE saved_stations DROP CONSTRAINT IF EXISTS unique_user_station;
+ALTER TABLE user_preferences DROP CONSTRAINT IF EXISTS user_preferences_user_id_key;
+ALTER TABLE station_removal_reports DROP CONSTRAINT IF EXISTS unique_user_station_report;
+
+-- 5c. Drop old indexes on VARCHAR columns
+DROP INDEX IF EXISTS idx_vehicles_user_id;
+DROP INDEX IF EXISTS idx_fuel_logs_user_id;
+DROP INDEX IF EXISTS idx_maintenance_records_user_id;
+DROP INDEX IF EXISTS idx_maintenance_schedules_user_id;
+DROP INDEX IF EXISTS idx_documents_user_id;
+DROP INDEX IF EXISTS idx_documents_user_vehicle;
+DROP INDEX IF EXISTS idx_notification_logs_user_id;
+DROP INDEX IF EXISTS idx_user_notifications_user_id;
+DROP INDEX IF EXISTS idx_user_notifications_unread;
+DROP INDEX IF EXISTS idx_user_preferences_user_id;
+DROP INDEX IF EXISTS idx_saved_stations_user_id;
+DROP INDEX IF EXISTS idx_audit_logs_user_created;
+DROP INDEX IF EXISTS idx_ownership_costs_user_id;
+DROP INDEX IF EXISTS idx_email_ingestion_queue_user_id;
+DROP INDEX IF EXISTS idx_pending_vehicle_assoc_user_id;
+DROP INDEX IF EXISTS idx_subscriptions_user_id;
+DROP INDEX IF EXISTS idx_donations_user_id;
+DROP INDEX IF EXISTS idx_tier_vehicle_selections_user_id;
+DROP INDEX IF EXISTS idx_terms_agreements_user_id;
+DROP INDEX IF EXISTS idx_community_stations_submitted_by;
+DROP INDEX IF EXISTS idx_removal_reports_reported_by;
+DROP INDEX IF EXISTS idx_admin_audit_logs_actor_id;
+DROP INDEX IF EXISTS idx_admin_audit_logs_target_id;
+DROP INDEX IF EXISTS idx_platform_change_log_changed_by;
+
+-- 5d. Drop old VARCHAR user_id columns from feature tables
+ALTER TABLE vehicles DROP COLUMN user_id;
+ALTER TABLE fuel_logs DROP COLUMN user_id;
+ALTER TABLE maintenance_records DROP COLUMN user_id;
+ALTER TABLE maintenance_schedules DROP COLUMN user_id;
+ALTER TABLE documents DROP COLUMN user_id;
+ALTER TABLE notification_logs DROP COLUMN user_id;
+ALTER TABLE user_notifications DROP COLUMN user_id;
+ALTER TABLE user_preferences DROP COLUMN user_id;
+ALTER TABLE saved_stations DROP COLUMN user_id;
+ALTER TABLE audit_logs DROP COLUMN user_id;
+ALTER TABLE ownership_costs DROP COLUMN user_id;
+ALTER TABLE email_ingestion_queue DROP COLUMN user_id;
+ALTER TABLE pending_vehicle_associations DROP COLUMN user_id;
+ALTER TABLE subscriptions DROP COLUMN user_id;
+ALTER TABLE donations DROP COLUMN user_id;
+ALTER TABLE tier_vehicle_selections DROP COLUMN user_id;
+ALTER TABLE terms_agreements DROP COLUMN user_id;
+
+-- 5e. Rename user_profile_id -> user_id in feature tables
+ALTER TABLE vehicles RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE fuel_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE maintenance_records RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE maintenance_schedules RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE documents RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE notification_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE user_notifications RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE user_preferences RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE saved_stations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE audit_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE ownership_costs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE email_ingestion_queue RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE pending_vehicle_associations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE subscriptions RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE donations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE tier_vehicle_selections RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE terms_agreements RENAME COLUMN user_profile_id TO user_id;
+
+-- 5f. Drop and rename special user columns
+ALTER TABLE community_stations DROP COLUMN submitted_by;
+ALTER TABLE community_stations RENAME COLUMN submitted_by_uuid TO submitted_by;
+ALTER TABLE station_removal_reports DROP COLUMN reported_by;
+ALTER TABLE station_removal_reports RENAME COLUMN reported_by_uuid TO reported_by;
+
+-- 5g. Drop and rename admin-referencing columns
+ALTER TABLE admin_users DROP COLUMN auth0_sub;
+ALTER TABLE admin_users DROP COLUMN created_by;
+ALTER TABLE admin_users RENAME COLUMN created_by_uuid TO created_by;
+
+ALTER TABLE admin_audit_logs DROP COLUMN actor_admin_id;
+ALTER TABLE admin_audit_logs DROP COLUMN target_admin_id;
+ALTER TABLE admin_audit_logs RENAME COLUMN actor_admin_uuid TO actor_admin_id;
+ALTER TABLE admin_audit_logs RENAME COLUMN target_admin_uuid TO target_admin_id;
+
+ALTER TABLE community_stations DROP COLUMN reviewed_by;
+ALTER TABLE community_stations RENAME COLUMN reviewed_by_uuid TO reviewed_by;
+
+ALTER TABLE backup_history DROP COLUMN created_by;
+ALTER TABLE backup_history RENAME COLUMN created_by_uuid TO created_by;
+
+ALTER TABLE platform_change_log DROP COLUMN changed_by;
+ALTER TABLE platform_change_log RENAME COLUMN changed_by_uuid TO changed_by;
+
+ALTER TABLE user_profiles DROP COLUMN deactivated_by;
+ALTER TABLE user_profiles RENAME COLUMN deactivated_by_uuid TO deactivated_by;
+
+-- 5h. Recreate indexes on new UUID columns (feature tables)
+CREATE INDEX idx_vehicles_user_id ON vehicles(user_id);
+CREATE INDEX idx_fuel_logs_user_id ON fuel_logs(user_id);
+CREATE INDEX idx_maintenance_records_user_id ON maintenance_records(user_id);
+CREATE INDEX idx_maintenance_schedules_user_id ON maintenance_schedules(user_id);
+CREATE INDEX idx_documents_user_id ON documents(user_id);
+CREATE INDEX idx_documents_user_vehicle ON documents(user_id, vehicle_id);
+CREATE INDEX idx_notification_logs_user_id ON notification_logs(user_id);
+CREATE INDEX idx_user_notifications_user_id ON user_notifications(user_id);
+CREATE INDEX idx_user_notifications_unread ON user_notifications(user_id, created_at DESC) WHERE is_read = false;
+CREATE INDEX idx_user_preferences_user_id ON user_preferences(user_id);
+CREATE INDEX idx_saved_stations_user_id ON saved_stations(user_id);
+CREATE INDEX idx_audit_logs_user_created ON audit_logs(user_id, created_at DESC);
+CREATE INDEX idx_ownership_costs_user_id ON ownership_costs(user_id);
+CREATE INDEX idx_email_ingestion_queue_user_id ON email_ingestion_queue(user_id);
+CREATE INDEX idx_pending_vehicle_assoc_user_id ON pending_vehicle_associations(user_id);
+CREATE INDEX idx_subscriptions_user_id ON subscriptions(user_id);
+CREATE INDEX idx_donations_user_id ON donations(user_id);
+CREATE INDEX idx_tier_vehicle_selections_user_id ON tier_vehicle_selections(user_id);
+CREATE INDEX idx_terms_agreements_user_id ON terms_agreements(user_id);
+
+-- 5i. Recreate indexes on special columns
+CREATE INDEX idx_community_stations_submitted_by ON community_stations(submitted_by);
+CREATE INDEX idx_removal_reports_reported_by ON station_removal_reports(reported_by);
+CREATE INDEX idx_admin_audit_logs_actor_id ON admin_audit_logs(actor_admin_id);
+CREATE INDEX idx_admin_audit_logs_target_id ON admin_audit_logs(target_admin_id);
+CREATE INDEX idx_platform_change_log_changed_by ON platform_change_log(changed_by);
+
+-- 5j. Recreate UNIQUE constraints on new UUID columns
+ALTER TABLE vehicles ADD CONSTRAINT unique_user_vin UNIQUE(user_id, vin);
+ALTER TABLE saved_stations ADD CONSTRAINT unique_user_station UNIQUE(user_id, place_id);
+ALTER TABLE user_preferences ADD CONSTRAINT user_preferences_user_id_key UNIQUE(user_id);
+ALTER TABLE station_removal_reports ADD CONSTRAINT unique_user_station_report UNIQUE(station_id, reported_by);
+
+COMMIT;

backend/src/core/logging/logger.ts

@@ -1,24 +1,42 @@
 /**
- * @ai-summary Structured logging with Winston
+ * @ai-summary Structured logging with Pino (Winston-compatible wrapper)
- * @ai-context All features use this for consistent logging
+ * @ai-context All features use this for consistent logging. API maintains Winston compatibility.
  */
-import * as winston from 'winston';
+import pino from 'pino';
 
-export const logger = winston.createLogger({
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-  level: 'info',
+const validLevels: LogLevel[] = ['debug', 'info', 'warn', 'error'];
-  format: winston.format.combine(
+
-    winston.format.timestamp(),
+const rawLevel = (process.env.LOG_LEVEL?.toLowerCase() || 'info') as LogLevel;
-    winston.format.errors({ stack: true }),
+const level = validLevels.includes(rawLevel) ? rawLevel : 'info';
-    winston.format.json()
+
-  ),
+if (process.env.LOG_LEVEL && rawLevel !== level) {
-  defaultMeta: {
+  console.warn(`Invalid LOG_LEVEL "${process.env.LOG_LEVEL}", falling back to "info"`);
-    service: 'motovaultpro-backend',
+}
+
+const pinoLogger = pino({
+  level,
+  formatters: {
+    level: (label) => ({ level: label }),
   },
-  transports: [
+  timestamp: pino.stdTimeFunctions.isoTime,
-    new winston.transports.Console({
-      format: winston.format.json(),
-    }),
-  ],
 });
 
-export default logger;
+// Wrapper maintains logger.info(msg, meta) API for backward compatibility
+export const logger = {
+  info: (msg: string, meta?: object) => pinoLogger.info(meta || {}, msg),
+  warn: (msg: string, meta?: object) => pinoLogger.warn(meta || {}, msg),
+  error: (msg: string, meta?: object) => pinoLogger.error(meta || {}, msg),
+  debug: (msg: string, meta?: object) => pinoLogger.debug(meta || {}, msg),
+  child: (bindings: object) => {
+    const childPino = pinoLogger.child(bindings);
+    return {
+      info: (msg: string, meta?: object) => childPino.info(meta || {}, msg),
+      warn: (msg: string, meta?: object) => childPino.warn(meta || {}, msg),
+      error: (msg: string, meta?: object) => childPino.error(meta || {}, msg),
+      debug: (msg: string, meta?: object) => childPino.debug(meta || {}, msg),
+    };
+  },
+};
+
+export default logger;

backend/src/core/middleware/require-tier.test.ts

@@ -0,0 +1,191 @@
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { requireTier } from './require-tier';
+
+// Mock logger to suppress output during tests
+jest.mock('../logging/logger', () => ({
+  logger: {
+    error: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
+    info: jest.fn(),
+  },
+}));
+
+const createRequest = (subscriptionTier?: string): Partial<FastifyRequest> => {
+  if (subscriptionTier === undefined) {
+    return { userContext: undefined };
+  }
+  return {
+    userContext: {
+      userId: '550e8400-e29b-41d4-a716-446655440000',
+      email: 'user@example.com',
+      emailVerified: true,
+      onboardingCompleted: true,
+      isAdmin: false,
+      subscriptionTier: subscriptionTier as any,
+    },
+  };
+};
+
+const createReply = (): Partial<FastifyReply> & { statusCode?: number; payload?: unknown } => {
+  const reply: any = {
+    sent: false,
+    code: jest.fn(function (this: any, status: number) {
+      this.statusCode = status;
+      return this;
+    }),
+    send: jest.fn(function (this: any, payload: unknown) {
+      this.payload = payload;
+      this.sent = true;
+      return this;
+    }),
+  };
+  return reply;
+};
+
+describe('requireTier middleware', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('pro user passes fuelLog.receiptScan check', () => {
+    it('allows pro user through without sending a response', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('pro');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('enterprise user passes all checks (tier inheritance)', () => {
+    it('allows enterprise user access to pro-gated features', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+
+    it('allows enterprise user access to document.scanMaintenanceSchedule', async () => {
+      const handler = requireTier('document.scanMaintenanceSchedule');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+
+    it('allows enterprise user access to vehicle.vinDecode', async () => {
+      const handler = requireTier('vehicle.vinDecode');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('free user blocked with 403 and correct response body', () => {
+    it('blocks free user from fuelLog.receiptScan', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+          featureName: 'Receipt Scan',
+          upgradePrompt: expect.any(String),
+        }),
+      );
+    });
+
+    it('blocks free user from document.scanMaintenanceSchedule', async () => {
+      const handler = requireTier('document.scanMaintenanceSchedule');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+          featureName: 'Scan for Maintenance Schedule',
+          upgradePrompt: expect.any(String),
+        }),
+      );
+    });
+
+    it('response body includes all required fields', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      const body = (reply.send as jest.Mock).mock.calls[0][0];
+      expect(body).toHaveProperty('requiredTier', 'pro');
+      expect(body).toHaveProperty('currentTier', 'free');
+      expect(body).toHaveProperty('featureName', 'Receipt Scan');
+      expect(body).toHaveProperty('upgradePrompt');
+      expect(typeof body.upgradePrompt).toBe('string');
+      expect(body.upgradePrompt.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('unknown feature key returns 500', () => {
+    it('returns 500 INTERNAL_ERROR for unregistered feature', async () => {
+      const handler = requireTier('unknown.nonexistent.feature');
+      const request = createRequest('pro');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(500);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'INTERNAL_ERROR',
+          message: 'Unknown feature configuration',
+        }),
+      );
+    });
+  });
+
+  describe('missing user.tier on request returns 403', () => {
+    it('defaults to free tier when userContext is undefined', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest(); // no tier = undefined userContext
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          currentTier: 'free',
+          requiredTier: 'pro',
+        }),
+      );
+    });
+  });
+});

backend/src/core/middleware/require-tier.ts

@@ -0,0 +1,64 @@
+/**
+ * @ai-summary Standalone tier guard middleware for route-level feature gating
+ * @ai-context Returns a Fastify preHandler that checks user subscription tier against feature requirements.
+ *   Must be composed AFTER requireAuth in preHandler arrays.
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { canAccessFeature, getFeatureConfig } from '../config/feature-tiers';
+import { logger } from '../logging/logger';
+
+/**
+ * Creates a preHandler middleware that enforces subscription tier requirements.
+ *
+ * Reads the user's tier from request.userContext.subscriptionTier (set by auth middleware).
+ * Must be placed AFTER requireAuth in the preHandler chain.
+ *
+ * Usage:
+ *   fastify.post('/premium-route', {
+ *     preHandler: [requireAuth, requireTier('fuelLog.receiptScan')],
+ *     handler: controller.method
+ *   });
+ *
+ * @param featureKey - Key from FEATURE_TIERS registry (e.g. 'fuelLog.receiptScan')
+ * @returns Fastify preHandler function
+ */
+export function requireTier(featureKey: string) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    // Validate feature key exists in registry
+    const featureConfig = getFeatureConfig(featureKey);
+    if (!featureConfig) {
+      logger.error('requireTier: unknown feature key', { featureKey });
+      return reply.code(500).send({
+        error: 'INTERNAL_ERROR',
+        message: 'Unknown feature configuration',
+      });
+    }
+
+    // Get user tier from userContext (populated by auth middleware)
+    const currentTier = request.userContext?.subscriptionTier || 'free';
+
+    if (!canAccessFeature(currentTier, featureKey)) {
+      logger.warn('requireTier: access denied', {
+        userId: request.userContext?.userId?.substring(0, 8) + '...',
+        currentTier,
+        requiredTier: featureConfig.minTier,
+        featureKey,
+      });
+
+      return reply.code(403).send({
+        error: 'TIER_REQUIRED',
+        requiredTier: featureConfig.minTier,
+        currentTier,
+        featureName: featureConfig.name,
+        upgradePrompt: featureConfig.upgradePrompt,
+      });
+    }
+
+    logger.debug('requireTier: access granted', {
+      userId: request.userContext?.userId?.substring(0, 8) + '...',
+      currentTier,
+      featureKey,
+    });
+  };
+}

backend/src/core/plugins/admin-guard.plugin.ts

@@ -58,9 +58,9 @@ const adminGuardPlugin: FastifyPluginAsync = async (fastify) => {
 
       // Check if user is in admin_users table and not revoked
       const query = `
-        SELECT auth0_sub, email, role, revoked_at
+        SELECT id, user_profile_id, email, role, revoked_at
         FROM admin_users
-        WHERE auth0_sub = $1 AND revoked_at IS NULL
+        WHERE user_profile_id = $1 AND revoked_at IS NULL
         LIMIT 1
       `;
 

backend/src/core/plugins/auth.plugin.ts

@@ -12,6 +12,7 @@ import { logger } from '../logging/logger';
 import { UserProfileRepository } from '../../features/user-profile/data/user-profile.repository';
 import { pool } from '../config/database';
 import { auth0ManagementClient } from '../auth/auth0-management.client';
+import { SubscriptionTier } from '../../features/user-profile/domain/user-profile.types';
 
 // Routes that don't require email verification
 const VERIFICATION_EXEMPT_ROUTES = [
@@ -56,6 +57,7 @@ declare module 'fastify' {
       onboardingCompleted: boolean;
       isAdmin: boolean;
       adminRecord?: any;
+      subscriptionTier: SubscriptionTier;
     };
   }
 }
@@ -119,43 +121,48 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
     try {
       await request.jwtVerify();
 
-      const userId = request.user?.sub;
+      // Two identifiers: auth0Sub (external, for Auth0 API) and userId (internal UUID, for all DB operations)
-      if (!userId) {
+      const auth0Sub = request.user?.sub;
+      if (!auth0Sub) {
         throw new Error('Missing user ID in JWT');
       }
 
+      let userId: string = auth0Sub; // Default to auth0Sub; overwritten with UUID after profile load
+
       // Get or create user profile from database
       let email = request.user?.email;
       let displayName: string | undefined;
       let emailVerified = false;
       let onboardingCompleted = false;
+      let subscriptionTier: SubscriptionTier = 'free';
 
       try {
         // If JWT doesn't have email, fetch from Auth0 Management API
         if (!email || email.includes('@unknown.local')) {
           try {
-            const auth0User = await auth0ManagementClient.getUser(userId);
+            const auth0User = await auth0ManagementClient.getUser(auth0Sub);
             if (auth0User.email) {
               email = auth0User.email;
               emailVerified = auth0User.emailVerified;
               logger.info('Fetched email from Auth0 Management API', {
-                userId: userId.substring(0, 8) + '...',
+                userId: auth0Sub.substring(0, 8) + '...',
                 hasEmail: true,
               });
             }
           } catch (auth0Error) {
             logger.warn('Failed to fetch user from Auth0 Management API', {
-              userId: userId.substring(0, 8) + '...',
+              userId: auth0Sub.substring(0, 8) + '...',
               error: auth0Error instanceof Error ? auth0Error.message : 'Unknown error',
             });
           }
         }
 
         // Get or create profile with correct email
-        const profile = await profileRepo.getOrCreate(userId, {
+        const profile = await profileRepo.getOrCreate(auth0Sub, {
-          email: email || `${userId}@unknown.local`,
+          email: email || `${auth0Sub}@unknown.local`,
           displayName: request.user?.name || request.user?.nickname,
         });
+        userId = profile.id;
 
         // If profile has placeholder email but we now have real email, update it
         if (profile.email.includes('@unknown.local') && email && !email.includes('@unknown.local')) {
@@ -170,11 +177,12 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
         displayName = profile.displayName || undefined;
         emailVerified = profile.emailVerified;
         onboardingCompleted = profile.onboardingCompletedAt !== null;
+        subscriptionTier = profile.subscriptionTier || 'free';
 
         // Sync email verification status from Auth0 if needed
         if (!emailVerified) {
           try {
-            const isVerifiedInAuth0 = await auth0ManagementClient.checkEmailVerified(userId);
+            const isVerifiedInAuth0 = await auth0ManagementClient.checkEmailVerified(auth0Sub);
             if (isVerifiedInAuth0 && !profile.emailVerified) {
               await profileRepo.updateEmailVerified(userId, true);
               emailVerified = true;
@@ -193,7 +201,7 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
       } catch (profileError) {
         // Log but don't fail auth if profile fetch fails
         logger.warn('Failed to fetch user profile', {
-          userId: userId.substring(0, 8) + '...',
+          userId: auth0Sub.substring(0, 8) + '...',
           error: profileError instanceof Error ? profileError.message : 'Unknown error',
         });
         // Fall back to JWT email if available
@@ -208,6 +216,7 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
         emailVerified,
         onboardingCompleted,
         isAdmin: false, // Default to false; admin status checked by admin guard
+        subscriptionTier,
       };
 
       // Email verification guard - block unverified users from non-exempt routes

backend/src/core/plugins/logging.plugin.ts

@@ -1,20 +1,24 @@
 /**
- * @ai-summary Fastify request logging plugin
+ * @ai-summary Fastify request logging plugin with correlation IDs
- * @ai-context Logs request/response details with timing
+ * @ai-context Logs request/response details with timing and requestId
  */
 import { FastifyPluginAsync } from 'fastify';
 import fp from 'fastify-plugin';
+import { randomUUID } from 'crypto';
 import { logger } from '../logging/logger';
 
 const loggingPlugin: FastifyPluginAsync = async (fastify) => {
   fastify.addHook('onRequest', async (request) => {
     request.startTime = Date.now();
+    // Extract X-Request-Id from Traefik or generate new UUID
+    request.requestId = (request.headers['x-request-id'] as string) || randomUUID();
   });
 
   fastify.addHook('onResponse', async (request, reply) => {
     const duration = Date.now() - (request.startTime || Date.now());
-    
+
     logger.info('Request processed', {
+      requestId: request.requestId,
       method: request.method,
       path: request.url,
       status: reply.statusCode,
@@ -24,13 +28,13 @@ const loggingPlugin: FastifyPluginAsync = async (fastify) => {
   });
 };
 
-// Augment FastifyRequest to include startTime
 declare module 'fastify' {
   interface FastifyRequest {
     startTime?: number;
+    requestId?: string;
   }
 }
 
 export default fp(loggingPlugin, {
   name: 'logging-plugin'
-});
+});

backend/src/core/plugins/tests/tier-guard.plugin.test.ts

@@ -0,0 +1,205 @@
+import Fastify, { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import tierGuardPlugin from '../tier-guard.plugin';
+
+const createReply = (): Partial<FastifyReply> & { payload?: unknown; statusCode?: number } => {
+  return {
+    sent: false,
+    code: jest.fn(function(this: any, status: number) {
+      this.statusCode = status;
+      return this;
+    }),
+    send: jest.fn(function(this: any, payload: unknown) {
+      this.payload = payload;
+      this.sent = true;
+      return this;
+    }),
+  };
+};
+
+describe('tier guard plugin', () => {
+  let fastify: FastifyInstance;
+  let authenticateMock: jest.Mock;
+
+  beforeEach(async () => {
+    fastify = Fastify();
+
+    // Mock authenticate to set userContext
+    authenticateMock = jest.fn(async (request: FastifyRequest) => {
+      request.userContext = {
+        userId: '550e8400-e29b-41d4-a716-446655440000',
+        email: 'user@example.com',
+        emailVerified: true,
+        onboardingCompleted: true,
+        isAdmin: false,
+        subscriptionTier: 'free',
+      };
+    });
+    fastify.decorate('authenticate', authenticateMock);
+
+    await fastify.register(tierGuardPlugin);
+  });
+
+  afterEach(async () => {
+    await fastify.close();
+    jest.clearAllMocks();
+  });
+
+  describe('requireTier with minTier', () => {
+    it('allows access when user tier meets minimum', async () => {
+      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
+        request.userContext = {
+          userId: '550e8400-e29b-41d4-a716-446655440000',
+          email: 'user@example.com',
+          emailVerified: true,
+          onboardingCompleted: true,
+          isAdmin: false,
+          subscriptionTier: 'pro',
+        };
+      });
+
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ minTier: 'pro' });
+      await handler(request, reply as FastifyReply);
+
+      expect(authenticateMock).toHaveBeenCalledTimes(1);
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+
+    it('allows access when user tier exceeds minimum', async () => {
+      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
+        request.userContext = {
+          userId: '550e8400-e29b-41d4-a716-446655440000',
+          email: 'user@example.com',
+          emailVerified: true,
+          onboardingCompleted: true,
+          isAdmin: false,
+          subscriptionTier: 'enterprise',
+        };
+      });
+
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ minTier: 'pro' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+    });
+
+    it('denies access when user tier is below minimum', async () => {
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ minTier: 'pro' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+        })
+      );
+    });
+  });
+
+  describe('requireTier with featureKey', () => {
+    it('denies free tier access to pro feature', async () => {
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ featureKey: 'document.scanMaintenanceSchedule' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+          feature: 'document.scanMaintenanceSchedule',
+          featureName: 'Scan for Maintenance Schedule',
+        })
+      );
+    });
+
+    it('allows pro tier access to pro feature', async () => {
+      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
+        request.userContext = {
+          userId: '550e8400-e29b-41d4-a716-446655440000',
+          email: 'user@example.com',
+          emailVerified: true,
+          onboardingCompleted: true,
+          isAdmin: false,
+          subscriptionTier: 'pro',
+        };
+      });
+
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ featureKey: 'document.scanMaintenanceSchedule' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+    });
+
+    it('allows access for unknown feature (fail open)', async () => {
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ featureKey: 'unknown.feature' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('error handling', () => {
+    it('returns 500 when authenticate handler is not a function', async () => {
+      const brokenFastify = Fastify();
+      // Decorate with a non-function value to simulate missing handler
+      brokenFastify.decorate('authenticate', 'not-a-function' as any);
+      await brokenFastify.register(tierGuardPlugin);
+
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = brokenFastify.requireTier({ minTier: 'pro' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(500);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'Internal server error',
+          message: 'Authentication handler missing',
+        })
+      );
+
+      await brokenFastify.close();
+    });
+
+    it('defaults to free tier when userContext is missing', async () => {
+      authenticateMock.mockImplementation(async () => {
+        // Don't set userContext
+      });
+
+      const request = {} as FastifyRequest;
+      const reply = createReply();
+
+      const handler = fastify.requireTier({ minTier: 'pro' });
+      await handler(request, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          currentTier: 'free',
+        })
+      );
+    });
+  });
+});

backend/src/core/plugins/tier-guard.plugin.ts

@@ -0,0 +1,126 @@
+/**
+ * @ai-summary Fastify tier authorization plugin
+ * @ai-context Enforces subscription tier requirements for protected routes
+ */
+
+import { FastifyPluginAsync, FastifyRequest, FastifyReply, FastifyInstance } from 'fastify';
+import fp from 'fastify-plugin';
+import { logger } from '../logging/logger';
+import { SubscriptionTier } from '../../features/user-profile/domain/user-profile.types';
+import { canAccessFeature, getFeatureConfig, getTierLevel } from '../config/feature-tiers';
+
+// Tier check options
+export interface TierCheckOptions {
+  minTier?: SubscriptionTier;
+  featureKey?: string;
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    requireTier: (options: TierCheckOptions) => (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+}
+
+const tierGuardPlugin: FastifyPluginAsync = async (fastify) => {
+  /**
+   * Creates a preHandler that enforces tier requirements
+   *
+   * Usage:
+   *   fastify.get('/premium-route', {
+   *     preHandler: [fastify.requireTier({ minTier: 'pro' })],
+   *     handler: controller.method
+   *   });
+   *
+   * Or with feature key:
+   *   fastify.post('/documents', {
+   *     preHandler: [fastify.requireTier({ featureKey: 'document.scanMaintenanceSchedule' })],
+   *     handler: controller.method
+   *   });
+   */
+  fastify.decorate('requireTier', function(this: FastifyInstance, options: TierCheckOptions) {
+    const { minTier, featureKey } = options;
+
+    return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+      try {
+        // Ensure user is authenticated first
+        if (typeof this.authenticate !== 'function') {
+          logger.error('Tier guard: authenticate handler missing');
+          return reply.code(500).send({
+            error: 'Internal server error',
+            message: 'Authentication handler missing',
+          });
+        }
+
+        await this.authenticate(request, reply);
+        if (reply.sent) {
+          return;
+        }
+
+        // Get user's subscription tier from context
+        const userTier = request.userContext?.subscriptionTier || 'free';
+
+        // Determine required tier and check access
+        let hasAccess = false;
+        let requiredTier: SubscriptionTier = 'free';
+        let upgradePrompt: string | undefined;
+        let featureName: string | undefined;
+
+        if (featureKey) {
+          // Feature-based tier check
+          hasAccess = canAccessFeature(userTier, featureKey);
+          const config = getFeatureConfig(featureKey);
+          requiredTier = config?.minTier || 'pro';
+          upgradePrompt = config?.upgradePrompt;
+          featureName = config?.name;
+        } else if (minTier) {
+          // Direct tier comparison
+          hasAccess = getTierLevel(userTier) >= getTierLevel(minTier);
+          requiredTier = minTier;
+        } else {
+          // No tier requirement specified - allow access
+          hasAccess = true;
+        }
+
+        if (!hasAccess) {
+          logger.warn('Tier guard: user tier insufficient', {
+            userId: request.userContext?.userId?.substring(0, 8) + '...',
+            userTier,
+            requiredTier,
+            featureKey,
+          });
+
+          return reply.code(403).send({
+            error: 'TIER_REQUIRED',
+            requiredTier,
+            currentTier: userTier,
+            feature: featureKey || null,
+            featureName: featureName || null,
+            upgradePrompt: upgradePrompt || `Upgrade to ${requiredTier} to access this feature.`,
+          });
+        }
+
+        logger.debug('Tier guard: access granted', {
+          userId: request.userContext?.userId?.substring(0, 8) + '...',
+          userTier,
+          featureKey,
+        });
+      } catch (error) {
+        logger.error('Tier guard: authorization check failed', {
+          error: error instanceof Error ? error.message : 'Unknown error',
+          userId: request.userContext?.userId?.substring(0, 8) + '...',
+        });
+
+        return reply.code(500).send({
+          error: 'Internal server error',
+          message: 'Tier check failed',
+        });
+      }
+    };
+  });
+};
+
+export default fp(tierGuardPlugin, {
+  name: 'tier-guard-plugin',
+  // Note: Requires auth-plugin to be registered first for authenticate decorator
+  // Dependency check removed to allow testing with mock authenticate
+});

backend/src/core/scheduler/index.ts

@@ -15,6 +15,14 @@ import {
   processBackupRetention,
   setBackupCleanupJobPool,
 } from '../../features/backup/jobs/backup-cleanup.job';
+import {
+  processAuditLogCleanup,
+  setAuditLogCleanupJobPool,
+} from '../../features/audit-log/jobs/cleanup.job';
+import {
+  processGracePeriodExpirations,
+  setGracePeriodJobPool,
+} from '../../features/subscriptions/jobs/grace-period.job';
 import { pool } from '../config/database';
 
 let schedulerInitialized = false;
@@ -31,6 +39,12 @@ export function initializeScheduler(): void {
   setBackupJobPool(pool);
   setBackupCleanupJobPool(pool);
 
+  // Initialize audit log cleanup job pool
+  setAuditLogCleanupJobPool(pool);
+
+  // Initialize grace period job pool
+  setGracePeriodJobPool(pool);
+
   // Daily notification processing at 8 AM
   cron.schedule('0 8 * * *', async () => {
     logger.info('Running scheduled notification job');
@@ -60,6 +74,23 @@ export function initializeScheduler(): void {
     }
   });
 
+  // Grace period expiration check at 2:30 AM daily
+  cron.schedule('30 2 * * *', async () => {
+    logger.info('Running grace period expiration job');
+    try {
+      const result = await processGracePeriodExpirations();
+      logger.info('Grace period job completed', {
+        processed: result.processed,
+        downgraded: result.downgraded,
+        errors: result.errors.length,
+      });
+    } catch (error) {
+      logger.error('Grace period job failed', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+
   // Check for scheduled backups every minute
   cron.schedule('* * * * *', async () => {
     logger.debug('Checking for scheduled backups');
@@ -90,8 +121,30 @@ export function initializeScheduler(): void {
     }
   });
 
+  // Audit log retention cleanup at 3 AM daily (90-day retention)
+  cron.schedule('0 3 * * *', async () => {
+    logger.info('Running audit log cleanup job');
+    try {
+      const result = await processAuditLogCleanup();
+      if (result.success) {
+        logger.info('Audit log cleanup job completed', {
+          deletedCount: result.deletedCount,
+          retentionDays: result.retentionDays,
+        });
+      } else {
+        logger.error('Audit log cleanup job failed', {
+          error: result.error,
+        });
+      }
+    } catch (error) {
+      logger.error('Audit log cleanup job failed', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+
   schedulerInitialized = true;
-  logger.info('Cron scheduler initialized - notification (8 AM), account purge (2 AM), backup check (every min), retention cleanup (4 AM)');
+  logger.info('Cron scheduler initialized - notification (8 AM), account purge (2 AM), grace period (2:30 AM), audit log cleanup (3 AM), backup check (every min), retention cleanup (4 AM)');
 }
 
 export function isSchedulerInitialized(): boolean {

backend/src/features/CLAUDE.md

@@ -0,0 +1,26 @@
+# backend/src/features/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `admin/` | Admin role management, catalog CRUD | Admin functionality, user oversight |
+| `audit-log/` | Centralized audit logging | Cross-feature event logging, admin logs UI |
+| `auth/` | Authentication endpoints | Login, logout, session management |
+| `backup/` | Database backup and restore | Backup jobs, data export/import |
+| `documents/` | Document storage and management | File uploads, document handling |
+| `fuel-logs/` | Fuel consumption tracking | Fuel log CRUD, statistics |
+| `maintenance/` | Maintenance record management | Service records, reminders |
+| `notifications/` | Email and push notifications | Alert system, email templates |
+| `ocr/` | OCR proxy to mvp-ocr service (VIN, receipt, manual extraction) | Image text extraction, receipt scanning, manual PDF extraction, async jobs |
+| `onboarding/` | User onboarding flow | First-time user setup |
+| `ownership-costs/` | Ownership cost tracking and reports | Cost aggregation, expense analysis |
+| `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation |
+| `stations/` | Gas station search and favorites | Google Maps integration, station data |
+| `subscriptions/` | Stripe payment and billing | Subscription tiers, donations, webhooks |
+| `terms-agreement/` | Terms & Conditions acceptance audit | Signup T&C, legal compliance |
+| `user-export/` | User data export | GDPR compliance, data portability |
+| `user-import/` | User data import | Restore from backup, data migration |
+| `user-preferences/` | User preference management | User settings API |
+| `user-profile/` | User profile management | Profile CRUD, avatar handling |
+| `vehicles/` | Vehicle management | Vehicle CRUD, fleet operations |

backend/src/features/admin/CLAUDE.md

@@ -0,0 +1,18 @@
+# admin/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding admin functionality |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core admin logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `scripts/` | Admin utility scripts | Admin automation |
+| `tests/` | Unit and integration tests | Adding or modifying tests |