The Software Factory — Proof Before Commit
Waves: Derived From Dependencies
The Graph Decides the Order
A wave is a set of stories that can run at the same time. /todo still writes a Wave Plan, but plan-check.js --waves derives the waves from two story fields, and the run checks the written plan against them.
| Field | Means | Effect |
|---|---|---|
**Dependencies:** |
"needs output of" — a file, field, contract or behavior another story produces | Hard: the dependency sits in a strictly earlier wave and is done first |
**After:** |
"prefers to follow" | Soft: only breaks ties among ready stories; never forces a wave |
plan-check.js --strict also validates the plan: the declared waves agree with the dependencies, there are no cycles, file budgets hold, and no two stories of a declared wave write the same file unless it is listed under Shared Hotspot Files. An overlap in a derived wave is a warning, not an error: those writers go to separate worktrees.
Overlapping Writers Get Their Own Worktrees
When two stories in one wave write the same file, plan-check.js --overlap lists them, and each writer runs in its own worktree created from local HEAD (git worktree add -b wave-{N}-{ID} {path} HEAD) — never from the remote's default branch, which may not hold the previous wave's commit. The Main Agent integrates the results with git cherry-pick --no-commit, and the gates and the tamper check run only in the main checkout.
Review on One Shared Cadence
/todo, /run-todo and /do share one review cadence:
- per wave, grouped by seam — stories that share a file, field or contract are reviewed together
- mid-epic — look back across waves and forward at the remaining plan
- final — against the acceptance criteria, closing every deferred item
A change to money, authentication or access also gets a security-auditor review in the wave it lands. Each review is logged as Review — Wave N with what was reviewed, fixed, deferred and skipped — and the seal refuses a wave commit without it.
Tests Arrive With Their Wave
Write a wave's tests only when that wave starts, after the previous wave's commit. A red test file for a later wave would fail the current wave's gate.
Do not list a dependency because a story "reads better after" another. Every Dependencies entry is treated as hard and pushes the story into a later wave. Use After: for preference.
Two stories in the same derived wave both edit one shared routes file. How does /run-todo run them?