create-anpunkit 2.0.0

package/template/.claude/hooks/session-start.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# SessionStart hook. stdout is injected into Claude's context every session.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+emit () { printf '%s\n' "$1"; }
+
+emit "=== ANPUNKIT AUTO-CONTEXT (injected by hook, NOT optional) ==="
+emit ""
+
+# 1. git state
+emit "## Git"
+emit "branch: $(git branch --show-current 2>/dev/null || echo n/a)"
+emit "uncommitted: $(git status --short 2>/dev/null | wc -l | tr -d ' ') file(s)"
+git log --oneline -3 2>/dev/null | sed 's/^/  /' || true
+emit ""
+
+# 2. active state
+if [ -f docs/STATE.md ]; then
+  emit "## STATE.md (current position - READ THIS FIRST)"
+  cat docs/STATE.md
+  emit ""
+else
+  emit "## STATE.md missing -> run /overview to bootstrap the project."
+  emit ""
+fi
+
+# 3. issue log
+if [ -f docs/ISSUES.md ]; then
+  OPEN=$(grep -c '^- \[ \]' docs/ISSUES.md 2>/dev/null || true)
+  OPEN=${OPEN:-0}
+  emit "## ISSUES.md (${OPEN} open) - check this before debugging anything"
+  awk '/^### / {p=1} p' docs/ISSUES.md 2>/dev/null | head -100
+  emit ""
+fi
+
+# 3b. research index
+if [ -f docs/research/INDEX.md ]; then
+  RCOUNT=$(grep -c '^[0-9]' docs/research/INDEX.md 2>/dev/null || true)
+  RCOUNT=${RCOUNT:-0}
+  emit "## research/INDEX.md (${RCOUNT} prior investigations)"
+  emit "grep this before any new research or debugging."
+  grep '^[0-9]' docs/research/INDEX.md 2>/dev/null | tail -15 | sed 's/^/  /' || true
+  emit ""
+fi
+
+# 3c. infra status + auth nudge
+if [ -f docs/INFRA.md ]; then
+  INFRA_STATUS=$(grep -m1 '^phase 0:' docs/INFRA.md 2>/dev/null || true)
+  PROJECT_HASH=$(echo "$PWD" | md5sum 2>/dev/null | cut -c1-8 || echo "anpunkit")
+  MARKER="/tmp/anpunkit-auth-${USER:-unknown}-${PROJECT_HASH}"
+  if [ ! -f "$MARKER" ]; then
+    emit "## Azure infra present — auth check needed"
+    emit "Run scripts/auth-setup.sh once this session before any Azure work."
+    if echo "$INFRA_STATUS" | grep -qi 'NOT DONE'; then
+      emit "Phase 0 not complete — run /infra to provision before starting phase 1."
+    fi
+    emit ""
+  fi
+fi
+
+# 3d. shared KB — pull latest + load snapshot
+KB_CONFIG=".claude/kb-config.json"
+if [ -f "$KB_CONFIG" ]; then
+  KB_PATH=$(python3 -c "import json; print(json.load(open('$KB_CONFIG')).get('kb_path',''))" 2>/dev/null || echo "")
+  KB_PATH_EXPANDED="${KB_PATH/#\~/$HOME}"
+
+  if [ -n "$KB_PATH_EXPANDED" ] && [ -d "$KB_PATH_EXPANDED" ]; then
+    emit "## Shared KB"
+
+    # Pull latest (fail silently — offline or no remote shouldn't break session start)
+    if git -C "$KB_PATH_EXPANDED" pull --ff-only --quiet 2>/dev/null; then
+      emit "KB pulled: OK"
+    else
+      emit "KB pull skipped (offline or conflict — using local copy)"
+    fi
+
+    # Load INDEX.md into session snapshot
+    KB_INDEX="${KB_PATH_EXPANDED}/INDEX.md"
+    SNAPSHOT="docs/.kb-snapshot.md"
+
+    if [ -f "$KB_INDEX" ]; then
+      TODAY=$(date +%Y-%m-%d)
+      CUTOFF=$(date -d "6 months ago" +%Y-%m-%d 2>/dev/null \
+               || python3 -c "from datetime import date, timedelta; print((date.today() - timedelta(days=180)).isoformat())" 2>/dev/null \
+               || echo "2000-01-01")
+
+      {
+        echo "# KB snapshot — loaded $(date +%Y-%m-%d)"
+        echo "# Stale = created date older than ${CUTOFF}"
+        echo ""
+        while IFS='|' read -r entry_date domain slug summary rest; do
+          entry_date=$(echo "$entry_date" | tr -d ' ')
+          # Mark stale if date field present and older than cutoff
+          if [ -n "$entry_date" ] && [[ "$entry_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+            if [[ "$entry_date" < "$CUTOFF" ]]; then
+              echo "[STALE] ${entry_date} |${domain} |${slug} |${summary} |${rest}"
+            else
+              echo "${entry_date} |${domain} |${slug} |${summary} |${rest}"
+            fi
+          else
+            echo "${entry_date} |${domain} |${slug} |${summary} |${rest}"
+          fi
+        done < <(grep -v '^#' "$KB_INDEX" | grep -v '^$')
+      } > "$SNAPSHOT"
+
+      TOTAL=$(grep -c '|' "$SNAPSHOT" 2>/dev/null || echo 0)
+      STALE=$(grep -c '^\[STALE\]' "$SNAPSHOT" 2>/dev/null || echo 0)
+      emit "KB snapshot loaded: ${TOTAL} entries (${STALE} stale — researcher will re-research these)"
+      emit "Snapshot at docs/.kb-snapshot.md — researcher reads this before web search."
+    else
+      emit "KB INDEX.md not found at ${KB_PATH_EXPANDED} — run /store-wisdom to populate it."
+    fi
+    emit ""
+  else
+    emit "## Shared KB: configured but path not found (${KB_PATH})"
+    emit "Re-run setup.sh to fix the KB path."
+    emit ""
+  fi
+fi
+
+# 4. hard rule reminder
+emit "## RULES (enforced this session)"
+emit "- caveman ULTRA mode is active."
+emit "- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first."
+emit "- debug attempts: WARN at 2; first hard-stop at 3 STOPS and asks you."
+emit "- end of every phase: run /synthesize, then /clear."
+emit "- small obvious change? use /quick, not /phase."
+emit "- Azure project? run scripts/auth-setup.sh once per session before Azure work."
+if [ -f "$KB_CONFIG" ]; then
+  emit "- KB active: researcher checks docs/.kb-snapshot.md before web search."
+  emit "- learned something worth keeping? run /store-wisdom."
+fi
+emit "=== END AUTO-CONTEXT ==="
+exit 0

package/template/.claude/hooks/subagent-stop.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# SubagentStop hook.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+mkdir -p docs/.snapshots
+LOG="docs/.snapshots/agent-trace.log"
+echo "$(date +%H:%M:%S) subagent finished" >> "$LOG"
+
+tail -n 50 "$LOG" > "$LOG.tmp" 2>/dev/null && mv "$LOG.tmp" "$LOG" || true
+exit 0

package/template/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "startup|clear|compact",
+        "hooks": [ { "type": "command", "command": "bash .claude/hooks/session-start.sh" } ] }
+    ],
+    "PreCompact": [
+      { "matcher": "auto|manual",
+        "hooks": [ { "type": "command", "command": "bash .claude/hooks/pre-compact.sh" } ] }
+    ],
+    "SubagentStop": [
+      { "hooks": [ { "type": "command", "command": "bash .claude/hooks/subagent-stop.sh" } ] }
+    ]
+  }
+}

