{"row":{"id":"ADR-090","title":"Structural doctrine enforcement — gates project the SSOT","file":"adr-090-structural-doctrine-enforcement.md","status":"accepted","date":"2026-06-10","cites":6,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["process","quality","gates","security"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-090: Structural doctrine enforcement — gates project the SSOT","id":"adr-090-structural-doctrine-enforcement--gates-project-the-ssot"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"ADR-003's thesis is "},{"k":"strong","text":"\"enforcement must be mechanical, not social\""},{"k":"text","text":". Yet\nseveral load-bearing invariants were still honor-system — recorded in prose\n(an ADR, an audit table, an ownership matrix) but with no gate that fails when\nthe prose is violated. A self-audit (2026-06-10) found four such gaps:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Gate 5 (mutation ≥90%)"},{"k":"text","text":" — checked only that the crate-spec "},{"k":"em","text":"mentioned"},{"k":"text","text":"\n\"Mutation\". No "},{"k":"code","text":"cargo-mutants"},{"k":"text","text":" was actually run/floored at admission."}],[{"k":"strong","text":"ADR-081 computer-use guards"},{"k":"text","text":" — \"MANDATORY-at-admission\" for the L1\ncrates that touch screen capture / accessibility secure-fields, but nothing\nfailed if a guard-owner crate shipped without its guard."}],[{"k":"strong","text":"Supply-chain policy"},{"k":"text","text":" — "},{"k":"code","text":"deny.toml"},{"k":"text","text":" + "},{"k":"code","text":"cargo-deny"},{"k":"text","text":" were configured but\nunwired; only "},{"k":"code","text":"cargo audit"},{"k":"text","text":" (advisories) ran, not bans/licenses/sources."}],[{"k":"strong","text":"Error one-voice"},{"k":"text","text":" — every error enum was migrated to the canonical\n"},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" trait (recorded in a completeness audit table), but a new\nerror enum could skip the trait silently."}]]},{"k":"p","inline":[{"k":"text","text":"The common shape: a "},{"k":"strong","text":"doctrine with a written SSOT"},{"k":"text","text":" (audit table · ownership\nmatrix · "},{"k":"code","text":"deny.toml"},{"k":"text","text":" policy · the 12-gate list) but "},{"k":"strong","text":"no projection of that\nSSOT into a pass/fail gate"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Every doctrine invariant that can be mechanically checked gets a structural\ngate, and the gate PROJECTS an existing SSOT rather than hardcoding a parallel\nlist."},{"k":"text","text":" This makes the doctrine evolutive (edit the SSOT, the gate follows) and\nantifragile (a regression that violates the doctrine turns a gate RED)."}]},{"k":"p","inline":[{"k":"text","text":"Four gates landed under this principle (2026-06-10):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Gate · SSOT it projects · Invariant"}],[{"k":"text","text":"`scripts/ci/check-mutation-floor.sh` · crate-spec Gate-5 row · real Gate 5 — `cargo-mutants` kill-ratio ≥ floor; BUDGET mode reads a `<!-- GATE5-EXEMPT: N -->` spec marker (survivors ≤ N)"}],[{"k":"text","text":"`scripts/hygiene/check-adr-081-guards.sh` (vector 35) · the ADR-081 ownership matrix · every MANDATORY guard whose owner-crate is a workspace member has an impl-binding (`scripts/ci/adr-081-guard-manifest.tsv`) + impl/test markers"}],[{"k":"text","text":"`scripts/hygiene/check-cargo-deny.sh` (vector 34) · `deny.toml` · full `cargo deny check` (advisories + bans + licenses + sources)"}],[{"k":"text","text":"`scripts/hygiene/check-error-one-voice.sh` (vector 37) · `error-trait-completeness-2026-06-10.md` → `error-one-voice-allowlist.tsv` · every thiserror enum in admitted-crate src impls `NikaErrorCode` or is a documented exemption"}]]},{"k":"p","inline":[{"k":"text","text":"Each gate carries an "},{"k":"strong","text":"orphan/parity check"},{"k":"text","text":" so its projected SSOT can't rot\n(a manifest/allowlist row must map to a real matrix row / real enum). Vector 36\n("},{"k":"code","text":"check-unused-deps.sh"},{"k":"text","text":", cargo-machete) shipped in the same arc."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The four doctrines are now structurally enforced — a future under-pressure\ndev can't let them rot silently (ADR-003's thesis, completed)."}],[{"k":"text","text":"Evolutive: adding a guard / error enum / banned dep updates one SSOT; the\ngate auto-extends. Zero parallel hardcoded lists."}],[{"k":"text","text":"The ADR-081 guard gate is a "},{"k":"strong","text":"forcing-function for the next crate"},{"k":"text","text":": when\n"},{"k":"code","text":"nika-input"},{"k":"text","text":" (M2.4) is admitted, its Guards 1+2 become owed-and-present and\nthe gate goes RED until they ship + test."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"check-mutation-floor.sh"},{"k":"text","text":" and "},{"k":"code","text":"cargo deny check"},{"k":"text","text":" are minutes-slow →\nadmission/CI-tier, not pre-commit. The 34-vector "},{"k":"code","text":"check-all.sh"},{"k":"text","text":" stays fast\n(the slow gates are invoked per-crate at admission)."}],[{"k":"text","text":"BUDGET mode is not reproducible for cross-platform L1 crates: a naive\n"},{"k":"code","text":"cargo mutants -- --lib"},{"k":"text","text":" mutates the cfg'd-out other-OS arms too, so the\nspec's reachable exempt-count (e.g. nika-a11y's 7) does not match the raw\nmacOS survivor count (~31). Calibration needs a per-crate "},{"k":"code","text":"mutants.toml"},{"k":"text","text":"\nexclude_re — a deferred-with-trigger follow-up. Until then those crates carry\nno exempt marker and are not FLOOR-gated."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The self-audit that found these gaps (and two bugs in the mutation gate as it\nwas first shipped) is itself the antifragile pattern: gates are audited like\nany other code, and a gate that would false-RED a legit admission is a bug\ncaught before it blocks."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"scripts/hygiene/check-all.sh"},{"k":"text","text":" — 34 live vectors (34-37 added this arc)"}],[{"k":"code","text":"scripts/hygiene/README.md"},{"k":"text","text":" — vector catalog 34-38"}],[{"k":"code","text":"docs/adr/adr-003-12-gate-admission.md"},{"k":"text","text":" — amendment recording the Gate-5 +\nADR-081 closure"}],[{"k":"code","text":"docs/architecture/error-trait-completeness-2026-06-10.md"},{"k":"text","text":" — the error\none-voice SSOT"}],[{"k":"code","text":"docs/adr/adr-081-l1-effect-crate-guard-contract.md"},{"k":"text","text":" — the guard ownership\nmatrix"}],[{"k":"code","text":"scripts/ci/adr-081-guard-manifest.tsv"},{"k":"text","text":" — the projected guard bindings"}],[{"k":"code","text":"scripts/ci/error-one-voice-allowlist.tsv"},{"k":"text","text":" — the projected error-voice allowlist"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Leave it social (memory + reminders)"},{"k":"text","text":" — rejected: ADR-003 already proved\nthe legacy codebase rotted under social enforcement (29 broken MCP aliases\nlived for months)."}],[{"k":"strong","text":"Hardcode the lists in each gate"},{"k":"text","text":" — rejected: a parallel list drifts from\nthe SSOT. Projection (gate reads the matrix / table / policy file) keeps one\nsource."}],[{"k":"strong","text":"One mega-gate"},{"k":"text","text":" — rejected: four orthogonal drift classes, four scripts,\nsingle responsibility (mirrors the existing vector design)."}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"This ADR records a "},{"k":"em","text":"principle"},{"k":"text","text":", not a frozen list. As new mechanically-checkable\ndoctrines appear (e.g. "},{"k":"code","text":"#[must_use]"},{"k":"text","text":" discipline, public-API surface lock via\n"},{"k":"code","text":"cargo-public-api"},{"k":"text","text":", semver-checks), they fall under the same rule: find the\nSSOT, project it into a gate, add an orphan check. Gate count is not sacred —\nthe projection-from-SSOT discipline is."}]}]

