{"row":{"id":"ADR-003","title":"12-gate crate admission protocol","file":"adr-003-12-gate-admission.md","status":"accepted","date":"2026-04-13","cites":20,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["process","quality","gates","admission"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-003: 12-gate crate admission protocol","id":"adr-003-12-gate-crate-admission-protocol"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The Diamond rewrite (ADR-001) is valuable only if the new crates don't accumulate the same debt as legacy (1,276 unwraps, 47 oversized files, silent rot). Code review alone failed in the legacy codebase — reviews happened, yet a P0 audit discovered 29 broken MCP aliases that had lived for months. The enforcement must be "},{"k":"strong","text":"mechanical"},{"k":"text","text":", not social."}]},{"k":"p","inline":[{"k":"text","text":"Five crates have been admitted to date ("},{"k":"code","text":"nika-error"},{"k":"text","text":", "},{"k":"code","text":"nika-catalog"},{"k":"text","text":", "},{"k":"code","text":"nika-catalog-verify"},{"k":"text","text":", "},{"k":"code","text":"nika-kernel"},{"k":"text","text":", "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":"). Each carries the commit body listing all 12 gate results. The process works under load."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Every crate passes "},{"k":"strong","text":"12 sequential gates"},{"k":"text","text":" before its path is added to "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" members:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"# · Gate · Enforces"}],[{"k":"text","text":"1 · SPEC doc · crate purpose + API surface documented in `docs/crate-specs/<name>.md`"}],[{"k":"text","text":"2 · TDD red/green · failing tests written before implementation"}],[{"k":"text","text":"3 · IMPL compiles · workspace builds with the new crate added"}],[{"k":"text","text":"4 · Zero Clippy warnings · `cargo clippy -- -D warnings` clean"}],[{"k":"text","text":"5 · Mutation ≥90% · `cargo-mutants` kills ≥90% of mutants (or documented exemption)"}],[{"k":"text","text":"6 · Property tests · `proptest` on security/parser/boundary code"}],[{"k":"text","text":"7 · Benchmarks · `criterion` on hot paths if applicable"}],[{"k":"text","text":"8 · Zero `cargo doc` warnings · `RUSTDOCFLAGS=\"-D warnings\" cargo doc --no-deps` clean"}],[{"k":"text","text":"9 · Canary E2E · 1 real workflow exercises the crate end-to-end (or exempted for infra crates)"}],[{"k":"text","text":"10 · Golden parity test · output matches legacy where applicable"}],[{"k":"text","text":"11 · 3-agent review swarm · parallel review by fresh agents, all findings resolved"}],[{"k":"text","text":"12 · Atomic commit · single commit with full admission body"}]]},{"k":"p","inline":[{"k":"text","text":"Exemptions (e.g., Gate 9 N/A for "},{"k":"code","text":"nika-error"},{"k":"text","text":") require written justification in the crate spec. No gate skipping without explicit record."}]},{"k":"p","inline":[{"k":"text","text":"Admission commit body format is mandatory (see "},{"k":"code","text":".claude/rules/commit-granularity.md"},{"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":"Every admitted crate starts at a correctness floor legacy never achieved: 0 unwraps, 0 clippy warnings, ≥90% mutation killed, documented public API."}],[{"k":"text","text":"Regression detection front-loaded, not retrofitted."}],[{"k":"text","text":"Proven on 5 crates: "},{"k":"code","text":"nika-error"},{"k":"text","text":" 100% mutation, "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" 100% mutation, "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" 95.7%."}],[{"k":"text","text":"Bisect-friendly history: one crate = one atomic commit."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Admission is expensive per crate (a full session per admission in some cases)."}],[{"k":"text","text":"Gate 5 ("},{"k":"code","text":"cargo-mutants"},{"k":"text","text":") is slow on larger crates — up to ~20 minutes on "},{"k":"code","text":"nika-catalog"},{"k":"text","text":"."}],[{"k":"text","text":"Gate 9 (E2E) is N/A for infrastructure crates, requiring explicit documented exemptions."}],[{"k":"text","text":"Velocity-over-Safety tension: an under-pressure solo dev might rationalize skipping a gate. The process must be socially enforced via memory + reminders."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Agent review (Gate 11) requires ~3 parallel sub-agents per admission — acceptable cost given error detection rate."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":".claude/CLAUDE.md"},{"k":"text","text":" — 12-gates summary"}],[{"k":"code","text":".claude/rules/commit-granularity.md"},{"k":"text","text":" — mandatory commit body format"}],[{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":" lines 196–216 — "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" admission with all 12 gates confirmed, commit "},{"k":"code","text":"ef8804371"}],[{"k":"code","text":"scripts/ci/"},{"k":"text","text":" — check scripts (≈one per Gate): "},{"k":"code","text":"check-clippy.sh"},{"k":"text","text":", "},{"k":"code","text":"check-crate-size.sh"},{"k":"text","text":", "},{"k":"code","text":"check-dead-code.sh"},{"k":"text","text":", "},{"k":"code","text":"check-expect.sh"},{"k":"text","text":", "},{"k":"code","text":"check-fn-length.sh"},{"k":"text","text":", "},{"k":"code","text":"check-loc-limits.sh"},{"k":"text","text":", "},{"k":"code","text":"check-no-default-features.sh"},{"k":"text","text":", "},{"k":"code","text":"check-tests.sh"},{"k":"text","text":", "},{"k":"code","text":"check-unwrap.sh"},{"k":"text","text":", "},{"k":"code","text":"check-adr-coverage.sh"},{"k":"text","text":" (see ADR-009), "},{"k":"code","text":"check-mutation-floor.sh"},{"k":"text","text":" (the REAL Gate 5 executor, 2026-06-10)"}],[{"k":"code","text":".github/workflows/diamond-ci.yml"},{"k":"text","text":" — CI matrix running the gates"}],[{"k":"text","text":"memory: "},{"k":"code","text":"crate-admit"},{"k":"text","text":" skill + "},{"k":"code","text":"gate-check"},{"k":"text","text":" skill — automation entrypoints"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Code review only","id":"alt-a--code-review-only"},{"k":"p","inline":[{"k":"text","text":"Rejected empirically — legacy had reviews, still accumulated 1,276 unwraps."}]},{"k":"h","depth":3,"text":"Alt B — 8-gate protocol","id":"alt-b--8-gate-protocol"},{"k":"p","inline":[{"k":"text","text":"Earlier draft. Rejected because mutation coverage, property tests, and the agent review swarm each caught real issues in admission sessions. Downgrading to 8 would re-open those failure modes."}]},{"k":"h","depth":3,"text":"Alt C — Gates as PR-level CI only (not admission commit)","id":"alt-c--gates-as-pr-level-ci-only-not-admission-commit"},{"k":"p","inline":[{"k":"text","text":"Rejected because CI failure on a PR that has already touched 6 crates is expensive to unwind. Gates run "},{"k":"em","text":"before"},{"k":"text","text":" admission commit lands on nika-diamond."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-001 — orphan rewrite (the reason this process exists)"}],[{"k":"text","text":"ADR-004 — context-window sizing (why we have ~40 admissions to run)"}],[{"k":"text","text":"ADR-009 — ADR process (Gate 12 invokes ADR check)"}],[{"k":"code","text":"crate-admit"},{"k":"text","text":" skill — guided admission workflow"}],[{"k":"code","text":"gate-check"},{"k":"text","text":" skill — run gates against an in-flight crate"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"If a future gate proves redundant (e.g., Gate 10 golden parity becomes meaningless post-v0.95), revisit and supersede. Gate count is not sacred — enforcement floor is."}]},{"k":"h","depth":2,"text":"Amendment — 2026-06-10 · social → structural enforcement","id":"amendment--2026-06-10--social--structural-enforcement"},{"k":"p","inline":[{"k":"text","text":"The Context section's thesis (\"enforcement must be "},{"k":"strong","text":"mechanical"},{"k":"text","text":", not social\")\nand the Negative note (\"an under-pressure solo dev might rationalize skipping a\ngate · socially enforced via memory + reminders\") had two residual honor-system\ngaps. Both are now structurally closed (no decision change · additive per\n"},{"k":"code","text":"cross-source-validation.md"},{"k":"text","text":" §2.7):"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Gate 5 (mutation ≥90%)"},{"k":"text","text":" was checked only by "},{"k":"em","text":"presence"},{"k":"text","text":" (the crate-spec\nmentioning \"Mutation\"). Now "},{"k":"code","text":"scripts/ci/check-mutation-floor.sh <crate> [floor]"},{"k":"text","text":" actually runs "},{"k":"code","text":"cargo-mutants"},{"k":"text","text":", parses the kill ratio (caught /\nviable, excluding unviable), and fails below the floor. Admission/CI-tier\n(minutes-slow — not pre-commit)."}],[{"k":"strong","text":"Gate 2 / ADR-081 guards"},{"k":"text","text":" for L1 computer-use crates ("},{"k":"code","text":"nika-screen"},{"k":"text","text":",\n"},{"k":"code","text":"nika-a11y"},{"k":"text","text":", "},{"k":"code","text":"nika-input"},{"k":"text","text":", "},{"k":"code","text":"nika-browser"},{"k":"text","text":", "},{"k":"code","text":"nika-vision-local"},{"k":"text","text":") were\n\"MANDATORY-at-admission\" in prose only. Now hygiene vector 35\n"},{"k":"code","text":"scripts/hygiene/check-adr-081-guards.sh"},{"k":"text","text":" reads the ADR-081 ownership matrix\nand FAILS if a workspace guard-owner lacks its guard impl+test (binding in\n"},{"k":"code","text":"scripts/ci/adr-081-guard-manifest.tsv"},{"k":"text","text":"). Declarative/evolutive: a future\nguard-owner (e.g. "},{"k":"code","text":"nika-input"},{"k":"text","text":" M2.4 Guards 1+2) goes RED at admission until\nthe guard ships."}]]},{"k":"p","inline":[{"k":"text","text":"Companion supply-chain hardening (same arc): hygiene vectors 34\n("},{"k":"code","text":"check-cargo-deny.sh"},{"k":"text","text":" — bans/licenses/sources, superset of vector 15 advisories)\nand 36 ("},{"k":"code","text":"check-unused-deps.sh"},{"k":"text","text":" — cargo-machete)."}]}]

ADR-003

12-gate crate admission protocol

accepted · 2026-04-13 · L0 L0.5 L1 L2 L3 L4 L5 · cites 20

ADR-003: 12-gate crate admission protocol #

Context #

The Diamond rewrite (ADR-001) is valuable only if the new crates don't accumulate the same debt as legacy (1,276 unwraps, 47 oversized files, silent rot). Code review alone failed in the legacy codebase — reviews happened, yet a P0 audit discovered 29 broken MCP aliases that had lived for months. The enforcement must be mechanical, not social.

Five crates have been admitted to date (nika-error, nika-catalog, nika-catalog-verify, nika-kernel, nika-kernel-mock). Each carries the commit body listing all 12 gate results. The process works under load.

Decision #

Every crate passes 12 sequential gates before its path is added to Cargo.toml members:

# · Gate · Enforces
1 · SPEC doc · crate purpose + API surface documented in `docs/crate-specs/<name>.md`
2 · TDD red/green · failing tests written before implementation
3 · IMPL compiles · workspace builds with the new crate added
4 · Zero Clippy warnings · `cargo clippy -- -D warnings` clean
5 · Mutation ≥90% · `cargo-mutants` kills ≥90% of mutants (or documented exemption)
6 · Property tests · `proptest` on security/parser/boundary code
7 · Benchmarks · `criterion` on hot paths if applicable
8 · Zero `cargo doc` warnings · `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps` clean
9 · Canary E2E · 1 real workflow exercises the crate end-to-end (or exempted for infra crates)
10 · Golden parity test · output matches legacy where applicable
11 · 3-agent review swarm · parallel review by fresh agents, all findings resolved
12 · Atomic commit · single commit with full admission body

Exemptions (e.g., Gate 9 N/A for nika-error) require written justification in the crate spec. No gate skipping without explicit record.

Admission commit body format is mandatory (see .claude/rules/commit-granularity.md).

Consequences #

Positive #

Every admitted crate starts at a correctness floor legacy never achieved: 0 unwraps, 0 clippy warnings, ≥90% mutation killed, documented public API.
Regression detection front-loaded, not retrofitted.
Proven on 5 crates: nika-error 100% mutation, nika-kernel 100% mutation, nika-kernel-mock 95.7%.
Bisect-friendly history: one crate = one atomic commit.

Negative #

Admission is expensive per crate (a full session per admission in some cases).
Gate 5 (cargo-mutants) is slow on larger crates — up to ~20 minutes on nika-catalog.
Gate 9 (E2E) is N/A for infrastructure crates, requiring explicit documented exemptions.
Velocity-over-Safety tension: an under-pressure solo dev might rationalize skipping a gate. The process must be socially enforced via memory + reminders.

Neutral #

Agent review (Gate 11) requires ~3 parallel sub-agents per admission — acceptable cost given error detection rate.

Evidence #

.claude/CLAUDE.md — 12-gates summary
.claude/rules/commit-granularity.md — mandatory commit body format
CHANGELOG.md lines 196–216 — nika-kernel admission with all 12 gates confirmed, commit ef8804371
scripts/ci/ — check scripts (≈one per Gate): check-clippy.sh, check-crate-size.sh, check-dead-code.sh, check-expect.sh, check-fn-length.sh, check-loc-limits.sh, check-no-default-features.sh, check-tests.sh, check-unwrap.sh, check-adr-coverage.sh (see ADR-009), check-mutation-floor.sh (the REAL Gate 5 executor, 2026-06-10)
.github/workflows/diamond-ci.yml — CI matrix running the gates
memory: crate-admit skill + gate-check skill — automation entrypoints

Alternatives considered #

Alt A — Code review only #

Rejected empirically — legacy had reviews, still accumulated 1,276 unwraps.

Alt B — 8-gate protocol #

Earlier draft. Rejected because mutation coverage, property tests, and the agent review swarm each caught real issues in admission sessions. Downgrading to 8 would re-open those failure modes.

Alt C — Gates as PR-level CI only (not admission commit) #

Rejected because CI failure on a PR that has already touched 6 crates is expensive to unwind. Gates run before admission commit lands on nika-diamond.

ADR-001 — orphan rewrite (the reason this process exists)
ADR-004 — context-window sizing (why we have ~40 admissions to run)
ADR-009 — ADR process (Gate 12 invokes ADR check)
crate-admit skill — guided admission workflow
gate-check skill — run gates against an in-flight crate

Notes #

If a future gate proves redundant (e.g., Gate 10 golden parity becomes meaningless post-v0.95), revisit and supersede. Gate count is not sacred — enforcement floor is.

The Context section's thesis ("enforcement must be mechanical, not social") and the Negative note ("an under-pressure solo dev might rationalize skipping a gate · socially enforced via memory + reminders") had two residual honor-system gaps. Both are now structurally closed (no decision change · additive per cross-source-validation.md §2.7):

Gate 5 (mutation ≥90%) was checked only by presence (the crate-spec mentioning "Mutation"). Now scripts/ci/check-mutation-floor.sh <crate> [floor] actually runs cargo-mutants, parses the kill ratio (caught / viable, excluding unviable), and fails below the floor. Admission/CI-tier (minutes-slow — not pre-commit).
Gate 2 / ADR-081 guards for L1 computer-use crates (nika-screen, nika-a11y, nika-input, nika-browser, nika-vision-local) were "MANDATORY-at-admission" in prose only. Now hygiene vector 35 scripts/hygiene/check-adr-081-guards.sh reads the ADR-081 ownership matrix and FAILS if a workspace guard-owner lacks its guard impl+test (binding in scripts/ci/adr-081-guard-manifest.tsv). Declarative/evolutive: a future guard-owner (e.g. nika-input M2.4 Guards 1+2) goes RED at admission until the guard ships.

Companion supply-chain hardening (same arc): hygiene vectors 34 (check-cargo-deny.sh — bans/licenses/sources, superset of vector 15 advisories) and 36 (check-unused-deps.sh — cargo-machete).

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

Every decision, with its status This one in the repo