sprint-orchestrator

# 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
```

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 orchestrator
     accepts §14 as the SoT and records the same proportion (default 100
     for `[x]`, 0 for `[ ]`).
   - Field: `sprint.qualityGates.M4_apiComplianceRate.current` (number).
   - **Tool (canonical from v2.1.16 Layer 2 onward)**: dispatch via
     `lib/application/quality-gates/measure-router.measureGate('M4', sprint,
     { agentTaskRunner })` → routed to `agents/gap-detector.md` per
     `GATE_MEASUREMENT_ROUTES.M4`. Same router serves `/sprint measure
     --gate M4` so design-exit auto-measurement and manual user invocation
     produce identical values (single SoT per Master Plan §11.3 AC7).
     Persistence + audit (`gate_measured` action) handled by
     `lib/application/sprint-lifecycle/measure-gate.usecase.measureGate`
     (Trust Level scope honored: L0/L1 preview-only, L2+ recorded).

3. **Persist both atomically** — canonical path from v2.1.16 Layer 2:
   ```javascript
   // Single SoT for design-exit dual record.
   const lifecycle = require('lib/application/sprint-lifecycle');
   const agg = await lifecycle.measurePhaseGates(sprint, 'design', {
     agentTaskRunner,        // injected