ADR-090

Structural doctrine enforcement — gates project the SSOT

accepted · 2026-06-10 · L0 L0.5 L1 L2 L3 L4 L5 · cites 6

ADR-090: Structural doctrine enforcement — gates project the SSOT #

Context #

ADR-003's thesis is "enforcement must be mechanical, not social". Yet several load-bearing invariants were still honor-system — recorded in prose (an ADR, an audit table, an ownership matrix) but with no gate that fails when the prose is violated. A self-audit (2026-06-10) found four such gaps:

Gate 5 (mutation ≥90%) — checked only that the crate-spec mentioned "Mutation". No cargo-mutants was actually run/floored at admission.
ADR-081 computer-use guards — "MANDATORY-at-admission" for the L1 crates that touch screen capture / accessibility secure-fields, but nothing failed if a guard-owner crate shipped without its guard.
Supply-chain policy — deny.toml + cargo-deny were configured but unwired; only cargo audit (advisories) ran, not bans/licenses/sources.
Error one-voice — every error enum was migrated to the canonical NikaErrorCode trait (recorded in a completeness audit table), but a new error enum could skip the trait silently.

The common shape: a doctrine with a written SSOT (audit table · ownership matrix · deny.toml policy · the 12-gate list) but no projection of that SSOT into a pass/fail gate.

