chore(repo): organize operating system and hygiene

.circleci/config.yml

@@ -215,7 +215,7 @@ jobs:
   # Required env vars in CircleCI project settings:
   #   VERCEL_TOKEN, VERCEL_PROJECT_ID, (optional) VERCEL_TEAM_ID
   lighthouse-preview:
-    executor: node
+    executor: node-large
     steps:
       - checkout
       - install-node-deps
@@ -228,10 +228,19 @@ jobs:
           name: Wait for Vercel preview to be READY
           command: |
             URL=$(bash .circleci/scripts/wait-for-vercel-preview.sh)
-            echo "export PREVIEW_URL='${URL}'" >> "$BASH_ENV"
+            if [ -z "${URL}" ]; then
+              echo "No Vercel preview URL available; skipping advisory Lighthouse run."
+              echo "export SKIP_LIGHTHOUSE=1" >> "$BASH_ENV"
+            else
+              echo "export PREVIEW_URL='${URL}'" >> "$BASH_ENV"
+            fi
       - run:
           name: Run Lighthouse CI
           command: |
+            if [ "${SKIP_LIGHTHOUSE:-0}" = "1" ]; then
+              echo "Skipping Lighthouse CI because preview credentials are not configured."
+              exit 0
+            fi
             npx lhci autorun --config=lighthouserc.cjs
       - store_artifacts:
           path: .lighthouseci/

.circleci/scripts/wait-for-vercel-preview.sh

@@ -14,7 +14,9 @@
 #                        finish in 1-3 min
 #   POLL_INTERVAL_S    — default 10
 #
-# Exits non-zero with a useful message on timeout or API error.
+# Exits non-zero with a useful message on timeout or API error. If CircleCI is
+# not configured with Vercel credentials yet, exits zero with no stdout so the
+# caller can skip the advisory Lighthouse run without blocking the PR.
 # Designed to be source'd OR run with `eval $(...)` to set
 # PREVIEW_URL in the calling shell. Standalone use: `bash this | tail -1`.
 #
@@ -23,9 +25,15 @@
 
 set -euo pipefail
 
-: "${VERCEL_TOKEN:?VERCEL_TOKEN env var is required}"
-: "${VERCEL_PROJECT_ID:?VERCEL_PROJECT_ID env var is required}"
-: "${CIRCLE_SHA1:?CIRCLE_SHA1 env var is required (CircleCI provides this)}"
+if [[ -z "${VERCEL_TOKEN:-}" || -z "${VERCEL_PROJECT_ID:-}" ]]; then
+  echo "Skipping Lighthouse preview: VERCEL_TOKEN or VERCEL_PROJECT_ID is not configured in CircleCI." >&2
+  exit 0
+fi
+
+if [[ -z "${CIRCLE_SHA1:-}" ]]; then
+  echo "Skipping Lighthouse preview: CIRCLE_SHA1 is not set." >&2
+  exit 0
+fi
 
 POLL_TIMEOUT_S="${POLL_TIMEOUT_S:-600}"
 POLL_INTERVAL_S="${POLL_INTERVAL_S:-10}"

.claude/README.md

@@ -1,220 +1,36 @@
-# 🎯 Production Audit Commands for Claude Code
+# Claude Agent Workspace
 
-## ✅ SIMPLE 2-STEP PROCESS
+This folder contains Claude-facing agents, commands, and older audit material.
 
-### Step 1: Generate Agent Prompts
+## Current Agents
 
-```bash
-# For GolfHelm
-python3 .claude/run_audit.py audit-golf 1
+Use `.claude/agents/` for focused review and handoff work:
 
-# For BaseballHelm
-python3 .claude/run_audit.py audit-baseball 1
+- `triage-captain.md`: turns broad requests into scoped, issue-ready work.
+- `ci-doctor.md`: investigates failing checks and local verification gaps.
+- `db-rls-auditor.md`: reviews Supabase migrations, policies, and RLS tests.
+- `test-writer.md`: adds focused unit, integration, or smoke coverage.
+- `docs-keeper.md`: keeps current docs and memory routing synchronized.
+- `pr-reviewer.md`: reviews changes for regressions and missing verification.
+- `ui-polish-reviewer.md`: reviews UI polish and visual consistency.
 
-# For Both Platforms
-python3 .claude/run_audit.py audit-both 1
-```
+## Current Rules
 
-This creates a file: `RUN_IN_CLAUDE_CODE.md`
+Read these before treating older generated prompts as current:
 
-### Step 2: Copy & Paste Into Claude Code
+- `../AGENTS.md`
+- `../CLAUDE.md`
+- `../docs/current/README.md`
+- `../docs/operations/GATE_MATRIX.md`
+- `../docs/operations/CI_RUNBOOK.md`
 
