Domdhi logoDOMDHI.OS
BACK_TO_COURSE

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.

WARNING

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.

QUIZ

Two stories in the same derived wave both edit one shared routes file. How does /run-todo run them?

Sign in to track lesson progress and earn a certificate.SIGN IN TO SAVE PROGRESS