cleargate 0.14.0 → 0.15.1

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

@@ -1,274 +0,0 @@
----
-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>/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).
-
-## Autonomy Contract
-
-During sprint execution (sprint_status: "Active"), you MUST NOT call `AskUserQuestion`
-or any other user-facing prompt EXCEPT under the five true-blocker cases enumerated in
-`.cleargate/knowledge/cleargate-protocol.md` § Sprint Execution Autonomy. When in doubt,
-write a blockers report (`STORY-NNN-NN-reporter-blockers.md`) and return BLOCKED.
-Do not interpret silence as permission to proceed on ambiguous scope.
-
-At sprint close, read `.cleargate/hook-log/autonomy-warnings.log` and produce an
-`## Autonomy Warnings` section in the sprint report (one line per warning entry, or
-"None recorded." if the file is absent or empty). The autonomy-warnings log captures
-any `AskUserQuestion` calls that fired during sprint execution — surface them for
-retrospective review even if the hook allowed them through in soft mode.
-
-## Preflight
-
-Before any other action, Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md`. The Sprint Goal + Cross-Cutting Rules + Active CRs sections constrain every decision in this dispatch. If the file is absent, surface to orchestrator (do not infer).
-
-## 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). Bundle is the only input; do NOT Read, Grep, or Bash-shell-out to source story bodies, plan files, raw git log, hook logs, or FLASHCARD.md. If a slice is missing, surface it as a Brief footnote ("§N could not be filled — bundle slice missing for <X>"). Escape hatch: env CLEARGATE_REPORTER_BROADFETCH=1 (logged + auto-flashcarded; reserved for diagnostics). |
-| **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>/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 seven sections (§§1-7) with no empty or missing section headers.
-
-After writing the report, push it to ClearGate so it appears alongside the sprint's work items:
-
-```
-cleargate push .cleargate/sprint-runs/<sprint-id>/SPRINT-<#>_REPORT.md
-```
-
-The report pushes under the id `<SPRINT-NN>-REPORT` — distinct from the `SPRINT-NN` work-item, so it never overwrites it. Reports need no `approved: true` field (the explicit `cleargate push` of the report is the approval, and missing/legacy frontmatter is tolerated). If the push fails because the project is pre-member, note it in the close handoff and skip — never block report generation on the push.
-
-## 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 and only. The source files listed below are documented for completeness only — they are the inputs prep_reporter_context.mjs slices into the bundle. Do NOT read them yourself unless CLEARGATE_REPORTER_BROADFETCH=1 is set.
-- 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")` -- grep for `#reporting` and `#hooks` tags before starting.
-
-2. **Three-source token reconciliation.** Parse all three token sources and compute the two-line split (CR-035):
-   - **Source 1 (session-totals — Sprint total):** read `.cleargate/sprint-runs/<id>/.session-totals.json`. Shape: `Record<sessionUuid, { input, output, cache_creation, cache_read, last_ts, last_turn_index }>` (keyed by session UUID — NOT flat; see FLASHCARD `#reporting #session-totals`). Sum `input + output + cache_creation + cache_read` across `Object.values(...)` to get the Sprint total. Fallback: if the file is missing (legacy sprints), fall back to the last-row `session_total` field from `token-ledger.jsonl` AND emit a `**Note:** .session-totals.json absent — falling back to last-row session_total (legacy mode).` line. **If `.reporter-context.md` was built by `prep_reporter_context.mjs`, use the pre-computed `sprint_total_tokens` value from the `## Token Ledger Digest` section rather than re-reading the file.**
-   - **Source 2 (ledger-deltas-by-agent — Sprint work):** parse `token-ledger.jsonl`, filter rows where `agent_type != 'reporter'`, sum `delta.input + delta.output + delta.cache_read + delta.cache_creation` across the filtered rows (CR-018 v2 schema). This gives the "Sprint work (dev+qa+architect)" number. Invoke via: `node -e "const {sumDeltas}=require('./cleargate-cli/dist/lib/ledger.js'); const fs=require('fs'); const rows=fs.readFileSync('<ledger>','utf-8').trim().split('\n').filter(Boolean).map(l=>JSON.parse(l)).filter(r=>r.agent_type!=='reporter'); const r=sumDeltas(rows); console.log(JSON.stringify(r))"`. Rows lacking `story_id` are attributed to the `unassigned` bucket -- 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). **If `.reporter-context.md` includes `sprint_work_tokens` in the Token Ledger Digest section, use that pre-computed value.**
-   - **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 3 (Reporter analysis pass):** the Reporter's own SubagentStop has not fired at report-write time. Report as: `TBD — see token-ledger.jsonl post-dispatch`. Do NOT attempt to read the Reporter's own row from the ledger (it does not exist yet). If `.reporter-context.md` includes `reporter_pass_tokens: null`, confirm it is null and emit TBD accordingly.
-   - **Format §3 as the two-line split:**
-     ```
-     Token cost (sprint work, dev+qa+architect): 10,974,922
-     Token cost (Reporter analysis pass):        TBD — see token-ledger.jsonl post-dispatch
-     Token cost (sprint total):                  23,845,652
-     ```
-   - **Divergence flag:** if Sprint-work and Sprint-total diverge by >20% AND a Reporter-pass estimate is unavailable (TBD), flag in §3 AND in §5 Tooling as a Yellow Friction finding (not Red — the TBD gap is expected).
-   - **Source 4 (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 5 (tertiary: task-notification):** if task-notification totals are available (e.g. from orchestrator notes), record them; otherwise mark as `N/A`.
-   - 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).
-
-3. **Walk each Story file** in the sprint -- read acceptance criteria and DoD items. Note which stories reached `Done`, `Escalated`, or `Parking Lot`.
-
-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 (compare dates against sprint start); extract top themes by tag.
-
-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-7 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 §§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.
-   §4 Observe: signal log of observations from this sprint — patterns noticed, anomalies flagged,
-      and flashcard archival candidates (cards that appear superseded, resolved, or duplicate).
-      For each archival candidate, record: card date+text, reason (superseded/resolved/duplicate),
-      and the superseding card or fix. Human approves the archival batch at Gate 4; approved cards
-      are moved to `.cleargate/FLASHCARD-archive.md` (cold-archive greppable reference) and marked
-      `[S]`/`[R]` in the live FLASHCARD.md. Cards are archived only on human approval — never auto-evicted.
-   §5 Lessons: new flashcards table + stale-candidate audit table (from step 5b) + supersede candidates.
-      (Re-numbered from §4 in template_version 2.)
-   §6 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.
-      (Re-numbered from §5 in template_version 2.)
-   §7 Change Log: append-only table; initial row = generation timestamp.
-      (Re-numbered from §6 in template_version 2.)
-
-   Required frontmatter: sprint_id, status, generated_at, generated_by, template_version: 2.
-
-7. **Aggregate script incidents (CR-046).** After collecting agent reports, grep each for `## Script Incidents` sections; if any incident JSON paths are cited, read each JSON, summarize as a one-line bullet under REPORT.md §Risks Materialized. Pattern: `<ts> · <agent_type> · <command> exited <exit_code> · <one-line stderr summary>`. Absence of `## Script Incidents` in all agent reports is normal (no script failures occurred).
-
-8. **Record a flashcard** on any reporting-specific friction encountered. `Skill(flashcard, "record: #reporting <lesson>")`.
-
-## Script Invocation
-
-Any bash/node script you invoke MUST go through the wrapper:
-`bash .cleargate/scripts/run_script.sh <cmd> [args...]`. The wrapper captures stdout/stderr/exit-code into `.cleargate/sprint-runs/<id>/.script-incidents/<ts>-<hash>.json` on failure. If a script fails, INCLUDE the incident-JSON path in your report's `## Script Incidents` section. Direct invocation (without wrapper) is forbidden under v2.
-
-## 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.
-
-## Token Budget Discipline (CR-036)
-
-The Reporter dispatch is budgeted at **200,000 tokens (soft warn)** and **500,000 tokens (hard advisory + auto-flashcard)**. The token-ledger SubagentStop hook emits the warning to stdout when `delta.input + delta.output + delta.cache_creation + delta.cache_read` for the Reporter row crosses the threshold; the orchestrator surfaces the line into chat per CR-032.
-
-If you encounter the soft warn at 200k while writing the report:
-1. Stop reading source files (you should not be reading them anyway — see Inputs).
-2. Check that `.reporter-context.md` was loaded from `.cleargate/sprint-runs/<id>/`.
-3. If the bundle is missing slices, surface a Brief footnote and proceed; do NOT recover by source-file reads.
-
-Hard advisory at 500k auto-records a flashcard `Reporter dispatch exceeded 500k tokens — investigate prompt or bundle`. The dispatch is NOT killed; the warning is informational. The Architect or human triages on next sprint.
-
-## Fresh Session Dispatch (CR-036)
-
-The orchestrator MUST dispatch the Reporter in a fresh context — do not inherit dev+qa cumulative conversation turns. Reporter dispatch runs in the orchestrator's session_id; the SubagentStop hook attributes tokens to the work_item via the dispatch marker (`.dispatch-<session-id>.json`). The orchestrator falls back to a fresh `claude` shell child via `bash .cleargate/scripts/write_dispatch.sh <sprint-id> reporter` (which already spawns cleanly).
-
-The Reporter starts cold each time. The bundle + template are the only context.
-
-## Fallback: Write-blocked Environment (STORY-014-10)
-
-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 SPRINT-<#>_REPORT.md body on stdout**, wrapped between unambiguous delimiters:
-
-   ```
-   ===REPORT-BEGIN===
-   # Sprint Report — <sprint-id>
-   ...
-   ===REPORT-END===
-   ```
-
-2. **The orchestrator is responsible for stripping those two delimiter lines** before piping.
-
-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
-   ```
-
-   `--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 file (`delete it or skip stdin mode`)
-   - atomic-writes via tmp+rename
-   - falls through to Step 5 (sprint_status flip) + Step 6 (suggest_improvements)
-
-4. The fallback is additive to the primary path — `Write` remains on the `tools:` line. Do not remove it.
-
-## 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.
-
-## Sprint Report v2.1 — Lane + Hotfix Metrics
-
-When `state.json` has `schema_version >= 2` AND at least one story shipped with `lane: fast`,
-the Reporter MUST populate the following additional rows and sections. When the activation
-conditions are not met (v1 state, or all stories `lane: standard`), these rows and sections
-may be omitted or left with placeholder values.
-
-### §3 Execution Metrics — Six New Rows
-
-The Reporter computes and writes these six rows in §3 (after the existing rows):
-
-| Row label | Computation | Source |
-|---|---|---|
-| `Fast-Track Ratio` | `count(stories where lane=fast at sprint close) / total stories × 100` | `state.json` `.stories[*].lane` |
-| `Fast-Track Demotion Rate` | `count(stories with LD event) / count(stories where lane=fast was ever assigned) × 100` | `state.json` `.stories[*].lane_demoted_at` + sprint markdown §4 LD rows |
-| `Hotfix Count (sprint window)` | Count of rows in `wiki/topics/hotfix-ledger.md` where `merged_at` is between sprint `started_at` and `closed_at` | `wiki/topics/hotfix-ledger.md` filtered by sprint window |
-| `Hotfix-to-Story Ratio` | `Hotfix Count / total in-sprint stories` | Derived from above |
-| `Hotfix Cap Breaches` | Count of rolling-7-day windows during the sprint window that had ≥ 3 hotfixes | `wiki/topics/hotfix-ledger.md` `merged_at` column |
-| `LD events` | Count of LD event rows in sprint markdown §4 events list | Sprint plan file `## §4 Events Log` or equivalent |
-
-**Sources detail:**
-
-- `state.json` lane fields per `.cleargate/scripts/state.schema.json` StoryEntry: `lane`, `lane_assigned_by`, `lane_demoted_at`, `lane_demotion_reason`.
-- Sprint markdown §4 LD events written by `pre_gate_runner.sh` `append_ld_event` (STORY-022-04). Each LD row records the story, timestamp, and demotion reason.
-- `wiki/topics/hotfix-ledger.md` — filter rows by `merged_at` between sprint `started_at` and `closed_at`. If the ledger is absent, record `Hotfix Count = 0` and a note explaining the fallback.
-- For historical sprints with `schema_version: 1` (no lane fields), default all lane metrics to `0` or `N/A` and note the fallback in §5 Tooling.
-
-### §5 Process — Lane Audit table
-
-One row per story that was ever assigned `lane: fast` during the sprint (whether it shipped fast
-or was auto-demoted). The Reporter computes the first four columns from `git log` + `state.json`;
-the last two columns are left blank for human fill-in at sprint close.
-
-Template row format (per `sprint_report.md` lines 167-172):
-
-```
-| Story | Files touched | LOC | Demoted? | In retrospect, was fast correct? (y/n) | Notes |
-```
-
-- **Story**: story ID (e.g. `STORY-022-08`).
-- **Files touched**: count via `git diff --name-only <base>..<story-sha>`.
-- **LOC**: `git diff --stat <base>..<story-sha>` insertions+deletions total.
-- **Demoted?**: `y` if `lane_demoted_at` is non-null in `state.json`; `n` otherwise.
-- **In retrospect, was fast correct?**: blank — human fills at close.
-- **Notes**: blank — human fills at close.
-
-### §5 Process — Hotfix Audit table
-
-One row per hotfix merged within the sprint window. Read from `wiki/topics/hotfix-ledger.md`
-filtered by `merged_at` between sprint `started_at` and `closed_at`. Last two columns blank.
-
-Template row format (per `sprint_report.md` lines 174-179):
-
-```
-| Hotfix ID | Originating signal | Files touched | LOC | Resolved-by SHA | Could this have been a sprint story? (y/n) | If y — why was it missed at planning? |
-```
-
-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 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,
-flag it as `trend: INCREASING` and recommend a retrospective action in §5 Tooling.
-
-For historical v1-schema sprints with no lane data, record `0 hotfixes (v1 — no ledger data)`.
-
-Template location: `sprint_report.md` lines 181-188. Leave the placeholder text intact for
-sprints with no hotfixes in the window.
-
-## Guardrails
-- **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 seven sections required.** §§1-7 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 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

