a-spec-lists-its-steps-and-the-build-lands-them-one-at-a

Summary

The design record for itd-2609212103565953: the ## Steps section and the loop's per-step lanes.

Scope

1. The template: ## Steps seeded empty by intent plan; the readiness gate reports the section's shape (a list or empty) as advisory (criterion 1).
2. The parser: spec.Steps(spec) returns the ordered list with footprints, or one implicit step (criterion 1).
3. The loop: the lane in the state file gains step: n/N; implement starts the next step's lane only when the previous lane's pull request is an ancestor of the default branch (criterion 2).
4. The remainder: spec close --remainder copies steps not marked landed into the new spec (criterion 3). Each step's indented lines are copied verbatim except a - needs: line, which is rewritten against the remainder's numbering (spc-2609202134341288, piece 6, "Which steps may run side by side").
5. Briefs and the run record: the brief renderer prints the step and its predecessors; the record lists step per lane (criterion 4).
6. The page: commands/intent.md and the build page say the word once for both (criterion 5).

Out of scope

• The build proposing a split; a task family; reordering mid-run.

Approach

A parser in the spec store, a counter in the state file, one branch in the loop's advance; the first spec to carry steps is the implement spec itself, whose three pieces become its ## Steps.

Footprint

• packages: internal/core/spec, internal/core/implement, internal/surface/cli
• tests: the parser over a stepped and an unstepped spec; the loop advancing only after merge with a fake forge; the remainder copy; the brief

How the criteria are satisfied

Progress

• Criteria 1 and 3 (scope 1, 2 and 4) are delivered by commit e5dfe0fc: the plan stub carries an empty ## Steps section, rendered from one list of stub sections; internal/core/spec/steps.go parses the section (- packages:, - tests: and - landed: <pull request or commit> indented under each numbered step) and turns a spec listing none into one implicit step; spec close --remainder carries the steps not marked landed into the remainder and refuses, writing nothing, on a section it cannot read; intent ready reports the section's shape on an advisory steps row.
• Criterion 4 (scope 5) is delivered by commit 3f20b5167: the brief renderer names the lane's spec step and each step before it with what landed it (the spec's landed: line at the lane's base, and the run's earlier lane with its branch, head and pull request), and refuses a base listing the lane's step otherwise; the run record carries an open line naming each later lane's spec step, beside the start line naming the first.
• Criterion 2 (scope 3) is delivered by the implement loop's landing (itd-2609201916151817, piece 9, commit 8ede4810f) and its scheduler (commit 3c19408cb): each spec step lands as its own lane through its own pull request, and a step with no - needs: line needs every earlier step (ruling DR6b keeps this intent's wording of 2026-09-21), so its lane opens only once the earlier lanes are done, a lane being done only when its pushed head is an ancestor of the default branch on origin (landedInRun and readyPending in internal/core/implement/loop/schedule.go). TestAStepWithoutANeedsLineWaitsForEveryEarlierStep in internal/core/implement/loop/parallel_test.go holds step 2's lane closed while lane 1's pull request is armed but not merged, with every slot free, and opens it once lane 1 has landed.
• Criterion 5 (scope 6) is delivered by the lane-stage rename the product thinker ruled on 2026-09-29 (BU1: "SPEC PIECES keep 'step'; rename the lane stages"; iss-2609291313276243): "step" now names the spec's piece and nothing else, a lane's are its stages (the state file, the loop's payloads and refusals say stage, schema version 4), and commands/intent.md and commands/build.md say so — one word for one thing.