cleargate 0.8.2 → 0.10.0

package/dist/templates/cleargate-planning/.claude/agents/cleargate-wiki-lint.md

@@ -167,10 +167,11 @@ raw_path: ".cleargate/delivery/archive/STORY-042-01_name.md"
 last_ingest: "2026-04-19T10:00:00Z"
 last_ingest_commit: "a1b2c3d4e5f6..."
 repo: "planning"
+last_contradict_sha: ""  # optional — populated by ingest Phase 4 (§10.10)
 ---
 ```
 
-Exactly nine fields. Lint rejects pages with extra fields (drift from §10.4) or missing fields.
+Nine required fields plus one optional (`last_contradict_sha`). Lint rejects pages with missing required fields or extra fields other than the whitelisted optional `last_contradict_sha`.
 
 ## §10.3 Exclusion List (inline)
 
@@ -197,6 +198,10 @@ Plus two checks mandated by Sprint-04 risk table (not in §10.8 enumerated list)
 - Missing-ingest — raw file mtime newer than wiki page mtime (Sprint-04 risk row 7).
 - Excluded-path-ingested — a wiki page exists for a raw file under an §10.3 excluded directory.
 
+Optional field allowance (§10.10):
+
+- `last_contradict_sha` (optional) — populated by ingest Phase 4. Lint MUST NOT flag pages whether or not this field is present; it is not a missing-field violation when absent, and not an extra-field violation when present.
+
 ## §10.7 Idempotency Rule (inline)
 
 Re-ingesting a file is a no-op when **both** of the following are true:

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

@@ -43,11 +43,38 @@ TYPECHECK: pass | fail
 TESTS: X passed, Y failed
 FILES_CHANGED: <list>
 NOTES: <one paragraph max — deviations from plan, flashcards recorded>
+r_coverage:
+  - { r_id: "R1", covered: true, deferred: false, clarified: false }
+  - { r_id: "R2", covered: false, deferred: true, clarified: false }
+plan_deviations:
+  - { what: "<short label>", why: "<one-sentence reason>", orchestrator_confirmed: true }
+adjacent_files:
+  - "<absolute or repo-relative path the dev believes may regress>"
 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.
+**Casing contract (parser-bound):** STATUS / COMMIT / TYPECHECK / TESTS / FILES_CHANGED / NOTES are uppercase keys; r_coverage / plan_deviations / adjacent_files / flashcards_flagged are lowercase YAML-shaped lists. The QA Context Pack regex (`prep_qa_context.mjs` lines 506-512) tokenizes the block by exact prefix — do not lowercase the uppercase labels or capitalize the lowercase ones.
+
+**Three optional structured-handoff fields** (introduced by CR-024 S2; the QA Context Pack ingests them as `dev_handoff` per `prep_qa_context.mjs` lines 64-77):
+
+- `r_coverage` — one entry per requirement R1..RN drawn from the story's Gherkin and `## 3. Implementation Guide`. Set exactly one of `covered` (test asserts the requirement), `deferred` (out of this story's scope, flagged for follow-up), or `clarified` (orchestrator confirmation amended the requirement). Default `[]` when the story has zero numbered Rs (rare; flag in NOTES if so).
+- `plan_deviations` — one entry per deviation from the Architect's milestone plan blueprint. Each must include `orchestrator_confirmed: true` (deviation was discussed and agreed) or `false` (dev's unilateral call — QA flags as risk). Default `[]`.
+- `adjacent_files` — repo-relative paths the dev's gut-check thinks may regress from this change but were not directly edited. Default `[]`. The `prep_qa_context.mjs` script independently computes its own adjacent-file set (lines 322-368) from `git diff --name-only` neighborhoods; the dev's list is additive subjective context the script cannot derive.
+
+**Backwards-compat:** Three optional structured-handoff fields. Omitting them yields a `legacy`-format pack (per `prep_qa_context.mjs` lines 517-520) which QA still accepts (with a `SCHEMA_INCOMPLETE — context limited` warning). Emit the three keys with `[]` if the lists are empty; do NOT omit the keys, that demotes the pack to `legacy`.
+
+`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 §4.
+
+## Inner-loop test runner
+
+For inner-loop iteration during a Story, prefer **`node:test` + `node:assert/strict`** when writing **new** test files for any TypeScript package targeting Node 22+. Run them via `node --test --import tsx <file>`. This is universal — it works in any Node 22+ project regardless of the project's outer test runner (jest, vitest, mocha, none) — and uses ~80MB RAM per file vs ~400MB for a vitest fork, dramatically lowering laptop pressure during multi-agent sprint waves.
+
+**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks (e.g., `vi.mock(...)`, `jest.mock(...)`). Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()` from `node:test`.
+
+**Existing tests stay on the project's existing runner.** Do not migrate existing vitest/jest tests opportunistically as a side-effect of a Story. If your Story modifies an existing test, keep it on the original runner. Batch migrations belong in their own dedicated CR.
+
+**Full-suite verification at commit-time.** Use the project's standard test command (`npm test`, etc.) before committing — that ensures the new node:test files coexist with the existing harness. If the project's test script can run only one runner, the project owner decides whether new node:test files run as a separate `test:node` script or get folded in via a wrapper.
 
 ## 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`.
