design-md-consolidation 1: journal entry + roadmap sweep-1 closed

This commit is contained in:
2026-05-10 12:17:35 +02:00
parent 172b974c9a
commit 7863f73b84
2 changed files with 108 additions and 2 deletions
+107
View File
@@ -12430,3 +12430,110 @@ Carried-debt status (after this iter):
Milestone-22 carried debt + the queued tipping-point observation
are now both closed. Next milestone targets remain orchestrator's
call.
## 2026-05-10 — Iteration design-md-consolidation 1: history-anchor sweep
First iteration of the milestone defined in
`docs/specs/2026-05-10-design-md-consolidation.md`. Sweep 1 closes
the "history anchors in DESIGN.md" item: every iter tag (`Iter Nx`,
bare `Nx`, `pre-Nx`, `Nx sketch`, `21'g`), family tag (`Family 20`),
date anchor (`2026-MM-DD`), status marker (`**Status: …**`), and
historical bench data-point that anchored the document to a specific
moment is removed or condensed. DESIGN.md now reads as a state-only
document for these classes of anchors; the *narratives* of how
decisions changed (Decision 9's three-frame story, Decision 11's
mono-vs-vdisp correction, Decision 7's REVERTED body, the "Migration
plan" in Decision 10) remain in their narrative form this iter and
are condensed in sweep 2.
Sites stripped (counts at iter start, full closure on commit):
- Iter tags (`Iter [0-9]+[a-z]?(\.[0-9]+)?` strict): 93 sites (Task 4).
- Bare iter-id residues (`pre-Nx`, `Nx sketch`, plain `Nx` like `14d`,
`15a`, `20f`, `22a`, `22b`, `22c`, `18g.1`, `16b.2`): 4 + ~16 sites
(Task 4 fixups).
- Family tags: 4 sites (Task 2).
- Date anchors: 13 sites (Task 3).
- Status markers (`**Status: …**`): 4 sites (Task 1).
- Bench data-points: 12 sites — 5 KEPT (the 1.3× retirement target
and ±15% tolerance, which are policy contracts), 7 REMOVED or
CONDENSED (Task 5).
Specific anchor examples discarded (representative):
- Decision 6 opener: `**Status: shipped.** Form (A) was chosen in
Iter 14b and implemented as` → `Form (A) is implemented as`.
- Decision 9 opener: `**Status: half-retirement as of 2026-05-09.**
Originally framed (2026-05-07) as "transitional Boehm…"` →
`Originally framed as "transitional Boehm…"` (the
narrative-of-changes paragraph is sweep-2 territory).
- Decision 10 opener: `**Committed 2026-05-08, after the GC bench
showed Boehm contributing ~60% of runtime…` → `**The GC bench
showed Boehm contributing a substantial fraction of runtime
(bench notes in JOURNAL).`
- Decision 11 opener: `**Committed 2026-05-09 (Iter 22a), as the
design pass that gates 22b implementer work.**` → `**The design
pass that gates implementer work.**`
Deliberate exception:
`docs/specs/2026-05-09-22-typeclasses.md` (line 1747) — date-prefixed
spec filename, kept verbatim because the on-disk file uses that
prefix and renaming would lose git history. The composite
acceptance grep masks paths beginning with `docs/`.
Acceptance:
- composite grep
`grep -nE 'Iter [0-9]+[a-z]?(\.[0-9]+)?|Family [0-9]+|^[^/]*2026-[0-9]{2}-[0-9]{2}|\*\*Status: |pre-[0-9]+[a-z]?|[0-9]+[a-z]? sketch|21.g' docs/DESIGN.md`
returns empty.
- bench-data residue grep returns only 5 KEEP-class lines (1.3× and
±15%).
- `cargo test --workspace` 0 FAILED across all 23 test binaries.
- `bench/check.py` 0 regressed (63 metrics, 2 improved beyond
tolerance, 61 stable); `bench/compile_check.py` 0 regressed (24
metrics, 24 stable).
- DESIGN.md size: 2262 → 2253 lines (small net reduction; sweeps 2-4
expected to reduce further).
The 1.3× Boehm-retirement target and the ±15% closure-band tolerance
are KEPT verbatim — they are policy contracts, not historical
measurements. The historical bench data-points that grounded those
targets (60% allocate-path overhead; 2.8× malloc slowdown; 4.14×
rc/bump on closure-chain; 3.31x / 4.00x mono-vs-vdisp; 1.000x Zen 3
saturated-predictor anchor) are removed from DESIGN.md; their values
remain in JOURNAL bench entries (`bench/run.sh` baseline records,
mono-dispatch micro-bench entry).
Tasks (commit subjects):
- design-md-consolidation 1.1: drop **Status:** markers from DESIGN.md
- design-md-consolidation 1.2: drop Family-N tags from DESIGN.md
- design-md-consolidation 1.2 fixup: trim trailing whitespace on DESIGN.md:33
- design-md-consolidation 1.3: drop date anchors from DESIGN.md
- design-md-consolidation 1.3 fixup: repair two date-strip quality issues
- design-md-consolidation 1.4: drop Iter-N tags from DESIGN.md
- design-md-consolidation 1.4 fixup: strip non-Iter-N iter anchors (14b sketch, pre-19b, pre-22a)
- design-md-consolidation 1.4 fixup: strip bare iter-id references (~16 sites)
- design-md-consolidation 1.4 nit: deduplicate 'fixture' word in user-class parenthetical
- design-md-consolidation 1.5: condense historical bench data-points in DESIGN.md
- design-md-consolidation 1.5 fixup: untangle line 863 run-on, deduplicate JOURNAL attribution, idiomatic 'larger still'
Carried into sweep 2: Decision 7's body (still present, awaiting
removal), Decision 9's "Originally framed … then re-framed …
revision flips" narrative, Decision 10's "Migration plan", Decision
11's "Why mono, not virtual dispatch (the empirically-grounded
version)" correction history, and the "future iter may"
speculations.
Process note: the plan's strict grep `Iter [0-9]+[a-z]?(\.[0-9]+)?`
caught 93 of the iter anchors but missed 20 bare-iter-id residues
(`pre-19b`, `14b sketch`, `14d`, `14e`, `15a`, `16b.2`, `18g.1`,
`20f`, `22a`, `22b`, `22b.4b`, `22c`). The implementer correctly
flagged these as "known debt" within the strict-grep boundary; the
orchestrator widened scope post-implementer-DONE because the spec's
intent (`all iter tags removed`) was clearly broader than the
plan's regex. Lesson for sweep 2-4 plan-writing: the acceptance
grep must match the spec intent, not just one specific anchor
form. Future plans for sweeps 2-4 will fold all anchor variants
(literal Iter-N, bare Nx, prefixed `pre-Nx`, possessive `Nx's`,
suffix `Nx sketch`, etc.) into one composite grep at plan-time.
+1 -2
View File
@@ -39,8 +39,7 @@ work progresses.
data-model hardening, workflow / cross-reference cleanup).
- context: `docs/specs/2026-05-10-design-md-consolidation.md`
- sub-entries:
- [~] Sweep 1 — remove history anchors
(`docs/plans/2026-05-10-design-md-consolidation-1-history-anchors.md`)
- [x] Sweep 1 — remove history anchors
- [ ] Sweep 2 — REVERTED + migration plans out
- [ ] Sweep 3 — schema SoT inversion + data-model hardening
- [ ] Sweep 4 — workflow / cross-reference cleanup