AILang/design/contracts/0004-feature-acceptance.md

Feature-acceptance criterion

Feature-acceptance criterion

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 way to express the situation. If the feature is only used when explicitly mentioned, it isn't earning its keep — the LLM is the only author, and what the LLM doesn't reach for naturally is dead surface area.

2. The feature measurably improves correctness or removes redundancy. Either it eliminates a class of bugs structurally (the schema forbids the wrong code), or it lets the LLM express the same logic in fewer sites that have to stay consistent across 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 — see language constraints — 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. Worked example: a bare while over mutable state would pass criteria 1 and 2 yet fail criterion 3 (it reinstates iterated-mutable-state reasoning the pure core exists to remove); a hypothetical "all repetition is either structurally-decreasing recursion over an acyclic ADT or an explicit named loop" iteration story would, if it could be built without a documented-unenforced precondition, pass all three — and the fact that the 2026-05 attempt could not (it forced a silent-divergence precondition; see docs/specs/0032-iteration-discipline-revert.md) is itself the bug-class-reintroduction discriminator working as intended.

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. 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:

• Human-attractive but LLM-neutral features are cut. Point-free style, operator overloading, implicit conversions, syntactic shortcuts that hide structure. They reward human authors who enjoy compression; they cost the LLM the explicit form it relies on to keep RC, uniqueness, and effects locally legible.

• Human-hostile but LLM-friendly features are kept. JSON as canonical authoring surface; mandatory mode annotations on every fn parameter; mandatory top-level type signatures; explicit clone for shared values. These cost a human author keystrokes; they let the LLM reason locally without spending context window on cross-references.

Empirically: if a feature is proposed and the LLM does not produce it in unprompted code samples, the feature is proposed for the wrong reason. The orchestrator's job is to notice that and cut.

Ratified by: CLAUDE.md § "Feature acceptance: LLM utility" (in-tree project discipline). The brainstorm skill, which lives in the ~/dev/skills/ plugin outside the repo, applies this criterion at spec time.