sprint-execution

name: sprint-execution description: | 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 "start the sprint", "run the sprint", "execute the sprint", "begin sprint execution", "kick off SPRINT-NN", "run STORY-NNN-NN"; CLI directives ending with → Load skill: sprint-execution. The skill does not draft work items, run triage, or manage planning — those stay in always-on CLAUDE.md surface.

Sprint Execution — The Playbook

You are the Orchestrator. You read this playbook top to bottom once when a sprint becomes active, then execute it. You never write production code. You delegate every implementation step to the four execution agents (architect, developer, qa, reporter) by spawning them via the Agent tool with the matching subagent_type.

This skill is the execution-time layer. Triage, drafting, and pre-sprint planning stay in CLAUDE.md and cleargate-protocol.md. Read those before deciding to load this skill.

0. When This Skill Loads

Three explicit load points (belt-and-suspenders — the SKILL description handles the rest):

1. SessionStart banner. When the doctor banner reports Active sprint: SPRINT-NN, the skill auto-loads. (Banner emitted by .claude/hooks/session-start.sh; .cleargate/sprint-runs/.active is the sentinel file.)
2. CLI directive. Any cleargate sprint * command finishing with the line → Load skill: sprint-execution instructs the orchestrator to load this skill before continuing.
3. Natural-language triggers. "start the sprint", "kick off SPRINT-NN", "run the sprint", "execute the loop", "run STORY-NNN-NN" → load the skill, do not improvise.

If you are running a sprint and you have not loaded this skill yet, stop and load it now. Do not orchestrate from memory.

0.5 Goal-First Execution

The sprint goal is the success criterion — not the count of merged stories. A sprint where every story passes QA but the goal is not met is a failed sprint. Read sprint_goal: from the active sprint plan's frontmatter (or §1 if unstructured) at kickoff and treat it as the anchor for every decision the orchestrator makes.

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.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.

What goal-first is NOT:

• Not authority to skip stories the orchestrator deems "off-goal" — splits and merges are decomposition-time decisions, never mid-sprint.
• Not authority to rewrite the goal mid-flight — that requires a CR or a sprint reset.
• Not a license to relax acceptance criteria — story Gherkin still passes verbatim.

It is pure framing: surface deviations from the goal as first-class events, not afterthoughts.

1. Agent Roster + Dispatch Contract

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 '' 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.

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.

Dispatch marker — written automatically before every spawn (fallback only)

The token-ledger hook attributes tokens by reading .cleargate/sprint-runs/<sprint>/.dispatch-<session-id>.json. The primary path is the PreToolUse:Task hook (pre-tool-use-task.sh), which auto-writes the marker on every Agent call without manual orchestrator intervention. The manual script below is a fallback for spawns the auto-hook cannot attribute (e.g. a generic Architect dispatch whose Task() prompt lacks a parseable work-item marker):

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 | devops | cleargate-wiki-contradict.

The script is idempotent: if a same-session auto-marker (written by pre-tool-use-task.sh) already exists for the current session, it exits 0 without writing a duplicate. Omitting the manual call when the auto-hook fires is correct; calling it when unsure is safe (the guard prevents duplication). The hook deletes the marker after consumption — write fresh per dispatch if needed.

2. v1 / v2 Mode Switch

Every step below is gated by the active sprint's execution_mode: frontmatter:

Default is v1. Read the field before spawning Developer/QA/Reporter. If absent, treat as v1. Do not infer mode from sprint number — read the frontmatter.

3. Phase A — Sprint Kickoff (Ready → Active)

Run this sequence exactly once, when the human says "start sprint NN" or equivalent. Halt on any failure; do not improvise around a failed gate.

A.1 Sprint Execution Gate (Gate 3) — preflight

cleargate sprint preflight <sprint-id>

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:

• Prev sprint not closed → run sprint close on prev first.
• Leftover worktree → git worktree remove if abandoned, otherwise merge.
• 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

git checkout -b sprint/S-NN main

Sprint branch is never committed to directly. All work lands via story-branch merges.

A.3 Initialize sprint state