@@ -1,209 +0,0 @@
-#!/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: exits non-zero to block Task spawn when unprocessed flashcards exist.
-# Set SKIP_FLASHCARD_GATE=1 to bypass the flashcard gate entirely.
-# Set CLEARGATE_ADVISORY=1 to downgrade the block to a warning (exit 0).
-
-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
-  # 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\n' \
-      "$(date -u +%FT%TZ)" "${#UNPROCESSED_CARDS[@]}" >> "${HOOK_LOG}"
-    if [[ "${CLEARGATE_ADVISORY:-0}" == "1" ]]; then
-      # Advisory mode: warning only, continue to sentinel write
-      printf 'FLASHCARD GATE WARNING: %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
-    else
-      # Default: 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
-    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)"
-  # STORY-033-02: key sentinel by RUN_ID when present (parallel-wave attribution).
-  # When RUN_ID is set, two concurrent Task dispatches sharing one session + one TURN_INDEX
-  # each get a distinct .pending-task-${RUN_ID}.json file and neither overwrites the other.
-  # When RUN_ID is absent (serial path), fall back to the BUG-029 uniquify form
-  # .pending-task-${TURN_INDEX}-$$-${RANDOM}.json so the serial baseline is preserved.
-  if [[ -n "${RUN_ID:-}" ]]; then
-    SENTINEL_FILE="${SPRINT_DIR}/.pending-task-${RUN_ID}.json"
-  else
-    # BUG-029 fix: uniquify when no RUN_ID (serial path).
-    # Old: .pending-task-${TURN_INDEX}.json  ← second call overwrites first.
-    # New: .pending-task-${TURN_INDEX}-$$-${RANDOM}.json  ← each call gets its own file.
-    SENTINEL_FILE="${SPRINT_DIR}/.pending-task-${TURN_INDEX}-$$-${RANDOM}.json"
-  fi
-
-  # 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

