AILang/docs/specs/0004-design-md-consolidation.md

# DESIGN.md Consolidation — Design Spec

**Date:** 2026-05-10
**Status:** Approved — proceeding to plan
**Authors:** Brummel (orchestrator) + Claude

## Goal

`docs/DESIGN.md` (today 2262 lines) mixes three time axes: timeless
state ("the language has X"), historical narrative ("Iter 18a added
Y, Iter 19b refined Y"), and workflow detail ("maintained by the
ailang-docwriter agent"). The mix forces every LLM reader (the
`ailang-architect` agent, the `brainstorm` skill, any future
orchestrator) to filter axis-by-axis on every read — work the
document should do once, structurally.

This milestone consolidates `DESIGN.md` to a single time axis —
**state plus timeless rationale** — and routes the other two axes
to their existing canonical sources:

| Source | Content | Time axis |
|--------|---------|-----------|
| `docs/DESIGN.md` | State + timeless why | timeless |
| `docs/JOURNAL.md` | History, migration, REVERTED, iter-decision corrections, queued options | chronological |
| `skills/<name>/SKILL.md` + agents | Workflow, discipline, agent rosters | trigger-bound |
| `crates/ailang-core/src/ast.rs` | Mirrors `DESIGN.md` §Data-model in code | mirrors DESIGN.md |

The milestone is documentation-only. No language semantics change.
No new compiler features ship. The single new artefact in code is a
schema-drift test (`design_schema_drift.rs`, sweep 3).

## Architecture

**Role of DESIGN.md (post-consolidation).** DESIGN.md describes
exclusively *what the language is* — schema, semantics, invariants,
timeless reasoning for why alternatives are excluded. It contains
no development history, no iter tags, no status markers, no
migration plans, no REVERTED audit trails, no workflow discipline.

**Cross-reference asymmetry.** References go primarily *into*
DESIGN.md, rarely *out of* it:

- JOURNAL → DESIGN: every iter entry may link to the affected
  section (existing practice).
- Skills/agents → DESIGN: `ailang-architect` reads DESIGN as the
  drift baseline; `brainstorm` checks Feature-Acceptance against
  DESIGN.
- DESIGN → JOURNAL: only at narrowly defined points where a
  prohibition's calibration is historical and JOURNAL holds the
  evidence (e.g. "tracing GC: see JOURNAL bench notes" — as a
  one-line pointer, not as an embedded data point).
- DESIGN → skills: not direct; DESIGN does not describe how the
  language is developed.

**Schema SoT inversion.** Decision 1 says "source = data, not text";
that makes DESIGN.md §Data-model structurally the schema spec.
Today's `whenever the two disagree, ast.rs is the source of truth`
disclaimer inverts: `ast.rs` gains a module-doc-comment pointing to
DESIGN.md §Data-model as the canonical source. A new drift test
(analogous to `crates/ailang-core/tests/spec_drift.rs`) enforces
structural agreement between the JSON-schema blocks in DESIGN.md
and the variants in `ast.rs` — the test is the mechanism that
makes the inversion load-bearing.

**Feature-acceptance criterion (transferred).** The criterion is
calibrated for language features; this milestone adds none.
Transferred form: a consolidated DESIGN.md is load-bearing for
`ailang-architect` (drift-review baseline), `brainstorm`
(Feature-Acceptance gate baseline), and any future LLM that needs
to understand the state. Mixing history + state forces every reader
into filtering work the document should do once. Consolidation
**improves correctness** (fewer drift opportunities between
DESIGN/JOURNAL/skills) and **removes redundancy** (one SoT per
axis instead of three overlapping ones). The criterion applies by
analogy.

## Components — the four thematic sweeps

Four sweeps, each reviewable against a clear search pattern. Order
is chosen so each later sweep operates on a quieter base.

### Sweep 1 — Remove history anchors

Mechanical pass; no semantic content changes.

- All iter tags removed (`Iter 14b`, `Iter 18a`, `Iter 22a`,
  `Family 20`, `since Iter 13a`, …).
- All date anchors removed (`Committed 2026-05-08`,
  `2026-05-09 revision flips`, `Iter 19b — FnDef.suppress`).
- All status markers removed (`Status: shipped`,
  `Status: half-retirement`, `as of 2026-05-09`).
