cleargate 0.2.0 → 0.3.0

package/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/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/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,107 +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.
-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.
 
----
+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).
 
-## For Product Management
+3. **Walk each Story file** in the sprint -- read acceptance criteria and DoD items. Note which stories reached `Done`, `Escalated`, or `Parking Lot`.
 
-### Sprint goal — did we hit it?
-One paragraph. The goal verbatim from the sprint file, followed by the plain-English answer.
+4. **Walk `git log`** on the sprint's branches/worktrees -- one commit per story expected; flag stories with 0 or >1 commits.
 
-### Headline deliverables
-- One bullet per user-facing capability (not per story). Group stories under their business outcome.
+5. **Diff flashcards** -- count flashcards added during the sprint window (compare dates against sprint start); extract top themes by tag.
 
-### Risks that materialized
-From the sprint's risk table — which mitigations fired, which were unused, what surprised us.
+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.
 
-### Cost envelope
-One line: "~$X across N agent invocations (M tokens cached, saving ~$Y vs. cold)."
+6. **Synthesize** the report using the v2 template structure (§§1-6 in order):
 
-### What's unblocked for next sprint
-Bullet list tying this sprint's outputs to downstream dependencies.
+   §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.
 
----
+   Required frontmatter: sprint_id, status, generated_at, generated_by, template_version: 1.
 
-## For Developers
+7. **Record a flashcard** on any reporting-specific friction encountered. `Skill(flashcard, "record: #reporting <lesson>")`.
 
-### Per-story walkthrough
-For each shipped story, one compact block:
+## 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.
 
-**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>
+## Fallback: Write-blocked Environment (STORY-014-10)
 
-### Agent efficiency breakdown
-| Role | Invocations | Tokens | Cost | Tokens/story | Notes |
-|---|---|---|---|---|---|
-| Architect | | | | | |
-| Developer | | | | | |
-| QA | | | | | |
-| Reporter | | | | | — this report |
+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:
 
-### What the loop got right
-3-5 bullets — based on flashcards + kickback rate + plan-adherence rate.
+1. **Return the full REPORT.md body on stdout**, wrapped between unambiguous delimiters:
 
-### 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).
+   ```
+   ===REPORT-BEGIN===
+   # Sprint Report — <sprint-id>
+   ...
+   ===REPORT-END===
+   ```
 
-### Open follow-ups
-Things deliberately deferred, with target sprint.
+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
+   ```
 
-## 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/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/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}" "$@"

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

@@ -0,0 +1,58 @@
+#!/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/templates/cleargate-planning/.claude/hooks/pre-commit.sh

@@ -0,0 +1,19 @@
+#!/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

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

@@ -2,3 +2,54 @@
 set -u
 REPO_ROOT="${CLAUDE_PROJECT_DIR}"
 node "${REPO_ROOT}/cleargate-cli/dist/cli.js" doctor --session-start 2>/dev/null || true
+
+# ── §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.
+MARKER="${REPO_ROOT}/.cleargate/.sync-marker.json"
+NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+NOW_EPOCH=$(date +%s)
+
+if [ ! -f "${MARKER}" ]; then
+  # First run — write marker with current timestamp and skip MCP call (24h grace).
+  mkdir -p "$(dirname "${MARKER}")"
+  printf '{"last_check":"%s"}' "${NOW_ISO}" > "${MARKER}"
+else
+  # Parse last_check epoch from marker using node (portable, avoids jq dep)
+  LAST_CHECK_ISO=$(node -e "try{const m=JSON.parse(require('fs').readFileSync('${MARKER}','utf8'));process.stdout.write(m.last_check||'1970-01-01T00:00:00Z')}catch{process.stdout.write('1970-01-01T00:00:00Z')}" 2>/dev/null || echo "1970-01-01T00:00:00Z")
+  LAST_EPOCH=$(node -e "process.stdout.write(String(Math.floor(new Date('${LAST_CHECK_ISO}').getTime()/1000)))" 2>/dev/null || echo "0")
+  ELAPSED=$(( NOW_EPOCH - LAST_EPOCH ))
+
+  if [ "${ELAPSED}" -ge 86400 ]; then
+    # ≥24h since last check — run probe (3s timeout, R7 mitigation)
+    RESULT_FILE=$(mktemp)
+    # Cross-platform 3-second timeout: prefer `timeout` (Linux); fall back to
+    # background-process kill (macOS where GNU coreutils may be absent).
+    if command -v timeout > /dev/null 2>&1; then
+      timeout 3 node "${REPO_ROOT}/cleargate-cli/dist/cli.js" sync --check > "${RESULT_FILE}" 2>/dev/null || true
+    else
+      node "${REPO_ROOT}/cleargate-cli/dist/cli.js" sync --check > "${RESULT_FILE}" 2>/dev/null &
+      _PROBE_PID=$!
+      (sleep 3 && kill "${_PROBE_PID}" 2>/dev/null) &
+      _KILL_PID=$!
+      wait "${_PROBE_PID}" 2>/dev/null || true
+      kill "${_KILL_PID}" 2>/dev/null || true
+      wait "${_KILL_PID}" 2>/dev/null || true
+    fi
+    UPDATES=$(node -e "
+try {
+  var data = require('fs').readFileSync(process.argv[1], 'utf8').trim();
+  var obj = JSON.parse(data);
+  process.stdout.write(String(obj.updates || 0));
+} catch(e) {
+  process.stdout.write('0');
+}
+" "${RESULT_FILE}" 2>/dev/null || echo "0")
+    rm -f "${RESULT_FILE}"
+    if [ "${UPDATES}" -gt 0 ] 2>/dev/null; then
+      printf '📡 ClearGate: %s remote updates since yesterday — run `cleargate sync` to reconcile.\n' "${UPDATES}"
+    fi
+    # Marker is updated by sync --check itself; no re-write needed here.
+  fi
+fi
+exit 0