The states, and the moves
A spec has one status at a time, carried in its frontmatter — identity and
state, nothing else. Four moves carry it from an idea to a shipped, archived
contract; reshape is a normal move back, not a failure. The two terminal states,
shipped and killed, exist only in archive/ —
set during archiving, never seen in specs/.
The states
Each state names what's true, who sets it, and where it can go next:
| State | What it means | Who sets it | Transitions |
|---|---|---|---|
draft | Being shaped. Acceptance checks may not yet be falsifiable; open questions may be unresolved. | Agent / PO, while shaping | → ratified (a human approves), or → killed (abandoned). |
ratified | A human read the contract and approved it — the approving merge is the record, and git owns who/when. Build-ready when open-questions.md is clean. | The named decider, by merging to main | → building (the implementer starts), or → draft (reshape). |
building | Under construction by the autonomous loop. Carries a stale_after date — the abandonment trigger. | Implementer, on starting the build | → shipped (graduates), → blocked (hits a contradiction), or → killed. |
blocked | Paused on something the loop can't resolve. Carries a stale_after date. Records the dead end in status.md. | Implementer, on hitting a contradiction | → building (resume after a reshape), or → killed. |
shipped | Done. The contract moves to archive/ verbatim with an acceptance-results link; knowledge/ describes the shipped reality. Exists only in archive/. | Graduation, wired to the implementation PR | Terminal. |
killed | Dropped. Archived with a one-line tombstone stating why ("abandoned" for a draft dropped before ship). The ID stays burned. Exists only in archive/. | A deliberate kill, or an abandoned draft | Terminal. |
The four moves
The lifecycle loop is the feature's journey across the gates — distinct from the autonomous build loop that runs inside the build step:
Shape agent + PO
An agent drafts the contract; the PO edits. The spec lives in draft until it carries a falsifiable Goal and partitioned acceptance checks. Specline runs in author mode here — advisory, reporting distance to ratifiable, not failure.
Ratify decider · the first gate
A named human reads the whole contract in one sitting (B1) and approves it by merging it to main — that merge is the ratification event, and git records who and when. draft → ratified.
Build agent · autonomous
The implementer flips the spec to building and runs the loop toward the Goal, against the agent-loopable checks. It escalates back to a human at the first of two triggers — loop_budget exhausted or stale_after reached. A contradiction flips it to blocked.
Graduate agent · wired to the impl PR
An agent-executed editing pass, triggered structurally by the implementation PR: archives the final spec.md as shipped, writes the present-tense knowledge/ doc, and deletes the spec folder. The human acceptance gate reviews the graduated doc — "is this what I decided?"
Reshape returns to shaping. A mid-build contradiction is a normal transition, not a breach: flip to blocked, land a spec-amendment that re-approves by merging to main (resetting stale_after in the same commit), then resume building. The merged spec on main is canonical, always.
Up: handbook — building. The law: the canon, "Lifecycle".