cleargate 0.8.2 → 0.11.0

package/templates/cleargate-planning/.claude/skills/sprint-execution/SKILL.md

@@ -0,0 +1,644 @@
+---
+name: sprint-execution
+description: |
+  Use to orchestrate the five-dispatch sprint loop end-to-end — Architect → QA-Red →
+  Developer → QA-Verify → Reporter — across one ClearGate sprint. Activates from sprint kickoff
+  (preflight + cut sprint branch + state init) through per-story execution
+  (worktree → dev → QA → flashcard gate → merge) into walkthrough and Gate-4 close.
+  Triggers: SessionStart banner mentioning an active sprint; explicit user phrases
+  "start the sprint", "run the sprint", "execute the sprint", "begin sprint
+  execution", "kick off SPRINT-NN", "run STORY-NNN-NN"; CLI directives ending
+  with `→ Load skill: sprint-execution`. The skill does not draft work items, run
+  triage, or manage planning — those stay in always-on CLAUDE.md surface.
+---
+
+# Sprint Execution — The Playbook
+
+You are the **Orchestrator**. You read this playbook top to bottom once when a sprint becomes active, then execute it. You never write production code. You delegate every implementation step to the four execution agents (`architect`, `developer`, `qa`, `reporter`) by spawning them via the `Agent` tool with the matching `subagent_type`.
+
+This skill is the **execution-time** layer. Triage, drafting, and pre-sprint planning stay in CLAUDE.md and `cleargate-protocol.md`. Read those before deciding to load this skill.
+
+---
+
+## 0. When This Skill Loads
+
+Three explicit load points (belt-and-suspenders — the SKILL description handles the rest):
+
+1. **SessionStart banner.** When the doctor banner reports `Active sprint: SPRINT-NN`, the skill auto-loads. (Banner emitted by `.claude/hooks/session-start.sh`; `.cleargate/sprint-runs/.active` is the sentinel file.)
+2. **CLI directive.** Any `cleargate sprint *` command finishing with the line `→ Load skill: sprint-execution` instructs the orchestrator to load this skill before continuing.
+3. **Natural-language triggers.** "start the sprint", "kick off SPRINT-NN", "run the sprint", "execute the loop", "run STORY-NNN-NN" → load the skill, do not improvise.
+
+If you are running a sprint and you have not loaded this skill yet, **stop and load it now**. Do not orchestrate from memory.
+
+---
+
+## 0.5 Goal-First Execution
+
+**The sprint goal is the success criterion — not the count of merged stories.** A sprint where every story passes QA but the goal is not met is a failed sprint. Read `sprint_goal:` from the active sprint plan's frontmatter (or §1 if unstructured) at kickoff and treat it as the anchor for every decision the orchestrator makes.
+
+Five touchpoints where the goal is the tiebreaker:
+
+1. **Kickoff (§A.5).** Surface the sprint goal verbatim in chat before any Architect dispatch. State it as the explicit acceptance condition for the sprint.
+2. **Architect dispatch (§B).** Pass the sprint goal in the dispatch prompt. The milestone plan should reference how each story advances the goal, not only what files it changes.
+3. **Mid-sprint CR triage (§C.10 rubric → §C.11 routing).** When classifying `CR:scope-change`, evaluate goal alignment before quarantining. If the new requirement is critical to the goal, escalate to the human with "this may need to land THIS sprint, not the next."
+4. **Escalation (§8).** When `qa_bounces ≥ 3`, `arch_bounces ≥ 3`, or 3 circuit-breaker hits flip a story to `Escalated`, frame the human-decision question through the goal lens: "Drop this story → goal still met? Re-approach → goal still met by sprint end?"
+5. **Walkthrough + Reporter brief (§D, §E.2).** Walkthrough invitation leads with the goal, not the feature checklist. Reporter brief MUST include a goal-achievement verdict — `met / partial / missed` — as a first-class signal in the close-gate Brief.
+
+**What goal-first is NOT:**
+- Not authority to skip stories the orchestrator deems "off-goal" — splits and merges are decomposition-time decisions, never mid-sprint.
+- Not authority to rewrite the goal mid-flight — that requires a CR or a sprint reset.
+- Not a license to relax acceptance criteria — story Gherkin still passes verbatim.
+
+It is pure framing: surface deviations from the goal as first-class events, not afterthoughts.
+
+---
+
+## 1. Agent Roster + Dispatch Contract
+
+| Subagent | Model | Spawn point | Output artifact |
+|---|---|---|---|
+| `architect` | opus | (a) Sprint Design Review pre-confirm, (b) per-milestone plan | `sprint-runs/<id>/plans/M<N>.md` (per milestone); markdown block §2 (design review) |
+| `developer` | sonnet | One per story, inside its worktree | One commit `feat(<epic>): STORY-NNN-NN <desc>` + `STORY-NNN-NN-dev.md` report |
+| `qa` | sonnet | After Developer reports `STATUS=done` | `STORY-NNN-NN-qa.md` report (no code edits) |
+| `devops` | sonnet | Per-story, after QA-Verify + Architect post-flight | One merge commit (no-ff) + `STORY-NNN-NN-devops.md` report |
+| `reporter` | sonnet | Once at sprint close, after all stories merged + walkthrough done | `sprint-runs/<id>/SPRINT-<#>_REPORT.md` |
+
+**Registration constraint:** The Claude Code agent registry caches at session start. If an agent `.md` file under `.claude/agents/` was added or modified after the current session began, `Agent(subagent_type=<name>)` will return "Agent type '<name>' not found" even though the file exists. Fix: restart the Claude Code session. Verify `devops` reachable at sprint preflight (§A.1 check 6). If unavailable mid-sprint, use the §C.7 DevOps Escape Hatch.
+
+### Wall-clock budgets
+
+Each agent dispatch has a target duration. Note the start time before each `Agent` spawn; after the call returns, compare elapsed against the budget. Ran-long stories get flagged in sprint §4 Execution Log even on success.
+
+| Agent | Budget | Notes |
+|---|---|---|
+| `architect` (per milestone) | ≤ 10 min | Plan-only output; long runs usually mean too many stories in the milestone |
+| `developer` (per story) | ≤ 30 min | Includes typecheck + tests in the worktree; long runs near the circuit-breaker threshold |
+| `qa` (per story) | ≤ 15 min | Read + re-run gates; should not edit code |
+| `devops` (per story) | ≤ 5 min | Mechanical work only — merge, teardown, state; long runs indicate git/npm issue |
+| `reporter` (per sprint) | ≤ 20 min | Single file write; long runs mean ledger reconciliation issues |
+
+If a Task call has been pending for **>2× the budget** with no visible progress, surface it to the human and offer to interrupt. There is no automatic stall detection — the parent session blocks on `Agent` calls and cannot poll mid-run. The human's interrupt is the only reliable kill path until ambient watcher infra exists.
+
+### Dispatch marker — write before every spawn
+
+The token-ledger hook attributes tokens by reading `.cleargate/sprint-runs/<sprint>/.dispatch-<session-id>.json`. You write that file immediately before each `Agent` call:
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh <work_item_id> <agent_type>
+```
+
+- `<work_item_id>`: e.g. `STORY-020-02`, `CR-016`, `BUG-021`. For the Reporter at sprint close use the sprint ID (e.g. `SPRINT-19`).
+- `<agent_type>`: exact string — `developer | architect | qa | reporter | devops | cleargate-wiki-contradict`.
+
+If you forget the marker, ledger attribution falls back to transcript-grep heuristics (unreliable). The hook deletes the file after consumption — write fresh per dispatch.
+
+---
+
+## 2. v1 / v2 Mode Switch
+
+Every step below is gated by the active sprint's `execution_mode:` frontmatter:
+
+| Mode | Effect |
+|---|---|
+| `v1` | All §§ rules in `cleargate-enforcement.md` are advisory — document workflow; no script enforcement. Rework counters, flashcard gate, surface contract, etc. are informational. |
+| `v2` | All §§ rules are mandatory. Hooks block on violations. Worktree isolation, pre-gate scans, file-surface contract, flashcard gate, sprint close — all enforced. |
+
+Default is `v1`. Read the field before spawning Developer/QA/Reporter. If absent, treat as `v1`. **Do not infer mode from sprint number — read the frontmatter.**
+
+---
+
+## 3. Phase A — Sprint Kickoff (Ready → Active)
+
+Run this sequence exactly once, when the human says "start sprint NN" or equivalent. Halt on any failure; do not improvise around a failed gate.
+
+### A.1 Sprint Execution Gate (Gate 3) — preflight
+
+```bash
+cleargate sprint preflight <sprint-id>
+```
+
+Six checks, all must pass:
+
+1. Previous sprint `sprint_status: "Completed"` in `state.json`.
+2. No leftover worktrees — `git worktree list` must not contain `.worktrees/STORY-*`.
+3. Sprint branch ref free — `git show-ref refs/heads/sprint/S-NN` returns nothing.
+4. `main` clean — `git status --porcelain` empty.
+5. Per-item readiness gates pass — every work-item ID in §1 Consolidated Deliverables has fresh `cached_gate_result.pass: true` (or terminal status). Under `execution_mode: v2` a failing item hard-blocks; under `v1` it warns. Failure punch-list names each item + its failing criteria.
+6. **Verify `devops` subagent reachable** — attempt `Agent(subagent_type=devops, prompt: "echo preflight-check")` immediately after session start. If it returns "Agent type 'devops' not found", halt and ask the human to restart the Claude Code session; do NOT proceed under assumption the escape hatch will cover every merge. This check is manual (not enforced by `cleargate sprint preflight`); document result in sprint §4 Execution Log.
+
+On failure, surface the punch list verbatim and halt. Per-item resolution:
+
+- Prev sprint not closed → run sprint close on prev first.
+- Leftover worktree → `git worktree remove` if abandoned, otherwise merge.
+- Branch ref exists → investigate; force-deletion only with explicit human approval.
+- Dirty main → human commits/stashes/discards. **Never `git reset --hard` or stash without explicit human approval.**
+- Per-item gate fail → run `cleargate gate check <file> -v` for the named item; fix the failing criterion (e.g., populate `context_source`, resolve TBDs); re-run preflight.
+- Devops unreachable → restart Claude Code session; re-run all 6 preflight checks.
+
+### A.2 Cut sprint branch
+
+```bash
+git checkout -b sprint/S-NN main
+```
+
+Sprint branch is **never committed to directly**. All work lands via story-branch merges.
+
+### A.3 Initialize sprint state
+
+```bash
+node .cleargate/scripts/init_sprint.mjs SPRINT-NN
+```
+
+This writes `.cleargate/sprint-runs/SPRINT-NN/state.json` and flips `.cleargate/sprint-runs/.active` to `SPRINT-NN`. Without `state.json` the lane router, dispatch hook, and close pipeline all fail.
+
+`init_sprint.mjs` also writes `<sprintDir>/sprint-context.md` from `.cleargate/templates/sprint_context.md`, populated with `sprint_id` + goal (extracted from sprint plan §0 `- **Sprint Goal:** …` bullet, or placeholder if absent) + active CR list. Every Dev/QA/Architect/DevOps dispatch reads this file as preflight (see §B + §C contracts + agent prompts `## Preflight`).
+
+### A.4 Architect Sprint Design Review (v2 only)
+
+Mandatory under `execution_mode: v2`; optional but encouraged under `v1`. Spawn the Architect with all candidate stories' §3 Implementation Guides + ADRs + flashcards + sprint plan path:
+
+```
+Task instruction: "SPRINT DESIGN REVIEW — write Sprint Plan §2 Execution Strategy.
+You have WRITE ACCESS to Sprint Plan §2 ONLY. Produce §§2.1–2.4 (Phase Plan,
+Merge Ordering, Shared-Surface Warnings, ADR-Conflict Flags) plus §2.4 Lane Audit."
+```
+
+Architect returns a markdown block; you insert it into the sprint plan file. Then halt and ask the human to confirm the sprint plan before any story executes.
+
+### A.5 Flip sprint status
+
+After human confirms, update sprint frontmatter `status: Active` (via `cleargate stamp` after the edit).
+
+> 🎯 **Goal check.** Before the first Architect dispatch, surface the sprint goal verbatim from the plan's `sprint_goal:` frontmatter (or §1 if unstructured) in chat: *"Sprint goal: <verbatim>. Success = this is met by close. Stories are the means; this is the end."* All subsequent halts and decisions reference back to this line.
+
+---
+
+## 4. Phase B — Per-Milestone Architect Plan
+
+Before any Developer dispatches in a milestone, spawn the Architect once for the whole milestone:
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh M<N> architect
+```
+
+Then `Agent(subagent_type=architect, ...)` with the milestone story IDs and instruction to write `.cleargate/sprint-runs/<sprint-id>/plans/M<N>.md`.
+
+**Skip per-milestone Architect for `lane: fast` stories** — they dispatch to Developer without a plan, per the lane contract (see `.claude/agents/architect.md` Lane Classification).
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action (Sprint Goal + Cross-Cutting Rules + Active CRs sections constrain every decision).
+
+> 🎯 **Goal check.** Pass the sprint goal verbatim in the Architect's dispatch prompt. The plan should explicitly tie each story to the goal under "Per-story blueprint" — e.g. *"STORY-NNN-NN advances goal by <one sentence>"*. Plans that don't reference the goal go back to the Architect with a re-dispatch.
+
+---
+
+## 5. Phase C — Per-Story Execution Loop
+
+Run this loop **per story**, in the order the milestone plan declares (parallel waves vs sequential chains). Each iteration: Worktree → **QA-Red** → **TPV (Test Pattern Validation, Architect-only)** → Developer → QA-Verify → (Architect pass for `lane: standard` v2 only) → Merge → Flashcard Gate.
+
+> **Naming note.** State-machine values (`Bouncing`, `Ready to Bounce`), `state.json` counter fields (`qa_bounces`, `arch_bounces`), and script names (`validate_bounce_readiness.mjs`) retain the legacy "bounce" term because they are code-bound. The narrative in this skill uses "execution loop", "story cycle", and "rework" to describe the same mechanics.
+
+### C.1 Pre-execution check
+
+```bash
+node .cleargate/scripts/validate_state.mjs
+node .cleargate/scripts/validate_bounce_readiness.mjs STORY-NNN-NN
+```
+
+`state.json` `sprintId` must equal the active sprint. If not, re-run `init_sprint.mjs` — **do not create a worktree with a stale state.json**.
+
+`validate_bounce_readiness.mjs` checks: story is "Ready to Bounce", §§1/2/3 present, working tree clean. Fail → halt.
+
+### C.2 Create worktree
+
+```bash
+git worktree add .worktrees/STORY-NNN-NN -b story/STORY-NNN-NN sprint/S-NN
+```
+
+Story branch is cut from the **sprint branch**, never from main. Verify:
+
+```bash
+git worktree list
+```
+
+**Do not run `git worktree add` inside `mcp/`.** It is a nested git repo. If the story touches `mcp/`, the Developer edits `mcp/` from inside `.worktrees/STORY-NNN-NN/mcp/...` — visible as a subdirectory of the outer worktree. (`cleargate-enforcement.md` §1.3.)
+
+### C.3 Spawn QA-Red (standard lane only — fast lane skips this step)
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN qa
+```
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the QA-Red dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+Then spawn with `subagent_type=qa`. Dispatch prompt MUST inject:
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+> `Mode: RED — write failing tests against §4 acceptance, no implementation Read access. Tests must fail with "not yet implemented" errors against the clean baseline. File-naming: *.red.node.test.ts (immutable post-Red). Forbidden: editing implementation files.`
+
+QA-Red returns:
+
+```
+QA-RED: WRITTEN | BLOCKED
+RED_TESTS: <list of *.red.node.test.ts files written>
+BASELINE_FAIL: <count of failing scenarios>
+flashcards_flagged: [ ... ]
+```
+
+On `QA-RED: BLOCKED`: surface Spec-Gap to human; do not proceed to §C.4 until resolved.
+
+On `QA-RED: WRITTEN`: orchestrator commits the Red tests on the story branch with subject `qa-red(STORY-NNN-NN): write failing tests`, then proceeds to §C.3.5 TPV Gate.
+
+**Fast lane skip:** if `state.json.stories[<id>].lane === "fast"`, skip this entire step AND §C.3.5 and proceed directly to §C.4 Spawn Developer.
+
+### C.3.5 TPV Gate (Architect-only — standard lane, v2 only)
+
+**Skip if:** `state.json.stories[<id>].lane === 'fast'` OR `execution_mode: v1`.
+
+After QA-Red commits Red tests, spawn the Architect in `Mode: TPV` to perform wiring-only validation before Dev dispatch. TPV does NOT evaluate test logic correctness — it verifies wiring so Dev does not waste a full dispatch on a mis-wired test harness.
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN architect
+```
+
+Dispatch prompt MUST inject:
+
+> `Mode: TPV — Test Pattern Validation only. You receive: story file, QA-Red commit SHA, list of *.red.node.test.ts files. Verify ONLY: (1) imports resolve to real paths, (2) constructor signatures match, (3) mocked methods exist on the mocked object, (4) after-hooks present when before-hooks write state, (5) file naming *.red.node.test.ts. Do NOT evaluate test logic. Return: TPV: APPROVED (Dev proceeds) or TPV: BLOCKED-WIRING-GAP — <one-sentence specific issue> (orchestrator routes back to QA-Red).`
+
+Architect returns one of:
+
+- `TPV: APPROVED` — proceed to §C.4 Spawn Developer.
+- `TPV: BLOCKED-WIRING-GAP — <issue>` — orchestrator increments `arch_bounces` via:
+  ```bash
+  node .cleargate/scripts/update_state.mjs STORY-NNN-NN --arch-bounce
+  ```
+  Then routes back to §C.3 QA-Red with the gap description in the re-dispatch prompt. If `arch_bounces ≥ 3` → flip story to `Escalated`, halt.
+
+TPV is a WIRING gate, not a correctness gate. A test that imports the right module but asserts incorrectly still gets `TPV: APPROVED` — Dev's TDD cycle handles assertion correctness.
+
+### C.4 Spawn Developer
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN developer
+```
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the Developer dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+Then spawn with `subagent_type=developer`. Inputs the prompt must include verbatim:
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+- `STORY=NNN-NN` (Developer must echo this on its first response line).
+- Path to story file.
+- Path to milestone plan.
+- Worktree path (assigned).
+- Sprint ID.
+
+Developer returns:
+
+```
+STORY: STORY-NNN-NN
+STATUS: done | blocked
+COMMIT: <sha> | none
+TYPECHECK: pass | fail
+TESTS: X passed, Y failed
+FILES_CHANGED: <list>
+flashcards_flagged: [ ... ]
+```
+
+If `STATUS=blocked`: route per §C.8 (Blockers Triage).
+
+### C.5 Spawn QA-Verify
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN qa
+```
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the QA-Verify dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+Dispatch prompt MUST inject: `Mode: VERIFY — read-only acceptance trace. Verify Developer's implementation against the story's §4 acceptance Gherkin. Do not write or modify any files.`
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+QA inputs: story file path, worktree path, Developer commit SHA. QA returns:
+
+```
+QA: PASS | FAIL
+ACCEPTANCE_COVERAGE: N of M scenarios
+MISSING: <list>
+REGRESSIONS: <list>
+flashcards_flagged: [ ... ]
+```
+
+**On `QA: FAIL`:** increment `qa_bounces` via `update_state.mjs STORY-NNN-NN --qa-bounce`. If counter ≥ 3 → flip story to `Escalated`, surface to human, halt. Else → re-spawn Developer with QA's bug report as input. Return to §C.4.
+
+**On `QA: PASS`:** update state to `QA Passed`, proceed.
+
+### C.6 Architect Pass (v2, `lane: standard` only)
+
+`lane: fast` skips this step entirely.
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the Architect Pass dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+```bash
+bash .cleargate/scripts/pre_gate_runner.sh arch .worktrees/STORY-NNN-NN/ sprint/S-NN
+```
+
+If pre-gate scan reveals new dependencies / structural issues → return to Developer (do NOT spawn Architect for mechanical failures). 3+ pre-gate failures → escalate.
+
+If pre-gate passes, spawn Architect for post-flight review. On `FAIL`: increment `arch_bounces`. ≥ 3 → escalate.
+
+### C.7 Story Merge
+
+**DevOps-owned.** The orchestrator does NOT run `git merge`, `git worktree remove`, `git branch -d`, `update_state.mjs`, or `npm run prebuild` directly. All mechanical merge work is delegated to the DevOps agent.
+
+**Required reports — verify before dispatch:**
+
+| Report | Required when |
+|---|---|
+| `STORY-NNN-NN-dev.md` | Always (all lanes) |
+| `STORY-NNN-NN-qa.md` | Always, unless lane=fast explicitly skipped QA-Verify |
+| `STORY-NNN-NN-arch.md` | v2 standard-lane only |
+| `STORY-NNN-NN-devops.md` | Written BY DevOps during this step (not a prerequisite) |
+
+Missing `dev.md` or `qa.md` (when required) → return to spawn that agent. **Do not dispatch DevOps with missing reports.**
+
+**Orchestrator dispatch sequence:**
+
+1. Mark the dispatch:
+   ```bash
+   bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN devops
+   ```
+
+2. Spawn the DevOps agent with the following context (§3.1 Context Pack):
+   ```
+   SPRINT-{NN} — DevOps dispatch for {STORY-ID}.
+
+   INPUTS:
+   - Story ID: {STORY-ID}
+   - Sprint ID: SPRINT-{NN}
+   - Worktree path: .worktrees/{STORY-ID}/
+   - Story branch: story/{STORY-ID}
+   - Sprint branch: sprint/S-{NN}
+   - Dev commit SHA: {abc1234}
+   - QA commit SHA (if present): {def5678}
+   - Architect commit SHA (if present): {ghi9012}
+   - Files-changed manifest: {list from git show --stat <dev-sha>}
+   - Canonical scaffold touched? {yes|no}
+   - Lane: {standard | fast}
+   - Required reports present:
+       - {STORY-ID}-dev.md    ✓
+       - {STORY-ID}-qa.md     ✓ (or "skipped — fast lane")
+       - {STORY-ID}-arch.md   ✓ (v2 standard lane only)
+
+   ACTIONS (in order):
+   1. Verify all required reports exist; halt if any missing.
+   2. Checkout sprint branch.
+   3. git merge story/{STORY-ID} --no-ff -m "merge(story/{STORY-ID}): {commit subject}"
+   4. If canonical scaffold touched: cd cleargate-cli && npm run prebuild
+   5. Mirror parity audit: for each file in files-changed where canonical mirror exists,
+      diff live ↔ canonical. Report drift in §Mirror Parity (DO NOT auto-fix).
+   6. Post-merge test verification: run only test files touched by this commit.
+   7. git worktree remove .worktrees/{STORY-ID}
+   8. git branch -d story/{STORY-ID}
+   9. CLEARGATE_STATE_FILE=... node .cleargate/scripts/update_state.mjs {STORY-ID} Done
+   ```
+
+3. **Halt** and wait for DevOps to return `STATUS=done` or `STATUS=blocked`.
+
+**On `STATUS=done`:** DevOps has written `.cleargate/sprint-runs/SPRINT-{NN}/reports/{STORY-ID}-devops.md`. If it notes live re-sync needed (mirror parity drift), address via `cleargate init` or hand-port at Gate-4 doc-refresh (see §C.9 Flashcard Gate for the next step, then proceed to the next story / wave).
+
+**On `STATUS=blocked`:** DevOps has written `{STORY-ID}-devops-blockers.md`. Surface the blockers report to the human. DevOps does NOT auto-resolve conflicts — orchestrator escalates and waits for human resolution before re-dispatching DevOps.
+
+**Forbidden orchestrator patterns (v2):** `git merge`, `git worktree remove`, `git branch -d`, `update_state.mjs`, `npm run prebuild` in the orchestrator's main session bash log. If any appear, classify as edge case and document in sprint §4 Execution Log.
+
+#### DevOps Escape Hatch — subagent_type=devops unavailable
+
+If spawning `Agent(subagent_type=devops)` returns "Agent type 'devops' not found" (registry miss — see §1 registration constraint note), the orchestrator executes the §C.7 ACTIONS steps 2-9 verbatim inline (in the orchestrator's own bash session). All rules still apply: no `git merge` short-circuit, no conflict auto-resolution. Write the same `STORY-NNN-NN-devops.md` report with an additional frontmatter field `operator: orchestrator-fallback` and note the session restart requirement. This path is exceptional — if it triggers, queue a session restart at the next natural break and verify `devops` appears in the next session's available agent list before continuing the sprint.
+
+### C.8 Blockers Triage (Developer circuit breaker)
+
+When Developer returns `BLOCKED: circuit breaker triggered`, read `.cleargate/sprint-runs/<id>/reports/STORY-NNN-NN-dev-blockers.md`. The report has three sections:
+
+| Non-N/A section | Routing |
+|---|---|
+| `## Test-Pattern` | Re-launch Developer with the pattern hint as additional context. Pass the sentence verbatim in the new prompt. |
+| `## Spec-Gap` | **Halt and surface the sentence to the human.** Do NOT re-launch Developer until human clarifies. |
+| `## Environment` | Re-run `pre_gate_runner.sh`. If pre-gate passes, re-launch Developer; otherwise surface env issue. |
+
+3 consecutive circuit-breaker hits on the same story → `update_state.mjs STORY-NNN-NN Escalated`, halt.
+
+### C.9 Flashcard Gate (v2 mandatory; v1 dogfood)
+
+After every story merge — **before creating story N+1's worktree** — process the merged `flashcards_flagged` list (union of dev + QA, dedupe by exact-string):
+
+For each card:
+
+| Action | Effect |
+|---|---|
+| **Approve** | Append the line verbatim to `.cleargate/FLASHCARD.md` (newest-first). |
+| **Reject** | Discard. Log `FLASHCARD-REJECT YYYY-MM-DD — "<card>" — reason: <one sentence>` in sprint §4 Execution Log. |
+
+Then mark each card processed:
+
+```bash
+HASH=$(printf '%s' "<card text>" | shasum -a 1 | cut -c1-12)
+touch .cleargate/sprint-runs/<sprint-id>/.processed-${HASH}
+```
+
+Under v2, the `pending-task-sentinel.sh` PreToolUse hook blocks the next `Task` spawn until every card has a `.processed-<hash>` marker. Bypass only with `SKIP_FLASHCARD_GATE=1` — log the bypass in sprint §4.
+
+### C.10 Mid-Sprint Triage
+
+When the user injects new input mid-sprint (between story kickoff and merge), classify it before routing. Use the keyword-heuristic classifier (`classify()` from `cleargate-cli/src/lib/triage-classifier.ts`) as a first-pass advisory, then confirm. See authoritative rubric: `.cleargate/knowledge/mid-sprint-triage-rubric.md`.
+
+| Class | Trigger | Counter | Human Approval | First-pass action |
+|---|---|---|---|---|
+| `bug` | Defect vs spec | `qa_bounces++` | No | Re-open story; Dev fix; QA re-verify |
+| `clarification` | Ambiguity question | None | No (yes if spec gap) | Update §1.2 in place; re-run impacted test |
+| `scope` | Net-new requirement | None | YES for mid-sprint add | Quarantine to next sprint (default); escalate if goal-critical |
+| `approach` | Different impl, same spec | None | No (yes if cross-story impact) | Reset Dev context; re-spawn with updated approach |
+
+**Confidence signal:** `classify()` returns `confidence: 'low'` when no keyword matched. LOW confidence classifications MUST be confirmed with the human before routing.
+
+**Scope-only note:** This rubric covers USER input only. QA-FAIL bounces continue to use `qa_bounces` (existing §C.5 path). TPV-gap bounces use `arch_bounces` (§C.3.5 path).
+
+For the operational routing table with per-type routing rules, see §C.11 (Mid-cycle User Input — CR Triage).
+
+### C.11 Mid-cycle User Input — CR Triage
+
+If the user injects new input mid-story, classify before routing:
+
+| Type | Effect | Routing |
+|---|---|---|
+| `CR:bug` | Defect in current story | Increments `qa_bounces`; re-open story; Dev fixes; QA re-verifies |
+| `CR:spec-clarification` | Removes ambiguity, no new scope | No counter; update §1.2 in place; re-run impacted test |
+| `CR:scope-change` | Net-new requirement | **Quarantine.** New Story file in `pending-sync/`; current story unchanged |
+| `CR:approach-change` | Different impl, same spec | No counter; reset Dev context; re-spawn with updated approach |
+
+Log every CR in sprint §4 Execution Log with date + ID.
+
+> 🎯 **Goal check on `CR:scope-change`.** Default routing is quarantine-into-next-sprint. **Override the default if the new requirement is critical to the active sprint goal** — escalate to the human with: *"This scope-change is goal-critical: the sprint goal is `<verbatim>` and without this change, the goal will not be met. Add to current sprint? (Adding mid-sprint requires explicit ack per §C.11.)"* Quarantine remains default for goal-incidental scope.
+
+### C.11 Script Invocation Contract (CR-046)
+
+All bash/node script invocations dispatched FROM agents (Developer / QA / Architect / DevOps) MUST use the wrapper:
+
+```bash
+bash .cleargate/scripts/run_script.sh <command> [args...]
+```
+
+**What the wrapper does (on failure):**
+- Captures stdout + stderr independently (≤4KB each; truncated with `... [truncated]` if exceeded).
+- Writes a structured JSON incident to `.cleargate/sprint-runs/<sprint-id>/.script-incidents/<ts>-<hash>.json`.
+- Propagates the original exit code to the caller.
+
+**Self-exemption clause:** The wrapper itself (`run_script.sh`) is exempt from wrapping — it sets `RUN_SCRIPT_ACTIVE=1` before executing the wrapped command so recursive calls pass through directly. Orchestrator-direct invocations of `run_script.sh` are the canonical entry point; they are exempt by this contract.
+
+**Agent reporting obligation:** If a wrapped script fails (incident JSON written), the dispatching agent MUST include the incident JSON path in its report's `## Script Incidents` section.
+
+**Pre-sprint invocations (before `.active` sentinel exists):** Wrapper writes to `.cleargate/sprint-runs/_off-sprint/.script-incidents/` when no active sprint is detected. This is expected during preflight steps.
+
+---
+
+## 6. Phase D — Sprint Walkthrough (v2)
+
+Mandatory under v2. After all stories merged into `sprint/S-NN` (every story state ∈ `TERMINAL_STATES`) and **before** sprint→main merge, invite the user to test on the sprint branch. Classify every piece of feedback:
+
+| Event | Definition | Bug-Fix Tax |
+|---|---|---|
+| `UR:bug` | Defect, crash, behavior broken vs spec | Increments |
+| `UR:review-feedback` | Polish, copy, UX preference | Does not increment |
+
+**When in doubt, ask:** "Is this broken vs spec, or a preference?" Do not default to `UR:bug`.
+
+Log every event in sprint §4. **Sprint branch MUST NOT merge to main while any `UR:bug` is unresolved.** `UR:review-feedback` may defer with explicit human sign-off.
+
+> 🎯 **Goal check.** Open the walkthrough invitation with the sprint goal verbatim, not a feature checklist: *"Sprint goal: `<verbatim>`. The branch is ready on `sprint/S-NN`. Test it and tell me — does the running build achieve the goal?"* This forces the framing to be outcome-vs-spec rather than feature-tour.
+
+---
+
+## 7. Phase E — Gate 4 Close (Reporter + Human Sign-off)
+
+This is a **Gate-3-class action**. Authorising sprint execution does NOT authorise close. Close requires its own dedicated human approval.
+
+### E.1 Step A — orchestrator runs close
+
+```bash
+node .cleargate/scripts/close_sprint.mjs <sprint-id>
+```
+
+No flags. Script validates Steps 1–2.6 (lifecycle reconciler runs at Step 2.6; see `cleargate-enforcement.md` §10), prefills `SPRINT-<#>_REPORT.md` stub if missing via the Reporter agent, and exits 0 with the prompt:
+
+> Review the report, then confirm close by re-running with --assume-ack.
+
+### E.2 Reporter dispatch (Step 3.5)
+
+If the report stub does not exist, dispatch the Reporter:
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh SPRINT-NN reporter
+```
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+> **Fresh session.** The Reporter MUST dispatch in a fresh session — do not inherit dev+qa cumulative context. `write_dispatch.sh` already spawns a clean shell child; the `Agent` tool path requires no session-continuation flag. If the runtime offers a session-reset knob (e.g. `--resume false` or equivalent), use it. The Reporter starts cold and reads only `.reporter-context.md` + `sprint_report.md`.
+
+> **Token budget.** Soft warn at 200k tokens, hard advisory at 500k (per CR-036). The token-ledger SubagentStop hook emits the warning to stdout; orchestrator surfaces the line into chat. Hard advisory auto-records a flashcard. The dispatch is NOT killed — the warning is informational; review the bundle slices on next sprint.
+
+Reporter writes `.cleargate/sprint-runs/<id>/SPRINT-<#>_REPORT.md` and returns the Brief:
+
+> **Goal:** `<verbatim sprint goal>` — **Verdict: met | partial | missed.**
+> Delivered N stories, M epics. Observe: X bugs, Y review-feedback. Carry-over: Z. Token cost: T.
+> See SPRINT-\<#>_REPORT.md for full report.
+> Ready to authorize close (Gate 4)?
+
+> 🎯 **Goal check.** The verdict line is mandatory and is the first line of the Brief. `met` = goal achieved as written. `partial` = some sprint-goal acceptance criteria met, others not — explain which in REPORT §1. `missed` = goal not achieved despite stories merging. A `partial` or `missed` verdict does NOT block close, but it is a first-class signal to the human that close-ack should be deliberate, not reflexive.
+
+### E.3 Step B — surface and HALT
+
+Surface the Brief verbatim to the human. **Halt.** Do not re-run with `--assume-ack`.
+
+The human either:
+
+- Re-runs `close_sprint.mjs <id> --assume-ack` themselves, OR
+- Says "approved, close it" — at which point you may pass the flag on their behalf.
+
+`--assume-ack` is reserved for **automated test environments only**. Passing it autonomously is a Gate-4 breach equivalent to an unauthorized push.
+
+### E.4 Doc & metadata refresh on close
+
+During Gate 4 sign-off, read `.cleargate/sprint-runs/<id>/.doc-refresh-checklist.md` (generated by `prep_doc_refresh.mjs`). Apply or punt each `- [ ]` item per `.cleargate/knowledge/sprint-closeout-checklist.md`. Items already `- [x]` mean "no changes detected, skip."
+
+### E.5 Sprint→main merge
+
+After sign-off and after all walkthrough `UR:bug` items resolved:
+
+```bash
+git checkout main
+git merge sprint/S-NN --no-ff -m "Sprint S-NN: <goal>"
+```
+
+Then flip sprint frontmatter `status: Completed`, archive the sprint file (`pending-sync/` → `archive/`).
+
+---
+
+## 8. Rework Counter Quick Reference
+
+| Counter | Increment trigger | Escalation |
+|---|---|---|
+| `qa_bounces` | Each `QA: FAIL` | ≥ 3 → `Escalated`, halt |
+| `arch_bounces` | Each `Architect: FAIL` | ≥ 3 → `Escalated`, halt |
+| Circuit breaker | 50 tool calls without test pass OR 2 identical failures | 3 hits same story → `Escalated`, halt |
+| Pre-gate failures | Each `pre_gate_runner.sh` non-zero | 3 hits same story → human escalation (descope / re-approach) |
+
+> 🎯 **Goal check on escalation.** When a story flips to `Escalated`, frame the human-decision question through the goal lens, not in isolation: *"STORY-NNN-NN escalated after N rework cycles. Sprint goal is `<verbatim>`. Options: (a) drop the story — is the goal still met without it? (b) re-approach with X — same goal met by sprint end? (c) split into smaller stories — which scope serves the goal? (d) defer to next sprint — does the goal change?"* Never present escalation as a generic "what do you want to do?" — always tie options to goal achievement.
+
+State updates go through:
+
+```bash
+node .cleargate/scripts/update_state.mjs STORY-NNN-NN [--qa-bounce | --arch-bounce | <new-state>]
+```
+
+`Escalated` halts the loop until human decides: descope, re-assign approach, or split story.
+
+---
+
+## 9. File-Surface Contract (v2)
+
+Each story's §3.1 "Context & Files" table is the **authoritative file surface** for its commit. The pre-commit hook (`.git/hooks/pre-commit` → `.claude/hooks/pre-commit-surface-gate.sh`) blocks commits that touch off-surface files.
+
+Off-surface edits require **either**:
+
+1. A `CR:scope-change` approved before the commit, OR
+2. An updated §3.1 table committed in the same story (self-amending — must be justified in commit message).
+
+Bypass with `SKIP_SURFACE_GATE=1` only when absolutely necessary; log in sprint §4. Under v1 the hook only warns.
+
+---
+
+## 10. What This Skill Does NOT Cover
+
+These live elsewhere — do not duplicate inline:
+
+- **Triage / drafting / Gate 1 Brief** → CLAUDE.md + `cleargate-protocol.md` §§1–4.
+- **Worktree command details and edge cases** → `cleargate-enforcement.md` §1.
+- **Lane classification rubric (7 checks)** → `.claude/agents/architect.md` Lane Classification + `cleargate-enforcement.md` §9.
+- **Sprint Plan template / Gate 2 Sprint Ready** → `.cleargate/templates/Sprint Plan Template.md`.
+- **Wiki ingest / lint / contradiction detection** → `cleargate-protocol.md` §10.
+- **Doctor exit codes** → `cleargate-enforcement.md` §8.
+- **Hotfix flow** → V-Bounce-style hotfix handling, see flashcard tag `#hotfix` and `wiki/topics/hotfix-ledger.md`.
+
+When in doubt, read the source-of-truth doc — this skill cites them, it does not replace them.
+
+---
+
+## 11. Conversational Discipline During Execution
+
+- **Sprint execution is autonomous.** Once started, run the loop end-to-end. Escalate only on blockers, gate failures, or destructive operations.
+- **Terse output.** Status updates one sentence each. Details live in story reports and `SPRINT-<#>_REPORT.md`, not in chat.
+- **Halt at gates without negotiation.** Gate 3 (preflight), Gate 4 (close sign-off), `Escalated` state — these are not advisory. Surface, halt, wait.
+- **Never `--no-verify`, `--assume-ack` autonomously, force-push, or `git reset --hard`.** Every one of these requires explicit per-action human approval.
+- **Verify, don't trust agent self-reports.** A Developer claiming `STATUS=done` is not done — QA verifies. A `QA: PASS` is not approved-to-merge until reports exist and merge prerequisites pass.