Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

plan: design-md-consolidation 4 (workflow / cross-reference cleanup — final sweep)

Browse Source
This commit is contained in:
Brummel
2026-05-10 13:03:01 +02:00
parent af2064af6e
commit 9185014022
1 changed files with 678 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-05-10-design-md-consolidation-4-workflow-cleanup.md
+678
View File
@@ -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/<name>/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/<name>/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/<name>/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/<name>/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/<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).
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: "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: <X> 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/<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):** 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"
```