Skip to main content
A crate does not join the Nika workspace by being merged. It joins by passing all twelve gates in the same commit. No “we’ll fix Gate 5 later.” No “the spec is obvious.” A crate admission is one atomic commit.
Canonical source: RUST_ENFORCEMENT.md §12 Gates · checker scripts/ci/check-crate-gates.sh (JSON output matches olympus CrateGates TypeScript schema).Live progress: / crates admitted · WIP ().

​
The 12 gates

1

Gate 1 — SPEC

A crate spec exists at docs/crate-specs/<crate>.md. It declares: purpose, layer (L0/L0.5/L1/L2/L3/L4), LOC budget, public API surface, security axes, tracked ADRs. No code before spec.
2

Gate 2 — TDD

Tests written before implementation. The commit history shows RED before GREEN: failing tests on one commit, minimal implementation on the next. Reviewed in gate 11.
3

Gate 3 — IMPL

Minimal implementation. Compiles with cargo build --workspace. Every test green with cargo test --workspace --lib. No # TEMP without a removal plan. No #[allow(dead_code)]. No files >1500 LOC.
4

Gate 4 — CLIPPY 0

cargo clippy --workspace --all-targets -- -D warnings — zero warnings. unwrap_used = "deny" enforced workspace-wide. Zero .unwrap() / .expect( in src/ outside #[cfg(test)].
5

Gate 5 — MUTATION ≥ 90%

cargo mutants -p <crate> — at least 90% of mutants killed. Catches untested branches, “happy path only” tests, dead clauses. Data-heavy crates (e.g., nika-catalog) may use 85% with justification in spec.
6

Gate 6 — PROPERTY

Property tests via proptest for any crate touching: security, parsers, encoding, taint propagation, capability resolution. Regression seeds checked into proptest-regressions/.
7

Gate 7 — BENCHMARKS

benches/ directory with criterion if the crate is on a hot path (parsers, catalog lookup, template resolution). Waivable for pure-types crates with justification in spec.
8

Gate 8 — DOCS

cargo doc --no-deps --document-private-items — zero warnings. All public items documented. #[doc(hidden)] used sparingly and with reason.
9

Gate 9 — CANARY E2E

A .nika.yaml canary workflow under tests/canary-<crate>.nika.yaml exercises the crate end-to-end against the rest of the workspace. Waivable for L0 foundation crates with no runtime surface.
10

Gate 10 — PARITY LEGACY

Golden test comparing output against the legacy v0.79 implementation (read via git show main:path/to/file.rs). Flags behavior drift from v0.79 for conscious review. Landing from Phase 5+.
11

Gate 11 — REVIEW SWARM

Three parallel agents review the PR: spn-nika:code-reviewer + spn-rust:rust-pro + feature-dev:code-reviewer. Every P0 and P1 finding must be fixed in the same session before merge.
12

Gate 12 — ATOMIC COMMIT

Single commit. Message:
feat(<crate>): admit to workspace — all 12 gates passed

Gate 1  SPEC     ✅  docs/crate-specs/<crate>.md
Gate 2  TDD      ✅  RED before GREEN confirmed
Gate 3  IMPL     ✅  <N> LOC, compiles, tests pass
...
Co-Authored-By: Nika 🦋 <nika@supernovae.studio>

​
Why twelve

Each gate catches a failure mode seen in production Rust codebases at scale. Dropping any one means accepting a known regression vector.
GateFailure mode caught
SPECScope creep, missing layer contract, undeclared axes
TDDTests that retrofit the implementation (always green from commit 1)
IMPLOversized files, dead code, TEMP debt
CLIPPYPanic-prone patterns, hidden bugs flagged by lints
MUTATION”100% test coverage” with zero real assertions
PROPERTYEdge cases in parsers / taint / crypto that example-based tests miss
BENCHMARKSSilent perf regression on hot paths
DOCSUndocumented public API, broken intra-doc links
CANARYIntegration breaks hidden by unit-test success
PARITYSilent behavior drift from the v0.79 baseline
REVIEWSingle-reviewer blind spots
ATOMICMerge-commit noise, non-bisectable history

​
Exemptions

A gate is genuinely not applicable for some crate types:
  • benches/ for a pure-types crate with no hot path.
  • Canary E2E for L0 foundation (nothing to execute end-to-end).
  • PARITY for crates with no v0.79 counterpart (Diamond-original code).
Exemptions are documented in docs/crate-specs/<crate>.md with a 1-paragraph justification. They are not defaults — they are deliberate.

​
Admission cadence

One crate at a time. No parallel admission. No “let’s admit these 3 together.” Each crate commit is atomic, bisectable, and reviewable in isolation.
The rhythm: 1 crate admission = 1 commit = 1 tag increment a per-admission alpha tag (v0.8x.0-alpha.N). Every 4 weeks, a blog post or dev log entry. Public accountability.

​
See also

Layer registry

Six layers. Mechanical sort test to pick the right layer for a new crate.

Forward-compat invariants

Eight patterns. The public-API contract every admitted crate honors.

L0 foundation decisions

Q1-Q13 locked — the per-crate decisions that shaped today’s L0.

Constellation

Live progress: admitted, WIP, planned.