Decision #

Every doctrine invariant that can be mechanically checked gets a structural gate, and the gate PROJECTS an existing SSOT rather than hardcoding a parallel list. This makes the doctrine evolutive (edit the SSOT, the gate follows) and antifragile (a regression that violates the doctrine turns a gate RED).

Four gates landed under this principle (2026-06-10):

Gate · SSOT it projects · Invariant
`scripts/ci/check-mutation-floor.sh` · crate-spec Gate-5 row · real Gate 5 — `cargo-mutants` kill-ratio ≥ floor; BUDGET mode reads a `` spec marker (survivors ≤ N)
`scripts/hygiene/check-adr-081-guards.sh` (vector 35) · the ADR-081 ownership matrix · every MANDATORY guard whose owner-crate is a workspace member has an impl-binding (`scripts/ci/adr-081-guard-manifest.tsv`) + impl/test markers
`scripts/hygiene/check-cargo-deny.sh` (vector 34) · `deny.toml` · full `cargo deny check` (advisories + bans + licenses + sources)
`scripts/hygiene/check-error-one-voice.sh` (vector 37) · `error-trait-completeness-2026-06-10.md` → `error-one-voice-allowlist.tsv` · every thiserror enum in admitted-crate src impls `NikaErrorCode` or is a documented exemption

Each gate carries an orphan/parity check so its projected SSOT can't rot (a manifest/allowlist row must map to a real matrix row / real enum). Vector 36 (check-unused-deps.sh, cargo-machete) shipped in the same arc.

Consequences #

Positive #

The four doctrines are now structurally enforced — a future under-pressure dev can't let them rot silently (ADR-003's thesis, completed).
Evolutive: adding a guard / error enum / banned dep updates one SSOT; the gate auto-extends. Zero parallel hardcoded lists.
The ADR-081 guard gate is a forcing-function for the next crate: when nika-input (M2.4) is admitted, its Guards 1+2 become owed-and-present and the gate goes RED until they ship + test.

Negative #

check-mutation-floor.sh and cargo deny check are minutes-slow → admission/CI-tier, not pre-commit. The 34-vector check-all.sh stays fast (the slow gates are invoked per-crate at admission).
BUDGET mode is not reproducible for cross-platform L1 crates: a naive cargo mutants -- --lib mutates the cfg'd-out other-OS arms too, so the spec's reachable exempt-count (e.g. nika-a11y's 7) does not match the raw macOS survivor count (~31). Calibration needs a per-crate mutants.toml exclude_re — a deferred-with-trigger follow-up. Until then those crates carry no exempt marker and are not FLOOR-gated.

Neutral #

The self-audit that found these gaps (and two bugs in the mutation gate as it was first shipped) is itself the antifragile pattern: gates are audited like any other code, and a gate that would false-RED a legit admission is a bug caught before it blocks.

Evidence #

scripts/hygiene/check-all.sh — 34 live vectors (34-37 added this arc)
scripts/hygiene/README.md — vector catalog 34-38
docs/adr/adr-003-12-gate-admission.md — amendment recording the Gate-5 + ADR-081 closure
docs/architecture/error-trait-completeness-2026-06-10.md — the error one-voice SSOT
docs/adr/adr-081-l1-effect-crate-guard-contract.md — the guard ownership matrix
scripts/ci/adr-081-guard-manifest.tsv — the projected guard bindings
scripts/ci/error-one-voice-allowlist.tsv — the projected error-voice allowlist

Alternatives considered #

Leave it social (memory + reminders) — rejected: ADR-003 already proved the legacy codebase rotted under social enforcement (29 broken MCP aliases lived for months).
Hardcode the lists in each gate — rejected: a parallel list drifts from the SSOT. Projection (gate reads the matrix / table / policy file) keeps one source.
One mega-gate — rejected: four orthogonal drift classes, four scripts, single responsibility (mirrors the existing vector design).

Notes #

This ADR records a principle, not a frozen list. As new mechanically-checkable doctrines appear (e.g. #[must_use] discipline, public-API surface lock via cargo-public-api, semver-checks), they fall under the same rule: find the SSOT, project it into a gate, add an orphan check. Gate count is not sacred — the projection-from-SSOT discipline is.

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

Every decision, with its status This one in the repo