package/template/.claude/skills/caveman/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  filler, articles, and pleasantries while keeping full technical accuracy.
+  Use when user says "caveman mode", "talk like caveman", "use caveman",
+  "less tokens", "be brief", or invokes /caveman.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after.

package/template/.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/template/.claude/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: karpathy-guidelines
+description: Coding and debugging discipline. Apply on every coding and debug task.
+---
+
+# karpathy-guidelines
+
+Apply on every coding + debug task. Caveman ULTRA mode.
+
+## Coding
+- Smallest change that works. No speculative abstraction. No "while I'm here".
+- Make it run, then make it right, then make it fast — in that order.
+- One concern per change. If the diff does two things, split it.
+- Read before write — understand the existing code path before editing.
+- Name things for what they are. Delete dead code, don't comment it out.
+- Prefer boring, obvious solutions over clever ones.
+
+## Debugging
+- Reproduce first.
+- One hypothesis at a time. State it before changing anything.
+- Change one variable, observe, conclude. No shotgun edits.
+- Read the actual error and stack — top to bottom — before theorizing.
+- When stuck: the bug is somewhere you're sure it isn't. Check assumptions.
+- 3 failed attempts -> stop poking, go research.
+
+## Honesty
+- Don't claim it works until you ran it.
+- "I don't know yet" is valid — say it instead of guessing.
+- A failing test is information. Don't edit the test to hide it.
+- Surface uncertainty to the orchestrator; don't paper over it.
+
+## Verification
+- Every change gets run. Lint/typecheck/smoke at minimum.
+- The real test is written blind by test-author — your own run is just sanity.

