cleargate 0.10.0 → 0.11.1

package/dist/templates/cleargate-planning/.claude/skills/sprint-execution/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: sprint-execution
 description: |
-  Use to orchestrate the four-agent sprint loop end-to-end — Architect → Developer →
-  QA → Reporter — across one ClearGate sprint. Activates from sprint kickoff
+  Use to orchestrate the five-dispatch sprint loop end-to-end — Architect → QA-Red →
+  Developer → QA-Verify → Reporter — across one ClearGate sprint. Activates from sprint kickoff
   (preflight + cut sprint branch + state init) through per-story execution
   (worktree → dev → QA → flashcard gate → merge) into walkthrough and Gate-4 close.
   Triggers: SessionStart banner mentioning an active sprint; explicit user phrases
@@ -40,7 +40,7 @@ Five touchpoints where the goal is the tiebreaker:
 
 1. **Kickoff (§A.5).** Surface the sprint goal verbatim in chat before any Architect dispatch. State it as the explicit acceptance condition for the sprint.
 2. **Architect dispatch (§B).** Pass the sprint goal in the dispatch prompt. The milestone plan should reference how each story advances the goal, not only what files it changes.
-3. **Mid-sprint CR triage (§C.9).** When classifying `CR:scope-change`, evaluate goal alignment before quarantining. If the new requirement is critical to the goal, escalate to the human with "this may need to land THIS sprint, not the next."
+3. **Mid-sprint CR triage (§C.10 rubric → §C.11 routing).** When classifying `CR:scope-change`, evaluate goal alignment before quarantining. If the new requirement is critical to the goal, escalate to the human with "this may need to land THIS sprint, not the next."
 4. **Escalation (§8).** When `qa_bounces ≥ 3`, `arch_bounces ≥ 3`, or 3 circuit-breaker hits flip a story to `Escalated`, frame the human-decision question through the goal lens: "Drop this story → goal still met? Re-approach → goal still met by sprint end?"
 5. **Walkthrough + Reporter brief (§D, §E.2).** Walkthrough invitation leads with the goal, not the feature checklist. Reporter brief MUST include a goal-achievement verdict — `met / partial / missed` — as a first-class signal in the close-gate Brief.
 
@@ -60,8 +60,11 @@ It is pure framing: surface deviations from the goal as first-class events, not
 | `architect` | opus | (a) Sprint Design Review pre-confirm, (b) per-milestone plan | `sprint-runs/<id>/plans/M<N>.md` (per milestone); markdown block §2 (design review) |
 | `developer` | sonnet | One per story, inside its worktree | One commit `feat(<epic>): STORY-NNN-NN <desc>` + `STORY-NNN-NN-dev.md` report |
 | `qa` | sonnet | After Developer reports `STATUS=done` | `STORY-NNN-NN-qa.md` report (no code edits) |
+| `devops` | sonnet | Per-story, after QA-Verify + Architect post-flight | One merge commit (no-ff) + `STORY-NNN-NN-devops.md` report |
 | `reporter` | sonnet | Once at sprint close, after all stories merged + walkthrough done | `sprint-runs/<id>/SPRINT-<#>_REPORT.md` |
 
+**Registration constraint:** The Claude Code agent registry caches at session start. If an agent `.md` file under `.claude/agents/` was added or modified after the current session began, `Agent(subagent_type=<name>)` will return "Agent type '<name>' not found" even though the file exists. Fix: restart the Claude Code session. Verify `devops` reachable at sprint preflight (§A.1 check 6). If unavailable mid-sprint, use the §C.7 DevOps Escape Hatch.
+
 ### Wall-clock budgets
 
 Each agent dispatch has a target duration. Note the start time before each `Agent` spawn; after the call returns, compare elapsed against the budget. Ran-long stories get flagged in sprint §4 Execution Log even on success.
@@ -71,6 +74,7 @@ Each agent dispatch has a target duration. Note the start time before each `Agen
 | `architect` (per milestone) | ≤ 10 min | Plan-only output; long runs usually mean too many stories in the milestone |
 | `developer` (per story) | ≤ 30 min | Includes typecheck + tests in the worktree; long runs near the circuit-breaker threshold |
 | `qa` (per story) | ≤ 15 min | Read + re-run gates; should not edit code |
+| `devops` (per story) | ≤ 5 min | Mechanical work only — merge, teardown, state; long runs indicate git/npm issue |
 | `reporter` (per sprint) | ≤ 20 min | Single file write; long runs mean ledger reconciliation issues |
 
 If a Task call has been pending for **>2× the budget** with no visible progress, surface it to the human and offer to interrupt. There is no automatic stall detection — the parent session blocks on `Agent` calls and cannot poll mid-run. The human's interrupt is the only reliable kill path until ambient watcher infra exists.
@@ -84,7 +88,7 @@ bash .cleargate/scripts/write_dispatch.sh <work_item_id> <agent_type>
 ```
 
 - `<work_item_id>`: e.g. `STORY-020-02`, `CR-016`, `BUG-021`. For the Reporter at sprint close use the sprint ID (e.g. `SPRINT-19`).