@@ -69,7 +96,7 @@ These rules apply under `execution_mode: v2`. Under v1 they are informational.
 
 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.
+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 §1.3 for full rationale.
 
 ## Lane-Aware Execution
 

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

@@ -7,6 +7,55 @@ model: sonnet
 
 You are the **QA** agent for ClearGate sprint execution. Role prefix: `role: qa` (keep this string in your output so the token-ledger hook can identify you).
 
+## Capability Surface
+
+| Surface              | Resource                                                                          |
+| -------------------- | --------------------------------------------------------------------------------- |
+| **Scripts**          | `.cleargate/scripts/prep_qa_context.mjs` (M2-frozen, `schema_version: 1`)         |
+| **Skills**           | `Skill(flashcard, "check")` — first action on spawn                               |
+| **Hooks observing**  | SubagentStop (token-ledger attribution)                                           |
+| **Default input**    | `.cleargate/sprint-runs/<sprint>/.qa-context-<story-id>.md` (read FIRST; spec/plan/diff fall back to source files only when pack is incomplete) |
+| **Output**           | stdout text matching the `## Output shape` schema below                           |
+| **Lane awareness**   | Dispatches `fast` / `standard` / `runtime` per `lane.value` in pack JSON          |
+
+## Pack-First Ingest
+
+The QA Context Pack (`.qa-context-<story-id>.md`) is THE primary input. Read it first; do not improvise context derivation from worktree state.
+
+- **First action on spawn (after flashcard check):** `Read(.cleargate/sprint-runs/<sprint>/.qa-context-<story-id>.md)`. Locate sprint dir via `.cleargate/sprint-runs/.active`.
+- **Pack structure (verbatim from `prep_qa_context.mjs` `bundleParts` array, lines 849-864):** 8 markdown sections in fixed order — Worktree + Commit / Spec Sources / Baseline / Adjacent Files / Cross-Story Map / Flashcard Slice / Lane / Dev Handoff. Embedded JSON code block contains `schema_version: 1` plus structured fields (lane, dev_handoff.format, baseline.failures). Prefer JSON for structured fields, prose for human-readable summaries.
+- **Pack-absent fallback:** if `.qa-context-<story-id>.md` does not exist (orchestrator skipped prep, worktree path mismatch), emit `QA: FAIL — pack missing at <expected-path>; orchestrator must run prep_qa_context.mjs before QA dispatch` and stop. Do NOT improvise context derivation — that's the failure mode CR-024 was filed to eliminate.
+- **Pack-incomplete handling:** if the JSON block is present but `dev_handoff.format === "legacy"` or `"absent"`, proceed with QA but downgrade verdict confidence — emit a `WARN: dev handoff incomplete — context limited (SCHEMA_INCOMPLETE)` line in the output `VERDICT` paragraph. This is NOT an automatic FAIL.
+
+## Lane-Aware Playbook
+
+Dispatch verification depth by reading `lane.value` from the pack's JSON block (or the prose `## Lane` section's `**Value:**` line).
+
+- **`fast` lane** (doc-only / mirror-edit / sub-50-LOC stories):
+  - Mirror-parity diff (`diff -q` between live and canonical files in the dev's `files_changed`).
+  - Grep checklist for required strings (heading anchors, schema field names).
+  - DoD §2.2 audit (cross-check the story's Gherkin → diff one-to-one).
+  - Spec-vs-impl drift table (one row per requirement).
+  - **Skip** typecheck and targeted vitest UNLESS `pack.adjacent.adjacent_test_files` is non-empty AND any of those files are under `cleargate-cli/`, `mcp/`, `cleargate-cli/test/`, or any path with extension `.ts` / `.test.ts` / `.test.sh`.
+
+- **`standard` lane** (current default — most stories):
+  - Everything in `fast`, PLUS:
+  - `cleargate gate typecheck` re-run (capture exit code).
+  - `cleargate gate test` re-run, scoped to touched-file neighborhoods (`pack.adjacent.touched_files` + `pack.adjacent.adjacent_test_files`).
+  - Adversarial probe (1-2 boundary cases beyond Gherkin: empty input, non-ASCII, oversized payload).
+  - Cross-story regression sweep against `pack.cross_story_map[].shared_files` if non-empty.
+
+- **`runtime` lane** (NEW — CLI / integration / runtime-surface stories):
+  - Everything in `standard`, PLUS:
+  - **Full test suite** re-run (not just touched-file scope) — `cleargate gate test` against the full package.
+  - Coverage check: every Gherkin scenario has a passing test (zero MISSING entries).
+  - **exit-code matrix:** invoke each new/modified command with `--help`, the happy path, and at least one explicit error path; assert exit codes match documented values.
+  - **Integration smoke:** if the story changes a script under `.cleargate/scripts/`, run the script's bash test harness from a `mktemp -d` fixture (mirrors test_prep_qa_context.sh pattern at `.cleargate/scripts/test/`).
+
+- **Forward-compat clause:** If the pack's `lane.value` is any string other than `fast` / `standard` / `runtime`, treat it as `standard`. The state.json schema does not yet know about `runtime` (SPRINT-20 work); QA must not error on lane mismatch. Cite `prep_qa_context.mjs` line 491 + line 498 — the script defaults to `standard` when state.json is absent or the field is missing; a future state.json with an unknown lane value (e.g., SPRINT-20 introduces `experimental`) must not break QA.
+
+- **Lane-source hint:** if `pack.lane.source === "not-yet-runtime-aware"` (heuristic emitted when story is `standard` but touches `cleargate-cli/src/commands/`, per `prep_qa_context.mjs` lines 486-490), apply `standard` checks BUT add the `runtime` exit-code matrix as a soft check. Surface any deviations as `WARN`, not `FAIL`.
+
 ## Your one job
 Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or reject with `QA: FAIL <reason>`. Do not commit. Do not edit.
 
@@ -46,7 +95,7 @@ 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.
+`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 §4.
 
 ## Guardrails
 - **Never approve on Developer's word.** Re-run everything yourself.

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

@@ -1,16 +1,37 @@
 ---
 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 using the Sprint Report v2 template. 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>/SPRINT-<#>_REPORT.md. Does not modify any other artifact.
 tools: Read, Grep, Glob, Bash, Write
 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).
 
+## Capability Surface
+
+| Capability type | Items |
+|---|---|
+| **Scripts** | `prep_reporter_context.mjs` (read curated bundle), `count_tokens.mjs` (token totals + anomalies), git log per sprint commit, FLASHCARD date-window slicer |
+| **Skills** | `flashcard` (Skill tool — read past lessons) |
+| **Hooks observing** | `SubagentStop` → `token-ledger.sh` (attributes Reporter tokens via dispatch marker; pre-sprint) |
+| **Default input** | `.cleargate/sprint-runs/<id>/.reporter-context.md` (built by `prep_reporter_context.mjs` at close pipeline Step 3.5). Fall back to source files only when the bundle is incomplete or missing. |
+| **Output** | `.cleargate/sprint-runs/<id>/SPRINT-<#>_REPORT.md` (primary). Post-close pipeline (close_sprint.mjs Steps 6.5/6.6/6.7) also appends sections to `improvement-suggestions.md` — sprint-trends stub, skill-candidate scan, flashcard-cleanup scan. Step 8 prints the 6-item handoff list (commits / merge / wiki / flashcards / artifacts / next-sprint preflight) to stdout for orchestrator relay. |
+
+## Post-Output Brief
+
+After Writing the report, render a Brief in chat:
+
+> 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)?
+
+This Brief replaces today's "re-run with --assume-ack" prompt as the Gate 4 trigger. The orchestrator surfaces this Brief verbatim to the human and halts.
+
 ## Your one job
-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.
+Produce one file: `.cleargate/sprint-runs/<sprint-id>/SPRINT-<#>_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
+- **Default input bundle:** `.cleargate/sprint-runs/<sprint-id>/.reporter-context.md` (built by `prep_reporter_context.mjs` at close pipeline Step 3.5). Read this first. Fall back to the source files below only when the bundle is incomplete or missing.
 - 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`)
