# docs-honesty-lint.1 — Implementation Plan

> **Parent spec:** `docs/specs/2026-05-18-docs-honesty-lint.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Make `docs/DESIGN.md` + `docs/PROSE_ROUNDTRIP.md` mirror only
the current state (present-tense), codify the honesty discriminator
in-tree, and guard it with a wrap-robust enumerated pin + a wrap-robust
advisory Sweep 5.

**Architecture:** Single iteration, six tasks. Task 1 lays the RED
pin (the contract; wrap-robust via a whitespace-normalising helper).
Task 2 ships wrap-robust Sweep 5 + all sweep-count lockstep wording +
the architect bullet. Task 3 inserts the discriminator meta-subsection.
Task 4 applies the 14 byte-exact DESIGN.md corrections + a procedural
catch-all for any extra sweep hit. Task 5 fixes the PROSE satellite +
relocates genuine forward intent to the roadmap. Task 6 turns the pin
GREEN and runs full verification. No language/checker/codegen/runtime
change; `ail check`/`run`/`build` byte-unchanged by construction.

**Tech Stack:** Rust integration test (`crates/ailang-core/tests/`),
Bash (`bench/architect_sweeps.sh`), Markdown (`docs/`), agent-def
Markdown (`skills/audit/agents/`).

---

## Files this plan creates or modifies

- Create: `crates/ailang-core/tests/docs_honesty_pin.rs` — wrap-robust enumerated absent/present regression pin, sibling to `effect_doc_honesty_pin.rs`.
- Modify: `bench/architect_sweeps.sh:50-56` — append wrap-robust Sweep 5; fix the "four sweeps clean" tail + header wording.
- Modify: `skills/audit/agents/ailang-architect.md:73-79` — add "DESIGN.md honesty drift" bullet after L79; fix "four sweeps" wording at L74,L77.
- Modify: `docs/DESIGN.md` — insert discriminator meta-subsection into the `## Project ecosystem` section (after L52); 14 byte-exact present-tense corrections (Task 4).
- Modify: `docs/PROSE_ROUNDTRIP.md:152-157` — strip the tool-use/MCP Wunschdenken paragraph; present-tense replacement.
- Modify: `docs/roadmap.md` (P3 — Ideas) — add the relocated LLM tool-use / MCP / LSP forward-integration idea (the sole genuine forward intent stripped that is not already represented).

**Procedural-enumeration note (spec L92-102, recon concern 3).** The
authoritative FIX scope is *every hit of `bash bench/architect_sweeps.sh`
after Sweep 5 is added, classified by the Task-4 discriminator table*.
The 14 corrections in Task 4 are every site knowable at plan time
(Boss ran the corrected Sweep-5 regex against the current tree); Task 4
Step "catch-all" handles anything the sweep surfaces that is not in the
table. The list is concrete (Iron Law) without being frozen-as-scope
(the sweep stays authoritative at exec time).

**Out of FIX scope — deliberate KEEPs (do NOT edit these):**
- `docs/DESIGN.md` L1215-1221 — the `(con T)`/`Type`-unchanged
  parenthetical is *self-labelled* "a tiebreaker, not a rationale —
  the substantive reasons above are what justify the choice." It
  asserts nothing false; it honestly discloses it is not a reason.
  Effort-as-rationale-disguised is a *different* anti-pattern with
  its own CLAUDE.md home; it is outside this spec's two-pronged
  discriminator. KEEP.
- `docs/DESIGN.md` L1516-1517 — "Does not introduce regions. Regions
  were considered and rejected; see …" is present-tense design
  rationale (a current exclusion + internal pointer). KEEP.
- `docs/DESIGN.md` L2725 — "`Diverge` is a reserved effect name with
  no op and no codegen." Gold-form honest-reserved. KEEP (and pinned
  present in Task 1).
- `docs/DESIGN.md` the bare `(iter 24.1)` / `(iter str-concat)`
  provenance tags on the heap-Str primitive list (L2041, L2043, L2045,
  L2047, L2049) — terse true provenance, asserts nothing false, not
  narrative. KEEP. (L2050's Sweep-1 hit is the bare date inside this
  true provenance tag — a Sweep-1 date false-positive, not drift.)
- `docs/DESIGN.md` L48-52 — the `## Project ecosystem` Docs bullet
  ("`docs/journal-archive.md` (archived monolith for pre-2026-05-11
  history)") is the present-tense doc-roles pointer the discriminator
  subsection joins. The L50 Sweep-1 hit is its embedded date. KEEP.