package/template/.cursor/commands/infra.md

@@ -0,0 +1,57 @@
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Action: $ARGUMENTS (default: "provision" if INFRA.md missing, "verify" if present)
+
+---
+
+## PRE-FLIGHT
+
+1. Check `az account show` — if it fails, STOP.
+   Tell me: "Run `scripts/auth-setup.sh` first."
+
+2. Determine mode from $ARGUMENTS or default logic.
+
+---
+
+## PROVISION / UPDATE flow
+
+1. Dispatch `infra-provisioner` with the mode.
+
+2. It returns WHAT-IF READY. Show me:
+   - resource list with SKUs and costs
+   - total monthly cost estimate
+   - what-if detail file path
+   Then ask:
+   > "Review docs/research/infra-whatif-<timestamp>.md. Type 'go' to apply,
+   >  or describe changes to make first."
+   WAIT. Do not proceed until I say "go".
+
+3. On "go": pass APPROVED to `infra-provisioner`.
+
+4. On "make changes": dispatch UPDATE with feedback. Loop to step 2.
+
+5. On APPLIED: tell me INFRA.md ✓, .env.test ✓, and any manual steps remaining.
+
+---
+
+## VERIFY flow
+
+1. Check INFRA.md exists. If missing: tell me to run `/infra provision` first.
+2. Dispatch `infra-provisioner` VERIFY mode.
+3. Return drift report.
+
+---
+
+## REGENERATE-ENV flow
+
+1. Check INFRA.md exists.
+2. Dispatch `infra-provisioner` REGENERATE-ENV.
+3. Confirm .env.test rewritten.
+
+---
+
+## Notes
+
+- /infra never touches PLAN.md, STATE.md, ISSUES.md, or DESIGN_LOG.md.
+- Infra errors are AZURE UNAVAILABLE or CONFIG ERROR — do NOT route to debugger.
+- If UNDERSPEC: list missing decisions, ask me to fill them, re-dispatch.

package/template/.cursor/commands/log-decision.md

@@ -0,0 +1,29 @@
+Caveman ULTRA mode.
+
+Append an architectural decision to docs/DESIGN_LOG.md. Change: $ARGUMENTS
+
+WHEN this applies — the change is ARCHITECTURAL:
+- new / removed / renamed agent, hook, or command
+- changed workflow rule (escalation, phase gate, test layering)
+- design decision where alternatives were weighed
+
+WHEN it does NOT apply:
+- code changes, features, phase progress -> HISTORY.md
+- bugs + fixes -> ISSUES.md
+- infra changes -> INFRA.md
+
+Steps:
+1. Read docs/DESIGN_LOG.md.
+2. Append a dated line to `## 0. Changelog`, newest first.
+3. If alternatives were weighed, ALSO append a full entry to §5:
+```
+
+### 5.x <decision title>
+
+Options: <a, b, c>. **Chosen: <x>.** <why it won.>
+
+```
+4. If agent/hook/command/file added or removed, update the file inventory (§6).
+5. NEVER rewrite or delete existing entries — append only.
+
+Confirm back in 2-3 lines: what was logged and where.

