Skip to content

Phases

A phase is a named step in a campaign, recognized by the objectives it lists. Use phases when a refactor happens in stages.

phases:
- { id: repository, objectives: [no-raw-queries-outside-repository] }
- { id: dual-write, objectives: [has-flag] }
- { id: backfilled, attested: true, intent: The backfill has run against production. }
- { id: cutover, objectives: [no-flag] }
- { id: aggregates, intent: Model refunds and disputes inside the billing aggregate. }
Field Meaning
id kebab-case
intent what the phase is for, in prose. Required on an open phase; the nudge shows it
objectives the objective ids that recognize this phase
attested true for a step no detector can see; left with campaigns attest
onTouch overrides the campaign’s onTouch for this phase
endState a node tree for the sector; see The end state
concessions [{ reason, at, by? }], required when a defined phase changes; see below

A phase is defined when it has objectives, attested, or an endState. It is open when it has only an intent, and an open phase must be last. The loader refuses an open phase that is not last, an objective listed by two phases, and an objective id the campaign does not declare.

A sector’s phase is derived, never set: it is the first phase that still has work for that sector (a holdout, a missing attestation, or an open phase). A sector past the last defined phase is done. objectives clear records reached, the furthest phase a sector has been at.

An objective counts for a sector from the phase that lists it until the phase its until field names (exclusive), or to the end. Use a window for a temporary shape, such as a flag that must exist during dual-write and be gone from cutover.

  • Entering a window, objectives clear records the sector’s count as initial, not a regression.
  • Leaving one, remaining holdouts become closed. That is not progress and doesn’t reset the stall clock.
  • A window ending at or before the sector’s reached never reopens for it.

The loader refuses an until naming an unknown phase, or one at or before the listing phase.

A phase with attested: true has no detector. You leave it with:

Terminal window
architecture campaigns attest <sector> <phase> --reason "<why>" [--evidence <url>]

It is accepted only while the sector is at that phase.

An open phase is where the plan runs out. The nudge shows its intent; anyone can leave a note:

Terminal window
architecture campaigns note <sector> "refunds read invoices but never write them"

Adding its first objective later is free (plan refined in the conformance report).

Changing a defined phase’s objectives, an objective’s detector, or the phase’s position fails check until the phase carries a new concessions entry:

- id: repository
objectives: [no-raw-queries-outside-repository]
concessions:
- { reason: "detector widened to catch knex calls", at: "2026-10-02", by: someone@example.com }

The next objectives clear re-baselines the affected sectors, recording { from, to, reason } in each ledger. check compares against the last plan clear wrote.

endState is a node tree whose root ~/ is the sector. It expands into objectives named end-state-<family> (imports, members, surface, structure, exports), each with holdout: declaration. Write it on a phase, or on the campaign for the last phase (a campaign with no phases gets one named end).

endState:
~/:
surface: [{ message: "no default exports", kinds: [default] }]
children:
"domain/": { layout: open, children: {}, imports: { allow: ["~/domain/**"] } }
"ports/": { layout: open, children: {}, imports: { allow: ["~/domain/**"] } }
"adapters/":
layout: open
children: {}
imports: { allow: ["~/ports/**", { sector: "*", via: "~/ports/" }] }
  • { sector, via } allows imports from another sector (* for any) through its via folder.
  • An end state needs sectors with one root: use a glob, file or nx perimeter. The loader refuses one over a marker perimeter, whose sectors may have several roots.
  • Only the CLI evaluates an end state.