- All bench data-point anchors (`60% allocate-path overhead`,
  `4.14× rc/bump`, `3.31x vs non-inlinable`) either removed or
  condensed to a one-line JOURNAL pointer — the data point is
  historical; the *prohibition* it grounds is timeless.

Acceptance:
`grep -nE 'Iter [0-9]+[a-z]?|Family [0-9]+|2026-[0-9]{2}-[0-9]{2}|Status: ' docs/DESIGN.md`
returns nothing (or a deliberate exception is recorded in the
JOURNAL entry for this iter).

### Sweep 2 — REVERTED + migration plans out

- Decision 7 (`Term::If` removal) deleted entirely. `Term::If`
  exists in the language; the witness is the Term-schema section.
- Decision 9 → Decision 10 "Migration plan" (7-point list)
  removed — migration is complete; the end state is described.
- Decision 11 "Why mono, not virtual dispatch (the
  empirically-grounded version)" — correction history (`The
  original rationale implicitly argued … 2026-05-10
  micro-benchmark refutes …`) condensed to a single "mono enables
  optimisations vdisp forbids" rationale.
- "future iter may"-speculations condensed: kept only where they
  carry a **binding prohibition** (e.g. "future iter that proposes
  laziness must prove cycle is collectible" — that is a language
  constraint). Pure aspirations ("a future Prelude milestone may
  add Show…") removed.
- Iter-numbered cross-references in surviving prose ("see Iter
  18d–18g shipping work") replaced with section-anchored links or
  removed.

Acceptance:
`grep -n 'REVERTED\|preserved for the audit trail\|Migration plan\|originally framed\|original rationale' docs/DESIGN.md`
returns nothing.

### Sweep 3 — Schema SoT inversion + Data-model hardening

- From the "Data model" section: all Rust type definitions
  removed (`Type::Fn { params: Vec<Type>, … }` etc.) — DESIGN.md
  specifies *JSON schema*, not Rust code.
- The `whenever the two disagree, ast.rs is the source of truth`
  disclaimer removed and replaced by a module-doc-comment in
  `ast.rs` pointing to DESIGN.md §Data-model.
- Drift test added: `crates/ailang-core/tests/design_schema_drift.rs`
  (analogous to `spec_drift.rs`) walks exhaustive matches over
  `Term` / `Pattern` / `Type` / `Def` / `Literal` and asserts an
  anchor for each variant exists in the JSON-schema block in
  DESIGN.md.
- A prominent sentence in the Data-model section establishes
  DESIGN.md as the schema SoT.

Acceptance:
`cargo test -p ailang-core design_schema_drift` green; no Rust type
definitions remain in `docs/DESIGN.md` (`grep -E '^\s*(struct|enum|pub )'`
returns nothing); `ast.rs` carries the SoT-pointer doc-comment.

### Sweep 4 — Workflow / cross-reference cleanup

- "Project ecosystem" entry `agents/` corrected (path is
  `skills/<name>/agents/`).
- "Verification and correctness" section: workflow detail
  ("Maintained by the `ailang-docwriter` agent (Iter 13d
  onward)") removed — the verification contract stays timelessly
  described; agent assignment belongs to the skills SoT.
- "What is not (yet) supported": iter anchors removed,
  "Recently lifted gates" paragraph removed (it is history).
  Section remains a pure state list.
- Cross-reference audit: every JOURNAL / skill reference from
  DESIGN.md examined; only those kept that ground a binding
  constraint.

Acceptance: every surviving cross-reference has a brief
justification (in commit message); no references to now-stale
paths.

## Data flow — readers of the document

| Reader | Question DESIGN.md must answer |
|--------|--------------------------------|
| `ailang-architect` (audit) | "Is the code drifting from the spec?" — DESIGN.md is the baseline. |
| `brainstorm` (new milestone) | "Does Feature-Acceptance hold? Is there a prohibition that kills this proposal?" |
| Future LLM (orchestrator successor) | "What *is* the language now? What may I not propose?" |
| Foreign LLM (zero-shot AILang author) | Not directly — that reader uses `crates/ailang-core/specs/form_a.md`. DESIGN.md is the meta-baseline, not the authoring spec. |

The first and third readers are the hardness tests: both are LLMs
without a human filter, who need to trust the document without
mixing it with JOURNAL or skills inside their context window. If
DESIGN.md embeds history, the LLM is forced into filter work the
document should not require.

## Error handling — drift detection

Three orthogonal mechanisms, each guarding a different drift
vector:

1. **`design_schema_drift.rs`** (sweep 3). Closes the
   ast.rs-vs-DESIGN-schema gap structurally. Every new
   `Term` / `Pattern` / `Type` / `Def` variant forces a DESIGN
   entry, otherwise the build fails.

2. **History-marker check in the audit skill** (sweep-1
   acceptance promoted to a standing discipline). The
   `ailang-architect` agent gains an additional mandatory check:
   `grep -nE 'Iter [0-9]+[a-z]?|Status: |Committed [0-9]{4}-' docs/DESIGN.md`
   must return nothing. The drift report flags any hit as an
   Iron-Law violation. This is the live-time guard against the
   "quick, drop an iter tag in DESIGN" reflex.

3. **Discipline note in `implement/SKILL.md`**: a clarification
   that DESIGN.md edits made during a feature-shipping iter must
   be phrased *timelessly* — the iter entry lands in the JOURNAL,
   the state entry in DESIGN. No new mechanism, but without this
   clarification the next implementer has two writing targets
   and no rule for which voice to use, and drift rebuilds.

## Testing strategy

Per sweep:
- **Sweep 1, 2, 4**: grep-based acceptance against the patterns
  listed in each sweep. The pattern run on the post-iter file
  must be empty (or carry an explicit, JOURNAL'd exception).
- **Sweep 3**: `cargo test -p ailang-core design_schema_drift`
  green. The test is RED-first: the iter starts by adding the
  test before the schema rewrite, so the GREEN transition is
  evidence the schema text matches `ast.rs`.

End-to-end:
- `cargo test --workspace` stays green throughout. No language
  semantics change; if any test breaks, that is a real
  regression and goes through the `debug` skill.
- `bench/check.py` and `bench/compile_check.py` stay at 0/0/0
  (they don't touch docs, but the milestone-close audit runs
  them).

No new `.ailx` fixtures: this milestone has no user-visible
surface, so `fieldtest` is skipped (per `skills/README.md`:
"Standard milestone-close path; skipped only for purely internal
milestones").

## Acceptance criteria

**Per sweep**: see four sweeps above.

**Across the whole milestone:**
- DESIGN.md has no iter tags, date anchors, status markers
  (sweep-1 patterns return nothing).
- DESIGN.md has no REVERTED section (Decision 7 gone), no
  migration plan.
- DESIGN.md describes the schema canonically; `ast.rs` points to
  DESIGN.md; `cargo test design_schema_drift` green.
- `ailang-architect` agent verifies DESIGN.md hygiene as part of
  drift review (its iron-law list gains the grep-pattern check).
- DESIGN.md size as a plausibility check: today 2262 lines —
  expected post-consolidation 1500-1800 lines, but this is an
  observation, not a target; an aggressive LOC target would push
  against substance.
- One JOURNAL entry per sweep, documenting what was discarded
  with an anchor example (e.g. "Decision 9 'half-retirement as
  of 2026-05-09' frame removed; state form: 'RC is canonical, GC
  is parity oracle, retirement gated on …'").

**Negative acceptance** (what must *not* happen):
- No semantic content of the language is lost (every constraint,
  every prohibition, every schema form remains; only the
  historical calibration migrates to JOURNAL).
- No circular references (DESIGN → JOURNAL → DESIGN for the
  rationale of a decision; that means the rationale was not
  formulable timelessly — and forces re-examination).
- No iter tag slips through (sweep-1 pattern is the sweep
  acceptance AND the standing drift lint).

## Iteration plan (for `plan` skill)

Four iterations, one per sweep, in the order above. The
`design_schema_drift.rs` test in sweep 3 follows the standard
RED-first TDD discipline carried by `ailang-implementer`. The
audit step at milestone close runs the regular `audit` skill
(architect drift review + bench regression suite); the architect's
mandatory checks are extended for this milestone with the
DESIGN.md-hygiene grep, then that extension is captured in
`audit/agents/ailang-architect.md` so the check survives beyond
this milestone.