design-md-consolidation 4: journal entry + milestone close + roadmap mark done

docs/JOURNAL.md

@@ -12759,3 +12759,211 @@ Process notes:
   the ClassDef/class class of bug structurally rather than
   through grep-presence + spot inspection. Out of scope for
   iter 3; queued.
+
+## 2026-05-10 — Iteration design-md-consolidation 4: workflow / cross-reference cleanup
+
+Fourth and final iteration of the milestone defined in
+`docs/specs/2026-05-10-design-md-consolidation.md`. Sweep 4
+closes the "workflow / cross-reference cleanup" item: the stale
+`agents/` ecosystem entry is replaced with a `Skills` entry
+pointing to `skills/<name>/agents/`; the workflow-detail
+attribution to `ailang-docwriter` in §"Verification and
+correctness" is dropped (the rule survives, the agent assignment
+lives in skills SoT); the "Recently lifted gates" history
+paragraph is removed from §"What is not (yet) supported"; the
+stale `see the JOURNAL queue` Pipeline pointer is updated to
+`docs/roadmap.md` (per the user's 2026-05-10 split that moved the
+forward queue out of JOURNAL); two additional residues caught by
+the cross-reference audit are closed in a fixup ("Sharpened later
+the same day" temporal anchor in Decision 10's opener — a
+Sweep-2 missed pattern; supplementary "see closure conversion in
+JOURNAL" pointer in the Term::Lam description — not load-bearing).
+
+Edits:
+
+- §"Project ecosystem" `Agents` bullet → `Skills` bullet: names
+  the six skills (`brainstorm`, `plan`, `implement`, `audit`,
+  `debug`, `fieldtest`) and points to `skills/<name>/agents/` as
+  the agent location; references `skills/README.md` instead of
+  the (now non-existent) `agents/README.md`.
+- §"Project ecosystem" `Docs` bullet expanded: adds `roadmap.md`
+  (forward queue), `specs/` (per-milestone design specs),
+  `plans/` (per-iteration implementation plans), and tags
+  DESIGN.md as "canonical state" + JOURNAL.md as "chronological
+  decisions log".
+- §"Verification and correctness" item 6: `ailang-docwriter`
+  agent attribution stripped; the "rustdoc warnings are fixed in
+  the iteration that introduced them, not as follow-up" rule
+  survives.
+- §"What is not (yet) supported" opener: the "Recently lifted
+  gates that used to live here: cross-module ADTs … `==`
+  polymorphism" enumeration removed. The first sentence
+  ("Snapshot of the current boundary. Items move out of this list
+  as iterations land; the JOURNAL records when.") survives as a
+  state-only lead-in.
+- Pipeline section: `retirement; see the JOURNAL queue.` →
+  `retirement; see \`docs/roadmap.md\` for the active queue.`
+- Decision 10 opener (fixup): `Sharpened later the same day:` →
+  removed; "was extended" → "is extended" (present-tense state).
+- Term::Lam description (fixup): `(see closure conversion in
+  JOURNAL)` parenthetical removed — the binding claim ("free
+  variables of its body are captured from the enclosing scope")
+  is self-sufficient.
+
+Cross-reference audit final inventory (post-fixup):
+
+- 3 JOURNAL bench-notes pointers retained as binding-evidence
+  anchors:
+  - line ~786 (Decision 10 opener: "bench notes in JOURNAL")
+  - line ~817 (closure-chain ratio: "current ratio recorded in
+    JOURNAL bench entries")
+  - line ~848 (tracing-GC argument: "JOURNAL bench notes")
+  - line ~1511 (mono-vs-vdisp ratio: "JOURNAL bench-notes entry
+    record the measured ratios")
+- 1 JOURNAL rationale pointer retained (line ~1611,
+  higher-rank-polymorphism prohibition: "rationale recorded in
+  JOURNAL").
+- 1 `docs/roadmap.md` pointer added (Pipeline section).
+- 1 `skills/README.md` pointer added (Project-ecosystem Skills
+  bullet).
+- 1 `skills/<name>/agents/` pointer added (Project-ecosystem
+  Skills bullet).
+- §"Project ecosystem" Docs bullet names DESIGN.md / JOURNAL.md /
+  roadmap.md / specs/ / plans/ as the doc family.
+- §"What is not (yet) supported" lead-in retains
+  "the JOURNAL records when" as a binding pointer to where each
+  feature's ship-date lives.
+
+Acceptance:
+
+- composite Sweep-4 grep
+  `grep -nE '\(\`agents/\`\)|agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL' docs/DESIGN.md`
+  empty.
+- Sweep-1 + Sweep-2 + Sweep-3 invariants stay empty (no
+  regression).
+- `cargo test -p ailang-core --test design_schema_drift` 7 tests
+  pass.
+- `cargo test --workspace` 0 FAILED.
+- `bench/check.py` 0 regressed (63 metrics; 4 improved beyond
+  tolerance, 59 stable). `bench/compile_check.py` 0 regressed (24
+  metrics, 24 stable).
+- DESIGN.md size: 2139 → 2132 lines (−7 this sweep, −130
+  cumulatively from 2262 at milestone start).
+
+Tasks (commit subjects):
+
+- design-md-consolidation 4.1: fix Project-ecosystem stale agents/ path; expand Docs bullet to name roadmap.md + specs/ + plans/
+- design-md-consolidation 4.2: strip ailang-docwriter agent workflow detail from Verification section; rule survives
+- design-md-consolidation 4.3: drop 'Recently lifted gates' history paragraph from §What-is-not-yet-supported
+- design-md-consolidation 4.4: cross-ref audit — JOURNAL queue → roadmap.md; bench pointers retained as binding-evidence anchors
+- design-md-consolidation 4.4 fixup: drop 'Sharpened later the same day' temporal anchor + supplementary 'see closure conversion in JOURNAL' pointer
+
+Process note: the cross-reference audit (Task 4) surfaced two
+additional residues — one Sweep-2 missed pattern ("Sharpened
+later the same day") and one not-load-bearing supplementary
+pointer ("see closure conversion in JOURNAL"). Both closed inside
+Sweep 4 via fixup. Audit-as-discovery worked as intended for
+Sweep 4 in the same way it worked for Sweep 3 (the schema-tag
+drift caught by `design_schema_drift.rs`): the closing iter of a
+milestone surfaces residues the earlier iters missed because
+their grep coverage was scoped to specific patterns.
+
+## 2026-05-10 — Milestone close: design-md-consolidation
+
+Four sweeps shipped over a single working day. DESIGN.md
+transitioned from a mixed state/history/workflow document
+(2262 lines) to a state-only specification (2132 lines, −5.7%)
+with three orthogonal SoTs cleanly separated:
+
+- `docs/DESIGN.md` — canonical state + timeless rationale.
+- `docs/JOURNAL.md` — chronological decisions log.
+- `docs/roadmap.md` — forward queue (introduced by user during
+  iter 1; integrated into the role table in iter 4).
+- `skills/<name>/SKILL.md` + `skills/<name>/agents/` — workflow
+  disciplines and agent rosters.
+- `crates/ailang-core/src/ast.rs` — Rust-side projection of
+  DESIGN.md §"Data model" (drift-tested).
+
+What changed across sweeps:
+
+- **Sweep 1 (history anchors):** 11 commits. Removed 93 iter
+  tags + ~16 bare iter-id residues + 4 family tags + 13 date
+  anchors + 4 status markers; condensed 7 of 12 historical bench
+  data-points (5 KEEPs grounded the 1.3× retirement target /
+  ±15% closure-band tolerance policy contracts).
+- **Sweep 2 (REVERTED + migration):** 7 commits. Deleted
+  Decision 7 (Term::If REVERTED block, 32 lines), Decision 10
+  Migration plan (32 lines), Decision 9 narrative-of-changes
+  opener + pre-Decision-9 history paragraphs, Decision 11
+  mono-vs-vdisp correction history; condensed 5 future-iter
+  speculations (1 KEPT as a binding prohibition restructured to
+  assertive form; 4 REMOVED as non-binding aspirations).
+- **Sweep 3 (schema SoT inversion):** 6 commits. Removed 2 Rust
+  code blocks from Decision 10; inverted §"Data model" SoT
+  relationship (DESIGN.md canonical, ast.rs projection, drift
+  test enforces); updated `ast.rs` module doc-comment to
+  bold-emphasise the inversion; created
+  `crates/ailang-core/tests/design_schema_drift.rs` (7 tests,
+  exhaustive match per enum); fixed real schema-vs-doc drift in
+  Decision 11 §"Form-A schema" (`"kind": "ClassDef"` /
+  `"InstanceDef"` → `"kind": "class"` / `"instance"` to match
+  the actual `rename_all = "lowercase"` serde output).
+- **Sweep 4 (workflow / cross-reference cleanup):** 5 commits +
+  1 close. Project-ecosystem Skills/Docs bullets modernised;
+  Verification workflow detail stripped; "Recently lifted gates"
+  history paragraph removed; stale JOURNAL queue pointer
+  updated to `docs/roadmap.md`; two cross-reference-audit
+  residues closed inside the iter via fixup.
+
+Cumulative commit count: 29 commits (4 spec/plan + 25 task /
+fixup / nit / close).
+
+Open questions queued for follow-up:
+
+- **Drift test fidelity widening.** The current
+  `design_schema_drift.rs` guards DESIGN.md text presence, not
+  serde-roundtrip fidelity. A future hardening would round-trip
+  a constructed `Def` value through `serde_json::to_value` and
+  assert the emitted JSON matches one of DESIGN.md's anchors
+  literally — that catches the ClassDef/class class of bug
+  structurally rather than through grep-presence + spot
+  inspection. Out of scope for this milestone; queued.
+- **Architect agent iron-law extension.** The architect agent's
+  drift-review iron law could be extended with the standing
+  greps from Sweeps 1, 2, and 4 so that future commits to
+  DESIGN.md cannot reintroduce history anchors / REVERTED
+  narratives / workflow detail without the architect flagging
+  it. Out of scope for this milestone; queued.
+
+Process retrospective:
+
+- The Sweep-1 lesson ("plan-time grep must match spec intent")
+  held across Sweeps 2-4. No fixup commits were required for
+  *missed* anchor variants in Sweeps 2, 3, or 4 — the variants
+  the spec named were all caught by their respective composite
+  greps on the first attempt.
+- Three real bugs / residues were surfaced and closed inside the
+  milestone, each by a different mechanism:
+  - Sweep 1 closing: bare iter-id forms ("pre-19b", "14d", "22a"
+    etc.) — caught by the implementer's "known debt" note +
+    orchestrator's widened grep.
+  - Sweep 3 closing: schema-tag drift `ClassDef`/`InstanceDef`
+    vs serde-emitted `class`/`instance` — caught by the new
+    drift test created in the same iter.
+  - Sweep 4 closing: "Sharpened later the same day" +
+    "(see closure conversion in JOURNAL)" — caught by the
+    cross-reference audit walk-through in Task 4.
+  Each closure was an in-scope expansion of the discovering
+  iter, not deferred debt.
+- Quality reviewer's nit-level findings (trailing whitespace,
+  dangling cross-references, doc-comment task-tag prefixes)
+  were closed inline as orchestrator edits where mechanical, or
+  dispatched as fixup commits where judgment was needed. The
+  two-stage review pattern (spec compliance → code quality)
+  caught residues that a single-stage review would have missed.
+- DESIGN.md size reduction (130 lines, 5.7%) is observation, not
+  target. The substantive change is the *structure* — three
+  axes cleanly separated, no mixed framing, drift-test enforcing
+  the schema axis. A reader can now trust DESIGN.md as
+  state-only without filtering history-vs-state-vs-workflow on
+  every paragraph.

docs/roadmap.md

@@ -33,16 +33,13 @@ work progresses.
 
 ## P0 — In flight
 
-- [~] **\[milestone\]** design-md-consolidation — `docs/DESIGN.md`
-  becomes a state-only specification across four thematic sweeps
-  (history anchors out, migration plans out, schema-SoT inversion +
-  data-model hardening, workflow / cross-reference cleanup).
-  - context: `docs/specs/2026-05-10-design-md-consolidation.md`
-  - sub-entries:
-    - [x] Sweep 1 — remove history anchors
-    - [x] Sweep 2 — REVERTED + migration plans out
-    - [x] Sweep 3 — schema SoT inversion + data-model hardening
-    - [ ] Sweep 4 — workflow / cross-reference cleanup
+- [x] **\[milestone\]** design-md-consolidation — `docs/DESIGN.md`
+  is now a state-only specification across four thematic sweeps
+  (history anchors out, REVERTED + migration plans out,
+  schema-SoT inversion + data-model hardening, workflow /
+  cross-reference cleanup). Closed 2026-05-10.
+  - context: `docs/specs/2026-05-10-design-md-consolidation.md`,
+    JOURNAL milestone-close entry of same date.
 
 ## P1 — Next