-```bash
-# Open the generated file
-open .production-team/GOLFHELM_AUDIT_ROUND_01/RUN_IN_CLAUDE_CODE.md
+## Legacy Material
 
-# Copy the message
-# Paste into Claude Code
-# Done!
-```
+Older files in this folder may describe prompt-generation systems or one-off audit runs. Keep them as historical evidence, not as the primary workflow.
 
----
+For new work, prefer:
 
-## 🎭 What Happens
-
-### When You Run the Command:
-
-1. **Loads ALL agent personalities** from `.production-team/`
-2. **Loads ALL agent memories** from `.production-team/memory/`
-3. **Applies platform scope** (Golf, Baseball, or Both)
-4. **Generates complete prompts** with full intelligence
-5. **Creates RUN_IN_CLAUDE_CODE.md** with everything Claude Code needs
-
-### The Three Genius Agents:
-
-**🛡️ Database Sentinel**
-- Full personality + methodology loaded
-- Memory from past rounds loaded
-- Scoped to platform (golf tables only, etc.)
-- Queries live database via Supabase MCP
-
-**🎯 Feature Maestro** ⭐ **(SUPER IMPORTANT)**
-- Full personality + methodology loaded
-- Memory from past rounds loaded
-- Tests all features with edge cases
-- Checks completeness systematically
-
-**✨ Experience Architect**
-- Full personality + methodology loaded
-- Memory from past rounds loaded
-- Enforces Da Vinci philosophy
-- Verifies glassmorphism + kelly green
-
----
-
-## 📁 Output Structure
-
-**After running `audit-golf`:**
-```
-.production-team/GOLFHELM_AUDIT_ROUND_01/
-├── PROMPT_DATABASE_SENTINEL.md .......... Full agent prompt
-├── PROMPT_FEATURE_MAESTRO.md ............ Full agent prompt
-├── PROMPT_EXPERIENCE_ARCHITECT.md ....... Full agent prompt
-├── RUN_IN_CLAUDE_CODE.md ................ Copy this into Claude Code
-├── 01_DATABASE_SENTINEL_FINDINGS.md ..... (Created by Claude Code)
-├── 02_FEATURE_MAESTRO_FINDINGS.md ....... (Created by Claude Code)
-├── 03_EXPERIENCE_ARCHITECT_FINDINGS.md .. (Created by Claude Code)
-├── 04_CROSS_AGENT_SYNTHESIS.md .......... (Created by Claude Code)
-└── 05_PRIORITY_ACTION_ITEMS.md .......... (Created by Claude Code)
-```
-
----
-
-## 🚀 Complete Workflow
-
-```bash
-# 1. Generate prompts for GolfHelm
-python3 .claude/run_audit.py audit-golf 1
-
-# 2. Open the instruction file
-cat .production-team/GOLFHELM_AUDIT_ROUND_01/RUN_IN_CLAUDE_CODE.md
-
-# 3. Copy the message from that file
-
-# 4. Open Claude Code (in Cursor or standalone)
-
-# 5. Paste the message
-
-# 6. Claude Code executes all 3 agents autonomously
-
-# 7. Review findings
-cat .production-team/GOLFHELM_AUDIT_ROUND_01/05_PRIORITY_ACTION_ITEMS.md
-
-# 8. Fix issues
-
-# 9. Run Round 2
-python3 .claude/run_audit.py audit-golf 2
-```
-
----
-
-## 💡 Why This Works
-
-### Before (Didn't Work):
-❌ You had to manually combine agent files  
-❌ No memory loaded  
-❌ Platform scope unclear  
-❌ Confusing to execute  
-
-### Now (Works Perfectly):
-✅ **One command** generates everything  
-✅ **Full agent intelligence** loaded  
-✅ **Memory automatically** loaded and applied  
-✅ **Platform scope** built-in  
-✅ **Simple copy/paste** into Claude Code  
-✅ **Agents run autonomously** with full capabilities  
-
----
-
-## 🎯 Available Commands
-
-```bash
-# GolfHelm only
-python3 .claude/run_audit.py audit-golf 1
-
-# BaseballHelm only
-python3 .claude/run_audit.py audit-baseball 1
-
-# Both platforms
-python3 .claude/run_audit.py audit-both 1
-
-# Round 2 (after fixes)
-python3 .claude/run_audit.py audit-golf 2
-```
-
----
-
-## 🧠 Memory System
-
-**First Run:**
-- Agents have no memory
-- Establish baseline findings
-- Create memory files
-
-**Second Run:**
-- Agents load memory from Round 1
-- Skip re-reporting fixed issues
-- Go deeper on edge cases
-- Update memory with new learnings
-
-**Round 3+:**
-- Agents have deep knowledge
-- Predict issues based on patterns
-- Expert-level auditing
-
----
-
-## 📊 Example Usage
-
-```bash
-$ python3 .claude/run_audit.py audit-golf 1
-
-======================================================================
-🎭 PRODUCTION AUDIT - GOLFHELM - ROUND 01
-======================================================================
-
-📁 Output: .production-team/GOLFHELM_AUDIT_ROUND_01
-
-🛡️ DATABASE SENTINEL
-──────────────────────────────────────────────────────────────────────
-✅ Generated prompt: .production-team/GOLFHELM_AUDIT_ROUND_01/PROMPT_DATABASE_SENTINEL.md
-   Memory loaded: No (first run)
-   Platform scope: GolfHelm
-
-🎯 FEATURE MAESTRO
-──────────────────────────────────────────────────────────────────────
-✅ Generated prompt: .production-team/GOLFHELM_AUDIT_ROUND_01/PROMPT_FEATURE_MAESTRO.md
-   Memory loaded: No (first run)
-   Platform scope: GolfHelm
-
-✨ EXPERIENCE ARCHITECT
-──────────────────────────────────────────────────────────────────────
-✅ Generated prompt: .production-team/GOLFHELM_AUDIT_ROUND_01/PROMPT_EXPERIENCE_ARCHITECT.md
-   Memory loaded: No (first run)
-   Platform scope: GolfHelm
-
-======================================================================
-✨ PROMPTS GENERATED!
-======================================================================
-
-📄 Next: Open and copy: .production-team/GOLFHELM_AUDIT_ROUND_01/RUN_IN_CLAUDE_CODE.md
-📋 Paste into Claude Code
-🚀 Agents will execute with full intelligence + memory
-```
-
-Then just:
-1. Open `RUN_IN_CLAUDE_CODE.md`
-2. Copy the message
-3. Paste into Claude Code
-4. Watch the genius agents work!
-
----
-
-## ✨ That's It!
-
-**One command. One copy/paste. Full intelligent agents with memory.**
-
-Start now:
-```bash
-python3 .claude/run_audit.py audit-golf 1
-```
+1. GitHub Issues for the task.
+2. `memory/registry.yml` for feature routing.
+3. The relevant current docs under `docs/current/` and `docs/operations/`.
+4. The smallest useful verification command before declaring completion.

