cleargate 0.10.0 → 0.11.0

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

@@ -7,6 +7,10 @@ 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).
 
+## 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
 
 | Surface              | Resource                                                                          |
@@ -18,6 +22,38 @@ You are the **QA** agent for ClearGate sprint execution. Role prefix: `role: qa`
 | **Output**           | stdout text matching the `## Output shape` schema below                           |
 | **Lane awareness**   | Dispatches `fast` / `standard` / `runtime` per `lane.value` in pack JSON          |
 
+## Mode Dispatch — Red vs Verify
+
+The orchestrator dispatch text drives mode selection. Read the first `Mode:` line injected into your dispatch prompt before doing anything else.
+
+**Mode: RED** (QA-Red dispatch — SKILL.md §C.3)
+
+Dispatch prompt contains: `Mode: RED — write failing tests against §4 acceptance, no implementation Read access.`
+
+In RED mode you:
+1. Read the story's §4 acceptance Gherkin (and ONLY the story file — no implementation source files).
+2. Write failing test files named `*.red.node.test.ts` covering each acceptance scenario.
+3. Confirm each test FAILS against the clean baseline (no implementation yet).
+4. Return the `QA-RED:` output shape (see §C.3 in SKILL.md).
+5. **Forbidden:** Read, edit, or reference any implementation file (`.ts` source, not tests).
+6. **Wiring soundness:** Tests must be wiring-sound for Architect TPV approval (SKILL.md §C.3.5). TPV checks: imports resolve, constructor signatures match, mocked methods exist, after-hooks present, file naming `*.red.node.test.ts`. Wiring gap → orchestrator routes back to QA-Red (increments `arch_bounces`, NOT `qa_bounces`).
+
+Output shape for RED mode:
+```
+QA-RED: WRITTEN | BLOCKED
+RED_TESTS: <list of *.red.node.test.ts files written>
+BASELINE_FAIL: <count of failing scenarios>
+flashcards_flagged: [ ... ]
+```
+
+On `QA-RED: BLOCKED`: emit a `Spec-Gap:` sentence describing the ambiguity that prevents writing tests.
+
+**Mode: VERIFY** (QA-Verify dispatch — SKILL.md §C.5)
+
+Dispatch prompt contains: `Mode: VERIFY — read-only acceptance trace.`
+
+In VERIFY mode you follow the standard QA workflow below (pack-first ingest, lane-aware playbook, full output shape). This is the default mode if no `Mode:` line is injected.
+
 ## 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.
@@ -104,6 +140,11 @@ flashcards_flagged:
 - **Flaky tests count as FAIL.** Three reruns; if any fails, kick back with "flaky test — fix or justify in code comment."
 - **Max kickback round is round 2.** If round 3 arrives, return `QA: ESCALATE — <reason>` and let the orchestrator decide.
 
+## 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.
+
 ## What you are NOT
 - Not the Developer — do not propose fixes in detail, just identify gaps.
 - Not the Architect — do not question the story's design, only whether the code meets it.

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

@@ -7,6 +7,10 @@ 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).
 
+## 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 |
@@ -14,7 +18,7 @@ You are the **Reporter** agent for ClearGate sprint retrospectives. Role prefix:
 | **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. |
+| **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
@@ -31,7 +35,7 @@ This Brief replaces today's "re-run with --assume-ack" prompt as the Gate 4 trig
 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.
+- **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`)
@@ -43,12 +47,20 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/SPRINT-<#>_REPORT.md`. Use
 
 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 `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).
+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 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.
+   - **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`.
@@ -78,12 +90,36 @@ Produce one file: `.cleargate/sprint-runs/<sprint-id>/SPRINT-<#>_REPORT.md`. Use
 
    Required frontmatter: sprint_id, status, generated_at, generated_by, template_version: 1.
 
-7. **Record a flashcard** on any reporting-specific friction encountered. `Skill(flashcard, "record: #reporting <lesson>")`.
+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:

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

@@ -2,6 +2,27 @@
 # 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
+
 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

package/dist/templates/cleargate-planning/.claude/hooks/stamp-and-gate.sh

