@am_shork/attest 0.1.7 → 0.2.1

package/CHANGELOG.md

@@ -5,118 +5,378 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Versioning
+
+Under 0.x SemVer a breaking change bumps the **minor**. "Breaking" means it
+changes the exit code of an existing valid setup, rejects previously-valid
+input, removes/renames a public API or `--json` field, or changes a default
+runtime behavior an existing invocation relies on — diagnostic message text is
+not API.
+
 ## [Unreleased]
 
-### Under consideration (non-breaking, not implemented)
-
-- **`attest check` is described as static validation, but it executes every
-  `*.reqs.ts` it finds.** Reading a registry means evaluating the module, via
-  Vite, anywhere under the project root. That is the same threat model as
-  `vitest run` — except `check` is advertised as "static structural validation
-  (fast CI pre-check)", which is exactly the wording that gets it scheduled
-  ahead of, or outside, whatever sandbox the test run is given. On a fork MR,
-  a `*.reqs.ts` with a top-level `fetch` is enough.
-  *The candidate fix, and why it is more than a patch:* read the registry from
-  the AST instead — the compiler API is already the parser layer's tool — for
-  `check`, `cover` and `render`, keeping the loader for `verify` and `archive`,
-  which run the suite anyway and so gain nothing from avoiding evaluation.
-  This makes "a registry is a literal" a design contract rather than a
-  limitation: `params: { maxMb: MAX_MB }` imported from application code
-  already violates the single-source rule the framework exists to enforce,
-  since the value's real owner is elsewhere. It would also turn `render`'s
-  purity from a convention into something structurally guaranteed — today a
-  `Date.now()` in a registry makes `--check` fail forever.
-  *What blocks it:* a non-literal registry must become an ERROR, never a silent
-  fallback to evaluation, or the guarantee is worth nothing — so this is a
-  breaking change for repos that compute their registry, and needs an explicit
-  opt-out (`--eval`) rather than a warning period, since a warning period
-  spends the whole transition still evaluating. The real risk is extractor
-  fidelity: `-1` is a unary expression, `1_000` is not `Number(text)`,
-  `as const` needs unwrapping, and any of those misread would break a repo the
-  change is supposed to leave untouched. Differential testing against the
-  current loader over every fixture is the prerequisite.
+### Under consideration
+
+Queued from the skills-manager adoption report (0.2.0, 41 requirements / 106
+scenarios, plain-TS). **Nothing below is built.** An entry here is a decision to
+ship, not a claim that it ships; each moves into `Added` / `Changed` / `Fixed`
+when it does, and this heading is deliberately not one of those, so no reader
+can take the section for a release note. The report's other proposals were
+declined and are not recorded.
+
+- **A report of N issues sharing one `code` should say so once.** The 0.1.1 →
+  0.2.0 upgrade printed six `registry-not-static` ERRORs in a row — one per
+  registry file, every one caused by the same prose written as `'…' + '…'` — and
+  left the reader to work out that they were one cause and one mechanical fix.
+  A summary line will name the shared cause when a code repeats; the per-file
+  lines stay exactly as they are, because they are what makes a diagnostic
+  clickable. Human output only — a summary that became an `Issue` would carry a
+  `code` into `--json`, `summary` and `hasError`, which is a report-contract
+  change and not what this is.
+
+## [0.2.1] - 2026-07-26
+
+The type layer stopped charging for the one behaviour the tool rewards, and
+three limits an adoption had to find on its own are now written down.
+
+### Added
+
+- **Reading a param cost a cast, and the cast was charged on the one behaviour
+  the tool rewards.** `defineRequirements` returned `Registry`, so every param
+  was the full `string | number | boolean | Array<…>` union and
+  `reqs[id].params.x` had to be converged at each read site — the reporting
+  adopter wrote `str()` / `strList()` helpers to do it. `possible-drift` goes
+  quiet precisely when a scenario reads `.params`, so the type layer was taxing
+  the behaviour the anti-drift heuristic exists to reward. It is now generic
+  over its argument with a `const` type parameter: `params.idleTimeoutMin` is
+  `30`, `params.vendorDirs` is an array of the strings written there, and a
+  declared ID is known to exist, so `reqs['AUTH-3']` needs no `!` under
+  `noUncheckedIndexedAccess`. Removing the casts from Attest's own `self/`
+  specs closed 21 latent type errors there. No runtime behaviour and no `--json`
+  change: since 0.2.0 the analysing commands read the registry from the AST, so
+  this type has no bearing on anything the engine sees.
+  **A widening, deliberately.** A `const` type parameter would infer array
+  literals as tuples — `readonly` ones under a constraint that admits them —
+  and neither is assignable to the mutable `Array<number | string | boolean>`
+  the schema parses to, which would have broken `const reqs: Registry =
+  defineRequirements({…})` and every `const xs: string[] = req.params.foo`; the
+  mapped type collapses them back to `E[]`. The result is still intersected with
+  `Registry`, so its index signature survives and `reqs[id]` with an `id: string`
+  — a shared test helper — still resolves, as does a param the registry does not
+  declare. **What that costs**, against the intent recorded when this was queued:
+  a mistyped literal `reqs['TYPO-9']` is *not* rejected outright. Rejecting an
+  unknown key and accepting a `string` one are the same question asked of one
+  index signature, and it cannot answer both ways; the fallback is what keeps
+  this non-breaking, so it wins. The weaker half is real — an unknown ID misses
+  the declared keys and resolves through the index signature, so under
+  `noUncheckedIndexedAccess` reading through it is an error where `reqs['AUTH-3']`
+  no longer is — and a wrong ID is an `unknown-req-id` ERROR from `check`
+  regardless, which reads registry and specs together. The type layer is the
+  second reader here, not the only one.
+- **Three things an adoption had to discover for itself.** Documentation only —
+  no behaviour changed, and each is a property the design deliberately has.
+  **`check` has no detection power over a params change**: editing a value
+  (`'main'` → `'trunk'`, an entry dropped from a nine-element list) leaves it at
+  `✓ No issues`, because `check` executes nothing and nothing became unbound or
+  uncovered. The single source makes the value impossible to *diverge*, which is
+  a different and stronger claim than announcing that it *moved* — but "params
+  are the single source for values that change" reads easily as "`check` guards
+  them", and what actually guards them is a scenario asserting on the value it
+  read. Now stated where params are introduced (README, design §2, the prompt
+  guide) and recorded as a limit in design §11, next to the others.
+  **`verify` does not read your `vitest.config.ts`**: the child run starts
+  isolated, so a verdict never depends on ambient configuration — which also
+  means framework code gets no transforms, no DOM and no aliases until
+  `--vitest-config` points it at one. The flag was documented in the README; the
+  trade-off behind it now sits in design §5.4, where the run scope is described,
+  because that is where a reader meets the isolation.
+  **A template literal keeps its whitespace**: one with no substitution reads
+  statically and is accepted, but preserves every newline and space of
+  indentation, and `render` copies the statement into the Markdown as written —
+  so editor-friendly wrapping lands in the generated document. This is the
+  reason registry prose is written as one long single-line string, which was
+  folklore until now.
+- **A codemod for the 0.2.0 `registry-not-static` migration.** Collapsing
+  multi-line `'…' + '…'` prose into one literal is mechanical and was done by
+  hand across 21 requirements in the first reported adoption. The 0.2.0 entry
+  now carries a compiler-API script that does it, tested on the shapes that make
+  it awkward: mixed quote styles, an apostrophe inside the prose, a template
+  literal in the chain, and a numeric `1 + 2` it must leave alone.
+- **Type tests, and a suite that runs them.** The repo had none, and this change
+  is entirely type-level: no runtime test and no `verify self` run could observe
+  a regression in it. `tests/registry-types.spec-d.ts` pins the narrowing, both
+  compatibility promises and the trade-off above; `vitest run` now typechecks in
+  the same pass (`tsconfig.typecheck.json`, which unlike the build project covers
+  `tests/` and `self/` — neither had ever been through a compiler). `DefinedRegistry`
+  is exported for consumers that need to name the type.
+
+- **A `{placeholder}` in a `rationale` reached the document unread.** `render`
+  interpolates `statement` and nothing else, and `unbound-param` only scans
+  statements, so braces written into a rationale passed through every check and
+  landed verbatim in the generated Markdown. The mistyped placeholder is the
+  obvious case; the one that misleads is the **correctly spelled** one, where
+  the author declared the param and simply picked the wrong field — nothing was
+  unbound, so nothing fired, and the document reviewers and audit read showed a
+  placeholder where a value was meant. A new `rationale-placeholder` WARNING now
+  reports any `{name}` in a rationale, bound or not.
+  Deliberately not the two alternatives. Extending `unbound-param` to rationales
+  would cover only the undeclared half — the half that misleads least. And
+  making `render` interpolate rationales would change the bytes of every
+  committed rendering, turning `render --check` red on an upgrade where the user
+  moved no intent, which this file already treats as breaking for that surface.
+  **A placeholder inside a Markdown code span is not reported.** That exclusion
+  came from dogfooding: the first run against Attest's own registry flagged
+  ATX-14, whose rationale explains that `` `{toString}` `` *looks* bound — prose
+  about a placeholder, not a misfiled one, and the only way to write a
+  requirement whose subject is the syntax itself. A rationale is Markdown and
+  `render` leaves a code span exactly as written, so a backticked token is
+  already marked as quoted.
+  WARNING sits below the `hasError` predicate that `ok`, `--json` and the exit
+  code all read from, so an existing green registry with braces in a rationale
+  gains a line of output and keeps its verdict. A new `code` on the existing
+  `Issue` shape is additive: `schemaVersion` stays `1`.
+
+## [0.2.0] - 2026-07-26
+
+Three things that could each end a run with the wrong verdict: a registry read
+by executing it, a green that attested nothing, and a red about code Attest was
+never pointed at.
+
+### Security
+
+- **`attest check` described itself as static validation while executing every
+  `*.reqs.ts` it found.** Reading a registry meant evaluating the module, via
+  Vite, anywhere under the project root — the same threat model as
+  `vitest run`, behind wording ("static structural validation (fast CI
+  pre-check)") that is exactly what gets a command scheduled ahead of, or
+  outside, whatever sandbox the test run is given. On a fork MR, a `*.reqs.ts`
+  with a top-level `fetch` was enough to reach CI secrets.
+  `check`, `cover` and `render` now read the registry from the **AST** — the
+  compiler API was already the parser layer's tool — and run no line of the
+  project. `verify` and `archive` still evaluate: they run the whole suite
+  anyway, so declining to run one more module would buy them nothing.
+  The extracted object literal is handed to the same `RegistrySchema`
+  `defineRequirements` calls, so a literal registry keeps its behaviour, its
+  codes and its diagnostic wording unchanged. That equivalence is not an
+  assertion: a differential suite reads every `*.reqs.ts` in the repo, and every
+  literal form that could be misread (`-1`, `1_000`, `0x10`, `30.0`, `1e3`, a
+  template literal with no substitution, `as const`, `satisfies`), through both
+  readers and requires the two registries to be deeply equal — down to key
+  order.
+  It also turns `render`'s purity from a convention into a structural
+  guarantee: a registry can no longer contain a `Date.now()` that makes
+  `render --check` fail forever.
+
+### Changed
+
+- **BREAKING: a registry must be a literal.** A registry `check`, `cover` or
+  `render` cannot read from the source is a new `registry-not-static` ERROR,
+  pointing at the line that stopped it. There is deliberately no fallback to
+  evaluation — a reader that quietly runs the file when extraction fails
+  guarantees nothing — and deliberately no warning period, which would spend
+  the whole transition still evaluating. `--eval` is the named way back, on all
+  three commands, and restores the old behaviour exactly.
+  This makes "a registry is a literal" a design contract rather than a tooling
+  limitation: `params: { maxMb: MAX_MB }` imported from application code already
+  violates the single-source rule the framework exists to enforce, because the
+  value's real owner is elsewhere. Affected repos have two migrations, and
+  inlining the value is the one that fixes the underlying problem.
+  A registry file may still be written as `const reqs = defineRequirements({…});
+  export default reqs;`, and may import `defineRequirements` under any alias or
+  through a namespace.
+  **Migrating concatenated prose.** The common shape is a statement or rationale
+  wrapped across lines as `'…' + '…'`, which is a computation and so no longer
+  reads. Collapsing it is purely mechanical — 21 requirements by hand in the
+  first reported adoption — so it is worth a codemod. Save this at the project
+  root and run it over the registry files; it rewrites only concatenations whose
+  every operand is a string (or substitution-free template) literal, leaving
+  `1 + 2` and anything with an identifier in it alone:
+
+  ```js
+  // flatten-reqs.mjs — node flatten-reqs.mjs requirements/*.reqs.ts
+  import ts from 'typescript';
+  import { readFileSync, writeFileSync } from 'node:fs';
+
+  const flat = (n) =>
+    ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.PlusToken
+      ? [flat(n.left), flat(n.right)].every(Boolean) && flat(n.left) + flat(n.right)
+      : (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n)) && n.text;
+
+  for (const file of process.argv.slice(2)) {
+    const src = readFileSync(file, 'utf8');
+    const sf = ts.createSourceFile(file, src, ts.ScriptTarget.Latest, true);
+    const edits = [];
+    const visit = (n) => {
+      const text = flat(n);
+      // the whole chain is one edit, so do not descend into it
+      if (text !== false && ts.isBinaryExpression(n)) return void edits.push([n.getStart(sf), n.getEnd(), text]);
+      n.forEachChild(visit);
+    };
+    visit(sf);
+    let out = src;
+    for (const [start, end, text] of edits.reverse())
+      out = `${out.slice(0, start)}${JSON.stringify(text)}${out.slice(end)}`;
+    if (edits.length) writeFileSync(file, out), console.log(`${file}: ${edits.length} collapsed`);
+  }
+  ```
+
+  It emits double-quoted strings (`JSON.stringify` does the escaping, so prose
+  containing an apostrophe survives); run the formatter afterwards. Write the
+  result as one long line rather than re-wrapping it — a template literal reads
+  statically but keeps its newlines and indentation, and `render` copies the
+  statement into the Markdown exactly as written.
+  The `--json` envelope is unchanged: `registry-not-static` is a new `code` on
+  the existing `Issue` shape, which is additive, so `schemaVersion` stays `1`.
+  `vite` remains a peer dependency — `verify` and `archive` run the suite through
+  it — but `check`, `cover` and `render` no longer start a Vite server at all.
+- **BREAKING: a vacuous green stops passing.** `attest verify` on a root with no
+  requirements printed `✓ No issues.` and exited `0`, because `passed` is "no
+  failing tests" and a run with nothing in it has none. It is now an `empty-spec`
+  ERROR, so `ok` becomes false and the exit code follows the existing `hasError`
+  path. The empty directory is the harmless version; the one that matters is the
+  repo whose registry stopped being found — a renamed folder, a moved root — where
+  the tests still run, still pass, and the report is indistinguishable from a real
+  green. Deliberately narrower than "no scenario executed": with at least one
+  requirement, a missing scenario is already `uncovered-requirement` and a declared
+  scenario that never ran is already `declared-not-run`, so firing on those would
+  only double-report a run that is red anyway. *Breaking:* a root that attests
+  nothing flips from exit 0 to exit 1 — which is the point, since it attested
+  nothing.
+- **BREAKING: a run executes only the spec files that declare a `requirement()`.**
+  `verify` swept every `*.spec.ts` under the root into a child run with no
+  aliases, no DOM and no plugins, so pointing it at the root of a repo that
+  already had a suite produced a guaranteed red about code Attest was never asked
+  to attest. That was the first thing a mid-project adopter saw, and it was not a
+  finding about their intent layer at all. The run scope is now derived from the
+  static plan, which already records which files declare intent. `archive` gets
+  the same scope, for the same reason: a change must not fail its gate because an
+  unrelated suite shares its root. *Breaking:* a repo relying on the sweep to run
+  requirement-less specs sees a different set execute — and `attest` was never the
+  right thing to run them with. Unchanged for `check`, `cover` and `render`, which
+  only ever counted `requirement()`/`scenario()` calls and so never had the bug.
+
+### Added
+
+- **`verify` reports what it looked at.** The human summary leads with
+  `— 20 requirements / 41 scenarios, 0 error, …` and is preceded by the run
+  scope (`Running 12 spec files`, plus how many were located and skipped for
+  declaring no `requirement()`). `--json` carries the same four numbers under
+  `counts`. This is the companion the change above needs: scoping the run means a
+  file whose `requirement()` the parser fails to see is now dropped from the run
+  rather than failing in it, and the gap between "located" and "in scope" is where
+  that would show. It is also a second line of defence against a vacuous green — a
+  report that says `0 requirements` cannot be misread as a full pass. `counts` is
+  a new optional field on an existing envelope, so `schemaVersion` stays `1`.
+
+### Fixed
+
+- **The design document described three anti-drift mechanisms; two exist.**
+  §6's mechanism 2, "red/green expectation tracking" — a new requirement's
+  scenarios must be red while a change is in progress and green at archive time,
+  with the framework blocking on a mismatch — was written as shipped behaviour,
+  with a strength rating, next to two mechanisms that are real. It was never
+  built. What ships is the weaker half: §8's gate requires green at archive time,
+  but nothing records or requires the earlier red, so a scenario that was green
+  from the start — asserting nothing — passes it. Anyone who budgeted their own
+  review against three mechanisms was covered by two. Now marked
+  **(not implemented)** inline, with the gap named. Same treatment for
+  `/atx:propose` and `/atx:apply` in §9, which are likewise designed and unbuilt;
+  the manual path (`changes/<name>/` + `attest archive`) is spelled out beside
+  them.
+- **Documentation described an API that does not exist.** §1's architecture
+  diagram — the first thing a reader meets — showed `@covers('AUTH-3')` and a
+  `covers(id)` back-link, an early spelling of what shipped as
+  `requirement(id)` / `scenario(name)`, with coverage reconstructed from the
+  `[reqId]` suite name. §5.4 already described the real mechanism, so the
+  document contradicted itself. The registry and spec samples also imported from
+  a bare `'attest'`, and §10 declared the package as `attest` exporting only
+  `.` — the published package is `@am_shork/attest` and has exported `./define`
+  since 0.1.2, which is the import path README tells users to write. These are
+  samples meant to be copied, and this repo's docs are also fed to agents, so a
+  stale name becomes generated code.
+- **Smaller documentation corrections.** §1 called its own three-row table "the
+  two core reports"; the Coverage row attributed coverage to runtime collection
+  alone, when `check`/`cover` read it statically. §4 listed the SHALL/MUST rule
+  under structural validation, where it is enforced by the schema one layer up.
+  §5.3's `Issue` sample omitted the `reqId` field the same snippet sets. §7
+  cited "§6" for a section of OpenSpec's analysis, not this document's §6.
+  The README's `--json` sample claimed `"version": "0.1.2"`, and its
+  prerequisites section was headed "Requirements" — a term this project already
+  uses for the intent layer.
+- **The feedback template and the GitLab issue template each claimed to be the
+  other.** They are not identical, and should not be: `outcome:` is for
+  maintainer-authored reports and `verdict:` for outside ones, so the issue form
+  is deliberately the outside-reporter subset. Both now say so, the key rule is
+  stated where it can be read, and the issue form gained the mid-project
+  follow-up its own `adoption: brownfield` field was asking for and never posed.
+
+Two checks now hold the parts of this that can be held mechanically, in
+`tests/docs-consistency.spec.ts`: the source cites design sections by number in
+58 places, and every citation must resolve in both languages, so inserting a
+section can no longer silently repoint them; and any JSON sample in the README
+that identifies itself as attest output must carry the current `version` and
+`schemaVersion`. Neither can catch a section that describes something unbuilt —
+that is what the inline marker is for.
+
+## Considered and rejected
+
+Decisions **not** to build something, kept where they can be found before the
+same candidate is proposed again. Nothing here shipped, so nothing here belongs
+to a release — this section is deliberately outside the version history and does
+not move when one is cut.
+
 - **Two gaps in the intent layer: nothing resists a bloated requirement, and
