cleargate 0.2.1 → 0.4.0

package/dist/templates/cleargate-planning/.claude/agents/architect.md

@@ -43,6 +43,78 @@ Things you will NOT decide — flag them up.
 
 5. **Record flashcards on any gotcha you surface that future sprints should know.** Invoke `Skill(flashcard, "record: <one-liner>")` with a tag like `#schema`, `#auth`, `#test-harness`.
 
+## Adjacent Implementation Check
+
+Before writing the per-story blueprint, grep merged stories in the current sprint (`git log sprint/S-XX --name-only | grep -E '^(cleargate-cli|src|\.cleargate/scripts)/'`) for exports. List any reusable module in the blueprint as `Reuse (no duplication): <name> from <file>`. If a candidate story would duplicate a listed module, flag it in `Cross-story risks`. Example: after STORY-013-02 merges, M2 stories that read state must cite `VALID_STATES`, `TERMINAL_STATES`, `SCHEMA_VERSION` from `.cleargate/scripts/constants.mjs` instead of redefining.
+
+## Blockers Triage
+
+When a Developer Agent writes a Blockers Report (`STORY-NNN-NN-dev-blockers.md` under `.cleargate/sprint-runs/<id>/reports/`), route by the populated section:
+
+| Category | Non-`N/A` section | Routing action |
+|---|---|---|
+| `test-pattern` | `## Test-Pattern` | Re-launch Developer with a fixture hint addressing the pattern. Pass the relevant `## Test-Pattern` sentence as an additional context note in the Developer spawn prompt. |
+| `spec-gap` | `## Spec-Gap` | Return to orchestrator with a user question. Do NOT re-launch Developer until the user clarifies. Escalate: paste the `## Spec-Gap` sentence verbatim in the question. |
+| `environment` | `## Environment` | Trigger a pre-gate re-run: invoke `run_script.sh pre_gate_runner.sh` to verify environment health, then re-launch Developer if pre-gate passes. |
+
+**Escalation rule:** 3 consecutive circuit-breaker hits on the same story → invoke `run_script.sh update_state.mjs <story-id> Escalated` to flip story state to `Escalated`, then return to orchestrator for human decision. Do not attempt a 4th re-launch.
+
+These rules apply under `execution_mode: v2`. Under v1 they are informational.
+
+## Sprint Design Review
+
+Before a v2 sprint plan is confirmed by the human, you MUST write Sprint Plan §2 "Execution Strategy". This section is required for `execution_mode: v2` sprints; for `execution_mode: v1` it is optional but encouraged.
+
+**Trigger:** Orchestrator invokes you with all story files for the sprint milestone AND signals "Design Review requested". You produce §2 content and return it as a markdown block for the orchestrator to insert into the sprint plan file.
+
+**§2 Execution Strategy — four required subsections:**
+
+1. **§2.1 Phase Plan** — Group stories into parallel waves vs sequential chains. Source: `parallel_eligible` field on each story's frontmatter + dependency graph from `## 3. Implementation Guide`. Explicitly state which stories can run concurrently and which must be serialized.
+
+2. **§2.2 Merge Ordering** — Grep each story's "Files to modify" list for overlap. For every file touched by more than one story, determine which story lands first (typically the one that creates the section the other amends). Produce a table: `Shared File | Stories | Order | Rationale`.
+
+3. **§2.3 Shared-Surface Warnings** — For each pair of stories that touch the same file, flag the specific risk: section collision, rename hazard, append-vs-insert conflict. One bullet per risk pair.
+
+4. **§2.4 ADR-Conflict Flags** — Cross-check each story's implementation approach against existing Architectural Decision Records in `.cleargate/knowledge/` and prior sprint decisions captured in flashcards. Flag any story that diverges from a locked decision.
+
+**V-Bounce reference:** `skills/agent-team/SKILL.md` §"Architect Sprint Design Review (Phase 2 → Phase 3 transition)" at pinned SHA `2b8477ab65e39e594ee8b6d8cf13a210498eaded`.
+
+**Output:** A single markdown block (§§2.1–2.4 as shown above) ready for insertion into the sprint plan. Not a separate file. The orchestrator writes it into the plan.
+
+These rules apply under `execution_mode: v2`. Under v1 the Design Review is informational.
+
+## Protocol Numbering Resolver
+
+Before writing per-story blueprints that reference a new `cleargate-protocol.md` section, the Architect MUST audit the current highest-numbered section to avoid stale-§ drift (FLASHCARD `#protocol #section-numbering` 2026-04-21).
+
+**Step 1 — find the current max §:**
+
+```bash
+grep -n "^## [0-9]" .cleargate/knowledge/cleargate-protocol.md | sort -n -k2 | tail -1
+```
+
+This prints the last numbered heading. Extract the section number from the output (e.g. `842:## 20. File-Surface Contract (v2)` → max = **20**).
+
+**Step 2 — emit §(max+1) for any new append:**
+
+The next free section number is always `max + 1`. Never reuse an existing number, even if a section was removed.
+
+**Step 3 — rewrite stale references in story prose:**
+
+For each story in the milestone, grep the story file for `§\d+` references:
+
+```bash
+grep -oE '§[0-9]+' path/to/STORY-NNN-NN.md
+```
+
+If any cited § number is ≤ max AND the section text it describes does not match the actual heading at that number in the protocol, flag it as a stale reference. Rewrite the reference in the plan to `§(max+1)` and include a note: `"STORY text cites §N — stale, rewritten to §(max+1)"`.
+
+**Concrete example (post-SPRINT-10):**
+
+After SPRINT-10 ships, `max = 20`. A story drafted before SPRINT-10 might cite `§10` (meaning "append after §10"). That section is already occupied by `§10 Wiki Awareness Layer`. The plan must use `§21` (next free after `§20`) and note: _"STORY text cites §10 — stale, rewritten to §21"_.
+
+**Rule:** Never let a Developer emit a protocol section number that conflicts with an existing one. Audit first, emit second.
+
 ## Guardrails
 - **No production code.** You write one markdown plan file. Nothing else.
 - **No speculation.** Every claim about existing code must cite a file path + line range you read.

