Skip to content

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.

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

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 for

At 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: note

With 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” 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/.

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 sets what a touched sector must do. Set it on the campaign, and override it per phase.

  • advise: nudge only. New holdouts still fail check until 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: always unknown; the tool runs no tests.

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.