node .cleargate/scripts/init_sprint.mjs SPRINT-NN

This writes .cleargate/sprint-runs/SPRINT-NN/state.json, flips .cleargate/sprint-runs/.active to SPRINT-NN (atomic tmp+rename), and ingests SDR lane assignments so fast-lane stories are stamped correctly without manual reclassification. Without state.json the lane router, dispatch hook, and close pipeline all fail.

Lane ingest (CR-078): init_sprint.mjs reads lane assignments from <sprintDir>/plans/waves.json (lane_assignments: { "STORY-ID": "fast"|"standard" } top-level key) when the file is present. When waves.json is absent it falls back to parsing the Sprint Plan §2.4 Lane Audit table (| Story-ID | fast | rationale |). Stories not declared in either source keep the standard default. Fast-lane stories receive lane_assigned_by: 'sdr-lane-audit'; no manual cleargate story lane … reclassification is needed after init.

.active sentinel (CR-078): init_sprint.mjs atomically writes the sprint ID to .active as its final step. This is the single place the sentinel is SET at kickoff; cleargate sprint close (sprint.ts) is the single place it is CLEARED. If a prior .active value differs from the sprint being initialised, init emits WARN: .active was SPRINT-NN, overwriting with SPRINT-MM — prior sprint may not have been closed to stderr but does not block.

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:

Task instruction: "SPRINT DESIGN REVIEW — write Sprint Plan §2 Execution Strategy.
You have WRITE ACCESS to Sprint Plan §2 ONLY. Produce §§2.1–2.4 (Phase Plan,
Merge Ordering, Shared-Surface Warnings, ADR-Conflict Flags) plus §2.4 Lane Audit."

Architect returns a markdown block; you insert it into the sprint plan file. Then halt and ask the human to confirm the sprint plan before any story executes.

A.5 Flip sprint status

After human confirms, update sprint frontmatter status: Active (via cleargate stamp after the edit).

🎯 Goal check. Before the first Architect dispatch, surface the sprint goal verbatim from the plan's sprint_goal: frontmatter (or §1 if unstructured) in chat: "Sprint goal: . Success = this is met by close. Stories are the means; this is the end." All subsequent halts and decisions reference back to this line.

4. Phase B — Per-Milestone Architect Plan

Before any Developer dispatches in a milestone, spawn the Architect once for the whole milestone:

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
bash .cleargate/scripts/write_dispatch.sh M<N> architect

Then Agent(subagent_type=architect, ...) with the milestone story IDs and instruction to write .cleargate/sprint-runs/<sprint-id>/plans/M<N>.md.

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 ". 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 → 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.

C.0 Execution mode — serial loop vs parallel waves (kill-switch)

Before running any story, read the sprint frontmatter execution_mode and pick the loop:

Kill-switch contract (zero behavior change). Either revert path — execution_mode: v2-serial OR CLEARGATE_PARALLEL_WAVES=off — runs today's serial five-dispatch Phase C loop (§C.1–§C.9) verbatim, with zero behavior change: no launch_wave.mjs invocation appears, and every story executes through the existing Worktree → QA-Red → TPV → Developer → QA-Verify → Architect → Merge → Flashcard sequence one at a time. The parallel-wave code never runs on the kill-switch path. This guarantee is what lets the next sprint adopt v2-parallel and instantly fall back if a wave misbehaves. The selector function is shouldRunParallel(execution_mode, env) in .cleargate/scripts/launch_wave.mjs.

SPRINT-32 note. This sprint ships the parallel-wave capability but runs SERIALLY (serial loop above). The §C.0.1 wave mechanics below ship for the NEXT (self-hosting) sprint. Full contract: protocol §23 "Parallel-Wave Execution Contract".

C.0.1 Parallel-wave launch (execution_mode: v2-parallel)

When parallel waves are active, the Orchestrator runs each wave from the Architect's waves.json (produced by the planning workflow, STORY-033-03) as one parallel() Workflow of worktree-isolated per-story segments, then consolidates at a serial barrier:

