The nudge
The nudge tells you, or an agent, when a diff touches code under a campaign: which campaign, what phase that sector is at, and what small change would move it forward. Run it from a stop hook or in CI.
architecture campaigns status --changed [--base <ref>] [--json] [--hotfix "<reason>"] [--by <email>]It reads the working-tree diff against HEAD, or against --base <ref>. See
Commands for the flags.
Output
Section titled “Output”At a defined phase, it lists what is left and the holdouts nearest your change:
billing-ddd billing — phase repository (2 of 6), 9 days here toward the next phase: no-raw-queries-outside-repository 7 · has-integration-test 1 in the files you touched, nearest your change (3 of 8): src/billing/InvoiceService.ts#reconcile:41 no-raw-queries-outside-repository src/billing/InvoiceService.ts#void:58 no-raw-queries-outside-repository src/billing/context.ts has-integration-test this diff: −no-raw-queries-outside-repository: InvoiceService.ts#refund#4b02a9e1 forward onTouch: ratchet — ok ask: hold — leave the sector no worse; paydown is welcome in its own commit, not asked forAt an open phase, it shows the intent and notes, and asks you to refine the phase or leave a
note:
billing-ddd billing — phase aggregates (6 of 6, open), 4 days here intent: Model refunds and disputes inside the billing aggregate. notes (1, data, left at this phase): 2026-10-04 "refunds read invoices but never write them" if this change taught you something about that shape: refine phase `aggregates` in the manifest (a defined phase needs at least one objective with a probe), in its own commit — or leave a note: architecture campaigns note billing "…" --campaign billing-ddd onTouch: advise — ok ask: noteWith nothing to say, a sector gets one line. It shows at most five holdouts per sector, nearest
first: match and declaration holdouts by distance from your change, then file holdouts, then
the sector’s own.
Before and after
Section titled “Before and after”“Before” is the ledger as of the last objectives clear; “after” is your working tree. A holdout
you fixed but haven’t cleared counts as progress, and one the ledger already carries is not growth.
In CI, use --base <ref>: the base commit is checked out and evaluated, including rerunning
report tools. Results are cached per commit under node_modules/.cache/goodbones/.
ask and verdict
Section titled “ask and verdict”Hooks should read these two fields, not the prose.
ask |
When |
|---|---|
none |
under advise; the holdouts are context only |
note |
the sector’s phase is open |
hold |
under ratchet: leave the sector no worse |
paydown-optional |
under paydown, when the diff edits no declaration carrying a holdout |
paydown-required |
under paydown, when it does: the sector must end with fewer holdouts |
verdict |
Meaning | Exit |
|---|---|---|
ok |
the policy is met | 0 |
hotfix |
growth let through with --hotfix, and recorded |
0 |
back |
some objective’s count got worse under ratchet or paydown |
non-zero |
no-paydown |
paydown-required, and the sector did not shrink |
non-zero |
direction is forward (nothing worse, something better), back (the reverse) or mixed.
Counts are compared per objective, never summed.
onTouch
Section titled “onTouch”onTouch sets what a touched sector must do. Set it on the campaign, and override it per phase.
advise: nudge only. New holdouts still failcheckuntil conceded. Default for open phases.ratchet: any count getting worse in a touched sector fails, even with a concession in the same diff. The only escape is--hotfix "<reason>". Moving a holdout to a neighbouring sector sends that sector back instead. Default for defined phases.paydown:ratchet, plus a diff that edits a declaration carrying a holdout must leave the sector with fewer holdouts.
A scalar objective goes back only when it worsens past
its tolerance, and paydown treats it as ratchet. Scalars are listed under measures.
--json prints one document for a hook or PR comment:
{ "version": 1, "mode": "ledger", "base": null, "touched": ["src/billing/InvoiceService.ts"], "sectors": [ { "campaign": "billing-ddd", "sector": "billing", "phase": { "id": "repository", "index": 1, "of": 6, "open": false, "since": "2026-09-22T00:00:00.000Z" }, "intent": "a repository behind a port", "notes": [], "onTouch": "ratchet", "ask": "hold", "verdict": "ok", "residue": { "before": { "no-raw-queries": 8 }, "after": { "no-raw-queries": 7 } }, "direction": "forward", "toward": { "no-raw-queries": 7 }, "holdouts": { "total": 8, "cap": 5, "shown": [ { "file": "src/billing/InvoiceService.ts", "subject": "reconcile#3bfd86f4", "objective": "no-raw-queries", "line": 41, "message": "Move the call behind the port." } ] }, "added": [], "removed": ["no-raw-queries: InvoiceService.ts#refund#4b02a9e1"], "measures": [], "belongsInSector": [] } ], "unbirths": [], "testsChecked": "unknown", "ok": true}belongsInSector: files the diff added inside the scope that no sector claims.unbirths: markers the diff deleted, and the sector each returns to the legacy.testsChecked: alwaysunknown; the tool runs no tests.
Wiring it in
Section titled “Wiring it in”Run status --changed --json from a stop hook or a CLAUDE.md instruction before an agent
finishes, and post it as a PR comment in CI. The oxlint plugin doesn’t nudge; it only reports
holdouts missing from the ledger.