# iter effect-doc-honesty — effect-system documentation-honesty tidy

**Date:** 2026-05-16
**Started from:** c41e0e5a9e48fd0099eda8c286f10ec7a30e8e8a
**Status:** DONE
**Tasks completed:** 6 of 6

## Summary

Documentation-honesty tidy: corrected three false effect-system
claims plus their two satellite mentions across the project docs,
guarded by one new doc-presence regression pin. No language,
checker, or codegen code changed — only a doc-comment, two markdown
spec files, an internal CLI guidance string, and a new integration
test. `ail check`/`ail run` behaviour is byte-unchanged by
construction; `cargo test --workspace` 600 → 604 (the four new pin
tests, zero regressions), `cargo build --workspace` clean. The
three sentinel drift/coverage tests (`design_schema_drift`,
`spec_drift`, `schema_coverage`) stay green, empirically confirming
none scans the effect-prose region.

## Per-task notes

- iter effect-doc-honesty.1: new pin `crates/ailang-core/tests/effect_doc_honesty_pin.rs`
  (4 tests asserting fiction strings absent + corrected anchors
  present across the 4 edited files); authored first, ran RED 0/4
  for the right reason (TDD: RED before corrections).
- iter effect-doc-honesty.2: `docs/DESIGN.md` Decision 3 row-polymorphic
  block → flat/unordered/closed set-equality + Diverge-reserved
  wording; line-2722 "IO and Diverge ops" bullet → IO-only +
  Diverge-reserved bullet. `design_md_effect_prose_is_true` GREEN.
- iter effect-doc-honesty.3: `crates/ailang-core/src/ast.rs` `Term::Do`
  doc-comment effect-handler-table-at-link-time fiction → real
  mechanism (typecheck against `Env::effect_ops`, `lower_effect_op`
  literal-match codegen). `term_do_doc_comment_is_true` GREEN.
- iter effect-doc-honesty.4: `crates/ailang-core/specs/form_a.md`
  line-226 "currently `IO` and `Diverge`" → IO-built-in-op /
  Diverge-reserved; rule-3 "`Diverge` for `diverge/*`" →
  io/print_str-is-the-only-built-in-op. `form_a_spec_effect_names_are_true`
  GREEN.
- iter effect-doc-honesty.5: `crates/ail/src/main.rs` merge-prose
  CONTRACT effect-annotation bullet dropped the non-existent
  `(effects Diverge)` example. Whole pin 4/4 GREEN.
- iter effect-doc-honesty.6: full verification — whole pin 4/4,
  `cargo test --workspace` 604/0 (600 prior + 4), drift/coverage
  trio green, `cargo build --workspace` clean.

## Concerns

- Task 2: the plan's verbatim Task-2 replacement body soft-wrapped
  the phrase "flat, unordered,\nclosed set of effect names"
  mid-phrase, which contradicts Task-1's single-line pin substring
  `"flat, unordered, closed set of effect names"` AND the plan's
  own self-review item 6 ("every pin substring is single-line — the
  documented iter-revert grep-wrap failure mode is avoided"). The
  two authoritative artefacts (exact replacement text vs. exact
  pin) could not both be applied verbatim. Resolved by preserving
  the exact corrected *wording* (byte-identical to the plan's
  intent) and the exact pin (Task 1, unchanged), moving only the
  soft-wrap column so the asserted phrase stays contiguous on one
  line. No wording added/dropped/changed. This is a planner
  self-review-item-3 cross-check gap (the asserted-substring vs.
  replacement-body check did not account for the replacement body's
  own line wrap) — orchestrator may want to tighten the planner's
  pin/replacement-body wrap cross-check.

## Known debt

- (none) — the tidy is self-contained; no deferred follow-up.

## Files touched

- `crates/ailang-core/tests/effect_doc_honesty_pin.rs` (new — the pin)
- `docs/DESIGN.md` (Decision 3 + "What is not supported" bullet)
- `crates/ailang-core/src/ast.rs` (`Term::Do` doc-comment)
- `crates/ailang-core/specs/form_a.md` (line 226 + rule 3)
- `crates/ail/src/main.rs` (merge-prose CONTRACT string)

## Stats

bench/orchestrator-stats/2026-05-16-iter-effect-doc-honesty.json