{"row":{"id":"ADR-009","title":"ADR process and hook discipline (meta)","file":"adr-009-adr-process.md","status":"accepted","date":"2026-04-14","cites":3,"supersedes":[],"superseded_by":[],"layers":[],"tags":["process","adr","documentation","meta"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-009: ADR process + hook discipline (meta)","id":"adr-009-adr-process--hook-discipline-meta"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Decisions rot. Architectural reasoning captured in Slack, commit messages, or agent memory degrades faster than the code it explains. Six months from a decision, the question "},{"k":"em","text":"\"why did we pick `trait_variant` over `async_trait`?\""},{"k":"text","text":" has to be re-derived from diffs — or, more often, never answered."}]},{"k":"p","inline":[{"k":"text","text":"Legacy Nika (v0.1–v0.27) had 8 ADRs, all "},{"k":"code","text":"Accepted"},{"k":"text","text":" status, no superseding chain, invisible to open-source contributors (they lived in the private monorepo at "},{"k":"code","text":"dx/adr/"},{"k":"text","text":"). When Diamond big-banged, those 8 ADRs were archived wholesale — not because they were wrong, but because the "},{"k":"strong","text":"link between decision and code had rotted"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"Diamond is a multi-year effort. Without a mechanical discipline for writing and maintaining ADRs, the same rot is inevitable."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Every architecturally-significant decision (ASD) lands with an ADR in the same commit."}]},{"k":"h","depth":3,"text":"Location","id":"location"},{"k":"p","inline":[{"k":"text","text":"ADRs live in "},{"k":"code","text":"nika/engine/docs/adr/"},{"k":"text","text":" (this repo, public). Diamond ADRs "},{"k":"strong","text":"must"},{"k":"text","text":" be public — the rationale is educational for open-source contributors and prevents the \"invisible decisions\" problem that killed the legacy ADRs."}]},{"k":"h","depth":3,"text":"Numbering","id":"numbering"},{"k":"p","inline":[{"k":"text","text":"Sequential: "},{"k":"code","text":"adr-001"},{"k":"text","text":", "},{"k":"code","text":"adr-002"},{"k":"text","text":", … Never reused, never reordered. Superseded ADRs keep their number and add "},{"k":"code","text":"Superseded by ADR-NNN"},{"k":"text","text":" to their status."}]},{"k":"h","depth":3,"text":"Template","id":"template"},{"k":"p","inline":[{"k":"code","text":"docs/adr/TEMPLATE.md"},{"k":"text","text":" is the mandatory shape:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Frontmatter: "},{"k":"code","text":"Status"},{"k":"text","text":" (Proposed / Accepted / Superseded) + "},{"k":"code","text":"Date"},{"k":"text","text":" + "},{"k":"code","text":"Phase"},{"k":"text","text":" + "},{"k":"code","text":"Deciders"}],[{"k":"text","text":"Sections: Context → Decision → Consequences (Positive / Negative / Neutral) → Evidence → Alternatives → Related → Notes"}]]},{"k":"h","depth":3,"text":"When to write one","id":"when-to-write-one"},{"k":"p","inline":[{"k":"text","text":"An ASD matches ≥2 of these triggers:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Crosses a crate or layer boundary (affects >1 crate, or defines a layer contract)"}],[{"k":"text","text":"Introduces a new invariant downstream code must respect"}],[{"k":"text","text":"Locks a public API (trait, struct, enum that other crates depend on)"}],[{"k":"text","text":"Makes a non-reversible choice (can't be undone without breaking users)"}],[{"k":"text","text":"Trades a quality attribute (perf vs correctness, simplicity vs flexibility)"}],[{"k":"text","text":"Replaces or supersedes a prior ADR"}]]},{"k":"p","inline":[{"k":"strong","text":"Do not write an ADR for:"},{"k":"text","text":" single-file refactors, bug fixes, dependency bumps, renames without behavior change, style decisions."}]},{"k":"h","depth":3,"text":"Enforcement (the \"hook\")","id":"enforcement-the-hook"},{"k":"p","inline":[{"k":"code","text":"scripts/ci/check-adr-coverage.sh"},{"k":"text","text":" — auxiliary gate script, warn-only initially:"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Parses workspace "},{"k":"code","text":"members"},{"k":"text","text":" from "},{"k":"code","text":"Cargo.toml"}],[{"k":"text","text":"For each admitted crate, greps "},{"k":"code","text":"docs/adr/*.md"},{"k":"text","text":" for "},{"k":"code","text":"\\bcrate_name\\b"}],[{"k":"text","text":"Reports coverage; exits 0 (warn) unless "},{"k":"code","text":"FAIL_ON_MISS=1"},{"k":"text","text":" is set (CI strict mode)"}]]},{"k":"p","inline":[{"k":"text","text":"Integration points:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crate-admit"},{"k":"text","text":" skill invokes this script at Gate 12 (atomic commit) as a soft check"}],[{"k":"text","text":"CI "},{"k":"code","text":".github/workflows/diamond-ci.yml"},{"k":"text","text":" runs "},{"k":"code","text":"FAIL_ON_MISS=1"},{"k":"text","text":" on the "},{"k":"code","text":"main"},{"k":"text","text":" branch"}],[{"k":"text","text":"PR template ("},{"k":"code","text":".github/pull_request_template.md"},{"k":"text","text":") asks: "},{"k":"em","text":"\"Does this change introduce an ASD? If yes, the ADR number: ADR-NNN. If no, explain why.\""}]]},{"k":"h","depth":3,"text":"Supersession","id":"supersession"},{"k":"p","inline":[{"k":"text","text":"When a decision is replaced:"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Set old ADR's status to "},{"k":"code","text":"Superseded by ADR-NNN"}],[{"k":"text","text":"Write the new ADR referencing "},{"k":"code","text":"Supersedes: ADR-M"},{"k":"text","text":" in its Related section"}],[{"k":"text","text":"Commit both changes together (one atomic commit)"}]]},{"k":"p","inline":[{"k":"text","text":"ADRs are "},{"k":"strong","text":"never deleted"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Clarity for future-self and contributors: every hard decision is traceable to a durable document."}],[{"k":"text","text":"Onboarding accelerant: new contributor reads "},{"k":"code","text":"docs/adr/"},{"k":"text","text":" to understand the reasoning, not just the shape."}],[{"k":"text","text":"Supersession chain lets anyone answer "},{"k":"em","text":"\"what was the old approach, why did it change?\""},{"k":"text","text":" in one git-log."}],[{"k":"text","text":"Public ADRs signal project seriousness — mature OSS projects (Rust, Kubernetes, Helix) all ship them."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Writing an ADR is friction. A rushed session may skip it."}],[{"k":"text","text":"Coverage-check is pattern-based (grep crate name); misses ADRs that discuss a crate without naming it."}],[{"k":"text","text":"ADR count grows; at >50 ADRs, navigation becomes harder without tooling. Revisit with "},{"k":"code","text":"docs/adr/INDEX.md"},{"k":"text","text":" auto-generation then."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The meta-ADR (this one) is self-referential: it mandates itself. That is acceptable — bootstrap is always a free variable."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"docs/adr/README.md"},{"k":"text","text":" — full process doc + template usage"}],[{"k":"code","text":"docs/adr/TEMPLATE.md"},{"k":"text","text":" — mandatory template"}],[{"k":"code","text":"scripts/ci/check-adr-coverage.sh"},{"k":"text","text":" — the coverage hook"}],[{"k":"code","text":"docs/adr/adr-001-diamond-orphan-branch.md"},{"k":"text","text":" through "},{"k":"code","text":"adr-008-toml-driven-catalog.md"},{"k":"text","text":" — 8 inaugural ADRs demonstrating the process"}],[{"k":"text","text":"memory: "},{"k":"code","text":"POST_AUDIT_REVISIONS.md"},{"k":"text","text":" — the process hole that motivated this meta-ADR"}],[{"k":"text","text":"Legacy reference: "},{"k":"code","text":"archive/nika-v0.79/adr/LEGACY-NOTE.md"},{"k":"text","text":" (supernovae-hq monorepo) — the rot that this ADR prevents"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Informal ADRs (blog posts, wiki pages)","id":"alt-a--informal-adrs-blog-posts-wiki-pages"},{"k":"p","inline":[{"k":"text","text":"Rejected. Not version-controlled with the code, lost on migrations, invisible to contributors."}]},{"k":"h","depth":3,"text":"Alt B — ADRs in commit messages only","id":"alt-b--adrs-in-commit-messages-only"},{"k":"p","inline":[{"k":"text","text":"Rejected. git-log is lossy UI for decisions that reference each other (supersession is hard to trace)."}]},{"k":"h","depth":3,"text":"Alt C — Private ADRs (in `dx/adr/`, like legacy)","id":"alt-c--private-adrs-in-dxadr-like-legacy"},{"k":"p","inline":[{"k":"text","text":"Rejected. Nika is AGPL open source; hiding architectural rationale from contributors is both technically counterproductive and philosophically inconsistent."}]},{"k":"h","depth":3,"text":"Alt D — ADR-per-crate (nested in `crate-specs/`)","id":"alt-d--adr-per-crate-nested-in-crate-specs"},{"k":"p","inline":[{"k":"text","text":"Rejected. Cross-cutting ADRs (layered architecture, forward-compat invariants) span multiple crates. Central "},{"k":"code","text":"docs/adr/"},{"k":"text","text":" preserves the sequential narrative."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-001 through ADR-008 — the inaugural batch"}],[{"k":"code","text":"scripts/ci/check-adr-coverage.sh"},{"k":"text","text":" — enforcement hook"}],[{"k":"text","text":"Michael Nygard, "},{"k":"link","text":"Documenting Architecture Decisions","href":"https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions"},{"k":"text","text":" (2011)"}],[{"k":"code","text":"archive/nika-v0.79/adr/LEGACY-NOTE.md"},{"k":"text","text":" (supernovae-hq) — prior-art, what happened when the habit wasn't enforced"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"If after ~50 ADRs navigation becomes painful, add "},{"k":"code","text":"docs/adr/INDEX.md"},{"k":"text","text":" generated from ADR frontmatter (status, date, tags). Keep README.md as the human narrative; INDEX.md as the machine view."}]}]

ADR-009

ADR process and hook discipline (meta)

accepted · 2026-04-14 · cites 3

ADR-009: ADR process + hook discipline (meta) #

Context #

Decisions rot. Architectural reasoning captured in Slack, commit messages, or agent memory degrades faster than the code it explains. Six months from a decision, the question "why did we pick `trait_variant` over `async_trait`?" has to be re-derived from diffs — or, more often, never answered.

Legacy Nika (v0.1–v0.27) had 8 ADRs, all Accepted status, no superseding chain, invisible to open-source contributors (they lived in the private monorepo at dx/adr/). When Diamond big-banged, those 8 ADRs were archived wholesale — not because they were wrong, but because the link between decision and code had rotted.

Diamond is a multi-year effort. Without a mechanical discipline for writing and maintaining ADRs, the same rot is inevitable.

Decision #

Every architecturally-significant decision (ASD) lands with an ADR in the same commit.

Location #

ADRs live in nika/engine/docs/adr/ (this repo, public). Diamond ADRs must be public — the rationale is educational for open-source contributors and prevents the "invisible decisions" problem that killed the legacy ADRs.

Numbering #

Sequential: adr-001, adr-002, … Never reused, never reordered. Superseded ADRs keep their number and add Superseded by ADR-NNN to their status.

Template #

docs/adr/TEMPLATE.md is the mandatory shape:

Frontmatter: Status (Proposed / Accepted / Superseded) + Date + Phase + Deciders
Sections: Context → Decision → Consequences (Positive / Negative / Neutral) → Evidence → Alternatives → Related → Notes

When to write one #

An ASD matches ≥2 of these triggers:

Crosses a crate or layer boundary (affects >1 crate, or defines a layer contract)
Introduces a new invariant downstream code must respect
Locks a public API (trait, struct, enum that other crates depend on)
Makes a non-reversible choice (can't be undone without breaking users)
Trades a quality attribute (perf vs correctness, simplicity vs flexibility)
Replaces or supersedes a prior ADR

Do not write an ADR for: single-file refactors, bug fixes, dependency bumps, renames without behavior change, style decisions.

Enforcement (the "hook") #

scripts/ci/check-adr-coverage.sh — auxiliary gate script, warn-only initially:

Parses workspace members from Cargo.toml
For each admitted crate, greps docs/adr/*.md for \bcrate_name\b
Reports coverage; exits 0 (warn) unless FAIL_ON_MISS=1 is set (CI strict mode)

Integration points:

crate-admit skill invokes this script at Gate 12 (atomic commit) as a soft check
CI .github/workflows/diamond-ci.yml runs FAIL_ON_MISS=1 on the main branch
PR template (.github/pull_request_template.md) asks: "Does this change introduce an ASD? If yes, the ADR number: ADR-NNN. If no, explain why."

Supersession #

When a decision is replaced:

Set old ADR's status to Superseded by ADR-NNN
Write the new ADR referencing Supersedes: ADR-M in its Related section
Commit both changes together (one atomic commit)

ADRs are never deleted.

Consequences #

Positive #

Clarity for future-self and contributors: every hard decision is traceable to a durable document.
Onboarding accelerant: new contributor reads docs/adr/ to understand the reasoning, not just the shape.
Supersession chain lets anyone answer "what was the old approach, why did it change?" in one git-log.
Public ADRs signal project seriousness — mature OSS projects (Rust, Kubernetes, Helix) all ship them.

Negative #

Writing an ADR is friction. A rushed session may skip it.
Coverage-check is pattern-based (grep crate name); misses ADRs that discuss a crate without naming it.
ADR count grows; at >50 ADRs, navigation becomes harder without tooling. Revisit with docs/adr/INDEX.md auto-generation then.

Neutral #

The meta-ADR (this one) is self-referential: it mandates itself. That is acceptable — bootstrap is always a free variable.

Evidence #

docs/adr/README.md — full process doc + template usage
docs/adr/TEMPLATE.md — mandatory template
scripts/ci/check-adr-coverage.sh — the coverage hook
docs/adr/adr-001-diamond-orphan-branch.md through adr-008-toml-driven-catalog.md — 8 inaugural ADRs demonstrating the process
memory: POST_AUDIT_REVISIONS.md — the process hole that motivated this meta-ADR
Legacy reference: archive/nika-v0.79/adr/LEGACY-NOTE.md (supernovae-hq monorepo) — the rot that this ADR prevents

Alternatives considered #

Alt A — Informal ADRs (blog posts, wiki pages) #

Rejected. Not version-controlled with the code, lost on migrations, invisible to contributors.

Alt B — ADRs in commit messages only #

Rejected. git-log is lossy UI for decisions that reference each other (supersession is hard to trace).

Alt C — Private ADRs (in `dx/adr/`, like legacy) #

Rejected. Nika is AGPL open source; hiding architectural rationale from contributors is both technically counterproductive and philosophically inconsistent.

Alt D — ADR-per-crate (nested in `crate-specs/`) #

Rejected. Cross-cutting ADRs (layered architecture, forward-compat invariants) span multiple crates. Central docs/adr/ preserves the sequential narrative.

ADR-001 through ADR-008 — the inaugural batch
scripts/ci/check-adr-coverage.sh — enforcement hook
Michael Nygard, Documenting Architecture Decisions (2011)
archive/nika-v0.79/adr/LEGACY-NOTE.md (supernovae-hq) — prior-art, what happened when the habit wasn't enforced

Notes #

If after ~50 ADRs navigation becomes painful, add docs/adr/INDEX.md generated from ADR frontmatter (status, date, tags). Keep README.md as the human narrative; INDEX.md as the machine view.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo