Skip to content

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 ~.

check verifies, per sector:

holdouts.length === initial + Σ concessions.delta − cleared − closed

A 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
Terminal window
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; cleared and lastCleared move.
  • A match holdout whose hash changed in the same declaration is rewritten in place.
  • A sector entering a window gets its initial. This writes the first ledger; check fails 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>"

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).

  • clear moves recorded when the value improves past the tolerance, adding to improved.
  • concede moves it when the value worsens past the tolerance, recording { from, to }.
  • closed is the value when the sector left the window. Values are rounded to six decimals.
  • A ledger whose kind or direction no longer matches the manifest is refused.

<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

<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.

  • Removed holdout, cleared +1: progress.
  • Added holdout: has a new concessions entry with a reason you accept.
  • closed rose: 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/billing
  • Stalled. A campaign with holdouts left is stalled when every lastCleared, and every sector’s latest since, attestation and note, is older than staleAfter. check prints a notice. Without staleAfter, a campaign never stalls.
  • Complete. At zero everywhere, onComplete: keep leaves the campaign as a guard; onComplete: remove fails check until you delete the campaign and its ledgers.

Set ARCHITECTURE_NOW (ISO date or epoch milliseconds) to pin the clock for timestamps and stalls.

architecture campaigns history [<campaign>] shows one row per commit: holdouts per objective, and whether the manifest changed.