Brummel
bcd41810f4
Reader-facing prose and rustdoc carried opaque shorthand like
"Decision 10", "clause-5", "mq.1", "ct.1", "eob.1", "rpe.1",
"post-mq.3", and "Iter 22b.1:" with no in-repo definition the reader
could follow. This commit replaces every such occurrence in the
durable tier the reader is most likely to land on (design/ ledger +
source //! module headers + the central /// public-item rustdoc) with
an inline content phrase plus, where applicable, a Markdown link to
the file that defines the referenced concept.
design/ ledger — 16 files:
Definition-site headings demoted from "Decision N: <title>" to
"<title>": authoring-surface, tail-calls, memory-model section in
rc-uniqueness.md, dual-allocator section, typeclass design,
effects "pure core + algebraic effects".
Cross-reference sites: "Decision 1" -> canonical-schema principle
(data-model); "Decision 3/4" -> effects + scope-boundaries; "Decision
6" -> authoring-surface; "Decision 8" -> tail-calls; "Decision 9" ->
rc-uniqueness (dual-allocator); "Decision 10" -> memory-model;
"Decision 11" -> typeclasses (model). "clause-5" -> body-link
durability gate. "clause-3" (in language-constraints) ->
bug-class-reintroduction discriminator. "mq.1/2/3", "ct.1/4",
"eob.1", "rpe.1" -> the canonical-form rule / the type-driven
dispatch / the Str carve-out / etc. "post-mq.3" -> "type-driven".
design/contracts/feature-acceptance.md: file-local "clauses 1/2/3"
-> "criteria 1/2/3" (sprachliche Kohärenz mit der File-Überschrift
"Feature-acceptance criterion"); "the clause-3 mechanism" -> "the
bug-class-reintroduction discriminator".
Source //! module headers — 24 files:
Stripped "Iter X.Y:" prefixes and "(Decision N)" / "(mq.X)" tags
from spec_drift, uniqueness, reuse_shape, migrate_canonical_types,
typeclass_22b{2,3,c}, suppress_filter, lift, mono, linearity,
diagnostic, method_dispatch_pin, method_collision_pin,
no_per_type_print_ops, mq3_multi_class_e2e, print_mono_body_shape,
print_no_leak_pin, cli_diag_human_workspace_load_error,
ct1_check_cli, prose snapshot, unbound_in_instance_method_pin,
mono_xmod_ctor_pattern, desugar.
Central /// public-item rustdoc:
ast.rs (full sweep — every "Iter X" + "Decision N" prefix
reformulated; mode/Type::Fn rustdoc now points at memory-model.md;
Constraint / SuperclassRef / InstanceDef / ClassDef rustdoc points
at typeclasses contract).
diagnostic.rs (all "(Iter X)" / "(mq.X)" tags on diagnostic codes
removed).
lib.rs (FORM_A_SPEC rustdoc points at authoring-surface.md
instead of "Decision 6").
canonical.rs (type_hash + Float-literal rustdoc).
Still outstanding (for a follow-up commit): ~500 inline `//`
code-body comments with `Iter X.Y` markers across the workspace, and
a handful of `///` rustdoc items in hash_pin / workspace_pin / lift /
mono / suppress_filter test-pin and internal-function bodies. Code
identifiers (test filenames like `mq3_multi_class_e2e.rs`, function
names like `iter18e_drop_iterative_default_preserves_hashes`) stay
verbatim per the user's "code identifiers stay verbatim" rule.
Tests: design_index_pin 5/5 + docs_honesty_pin 5/5; workspace builds
clean; full `cargo test --workspace` previously green (every
`test result: ok` line, no FAILED line).
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# 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](language-constraints.md) — 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/2026-05-16-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: `skills/brainstorm/SKILL.md`.
|