Skip to content

State machine

How a run advances between phases and when it escalates.

Underneath the phases is a state machine: the contract that decides when a run may move forward, when it must loop back and retry, and when it stops and asks for your help. It is deliberately strict — Pipemason would rather pause and tell you what it needs than guess and produce something subtly wrong.

Advancing between phases

Each phase has a precondition for the next phase to begin. A run only advances when the current phase has met its gate — for example, tests that genuinely fail before implementation begins, every test green and the domain lint- and typecheck-clean before verification, and a clean rebase before the final checks. Until a gate is met, the run does not move on.

Looping back on failure

When a gate fails, the run loops back to the phase that can fix it rather than pushing ahead:

  • A failed quality gate in verify loops back to implement (or ui).
  • A failed runtime smoke check loops back to implement (or ui).
  • A visible screenshot mismatch loops back to ui with the diff image.

Every loop is recorded and counts against a retry budget, so a run cannot churn forever on the same problem.

When a run escalates

Escalation is the deliberate stop. Instead of auto-resolving something ambiguous, the run sets itself to a failed-and-waiting state and records what it needs. The common triggers are:

  1. A retry budget is exhausted — too many attempts at the same failure class, too many total iterations, or a phase that ran past its time limit.
  2. A rebase conflict, which always needs human judgment and is never auto-resolved.
  3. A security gate blocking on a high-severity finding.
  4. Unresolved questions in the spec that block the contracts phase.
  5. A contract or cross-reference disagreement the architect phase cannot settle.
  6. An explicit abort from you.

Reading an escalation

An escalation is written into .pipeline/STATE.md with the context you need: the phase it stopped in, the reason, what it is awaiting from you, and a suggested recovery action. Print it any time with:

pipemason status

Resuming

Fix the underlying issue the escalation describes — resolve the conflict, answer the open question, address the finding — then resume:

pipemason resume

The run re-enters at the phase it stopped in and continues from there. It never silently advances past an unresolved escalation.

Note

Gates are not skipped by default. A quality or security gate can only be bypassed with an explicit opt-out flag, and any bypass is logged loudly in the run's iteration log so it is never silent.

Programs have their own machine

Everything above governs a single run. A program runs a second state machine above it — planning, then iterating one run per story, then an integrated verification pass — with its own escalation triggers, such as a roadmap that contains cycles. See Programs for that level.