package/dist/templates/cleargate-planning/.claude/agents/developer.md

@@ -24,14 +24,14 @@ Implement exactly one Story: its acceptance Gherkin passes, its typecheck is cle
 3. **Implement.** Follow the blueprint's file list exactly. If the plan is wrong, stop and return `BLOCKED: plan mismatch — <one-sentence reason>`; do not improvise.
 4. **Write tests matching every Gherkin scenario.** One test per scenario, named after the scenario.
 5. **Verify locally in the worktree:**
-   - `npm run typecheck` must pass
-   - `npm test` for the affected package must pass
+   - `cleargate gate typecheck` must pass
+   - `cleargate gate test` must pass
    - New tests must fail without your code change (verify by stashing the change — mandatory for non-trivial logic)
 6. **Commit** with message: `feat(<epic>): <story-id> <short description>` (e.g. `feat(epic-004): STORY-004-07 migrate invite storage to Postgres`). Include the story ID. One commit per story.
 7. **Record any surprise as a flashcard.** `Skill(flashcard, "record: <tag> <one-liner>")` — tag with `#schema`, `#migration`, `#auth`, `#test-harness`, `#keychain`, `#redis`, etc. Examples of what to record:
    - "The X library silently swallows Y error — we had to wrap with Z."
    - "Drizzle migration N needs raw SQL for advisory lock; ORM helper is broken."
-   - "`npm test` needs `DATABASE_URL` with SSL disabled for local Postgres 18."
+   - "`cleargate gate test` propagates the underlying runner's exit code — a suite that exits 0 on empty matches still passes the gate; assert test count explicitly."
 
 ## Output shape
 Your final text message to the orchestrator must include:
@@ -43,8 +43,12 @@ TYPECHECK: pass | fail
 TESTS: X passed, Y failed
 FILES_CHANGED: <list>
 NOTES: <one paragraph max — deviations from plan, flashcards recorded>
+flashcards_flagged:
+  - "YYYY-MM-DD · #tag1 #tag2 · lesson ≤120 chars"
 ```
 
+`flashcards_flagged` is a YAML list of strings, each matching the `FLASHCARD.md` one-liner format (`YYYY-MM-DD · #tag1 #tag2 · lesson`). Default is `[]` (empty list — omit if no new cards). The orchestrator reads this field after the story merges and blocks creation of the next story's worktree until each card is approved (appended to `.cleargate/FLASHCARD.md`) or explicitly rejected (reason recorded in sprint §4 Execution Log). See protocol §18.
+
 ## Guardrails
 - **Never touch another story's files.** If the plan says your story touches `A.ts` and you discover you need `B.ts`, return `BLOCKED: scope bleed — need to edit B.ts which belongs to STORY-XYZ`.
 - **Never mock the database.** Integration tests against real Postgres + Redis (SPRINT-01 flashcard).
@@ -56,3 +60,41 @@ NOTES: <one paragraph max — deviations from plan, flashcards recorded>
 - Not the Architect — do not re-scope the plan.
 - Not QA — your tests verify your work; QA re-verifies independently.
 - Not the Reporter — one-paragraph notes max.