- `crates/ailang-core/specs/form_a.md` — not modified, not pinned.
  Its only forward-style line ("multi-superclass chains are not yet
  supported", soft-wrapped L130-131) is gold-form honest-reserved.
  (Recon concern 2: the spec prose collapsed the line-wrap; the
  *decision* — no change — is correct and needs no pin.)

---

## Task 1: RED pin — `docs_honesty_pin.rs` (wrap-robust contract)

**Files:**
- Create: `crates/ailang-core/tests/docs_honesty_pin.rs`

Rationale for the `norm()` deviation from the spec's illustrative pin
shape (spec L164-201 used naive `d.contains()`): `docs/DESIGN.md` is
hard-wrapped at ~70 columns, so almost every target phrase is split
across two source lines. A naive single-line `contains()` would assert
nothing on wrapped phrases (false green). `norm()` collapses every
whitespace run (incl. newline+indent) to a single space before
matching, making every assertion wrap-independent. This simultaneously
discharges spec Testing-strategy item 0 AND planner self-review item 6
(pin ↔ replacement-body contiguity): with `norm()`, contiguity is
automatic — Task 4 may wrap replacement prose however Markdown needs;
the pin still matches on word content. This is strictly more robust
than the effect-doc-honesty precedent's fragile "keep the phrase on
one line" approach.

- [ ] **Step 1: Write the pin file**

```rust
//! Regression pin: the canonical docs must stay present-tense-honest.
//!
//! `docs/DESIGN.md` (and `docs/PROSE_ROUNDTRIP.md`) must not assert
//! something exists/works/changed that does not. This pin fails if any
//! swept-and-corrected Wunschdenken / post-mortem string reappears, or
//! if any present-tense corrected anchor (incl. the protected
//! honest-reserved exceptions) is dropped. Matching is
//! whitespace-normalised so the assertions are independent of the
//! docs' hard line-wrap. Companion to `effect_doc_honesty_pin.rs` and
//! to Sweep 5 of `bench/architect_sweeps.sh`.

use std::fs;

fn read(rel: &str) -> String {
    let p = concat!(env!("CARGO_MANIFEST_DIR"), "/../../");
    fs::read_to_string(format!("{p}{rel}"))
        .unwrap_or_else(|e| panic!("read {rel}: {e}"))
}

/// Collapse every whitespace run (incl. newline + indent) to a single
/// space, so a phrase split across the docs' hard line-wrap still
/// matches a single-line assertion substring.
fn norm(s: &str) -> String {
    s.split_whitespace().collect::<Vec<_>>().join(" ")
}

#[test]
fn design_md_has_no_wunschdenken() {
    let d = norm(&read("docs/DESIGN.md"));
    assert!(!d.contains("is on the path to retirement"),
        "DESIGN.md: Boehm retirement is forward intent — it lives in docs/roadmap.md, not DESIGN.md");
    assert!(!d.contains("Will back `Show Float`"),
        "DESIGN.md: 'Will back Show Float' asserts a future capability as fact");
    assert!(!d.contains("codegen ships in a future iter"),
        "DESIGN.md: float_to_str codegen is reserved/not-yet-shipped, not a promised future ship");
    assert!(!d.contains("may land in a future iteration"),
        "DESIGN.md: auto-derivation 'may land in a future iteration' is Wunschdenken");
    assert!(!d.contains("If/when concurrency arrives"),
        "DESIGN.md: 'if/when concurrency arrives … will be' is forward conditional");
    assert!(!d.contains("was deferred — all three layer additively"),
        "DESIGN.md: deferred future integration paths are roadmap intent, not DESIGN.md");
}

#[test]
fn design_md_has_no_doc_archaeology() {
    let d = norm(&read("docs/DESIGN.md"));
    assert!(!d.contains("An earlier draft of this Decision said"),
        "DESIGN.md: doc-archaeology ('an earlier draft said … a follow-up replaced it') lives in docs/journals/");
    assert!(!d.contains("previously all diagnostics were `Error`"),
        "DESIGN.md: 'previously all diagnostics were Error' is project history → docs/journals/");
    assert!(!d.contains("What did change in 2026-05-13 (this milestone) is"),
        "DESIGN.md: 'what did change in <date> (this milestone)' is post-mortem narrative");
    assert!(!d.contains("primitives were retired 2026-05-14 in iter rpe.1"),
        "DESIGN.md: 'X were retired <date> in iter Y' is history → docs/journals/");
    assert!(!d.contains("were retired in iter rpe.1 (2026-05-14)"),
        "DESIGN.md: the second per-type-print-op retirement-narrative sentence is history");
    assert!(!d.contains("originally listed here as the eighth fixture, was retired"),
        "DESIGN.md: 'originally listed … was retired by milestone X' is doc-archaeology");
}

#[test]
fn design_md_present_tense_anchors_present() {
    let d = norm(&read("docs/DESIGN.md"));
    // the discriminator meta-subsection (Task 3)
    assert!(d.contains("the honesty rule it holds itself to"),
        "DESIGN.md must carry the discriminator meta-subsection heading");
    assert!(d.contains("whether the document asserts something exists, works, or changed that does not"),
        "DESIGN.md discriminator must state the operational test");
    // protected honest-reserved exceptions — over-correction guard
    assert!(d.contains("`Diverge` is a reserved effect name with no op and no codegen"),
        "the gold-form honest-reserved anchor must remain (do not over-strip)");
    assert!(d.contains("Regions were considered and rejected"),
        "the present-tense design-rationale exclusion must remain (do not over-strip)");
    assert!(d.contains("a tiebreaker, not a rationale"),
        "the self-labelled tiebreaker is honest and stays (do not over-strip)");
    // corrected present-tense anchors (Task 4)
    assert!(d.contains("`--alloc=gc` selects the transitional Boehm backend"),
        "DESIGN.md must describe Boehm present-tense, not as 'on the path to retirement'");
    assert!(d.contains("type-installed; codegen is reserved and not yet shipped"),
        "float_to_str must be present-tense honest-reserved");
    assert!(d.contains("AILang demands annotations *because* the LLM author can produce them effortlessly"),
        "the 'does not infer everything' bullet must be present-tense (no doc-archaeology)");
    assert!(d.contains("`io/print_str` is the only built-in direct-output effect-op"),
        "the print-op set must be stated present-tense, not as a retirement narrative");
}

#[test]
fn prose_roundtrip_md_has_no_wunschdenken() {
    let p = norm(&read("docs/PROSE_ROUNDTRIP.md"));
    assert!(!p.contains("A future iter may layer a tool-use schema"),
        "PROSE_ROUNDTRIP.md: tool-use/MCP forward intent lives in docs/roadmap.md");
    assert!(p.contains("the lowest-common-denominator cycle and always works with any client"),
        "PROSE_ROUNDTRIP.md must close present-tense on the static-prompt path");
}
```

- [ ] **Step 2: Run the pin — verify it fails RED for the right reasons**

Run: `cargo test --workspace -p ailang-core --test docs_honesty_pin`
Expected: COMPILES, 4 tests run, all 4 FAIL. Specifically:
`design_md_has_no_wunschdenken` fails on the first `assert!` ("is on
the path to retirement" still present); `design_md_has_no_doc_archaeology`
fails ("An earlier draft of this Decision said" still present);
`design_md_present_tense_anchors_present` fails ("the honesty rule it
holds itself to" absent — Task 3 not yet done);
`prose_roundtrip_md_has_no_wunschdenken` fails ("A future iter may
layer a tool-use schema" still present). This RED state is the
contract Tasks 3-5 discharge.

---

## Task 2: Wrap-robust Sweep 5 + sweep-count lockstep + architect bullet

**Files:**
- Modify: `bench/architect_sweeps.sh:50-56`
- Modify: `skills/audit/agents/ailang-architect.md:73-79` (bullet) and `:74,77` (wording)

Concern-1 lockstep (recon): adding a fifth sweep makes "All four
sweeps clean." / the header "four design-md-consolidation sweeps" /
`ailang-architect.md` "the four sweeps" stale. Per planner self-review
item 7, every coordinated edit ships in THIS task — no deferral.

The Sweep-5 regex uses **contiguous source-line fragments**, not full
phrases: `architect_sweeps.sh`'s `run_sweep` is line-based
(`grep -nE … "$DESIGN"`), and the target phrases are soft-wrapped, so a
full-phrase pattern would miss them (Boss verified: the spec's
illustrative full-phrase regex caught only 4 of the ~12 sites). Each
fragment below was verified contiguous on a single current DESIGN.md
line.

- [ ] **Step 1: Append Sweep 5 after Sweep 4**

In `bench/architect_sweeps.sh`, the current lines 50-56 are:

```bash
run_sweep "4 (workflow + stale cross-references)" \
    'agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL'

if [[ $HITS -eq 0 ]]; then
    echo "All four sweeps clean."
fi
exit $HITS
```

Replace those exact lines with:

```bash
run_sweep "4 (workflow + stale cross-references)" \
    'agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL'

run_sweep "5 (honesty: wunschdenken + non-citation post-mortem)" \
    'on the path to|may land in a future|ships in a future iter|[Ww]ill back `Show|[Ww]ill eventually (be|support|back)|[Ii]f/?when [a-z]+ (arrives|lands)|[Aa]n earlier draft of this|previously all diagnostics were|[Ww]hat did change in 20|were retired 20[0-9]{2}-|retired in iter [a-z]|originally listed|\bwas deferred\b|foundation for [a-z]'

if [[ $HITS -eq 0 ]]; then
    echo "All five sweeps clean."
fi
exit $HITS
```

- [ ] **Step 2: Fix the script header "four sweeps" wording**

In `bench/architect_sweeps.sh`, the current header lines 4-6 are:

```bash
# Run the four design-md-consolidation sweep-invariant greps against
# docs/DESIGN.md. Output: matched lines, prefixed by sweep name. Exit 0
# if all four sweeps are clean, 1 if any anchor was found.
```

Replace with:

```bash
# Run the five DESIGN.md honesty/anchor sweep-invariant greps against
# docs/DESIGN.md. Output: matched lines, prefixed by sweep name. Exit 0
# if all five sweeps are clean, 1 if any anchor was found. Sweeps 1-4
# are the design-md-consolidation history-anchor invariants; Sweep 5
# is the docs-honesty-lint Wunschdenken / post-mortem invariant.
```

And the current header line 16:

```bash
# A non-zero exit is advisory, not authoritative: the architect agent
```

is unchanged (the advisory contract still holds for all five). No edit
to line 16; it is quoted only to bound the replacement at line 6.

- [ ] **Step 3: Run the sweep — confirm Sweep 5 fires on the still-uncorrected tree**

Run: `bash bench/architect_sweeps.sh; echo "EXIT=$?"`
Expected: EXIT=1. Output now includes a `=== Sweep: 5 (honesty: …) ===`
block listing the uncorrected honesty sites (at minimum DESIGN.md
lines containing "on the path to", "may land in a future", "ships in
a future iter", "Will back `Show", "If/when concurrency", "An earlier
draft of this", "previously all diagnostics were", "What did change in
20", "were retired 20…", "retired in iter", "originally listed", "was
deferred"). Sweeps 1-4 unchanged from the recon baseline. This proves
Sweep 5 detects the wrapped sites the spec's illustrative regex missed.

- [ ] **Step 4: Add the "DESIGN.md honesty drift" architect bullet**

In `skills/audit/agents/ailang-architect.md`, the current lines 73-79
are the "DESIGN.md history-anchor regrowth" bullet:

```markdown
- **DESIGN.md history-anchor regrowth.** Run
  `bash bench/architect_sweeps.sh` from the repo root. Exit 0 = clean.
  Exit 1 = at least one of the four sweeps from the
  design-md-consolidation milestone (2026-05-10) matched. Review each
  match: a legitimate quote (e.g. a journal-entry citation inside a
  block-quote) is fine; a fresh history anchor / REVERTED narrative /
  workflow detail / stale cross-reference is drift to flag.
```

Replace those exact lines with (the wording fix "four"→"five
sweeps … 1-4 / Sweep 5" PLUS the new sibling bullet appended):

```markdown
- **DESIGN.md history-anchor regrowth.** Run
  `bash bench/architect_sweeps.sh` from the repo root. Exit 0 = clean.
  Exit 1 = at least one of the five sweeps matched. Sweeps 1-4 are the
  design-md-consolidation history-anchor invariants (2026-05-10):
  review each match — a legitimate quote (e.g. a journal-entry
  citation inside a block-quote) is fine; a fresh history anchor /
  REVERTED narrative / workflow detail / stale cross-reference is
  drift to flag.
- **DESIGN.md honesty drift.** Sweep 5 of `bench/architect_sweeps.sh`
  (the docs-honesty-lint invariant) 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.
```

- [ ] **Step 5: Confirm no other "four sweeps" string survives in the architect file**

Run: `grep -n "four sweeps\|the four sweeps\|four design-md" skills/audit/agents/ailang-architect.md`
Expected: no output (exit 1 from grep = no match). If any line prints,
it is a missed lockstep site — fix it to the "five / Sweeps 1-4 +
Sweep 5" wording before proceeding.

---

## Task 3: Insert the discriminator meta-subsection into DESIGN.md

**Files:**
- Modify: `docs/DESIGN.md` (insert after L52, inside `## Project ecosystem`)

The `## Project ecosystem` section spans L19-L59. Its Docs bullet is
L48-L52; the section's closing prose begins L56. Insert the new `###`
subsection between the Docs bullet and the closing prose.

- [ ] **Step 1: Read the exact insertion anchor**

Run: `sed -n '52,57p' docs/DESIGN.md`
Expected (verbatim, current tree):

```
  specs), `plans/` (per-iteration implementation plans).

The set of skills + agents is the development toolchain; new entries
are added here as soon as they are established. The skill system is
documented in `skills/README.md`; the agent roster lives there too.
```

(Line 52 ends the Docs bullet; line 53 is blank; lines 54-55 begin the
closing prose. The exact closing-prose wording on your tree is what
Step 2 anchors against — quote it from this Step's output, do not
assume.)

- [ ] **Step 2: Insert the meta-subsection after the blank line that follows L52**

Insert, immediately after the `specs), \`plans/\` …` line and its
following blank line (i.e. as a new block before
`The set of skills + agents is the development toolchain`):

```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 <date> / 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.

```

(Trailing blank line included so the following `The set of skills +
agents …` paragraph keeps its blank-line separator.)

- [ ] **Step 3: Verify the subsection landed and is present-tense**

Run: `grep -n "the honesty rule it holds itself to\|asserts something exists, works, or changed that does not" docs/DESIGN.md`
Expected: two lines print (the heading ~L54 area and the discriminator
sentence). Confirm by eye that the inserted block contains no
first-person future ("we will", "planned") — it describes a rule the
document *currently* obeys.

---

## Task 4: Apply the 14 byte-exact DESIGN.md corrections + procedural catch-all

**Files:**
- Modify: `docs/DESIGN.md` (14 enumerated sites + any extra sweep hit)

Every correction below gives the exact current text (verbatim, with
its line numbers as of plan time — re-confirm with the cited `grep`
since Task 3 shifted lines below L54 by +~22) and the exact
replacement. Apply each with an exact-string edit. The discriminator
classification is stated for each so the implementer can verify the
judgement, not just transcribe.

> **Line-number caveat:** Task 3 inserted ~22 lines at ~L54, so every
> site below L54 is now ~22 lines lower than its plan-time number.
> Anchor every edit by the verbatim *string*, not the line number.
> The `grep` in each step relocates the site reliably.

- [ ] **Step 1: L484 — strip the iter history-anchor (history-anchor)**

Run: `grep -n "Both extensions accepted" docs/DESIGN.md`
Current text (verbatim, two lines):

```
  **Both extensions accepted.** Since iter ext-cli.1 (2026-05-12),
  every path-taking CLI subcommand accepts either `.ail` (Form A)
```

Replace with:

```
  **Both extensions accepted.** Every path-taking CLI subcommand
  accepts either `.ail` (Form A)
```

(The bold lead is a present-tense fact and stays; only the
`Since iter ext-cli.1 (2026-05-12),` provenance clause is removed.
The trailing `or \`.ail.json\` (Form B) as input.` on the next line is
unchanged.)

- [ ] **Step 2: L503 — present-tense the authored-form statement (post-mortem)**

Run: `grep -n "What did change in 2026-05-13" docs/DESIGN.md`
Current text (verbatim):

```
  unchanged. What did change in 2026-05-13 (this milestone) is
  which form is authored: authors now write Form A; the JSON-AST
  is materialised in-process by callers that need it. The two
```

Replace with:

```
  unchanged. The authored form is Form A; the JSON-AST is
  materialised in-process by callers that need it. The two
```

- [ ] **Step 3: L650-653 — present-tense the cycle's fallback (Wunschdenken + malformed)**

Run: `grep -n "richer integration paths" docs/DESIGN.md`
Current text (verbatim, four lines — note the current text is also
grammatically broken: "layer additively on the static-prompt path
ships, which remains"):

```
The discussion of richer integration paths (LLM tool-use, MCP
server, LSP) was deferred — all three layer additively on the
static-prompt path ships, which remains the
lowest-common-denominator fallback that always works.
```

Replace with:

```
The cycle's lowest-common-denominator path is the static prompt
(`ail merge-prose | client | ail parse | ail check`), which works
with any client.
```

(LLM tool-use / MCP / LSP forward integration intent is relocated to
`docs/roadmap.md` P3 in Task 5 Step 2.)

- [ ] **Step 4: L655 — de-date the empirical-addendum heading (mild archaeology)**

Run: `grep -n "### Empirical addendum" docs/DESIGN.md`
Current text (verbatim):

```
### Empirical addendum (2026-05-12)
```

Replace with:

```
### Empirical addendum — cross-model authoring measurement
```

(The section *content* — the measurement results — is present-tense
evidence for Decision 6 and is unchanged.)

- [ ] **Step 5: L1318-1321 — present-tense the Warning severity (post-mortem)**

Run: `grep -n "The first ever Warning-level diagnostic" docs/DESIGN.md`
Current text (verbatim, four lines):

```
Severity: `Warning`. The first ever Warning-level diagnostic;
previously all diagnostics were `Error`. CLI exit semantics
adjusted: `ail check`, `ail build`, `ail emit-ir` exit 1 only on
at least one Error. Warnings print but do not abort.
```

Replace with:

```
Severity: `Warning`. `ail check`, `ail build`, `ail emit-ir` exit 1
only on at least one `Error`; warnings print but do not abort.
```

- [ ] **Step 6: L1504-1509 — present-tense the "does not infer everything" bullet (doc-archaeology)**

Run: `grep -n "An earlier draft of this" docs/DESIGN.md`
Current text (verbatim, six lines):

```
- **Does not infer everything.** An earlier draft of this
  Decision said "uniqueness is fully inferred" — that was the
  mainstream RC position. A follow-up discussion
  replaced it: AILang demands annotations *because* the LLM
  author can produce them effortlessly. The compiler does
  inference *plus* verification of contracts.
```

Replace with:

```
- **Does not infer everything.** AILang demands annotations
  *because* the LLM author can produce them effortlessly. The
  compiler does inference *plus* verification of contracts.
```

- [ ] **Step 7: L1513-1515 — present-tense the atomic-refcount bullet (Wunschdenken)**

Run: `grep -n "Does not commit to atomic refcounts" docs/DESIGN.md`
Current text (verbatim, three lines):

```
- **Does not commit to atomic refcounts.** AILang is currently
  single-threaded. If/when concurrency arrives, atomic-vs-non-
  atomic will be a separate decision per allocation kind.
```

Replace with:

```
- **Does not commit to atomic refcounts.** AILang is
  single-threaded; refcounts are non-atomic.
```

- [ ] **Step 8: L1837-1839 — drop the auto-derivation future tail (Wunschdenken)**

Run: `grep -n "AILang does not auto-derive instances" docs/DESIGN.md`
Current text (verbatim, four lines):

```
**No `deriving`.** AILang does not auto-derive instances. `instance Eq
MyType` must be written by hand. Auto-derivation may land in a future
iteration if the Feature-acceptance criterion holds for it; that
discussion is out of scope here.
```

Replace with:

```
**No `deriving`.** AILang does not auto-derive instances. `instance Eq
MyType` must be written by hand.
```

(The "may land in a future iteration if the criterion holds" tail is
speculative — not a committed forward intent — so it is deleted, not
relocated; a roadmap "maybe someday" entry would itself be vapour.)

- [ ] **Step 9: L2045-2046 — present-tense honest-reserved float_to_str (Wunschdenken)**

Run: `grep -n "float_to_str : (borrow Float)" docs/DESIGN.md`
Current text (verbatim, two lines):

```
- `float_to_str : (borrow Float) -> Str` (iter 24.1, type-installed;
  codegen ships in a future iter per roadmap). Will back `Show Float`.
```

Replace with:

```
- `float_to_str : (borrow Float) -> Str` (iter 24.1) —
  type-installed; codegen is reserved and not yet shipped.
```

(`type-installed` is honest present-reserved and stays in present-
tense form; "codegen ships in a future iter per roadmap" and "Will
back `Show Float`" are the Wunschdenken removed. The roadmap already
carries the heap-Str/`float_to_str` queue entry — no relocation.)

- [ ] **Step 10: L2025-2028 — present-tense the print-op set (post-mortem)**

Run: `grep -n "primitives were retired 2026-05-14 in iter rpe.1" docs/DESIGN.md`
Current text (verbatim, four lines):

```
Routing through `print` replaces the ad-hoc per-type print
effect-ops; the `io/print_int`, `io/print_bool`, `io/print_float`
primitives were retired 2026-05-14 in iter rpe.1, leaving
`io/print_str` as the only surviving direct-output effect-op.
```

Replace with:

```
Routing through `print` is the path for non-`Str` primitives;
`io/print_str` is the only built-in direct-output effect-op.
```

- [ ] **Step 11: L2063-2065 — delete the duplicate retirement-narrative sentence (post-mortem)**

Run: `grep -n "were retired in iter rpe.1 (2026-05-14)" docs/DESIGN.md`
Current text (verbatim, three lines):

```
the heap-Str result of `show x` into `io/print_str`. The per-type
effect-ops `io/print_int`, `io/print_bool`, `io/print_float` were
retired in iter rpe.1 (2026-05-14).
```

Replace with:

```
the heap-Str result of `show x` into `io/print_str`.
```

(The preceding clause already states the present behaviour; the
"were retired in iter rpe.1" sentence is pure history and is deleted.)

- [ ] **Step 12: L2133-2138 — present-tense the prelude-embed parenthetical (doc-archaeology)**

Run: `grep -n "originally listed" docs/DESIGN.md`
Current text (verbatim, six lines):

```
rejection-shape tests, not in the round-trip gate. (The
prelude's compile-time-embed carve-out, originally listed
here as the eighth fixture, was retired 2026-05-14 by
milestone prelude-decouple; the prelude is now embedded as
`examples/prelude.ail` in `ailang-surface` and parsed at
compile time via `ailang_surface::parse_prelude`.)
```

Replace with:

```
rejection-shape tests, not in the round-trip gate. (The prelude is
embedded as `examples/prelude.ail` in `ailang-surface` and parsed
at compile time via `ailang_surface::parse_prelude`.)
```

- [ ] **Step 13: L2519-2520 — present-tense the Boehm backend (Wunschdenken)**

Run: `grep -n "is on the path to" docs/DESIGN.md`
Current text (verbatim, two lines):

```
rewrites respectively. Boehm-on-`--alloc=gc` is on the path to
retirement; see `docs/roadmap.md` for the active queue.
```

Replace with:

```
rewrites respectively. `--alloc=gc` selects the transitional Boehm
backend; `--alloc=rc` is the canonical backend (Decision 10) and the
CLI default.
```

(Boehm-retirement forward intent is already a P2 todo in
`docs/roadmap.md` — no relocation needed.)

- [ ] **Step 14: Procedural catch-all — classify any remaining Sweep-5 hit**

Run: `bash bench/architect_sweeps.sh`
For every line in the `=== Sweep: 5 (honesty: …) ===` block that is
NOT one of the 13 sites corrected in Steps 1-13 above, apply the
discriminator (DESIGN.md §"What this document is — and the honesty
rule it holds itself to"):
  - present-tense correctly-labelled reserved/excluded claim →
    **KEEP**, record "KEEP: <line> — reason" in the per-iter journal.
  - present-tense design rationale → **KEEP**, record likewise.
  - block-quote journal citation → **KEEP**, record likewise.
  - Wunschdenken (forward intent) → rewrite present-tense or, if
    genuine committed forward intent not already in `docs/roadmap.md`,
    relocate there; record "FIX: <line> — before→after" in the
    journal AND add a matching `assert!(!d.contains("…"))` +
    present-anchor pair to `docs_honesty_pin.rs`.
  - post-mortem / doc-archaeology → rewrite present-tense; record +
    pin as above.
This step makes the enumeration the sweep-output-classified set (spec
L92-102), not a frozen list. Expected on the current tree: zero
additional hits beyond Steps 1-13 (Boss pre-verified), so this step
typically records only the KEEP set; it exists so a missed/new site
cannot slip the gate.

- [ ] **Step 15: Re-run the pin — DESIGN.md assertions now GREEN**

Run: `cargo test --workspace -p ailang-core --test docs_honesty_pin design_md`
Expected: `design_md_has_no_wunschdenken`, `design_md_has_no_doc_archaeology`,
and `design_md_present_tense_anchors_present` all PASS (Task 3 + Task 4
discharged them). `prose_roundtrip_md_has_no_wunschdenken` is NOT in
this filter (Task 5 discharges it).

---

## Task 5: PROSE_ROUNDTRIP satellite + roadmap relocation

**Files:**
- Modify: `docs/PROSE_ROUNDTRIP.md:152-157`
- Modify: `docs/roadmap.md` (P3 — Ideas)

- [ ] **Step 1: Strip the tool-use/MCP Wunschdenken paragraph**

Run: `grep -n "A future iter may layer a tool-use schema" docs/PROSE_ROUNDTRIP.md`
Current text (verbatim, L152-157, the final paragraph of the file):

```
A future iter may layer a tool-use schema (LLM calls back into
`ail parse` / `ail check` from inside its turn) or an MCP server
(any MCP-compatible client discovers AILang's resources, tools, and
prompts) on top of this cycle. Both are additive — the static-prompt
fallback documented here remains the lowest-common-denominator path
that always works.
```

Replace with:

```
The static-prompt path documented here is the lowest-common-denominator
cycle and always works with any client.
```

- [ ] **Step 2: Add the relocated forward intent to roadmap P3**

In `docs/roadmap.md`, the `## P3 — Ideas` section ends with the
`Richer integration paths between RC and uniqueness` idea. Read the
last P3 entry:

Run: `grep -n "Richer integration paths between RC and" docs/roadmap.md`
Current tail (verbatim):

```
- [ ] **\[idea\]** Richer integration paths between RC and
  uniqueness — deferred from the 21' arc; revisit once the
  uniqueness inference covers more program shapes.
```

Append immediately after that entry's last line:

```
- [ ] **\[idea\]** LLM tool-use schema / MCP server / LSP front-end
  over the prose-roundtrip cycle — additive layers on top of the
  static-prompt `ail merge-prose | client | ail parse | ail check`
  path (LLM calls back into `ail parse`/`ail check` mid-turn; an
  MCP-compatible client discovers AILang's resources/tools/prompts).
  Relocated here from DESIGN.md §"prose roundtrip" + PROSE_ROUNDTRIP.md
  by the docs-honesty-lint milestone (forward intent does not live in
  the canonical docs).
  - context: `docs/specs/2026-05-18-docs-honesty-lint.md`
```

- [ ] **Step 3: Re-run the full pin — all four tests GREEN**

Run: `cargo test --workspace -p ailang-core --test docs_honesty_pin`
Expected: 4 tests, all PASS.

---

## Task 6: Full verification

**Files:** none modified — verification only.

- [ ] **Step 1: Pin GREEN in isolation**

Run: `cargo test --workspace -p ailang-core --test docs_honesty_pin`
Expected: `test result: ok. 4 passed; 0 failed`.

- [ ] **Step 2: Full workspace test — no regression**

Run: `cargo test --workspace 2>&1 | tail -5`
Expected: all suites pass; total = prior baseline + 4 (the new pin
tests). Zero failures. (Baseline before this iter is whatever
`cargo test --workspace` reported at `928e1c0`; the only delta is +4.)

- [ ] **Step 3: Sentinel drift/coverage trio still green**

Run: `cargo test --workspace -p ailang-core --test design_schema_drift --test spec_drift --test schema_coverage`
Expected: all green — empirically confirms none of the three scans the
corrected prose regions (same invariant the effect-doc-honesty iter
relied on).

- [ ] **Step 4: Sweep 5 clean; Sweeps 1-4 reduced where corrected**

Run: `bash bench/architect_sweeps.sh; echo "EXIT=$?"`
Expected: the `=== Sweep: 5 …===` block is ABSENT (zero honesty hits —
every FIX site corrected). Sweeps 1-4: Sweep 1's hit count is reduced
versus the recon baseline (the corrected L484/L503/L655/L2027/L2065/L2135
date-anchors are gone); any residual Sweep-1 hits are the deliberate
KEEPs (L50 doc-roles pointer date, L2050 true `(iter str-concat,
2026-05-13)` provenance). EXIT may still be 1 iff a deliberate-KEEP
Sweep-1 date-anchor remains — that is expected and architect-
adjudicated, not a failure of this iter. Record the post-iter sweep
output in the per-iter journal.

- [ ] **Step 5: Workspace builds; no language/codegen change**

Run: `cargo build --workspace 2>&1 | tail -2`
Expected: `Finished` clean, zero warnings introduced by this iter.
(No `crates/**/src/**` file other than the new test was touched —
confirm with `git diff --stat -- 'crates/**/src/**'` = empty.)

- [ ] **Step 6: `ail` behaviour byte-unchanged (spec invariant)**

Run: `git diff --stat -- 'crates/' 'runtime/' | grep -v 'tests/docs_honesty_pin.rs' || echo "ONLY THE PIN"`
Expected: `ONLY THE PIN` (the sole `crates/` change is the new test
file; no checker/codegen/runtime source touched, so `ail
check`/`run`/`build` are byte-unchanged by construction — no behavioural
re-test needed).

---

## Self-review (planner Step 5) — completed inline

1. **Spec coverage:** spec Architecture layer 1 (discriminator
   subsection) → Task 3; layer 2 (corrections, DESIGN.md + satellites)
   → Tasks 4-5; layer 3 (pin + Sweep 5 + architect bullet) → Tasks
   1-2. Spec Components table rows all mapped (DESIGN.md→T3/T4,
   PROSE→T5, doc-comments→T4 catch-all if any echo surfaces, pin→T1,
   architect_sweeps.sh→T2, ailang-architect.md→T2, roadmap→T5).
   Acceptance criteria 1-8 each have a verifying step (T3S3, T4S14,
   T1+T5S3, T6S4, T2S4-5, T6S2-3, T6S5-6, T5S2). Covered.
2. **Placeholder scan:** no "TBD/TODO/implement later/similar to
   Task/add appropriate". Every edit shows verbatim before + exact
   after. The Task-4 catch-all is a fully-specified decision
   procedure with a concrete rubric, not a placeholder (spec-mandated
   procedural enumeration, L92-102).
3. **Type/name/path consistency:** `docs_honesty_pin.rs`, `norm()`,
   `read()`, sweep name "5 (honesty: …)", the bullet title "DESIGN.md
   honesty drift", the subsection heading "What this document is — and
   the honesty rule it holds itself to" are identical across Tasks
   1/2/3/6. Pin present-anchors quote the exact Task-3/Task-4
   replacement strings (cross-checked: "`--alloc=gc` selects the
   transitional Boehm backend" = T4S13 after; "type-installed; codegen
   is reserved and not yet shipped" = T4S9 after; "AILang demands
   annotations *because* the LLM author can produce them effortlessly"
   = T4S6 after; "`io/print_str` is the only built-in direct-output
   effect-op" = T4S10 after; "the lowest-common-denominator cycle and
   always works with any client" = T5S1 after; discriminator anchors =
   T3 body).
4. **Step granularity:** every step is one edit or one command,
   2-5 min. Task 4 is 15 steps but each is one site.
5. **No commit steps:** none present.
6. **Pin/replacement substring contiguity:** discharged structurally
   by `norm()` (Task 1) — all pin assertions match on
   whitespace-normalised content, so no replacement-body line-wrap can
   desync from a pin substring. Each pin present-anchor was
   word-for-word cross-checked against its Task-3/4/5 replacement
   (item 3 above). This is the recurring grep/contains line-wrap
   family (iter-revert Concern 2; effect-doc-honesty Task 2) — scrubbed
   here by the normalising mechanism, not by fragile single-line
   discipline.
7. **Compile-gate vs deferred-caller:** N/A — no signature change; the
   only `crates/` change is an additive test file. No crate-wide
   compile gate depends on a deferred edit. Task 2's Sweep-5-fires
   check (T2S3) precedes the corrections by design (makes the
   candidate list runnable — recon concern 3 chicken/egg resolved).
8. **Verification-command filter strings resolve:** `--test
   docs_honesty_pin` targets the file created in T1 (exists by the
   time any Run referencing it executes — T1 is first). `--test
   design_schema_drift --test spec_drift --test schema_coverage` —
   recon ratified all three files exist. `cargo test … design_md`
   filter (T4S15) matches the three `design_md_*` test fns named in
   T1. `grep -n "four sweeps…"` (T2S5) is an expect-empty negative
   check with an explicit "no output" expected result, so "nothing
   matched" is the asserted success, not a masked no-op. `git diff
   --stat` filters (T6S5-6) are existence/emptiness checks with
   explicit expected output.