1. Pre-launch (worktrees). Pre-create each wave story's worktree serially via git worktree add .worktrees/STORY-X -b story/STORY-X sprint/S-NN (ClearGate-managed worktrees — NOT the Workflow tool's isolation:'worktree', which checks out tracked-files-only off the wrong base; spike decision 2). Serial pre-creation avoids concurrent git worktree add racing the repo index. The flashcard WRITE-gate suppression (SKIP_FLASHCARD_GATE=1, inherited by every segment because per-thunk child env is not settable — spike Q5; reading is unaffected) is owned by launch_wave.mjs, not the Orchestrator (BUG-034): launchWave() snapshots the prior value, sets =1 before parallel(), and restores the exact prior value in a try/finally. The Orchestrator MUST NOT set or restore this var by hand — doing so would double-manage it and reintroduce the leak.

2. Launch. Invoke launch_wave.mjs, which drives parallel() over one segment per story. Each segment mints a stable, distinct RUN_ID (mintRunId(storyId, sprintId)), runs the linear pipeline (QA-Red → TPV → Developer → QA-Verify → Architect post-flight) inside its OWN .worktrees/STORY-X, accumulates tokens from the outset, and RETURNS a schema-typed verdict — it never blocks. A §22 true-blocker becomes a BLOCKED verdict carrying blocker.type (one of the five §22 kinds), never an AskUserQuestion (workflows cannot halt for a human mid-run).

3. Barrier — validate. Run validateVerdicts(verdicts) (exported from launch_wave.mjs). It accepts a well-formed array and raises a validation Error naming the offending storyId on a malformed verdict (missing required field, unknown discriminant, or non-GREEN without blocker). The named segment is marked ESCALATED and gets no ledger row; sibling GREEN verdicts consolidate normally.

4. Barrier — flashcards (between-wave gate, §C.9). Process every segment's flashcards_flagged[] and write the .processed-<hash> markers before launching the next wave — see §C.9.

5. Barrier — serial merge (§C.7). For each GREEN story in turn, DevOps merges story/STORY-X to sprint/S-NN — one worktree at a time, never two concurrently — see §C.7.

6. Barrier — advance. The SKIP_FLASHCARD_GATE value was ALREADY restored by launch_wave.mjs's finally the moment launchWave() returned or threw (BUG-034 — no longer a prose obligation; a mid-barrier throw can no longer leak gate suppression into the serial fallback). If every verdict is GREEN, advance to the next wave. If any verdict is ESCALATED/BLOCKED, halt the wave loop for the human (fully autonomous up to this point per §6 Q3 / protocol §22); on the human's "re-approach", resumeFromRunId re-enters the same run and re-dispatches only the ESCALATED/BLOCKED story's segment — GREEN segments short-circuit on resume with zero new ledger rows (spike Q4: 0 tokens on replay), so re-merging GREEN stories is a no-op.

Idempotent segments. Segments are idempotent as a belt-and-suspenders safety net: a resumeFromRunId re-run of a GREEN segment, or a re-launch after a partial failure, must produce no duplicate side effects (no double-commit, no double-merge, no duplicate ledger row). The RUN_ID-keyed ledger no-op (STORY-033-02) and the serial barrier merge together enforce this; segment idempotency is the redundant guard if either upstream protection regresses.

C.1 Pre-execution check

node .cleargate/scripts/validate_state.mjs
node .cleargate/scripts/validate_bounce_readiness.mjs STORY-NNN-NN

state.json sprintId must equal the active sprint. If not, re-run init_sprint.mjs — do not create a worktree with a stale state.json.

validate_bounce_readiness.mjs checks: story is "Ready to Bounce", §§1/2/3 present, working tree clean. Fail → halt.

C.2 Create worktree

git worktree add .worktrees/STORY-NNN-NN -b story/STORY-NNN-NN sprint/S-NN

Story branch is cut from the sprint branch, never from main. Verify:

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.)

After creating the worktree, provision configured gitignored config into it:

bash .cleargate/scripts/provision_worktree_config.sh .worktrees/STORY-NNN-NN