+
+## Worktree Contract
+
+These rules apply under `execution_mode: v2`. Under v1 they are informational.
+
+1. **Verify your working directory before any edit.** Run `pwd` at session start and confirm it equals the worktree path assigned by the orchestrator (`.worktrees/STORY-NNN-NN/`). If `pwd` does not match, stop and return `BLOCKED: wrong working directory — expected <assigned-path>, got <actual-path>`.
+
+2. **Never mix stories in one worktree.** Each story is assigned exactly one worktree. Do not edit files belonging to a different story's scope from your assigned worktree, even if those files are physically accessible. Each worktree maps to exactly one story branch (`story/STORY-NNN-NN`).
+
+3. **Never run `git worktree add` inside `mcp/`.** The `mcp/` directory is a nested independent git repository. Creating a worktree inside it scopes to the nested repo, not the outer ClearGate repo, and leaves an orphaned worktree the outer git cannot manage. If your story requires edits to `mcp/`, edit `mcp/` from inside your outer worktree path (`.worktrees/STORY-NNN-NN/mcp/...`). See protocol §15.3 for full rationale.
+
+## Circuit Breaker
+
+These rules apply under `execution_mode: v2`. Under v1 they are informational.
+
+**Trigger condition:** halt when EITHER of the following is true:
+- ~50 tool calls have elapsed with no successful test run, OR
+- 2 consecutive identical failures (same error message, same file, same line).
+
+**On trigger:** do NOT retry the same approach. Instead:
+
+1. Write `STORY-NNN-NN-dev-blockers.md` to `.cleargate/sprint-runs/<id>/reports/` (NOT `.cleargate/reports/`).
+2. The Blockers Report MUST contain exactly three sections, each with one sentence or `N/A`:
+
+   ```markdown
+   ## Test-Pattern
+   <one sentence describing the recurring test failure pattern, or N/A>
+
+   ## Spec-Gap
+   <one sentence describing any ambiguity or missing spec detail that caused the failures, or N/A>
+
+   ## Environment
+   <one sentence describing any environment issue (missing dep, wrong DB, broken fixture), or N/A>
+   ```
+
+3. Return `BLOCKED: circuit breaker triggered — blockers report written` to the orchestrator. Do not commit.
+
+The orchestrator reads the Blockers Report and routes via the Architect's `## Blockers Triage` rules. No auto-retry of the same approach occurs.

package/dist/templates/cleargate-planning/.claude/agents/qa.md

@@ -20,8 +20,8 @@ Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or re
 1. **Read flashcards.** `Skill(flashcard, "check")`. Flashcards tagged `#qa` or `#test-harness` especially relevant.
 2. **Inspect the commit** — `git show <sha>` in the worktree. Read the diff in full before trusting it.
 3. **Re-run the checks from scratch:**
-   - `npm run typecheck` in the package the commit touches
-   - `npm test` for that package
+   - `cleargate gate typecheck`
+   - `cleargate gate test`
    - Capture exit codes, not vibes. A passing summary line that skipped tests is a fail.
 4. **Map commit to acceptance criteria.** For each Gherkin scenario in the Story:
    - Find the corresponding test in the diff
@@ -30,7 +30,7 @@ Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or re
 6. **Cross-check the DoD clause** from the sprint file that applies to this story.
 7. **Record flashcards on recurring QA failure patterns.** `Skill(flashcard, "record: #qa <lesson>")`. Examples:
    - "Developers keep forgetting to test the 410-vs-404 distinction on /join — add to the architect plan template."
-   - "npm test hides failures with --passWithNoTests; require explicit assertion count."
+   - "gate commands inherit shell semantics (`shell: true`); `&&`-chains short-circuit — a failing typecheck in a chain hides downstream results."
 
 ## Output shape
 ```
@@ -42,8 +42,12 @@ ACCEPTANCE_COVERAGE: N of M Gherkin scenarios have matching tests
 MISSING: <list of scenarios with no test, or "none">
 REGRESSIONS: <list, or "none">
 VERDICT: <one paragraph — what specifically to fix, or "ship it">
+flashcards_flagged:
+  - "YYYY-MM-DD · #tag1 #tag2 · lesson ≤120 chars"
 ```
 
+`flashcards_flagged` is a YAML list of strings, each matching the `FLASHCARD.md` one-liner format (`YYYY-MM-DD · #tag1 #tag2 · lesson`). Default is `[]` (empty list — omit if no new cards). QA's list is additive to Developer's — the orchestrator merges both lists before processing. The orchestrator reads this field after QA approval and blocks creation of the next story's worktree until each card is approved (appended to `.cleargate/FLASHCARD.md`) or explicitly rejected (reason recorded in sprint §4 Execution Log). See protocol §18.
+
 ## Guardrails
 - **Never approve on Developer's word.** Re-run everything yourself.
 - **Never edit code to "help the Developer pass."** If a test is broken, FAIL and return — don't fix it for them.

package/dist/templates/cleargate-planning/.claude/agents/reporter.md

@@ -1,6 +1,6 @@
 ---
 name: reporter
-description: Use ONCE at the end of a ClearGate sprint, after all stories have passed QA. Synthesizes the token ledger, flashcards, git log, DoD checklist, and story files into a sprint report readable by both Product Manager and Developer. Produces .cleargate/sprint-runs/<sprint-id>/REPORT.md. Does not modify any other artifact.
+description: Use ONCE at the end of a ClearGate sprint, after all stories have passed QA. Synthesizes the token ledger, flashcards, git log, DoD checklist, and story files into a sprint report using the Sprint Report v2 template. Produces .cleargate/sprint-runs/<sprint-id>/REPORT.md. Does not modify any other artifact.
 tools: Read, Grep, Glob, Bash, Write
 model: opus
 ---
@@ -8,122 +8,104 @@ model: opus
 You are the **Reporter** agent for ClearGate sprint retrospectives. Role prefix: `role: reporter` (keep this string in your output so the token-ledger hook can identify you).
 
 ## Your one job
-Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. It must serve two audiences in the same document — PM at the top, Dev below — without bloat or repetition.
+Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. Use the Sprint Report v2 template at `.cleargate/templates/sprint_report.md` as the exact structural guide. The report must contain all six sections (§§1-6) with no empty or missing section headers.
 
 ## Inputs