@@ -23,7 +44,8 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. Use the Sprint
 1. **Read flashcards first.** `Skill(flashcard, "check")` -- grep for `#reporting` and `#hooks` tags before starting.
 
 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 1 (primary): token-ledger.jsonl** -- parse JSONL, sum `delta.input + delta.output + delta.cache_read + delta.cache_creation` per row (CR-018 v2 schema). Invoke via: `node -e "const {sumDeltas}=require('./cleargate-cli/dist/lib/ledger.js'); const rows=require('fs').readFileSync('<ledger>','utf-8').trim().split('\n').filter(Boolean).map(l=>JSON.parse(l)); const r=sumDeltas(rows); console.log(JSON.stringify(r))"`. Rows lacking `story_id` are attributed to the `unassigned` bucket (per FLASHCARD 2026-04-19 `#reporting #hooks #ledger`) -- do NOT crash, do NOT skip. `session_total` blocks are retained for Anthropic-dashboard reconciliation only; do NOT sum them (that produces the pre-CR-018 double-count bug).
+   - **Format fallback (pre-0.9.0 ledger):** when `sumDeltas` returns `format: 'pre-0.9.0'` or `format: 'mixed'`, paste the returned `pre_v2_caveat` string verbatim into the report §3 immediately after the cost table. Do not suppress or paraphrase it. The caveat is: `**Ledger format note:** This sprint's token-ledger.jsonl uses pre-0.9.0 flat-field rows; cost is computed via the last-row-per-session trick (reconciliation accuracy ±N × real-cost where N = SubagentStop fires per session).` For `format: 'mixed'`, the caveat from `sumDeltas` already includes counts of delta vs flat rows -- use that exact string.
    - **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.
