{"row":{"id":"ADR-001","title":"Diamond orphan branch rewrite instead of iterative refactor","file":"adr-001-diamond-orphan-branch.md","status":"accepted","date":"2026-04-13","cites":9,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["architecture","rewrite","diamond","orphan-branch"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-001: Diamond — orphan branch rewrite instead of iterative refactor","id":"adr-001-diamond--orphan-branch-rewrite-instead-of-iterative-refactor"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Legacy Nika ("},{"k":"code","text":"main"},{"k":"text","text":", v0.79.3) had reached 322k LOC across 31 crates with 1,276 "},{"k":"code","text":".unwrap()"},{"k":"text","text":" calls and 47 files above the 1,500-LOC cap. The single biggest correctness risk became "},{"k":"strong","text":"context loss"},{"k":"text","text":": no AI assistant could fit the whole system in a single context window. The math in "},{"k":"code","text":"ROADMAP.md"},{"k":"text","text":" is explicit — a 138k-LOC monolith ("},{"k":"code","text":"nika-core"},{"k":"text","text":") ≈ 750k tokens ≈ 75% of a 1M-token context just to read one crate. Reviewing any non-trivial change devolved into pattern-matching against partial slices, which is how hallucinated refactors land."}]},{"k":"p","inline":[{"k":"text","text":"Shadow-zone audit (16-agent Rust Council, 2026-04-13) confirmed 7 subsystems where documentation diverged from implementation. Incremental refactor would require untangling these in-place while maintaining compat."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Create an "},{"k":"strong","text":"orphan branch `nika-diamond`"},{"k":"text","text":" from scratch. No code inherited from "},{"k":"code","text":"main"},{"k":"text","text":". Legacy "},{"k":"code","text":"main"},{"k":"text","text":" becomes a read-only reference via "},{"k":"code","text":"git show brouillon:path"},{"k":"text","text":". Every line of the diamond is "},{"k":"strong","text":"rewritten"},{"k":"text","text":", not ported. 32 legacy crate directories are excluded from "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" members via the "},{"k":"code","text":"exclude"},{"k":"text","text":" key — they sit in the orphan working tree but do not participate in the workspace."}]},{"k":"p","inline":[{"k":"text","text":"Legacy "},{"k":"code","text":"main"},{"k":"text","text":" stays frozen at v0.79.3. The diamond starts at "},{"k":"strong","text":"v0.80.0"},{"k":"text","text":" to mark the boundary. Users on v0.79.x cannot benefit until v0.90 feature parity."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Each diamond crate fits entirely in an AI context window (≤15k LOC ≈ 70k tokens ≈ 7% of 1M-token context, 10× headroom)."}],[{"k":"text","text":"Zero accumulated legacy debt admitted — each crate enters via the 12-gate protocol (see ADR-003)."}],[{"k":"text","text":"Clean APIs enforced up-front; no breaking-change migrations mid-Diamond."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Approximately 11–12 months to feature parity (v0.90 milestone). Substantially longer than incremental refactor."}],[{"k":"text","text":"No interim releasable state for Diamond users; the v0.79→v0.80 cliff is real."}],[{"k":"text","text":"5 admitted crates at v0.80.0-alpha.x means tiny installable surface today."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Legacy bug fixes (CVE-class only) require separate back-port commits on "},{"k":"code","text":"main"},{"k":"text","text":". None expected post-abandonment."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Cargo.toml"},{"k":"text","text":" lines 1–17 — 5 admitted "},{"k":"code","text":"members"},{"k":"text","text":", 32 excluded legacy crates"}],[{"k":"code","text":"ROADMAP.md"},{"k":"text","text":" lines 17–35 — \"Why Diamond\" context-window argument"}],[{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":" lines 307–320 — v0.80.0-alpha.0 commit "},{"k":"code","text":"42909b1c7"}],[{"k":"code","text":"DIAMOND.md"},{"k":"text","text":" lines 40–53 — orphan-branch rationale"}],[{"k":"text","text":"memory: "},{"k":"code","text":"POST_AUDIT_REVISIONS.md"},{"k":"text","text":" — 10 locked decisions, 2026-04-13"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Iterative in-place refactor","id":"alt-a--iterative-in-place-refactor"},{"k":"p","inline":[{"k":"text","text":"Split each oversized file, add gates progressively, delete unwraps crate-by-crate on "},{"k":"code","text":"main"},{"k":"text","text":". Rejected because the ~8k-LOC "},{"k":"code","text":"nika-core/src/binding/"},{"k":"text","text":" alone would need 4–5 ADR-scale decisions each and the audit proved human+AI context capacity would not hold across 322k LOC over 11+ months."}]},{"k":"h","depth":3,"text":"Alt B — Workspace overlay (additive)","id":"alt-b--workspace-overlay-additive"},{"k":"p","inline":[{"k":"text","text":"Keep "},{"k":"code","text":"main"},{"k":"text","text":", add new crates alongside, migrate consumers lazily. Rejected because compat tax (dual APIs, feature flags, fallback logic) would re-create the 2,945-LOC "},{"k":"code","text":"resolve.rs"},{"k":"text","text":" class of file inside the new crates within months."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-003 — 12-gate admission (the quality floor every diamond crate must pass)"}],[{"k":"text","text":"ADR-004 — context-window-sized crates (the sizing rule the rewrite enables)"}],[{"k":"code","text":"archive/nika-v0.79/adr/"},{"k":"text","text":" (supernovae-hq monorepo) — 8 pre-Diamond ADRs, superseded by this rewrite"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Revisit if a v0.95 feature requires legacy behavior that was never documented. Otherwise this ADR is terminal — orphan rewrites are not reverted."}]}]

ADR-001

Diamond orphan branch rewrite instead of iterative refactor

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

ADR-001: Diamond — orphan branch rewrite instead of iterative refactor #

Context #

Legacy Nika (main, v0.79.3) had reached 322k LOC across 31 crates with 1,276 .unwrap() calls and 47 files above the 1,500-LOC cap. The single biggest correctness risk became context loss: no AI assistant could fit the whole system in a single context window. The math in ROADMAP.md is explicit — a 138k-LOC monolith (nika-core) ≈ 750k tokens ≈ 75% of a 1M-token context just to read one crate. Reviewing any non-trivial change devolved into pattern-matching against partial slices, which is how hallucinated refactors land.

Shadow-zone audit (16-agent Rust Council, 2026-04-13) confirmed 7 subsystems where documentation diverged from implementation. Incremental refactor would require untangling these in-place while maintaining compat.

Decision #

Create an orphan branch `nika-diamond` from scratch. No code inherited from main. Legacy main becomes a read-only reference via git show brouillon:path. Every line of the diamond is rewritten, not ported. 32 legacy crate directories are excluded from Cargo.toml members via the exclude key — they sit in the orphan working tree but do not participate in the workspace.

Legacy main stays frozen at v0.79.3. The diamond starts at v0.80.0 to mark the boundary. Users on v0.79.x cannot benefit until v0.90 feature parity.

Consequences #

Positive #

Each diamond crate fits entirely in an AI context window (≤15k LOC ≈ 70k tokens ≈ 7% of 1M-token context, 10× headroom).
Zero accumulated legacy debt admitted — each crate enters via the 12-gate protocol (see ADR-003).
Clean APIs enforced up-front; no breaking-change migrations mid-Diamond.

Negative #

Approximately 11–12 months to feature parity (v0.90 milestone). Substantially longer than incremental refactor.
No interim releasable state for Diamond users; the v0.79→v0.80 cliff is real.
5 admitted crates at v0.80.0-alpha.x means tiny installable surface today.

Neutral #

Legacy bug fixes (CVE-class only) require separate back-port commits on main. None expected post-abandonment.

Evidence #

Cargo.toml lines 1–17 — 5 admitted members, 32 excluded legacy crates
ROADMAP.md lines 17–35 — "Why Diamond" context-window argument
CHANGELOG.md lines 307–320 — v0.80.0-alpha.0 commit 42909b1c7
DIAMOND.md lines 40–53 — orphan-branch rationale
memory: POST_AUDIT_REVISIONS.md — 10 locked decisions, 2026-04-13

Alternatives considered #

Alt A — Iterative in-place refactor #

Split each oversized file, add gates progressively, delete unwraps crate-by-crate on main. Rejected because the ~8k-LOC nika-core/src/binding/ alone would need 4–5 ADR-scale decisions each and the audit proved human+AI context capacity would not hold across 322k LOC over 11+ months.

Alt B — Workspace overlay (additive) #

Keep main, add new crates alongside, migrate consumers lazily. Rejected because compat tax (dual APIs, feature flags, fallback logic) would re-create the 2,945-LOC resolve.rs class of file inside the new crates within months.

ADR-003 — 12-gate admission (the quality floor every diamond crate must pass)
ADR-004 — context-window-sized crates (the sizing rule the rewrite enables)
archive/nika-v0.79/adr/ (supernovae-hq monorepo) — 8 pre-Diamond ADRs, superseded by this rewrite

Notes #

Revisit if a v0.95 feature requires legacy behavior that was never documented. Otherwise this ADR is terminal — orphan rewrites are not reverted.

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

Every decision, with its status This one in the repo