package/template/.cursor/commands/log-issue.md

@@ -0,0 +1,23 @@
+Caveman ULTRA mode.
+
+Append an entry to docs/ISSUES.md. Error: $ARGUMENTS
+
+Canonical format:
+```
+
+### <short error title — searchable, literal error keywords>
+
+- [x] open      (or “- [x] resolved”)
+- symptom: <what was observed>
+- root cause: <the REAL underlying cause>
+- solution: <exact fix, or “pending”>
+- failed attempts: <approaches that did NOT work>
+
+```
+Rules:
+- title must contain literal error keywords -> grep finds it.
+- root cause is the real cause, not "the line threw an error".
+- always fill "failed attempts" — stops repeated dead ends.
+- open issues go at the TOP; resolved below; archived oldest at bottom.
+
+Confirm the entry back in 2 lines.

package/template/.cursor/commands/overview.md

@@ -0,0 +1,102 @@
+Caveman ULTRA mode.
+
+Recommended: run from plan mode (Shift+Tab). Planning agents are read-only by
+tool grant; plan mode adds a read-only gate on the main session too. Optional.
+
+Goal: stand up a fresh project workspace with a well-grounded plan.
+
+---
+
+## Steps
+
+### Round 1 — Initial grill
+
+1. Run the `grill-me` skill to interrogate me. Goal: understand initial scope.
+   Cover: project purpose, success criteria, external services, Azure services
+   needed (type + sizing), region, deployment target (Azure or local for E2E),
+   known constraints, unknowns.
+   Do not stop early. Do not write OVERVIEW.md yet.
+
+Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
+
+---
+
+### Design research
+
+2. Extract DESIGN TOPICS from the round-1 answers. These are things we need
+   to verify before planning:
+   - Each external service mentioned: what does it support at the relevant tier?
+     Quotas, rate limits, known gaps?
+   - Azure services: any sizing or SKU constraints relevant to the use case?
+   - Auth patterns: any MSAL/Entra constraints for this scenario?
+   - Any other architectural assumption in the round-1 answers worth verifying.
+
+3. Dispatch `researcher` in DESIGN mode with the DESIGN TOPICS list.
+   It returns a terse summary + file paths. Read the design-<slug>.md files
+   only if needed.
+
+---
+
+### Round 2 — Research-informed re-grill
+
+4. Run `grill-me` again — a second focused pass. Seed it with:
+   - The round-1 answers (already established — do not re-ask these)
+   - The design-research key findings and new questions raised
+
+   The re-grill asks whatever it needs to build complete understanding. It is
+   not limited to "gaps from research" — research context makes new questions
+   relevant even if it found no blockers. Do not re-ask what round 1 already
+   established clearly.
+
+---
+
+### Write OVERVIEW.md
+
+5. Write docs/OVERVIEW.md from the COMBINED output of round-1 + design-research
+   + round-2. Include:
+   - Project purpose and success criteria
+   - Scope and constraints (informed by research findings)
+   - External services with confirmed capabilities/limits
+   - "Azure services" section: every service with expected SKU
+   - Deployment target (azure-deployed or local-docker for E2E)
+   - Known risks / open questions (if any remain)
+
+   OVERVIEW.md is written HERE — after the re-grill, not before.
+
+---
+
+### Plan
+
+6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
+   PLAN.md MUST:
+   - Start with Phase 0 (infra setup) as the first entry (always).
+   - End with a final code phase that contains the deploy task block.
+
+7. Create docs/STATE.md:
+```
+
+# STATE
+
+phase: 0 (pending)
+completed: project bootstrapped — design research done, double grill done
+next: run /infra to provision Azure infrastructure
+blocker: none
+
+```
+8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
+
+9. Create empty docs/HISTORY.md.
+
+10. Create docs/INFRA.md from the template (populated by /infra).
+
+11. Create docs/ENDPOINTS.md:
+ ```
+ # Endpoints — <project name>
+ > Maintained by implementer. Updated each phase.
+ > Base URL: (populated after deployment phase)
+ ```
+
+Then stop and show me PLAN.md for approval before any phase starts.
+
+Remind me: "Run `/infra` next to provision the Azure environment (Phase 0)
+before starting Phase 1."

