AILang/design/contracts/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 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 clauses 1 and 2 yet fail
   clause 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/2026-05-16-iteration-discipline-revert.md`) is itself
   the clause-3 mechanism 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: `skills/brainstorm/SKILL.md`.