.claude/agents/ci-doctor.md

@@ -0,0 +1,17 @@
+# CI Doctor
+
+Purpose: diagnose failing CI and propose the smallest safe fix.
+
+## Responsibilities
+
+- Read the failed job logs before suggesting code changes.
+- Use `docs/operations/GATE_MATRIX.md` to classify hard blockers versus advisory checks.
+- Prefer fixing root causes over relaxing gates.
+- Do not make unrelated code, docs, or baseline changes.
+
+## Done Means
+
+- Root cause is named.
+- Minimal fix is identified.
+- Required verification command is listed.
+- Any advisory-only failure is clearly labeled advisory.

.claude/agents/db-rls-auditor.md

@@ -0,0 +1,18 @@
+# DB / RLS Auditor
+
+Purpose: review Supabase migrations, RLS policies, security-definer functions, and data access paths.
+
+## Responsibilities
+
+- Treat database and security mistakes as high risk.
+- Check new tables for RLS enablement and policies in the same migration.
+- Check `SECURITY DEFINER` functions for explicit `search_path`.
+- Verify data access paths use authenticated user context.
+- Require migration lint, RLS tests, database type drift checks, and ledger checks when relevant.
+
+## Required References
+
+- `memory/context/golfhelm-database.md`
+- `memory/glossary.md`
+- `docs/operations/GATE_MATRIX.md`
+- `docs/operations/HOT_FILES.md`

.claude/agents/docs-keeper.md

@@ -0,0 +1,19 @@
+# Docs Keeper
+
+Purpose: keep current-state docs, feature docs, and registry mappings aligned with behavior.
+
+## Responsibilities
+
+- Keep current docs concise and present-tense.
+- Move old plans and audits to historical locations instead of letting them look current.
+- Update `memory/registry.yml` when feature ownership or path routing changes.
+- Do not manually edit generated blocks marked with AUTOGEN comments.
+
+## Source Of Truth
+
+- GitHub Issues: current work.
+- GitHub Project: current priority.
+- `memory/registry.yml`: feature routing.
+- `docs/operations/`: runbooks and incident history.
+- `docs/audits/`: historical audits.
+- `.helm/`: archive only.

.claude/agents/pr-reviewer.md

@@ -0,0 +1,17 @@
+# PR Reviewer
+
+Purpose: review a PR diff for scope, missing tests, missing docs, risky files, and incomplete acceptance criteria.
+
+## Responsibilities
+
+- Lead with bugs, regressions, security issues, and test gaps.
+- Check whether changed files map through `memory/registry.yml`.
+- Verify hot-file rules in `docs/operations/HOT_FILES.md`.
+- Distinguish hard blockers from advisory checks using `docs/operations/GATE_MATRIX.md`.
+- Avoid style-only comments unless they hide a real maintenance or user risk.
+
+## Output Shape
+
+- Findings ordered by severity with file and line references.
+- Open questions.
+- Brief verification summary.