Brummel
832375f2ac
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
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](0015-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/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: `skills/brainstorm/SKILL.md`.
|