-  nothing resists a duplicated one.** Recorded as a design note, with the
-  evidence that currently blocks each candidate fix.
-  *Against bloat, what already works:* `uncovered-requirement` being an ERROR is
-  the real mechanism — every requirement costs an executable scenario, so "the
-  system should be maintainable" cannot be written and left standing. That is a
-  genuine cost function on the intent layer, which prose SDD does not have.
-  *What doesn't:* coverage is binary (≥1 scenario), so five sharp requirements
-  cost five mandatory scenarios while one requirement lumping five obligations
-  together costs one. **The rule as designed rewards lumping**, and the engine
-  has no notion of "one requirement = one obligation". Attest's own registry
-  shows it: `ATX-5` carries two obligations under one SHALL, `ATX-9` three
-  clauses, `ATX-10` two.
-  *Against duplication and contradiction:* effectively nothing. Every
-  cross-requirement check in the engine is keyed on the **id** —
-  `duplicate-requirement` (same id in two registry files), `rename-target-exists`,
-  and `add-conflict`, which content-compares only when ids collide. Two
-  requirements under different ids that contradict each other (`AUTH-3` expires a
-  session after 30 minutes, `SESS-7` says sessions never expire) pass schema,
-  `check`, `verify` and the archive gate, each green under its own scenario.
-  `params` does not help, and the reason is structural: it is an
-  **intra-requirement** mechanism. It pins one requirement's statement to its own
-  assertions; two requirements may each own a `params` entry of the same name with
-  different values and both stay green. Design §11 admits semantic drift needs
-  human review — semantic *duplication* is the same category and is not mentioned
-  at all. This matters most in the workflow the package exists for: an agent asked
-  for a new behaviour is additive by default, and will add `SESS-7` rather than
-  `modified: { 'AUTH-3': … }`. The delta workflow provides the correct path; it
-  does not force it, and the one counter-pressure (a new requirement costs a
-  scenario) does not deter an agent that will happily write one.
-  *Candidate 1 — `divergent-param` (WARNING):* the same param name declared in
-  more than one requirement with different values, scoped to a shared id prefix
-  (`AUTH-*` vs `AUTH-*`) to limit collisions between unrelated domains. It would
-  not detect abstract contradiction, only its most common concrete form: one named
-  constant pinned twice, differently. **Blocked, and by this repo's own registry:**
-  `idleTimeoutMin` is `15` in `ATX-3` and `30` in `ATX-10`, both under the same
-  prefix, and both legitimate — unrelated illustrative fixtures. So the false
-  positive is not hypothetical, and prefix scoping does not save a repo that uses
-  one prefix throughout. The mechanism needs a way to declare two params
-  independent before it can ship, and that escape hatch is undesigned.
-  *Candidate 2 — `compound-requirement` (WARNING):* more than one RFC-2119
-  keyword in a single `statement` is objectively more than one obligation, which
-  directly opposes the lumping incentive above. Cheap and deterministic, but its
-  reach is narrow: over the 12 self requirements it flags exactly one (`ATX-10`,
-  `SHALL … and MUST …`) and misses both `ATX-5` and `ATX-9`, which pack multiple
-  clauses under a single keyword.
-  *Explicitly rejected:* similarity matching between statements (token overlap,
-  embeddings). That reintroduces the fuzzy AI comparison design §0 exists to
-  remove. Real semantic duplication needs judgement and belongs to human review
-  at the propose stage; the engine should not pretend to prove it.
-  Both candidates are WARNING-level, so neither would change the exit code of an
-  existing valid setup (only ERROR fails a run) — they are listed here rather than
-  under 0.2.0 for that reason.
-
-The breaking items below are held for **0.2.0** (under 0.x SemVer a breaking
-change bumps the minor). "Breaking" means it changes the exit code of an existing
-valid setup, rejects previously-valid input, removes/renames a public API or
-`--json` field, or changes a default runtime behavior an existing invocation
-relies on — diagnostic message text is not API.
-
-### Planned for 0.2.0 (breaking)
-
-- **A vacuous green stops passing.** Today `attest verify` on a spec that ran no
-  scenarios (an empty or requirement-less directory) prints
-  `✓ No issues. — 0 error, …` and exits `0`, because `runAndCollect` reads "no
-  failing tests" as `passed`. `verify` will instead emit a new `empty-spec`
-  ERROR when zero scenarios executed (or the registry has zero requirements),
-  so `ok` becomes `false` and the exit code follows the existing `hasError`
-  path. Wires up `hasSpecs()` (present in `pipeline.ts`, never called today).
-  *Breaking:* an "empty directory → exit 0" run flips to exit 1 — which is the
-  point, since that run attests nothing. *Non-breaking companion (may land
-  earlier in 0.1.x):* requirement/scenario counts in the summary line
-  (`— 33 requirements / 59 scenarios, 0 error, …`).
-- **Default spec discovery ignores files with no `requirement()`.** `verify` at
-  a repo root currently sweeps every `**/*.spec.ts` — including a pre-existing
-  suite — into a runner with no aliases/DOM, a guaranteed red unrelated to the
-  code. The default will change to run only spec files that declare at least one
-  `requirement()`, so an incumbent suite is left untouched without forcing a
-  directory layout. *Breaking:* a repo relying on the root scan to pick up
-  requirement-less specs sees a different set run. *Non-breaking companion (may
-  land earlier in 0.1.x):* a pre-run report of how many spec files were located
-  and how many contain a `requirement()` call.
+  nothing resists a duplicated one.** The gaps themselves are described in design
+  §11, which is where a permanent property of the design belongs. What is kept
+  here is the list of mechanisms tried and what killed each, so the same three
+  are not proposed again without new evidence. All three were scored against
+  every registry this repo ships *before* any was written into the engine — the
+  order `divergent-param` was originally designed in the wrong way round. The
+  measurement is runnable in `tests/intent-rule-candidates.spec.ts` and fails
+  when a requirement is added without a hand-labelled obligation count, because
+  the reach figure once quoted here went stale exactly that way.
+  *`compound-requirement` (WARNING) — rejected.* More than one RFC-2119 keyword
+  in one `statement` is objectively more than one obligation. Measured: of the 7
+  requirements in the corpus carrying more than one, it flags 2 (`ATX-10`,
+  `ATX-21`) and misses `ATX-5`, `ATX-9`, `ATX-13`, `ATX-14`, `ATX-17` — every
+  one that packs clauses under a single keyword, which is the form the coverage
+  incentive actually rewards. A wider variant (keyword plus a coordinating
+  `and`/`while`/`;`) reaches 6 of 7 with one wrong hit, so reach is not the
+  deciding argument.
+  This is: both variants are silenced by deleting the word that triggered them,
+  and neither can tell that deletion from a real split. `SHALL do A and MUST do
+  B` clears the warning as `SHALL do A and do B` — same two obligations, one
+  fewer normative keyword. A rule whose cheapest fix degrades the artifact it
+  protects does not ship.
+  *`divergent-param` (WARNING) — rejected.* One param name declared with
+  different values in two requirements sharing an id prefix. Measured: it fires
+  twice on this repo and both firings are wrong — `idleTimeoutMin` (`15` in
+  `ATX-3`, `30` in `ATX-10`), unrelated illustrative fixtures, and `code`
+  (`registry-not-static` in `ATX-17`, `empty-spec` in `ATX-18`,
+  `rationale-placeholder` in `ATX-21`), diagnostics that could not possibly
+  agree. The second arrived on its own when `ATX-18` was added and grew a third
+  member on its own again when `ATX-21` was, which is the more damning half: a
+  generic param name collides more often as a registry grows, so the
+  false-positive rate rises with adoption — the opposite of what a shippable rule
+  does. Still zero true positives across 25 requirements. The escape hatch it was blocked on has since been designed
+  and does not rescue it: with no config file the only workable shape is an
+  additive `independentParams?: string[]` on the requirement (a CLI flag is
+  per-invocation for what is a permanent property of two requirements; changing
+  the `params` shape rejects every existing registry). Viable, but it is
+  permanent schema surface for a rule with no demonstrated true positive, and in
+  practice it would be written *after* the warning fires — a one-line silencer.
+  *Countable obligations (breaking) — rejected.* An `obligations: string[]` per
+  requirement, with coverage counted per obligation, removing the lumping
+  incentive at the source instead of detecting it afterwards. Rejected because
+  the **id is already that unit**: splitting into two ids costs two scenarios and
+  buys the same incentive with no new concept (`ATX-11`/`ATX-12` are exactly that
+  split). It would touch the parser, coverage, `render`, `SPEC.md`, delta apply
+  and the `--json` schema, and it relocates the incentive rather than removing
+  it — nothing can force the array to be complete.
+  *Not considered:* similarity matching between statements (token overlap,
+  embeddings). That reintroduces the fuzzy comparison design §0 exists to remove;
+  real semantic duplication needs judgement and belongs to human review at the
+  propose stage.
 
 ## [0.1.7] - 2026-07-26
 
@@ -438,7 +698,9 @@ Initial release.
   (MIT), whose four-stage engine and diff-first change model Attest's
   architecture is adapted from (re-implemented from scratch, no source copied).
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.1.7...main
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.2.1...main
+[0.2.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.1
+[0.2.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.0
 [0.1.7]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.7
 [0.1.6]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.6
 [0.1.5]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.5