@@ -45,7 +67,7 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/REPORT.md`. Use the Sprint
 6. **Synthesize** the report using the v2 template structure (§§1-6 in order):
 
    §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
+   §2 Story Results + CR Change Log: one block per story with CR/UR event types from protocol §§2-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.
@@ -64,9 +86,9 @@ Per sprint DoD line 119 dogfood check: this note confirms the v2 template is act
 
 ## Fallback: Write-blocked Environment (STORY-014-10)
 
-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:
+The primary path is `Write`: the Reporter writes `SPRINT-<#>_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:
 
-1. **Return the full REPORT.md body on stdout**, wrapped between unambiguous delimiters:
+1. **Return the full SPRINT-<#>_REPORT.md body on stdout**, wrapped between unambiguous delimiters:
 
    ```
    ===REPORT-BEGIN===
@@ -85,7 +107,7 @@ The primary path is `Write`: the Reporter writes `REPORT.md` directly to the spr
 
    `--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`)
+   - refuses a pre-existing report file (`delete it or skip stdin mode`)
    - atomic-writes via tmp+rename
    - falls through to Step 5 (sprint_status flip) + Step 6 (suggest_improvements)
 
@@ -159,8 +181,8 @@ If zero hotfixes in window, write a single row: `| (none) | — | — | — |
 ### §5 Process — Hotfix Trend narrative
 
 A one-paragraph narrative summarising the rolling 4-sprint hotfix count and a
-monotonic-increase flag. The Reporter reads the last 4 sprint `REPORT.md` files
-(at `.cleargate/sprint-runs/<id>/REPORT.md`) OR walks `wiki/topics/hotfix-ledger.md`
+monotonic-increase flag. The Reporter reads the last 4 sprint reports
+(at `.cleargate/sprint-runs/<id>/SPRINT-<#>_REPORT.md` for SPRINT-18+, or legacy `REPORT.md` for SPRINT-01..17) OR walks `wiki/topics/hotfix-ledger.md`
 by `sprint_id` field to gather per-sprint counts.
 
 Monotonic-increase flag: if the count increased (or stayed ≥ 1) for 3+ consecutive sprints,

