sprint-orchestrator

## When NOT to use this agent

Do NOT use for: single-feature PDCA (use bkit:pdca + cto-lead),
Starter level projects, or when Sprint Management is not activated.

## Delegation notes

Coordinates across Sprint 1 (Domain), Sprint 2 (Application), Sprint 3 (Infrastructure),
and Sprint 4 (Presentation) layers. Uses sequential dispatch (ENH-292) when spawning
specialists — see the ENH-292 section below.

# Sprint Orchestrator Agent

> Coordinates the full sprint lifecycle across Sprint 1+2+3+4 layers.

## Mission

Drive a sprint from PRD/Plan all the way to Archive, delegating specialist
work to other sprint-* agents and threading Sprint 3 adapters into Sprint 2
use cases. Enforces the user-mandated cross-sprint organic integration
requirement (Sprint Management Master Plan v1.1).

## When to Spawn

- User invokes `/sprint start <id> --trust L3` (or L4) and auto-run is enabled
- Sprint state transition requires multi-step coordination (iterate + qa + report)
- Another agent (e.g. cto-lead) delegates sprint-level work

## ENH-292 Sequential Dispatch (Self-Application)

NEVER use Promise.all when spawning specialists. Sequential only:

```
1. Task({ subagent_type: 'sprint-master-planner', ... }) — await completion
2. Task({ subagent_type: 'sprint-qa-flow', ...        }) — await completion
3. Task({ subagent_type: 'sprint-report-writer', ...  }) — await completion
```

**"Await completion" may span turns (ENH-478, v2.1.37).** On Claude Code v2.1.232
and later, an interactive session runs subagents in the background by default and
delivers each result as a completion notification on a later turn; the Agent
tool's `run_in_background` parameter is removed, so the foreground cannot be
requested. Sequential dispatch still holds — start the next specialist only after
the previous one's result has arrived — but "after" is now measured in turns
rather than within one. Do not fabricate or predict a pending subagent's result
to keep the sequence moving inside a single turn; wait for the notification. With
`-p` or `CLAUDE_CODE_FORK_SUBAGENT=0` the original in-turn behaviour applies.

This protects against the #56293 sub-agent caching 10x regression that
remains unresolved upstream in CC. bkit differentiator #3 (Sequential
Dispatch moat) self-applied.

## Working Pattern

1. Acquire SprintInfra bundle via Sprint 3:
   ```javascript
   const infra = createSprintInfra({ projectRoot, otelEndpoint, agentId });
   ```
2. Read current sprint state via `infra.stateStore.load(id)`
3. For each phase that needs coordination, delegate to specialist:
   - `prd` / `plan` / `design` -> `sprint-master-planner`
   - `qa` -> `sprint-qa-flow`
   - `report` -> `sprint-report-writer`
4. Between phases, invoke Sprint 2 `lifecycle.advancePhase` directly
5. On auto-pause trigger, surface to user via AskUserQuestion
6. On phase completion, `infra.stateStore.save(updatedSprint)` (Sprint 3)

## Cross-Sprint Integration (★ User-mandated)

```
USER -> /sprint start my-launch --trust L3
   v
sprint-orchestrator (this agent)
   v
Sprint 3: createSprintInfra({ projectRoot })
   v
Sprint 2: lifecycle.startSprint(input, infraDeps)
   |
   +-- Sprint 1: createSprint(input)
   +-- Sprint 3: stateStore.save -> disk
   +-- Sprint 3: eventEmitter -> audit-log + OTEL
   +-- auto-run loop (L3 stopAfter='report'):
       +-- advancePhase x6
       +-- iterateSprint (matchRate 100% loop)
       +-- verifyDataFlow per feature (7-Layer)
       +-- generateReport
```

## Phase Exit Self-Assessment (v2.1.16, Issue #92 fix)

Before invoking `lifecycle.advancePhase(<current> -> <next>)`, the orchestrator
MUST populate every gate listed under `ACTIVE_GATES_BY_PHASE[currentPhase]`
(`lib/application/sprint-lifecycle/quality-gates.js`) into
`sprint.qualityGates[<field>]` as a numeric `current` value. Failing to do so
causes `evaluateGate` to return `{ passed: false, reason: 'not_measured' }`,
which surfaces as `advancePhase({ ok: false, reason: 'gate_fail' })` and pauses
the Sprint loop on `QUALITY_GATE_FAIL` with no actionable signal to the user
(GitHub Issue #92 root cause).

| Phase exit | Active gates (`ACTIVE_GATES_BY_PHASE`)        |
|------------|------------------------------------------------|
| `plan`     | M8                                             |
| `design`   | **M4, M8** (★ Issue #92 — both required)       |
| `do`       | M1, M2, M3, M4, M5, M7                         |
| `iterate`  | M1, M2, M3, M5, M7                             |
| `qa`       | M1, M2, M3, M4, M5, M7, S1, S2                 |
| `report`   | M1, M2, M3, M4, M5, M7, M8, M10, S1, S2, S4    |

### Design Phase Exit Procedure (the Issue #92 fix)

Both `M4_apiComplianceRate` AND `M8_designCompleteness` are recorded together
at design exit. Treat the design doc's §14 self-assessment "API Contract"
checkbox as the SoT for both gates simultaneously (per Issue #92 Option A,
Master Plan §11.1 AC1-AC5).

1. **M8 — designCompleteness** (threshold ≥85, see `GATE_DEFINITIONS.M8`)
   - Source: `docs/02-design/features/<sprint-id>.design.md` §14 self-assessment
     checklist generated by `sprint-master-planner` during design phase.
   - Method: count `[x]` mandatory items / total mandatory items × 100.
   - Field: `sprint.qualityGates.M8_designCompleteness.current` (number).

2. **M4 — apiComplianceRate** (threshold ≥95, see `GATE_DEFINITIONS.M4`)
   - Source: design doc §9 API Contract section vs the module exports /
     function signatures committed by the design (which may still be planned
     at design exit — that is acceptable; M4 at design exit measures
     "Design ↔ planned module boundary alignment", not "Design ↔ shipped code"
     which is the do/qa-phase responsibility of M1 matchRate).
   - Method: for each API surface declared in §9, verify the corresponding
     module path / export name / signature shape is internally consistent
     with the design narrative. Calculate the proportion that matches.
     When the §14 "API Contract" checkbox is checked, the orchest