-- `<agent_type>`: exact string — `developer | architect | qa | reporter | cleargate-wiki-contradict`.
+- `<agent_type>`: exact string — `developer | architect | qa | reporter | devops | cleargate-wiki-contradict`.
 
 If you forget the marker, ledger attribution falls back to transcript-grep heuristics (unreliable). The hook deletes the file after consumption — write fresh per dispatch.
 
@@ -113,13 +117,14 @@ Run this sequence exactly once, when the human says "start sprint NN" or equival
 cleargate sprint preflight <sprint-id>
 ```
 
-Five checks, all must pass:
+Six checks, all must pass:
 
 1. Previous sprint `sprint_status: "Completed"` in `state.json`.
 2. No leftover worktrees — `git worktree list` must not contain `.worktrees/STORY-*`.
 3. Sprint branch ref free — `git show-ref refs/heads/sprint/S-NN` returns nothing.
 4. `main` clean — `git status --porcelain` empty.
 5. Per-item readiness gates pass — every work-item ID in §1 Consolidated Deliverables has fresh `cached_gate_result.pass: true` (or terminal status). Under `execution_mode: v2` a failing item hard-blocks; under `v1` it warns. Failure punch-list names each item + its failing criteria.
+6. **Verify `devops` subagent reachable** — attempt `Agent(subagent_type=devops, prompt: "echo preflight-check")` immediately after session start. If it returns "Agent type 'devops' not found", halt and ask the human to restart the Claude Code session; do NOT proceed under assumption the escape hatch will cover every merge. This check is manual (not enforced by `cleargate sprint preflight`); document result in sprint §4 Execution Log.
 
 On failure, surface the punch list verbatim and halt. Per-item resolution:
 
@@ -128,6 +133,7 @@ On failure, surface the punch list verbatim and halt. Per-item resolution:
 - Branch ref exists → investigate; force-deletion only with explicit human approval.
 - Dirty main → human commits/stashes/discards. **Never `git reset --hard` or stash without explicit human approval.**
 - Per-item gate fail → run `cleargate gate check <file> -v` for the named item; fix the failing criterion (e.g., populate `context_source`, resolve TBDs); re-run preflight.
+- Devops unreachable → restart Claude Code session; re-run all 6 preflight checks.
 
 ### A.2 Cut sprint branch
 
@@ -145,6 +151,8 @@ node .cleargate/scripts/init_sprint.mjs SPRINT-NN
 
 This writes `.cleargate/sprint-runs/SPRINT-NN/state.json` and flips `.cleargate/sprint-runs/.active` to `SPRINT-NN`. Without `state.json` the lane router, dispatch hook, and close pipeline all fail.
 
+`init_sprint.mjs` also writes `<sprintDir>/sprint-context.md` from `.cleargate/templates/sprint_context.md`, populated with `sprint_id` + goal (extracted from sprint plan §0 `- **Sprint Goal:** …` bullet, or placeholder if absent) + active CR list. Every Dev/QA/Architect/DevOps dispatch reads this file as preflight (see §B + §C contracts + agent prompts `## Preflight`).
+
 ### A.4 Architect Sprint Design Review (v2 only)
 
 Mandatory under `execution_mode: v2`; optional but encouraged under `v1`. Spawn the Architect with all candidate stories' §3 Implementation Guides + ADRs + flashcards + sprint plan path:
@@ -177,13 +185,15 @@ Then `Agent(subagent_type=architect, ...)` with the milestone story IDs and inst
 
 **Skip per-milestone Architect for `lane: fast` stories** — they dispatch to Developer without a plan, per the lane contract (see `.claude/agents/architect.md` Lane Classification).
 
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action (Sprint Goal + Cross-Cutting Rules + Active CRs sections constrain every decision).
+
 > 🎯 **Goal check.** Pass the sprint goal verbatim in the Architect's dispatch prompt. The plan should explicitly tie each story to the goal under "Per-story blueprint" — e.g. *"STORY-NNN-NN advances goal by <one sentence>"*. Plans that don't reference the goal go back to the Architect with a re-dispatch.
 
 ---
 
 ## 5. Phase C — Per-Story Execution Loop
 