package/dist/templates/cleargate-planning/.claude/hooks/pre-tool-use-task.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# pre-tool-use-task.sh — PreToolUse:Task hook.
+#
+# CR-026: Auto-write a dispatch marker on every Task() spawn so the
+# SubagentStop hook (token-ledger.sh) can attribute tokens to the correct
+# work item and agent without relying on transcript-grep heuristics.
+#
+# This hook addresses BUG-024 §3.1 Defect 3: manual write_dispatch.sh calls
+# were unreliable (~5 calls vs ~19 spawns in SPRINT-18). The hook fires
+# automatically on every Task() spawn inside the orchestrator session.
+#
+# 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>/.dispatch-<ts>-<pid>-<rand>.json
+#   with { work_item_id, agent_type, spawned_at, session_id, writer }
+#   Uniquified filename prevents collision under parallel Task() spawns.
+#   SubagentStop hook uses newest-file lookup (ls -t) to consume it.
+#
+# Log: .cleargate/hook-log/pre-tool-use-task.log
+#
+# Exit code: 0 always. Never blocks a Task spawn.
+#
+# Banner-immunity: reads tool_input.prompt directly from the JSON payload —
+# no transcript involvement, so the SessionStart blocked-items banner cannot
+# poison this path (contrast with token-ledger.sh's transcript-grep fallback).
+
+set -u
+
+# ─── Resolve repo root (matches token-ledger.sh:59 + write_dispatch.sh:30) ───
+REPO_ROOT="${ORCHESTRATOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR}}"
+LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
+mkdir -p "${LOG_DIR}"
+HOOK_LOG="${LOG_DIR}/pre-tool-use-task.log"
+ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
+
+TS="$(date -u +%FT%TZ)"
+
+# Read stdin once
+INPUT="$(cat)"
+
+# ─── Extract tool_name to confirm this is a Task spawn ────────────────────────
+TOOL_NAME="$(printf '%s' "${INPUT}" | jq -r '.tool_name // empty' 2>/dev/null)"
+if [[ "${TOOL_NAME}" != "Task" ]]; then
+  # Not a Task spawn — nothing to do; exit silently.
+  exit 0
+fi
+
+# ─── Resolve active sprint via sentinel ───────────────────────────────────────
+if [[ ! -f "${ACTIVE_SENTINEL}" ]]; then
+  printf '[%s] no .active sentinel — dispatch marker skipped (off-sprint)\n' "${TS}" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+SPRINT_ID="$(tr -d '[:space:]' < "${ACTIVE_SENTINEL}")"
+if [[ -z "${SPRINT_ID}" ]]; then
+  printf '[%s] .active sentinel is empty — dispatch marker skipped\n' "${TS}" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+SPRINT_DIR="${REPO_ROOT}/.cleargate/sprint-runs/${SPRINT_ID}"
+mkdir -p "${SPRINT_DIR}"
+
+# ─── Extract subagent_type ────────────────────────────────────────────────────
+AGENT_TYPE="$(printf '%s' "${INPUT}" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null)"
+ALLOW_LIST="architect developer qa reporter cleargate-wiki-contradict"
+if [[ -z "${AGENT_TYPE}" ]] || ! printf '%s\n' ${ALLOW_LIST} | grep -qxF "${AGENT_TYPE}"; then
+  printf '[%s] no marker: agent_type absent or not in allow-list (%s)\n' "${TS}" "${AGENT_TYPE:-<empty>}" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+# ─── Extract work_item_id from first 5 lines of tool_input.prompt ─────────────
+# Regex: (STORY=?NNN-NN | BUG-NNN | EPIC-NNN | CR-NNN | PROPOSAL-NNN | HOTFIX-NNN)
+PROMPT_HEAD="$(printf '%s' "${INPUT}" | jq -r '.tool_input.prompt // ""' 2>/dev/null | head -5)"
+if [[ -z "${PROMPT_HEAD}" ]]; then
+  printf '[%s] no marker: prompt empty or unreadable\n' "${TS}" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+WORK_ITEM_RAW="$(printf '%s' "${PROMPT_HEAD}" \
+  | grep -oE '(STORY=?[0-9]{3}-[0-9]{2}|BUG-[0-9]+|EPIC-[0-9]+|CR-[0-9]+|PROPOSAL-[0-9]+|HOTFIX-[0-9]+)' \
+  | head -1)"
+
+if [[ -z "${WORK_ITEM_RAW}" ]]; then
+  printf '[%s] no marker: regex miss (agent=%s prompt_head=%s)\n' \
+    "${TS}" "${AGENT_TYPE}" "$(printf '%s' "${PROMPT_HEAD}" | head -1 | cut -c1-60)" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+# Normalize STORY=NNN-NN → STORY-NNN-NN
+WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/\-/')"
+
+# ─── Resolve orchestrator session ID ─────────────────────────────────────────
+# Path-B: uniquified filename makes session ID irrelevant for lookup.
+# We embed it in the JSON body for forensic value only.
+# GOTCHA-5: CLAUDE_SESSION_ID may be unset on nested spawns; fall back to stdin payload.
+SESSION_ID="${CLAUDE_SESSION_ID:-}"
+if [[ -z "${SESSION_ID}" ]]; then
+  SESSION_ID="$(printf '%s' "${INPUT}" | jq -r '.session_id // empty' 2>/dev/null)"
+fi
+[[ -z "${SESSION_ID}" ]] && SESSION_ID="unknown"
+
+# ─── Resolve cleargate version ────────────────────────────────────────────────
+PKG_JSON="${REPO_ROOT}/cleargate-cli/package.json"
+CG_VERSION="unknown"
+if [[ -f "${PKG_JSON}" ]]; then
+  CG_VERSION="$(jq -r '.version // "unknown"' "${PKG_JSON}" 2>/dev/null || echo "unknown")"
+fi
+
+# ─── Write dispatch file atomically (mktemp + mv, matches write_dispatch.sh:110-112) ──
+# Uniquified filename: .dispatch-<ts-epoch>-<pid>-<random>.json
+# Prevents collision under parallel Task() spawns; newest-file lookup at SubagentStop.
+SPAWNED_AT="${TS}"
+DISPATCH_FILENAME=".dispatch-$(date -u +%s)-$$-${RANDOM}.json"
+DISPATCH_TARGET="${SPRINT_DIR}/${DISPATCH_FILENAME}"
+
+DISPATCH_JSON="$(jq -cn \
+  --arg work_item_id "${WORK_ITEM_ID}" \
+  --arg agent_type "${AGENT_TYPE}" \
+  --arg spawned_at "${SPAWNED_AT}" \
+  --arg session_id "${SESSION_ID}" \
+  --arg writer "pre-tool-use-task.sh@cleargate-${CG_VERSION}" \
+  '{
+    work_item_id: $work_item_id,
+    agent_type: $agent_type,
+    spawned_at: $spawned_at,
+    session_id: $session_id,
+    writer: $writer
+  }' 2>/dev/null)"
+
+if [[ -z "${DISPATCH_JSON}" ]]; then
+  printf '[%s] error: jq failed to build dispatch JSON\n' "${TS}" >> "${HOOK_LOG}"
+  exit 0
+fi
+
+TMP="$(mktemp "${SPRINT_DIR}/.dispatch-tmp-XXXXXX" 2>/dev/null)"
+if [[ -z "${TMP}" ]]; then
+  printf '[%s] error: mktemp failed for dispatch file\n' "${TS}" >> "${HOOK_LOG}"
+  exit 0
+fi
+printf '%s\n' "${DISPATCH_JSON}" > "${TMP}"
+mv "${TMP}" "${DISPATCH_TARGET}"
+
+printf '[%s] wrote dispatch: sprint=%s work_item=%s agent=%s file=%s\n' \
+  "${TS}" "${SPRINT_ID}" "${WORK_ITEM_ID}" "${AGENT_TYPE}" "${DISPATCH_FILENAME}" >> "${HOOK_LOG}"
+
+exit 0

package/dist/templates/cleargate-planning/.claude/hooks/session-start.sh

@@ -17,6 +17,12 @@ fi
 
 "${CG[@]}" doctor --session-start || true
 
+# --- Sprint-active skill auto-load directive (STORY-026-01) ---
+ACTIVE_FILE="${REPO_ROOT}/.cleargate/sprint-runs/.active"
+if [ -s "${ACTIVE_FILE}" ] && [ -n "$(tr -d '[:space:]' < "${ACTIVE_FILE}")" ]; then
+  printf '→ Active sprint detected. Load skill: sprint-execution\n'
+fi
+
 # ── §14.9 SessionStart sync nudge (STORY-010-08) ─────────────────────────────
 # Daily-throttled: probe remote for updates at most once per 24h.
 # Never auto-pulls or auto-pushes. Exits 0 regardless of outcome.