concepts
Phases
Every run and program advances through a sequence of phases. Each phase has an input artifact, an output artifact, and a gate that decides whether to advance. The dashboard shows the current phase live; commits in the resulting branch are organised one phase at a time.
Per-story phases
Walked once per run. Gates skip phases that don't apply (e.g. no end-to-end tests on a docs-only change). The pipeline enforces order — a phase cannot start before the previous one's artifact is frozen.
| Phase | Writes / freezes | Advance gate |
|---|---|---|
analyze | spec.md | spec satisfies the brief; acceptance criteria are testable |
plan | test-plan.md | every acceptance criterion has ≥1 test row |
contracts | contracts/*.ts | every cross-domain call has a frozen type |
test-red | failing tests | tests fail for the right reason (not import / setup) |
impl | production code | red tests now green; typecheck + lint clean |
review | review pass + retry loop | no unresolved comments above severity threshold |
e2e | e2e flows | all flows pass headless |
security | audit reports | no critical findings; allowlist diffs accounted for |
verify | verify-report.md | aggregate of every prior gate; one failure stops the phase |
pr | commits + PR | branch pushed; PR opened with summary |
Program-level phases
Walked once per program; each one wraps the per-story machine. Which run depends on the mode.
| Phase | Modes | Writes / freezes |
|---|---|---|
audit | brownfield-* | AUDIT.md |
program_plan | all | ROADMAP.md |
migration_plan | brownfield-upgrade | MIGRATIONS.md |
design_system | greenfield-* | DESIGN-SYSTEM.md |
iterate | all | dispatches stories in DAG order |
program_verify | all | verify-report.md |
Why phases freeze
Once a phase's artifact is frozen, no downstream work may rewrite it. This is what makes re-runs cheap and reviewers tractable — one frozen artifact per decision. Escalations are the only way to amend a frozen artifact, and they always go through you.