@@ -1,33 +0,0 @@
-#!/usr/bin/env bash
-# pre-commit-surface-gate.sh
-set -euo pipefail
-REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-
-# CR-043: Red-test immutability check (Option A — runs BEFORE file-surface delegation)
-if [[ "${SKIP_RED_GATE:-}" != "1" ]]; then
-  CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
-  if [[ "${CURRENT_BRANCH}" == story/STORY-* || "${CURRENT_BRANCH}" == story/CR-* || "${CURRENT_BRANCH}" == story/BUG-* ]]; then
-    # Look for staged modifications to *.red.test.ts or *.red.node.test.ts files
-    STAGED_RED="$(git diff --cached --name-only --diff-filter=M 2>/dev/null | grep -E '\.red\.(node\.)?test\.ts$' || true)"
-    if [[ -n "${STAGED_RED}" ]]; then
-      # Check whether a qa-red commit exists on this branch (subject starts with "qa-red(")
-      if git log --pretty=%s HEAD 2>/dev/null | grep -qE '^qa-red\('; then
-        echo "[red-gate] REJECT: Developer commits cannot modify *.red.test.ts or *.red.node.test.ts files post-QA-Red." >&2
-        echo "[red-gate] Modified files: ${STAGED_RED}" >&2
-        echo "[red-gate] Bypass: SKIP_RED_GATE=1 (log bypass in sprint §4 Execution Log)." >&2
-        exit 1
-      fi
-    fi
-  fi
-else
-  echo "[red-gate] BYPASS: SKIP_RED_GATE=1 set — skipping Red-test immutability check. Log bypass in sprint §4." >&2
-fi
-
-if ! npm run check:no-vitest -s --prefix mcp 2>/dev/null || ! npm run check:no-vitest -s --prefix cleargate-cli 2>/dev/null || ! npm run check:no-vitest -s --prefix admin 2>/dev/null; then exit 1; fi
-
-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}" "$@"