This symlinks (or copies, per config.yml worktree.provision_mode) the roots in config.yml worktree.provision_config (default [.env]) so the target's build/tests load their config in-worktree without a manual step. The provisioned roots are exempt from the stray_env_files pre-gate scan — the same configured list serves as both the provisioning spec and the scan-exemption list (single source of truth, CR-079).

C.3 Spawn QA-Red (standard lane only — fast lane skips this step)

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
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, run the wiring/pre-gate scan first:

bash .cleargate/scripts/pre_gate_runner.sh arch .worktrees/STORY-NNN-NN/ sprint/S-NN

Semantic fixture lint (CR-081 — included in the pre-gate scan above): pre_gate_runner.sh arch automatically invokes qa_red_lint.mjs (check #5 inside run_arch()) against the worktree's QA-Red test files (*.red.node.test.ts and other red-test forms). This is a pre-gate step — it runs as part of the scan, before any TPV or Developer dispatch. If qa_red_lint flags a semantic fixture error (R-enum: invalid enum literal; R-query: duplicate-text queryByText/getByText), the scan exits non-zero and routes back to QA-Red via arch_bounces (identical to a TPV wiring gap — increment arch_bounces via node .cleargate/scripts/update_state.mjs STORY-NNN-NN --arch-bounce, then re-dispatch §C.3 QA-Red with the lint flag description). The lint check is gated by arch.qa_red_lint in gate-checks.json (default true).

Conditional TPV dispatch (scan-flag gated — a clean standard-lane story proceeds to §C.4 with NO Architect TPV dispatch):

• If the scan returns exit 0 with no flags: skip the live Architect Mode: TPV dispatch and proceed directly to §C.4 Spawn Developer. No Architect agent is spawned for TPV on the clean path.
• If the scan returns a flag (exit 1) or scan-could-not-run (exit 2): 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.

Safeguard (non-removable): ANY pre-gate flag — demotion, arch_bounce signal, surface drift, new-deps, structural issue, OR exit-2 (scan-could-not-run) — MUST still dispatch the live Architect. Treat exit 2 as a flag (fail toward dispatching, never toward skipping). This optimization removes the Architect ONLY on a proven-clean scan; it never removes the Architect from a flagged path.

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
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:

  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

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
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.

• Worktree path (assigned).

• Sprint ID.

Developer returns:

STORY: STORY-NNN-NN
STATUS: done | blocked
COMMIT: <sha> | none
TYPECHECK: pass | fail
TESTS: X passed, Y failed
FILES_CHANGED: <list>
flashcards_flagged: [ ... ]

If STATUS=blocked: route per §C.8 (Blockers Triage).

C.5 Spawn QA-Verify

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
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:

QA: PASS | FAIL
ACCEPTANCE_COVERAGE: N of M scenarios
MISSING: <list>
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.4.

On QA: PASS: update state to QA Passed, proceed.

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 .cleargate/scripts/pre_gate_runner.sh arch .worktrees/STORY-NNN-NN/ sprint/S-NN

If pre-gate scan reveals new dependencies / structural issues → return to Developer (do NOT spawn Architect for mechanical failures). 3+ pre-gate failures → escalate.

Conditional post-flight dispatch (scan-flag gated — a clean standard-lane story dispatches ≤4 agents, not 6; ≤5 when one re-entry fires; 6 when both flag):

• If the scan returns exit 0 with no flags (clean scan): skip the live Architect post-flight dispatch and proceed directly to §C.7 Story Merge. No Architect agent is spawned on the clean path. This drops a fully-clean standard-lane story from 6 dispatches to 4 (QA-Red → Developer → QA-Verify → DevOps — both §C.3.5 TPV and §C.6 post-flight skipped on a fully-clean scan).
• If the scan returns a flag (exit 1) or scan-could-not-run (exit 2): spawn the live Architect for post-flight review. On FAIL: increment arch_bounces. ≥ 3 → escalate.

Safeguard (non-removable): ANY pre-gate flag — demotion, arch_bounce signal, surface drift, new-deps, structural issue, OR exit-2 (scan-could-not-run) — MUST still dispatch the live Architect. Treat exit 2 as a flag (fail toward dispatching, never toward skipping). This optimization removes the Architect ONLY on a proven-clean scan; it never removes the Architect from a flagged path.

C.7 Story 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.

Serial barrier merge (parallel waves only). Under execution_mode: v2-parallel, when a wave's verdicts consolidate at the barrier, the merge is serial: DevOps merges each GREEN story/STORY-X to sprint/S-NN one worktree at a time — no two worktrees merge concurrently. Even though the wave's segments ran in parallel and committed to FS-isolated .worktrees/STORY-X (each with its own .git index, so the per-worktree pre-commit surface gate never races), the shared sprint/S-NN branch is a single-writer axis. The Orchestrator therefore loops over the GREEN stories in order and dispatches DevOps for one merge at a time, awaiting STATUS=done before the next. A mixed GREEN+ESCALATED wave merges the GREEN stories immediately at the barrier (serial), then resumes only the ESCALATED segment via resumeFromRunId — the already-merged GREEN segments short-circuit on resume (zero new ledger rows). Serial-loop sprints merge each story as it completes, exactly as below.

Required reports — verify before dispatch:

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:

   # Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
   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, AND only when pre-gate scan flagged — absent if Architect was not dispatched)
   
   ACTIONS (in order):
   1. Verify all required reports exist; halt if any missing. Exception: arch.md is required ONLY when the §C.6 pre-gate scan flagged (Architect was dispatched); a clean-scan story legitimately has no arch.md and must NOT halt.
   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:

3 consecutive circuit-breaker hits on the same story → update_state.mjs STORY-NNN-NN Escalated, halt.

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):

For each card:

Then mark each card processed:

HASH=$(printf '%s' "<card text>" | shasum -a 1 | cut -c1-12)
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.

Between-wave relocation (parallel waves only). Under execution_mode: v2-parallel the flashcard gate moves from between-story to between-wave. The PreToolUse write-gate cannot fire mid-wave (it would block a segment's own Task spawns inside the running parallel() Workflow and deadlock the wave), so launch_wave.mjs sets SKIP_FLASHCARD_GATE=1 (relocating only the WRITE-gate; flashcard reading inside segments is unaffected) for the duration of the parallel() dispatch and restores it in a try/finally (BUG-034 — code-enforced, not a prose obligation). Each segment returns its cards in its verdict's flashcards_flagged[] instead of blocking. At the barrier, BEFORE launching the next wave, the Orchestrator collects the union of every segment's flashcards_flagged[] (dedupe by exact-string), approves/rejects each card exactly as in the per-story table above, and writes the .processed-<hash> markers — HASH=$(printf '%s' "<card text>" | shasum -a 1 | cut -c1-12); touch .cleargate/sprint-runs/<sprint-id>/.processed-${HASH}. Because launchWave()'s finally has already restored the gate to its exact prior value by the time it returns, the write-gate is active again before any non-wave dispatch — even if validation or merge throws. The markers are written between waves, not between stories.

C.10 Mid-Sprint Triage

When the user injects new input mid-sprint (between story kickoff and merge), classify it before routing. Apply the keyword-heuristic rubric from .cleargate/knowledge/mid-sprint-triage-rubric.md as a first-pass advisory, then confirm with the user. The four classes are: bug, clarification, scope, approach — match the user's language against the keyword banks in the rubric doc.

Confidence signal: When no keyword in the rubric matches the user's input, treat the classification as low-confidence. 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:

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.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 .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.

6. Phase D — Sprint Walkthrough (v2)

Mandatory under v2. After all stories merged into sprint/S-NN (every story state ∈ TERMINAL_STATES) and before sprint→main merge, invite the user to test on the sprint branch. Classify every piece of feedback:

When in doubt, ask: "Is this broken vs spec, or a preference?" Do not default to UR:bug.

Log every event in sprint §4. Sprint branch MUST NOT merge to main while any UR:bug is unresolved. UR:review-feedback may defer with explicit human sign-off.

🎯 Goal check. Open the walkthrough invitation with the sprint goal verbatim, not a feature checklist: "Sprint goal: <verbatim>. The branch is ready on sprint/S-NN. Test it and tell me — does the running build achieve the goal?" This forces the framing to be outcome-vs-spec rather than feature-tour.

6.5 Phase D.5 — Consolidation

When: Runs ONCE per sprint, after all stories have merged into sprint/S-NN (walkthrough done, all UR:bug items resolved) and before Gate-4 close (Phase E). Worktrees are already torn down by §C.7 at this point — this is a sprint-branch operation, not a story-branch operation.

Rationale: Each story is built by a Developer sealed in its own worktree, blind to the others. Cross-story duplication, divergent patterns, and missed reuse are structurally invisible during execution. Phase D.5 is the only place one reviewer sees the whole sprint diff — it is the dedup/reuse/altitude pass that per-story isolation cannot provide.

D.5.1 Run /simplify on the full sprint diff

Invoke the code-simplifier agent (/simplify) against the full sprint diff:

git diff main...sprint/S-NN

The agent applies reuse, deduplication, and altitude fixes and produces ONE consolidation commit on the sprint branch sprint/S-NN. This is not a story branch commit — the worktrees are gone.

Red-test immutability constraint: The consolidation MUST NOT touch any *.red.node.test.ts file (frozen post-Red per §C.3 — same immutability rule as Developer). Before accepting the consolidation commit, the Orchestrator MUST verify the commit's file list contains no *.red.node.test.ts path:

git show --name-only <consolidation-sha> | grep '\.red\.node\.test\.ts'
# Must return empty — any match is a violation; revert immediately.

If *.red.node.test.ts files appear in the consolidation commit's file list, revert the commit unconditionally and log the violation in sprint §4 Execution Log.

D.5.2 QA-Verify re-runs the full suite (safety net)

After the consolidation commit lands on sprint/S-NN, dispatch QA in Consolidation mode (see qa.md § Consolidation-mode dispatch) — a sprint-diff full-suite re-run, read-only, sole question: does the full suite stay green after the /simplify commit?

Green → keep: Full suite is green — keep the consolidation commit on sprint/S-NN and proceed to Phase E (Gate 4 close).

Red → revert: Full suite is red — run git revert <consolidation-sha> on sprint/S-NN. Log the revert in sprint §4 Execution Log. Close the sprint on the un-simplified still-green diff. The un-simplified diff is the correctness floor — a failed simplification never blocks the sprint.

D.5.3 Optional advisory sprint-diff code review

After D.5.1–D.5.2 (whether or not consolidation succeeded), the Orchestrator MAY run an advisory /code-review on git diff main...sprint/S-NN. This is advisory only — it is NOT a gate. Findings go into sprint §4 Execution Log; they do not block Phase E.

7. Phase E — Gate 4 Close (Reporter + Human Sign-off)

This is a Gate-3-class action. Authorising sprint execution does NOT authorise close. Close requires its own dedicated human approval.

E.1 Step A — orchestrator runs close

node .cleargate/scripts/close_sprint.mjs <sprint-id>

No flags. Script validates Steps 1–2.6 (lifecycle reconciler runs at Step 2.6; see cleargate-enforcement.md §10), prefills SPRINT-<#>_REPORT.md stub if missing via the Reporter agent, and exits 0 with the prompt:

Review the report, then confirm close by re-running with --assume-ack.

E.2 Reporter dispatch (Step 3.5)

If the report stub does not exist, dispatch the Reporter:

# Fallback only — auto-marker written by PreToolUse:Task hook in most sessions.
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. 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)?

