From 9185014022335369a36065c90179ebc3990ab120 Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 10 May 2026 13:03:01 +0200 Subject: [PATCH] =?UTF-8?q?plan:=20design-md-consolidation=204=20(workflow?= =?UTF-8?q?=20/=20cross-reference=20cleanup=20=E2=80=94=20final=20sweep)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ign-md-consolidation-4-workflow-cleanup.md | 678 ++++++++++++++++++ 1 file changed, 678 insertions(+) create mode 100644 docs/plans/2026-05-10-design-md-consolidation-4-workflow-cleanup.md diff --git a/docs/plans/2026-05-10-design-md-consolidation-4-workflow-cleanup.md b/docs/plans/2026-05-10-design-md-consolidation-4-workflow-cleanup.md new file mode 100644 index 0000000..0f3e760 --- /dev/null +++ b/docs/plans/2026-05-10-design-md-consolidation-4-workflow-cleanup.md @@ -0,0 +1,678 @@ +# design-md-consolidation iter 4 — sweep 4: workflow / cross-reference cleanup + +> **Parent spec:** `docs/specs/2026-05-10-design-md-consolidation.md` +> §"Sweep 4 — Workflow / cross-reference cleanup". +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Final pass — fix stale `agents/` path references, strip +workflow detail from the "Verification and correctness" section, +remove the "Recently lifted gates" history paragraph from +"What is not (yet) supported", and audit surviving cross-references +to JOURNAL/skills so each grounds a binding constraint. + +**Architecture:** Documentation-only refactor. Each task targets +one self-contained section. "RED" is a pre-task grep / line-range +read showing the target sites; "GREEN" is the post-task grep +returning empty. No code changes. The drift test +`design_schema_drift.rs` from Sweep 3 must continue to pass — i.e. +no JSON-schema anchor in §"Data model" is touched. + +**Tech Stack:** Edit (`docs/DESIGN.md`); grep; `cargo test +--workspace`; `bench/check.py`; `bench/compile_check.py`. + +**Files this plan modifies:** +- Modify: `docs/DESIGN.md` — four edits across §"Project ecosystem", + §"Verification and correctness", §"What is not (yet) supported", + Pipeline section. +- Append: `docs/JOURNAL.md` — iter entry + milestone-close summary. +- Modify: `docs/roadmap.md` — Sweep 4 `[ ]` → `[x]`; mark milestone + done. + +**Lesson note for sweep 4.** The sweep-1 grep-completeness lesson +is now systemic: every prior sweep's plan-time grep matched the +spec intent. This iter follows the same discipline — composite +acceptance grep at Step 1 of Task 5 covers all four bullet points. + +--- + +## Task 1: Fix Project-ecosystem stale path references + +**Files:** Modify: `docs/DESIGN.md` lines 42-45 (the §Project-ecosystem +bullets for Agents and Docs). + +The `Agents` bullet currently reads `**Agents** (\`agents/\`): … +specialised sub-prompts … See \`agents/README.md\`.` The actual +location is `skills//agents/` (per the skill-system +restructure on 2026-05-09); `agents/README.md` no longer exists at +that path; `skills/README.md` is the current canonical roster. + +The `Docs` bullet currently reads `**Docs** (\`docs/\`): DESIGN.md +(what and why), JOURNAL.md (history).` It does not mention +`roadmap.md` (added 2026-05-10) and does not mention the per- +milestone `specs/` or per-iteration `plans/` directories. + +- [ ] **Step 1: Pre-test — confirm current state** + +```bash +sed -n '42,45p' docs/DESIGN.md +``` + +Expected (4 lines): +``` +- **Agents** (`agents/`): specialised sub-prompts (implementer, + architect, tester, debugger) that form the project's own LLM tooling. + They are a versioned part of the repo. See `agents/README.md`. +- **Docs** (`docs/`): DESIGN.md (what and why), JOURNAL.md (history). +``` + +- [ ] **Step 2: Replace both bullets** + +Edit `docs/DESIGN.md`: +- old: +``` +- **Agents** (`agents/`): specialised sub-prompts (implementer, + architect, tester, debugger) that form the project's own LLM tooling. + They are a versioned part of the repo. See `agents/README.md`. +- **Docs** (`docs/`): DESIGN.md (what and why), JOURNAL.md (history). +``` +- new: +``` +- **Skills** (`skills/`): specialised disciplines + (`brainstorm`, `plan`, `implement`, `audit`, `debug`, + `fieldtest`) plus the agent rosters they dispatch + (`skills//agents/`). They form the project's own + development methodology and are versioned with the codebase. + See `skills/README.md`. +- **Docs** (`docs/`): `DESIGN.md` (canonical state), + `JOURNAL.md` (chronological decisions log), + `roadmap.md` (forward queue), `specs/` (per-milestone design + specs), `plans/` (per-iteration implementation plans). +``` + +The new bullets: +- Skills bullet names the six skills explicitly and points to + `skills//agents/` as the agent location. +- Docs bullet adds `roadmap.md` (forward queue) and the + `specs/` / `plans/` directories. +- "DESIGN.md (canonical state)" reflects the Sweep 3 SoT + inversion ("DESIGN.md is the canonical schema" generalises to + "DESIGN.md is the canonical state of the language"). +- "JOURNAL.md (chronological decisions log)" reflects the user's + 2026-05-10 split (forward queue moved out of JOURNAL into + `roadmap.md`). + +- [ ] **Step 3: Post-test** + +```bash +grep -nE 'agents/[^>]' docs/DESIGN.md +``` + +Expected: 1 match — the new `skills//agents/` reference. No +bare `(\`agents/\`)` ecosystem entry. + +```bash +grep -n 'agents/README.md' docs/DESIGN.md +``` + +Expected: empty (the stale README path is removed). + +```bash +grep -n 'skills/README.md' docs/DESIGN.md +``` + +Expected: 1 match (the new pointer). + +- [ ] **Step 4: Commit** + +```bash +git add docs/DESIGN.md +git commit -m "design-md-consolidation 4.1: fix Project-ecosystem stale agents/ path; expand Docs bullet to name roadmap.md + specs/ + plans/" +``` + +--- + +## Task 2: Strip workflow detail from Verification section + +**Files:** Modify: `docs/DESIGN.md` line 1966 (item 6 of the +"Verification and correctness" numbered list). + +Item 6 currently reads: +``` +6. **Rustdoc cleanliness**: `cargo doc --no-deps` runs warning-free. + Maintained by the `ailang-docwriter` agent; fixing a + rustdoc warning is part of the iteration that introduced it, not a follow-up. +``` + +The `ailang-docwriter` agent is a workflow detail that lives in +`skills/audit/agents/`. The verification contract (rustdoc clean ++ no follow-up) is timeless and stays. The agent assignment is +SoT-located in the skills directory. + +- [ ] **Step 1: Pre-test — confirm current state** + +```bash +grep -n 'ailang-docwriter' docs/DESIGN.md +``` + +Expected: 1 match at the line described above. + +- [ ] **Step 2: Strip the agent reference** + +Edit: +- old: +``` +6. **Rustdoc cleanliness**: `cargo doc --no-deps` runs warning-free. + Maintained by the `ailang-docwriter` agent; fixing a + rustdoc warning is part of the iteration that introduced it, not a follow-up. +``` +- new: +``` +6. **Rustdoc cleanliness**: `cargo doc --no-deps` runs warning-free. + Fixing a rustdoc warning is part of the iteration that + introduced it, not a follow-up. +``` + +The substantive contract (warning-free + fix-in-iteration) survives; +only the agent-assignment workflow detail is cut. + +- [ ] **Step 3: Post-test** + +```bash +grep -n 'ailang-docwriter' docs/DESIGN.md +``` + +Expected: empty. + +```bash +grep -n 'Fixing a rustdoc warning is part of the iteration' docs/DESIGN.md +``` + +Expected: 1 match (the surviving rule). + +- [ ] **Step 4: Commit** + +```bash +git add docs/DESIGN.md +git commit -m "design-md-consolidation 4.2: strip ailang-docwriter agent workflow detail from Verification section; rule survives" +``` + +--- + +## Task 3: Remove "Recently lifted gates" paragraph + +**Files:** Modify: `docs/DESIGN.md` lines 1971-1984 (the prose +paragraph at the start of §"What is not (yet) supported", before +the bullet list of unsupported features). + +The current opener reads: +``` +Snapshot of the current boundary. Items move out of this list +as iterations land; the JOURNAL records when. Recently +**lifted** gates that used to live here: cross-module ADTs (via qualified `module.Type` / `module.Ctor` references in +both `(con ...)` and `(term-ctor ...)` / `(pat-ctor ...)` positions); +GC for ADT boxes, lambda envs, and closure pairs (Boehm conservative +collector, see Decision 9); nested constructor +sub-patterns inside `match` (via the desugar pass); +literal sub-patterns inside a Ctor pattern (the +desugar pass rewrites every `Pattern::Lit` to a `Term::If` on `==`, +both at the top level of an arm and inside a Ctor sub-pattern); +`==` extended from Int-only to a polymorphic +`forall a. (a, a) -> Bool` over `Int`/`Bool`/`Str`/`Unit` (codegen +monomorphises and dispatches on the +resolved arg type; ADT/Fn arg types are rejected at codegen). +``` + +This paragraph contains: +- A boundary-snapshot lead-in (state-only — keep, possibly tightened). +- The "Recently lifted gates" enumeration — pure history; the + features are now part of the supported list further down. Remove. + +- [ ] **Step 1: Pre-test — locate the paragraph** + +```bash +grep -n 'Recently' docs/DESIGN.md +``` + +Expected: 1 match around line 1972. + +```bash +grep -n '^## What is not (yet) supported' docs/DESIGN.md +``` + +Expected: 1 match around line 1969. + +Read the paragraph: +```bash +sed -n '1969,1985p' docs/DESIGN.md +``` + +- [ ] **Step 2: Replace the opener** + +Edit: +- old (the whole multi-sentence opener): +``` +Snapshot of the current boundary. Items move out of this list +as iterations land; the JOURNAL records when. Recently +**lifted** gates that used to live here: cross-module ADTs (via qualified `module.Type` / `module.Ctor` references in +both `(con ...)` and `(term-ctor ...)` / `(pat-ctor ...)` positions); +GC for ADT boxes, lambda envs, and closure pairs (Boehm conservative +collector, see Decision 9); nested constructor +sub-patterns inside `match` (via the desugar pass); +literal sub-patterns inside a Ctor pattern (the +desugar pass rewrites every `Pattern::Lit` to a `Term::If` on `==`, +both at the top level of an arm and inside a Ctor sub-pattern); +`==` extended from Int-only to a polymorphic +`forall a. (a, a) -> Bool` over `Int`/`Bool`/`Str`/`Unit` (codegen +monomorphises and dispatches on the +resolved arg type; ADT/Fn arg types are rejected at codegen). +``` +- new: +``` +Snapshot of the current boundary. Items move out of this list +as iterations land; the JOURNAL records when. +``` + +The first sentence (boundary snapshot lead-in) and the JOURNAL +attribution stay; everything after the period (the "Recently +lifted gates" enumeration) is removed. The bullet list that +follows the opener is unchanged — that's the actual +"not yet supported" content. + +- [ ] **Step 3: Post-test** + +```bash +grep -n 'Recently' docs/DESIGN.md +``` + +Expected: empty (or only legitimate uses unrelated to this +paragraph; verify each remaining hit, if any). + +```bash +grep -n 'lifted gates' docs/DESIGN.md +``` + +Expected: empty. + +```bash +grep -n 'Snapshot of the current boundary' docs/DESIGN.md +``` + +Expected: 1 match (the surviving lead-in). + +- [ ] **Step 4: Commit** + +```bash +git add docs/DESIGN.md +git commit -m "design-md-consolidation 4.3: drop 'Recently lifted gates' history paragraph from §What-is-not-yet-supported" +``` + +--- + +## Task 4: Cross-reference audit (JOURNAL queue → roadmap) + +**Files:** Modify: `docs/DESIGN.md` line 1909 (Pipeline section, +end of allocator backends paragraph). + +Cross-reference inventory after Tasks 1-3: + +| Site | Reference | Disposition | +|------|-----------|-------------| +| line 811 | `(current ratio recorded in JOURNAL bench entries)` | KEEP — grounds the closure-chain ratio claim. | +| line 842 | `(JOURNAL bench notes)` | KEEP — grounds the tracing-GC argument. | +| line 1505 | `(\`bench/mono_dispatch.py\` and the corresponding JOURNAL bench-notes entry record the measured ratios)` | KEEP — grounds the mono-vs-vdisp claim. | +| line 1909 | `see the JOURNAL queue` | UPDATE — the JOURNAL queue moved to `docs/roadmap.md` on 2026-05-10; the JOURNAL is now decisions-log only. | + +The first three are bench-evidence pointers — each grounds a +binding empirical claim ("closure-chain ratio", "tracing GC +allocate-path overhead", "mono-vs-vdisp ratio"). They stay. + +The fourth is a stale forward-queue pointer. + +- [ ] **Step 1: Pre-test — confirm sites** + +```bash +grep -nE 'JOURNAL queue|JOURNAL bench' docs/DESIGN.md +``` + +Expected: 4 matches — three bench pointers (KEEP) and one queue +pointer (UPDATE). + +```bash +grep -n 'see the JOURNAL queue' docs/DESIGN.md +``` + +Expected: 1 match at line ~1909. + +- [ ] **Step 2: Update the queue pointer** + +Edit: +- old: `retirement; see the JOURNAL queue.` +- new: `retirement; see \`docs/roadmap.md\` for the active queue.` + +- [ ] **Step 3: Post-test** + +```bash +grep -n 'JOURNAL queue' docs/DESIGN.md +``` + +Expected: empty. + +```bash +grep -n 'see \`docs/roadmap.md\` for the active queue' docs/DESIGN.md +``` + +Expected: 1 match. + +```bash +grep -nE 'JOURNAL bench' docs/DESIGN.md +``` + +Expected: 3 matches (the three bench-pointer KEEPs from the +inventory). + +- [ ] **Step 4: Final cross-reference review** + +Walk every surviving JOURNAL/skill reference in `docs/DESIGN.md`: + +```bash +grep -nE 'JOURNAL|skills/|docs/roadmap\.md' docs/DESIGN.md +``` + +Expected matches per the inventory above (3 KEEP bench pointers + +1 new roadmap pointer + 1 from the Project ecosystem Docs bullet ++ 1 from the Skills bullet). No stale references; each surviving +reference grounds a binding claim or names an SoT. + +- [ ] **Step 5: Commit** + +```bash +git add docs/DESIGN.md +git commit -m "design-md-consolidation 4.4: cross-ref audit — JOURNAL queue → roadmap.md; bench pointers retained as binding-evidence anchors" +``` + +--- + +## Task 5: Final validation + JOURNAL entry + milestone close + +**Files:** Read: `docs/DESIGN.md`. Append: `docs/JOURNAL.md`. +Modify: `docs/roadmap.md`. + +This task closes Sweep 4 AND the design-md-consolidation milestone. +The JOURNAL entry has two parts: (a) the iter entry per the usual +template, (b) a milestone-close summary capturing the cumulative +state across all four sweeps. + +- [ ] **Step 1: Composite Sweep-4 acceptance grep** + +```bash +grep -nE '\(\`agents/\`\)|agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue' docs/DESIGN.md +``` + +Expected: empty. + +```bash +grep -n 'skills/README.md' docs/DESIGN.md +``` + +Expected: 1 match (Project-ecosystem Skills bullet). + +- [ ] **Step 2: Sweeps 1+2+3 invariants stay clean (regression check)** + +```bash +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 +``` + +Expected: empty (Sweep-1). + +```bash +grep -nE 'REVERTED|preserved for the audit trail|Migration plan|[Oo]riginally framed|original rationale|empirically-grounded version|A future (iter|iteration|milestone|Prelude) may|A future iter that|a (later|future) iter(ation)? \(deferred\)|Concrete design deferred' docs/DESIGN.md +``` + +Expected: empty (Sweep-2). + +```bash +grep -nE '^\s*(struct |enum |pub (struct|enum|fn))' docs/DESIGN.md +``` + +Expected: empty (Sweep-3 part A — no Rust type defs). + +```bash +grep -n 'whenever the two disagree\|ast.rs is the source of truth' docs/DESIGN.md +``` + +Expected: empty (Sweep-3 part B — old SoT disclaimer gone). + +```bash +grep -n 'This section is the canonical schema' docs/DESIGN.md +``` + +Expected: 1 match (Sweep-3 canonical-schema sentence still present). + +- [ ] **Step 3: Drift test stays green** + +```bash +cargo test -p ailang-core --test design_schema_drift 2>&1 | tail -5 +``` + +Expected: `test result: ok. 7 passed; 0 failed`. + +- [ ] **Step 4: Workspace tests stay green** + +```bash +cargo test --workspace 2>&1 | grep -E "test result:|FAILED" | grep -v "0 failed" | head -10 +``` + +Expected: empty (no FAILED). + +- [ ] **Step 5: Bench gates stay green** + +```bash +python3 bench/check.py 2>&1 | tail -3 +python3 bench/compile_check.py 2>&1 | tail -3 +``` + +Expected: each summary `0 regressed`. + +- [ ] **Step 6: Append JOURNAL iter entry + milestone-close summary** + +Append two paragraphs to `docs/JOURNAL.md`. The first is the +standard iter entry; the second is the milestone-close summary. + +Template (adjust specifics to actual outcome — record actual +DESIGN.md line count and any cross-reference inventory specifics): + +```markdown + +## 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//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). + +Edits: + +- §"Project ecosystem" `Agents` bullet → `Skills` bullet: + names the six skills (`brainstorm`, `plan`, `implement`, + `audit`, `debug`, `fieldtest`) and points to + `skills//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: "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.` + +Cross-reference audit results: +- 3 JOURNAL bench-notes pointers retained as + binding-evidence anchors (closure-chain ratio at line 811; + tracing-GC argument at line 842; mono-vs-vdisp ratio at + line 1505 region). +- 1 `docs/roadmap.md` pointer added (Pipeline section). +- 1 `skills/README.md` pointer added (Project-ecosystem + Skills bullet). +- All other surviving references (agent file names in + contexts where they ground a binding claim) verified + in-scope. + +Acceptance: +- Composite Sweep-4 grep + `grep -nE '\(\`agents/\`\)|agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue' docs/DESIGN.md` + empty. +- Sweep-1 + Sweep-2 + Sweep-3 invariants stay empty. +- `design_schema_drift` 7 tests pass. +- `cargo test --workspace` 0 FAILED. +- `bench/check.py` + `bench/compile_check.py` 0 regressed. +- DESIGN.md size: lines (record actual; expected ≈ 2120-2125). + +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 + +## 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 (≈ 2120 lines, +−6%) 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//SKILL.md` + `skills//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):** 4 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`. + +Open questions queued for follow-up: + +- Drift test currently 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. + +- 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 onward. +- One real schema-vs-doc bug was surfaced and closed inside + the milestone (Sweep 3 `"kind": "ClassDef"` → + `"kind": "class"`). The drift test was created with the + bug in scope — a guard that was supposed to be GREEN on + first run instead surfaced a pre-existing inconsistency. + This is the value the test was designed to provide. +- Quality reviewer's nit-level findings (trailing + whitespace, dangling cross-references, doc-comment + task-tag prefixes) closed inline as orchestrator edits + where mechanical, dispatched as fixup commits where + judgment was needed. +``` + +- [ ] **Step 7: Update roadmap.md** + +Edit `docs/roadmap.md`: +- old: +``` +- [~] **\[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 +``` +- new: +``` +- [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. +``` + +The four sub-entries collapse to a one-line milestone-done +record. The roadmap convention (per the file's own preamble) +allows finished entries to "stay briefly for context, then is +removed (with a one-line mirror in `docs/JOURNAL.md`)" — so the +explicit mirror is the JOURNAL milestone-close paragraph. + +- [ ] **Step 8: Commit** + +```bash +git add docs/JOURNAL.md docs/roadmap.md +git commit -m "design-md-consolidation 4: journal entry + milestone close + roadmap mark done" +```