Ledger
A ledger is a committed JSON file, one per objective, listing every place the pattern still occurs
in each sector. It only shrinks on its own. It lives at <ledger>/<campaign>/<objective>.json;
ledger is a top-level manifest key (default .architecture-campaigns/).
{ "version": 2, "campaign": "billing-ddd", "objective": "no-raw-queries-outside-repository", "created": "2026-09-22T21:56:54.000Z", "sectors": { "billing": { "entered": "2026-09-22T21:56:54.000Z", "initial": 212, "cleared": 187, "closed": 0, "lastCleared": "2026-10-01T09:12:03.000Z", "holdouts": ["InvoiceService.ts#reconcile#3bfd86f4"] } }, "concessions": [ { "sector": "billing", "at": "2026-09-28T14:02:11.000Z", "by": "someone@example.com", "delta": 2, "reason": "hotfix for invoice rounding; BILL-412", "holdouts": ["InvoiceService.ts#void#9a1c02ef", "InvoiceService.ts#void#c31d7f08"] } ]}Holdouts are file or file#subject, relative to the sector’s root, one per line. A sector’s own
holdout (a failed sector term) is ~.
The arithmetic
Section titled “The arithmetic”check verifies, per sector:
holdouts.length === initial + Σ concessions.delta − cleared − closedA re-baseline concession { from, to } counts as to − from. In the example, 212 + 2 − 187 − 0 =
27, so the holdouts list (shortened above) holds 27 entries. A holdout added by hand breaks the
equation and fails check.
| Field | Meaning |
|---|---|
initial |
the count when the sector entered the objective’s window |
cleared |
holdouts that stopped firing and were cleared |
closed |
holdouts still firing when the sector left the window; not progress |
Update the ledger
Section titled “Update the ledger”architecture objectives clear [<campaign>[/<objective>]]architecture objectives concede <campaign>[/<objective>] --reason "<why>"clear reconciles the ledger with the code, never adding a holdout:
- Holdouts that no longer fire are removed;
clearedandlastClearedmove. - A
matchholdout whose hash changed in the same declaration is rewritten in place. - A sector entering a window gets its
initial. This writes the first ledger;checkfails until it exists. - A sector leaving a window, or gone, has its remaining holdouts
closed. - After a phase concession,
sectors are re-baselined with
{ from, to }. - It also writes each sector’s record and the plan.
concede is the only way to add holdouts. It appends a concession with the sector, holdouts,
reason, time and author. See Commands for its flags.
A hit the ledger doesn’t carry fails check with the objective’s how:
campaign billing-ddd: 1 new hit the ledger does not carry. Fix them, or record why the count may rise: no-raw-queries-outside-repository · billing · InvoiceService.ts#refund#4b02a9e1 src/billing/InvoiceService.ts: Move the call behind the port.
architecture objectives concede billing-ddd --reason "<why>"Scalar objectives
Section titled “Scalar objectives”A scalar objective’s ledger has "kind": "measure"
and a direction, and stores numbers instead of holdouts:
{ "version": 2, "kind": "measure", "campaign": "js-to-ts", "objective": "any-density", "created": "2026-09-24T00:00:00.000Z", "direction": "down", "sectors": { "billing": { "entered": "2026-09-24T00:00:00.000Z", "initial": 14.2, "recorded": 9.8, "improved": 4.4, "closed": null, "lastImproved": "2026-10-02T00:00:00.000Z" } }, "concessions": [ { "sector": "billing", "from": 9.8, "to": 11, "reason": "…", "at": "…", "by": "…" } ]}check holds each sector to recorded, within the objective’s tolerance, and verifies
recorded = initial + Σ (to − from) − improved (in the worse direction).
clearmovesrecordedwhen the value improves past the tolerance, adding toimproved.concedemoves it when the value worsens past the tolerance, recording{ from, to }.closedis the value when the sector left the window. Values are rounded to six decimals.- A ledger whose
kindordirectionno longer matches the manifest is refused.
The sector’s record
Section titled “The sector’s record”<campaign>/sectors/<sector>.json is written by clear, campaigns attest and campaigns note.
Don’t edit it by hand.
{ "version": 1, "campaign": "billing-ddd", "sector": "billing", "reached": "cutover", "since": "2026-10-02T00:00:00.000Z", "attested": [ { "phase": "backfilled", "reason": "backfill ran", "evidence": "https://ci/runs/4812", "at": "…", "by": "…" } ], "notes": [{ "at": "…", "by": "…", "phase": "aggregates", "text": "refunds never write invoices" }]}| Field | Meaning |
|---|---|
reached |
the furthest phase the sector has been at; only advances. A passed window never reopens |
since |
when reached last advanced |
attested |
entries from campaigns attest |
notes |
entries from campaigns note; the last 20 kept, each at most 500 characters |
The plan
Section titled “The plan”<campaign>/plan.json is the phase list clear last saw. check compares the manifest to it: a
new phase, or an open phase gaining objectives, is plan refined and allowed. A defined phase
changed or removed is plan changed and fails until the phase has a new concessions entry.
Reviewing a ledger diff
Section titled “Reviewing a ledger diff”- Removed holdout,
cleared+1: progress. - Added holdout: has a new
concessionsentry with a reason you accept. -
closedrose: a sector left a window; no debt was paid. - New sector with a large
initial: code just joined the campaign, and legacy shrank to match. -
{ from, to }concession: a phase change; the reason is in the manifest.
Use CODEOWNERS to put the campaign’s owner on every ledger change:
.architecture-campaigns/billing-ddd/ @dataquail/billingStalls and completion
Section titled “Stalls and completion”- Stalled. A campaign with holdouts left is stalled when every
lastCleared, and every sector’s latestsince, attestation and note, is older thanstaleAfter.checkprints a notice. WithoutstaleAfter, a campaign never stalls. - Complete. At zero everywhere,
onComplete: keepleaves the campaign as a guard;onComplete: removefailscheckuntil you delete the campaign and its ledgers.
Set ARCHITECTURE_NOW (ISO date or epoch milliseconds) to pin the clock for timestamps and stalls.
History
Section titled “History”architecture campaigns history [<campaign>] shows one row per commit: holdouts per objective,
and whether the manifest changed.