package/dist/templates/cleargate-planning/.claude/hooks/pre-commit-test-ratchet.sh

@@ -1,58 +0,0 @@
-#!/usr/bin/env bash
-# pre-commit-test-ratchet.sh — STORY-014-04: Pre-existing Test-Failure Ratchet
-#
-# Invoked by .claude/hooks/pre-commit.sh dispatcher (STORY-014-01).
-# Runs test_ratchet.mjs in 'check' mode and blocks commit on regression.
-#
-# Bypass (discouraged): SKIP_TEST_RATCHET=1
-# Timeout: 120s (enough for current cleargate-cli suite ~45s)
-#
-# macOS compatibility: 'timeout' is GNU coreutils; on macOS use 'gtimeout' (brew coreutils).
-# Fallback: if neither is available, run without timeout and print a warning.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="${CLEARGATE_REPO_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"
-
-# ---------------------------------------------------------------------------
-# Bypass
-# ---------------------------------------------------------------------------
-if [[ "${SKIP_TEST_RATCHET:-0}" == "1" ]]; then
-  echo "test-ratchet: SKIP_TEST_RATCHET=1 — bypassing test ratchet check (discouraged)" >&2
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# Resolve timeout binary (GNU on Linux; gtimeout on macOS via brew)
-# ---------------------------------------------------------------------------
-TIMEOUT_CMD=""
-if command -v timeout &>/dev/null; then
-  TIMEOUT_CMD="timeout 120"
-elif command -v gtimeout &>/dev/null; then
-  TIMEOUT_CMD="gtimeout 120"
-else
-  echo "test-ratchet: WARNING — 'timeout' not found; running without 120s guard" >&2
-fi
-
-# ---------------------------------------------------------------------------
-# Run ratchet
-# ---------------------------------------------------------------------------
-RATCHET_SCRIPT="${REPO_ROOT}/.cleargate/scripts/test_ratchet.mjs"
-
-if [[ ! -f "${RATCHET_SCRIPT}" ]]; then
-  echo "test-ratchet: ERROR — ratchet script not found at ${RATCHET_SCRIPT}" >&2
-  exit 1
-fi
-
-export CLEARGATE_REPO_ROOT="${REPO_ROOT}"
-
-${TIMEOUT_CMD} node "${RATCHET_SCRIPT}" check
-STATUS=$?
-
-if [[ ${STATUS} -eq 124 ]]; then
-  echo "test-ratchet: ERROR — ratchet timed out after 120s; commit blocked" >&2
-  exit 1
-fi
-
-exit ${STATUS}

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

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-# pre-commit.sh — Dispatcher: chains all pre-commit-*.sh hooks in lexical order.
-#
-# Install: ln -sf ../../.claude/hooks/pre-commit.sh .git/hooks/pre-commit
-#
-# Each pre-commit-*.sh is expected to exit 0 on success or non-zero to block.
-# The dispatcher exits on the first non-zero exit code.
-
-set -euo pipefail
-
-HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-for hook in "${HOOK_DIR}"/pre-commit-*.sh; do
-  [[ -f "${hook}" ]] || continue
-  [[ -x "${hook}" ]] || continue
-  bash "${hook}" || exit $?
-done
-
-exit 0