package/template/.cursor/commands/phase.md

@@ -0,0 +1,197 @@
+Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
+you do NOT implement or debug yourself.
+
+Note: subagents cannot talk to the user. Only YOU can.
+
+Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
+
+---
+
+## 0. PRE-FLIGHT
+
+a. INFRA CHECK (phases > 0):
+   - Read docs/INFRA.md. If Phase 0 not done -> STOP.
+     Tell me: "Phase 0 (infra) not complete. Run `/infra` first."
+   - Exception: if $ARGUMENTS is "0", tell me to run `/infra` directly.
+
+b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
+   - No phase in progress, requested is next pending -> START at step 1.
+   - Same phase in-progress -> RESUME from STATE.md "next action".
+   - Different phase in-progress -> STOP. Tell me which phase is open.
+   - Out of dependency order -> STOP. Warn, proceed only if I confirm.
+   - Phase not in PLAN.md -> STOP. Suggest /overview or /replan.
+
+c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
+   pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
+
+d. AUTH NUDGE: if INFRA.md exists and auth marker absent, remind me to run
+   `scripts/auth-setup.sh`. Not a gate — just a reminder.
+
+---
+
+## 1. RESEARCH + TDD APPLICABILITY
+
+Dispatch `researcher` in IMPL mode scoped to this phase.
+Returns terse summary + path. Read the file only if needed.
+Unknowns block the phase -> re-dispatch narrowed. No guessing.
+
+Then classify the phase:
+
+  `TDD_PHASE` = the phase adds or changes a PUBLIC CALLABLE SURFACE (endpoint,
+  exported function/class, CLI command, message contract) assertable from the
+  acceptance spec. Size is NOT the criterion.
+
+- Clear public surface -> `TDD_PHASE=true` -> run the TDD path (§2 → §3a → §3b).
+- Pure infra/config/doc, no public surface -> `TDD_PHASE=false` -> run the
+  non-TDD path (§2N → §3N).
+- AMBIGUOUS -> default `TDD_PHASE=true`, but STATE the classification + the reason
+  to me, so I can override to non-TDD BEFORE SCAFFOLD fires. (Hard rule 11: never
+  downgrade a TDD phase just to dodge the RED gate.)
+
+=====================================================================
+## TDD PATH  (TDD_PHASE=true)
+=====================================================================
+
+## 2. SCAFFOLD
+
+Dispatch `implementer` in SCAFFOLD mode: interface stubs only (signatures +
+types; bodies raise NotImplementedError / return 501); NO logic, NO tests.
+Returns the stub files + the interface surface.
+
+## 3a. RED
+
+Dispatch `test-author` to write the REAL API suite (+ mock) BLIND against the
+stubs + acceptance. Place contract/ENDPOINTS tests in `tests/regression/`,
+phase-local tests in `tests/phase-<n>/`. Run the suite.
+
+RED GATE = every acceptance test COLLECTS cleanly AND FAILS (assertion /
+NotImplemented).
+- Any test PASSES on stubs -> STOP (spec trivial or test wrong); show me.
+- Collection / import / syntax error -> stub mismatch; re-dispatch SCAFFOLD to
+  fix SIGNATURES (not logic); re-run.
+- UNDERSPEC -> STOP; ask me to sharpen the acceptance spec.
+
+## 3b. GREEN
+
+Dispatch `implementer` in FILL mode with the phase spec + research + the test
+file paths (it MAY read the tests — frozen before logic, no overfit — but must
+NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
+
+Dispatch `e2e-runner` IF this phase touches the frontend (reads INFRA.md target;
+`scripts/e2e-stack.sh up` / Playwright / `down`).
+
+PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
+
+=====================================================================
+## NON-TDD PATH  (TDD_PHASE=false)
+=====================================================================
+
+## 2N. IMPLEMENT
+
+Dispatch `implementer` (legacy mode) with phase spec + research summary.
+Returns STUCK -> go to ESCALATE.
+If IS_FINAL_PHASE: phase spec includes the deploy task; confirm the return
+includes "deployed URL" before proceeding.
+
+## 3N. TEST (blind)
+
+Dispatch `test-author`. It writes MOCK + REAL API suites from the acceptance
+spec — never reads the logic. (e2e-runner only if frontend.)
+
+=====================================================================
+
+## GATE (both paths)
+
+PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
+the accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
+entry has a regression test (checked at CLOSE).
+- GATE PASS -> go to CLOSE.
+- GATE BLOCKED (SERVICE UNAVAILABLE, STACK NOT READY, AZURE UNAVAILABLE, FLAKE)
+  -> tell me, wait. Not a code bug. For AZURE UNAVAILABLE: suggest `/infra verify`.
+- GATE FAIL (LOGIC FAIL) -> go to FIX.
+
+---
+
+## 4. FIX
+
+Dispatch `debugger` (isolated context) on the specific failure.
+- FIXED -> re-run TEST (and the regression corpus).
+- SERVICE UNAVAILABLE -> tell me, wait. Suggest `/infra verify` if Azure.
+- WARN (2 attempts failed) -> relay immediately, then let debugger finish attempt 3.
+- STUCK -> go to ESCALATE.
+
+---
+
+## 5. ESCALATE — circuit breaker. Mode B.
+
+FIRST STUCK: STOP. Present to me: the problem, 3 failed hypotheses, the
+debugger's recommendation, the debug file path. Ask what to do. Wait. Options:
+  (a) "re-research" -> /unstuck
+  (b) hint -> re-dispatch debugger with hint, budget 3
+  (c) "skip" / "re-slice" -> mark blocked, dispatch planner
+
+SECOND STUCK: STOP completely. Full summary — every hypothesis, current state,
+what to try next. Hand control to me.
+
+---
+
+## 6. CLOSE
+
+REGRESSION GATE (before closing — Feature 3):
+- Run `scripts/regression.sh` (mock corpus). A failure BLOCKS close -> route to FIX.
+- ENDPOINTS COVERAGE: every `docs/ENDPOINTS.md` entry MUST have >=1 test in
+  `tests/regression/`. Zero coverage -> FAIL HARD; do not close.
+- IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
+  corpus). A failure blocks close.
+
+Mark phase `done` in docs/PLAN.md.
+
+ARCHITECTURE SELF-CHECK: did this phase add/remove/rename an agent, hook, or
+command, or change a workflow rule? YES -> run `/log-decision`. NO -> state why not.
+
+IF IS_FINAL_PHASE — FINAL CLOSE sequence:
+
+  a. Run `/synthesize` — pass the signal that this is the final phase so the
+     synthesizer runs the extended pass (OVERVIEW.md + README.md update).
+
+  b. Read docs/ENDPOINTS.md. Surface a "READY TO USE" summary to me:
+     ```
+     ✅ PROJECT COMPLETE
+
+     Deployed at: <base URL from docs/INFRA.md "Deployed base URL">
+
+     ## Endpoints
+     <paste the full docs/ENDPOINTS.md table>
+
+     ## Quick start
+     - Base URL: <URL>
+     - Auth: <Bearer token / API key / none — from ENDPOINTS.md>
+     - Health check: GET <base URL>/health
+
+     ## Docs
+     - Full endpoint catalogue: docs/ENDPOINTS.md
+     - Infrastructure: docs/INFRA.md
+     - Project history: docs/HISTORY.md
+     ```
+  Tell me the project is complete and ready to use.
+
+ELSE (not final phase):
+
+  Run `/synthesize`.
+  Tell me phase done + the next phase. Recommend `/clear` then `/phase` next.
+
+---
+
+## STATE CHECKPOINTING
+
+After each step, update docs/STATE.md:
+```
+
+phase: <n> (in progress)
+tdd: <true|false>
+completed: <steps done so far>
+next: <exact next step>
+blocker: <none or open issue>
+
+```
+Keep STATE.md small — overwrite, do not append.