Brummel
19dc42f5ca
The first formal-links milestone shipped clause-5 + 8 links across the
existing file layout. Browsing surfaced that file-only granularity is
only as precise as the file boundaries — three files mixed two or
three navigation targets under one address, so the 8 links could not
multiply without ambiguity. This commit fixes the substrate, then
applies the sweep the original milestone deferred.
Splits (each extracts an already-self-contained section into its own
file so links land on the topic, not the parent doc's TOC):
contracts/typeclasses.md
→ +contracts/prelude-classes.md (Eq/Ord/Show ships, polymorphic `print`)
→ +contracts/method-dispatch.md (5-step dispatch rule, candidate index)
contracts/memory-model.md
→ +contracts/language-constraints.md (the 4 binding constraints
making RC sound without a
cycle collector)
models/authoring-surface.md
→ +models/prose-projection.md (Form-B / `ail prose` / merge-prose)
Each new file enters design/INDEX.md as its own row (three contracts
share show_no_instance_e2e.rs / uniqueness.rs as ratifying tests;
prose-projection is a model). Two pre-existing links rebind to the
new topic-files (memory-model.md → method-dispatch.md;
float-semantics.md → prelude-classes.md).
Link sweep: 8 → 88 formal Markdown links over 23 files. Every file
in design/contracts/ + design/models/ now has at least one outgoing
link; the tree is fully connected. Links are file-relative
`[label](path)` per the established convention, fenced code blocks
are skipped (a `](` inside ```jsonc``` is literal text), the durable
tier (design/ + crates/ + runtime/) is enforced by clause-5.
Tests:
- design_index_pin.rs (5/5 clauses): clean-cut, INDEX resolution,
ratifying-test resolution, no decision-record prose in contracts/,
body links durable + resolving.
- docs_honesty_pin.rs (5/5): one assertion rebinds from typeclasses.md
to prelude-classes.md (where the gated sentence now lives);
design_corpus widens to include the 4 new files so the Wunschdenken
/ doc-archaeology sweeps continue to cover everything that used to
live in the parents.
No spec/plan/journal for this batch — interactive collaboration after
the milestone closed; the user gated the splits explicitly before the
sweep.
3.8 KiB
Feature-acceptance criterion
Feature-acceptance criterion
A proposed feature ships only if all three hold:
-
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.
-
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.
-
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
whileover 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; seedocs/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
clonefor 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.