ADR-0106 — Keep-clean tooling: make zero-noise structural, not a convention
- Sections
- 4
- Format
- Markdown
- Order
- 142 / 156
Context
Ephemeral-by-default (ADR-0104) and collapse-by-default (ADR-0105) stop the flow artifacts from piling up. But the durable set (specs, findings, decisions) still grows over years, and at scale its dominant failure is duplication, not absence (ADR-0096 §3.5). Single-sourcing, age-out, and freshness are all discipline-dependent — and discipline drifts. A guarantee of zero durable noise can only come from tooling. Ratified from RFC-keep-clean-tooling (suspec-works#72 items 2/5/6/8; suspec-cli#1).
Decision
Specify the keep-clean tooling as the stated anti-bloat forcing function (build is a later plan; this ADR fixes the shape + honesty posture):
- Derived index/board —
suspec statusderives the board from live artifacts; never a hand-maintained list. Toolable (already partly shipped). suspec clean/ gc — delete the gitignored ephemeral past its window; archive any committed-transitory underarchive/; report what changed. Toolable.- Dedup / single-sourcing check — flag a finding or spec section that restates another. Toolable when measured.
- Freshness / supersede check — realizes ADR-0096's specified-not-shipped item (every
superseded_byresolves; the index lists it; past-freshness artifacts flagged). Toolable; the spec-side gates on the living-specs ADR. - Spec-coverage drift (suspec-cli#1) — advisory now, a check once measured 0-FP.
- Promotion-or-die — at Close, a durable discovery promotes to its home or evaporates with the ephemeral scratch. Toolable as a close-gate.
Cost/usage visibility (suspec-works#72.8) splits to its own RFC — it crosses the reconcile-only boundary (ADR-0077: suspec-cli has no token data; the runner must feed it). Honesty framework (ADR-0063): each item ships only when it clears the measurement bar; until then it is named, not enforced.
Consequences
- The human authors only durable truth; the tooling keeps everything else from accumulating — bloat becomes structurally impossible, not a weekly fight.
- Build deferred to a later plan, sequenced by the 0-FP bar. Composes with ADR-0104 (gc prunes the gitignored set) and ADR-0105 (a derived index makes the dial navigable).
- Items 4 (spec freshness/supersede) and 6 (promotion for specs) gate on the living-specs ADR (the spec status/supersede lifecycle must be decided first).
Affected obligations / constraints
- Realizes: ADR-0096's specified-not-shipped supersede/index check. Honors: ADR-0063 (level every claim). Bounded by: ADR-0077 (reconcile-only — cost visibility is out-of-band).
- Does NOT change: the checks contract here (no
checks.yamlrule lands with this ADR).
Starter kit: Set up a workspace