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
Section titled “A sector’s phase”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.
Windows
Section titled “Windows”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 clearrecords the sector’s count asinitial, 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
reachednever reopens for it.
The loader refuses an until naming an unknown phase, or one at or before the listing phase.
Attested phases
Section titled “Attested phases”A phase with attested: true has no detector. You leave it with:
architecture campaigns attest <sector> <phase> --reason "<why>" [--evidence <url>]It is accepted only while the sector is at that phase.
Open phases
Section titled “Open phases”An open phase is where the plan runs out. The nudge shows its intent; anyone can leave a note:
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
Section titled “Changing a defined phase”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.
The end state
Section titled “The end state”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 itsviafolder.- An end state needs sectors with one root: use a
glob,fileornxperimeter. The loader refuses one over amarkerperimeter, whose sectors may have several roots. - Only the CLI evaluates an end state.