-Run this loop **per story**, in the order the milestone plan declares (parallel waves vs sequential chains). Each iteration: Worktree → Developer → QA → (Architect pass for `lane: standard` v2 only) → Merge → Flashcard Gate.
+Run this loop **per story**, in the order the milestone plan declares (parallel waves vs sequential chains). Each iteration: Worktree → **QA-Red** → **TPV (Test Pattern Validation, Architect-only)** → Developer → QA-Verify → (Architect pass for `lane: standard` v2 only) → Merge → Flashcard Gate.
 
 > **Naming note.** State-machine values (`Bouncing`, `Ready to Bounce`), `state.json` counter fields (`qa_bounces`, `arch_bounces`), and script names (`validate_bounce_readiness.mjs`) retain the legacy "bounce" term because they are code-bound. The narrative in this skill uses "execution loop", "story cycle", and "rework" to describe the same mechanics.
 
@@ -212,14 +222,72 @@ git worktree list
 
 **Do not run `git worktree add` inside `mcp/`.** It is a nested git repo. If the story touches `mcp/`, the Developer edits `mcp/` from inside `.worktrees/STORY-NNN-NN/mcp/...` — visible as a subdirectory of the outer worktree. (`cleargate-enforcement.md` §1.3.)
 
-### C.3 Spawn Developer
+### C.3 Spawn QA-Red (standard lane only — fast lane skips this step)
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN qa
+```
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the QA-Red dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+Then spawn with `subagent_type=qa`. Dispatch prompt MUST inject:
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+> `Mode: RED — write failing tests against §4 acceptance, no implementation Read access. Tests must fail with "not yet implemented" errors against the clean baseline. File-naming: *.red.node.test.ts (immutable post-Red). Forbidden: editing implementation files.`
+
+QA-Red returns:
+
+```
+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`: surface Spec-Gap to human; do not proceed to §C.4 until resolved.
+
+On `QA-RED: WRITTEN`: orchestrator commits the Red tests on the story branch with subject `qa-red(STORY-NNN-NN): write failing tests`, then proceeds to §C.3.5 TPV Gate.
+
+**Fast lane skip:** if `state.json.stories[<id>].lane === "fast"`, skip this entire step AND §C.3.5 and proceed directly to §C.4 Spawn Developer.
+
+### C.3.5 TPV Gate (Architect-only — standard lane, v2 only)
+
+**Skip if:** `state.json.stories[<id>].lane === 'fast'` OR `execution_mode: v1`.
+
+After QA-Red commits Red tests, spawn the Architect in `Mode: TPV` to perform wiring-only validation before Dev dispatch. TPV does NOT evaluate test logic correctness — it verifies wiring so Dev does not waste a full dispatch on a mis-wired test harness.
+
+```bash
+bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN architect
+```
+
+Dispatch prompt MUST inject:
+
+> `Mode: TPV — Test Pattern Validation only. You receive: story file, QA-Red commit SHA, list of *.red.node.test.ts files. Verify ONLY: (1) imports resolve to real paths, (2) constructor signatures match, (3) mocked methods exist on the mocked object, (4) after-hooks present when before-hooks write state, (5) file naming *.red.node.test.ts. Do NOT evaluate test logic. Return: TPV: APPROVED (Dev proceeds) or TPV: BLOCKED-WIRING-GAP — <one-sentence specific issue> (orchestrator routes back to QA-Red).`
+
+Architect returns one of:
+
+- `TPV: APPROVED` — proceed to §C.4 Spawn Developer.
+- `TPV: BLOCKED-WIRING-GAP — <issue>` — orchestrator increments `arch_bounces` via:
+  ```bash
+  node .cleargate/scripts/update_state.mjs STORY-NNN-NN --arch-bounce
+  ```
+  Then routes back to §C.3 QA-Red with the gap description in the re-dispatch prompt. If `arch_bounces ≥ 3` → flip story to `Escalated`, halt.
+
+TPV is a WIRING gate, not a correctness gate. A test that imports the right module but asserts incorrectly still gets `TPV: APPROVED` — Dev's TDD cycle handles assertion correctness.
+
+### C.4 Spawn Developer
 
 ```bash
 bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN developer
 ```
 
+**Script invocation rule (CR-046):** Any bash/node script invoked within the Developer dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
 Then spawn with `subagent_type=developer`. Inputs the prompt must include verbatim:
 
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
 - `STORY=NNN-NN` (Developer must echo this on its first response line).
 - Path to story file.
 - Path to milestone plan.
@@ -238,14 +306,20 @@ FILES_CHANGED: <list>
 flashcards_flagged: [ ... ]
 ```
 