🎯 Goal check. The verdict line is mandatory and is the first line of the Brief. met = goal achieved as written. partial = some sprint-goal acceptance criteria met, others not — explain which in REPORT §1. missed = goal not achieved despite stories merging. A partial or missed verdict does NOT block close, but it is a first-class signal to the human that close-ack should be deliberate, not reflexive.

E.3 Step B — surface and HALT

Surface the Brief verbatim to the human. Halt. Do not re-run with --assume-ack.

The human either:

• Re-runs close_sprint.mjs <id> --assume-ack themselves, OR
• Says "approved, close it" — at which point you may pass the flag on their behalf.

--assume-ack is reserved for automated test environments only. Passing it autonomously is a Gate-4 breach equivalent to an unauthorized push.

E.4 Doc & metadata refresh on close

During Gate 4 sign-off, read .cleargate/sprint-runs/<id>/.doc-refresh-checklist.md (generated by prep_doc_refresh.mjs). Apply or punt each - [ ] item per .cleargate/knowledge/sprint-closeout-checklist.md. Items already - [x] mean "no changes detected, skip."

E.5 Sprint→main merge

After sign-off and after all walkthrough UR:bug items resolved:

git checkout main
git merge sprint/S-NN --no-ff -m "Sprint S-NN: <goal>"