@@ -24,8 +24,19 @@ TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 # Ordered chain — stamp MUST precede gate (gate may read draft_tokens)
 "${CG[@]}" stamp-tokens "$FILE" >>"$LOG" 2>&1
 SR1=$?
-"${CG[@]}" gate check "$FILE" >>"$LOG" 2>&1
+# CR-032: capture gate check stdout to tmpfile so we can re-emit ⚠️ lines to
+# hook stdout (→ Claude Code system-reminder). gate.ts emits ❌ lines to
+# stdout (gate.ts:259), not stderr; the tmpfile captures them separately.
+GATE_OUT=$(mktemp)
+"${CG[@]}" gate check "$FILE" >"$GATE_OUT" 2>>"$LOG"
 SR2=$?
+cat "$GATE_OUT" >>"$LOG"
+if [ "$SR2" -ne 0 ]; then
+  WORK_ITEM_ID=$(grep -m1 -oE '(EPIC|STORY|CR|BUG|HOTFIX|PROPOSAL|INITIATIVE|SPRINT)-[0-9]+(-[0-9]+)?' "$FILE" | head -1)
+  : "${WORK_ITEM_ID:=<work-item>}"
+  grep '^❌' "$GATE_OUT" 2>/dev/null | sed -E "s/^❌ /⚠️ gate failed: ${WORK_ITEM_ID} — /"
+fi
+rm -f "$GATE_OUT"
 "${CG[@]}" wiki ingest "$FILE" >>"$LOG" 2>&1
 SR3=$?
 echo "[$TS] stamp=$SR1 gate=$SR2 ingest=$SR3 file=$FILE" >>"$LOG"

package/dist/templates/cleargate-planning/.claude/hooks/token-ledger.sh

@@ -224,7 +224,7 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
     [[ -z "${AGENT_TYPE}" || "${AGENT_TYPE}" == "null" ]] && AGENT_TYPE="unknown"
 
     if [[ "${AGENT_TYPE}" == "unknown" ]]; then
-      for role in architect developer qa reporter cleargate-wiki-contradict; do
+      for role in architect developer qa reporter devops cleargate-wiki-contradict; do
         if grep -qiE "\\b${role}\\b agent|role: ${role}|you are the ${role}" "${TRANSCRIPT_PATH}" 2>/dev/null; then
           AGENT_TYPE="${role}"
           break
@@ -401,6 +401,26 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
     "${SENTINEL_TURN_INDEX}" \
     >> "${HOOK_LOG}"
 
+  # --- CR-036: Reporter token-budget warning (chat-injection per CR-032 pattern) ---
+  if [[ "${AGENT_TYPE}" == "reporter" ]]; then
+    REPORTER_TOTAL=$(( DELTA_IN + DELTA_OUT + DELTA_CC + DELTA_CR ))
+    REPORTER_BUDGET_SOFT=200000
+    REPORTER_BUDGET_HARD=500000
+    if [[ "${REPORTER_TOTAL}" -gt "${REPORTER_BUDGET_HARD}" ]]; then
+      printf '\n⚠️ Reporter token budget exceeded: %s > %s (HARD advisory)\n' \
+        "${REPORTER_TOTAL}" "${REPORTER_BUDGET_HARD}"
+      # Auto-flashcard via cleargate CLI (best-effort; never block)
+      if command -v cleargate >/dev/null 2>&1; then
+        cleargate flashcard record \
+          "Reporter dispatch exceeded 500k tokens — investigate prompt or bundle" \
+          >/dev/null 2>&1 || true
+      fi
+    elif [[ "${REPORTER_TOTAL}" -gt "${REPORTER_BUDGET_SOFT}" ]]; then
+      printf '\n⚠️ Reporter token budget exceeded: %s > %s (soft warn)\n' \
+        "${REPORTER_TOTAL}" "${REPORTER_BUDGET_SOFT}"
+    fi
+  fi
+
   # --- delete processed sentinel ---
   if [[ -n "${PROCESSED_FILE}" && -f "${PROCESSED_FILE}" ]]; then
     rm -f "${PROCESSED_FILE}"