-If `STATUS=blocked`: route per §C.7 (Blockers Triage).
+If `STATUS=blocked`: route per §C.8 (Blockers Triage).
 
-### C.4 Spawn QA
+### C.5 Spawn QA-Verify
 
 ```bash
 bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN qa
 ```
 
+**Script invocation rule (CR-046):** Any bash/node script invoked within the QA-Verify dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
+Dispatch prompt MUST inject: `Mode: VERIFY — read-only acceptance trace. Verify Developer's implementation against the story's §4 acceptance Gherkin. Do not write or modify any files.`
+
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
 QA inputs: story file path, worktree path, Developer commit SHA. QA returns:
 
 ```
@@ -256,14 +330,18 @@ REGRESSIONS: <list>
 flashcards_flagged: [ ... ]
 ```
 
-**On `QA: FAIL`:** increment `qa_bounces` via `update_state.mjs STORY-NNN-NN --qa-bounce`. If counter ≥ 3 → flip story to `Escalated`, surface to human, halt. Else → re-spawn Developer with QA's bug report as input. Return to §C.3.
+**On `QA: FAIL`:** increment `qa_bounces` via `update_state.mjs STORY-NNN-NN --qa-bounce`. If counter ≥ 3 → flip story to `Escalated`, surface to human, halt. Else → re-spawn Developer with QA's bug report as input. Return to §C.4.
 
 **On `QA: PASS`:** update state to `QA Passed`, proceed.
 
-### C.5 Architect Pass (v2, `lane: standard` only)
+### C.6 Architect Pass (v2, `lane: standard` only)
 
 `lane: fast` skips this step entirely.
 
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+**Script invocation rule (CR-046):** Any bash/node script invoked within the Architect Pass dispatch MUST go through the wrapper: `bash .cleargate/scripts/run_script.sh <cmd> [args...]`. Direct invocation without the wrapper is forbidden under v2.
+
 ```bash
 bash .cleargate/scripts/pre_gate_runner.sh arch .worktrees/STORY-NNN-NN/ sprint/S-NN
 ```
@@ -272,24 +350,75 @@ If pre-gate scan reveals new dependencies / structural issues → return to Deve
 
 If pre-gate passes, spawn Architect for post-flight review. On `FAIL`: increment `arch_bounces`. ≥ 3 → escalate.
 
-### C.6 Story Merge
+### C.7 Story Merge
 
-```bash
-git checkout sprint/S-NN
-git merge story/STORY-NNN-NN --no-ff -m "merge(story/STORY-NNN-NN): STORY-NNN-NN <title>"
-git worktree remove .worktrees/STORY-NNN-NN
-git branch -d story/STORY-NNN-NN
-```
-
-Verify all required reports exist before merge:
+**DevOps-owned.** The orchestrator does NOT run `git merge`, `git worktree remove`, `git branch -d`, `update_state.mjs`, or `npm run prebuild` directly. All mechanical merge work is delegated to the DevOps agent.
 
-- `STORY-NNN-NN-dev.md` (always required, regardless of lane)
-- `STORY-NNN-NN-qa.md` (required unless lane=fast skipped QA)
-- `STORY-NNN-NN-arch.md` (required for v2 standard-lane only)
+**Required reports — verify before dispatch:**
 