Then flip sprint frontmatter status: Completed, archive the sprint file (pending-sync/ → archive/).

8. Rework Counter Quick Reference

🎯 Goal check on escalation. When a story flips to Escalated, frame the human-decision question through the goal lens, not in isolation: "STORY-NNN-NN escalated after N rework cycles. Sprint goal is <verbatim>. Options: (a) drop the story — is the goal still met without it? (b) re-approach with X — same goal met by sprint end? (c) split into smaller stories — which scope serves the goal? (d) defer to next sprint — does the goal change?" Never present escalation as a generic "what do you want to do?" — always tie options to goal achievement.

State updates go through:

node .cleargate/scripts/update_state.mjs STORY-NNN-NN [--qa-bounce | --arch-bounce | <new-state>]

Escalated halts the loop until human decides: descope, re-assign approach, or split story.

9. File-Surface Contract (v2)

Each story's §3.1 "Context & Files" table is the authoritative file surface for its commit. The pre-commit hook (.git/hooks/pre-commit → .claude/hooks/pre-commit-surface-gate.sh) blocks commits that touch off-surface files.

Off-surface edits require either:

1. A CR:scope-change approved before the commit, OR
2. An updated §3.1 table committed in the same story (self-amending — must be justified in commit message).

Bypass with SKIP_SURFACE_GATE=1 only when absolutely necessary; log in sprint §4. Under v1 the hook only warns.

10. What This Skill Does NOT Cover

These live elsewhere — do not duplicate inline:

• Triage / drafting / Gate 1 Brief → CLAUDE.md + cleargate-protocol.md §§1–4.
• Worktree command details and edge cases → cleargate-enforcement.md §1.
• Lane classification rubric (7 checks) → .claude/agents/architect.md Lane Classification + cleargate-enforcement.md §9.
• Sprint Plan template / Gate 2 Sprint Ready → .cleargate/templates/Sprint Plan Template.md.
• Wiki ingest / lint / contradiction detection → cleargate-protocol.md §10.
• Doctor exit codes → cleargate-enforcement.md §8.
• Hotfix flow → V-Bounce-style hotfix handling, see flashcard tag #hotfix and wiki/topics/hotfix-ledger.md.

When in doubt, read the source-of-truth doc — this skill cites them, it does not replace them.

11. Conversational Discipline During Execution

• Sprint execution is autonomous. See .cleargate/knowledge/cleargate-protocol.md § Sprint Execution Autonomy for the canonical rule and blocker enumeration. In short: once started, run the loop end-to-end; halt only on the five defined true-blocker cases (destructive actions, secrets, user-intent decisions, technical impossibility, spec-internal contradictions).
• Terse output. Status updates one sentence each. Details live in story reports and SPRINT-<#>_REPORT.md, not in chat.
• Halt at gates without negotiation. Gate 3 (preflight), Gate 4 (close sign-off), Escalated state — these are not advisory. Surface, halt, wait.
• Never --no-verify, --assume-ack autonomously, force-push, or git reset --hard. Every one of these requires explicit per-action human approval.
• Verify, don't trust agent self-reports. A Developer claiming STATUS=done is not done — QA verifies. A QA: PASS is not approved-to-merge until reports exist and merge prerequisites pass.