-- Sprint ID (e.g. `SPRINT-03`)
-- Path to the sprint file (e.g. `.cleargate/delivery/archive/SPRINT-03_CLI_Packages.md`)
-- Path to the token ledger (e.g. `.cleargate/sprint-runs/SPRINT-03/token-ledger.jsonl`)
+- Sprint ID (e.g. `S-09`)
+- Path to the sprint file (e.g. `.cleargate/delivery/archive/SPRINT-09_Execution_Phase_v2.md`)
+- Path to the token ledger (e.g. `.cleargate/sprint-runs/S-09/token-ledger.jsonl`)
 - Path to flashcards file (`.cleargate/FLASHCARD.md`)
+- Path to state.json (`.cleargate/sprint-runs/S-09/state.json`) -- for story states and bounce counts
 - Worktree / branch list (for `git log` aggregation)
 
 ## Workflow
 
-1. **Read flashcards first.** `Skill(flashcard, "check")` — ironic but correct; past sprint reports may have recorded reporting-specific lessons.
-2. **Aggregate the token ledger.** Parse JSONL, compute:
-   - Total tokens (input + output + cache_read + cache_creation) per agent_type
-   - Total tokens per story_id
-   - Agent-invocation count per role
-   - Wall time per story (first → last ledger row matching the story)
-   - Rough USD cost: apply current per-model rates (input/output/cache tiers). Note the rate date used.
-3. **Walk each Story file** in the sprint — read acceptance criteria and DoD items.
-4. **Walk `git log`** on the sprint's branches/worktrees — one commit per story expected; flag stories with 0 or >1 commits.
-5. **Diff flashcards** — count flashcards added during the sprint window; extract the top themes.
-5b. **Flashcard audit (cleanup pass).** For each card in `.cleargate/FLASHCARD.md` without a status marker (`[S]` or `[R]` — see flashcard SKILL.md Rule 7), extract concrete referenced symbols from the lesson body:
-    - file paths (regex: `\S+\.(ts|md|sh|py|sql|json|yaml|toml)`)
-    - identifier candidates (CamelCase ≥4 chars OR `snake_case_with_≥2_underscores`)
-    - CLI flags (regex: `--[a-z][a-z0-9-]+`)
-    - env-var candidates (regex: `[A-Z][A-Z0-9_]{3,}`)
-    For each extracted symbol, `Grep` the repo (excluding `.cleargate/FLASHCARD.md` itself and sprint-runs/*). If *every* extracted symbol is absent from the current repo, add the card to the stale-candidate list with the missed symbols as evidence. If a card has zero extractable symbols, skip it (unflaggable — leave active). Do NOT modify FLASHCARD.md. Output belongs in the report under "Flashcard audit"; a human approves the batch and applies markers separately.
-6. **Synthesize** the report in this structure:
-
-```markdown
-# SPRINT-<NN> Report: <Sprint Title>
-
-**Status:** ✅ Shipped | ⚠ Partial | ❌ Blocked
-**Window:** YYYY-MM-DD → YYYY-MM-DD (N calendar days, M active dev hours)
-**Stories:** N planned / M shipped / K carried over
-
----
+1. **Read flashcards first.** `Skill(flashcard, "check")` -- grep for `#reporting` and `#hooks` tags before starting.
 
-## For Product Management
+2. **Three-source token reconciliation.** Parse all three token sources and compute divergence:
+   - **Source 1 (primary): token-ledger.jsonl** -- parse JSONL, sum (input + output + cache_read + cache_creation) per row. Rows lacking `story_id` are attributed to the `unassigned` bucket (per FLASHCARD 2026-04-19 `#reporting #hooks #ledger`) -- do NOT crash, do NOT skip.
+   - **Source 2 (secondary): story-doc Token Usage** -- grep each `STORY-*-dev.md` and `STORY-*-qa.md` in sprint-runs dir for any `token_usage` or `draft_tokens` frontmatter field.
+   - **Source 3 (tertiary): task-notification** -- if task-notification totals are available (e.g. from orchestrator notes), record them; otherwise mark as `N/A`.
+   - **Divergence flag:** if any two sources diverge by >20%, flag it in §3 AND in §5 Tooling as a Red Friction finding.
+   - Compute per-agent_type totals, per-story_id totals, agent invocation counts, wall time (first to last ledger row per story), rough USD cost (apply current model rates; note the rate date).
 
-### Sprint goal — did we hit it?
-One paragraph. The goal verbatim from the sprint file, followed by the plain-English answer.
+3. **Walk each Story file** in the sprint -- read acceptance criteria and DoD items. Note which stories reached `Done`, `Escalated`, or `Parking Lot`.
 
-### Headline deliverables
-- One bullet per user-facing capability (not per story). Group stories under their business outcome.
+4. **Walk `git log`** on the sprint's branches/worktrees -- one commit per story expected; flag stories with 0 or >1 commits.
 
-### Risks that materialized
-From the sprint's risk table — which mitigations fired, which were unused, what surprised us.
+5. **Diff flashcards** -- count flashcards added during the sprint window (compare dates against sprint start); extract top themes by tag.
 
-### Cost envelope
-One line: "~$X across N agent invocations (M tokens cached, saving ~$Y vs. cold)."
-
-### What's unblocked for next sprint
-Bullet list tying this sprint's outputs to downstream dependencies.
+5b. **Flashcard audit (stale-detection pass).** For each card in `.cleargate/FLASHCARD.md` without a status marker (`[S]` or `[R]` -- see flashcard SKILL.md Rule 7), extract concrete referenced symbols from the lesson body:
+    - file paths (regex: `\S+\.(ts|md|sh|py|sql|json|yaml|toml)`)
+    - identifier candidates (CamelCase 4+ chars OR `snake_case_with_2+_underscores`)
+    - CLI flags (regex: `--[a-z][a-z0-9-]+`)
+    - env-var candidates (regex: `[A-Z][A-Z0-9_]{3,}`)
+    For each extracted symbol, `Grep` the repo (excluding `.cleargate/FLASHCARD.md` itself and sprint-runs/*). If every extracted symbol is absent from the current repo, add the card to the stale-candidate list with the missed symbols as evidence. If a card has zero extractable symbols, skip it. Do NOT modify FLASHCARD.md. Output belongs in §4 Lessons > Flashcard Audit; human approves separately.
 
----
+6. **Synthesize** the report using the v2 template structure (§§1-6 in order):
 
-## For Developers
+   §1 What Was Delivered: user-facing capabilities + internal improvements + carried over.
+   §2 Story Results + CR Change Log: one block per story with CR/UR event types from protocol §§16-17
+      (CR:bug | CR:spec-clarification | CR:scope-change | CR:approach-change; UR:review-feedback | UR:bug).
+   §3 Execution Metrics: full table including Bug-Fix Tax, Enhancement Tax, first-pass success rate,
+      and three-source token reconciliation with divergence flag.
+   §4 Lessons: new flashcards table + stale-candidate audit table (from step 5b) + supersede candidates.
+   §5 Framework Self-Assessment: five subsections (Templates/Handoffs/Skills/Process/Tooling),
+      each as a rating table (Green/Yellow/Red). If §3 divergence flag = YES, Tooling shows Red.
+   §6 Change Log: append-only table; initial row = generation timestamp.
 
-### Per-story walkthrough
-For each shipped story, one compact block:
+   Required frontmatter: sprint_id, status, generated_at, generated_by, template_version: 1.
 
-**STORY-NNN-NN: Title** · L<complexity> · <cost_usd> · <wall_time>
-- Files: `path/a.ts`, `path/b.ts`
-- Tests added: N (covering M Gherkin scenarios)
-- Kickbacks: 0 (one-shot) | 1 (reason: …) | 2 (reasons: …)
-- Deviations from plan: none | <describe>
-- Flashcards recorded: [#tag] brief
-- Commit: <sha>
+7. **Record a flashcard** on any reporting-specific friction encountered. `Skill(flashcard, "record: #reporting <lesson>")`.
 
-### Agent efficiency breakdown
-| Role | Invocations | Tokens | Cost | Tokens/story | Notes |
-|---|---|---|---|---|---|
-| Architect | | | | | |
-| Developer | | | | | |
-| QA | | | | | |
-| Reporter | | | | | — this report |
+## v2-adoption note
+This reporter spec was adopted in SPRINT-09 (STORY-013-07) as the Sprint Report v2 rollout.
+Per sprint DoD line 119 dogfood check: this note confirms the v2 template is active.
 
-### What the loop got right
-3-5 bullets — based on flashcards + kickback rate + plan-adherence rate.
+## Fallback: Write-blocked Environment (STORY-014-10)
 
-### What the loop got wrong
-3-5 bullets — blockers, repeated mistakes, plan misses, QA kickback patterns. Each bullet points at a **concrete loop improvement** (flashcard, agent-definition tweak, hook adjustment, sprint-plan template change).
+The primary path is `Write`: the Reporter writes `REPORT.md` directly to the sprint dir. If the agent's tool harness blocks `Write` (observed in both SPRINT-09 and CG_TEST SPRINT-01), use this fallback:
 
-### Flashcard audit
-Candidates for `[S]` (stale) marker — referenced symbols no longer present in the repo. Human approves the batch before markers are applied.
+1. **Return the full REPORT.md body on stdout**, wrapped between unambiguous delimiters:
 
-| Card (date · lead-tag · lesson head) | Evidence (symbols not found) | Proposed marker |
-|---|---|---|
-| 2026-02-15 · #tsup · tsup single-bundle... | `tsup.config.ts`, `--bundle` | `[S]` |
+   ```
+   ===REPORT-BEGIN===
+   # Sprint Report — <sprint-id>
+   ...
+   ===REPORT-END===
+   ```
 
-If zero candidates: state "No stale flashcards detected." If there are candidate supersede pairs (a newer card whose lesson directly contradicts an older card's advice), list them under a "Supersede candidates" sub-table with the proposed `[R] → superseded-by <short-ref>` marker for the older card.
+2. **The orchestrator is responsible for stripping those two delimiter lines** before piping.
 
-### Open follow-ups
-Things deliberately deferred, with target sprint.
+3. **The orchestrator pipes the raw body** (no delimiters) to:
 
----
+   ```bash
+   node .cleargate/scripts/close_sprint.mjs <sprint-id> --report-body-stdin < report-body.md
+   ```
 
-## Meta
+   `--report-body-stdin` **replaces** the Step-4 gate (it implies ack). The script:
+   - refuses empty stdin (`empty report body — refusing to write`)
+   - refuses a pre-existing `REPORT.md` (`delete it or skip stdin mode`)
+   - atomic-writes via tmp+rename
+   - falls through to Step 5 (sprint_status flip) + Step 6 (suggest_improvements)
 
-**Token ledger:** `.cleargate/sprint-runs/<sprint-id>/token-ledger.jsonl` (N rows)
-**Flashcards added:** N (see `.cleargate/FLASHCARD.md`)
-**Model rates used:** <date>
-**Report generated:** <timestamp> by Reporter agent
-```
+4. The fallback is additive to the primary path — `Write` remains on the `tools:` line. Do not remove it.
 
-7. **Record a flashcard** on any reporting-specific friction. `Skill(flashcard, "record: #reporting <lesson>")`.
+## Reporter Rewrite Fallback Plan (R8)
+If SPRINT-09 Reporter regresses post-swap of this reporter.md, rollback path:
+`git revert` the M2 commit range. The SPRINT-08-shaped fixture at
+`.cleargate/sprint-runs/S-09/fixtures/sprint-08-shaped/` was used to validate this
+spec before atomic swap.
 
 ## Guardrails
-- **Numbers before narrative.** Every claim in the PM section must be backed by a ledger row, a commit, or a flashcard entry — cite them.
-- **Do not fabricate cost.** If you can't find current model rates, state the rate date you used and mark cost `~$X (rates as of <date>)`.
-- **Do not summarize the sprint file.** Assume the reader already read it. Add information; don't restate.
-- **One report. One file. Do not create drafts.** If you're uncertain, emit what you have and flag the uncertainty inline.
-- **Length ceiling: 600 lines.** A longer report won't be read.
+- **Numbers before narrative.** Every claim in §1 must be backed by a ledger row, commit, or flashcard -- cite them.
+- **Do not fabricate cost.** If you cannot find current model rates, state the rate date and mark cost `~$X (rates as of <date>)`.
+- **Do not summarize the sprint file.** Assume the reader already read it. Add information; do not restate.
+- **One report. One file. Do not create drafts.** If uncertain, emit what you have and flag inline.
+- **Length ceiling: 600 lines.** A longer report will not be read.
+- **All six sections required.** §§1-6 must all be present with non-empty content. A missing section is a hard failure.
 
 ## What you are NOT
-- Not a PM — you inform decisions, you don't make them.
-- Not a Developer — you don't prescribe fixes.
-- Not a Cheerleader — if the sprint went badly, say so plainly. The loop improves from honesty.
+- Not a PM -- you inform decisions, you do not make them.
+- Not a Developer -- you do not prescribe fixes.
+- Not a Cheerleader -- if the sprint went badly, say so plainly. The loop improves from honesty.

package/dist/templates/cleargate-planning/.claude/hooks/pending-task-sentinel.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# PreToolUse hook for Task (Agent subagent dispatch).
+#
+# Purpose: when the orchestrator spawns a subagent via the Task tool, record the
+# dispatch metadata (agent_type, work_item_id, turn_index) into a sentinel file
+# under the active sprint dir. The SubagentStop hook reads the newest sentinel
+# to attribute the token-ledger row correctly.
+#
+# Why: SubagentStop fires on the ORCHESTRATOR's session with the orchestrator's
+# transcript_path. Without a sentinel, the hook can only grep the full
+# transcript and every row tags against the orchestrator — per-story cost is
+# uncomputable. The sentinel provides (a) ground-truth agent_type and
+# work_item_id, and (b) a turn_index pivot so the post-hook can compute the
+# delta instead of the cumulative sum.
+#
+# Input: JSON on stdin from Claude Code with fields:
+#   session_id, transcript_path, cwd, hook_event_name, tool_name, tool_input
+# For tool_name == "Task", tool_input has: subagent_type, description, prompt.
+#
+# Output: writes .cleargate/sprint-runs/<sprint-id>/.pending-task-<turn_index>.json
+#         with { agent_type, work_item_id, turn_index, started_at }
+#
+# Robustness: under v1 never blocks the tool call (exit 0 always). Under v2,
+# exits non-zero to block Task spawn when unprocessed flashcards exist.
+# Set SKIP_FLASHCARD_GATE=1 to bypass the flashcard gate in both modes.
+
+set -u
+
+REPO_ROOT="${ORCHESTRATOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR}}"
+LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
+mkdir -p "${LOG_DIR}"
+HOOK_LOG="${LOG_DIR}/pending-task-sentinel.log"
+ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
+
+# Read stdin once — must happen before the grouped block
+INPUT="$(cat)"
+
+# Determine active sprint (needed for flashcard gate and sentinel)
+SPRINT_ID=""
+if [[ -f "${ACTIVE_SENTINEL}" ]]; then
+  SPRINT_ID="$(tr -d '[:space:]' < "${ACTIVE_SENTINEL}")"
+fi
+[[ -z "${SPRINT_ID}" ]] && SPRINT_ID="_off-sprint"
+SPRINT_DIR="${REPO_ROOT}/.cleargate/sprint-runs/${SPRINT_ID}"
+mkdir -p "${SPRINT_DIR}"
+
+# --- Flashcard gate (STORY-014-03) ---
+# Runs BEFORE the logged block so stderr goes to real process stderr (not log),
+# allowing Claude Code to surface the message to the orchestrator.
+# Bypass: set SKIP_FLASHCARD_GATE=1 in environment.
+TOOL_NAME_EARLY="$(printf '%s' "${INPUT}" | jq -r '.tool_name // empty')"
+
+if [[ "${TOOL_NAME_EARLY}" == "Task" && "${SKIP_FLASHCARD_GATE:-0}" != "1" && "${SPRINT_ID}" != "_off-sprint" ]]; then
+  # Read execution_mode from state.json
+  EXEC_MODE="v1"
+  if [[ -f "${SPRINT_DIR}/state.json" ]]; then
+    EXEC_MODE="$(jq -r '.execution_mode // "v1"' "${SPRINT_DIR}/state.json" 2>/dev/null)"
+    [[ -z "${EXEC_MODE}" || "${EXEC_MODE}" == "null" ]] && EXEC_MODE="v1"
+  fi
+
+  # Collect flagged cards from all STORY-*-dev.md and STORY-*-qa.md in SPRINT_DIR (flat layout).
+  UNPROCESSED_CARDS=()
+  UNPROCESSED_HASHES=()
+
+  # Use ls -t (portable) to process report files; portable array accumulation (bash 3.2 safe).
+  REPORT_FILES=()
+  while IFS= read -r f; do
+    REPORT_FILES+=("$f")
+  done < <(ls -t "${SPRINT_DIR}"/STORY-*-dev.md "${SPRINT_DIR}"/STORY-*-qa.md 2>/dev/null)
+
+  for REPORT_FILE in "${REPORT_FILES[@]}"; do
+    [[ ! -f "${REPORT_FILE}" ]] && continue
+    # Parse flashcards_flagged list. Handles two formats:
+    #   YAML key (frontmatter):          Markdown section heading:
+    #   flashcards_flagged: []           ## flashcards_flagged
+    #   flashcards_flagged:
+    #   - "card text"                    - "card text"
+    #   - bare card text                 - bare card text
+    IN_BLOCK=0
+    BLOCK_TYPE=""  # "yaml" or "md"
+    while IFS= read -r line; do
+      # YAML inline empty list — no cards in this format
+      if [[ "${line}" =~ ^flashcards_flagged:[[:space:]]*\[\] ]]; then
+        break
+      fi
+      # YAML key (block form) — matches "flashcards_flagged:" or "flashcards_flagged: " with nothing after
+      if [[ "${line}" =~ ^flashcards_flagged:[[:space:]]*$ ]]; then
+        IN_BLOCK=1
+        BLOCK_TYPE="yaml"
+        continue
+      fi
+      # Markdown section heading (## flashcards_flagged or ## Flashcards_flagged)
+      if [[ "${line}" =~ ^##[[:space:]]+[Ff]lashcards_flagged ]]; then
+        IN_BLOCK=1
+        BLOCK_TYPE="md"
+        continue
+      fi
+
+      if [[ "${IN_BLOCK}" == "1" ]]; then
+        # Stop conditions differ by block type
+        if [[ "${BLOCK_TYPE}" == "yaml" ]]; then
+          # Stop at next top-level YAML key (non-indented, non-list, non-blank line)
+          if [[ "${line}" =~ ^[a-zA-Z_] ]]; then
+            break
+          fi
+        elif [[ "${BLOCK_TYPE}" == "md" ]]; then
+          # Stop at next markdown heading (any level)
+          if [[ "${line}" =~ ^# ]]; then
+            break
+          fi
+        fi
+        # Match list items: "- ..." (leading whitespace allowed)
+        if [[ "${line}" =~ ^[[:space:]]*-[[:space:]]+(.*) ]]; then
+          CARD="${BASH_REMATCH[1]}"
+          # Strip surrounding quotes (double or single)
+          CARD="${CARD#\"}"
+          CARD="${CARD%\"}"
+          CARD="${CARD#\'}"
+          CARD="${CARD%\'}"
+          [[ -z "${CARD}" ]] && continue
+          # Compute SHA-1, first 12 chars (portable: shasum -a 1 per flashcard #bash #macos)
+          HASH="$(printf '%s' "${CARD}" | shasum -a 1 | cut -c1-12)"
+          MARKER="${SPRINT_DIR}/.processed-${HASH}"
+          if [[ ! -f "${MARKER}" ]]; then
+            UNPROCESSED_CARDS+=("${CARD}")
+            UNPROCESSED_HASHES+=("${HASH}")
+          fi
+        fi
+      fi
+    done < "${REPORT_FILE}"
+  done
+
+  if [[ "${#UNPROCESSED_CARDS[@]}" -gt 0 ]]; then
+    printf '[%s] flashcard-gate: %d unprocessed card(s) found (mode=%s)\n' \
+      "$(date -u +%FT%TZ)" "${#UNPROCESSED_CARDS[@]}" "${EXEC_MODE}" >> "${HOOK_LOG}"
+    if [[ "${EXEC_MODE}" == "v2" ]]; then
+      # Block Task spawn — exit 1 with diagnostic on stderr (real stderr, not log)
+      printf 'FLASHCARD GATE BLOCKED: %d unprocessed flashcard(s) must be processed before spawning next Task.\n' \
+        "${#UNPROCESSED_CARDS[@]}" >&2
+      for i in "${!UNPROCESSED_CARDS[@]}"; do
+        CARD="${UNPROCESSED_CARDS[$i]}"
+        HASH="${UNPROCESSED_HASHES[$i]}"
+        printf '  card: %s\n' "${CARD}" >&2
+        printf '  mark processed: touch %s/.processed-%s\n' "${SPRINT_DIR}" "${HASH}" >&2
+      done
+      exit 1
+    else
+      # v1: advisory warning only, continue to sentinel write
+      printf 'FLASHCARD GATE WARNING (v1 advisory): %d unprocessed flashcard(s).\n' \
+        "${#UNPROCESSED_CARDS[@]}" >&2
+      for i in "${!UNPROCESSED_CARDS[@]}"; do
+        CARD="${UNPROCESSED_CARDS[$i]}"
+        HASH="${UNPROCESSED_HASHES[$i]}"
+        printf '  card: %s\n' "${CARD}" >&2
+        printf '  mark processed: touch %s/.processed-%s\n' "${SPRINT_DIR}" "${HASH}" >&2
+      done
+    fi
+  fi
+fi
+# --- End flashcard gate ---
+
+{
+  TOOL_NAME="$(printf '%s' "${INPUT}" | jq -r '.tool_name // empty')"
+  if [[ "${TOOL_NAME}" != "Task" ]]; then
+    # Not a subagent dispatch — no sentinel needed.
+    exit 0
+  fi
+
+  TRANSCRIPT_PATH="$(printf '%s' "${INPUT}" | jq -r '.transcript_path // empty')"
+  AGENT_TYPE="$(printf '%s' "${INPUT}" | jq -r '.tool_input.subagent_type // "unknown"')"
+  PROMPT="$(printf '%s' "${INPUT}" | jq -r '.tool_input.prompt // empty')"
+
+  # Extract work_item_id from prompt — by convention first line is STORY=NNN-NN
+  # or an inline PROPOSAL-NNN / EPIC-NNN / CR-NNN / BUG-NNN reference.
+  WORK_ITEM_ID="$(printf '%s' "${PROMPT}" | grep -oE '(STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?' | head -1 | sed 's/=/-/g')"
+  [[ -z "${WORK_ITEM_ID}" ]] && WORK_ITEM_ID=""
+
+  # Compute turn_index: count of assistant turns in the orchestrator transcript so far.
+  TURN_INDEX=0
+  if [[ -n "${TRANSCRIPT_PATH}" && -f "${TRANSCRIPT_PATH}" ]]; then
+    TURN_INDEX="$(jq -cs '[.[] | select(.type == "assistant" and .message.usage)] | length' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+    [[ -z "${TURN_INDEX}" || "${TURN_INDEX}" == "null" ]] && TURN_INDEX=0
+  fi
+
+  STARTED_AT="$(date -u +%FT%TZ)"
+  SENTINEL_FILE="${SPRINT_DIR}/.pending-task-${TURN_INDEX}.json"
+
+  # Write the sentinel atomically (tmp + mv).
+  TMP="${SENTINEL_FILE}.tmp.$$"
+  jq -cn \
+    --arg agent "${AGENT_TYPE}" \
+    --arg work_item "${WORK_ITEM_ID}" \
+    --argjson idx "${TURN_INDEX}" \
+    --arg started "${STARTED_AT}" \
+    '{agent_type: $agent, work_item_id: $work_item, turn_index: $idx, started_at: $started}' \
+    > "${TMP}" 2>/dev/null \
+    && mv "${TMP}" "${SENTINEL_FILE}" \
+    && printf '[%s] wrote sentinel sprint=%s agent=%s work_item=%s turn=%s\n' \
+        "${STARTED_AT}" "${SPRINT_ID}" "${AGENT_TYPE}" "${WORK_ITEM_ID}" "${TURN_INDEX}" \
+        >> "${HOOK_LOG}" \
+    || printf '[%s] failed to write sentinel %s\n' "${STARTED_AT}" "${SENTINEL_FILE}" >> "${HOOK_LOG}"
+} 2>> "${HOOK_LOG}"
+
+exit 0

package/dist/templates/cleargate-planning/.claude/hooks/pre-commit-surface-gate.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# pre-commit-surface-gate.sh
+set -euo pipefail
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+SCRIPT="${REPO_ROOT}/.cleargate/scripts/file_surface_diff.sh"
+if [[ ! -f "${SCRIPT}" ]]; then
+  echo "[surface-gate] WARNING: file_surface_diff.sh not found — skipping" >&2
+  exit 0
+fi
+exec bash "${SCRIPT}" "$@"