-Missing report → return to spawn that agent. **Do not merge with missing reports.**
-
-### C.7 Blockers Triage (Developer circuit breaker)
+| Report | Required when |
+|---|---|
+| `STORY-NNN-NN-dev.md` | Always (all lanes) |
+| `STORY-NNN-NN-qa.md` | Always, unless lane=fast explicitly skipped QA-Verify |
+| `STORY-NNN-NN-arch.md` | v2 standard-lane only |
+| `STORY-NNN-NN-devops.md` | Written BY DevOps during this step (not a prerequisite) |
+
+Missing `dev.md` or `qa.md` (when required) → return to spawn that agent. **Do not dispatch DevOps with missing reports.**
+
+**Orchestrator dispatch sequence:**
+
+1. Mark the dispatch:
+   ```bash
+   bash .cleargate/scripts/write_dispatch.sh STORY-NNN-NN devops
+   ```
+
+2. Spawn the DevOps agent with the following context (§3.1 Context Pack):
+   ```
+   SPRINT-{NN} — DevOps dispatch for {STORY-ID}.
+
+   INPUTS:
+   - Story ID: {STORY-ID}
+   - Sprint ID: SPRINT-{NN}
+   - Worktree path: .worktrees/{STORY-ID}/
+   - Story branch: story/{STORY-ID}
+   - Sprint branch: sprint/S-{NN}
+   - Dev commit SHA: {abc1234}
+   - QA commit SHA (if present): {def5678}
+   - Architect commit SHA (if present): {ghi9012}
+   - Files-changed manifest: {list from git show --stat <dev-sha>}
+   - Canonical scaffold touched? {yes|no}
+   - Lane: {standard | fast}
+   - Required reports present:
+       - {STORY-ID}-dev.md    ✓
+       - {STORY-ID}-qa.md     ✓ (or "skipped — fast lane")
+       - {STORY-ID}-arch.md   ✓ (v2 standard lane only)
+
+   ACTIONS (in order):
+   1. Verify all required reports exist; halt if any missing.
+   2. Checkout sprint branch.
+   3. git merge story/{STORY-ID} --no-ff -m "merge(story/{STORY-ID}): {commit subject}"
+   4. If canonical scaffold touched: cd cleargate-cli && npm run prebuild
+   5. Mirror parity audit: for each file in files-changed where canonical mirror exists,
+      diff live ↔ canonical. Report drift in §Mirror Parity (DO NOT auto-fix).
+   6. Post-merge test verification: run only test files touched by this commit.
+   7. git worktree remove .worktrees/{STORY-ID}
+   8. git branch -d story/{STORY-ID}
+   9. CLEARGATE_STATE_FILE=... node .cleargate/scripts/update_state.mjs {STORY-ID} Done
+   ```
+
+3. **Halt** and wait for DevOps to return `STATUS=done` or `STATUS=blocked`.
+
+**On `STATUS=done`:** DevOps has written `.cleargate/sprint-runs/SPRINT-{NN}/reports/{STORY-ID}-devops.md`. If it notes live re-sync needed (mirror parity drift), address via `cleargate init` or hand-port at Gate-4 doc-refresh (see §C.9 Flashcard Gate for the next step, then proceed to the next story / wave).
+
+**On `STATUS=blocked`:** DevOps has written `{STORY-ID}-devops-blockers.md`. Surface the blockers report to the human. DevOps does NOT auto-resolve conflicts — orchestrator escalates and waits for human resolution before re-dispatching DevOps.
+
+**Forbidden orchestrator patterns (v2):** `git merge`, `git worktree remove`, `git branch -d`, `update_state.mjs`, `npm run prebuild` in the orchestrator's main session bash log. If any appear, classify as edge case and document in sprint §4 Execution Log.
+
+#### DevOps Escape Hatch — subagent_type=devops unavailable
+
+If spawning `Agent(subagent_type=devops)` returns "Agent type 'devops' not found" (registry miss — see §1 registration constraint note), the orchestrator executes the §C.7 ACTIONS steps 2-9 verbatim inline (in the orchestrator's own bash session). All rules still apply: no `git merge` short-circuit, no conflict auto-resolution. Write the same `STORY-NNN-NN-devops.md` report with an additional frontmatter field `operator: orchestrator-fallback` and note the session restart requirement. This path is exceptional — if it triggers, queue a session restart at the next natural break and verify `devops` appears in the next session's available agent list before continuing the sprint.
+
+### C.8 Blockers Triage (Developer circuit breaker)
 
 When Developer returns `BLOCKED: circuit breaker triggered`, read `.cleargate/sprint-runs/<id>/reports/STORY-NNN-NN-dev-blockers.md`. The report has three sections:
 
@@ -301,7 +430,7 @@ When Developer returns `BLOCKED: circuit breaker triggered`, read `.cleargate/sp
 
 3 consecutive circuit-breaker hits on the same story → `update_state.mjs STORY-NNN-NN Escalated`, halt.
 
-### C.8 Flashcard Gate (v2 mandatory; v1 dogfood)
+### C.9 Flashcard Gate (v2 mandatory; v1 dogfood)
 
 After every story merge — **before creating story N+1's worktree** — process the merged `flashcards_flagged` list (union of dev + QA, dedupe by exact-string):
 
@@ -321,7 +450,24 @@ touch .cleargate/sprint-runs/<sprint-id>/.processed-${HASH}
 
 Under v2, the `pending-task-sentinel.sh` PreToolUse hook blocks the next `Task` spawn until every card has a `.processed-<hash>` marker. Bypass only with `SKIP_FLASHCARD_GATE=1` — log the bypass in sprint §4.
 
-### C.9 Mid-cycle User Input — CR Triage
+### C.10 Mid-Sprint Triage
+
+When the user injects new input mid-sprint (between story kickoff and merge), classify it before routing. Use the keyword-heuristic classifier (`classify()` from `cleargate-cli/src/lib/triage-classifier.ts`) as a first-pass advisory, then confirm. See authoritative rubric: `.cleargate/knowledge/mid-sprint-triage-rubric.md`.
+
+| Class | Trigger | Counter | Human Approval | First-pass action |
+|---|---|---|---|---|
+| `bug` | Defect vs spec | `qa_bounces++` | No | Re-open story; Dev fix; QA re-verify |
+| `clarification` | Ambiguity question | None | No (yes if spec gap) | Update §1.2 in place; re-run impacted test |
+| `scope` | Net-new requirement | None | YES for mid-sprint add | Quarantine to next sprint (default); escalate if goal-critical |
+| `approach` | Different impl, same spec | None | No (yes if cross-story impact) | Reset Dev context; re-spawn with updated approach |
+
+**Confidence signal:** `classify()` returns `confidence: 'low'` when no keyword matched. LOW confidence classifications MUST be confirmed with the human before routing.
+
+**Scope-only note:** This rubric covers USER input only. QA-FAIL bounces continue to use `qa_bounces` (existing §C.5 path). TPV-gap bounces use `arch_bounces` (§C.3.5 path).
+
+For the operational routing table with per-type routing rules, see §C.11 (Mid-cycle User Input — CR Triage).
+
+### C.11 Mid-cycle User Input — CR Triage
 
 If the user injects new input mid-story, classify before routing:
 
@@ -334,7 +480,26 @@ If the user injects new input mid-story, classify before routing:
 
 Log every CR in sprint §4 Execution Log with date + ID.
 
-> 🎯 **Goal check on `CR:scope-change`.** Default routing is quarantine-into-next-sprint. **Override the default if the new requirement is critical to the active sprint goal** — escalate to the human with: *"This scope-change is goal-critical: the sprint goal is `<verbatim>` and without this change, the goal will not be met. Add to current sprint? (Adding mid-sprint requires explicit ack per §C.9.)"* Quarantine remains default for goal-incidental scope.
+> 🎯 **Goal check on `CR:scope-change`.** Default routing is quarantine-into-next-sprint. **Override the default if the new requirement is critical to the active sprint goal** — escalate to the human with: *"This scope-change is goal-critical: the sprint goal is `<verbatim>` and without this change, the goal will not be met. Add to current sprint? (Adding mid-sprint requires explicit ack per §C.11.)"* Quarantine remains default for goal-incidental scope.
+
+### C.11 Script Invocation Contract (CR-046)
+
+All bash/node script invocations dispatched FROM agents (Developer / QA / Architect / DevOps) MUST use the wrapper:
+
+```bash
+bash .cleargate/scripts/run_script.sh <command> [args...]
+```
+
+**What the wrapper does (on failure):**
+- Captures stdout + stderr independently (≤4KB each; truncated with `... [truncated]` if exceeded).
+- Writes a structured JSON incident to `.cleargate/sprint-runs/<sprint-id>/.script-incidents/<ts>-<hash>.json`.
+- Propagates the original exit code to the caller.
+
+**Self-exemption clause:** The wrapper itself (`run_script.sh`) is exempt from wrapping — it sets `RUN_SCRIPT_ACTIVE=1` before executing the wrapped command so recursive calls pass through directly. Orchestrator-direct invocations of `run_script.sh` are the canonical entry point; they are exempt by this contract.
+
+**Agent reporting obligation:** If a wrapped script fails (incident JSON written), the dispatching agent MUST include the incident JSON path in its report's `## Script Incidents` section.
+
+**Pre-sprint invocations (before `.active` sentinel exists):** Wrapper writes to `.cleargate/sprint-runs/_off-sprint/.script-incidents/` when no active sprint is detected. This is expected during preflight steps.
 
 ---
 
@@ -377,6 +542,12 @@ If the report stub does not exist, dispatch the Reporter:
 bash .cleargate/scripts/write_dispatch.sh SPRINT-NN reporter
 ```
 
+- Cross-cutting rules: Read `.cleargate/sprint-runs/<sprint-id>/sprint-context.md` BEFORE any other action.
+
+> **Fresh session.** The Reporter MUST dispatch in a fresh session — do not inherit dev+qa cumulative context. `write_dispatch.sh` already spawns a clean shell child; the `Agent` tool path requires no session-continuation flag. If the runtime offers a session-reset knob (e.g. `--resume false` or equivalent), use it. The Reporter starts cold and reads only `.reporter-context.md` + `sprint_report.md`.
+
+> **Token budget.** Soft warn at 200k tokens, hard advisory at 500k (per CR-036). The token-ledger SubagentStop hook emits the warning to stdout; orchestrator surfaces the line into chat. Hard advisory auto-records a flashcard. The dispatch is NOT killed — the warning is informational; review the bundle slices on next sprint.
+
 Reporter writes `.cleargate/sprint-runs/<id>/SPRINT-<#>_REPORT.md` and returns the Brief:
 
 > **Goal:** `<verbatim sprint goal>` — **Verdict: met | partial | missed.**

package/dist/templates/cleargate-planning/.cleargate/knowledge/mid-sprint-triage-rubric.md

@@ -0,0 +1,160 @@
+# Mid-Sprint Triage Rubric
+
+**CR-047 · SPRINT-23 · Authoritative Reference**
+
+This document is the authoritative rubric for classifying mid-sprint user input. It complements the operational routing table in SKILL.md §C.10 (new rubric section). Read this doc to understand *why* a class exists; read SKILL.md §C.11 (post-CR-047 renumber) to see *how* routing works in practice.
+
+---
+
+## Overview
+
+When a user injects input during an active sprint (between story kickoff and story merge), the orchestrator must classify it before routing. Unclassified input leads to either silent scope creep or unnecessary story restarts. The four classes below are mutually exclusive and exhaustive.
+
+**Classifier aid:** `cleargate-cli/src/lib/triage-classifier.ts` exports a `classify()` pure function that performs keyword-heuristic pre-classification. Output is advisory — the orchestrator confirms before acting. `confidence: 'low'` always requires human verification.
+
+---
+
+## Class 1: Bug
+
+**Definition:** The user reports that existing implemented behaviour is incorrect, broken, or regressed against the current story's acceptance spec. A bug does NOT introduce new requirements — it identifies a gap between the spec and the actual behaviour.
+
+**Keywords (heuristic):** broken, crashes, doesn't work, does not work, regression, nothing works, not working, failed, failure, error, exception, bug, defect, broke.
+
+**Boundary cases:**
+- "The button is broken" → Bug (existing behaviour broken vs spec).
+- "The button should also glow" → NOT Bug; this is Scope Change (new requirement).
+- "After the deploy nothing works" → Bug (regression language).
+
+**Worked examples:**
+
+1. "The login button is broken — it throws a 500 error instead of returning 401."
+   → Class: Bug · Route: re-open story, Dev fixes, QA re-verifies.
+
+2. "After the deploy the email sending stopped working."
+   → Class: Bug · Route: same as above.
+
+**Routing rules:**
+
+- Increment `qa_bounces` via `update_state.mjs <story-id> --qa-bounce`.
+- Re-open the story; Developer fixes; QA re-verifies (full loop).
+- Log in sprint §4 Execution Log: date + story ID + one-line description.
+- Human approval: NOT required (orchestrator routes autonomously).
+
+**Bounce-counter impact:** `qa_bounces++`. If `qa_bounces ≥ 3` → `Escalated`, halt.
+
+---
+
+## Class 2: Spec Clarification
+
+**Definition:** The user asks a question or requests clarification about an existing requirement without adding new scope. The story's acceptance Gherkin remains unchanged after the clarification — at most, ambiguous language in §1.2 gets updated in place.
+
+**Keywords (heuristic):** what does, what is, clarify, clarification, is the same as, the same as, same as, mean in, mean by, what do you mean, does it include, is this, should it.
+
+**Boundary cases:**
+- "What does 'eligible' mean in §3?" → Clarification (no new scope).
+- "Is 'merged' the same as 'closed'?" → Clarification (terminology disambiguation).
+- "What does 'eligible' mean — and should we also check for X?" → SPLIT: Clarification + Scope Change. Handle separately.
+
+**Worked examples:**
+
+1. "What does 'eligible' mean in the eligibility check requirement?"
+   → Class: Clarification · Update §1.2 with the answer; no story restart.
+
+2. "Is 'merged' the same as 'closed' for the purposes of the state machine?"
+   → Class: Clarification · Add a definition note; no counter impact.
+
+**Routing rules:**
+
+- No counter increment.
+- Update §1.2 (Acceptance Criteria) in place with the clarified definition.
+- Re-run only the impacted test(s) (not full loop).
+- Log in sprint §4 Execution Log: date + story ID + one-line clarification.
+- Human approval: NOT required for terminology clarifications. Required if the clarification reveals a spec gap (surface to human before updating §1.2).
+
+**Bounce-counter impact:** None.
+
+---
+
+## Class 3: Scope Change
+
+**Definition:** The user introduces a net-new requirement that was not in the original story spec. Even if "obvious" or "related", if the Gherkin would need a new scenario, it is Scope Change.
+
+**Keywords (heuristic):** also need, we also need, plus add, additionally, new requirement, add a, add an, plus, as well, in addition, new feature, extend with.
+
+**Boundary cases:**
+- "We also need a CSV export" → Scope Change (new feature).
+- "Plus add audit logging" → Scope Change (additional requirement).
+- "The export is broken" → NOT Scope Change; this is Bug.
+
+**Worked examples:**
+
+1. "We also need a CSV export alongside the existing JSON export."
+   → Class: Scope Change · Quarantine into new story in `pending-sync/`. Current story unchanged.
+
+2. "Plus add audit logging for all admin actions."
+   → Class: Scope Change · Same quarantine routing.
+
+**Routing rules:**
+
+- **Quarantine by default.** Create a new Story file in `.cleargate/delivery/pending-sync/` for the next sprint.
+- Current story proceeds UNCHANGED.
+- **Goal-critical override:** if the new requirement is critical to the active sprint goal, escalate to human: *"This scope-change is goal-critical: the sprint goal is `<verbatim>` and without this change, the goal will not be met. Add to current sprint? (Adding mid-sprint requires explicit ack.)"*
+- Log in sprint §4 Execution Log: date + new story ID + one-line description.
+- Human approval: REQUIRED for mid-sprint addition; NOT required for quarantine.
+
+**Bounce-counter impact:** None (quarantine path). If mid-sprint addition approved: treat as a new story dispatch (all counters reset for the new story).
+
+---
+
+## Class 4: Approach Change
+
+**Definition:** The user proposes a different implementation technique or technology for the same spec. The acceptance Gherkin remains identical — only the *how* changes, not the *what*.
+
+**Keywords (heuristic):** instead of, switch to, different way, different approach, replace with, rather than, alternative, migrate to.
+
+**Boundary cases:**
+- "Instead of polling, switch to websockets" → Approach Change (same behaviour spec, different mechanism).
+- "Switch to Postgres instead of Redis for invite storage" → Approach Change (storage backend, same API).
+- "Instead of storing invites, delete them" → NOT Approach Change; this is Scope Change (spec changes).
+
+**Worked examples:**
+
+1. "Instead of polling the API every 5 seconds, switch to websockets for real-time updates."
+   → Class: Approach Change · No counter; reset Developer context; re-spawn with updated approach note.
+
+2. "Use a different algorithm — BFS instead of DFS for the graph traversal."
+   → Class: Approach Change · Same routing.
+
+**Routing rules:**
+
+- No counter increment.
+- Reset Developer context (re-spawn Developer with the updated approach in the dispatch prompt).
+- Story Gherkin and acceptance criteria remain UNCHANGED.
+- Log in sprint §4 Execution Log: date + story ID + one-line approach delta.
+- Human approval: NOT required if the approach is technically equivalent. Required if the approach change affects cost, timeline, or cross-story surfaces.
+
+**Bounce-counter impact:** None.
+
+---
+
+## Routing Summary Table
+
+| Class | Trigger | Counter | Human Approval | Routing Action |
+|---|---|---|---|---|
+| Bug | Defect vs spec | `qa_bounces++` | No | Re-open story; Dev fix; QA re-verify |
+| Spec Clarification | Ambiguity question | None | No (yes if spec gap) | Update §1.2 in place; re-run impacted test |
+| Scope Change | Net-new requirement | None | YES for mid-sprint add | Quarantine to next sprint (default); escalate if goal-critical |
+| Approach Change | Different impl, same spec | None | No (yes if cross-story impact) | Reset Dev context; re-spawn with updated approach |
+
+---
+
+## Cross-References
+
+- **SKILL.md §C.10** — NEW Mid-Sprint Triage section (operational routing table, added by CR-047).
+- **SKILL.md §C.11** — Mid-cycle User Input table (pre-CR-047 §C.10; renumbered to §C.11 by this CR).
+- **`cleargate-cli/src/lib/triage-classifier.ts`** — keyword-heuristic classifier (advisory, not authoritative).
+- **SKILL.md §C.3.5** — TPV Gate (Architect-only wiring check between QA-Red and Developer).
+
+---
+
+_This document is append-only. Add new examples or boundary cases at the bottom of the relevant class block. Do not restructure class ordering — it matches the classifier priority (bug → approach → scope → clarification)._