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 isskills//agents/(per the skill-system restructure on 2026-05-09);agents/README.mdno 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 mentionroadmap.md(added 2026-05-10) and does not mention the per- milestonespecs/or per-iterationplans/` directories.

• Step 1: Pre-test — confirm current state

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

grep -nE 'agents/[^>]' docs/DESIGN.md

Expected: 1 match — the new skills/<name>/agents/ reference. No bare (\agents/`)` ecosystem entry.

grep -n 'agents/README.md' docs/DESIGN.md

Expected: empty (the stale README path is removed).

grep -n 'skills/README.md' docs/DESIGN.md

Expected: 1 match (the new pointer).

• Step 4: Commit

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

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

grep -n 'ailang-docwriter' docs/DESIGN.md

Expected: empty.

grep -n 'Fixing a rustdoc warning is part of the iteration' docs/DESIGN.md

Expected: 1 match (the surviving rule).

• Step 4: Commit

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

grep -n 'Recently' docs/DESIGN.md

Expected: 1 match around line 1972.

grep -n '^## What is not (yet) supported' docs/DESIGN.md

Expected: 1 match around line 1969.

Read the paragraph:

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

grep -n 'Recently' docs/DESIGN.md

Expected: empty (or only legitimate uses unrelated to this paragraph; verify each remaining hit, if any).

grep -n 'lifted gates' docs/DESIGN.md

Expected: empty.

grep -n 'Snapshot of the current boundary' docs/DESIGN.md

Expected: 1 match (the surviving lead-in).

• Step 4: Commit

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

grep -nE 'JOURNAL queue|JOURNAL bench' docs/DESIGN.md

Expected: 4 matches — three bench pointers (KEEP) and one queue pointer (UPDATE).

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

grep -n 'JOURNAL queue' docs/DESIGN.md

Expected: empty.

grep -n 'see \`docs/roadmap.md\` for the active queue' docs/DESIGN.md

Expected: 1 match.

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:

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

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

grep -nE '\(\`agents/\`\)|agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue' docs/DESIGN.md

Expected: empty.

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)

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).

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).

grep -nE '^\s*(struct |enum |pub (struct|enum|fn))' docs/DESIGN.md

Expected: empty (Sweep-3 part A — no Rust type defs).

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).

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

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

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

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):

## 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

git add docs/JOURNAL.md docs/roadmap.md
git commit -m "design-md-consolidation 4: journal entry + milestone close + roadmap mark done"