roadmap: close DESIGN.md->design/ ([~]->[x]); WhatsNew: design-spec-restructure done-state

docs/WhatsNew.md

@@ -234,3 +234,7 @@ It is proven, not asserted: each worker's result is bit-for-bit identical to an
 Driving the kernel from many threads at once surfaced one real concurrency gap in the runtime's internal bookkeeping — caught by the leak check, diagnosed to root cause, fixed, and re-verified — so the safety guarantee has teeth rather than being a claim on paper. Nothing about how programs are written, type-checked, or compiled changed; only host-side glue and one runtime-internal counter. The build was reviewed clean; the one flagged benchmark number was traced to its root cause and is an accepted, documented side effect of that necessary concurrency fix on the transitional memory path, with the primary path unaffected.
 
 This closes the multi-step arc that began with making a single numeric function callable from a host: it is now a real, concurrent, data-fed compute kernel. The next direction — whether to add a batch/array crossing to amortise the now-measured per-call cost — is a fresh decision, now driven by a real measurement rather than speculation.
+
+## 2026-05-19 — Design spec restructured into a typed ledger
+
+The 3000-line single design document is gone. The design spec is now a "design/" directory: a typed INDEX as the single entry point, separate contract files (the binding, test-linked rules), and model write-ups; the historical "why we chose/rejected X" prose moved into the journals. A self-checking test now keeps history and rationale from leaking back into the contract files, so the part of the spec read every cycle stays small and addressable. Everything that pointed at the old file — build tooling, the review reading-lists, and the compiler hints that tell the author which spec section to read — now points at the new layout. No language or behaviour change; documentation structure only. The build was reviewed clean and the one drift found (migrated history prose sitting in a few contract files) was fixed in the same pass; benchmarks were proven byte-for-byte unaffected.

docs/roadmap.md

@@ -381,15 +381,39 @@ work progresses.
 
 ## P2 — Medium-term
 
-- [~] **\[milestone\]** DESIGN.md → `design/` — role-split into a
-  typed contract ledger + per-model whitepapers, decision-records
-  rehomed to `docs/journals/`. `docs/DESIGN.md` is one 2905-line
-  file doing three different jobs for three different consumers
-  with three different lifetimes; the line count is the symptom of
-  role-conflation, not of mess. Replace it with a `design/`
-  directory split along the consumer/lifetime axis, with a typed
-  `design/INDEX.md` as the sole addressable spine and primary
-  entry point.
+- [x] **\[milestone\]** DESIGN.md → `design/` — CLOSED 2026-05-19.
+  The 3020-line `docs/DESIGN.md` is **deleted** (clean cut, no
+  stub) and replaced by the `design/` ledger: `design/INDEX.md`
+  (sole addressable spine, typed Contracts+Models tables with
+  polymorphic links — prose file OR authoritative source `//!`),
+  14 `design/contracts/*.md` test-linked invariants + 3
+  source-link-only contracts (mangling/env-construction/
+  qualified-xref — code is SoT), 5 `design/models/*.md`
+  whitepapers, and `docs/journals/2026-05-19-design-decision-records.md`
+  (the relitigation-guard archive). RED-first
+  `design_index_pin.rs` 4-clause anti-regrowth spine; clause-3 is
+  a hand-rolled **faithful Sweep-1 superset** so the in-code hard
+  gate enforces the honesty spirit (clause-3 GREEN ⟹ Sweep-1
+  clean in contracts/). Build-atomic by task ordering (the only
+  compile-time consumer's `include_str!` retargeted before the
+  deletion). Every live `DESIGN.md` reference — 4 executables, 2
+  diagnostics + 2 E2Es, ~12 agent reading lists, 5 SKILL bodies,
+  CLAUDE.md, README, ~25 code/C/.ail/spec comment xrefs —
+  retargeted in lockstep; the honesty rule rewritten to name the
+  new rationale home. Process: spec `a64b2cc`/`314e5e4`
+  (grounding-check PASS ×2) → plan `deeffb1` → iter .1 `176821c`
+  (DONE 9/9) → `audit` `2ba5e16` (architect drift_found
+  `[medium]`+`[low]`, relocation byte-faithful; bencher
+  causally-exonerated DECISIVE on byte-identical IR+binaries,
+  baseline pristine — M2/M3/M5 disposition) → tidy `f2cdd67`/
+  `f683f1a` (DONE 7/7; the audit Resolution mechanism+scope
+  corrected on planning-time evidence after a correctly-BLOCKED
+  plan defect — the "two+ defects ⇒ fix the upstream artifact"
+  discipline, not a third patch). No fieldtest (zero
+  authoring-surface change — reasoned exclusion). Stays briefly
+  for context; remove once stale (full record in
+  `docs/journals/INDEX.md`). Original decided-shape rationale
+  retained below for context until pruned.
 
   **Motivation.** The just-closed `docs-honesty-lint` milestone is
   the proof this is not a cleanup problem: it ran a full docs pass
@@ -474,12 +498,13 @@ work progresses.
   DESIGN.md. Brainstorm hard-gate before any plan/code — it
   rewrites enforced invariants and agent contracts.
   - context: spec `docs/specs/2026-05-19-design-md-rolesplit.md`
-    (grounding-check PASS 13/13, one re-dispatch after a corrected
-    commitment-4 pin-status claim); 2026-05-18 chat
-    (DESIGN.md-management dialogue — six-turn convergence:
-    role-conflation diagnosis, three-job split axis, "let the code
-    speak" principle, qmd rejection, blast-radius sequencing).
-    In flight — ABI-arc sequencing blocker cleared by M5 close.
+    (incl. the Boss-adjudicated relocation Appendix; grounding-check
+    PASS ×2); audit `docs/journals/2026-05-19-audit-design-md-rolesplit.md`;
+    iter journals `2026-05-19-iter-design-md-rolesplit.{1,tidy}.md`;
+    `docs/journals/2026-05-19-design-decision-records.md`; origin
+    2026-05-18 chat (DESIGN.md-management dialogue — six-turn
+    convergence). CLOSED — audited + drift-resolved; hard gate
+    enforces the honesty spirit.
 
 - [ ] **\[milestone\]** Flat array/slice primitive — performance
   follow-up to the Embedding ABI arc, *not* a capability gap.