AILang/docs/plans/0015-design-md-consolidation-4-workflow-cleanup.md

# design-md-consolidation iter 4 — sweep 4: workflow / cross-reference cleanup

> **Parent spec:** `docs/specs/0004-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/0004-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/0004-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/0004-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"
```