# DESIGN.md / docs honesty lint — Design Spec **Date:** 2026-05-18 **Status:** Draft — awaiting user spec review **Authors:** Brummel (orchestrator) + Claude ## Goal Make `docs/DESIGN.md` (and the in-tree satellites that repeat its claims) mirror **only** the actual current state of the language — correct, present-tense — and make that property *load-bearing* so it cannot silently regrow. `docs/DESIGN.md` is the artefact the `ailang-architect` agent drift-checks the codebase against. A DESIGN.md that asserts something which is not true, or that narrates future intent / past mishaps as if they were part of the language description, makes the drift review unsound at its root: the architect cannot tell "code drifted from the spec" from "the spec was never true". This milestone closes that. Two failure modes are banned from the canonical docs: - **Wunschdenken** — aspirational "foundation for / we'd like / planned / will back / on the path to / if-when X arrives we'll …" forward intent. Genuine forward intent belongs in `docs/roadmap.md`, never in DESIGN.md. - **Post-mortem / doc-archaeology narrative** — "an earlier draft said X; a follow-up replaced it / previously all diagnostics were Error / what changed in is / X was retired in iter Y / preserved for the audit trail". Project and document history belongs in `docs/journals/`, never in DESIGN.md. One exception is legitimate and must be **preserved**: a **present-tense reserved / unimplemented / deliberately-excluded** claim that is explicitly AND correctly labelled as such. The effect-doc-honesty precedent (2026-05-16) established the gold form: *"`Diverge` is a reserved effect name with no op and no codegen."* The discriminator is whether the doc asserts something exists/works/changed that does not — not whether the sentence mentions the future or the past. ## Architecture Three layers, one iteration (the structure ratified with the user; mirrors the effect-doc-honesty precedent, which shipped as a single 6-task iter): 1. **The discriminator, codified present-tense inside DESIGN.md.** A short meta-subsection added to DESIGN.md's existing document-roles area states the honesty rule the document holds itself to. This makes the boundary discoverable by any future LLM reading DESIGN.md and gives the architect a citable in-tree anchor. It is itself written present-tense (it describes a rule the document *currently* obeys, not one it *will* adopt). 2. **The corrections.** Every passage that the discriminator classifies as Wunschdenken or non-citation post-mortem is rewritten present-tense (or, for genuine forward intent, relocated to `docs/roadmap.md`; the roadmap already carries the Boehm- retirement and auto-derivation queue entries, so most relocations are deletions, not moves). Scope: `docs/DESIGN.md` plus the in-tree satellites that repeat the same claim — `docs/PROSE_ROUNDTRIP.md` and any load-bearing `///` / `//!` doc-comment that echoes a corrected DESIGN.md sentence. (`crates/ailang-core/specs/form_a.md` was swept: its sole hit, *"multi-superclass chains are not yet supported"*, is gold-form honest-reserved — no change.) 3. **The anti-regrowth mechanism — pin (hard) + sweep+architect (standing).** Two complementary guards, exactly the design-md-consolidation pattern already in the tree: - **Enumerated pin (authoritative, cargo-test gate).** A new `crates/ailang-core/tests/docs_honesty_pin.rs`, sibling to the existing `effect_doc_honesty_pin.rs`: for every corrected site, one assertion that the fiction/Wunschdenken/post-mortem string is **absent** and one that the present-tense corrected anchor is **present**. This is a hard `cargo test --workspace` gate. - **Sweep 5 + architect bullet (standing, advisory, forward).** `bench/architect_sweeps.sh` already runs four design-md-consolidation greps as an advisory companion to the architect's "DESIGN.md history-anchor regrowth" check. Sweep 2 *already* partially catches Wunschdenken (`A future iter may`, `REVERTED`) — but its wording is too narrow (it misses "may land in a future iteration", "is on the path to retirement", "an earlier draft of this Decision said", "what changed in is", "were retired in iter"). This milestone adds **Sweep 5 (honesty)** closing those wording gaps, plus a new **"DESIGN.md honesty drift"** bullet in the architect's "What you check" list that cites the DESIGN.md discriminator meta-subsection. The pin protects the corrected set; Sweep 5 + the bullet catch *new* regrowth the enumerated pin cannot see. **Why the enumeration is procedural, not a frozen list.** The authoritative scope is *"the discriminator applied to the full `architect_sweeps.sh` (incl. Sweep 5) output, every hit classified"*. Running the existing sweep already surfaces post-mortem sites a narrow hand-grep misses (e.g. DESIGN.md:2027/2065 *"primitives were retired 2026-05-14 in iter rpe.1"*, :503 *"what did change in 2026-05-13 (this milestone) is"*, :2135 *"originally listed here … was retired"* — all currently waved through as Sweep-1 "legitimate quotes"). The spec owns the discriminator and the procedure; the planner owns the byte-exact classified enumeration (planner Iron Law). A frozen orchestrator list would itself be a honesty risk. ## Concrete code shapes This is a **documentation-integrity milestone: it has no `.ail` authoring surface by nature.** Per the brainstorm skill's no-surface clause, the concrete deliverables are (a) the executable pin (Rust), and (b) the prose before → after — exactly the effect-doc-honesty precedent's shape. Feature-acceptance clause 1 ("an LLM reaches for it") is N/A (no surface); the measurable correctness improvement (clause 2) is that the architect's drift review stops being unsound; clause 3 is trivially met (no language construct, no bug class). ### Primary deliverable A — the discriminator, as it will read in DESIGN.md A new present-tense meta-subsection (placed in DESIGN.md's document-roles area, near the existing `roadmap.md` / `journals/` pointer at ~line 50): ```markdown ### What this document is — and the honesty rule it holds itself to DESIGN.md describes what AILang **is now**: schema, semantics, invariants, runtime contracts, and the rationale for each. It is present-tense by construction. Two things never belong here: - **Forward intent** ("planned / will back / on the path to / if-when X arrives") — that lives in `docs/roadmap.md`. - **History** ("an earlier draft said / previously / what changed in / retired in iter Y") — that lives in `docs/journals/`. The single legitimate exception is a present-tense reserved or deliberately-excluded claim that is explicitly and correctly labelled (e.g. "`Diverge` is a reserved effect name with no op and no codegen"; "No `deriving` — instances are written by hand"; "Regions were considered and rejected; see X"). The discriminator is not whether a sentence mentions past or future, but whether the document **asserts something exists, works, or changed that does not**. Design rationale — *why* the language excludes a thing — is in scope and present-tense; the *narrative of how the document reached that wording* is not. ``` ### Primary deliverable B — worked discriminator classifications (the clause-2 evidence) The discriminator is the design judgement. These are the boundary cases, each shown before → after, that *prove* it is operational (not a hand-wave): | DESIGN.md | Before | Classification | After | |---|---|---|---| | ~L1504 | "An earlier draft of this Decision said 'uniqueness is fully inferred' … A follow-up discussion replaced it: AILang demands annotations *because* …" | **Post-mortem** (doc-archaeology) → journals | "AILang demands annotations because the LLM author can produce them effortlessly; the compiler does inference plus verification of contracts." | | ~L2519 | "Boehm-on-`--alloc=gc` is on the path to retirement; see `docs/roadmap.md` for the active queue." | **Wunschdenken** (a plan, not a present fact) → roadmap (already carries the Boehm-retirement entry) | "`--alloc=gc` selects the transitional Boehm backend; `--alloc=rc` is the canonical backend (Decision 10) and the CLI default." | | ~L2046 | "`float_to_str` (iter 24.1, type-installed; codegen ships in a future iter per roadmap). Will back `Show Float`." | "type-installed" honest-reserved (**keep**); "Will back `Show Float`" Wunschdenken (**strip**) | "`float_to_str : (borrow Float) -> Str` — type-installed; codegen reserved, not yet shipped." | | ~L1318 | "The first ever Warning-level diagnostic; previously all diagnostics were `Error`." | **Post-mortem** → journals | "Severity: `Warning`. `ail check`/`build`/`emit-ir` exit 1 only on at least one `Error`; warnings print but do not abort." | | ~L484 | "**Both extensions accepted.** Since iter ext-cli.1 (2026-05-12), every path-taking CLI subcommand accepts either …" | **History-anchor** (inline narrative, not a block-quote citation) → strip anchor | "Every path-taking CLI subcommand accepts either `.ail` (Form A) or `.ail.json` (Form B) as input." | | ~L1516 | "Does not introduce regions. Regions were considered and rejected; see 'Why not other memory models' above." | **Design rationale** (present-tense exclusion + internal pointer) | **KEEP unchanged** — this is the protected exception, not drift. | | ~L655 | "### Empirical addendum (2026-05-12)" + cross-model measurement results | Section *content* is present-tense evidence for Decision 6 (**keep**); the dated heading is a mild archaeology marker | Heading de-dated to "### Empirical addendum (cross-model authoring measurement)"; data unchanged. | | ~L2725 | "`Diverge` is a reserved effect name with no op and no codegen." | Gold-form honest-reserved | **KEEP unchanged** — the discriminator's positive anchor. | ### Secondary supporting — the pin shape (mirrors `effect_doc_honesty_pin.rs`) ```rust //! Regression pin: the canonical docs must stay present-tense-honest. //! Fails if any swept-and-corrected Wunschdenken / post-mortem string //! reappears, or any present-tense corrected anchor is dropped. use std::fs; fn read(rel: &str) -> String { /* identical helper to effect_doc_honesty_pin.rs */ } #[test] fn design_md_has_no_wunschdenken() { let d = read("docs/DESIGN.md"); assert!(!d.contains("is on the path to retirement"), "..."); // L2519 assert!(!d.contains("Will back `Show Float`"), "..."); // L2046 assert!(!d.contains("may land in a future iteration"), "..."); // L1837 // … one per corrected Wunschdenken site } #[test] fn design_md_has_no_doc_archaeology() { let d = read("docs/DESIGN.md"); assert!(!d.contains("An earlier draft of this Decision said"), "..."); // L1504 assert!(!d.contains("previously all diagnostics were"), "..."); // L1318 assert!(!d.contains("were retired 2026-05-14 in iter rpe.1"), "..."); // L2027/2065 // … one per corrected post-mortem site } #[test] fn design_md_present_tense_anchors_present() { let d = read("docs/DESIGN.md"); assert!(d.contains("the honesty rule it holds itself to"), "discriminator meta-subsection present"); assert!(d.contains("`Diverge` is a reserved effect name with no op and no codegen"), "the gold-form honest-reserved anchor must remain (regression: do not over-strip)"); // … the discriminator's protected-exception anchors, pinned so the // sweep-and-correct does not over-correct a legitimate reserved claim } #[test] fn prose_roundtrip_md_has_no_wunschdenken() { let p = read("docs/PROSE_ROUNDTRIP.md"); assert!(!p.contains("A future iter may layer a tool-use schema"), "..."); // L152 } ``` ### Secondary supporting — Sweep 5 + architect bullet `bench/architect_sweeps.sh`, appended after Sweep 4: ```bash run_sweep "5 (honesty: wunschdenken + non-citation post-mortem)" \ 'on the path to retirement|may land in a future iteration|[Ww]ill back `Show|[Ww]ill (eventually|later) (be|support|back)|[Ii]f/?when .* (arrives|lands).*(will|would)|an earlier draft of this Decision said|previously all diagnostics were|what did change in 2026-|were retired 20[0-9]{2}-[0-9]{2}-[0-9]{2} in iter|originally listed here' ``` `skills/audit/agents/ailang-architect.md`, new bullet in "What you check" (sibling to "DESIGN.md history-anchor regrowth"): ```markdown - **DESIGN.md honesty drift.** Sweep 5 of `bench/architect_sweeps.sh` flags Wunschdenken / non-citation post-mortem. Apply the discriminator from DESIGN.md §"What this document is — and the honesty rule it holds itself to": a hit is drift unless it is a present-tense correctly-labelled reserved/excluded claim, present- tense design rationale, or a block-quote journal citation. Forward intent is roadmap drift; document/project history is journal drift. ``` ## Components | Artefact | Change | |---|---| | `docs/DESIGN.md` | + discriminator meta-subsection (~line 50 area); ~12–18 passages rewritten present-tense / stripped (planner enumerates byte-exact from the classified sweep output) | | `docs/PROSE_ROUNDTRIP.md` | L152 "A future iter may layer …" tool-use/MCP Wunschdenken stripped (the present-tense doc describes the cycle that exists; roadmap already owns forward integration intent) | | load-bearing `///`/`//!` doc-comments | any that echo a corrected DESIGN.md sentence, corrected in lockstep (effect-doc-honesty satellite precedent) | | `crates/ailang-core/tests/docs_honesty_pin.rs` | **new** — enumerated absent/present pin, sibling to `effect_doc_honesty_pin.rs` | | `bench/architect_sweeps.sh` | + Sweep 5 (honesty) | | `skills/audit/agents/ailang-architect.md` | + "DESIGN.md honesty drift" bullet citing the meta-subsection | | `docs/roadmap.md` | the P1 honesty-lint entry checked off + this spec referenced; relocations land here only if a stripped forward-intent line is *not* already represented (audit-time check — most are already present) | No language, checker, codegen, or runtime code changes. `ail check`/`run`/`build` byte-unchanged by construction. ## Data flow Build/test path is unchanged (docs + a new test file + a shell sweep + an agent-definition file). The only new runtime artefact is the pin test, which reads the doc files from `CARGO_MANIFEST_DIR/../../` exactly as `effect_doc_honesty_pin.rs` does. The architect's review flow gains one bullet and one sweep; both are advisory exactly like the existing four sweeps (the script header already states non-zero exit is advisory, architect-adjudicated). ## Error handling - **Over-correction risk** (stripping a legitimate honest-reserved claim): countered by the pin's *present*-anchor assertions — `design_md_present_tense_anchors_present` fails if the gold-form reserved claims (`Diverge` reserved, `No deriving`, regions rejected, the known carve-outs) are dropped. The discriminator's protected-exception list is itself pinned. - **Sweep-5 false positives**: by design advisory, architect- adjudicated against the codified discriminator — identical to the existing four sweeps. Not a hard gate. - **Pin brittleness** (a future legitimate edit trips an absent- assertion): acceptable and intended — the pin is a *presence* contract; a future edit that reintroduces a banned string must consciously update the pin, which is the point (same contract as `effect_doc_honesty_pin.rs`). ## Testing strategy 0. **Single-line pin substrings (carried from the effect-doc-honesty Concern).** Every asserted absent/present substring MUST be a contiguous single line in the doc file. The known failure mode: the plan's verbatim corrected-replacement body soft-wraps a phrase mid-string, contradicting a single-line pin substring, so the two authoritative artefacts cannot both be applied verbatim. The planner's pin-substring ↔ replacement-body-wrap cross-check must account for the replacement body's own line wrap. 1. **RED first** (TDD, per implementer discipline): author `docs_honesty_pin.rs` *before* the corrections; it runs RED (absent-assertions fail because the fiction strings are still present; present-anchor assertions fail because the discriminator subsection is not yet written). 2. Apply the discriminator to the full `architect_sweeps.sh` (incl. the new Sweep 5) output; classify every hit; correct every FIX-classified passage; add the meta-subsection. 3. Pin goes GREEN. `cargo test --workspace` = prior + N new pin tests, zero regressions. 4. The three sentinel drift/coverage tests (`design_schema_drift`, `spec_drift`, `schema_coverage`) stay green (empirically confirms none scans the corrected prose regions — same check the effect-doc-honesty iter ran). 5. `bash bench/architect_sweeps.sh` re-run: Sweep 5 clean (0 honesty hits); Sweeps 1–4 unchanged except where a corrected line removed a previously-waved Sweep-1 date-anchor. 6. `cargo build --workspace` clean; `bench/check.py`, `bench/compile_check.py`, `bench/cross_lang.py` unaffected (no codegen change) — the milestone-close audit confirms. ## Acceptance criteria - [ ] DESIGN.md carries the present-tense discriminator meta-subsection; it is itself present-tense (describes a rule the document currently obeys). - [ ] Every `architect_sweeps.sh`+Sweep-5 hit is classified by the discriminator; every FIX-classified passage in DESIGN.md + satellites is rewritten present-tense or relocated to roadmap; every KEEP passage (honest-reserved, design-rationale, block-quote citation) is unchanged. - [ ] `crates/ailang-core/tests/docs_honesty_pin.rs` exists, was authored RED-first, and is GREEN: every corrected fiction string absent, every present-tense + protected-exception anchor present. - [ ] `bench/architect_sweeps.sh` has Sweep 5; running it reports zero honesty hits. - [ ] `skills/audit/agents/ailang-architect.md` has the "DESIGN.md honesty drift" bullet citing the meta-subsection. - [ ] `cargo test --workspace` green (prior count + new pin tests, 0 regressions); `cargo build --workspace` clean; the three sentinel drift/coverage tests still green. - [ ] No language/checker/codegen/runtime change; `ail check`/`run`/`build` byte-unchanged. - [ ] `docs/roadmap.md` P1 honesty-lint entry checked off; any stripped genuine forward intent not already in the roadmap is added there.