design: feature-acceptance criterion clause 3 + iteration-discipline roadmap milestone

Sharpen the feature-acceptance criterion (DESIGN.md, mirrored in the
brainstorm gate) with a third conjunctive-necessary clause: a feature
reintroduces no bug class the core constraint exists to eliminate.
Criterion 1 ("an LLM reaches for it") does not discriminate — an LLM
reaches for every construct native to its imperative training
distribution, so utility alone would launder the imperative paradigm
back in one construct at a time. Clause 3 is the discriminator; a
documentation note is not a reshape (the gate is whether the wrong
code fails to typecheck).

Record the decided iteration story as a P1 milestone: structural
recursion permitted (total-by-construction under Decision 10's
acyclic-ADT invariant) + named loop/recur as the only other
repetition + tail-app retired. Discharges fieldtest finding F1 without
introducing an imperative construct; closes the residual "forgot to
mark tail" trap completely; unifies with Decision 10 (acyclic values
AND acyclic implicit call graph). Supersedes the "while-loops legal"
scope bullet of the Stateful-islands milestone, which is amended for
internal consistency. The escaping-state path (ref/MutArray/Stateful)
is unaffected and stays in Stateful-islands.
This commit is contained in:
2026-05-15 12:53:20 +02:00
parent 1ff7e811af
commit 9973546e3b
3 changed files with 116 additions and 9 deletions
+28 -3
View File
@@ -70,7 +70,7 @@ is the default.
## Feature-acceptance criterion
A proposed feature ships only if both hold:
A proposed feature ships only if all three hold:
1. **An LLM author naturally produces code that uses it.** Without
prompting toward the feature, the LLM reaches for it as the clean
@@ -86,10 +86,35 @@ A proposed feature ships only if both hold:
edits. Aesthetic appeal — "feels elegant", "is idiomatic" — does
not count.
3. **The feature reintroduces no bug class the core constraint exists
to eliminate.** Criterion 1 is necessary but does *not*
discriminate: an LLM reaches for *every* construct native to its
imperative training distribution, so "the LLM reaches for it" is
satisfied by exactly the constructs AILang most deliberately
refuses. A feature can pass 1 and 2 — LLMs reach for it unprompted,
and it removes redundancy — and still be a regression, because it
reinstates the error surface the pure core, local-reasoning, and
RC-acyclicity guarantees were built to remove. The decisive
question is whether the construct re-opens a class of mistakes
(iterated-mutable-state reasoning, silently-unbounded recursion,
reference cycles) that a foundational invariant closes. If it does,
it is cut even when 1 and 2 hold — *or* it must be reshaped until
the bug class is structurally impossible rather than merely
discouraged. A documentation note is not a reshape; the
discriminator is whether the wrong code fails to typecheck, not
whether a guideline advises against it. The canonical worked
example is the iteration story: a bare `while` over mutable state
passes 1 and 2 yet fails 3 (it reinstates iterated-mutable-state
reasoning); structural recursion over an acyclic ADT and a named
loop/recur point pass all three (the bug class is closed by
construction, not by advice).
This is the positive complement to the CLAUDE.md rule that
implementation effort is not a rationale: cost is not a reason *for* a
feature, and neither is human aesthetic preference. The only thing
that is, is LLM-author utility.
feature, and neither is human aesthetic preference. LLM-author utility
(1, 2) is necessary; criterion 3 is the discriminator that keeps
utility from laundering the imperative paradigm back in one construct
at a time.
Two corollaries: