@am_shork/attest 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -13,6 +13,375 @@ 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.
 
+## [0.5.0] - 2026-08-03
+
+### Changed
+
+- **Design §11 now states what earns a `params` entry, and the README no longer
+  states a rule that produces the defect it warns about.** Two prose changes,
+  one subject, and both came out of the same adoption report.
+  *What earns a param:* **params for promises, plain constants for tuning.** A
+  value belongs in `params` when the requirement promises it — a timeout the user
+  is owed, a budget someone would file a bug about; a value that only tunes
+  behaviour stays an ordinary constant, because nothing is owed to anyone when a
+  tuning knob changes. `mine-capablanca` arrived at this unaided and applied it
+  consistently across 34 requirements (11 carrying params, 19 values), which is
+  the best available evidence that it is the natural rule — and it was written
+  down nowhere. It pushes back on the second of the two ways intent bloats, the
+  one §11's lumping bullet does not cover: a registry that accumulates every knob
+  in the project. Folded into the same paragraph, because it is the same rule
+  stated over the *type* rather than the value: what a param may therefore be — a
+  scalar, or an array of scalars. Stating those apart is what let one adopter
+  derive the first unaided and meet the second as `Invalid input`.
+  *And the rule that was half-wrong:* "Read the param inside the assertion, not
+  beside it" appeared in the README, the `init` skill and the `possible-drift`
+  section, and it is **necessary but not sufficient** — an assertion that
+  recomputes its expectation from the same param the code under test just read
+  has no independent term, so both sides move together and no edit can make it
+  fail. Measured, not theorised: a mine-density band moved by 3.3× with the whole
+  suite green, `check` silent, and the drift heuristic correctly quiet, because a
+  covering scenario did read the param. Every site now says what the evidence
+  supports — *the expectation must not be a function of the param the code under
+  test consumed* — and `possible-drift` carries a worked ✗/✓ pair. §11 records
+  the sharper statement of the hole: a tautological assertion is a scenario that
+  cannot fail, which the red-before-implement gate exists to catch, and it does
+  catch them in a change — but **changing an existing param's value goes through
+  no gate at all**.
+  No behaviour changed and no gate moved; the detector for the tautological form
+  stays under `Under consideration`, with all three of its blockers intact.
+  Documenting a trap is not the same as deciding not to detect it.
+
+- **A change's spec files now live at the location they will be merged to,
+  marked `*.proposed.spec.ts`.** `changes/<name>/` keeps `proposal.md`,
+  `requirements.delta.ts` and `first-run.json`; the scenarios sit beside the code
+  they attest, and merging one is a rename in place. Reported by
+  `mine-capablanca`: every one of eight merges rewrote the relative imports of
+  the change's specs, and the imports were the only thing that moved.
+  **"Depth" was the wrong word for it, and finding that out changed the
+  design.** The entry that queued this said the specs sat at a *different depth*
+  from where they land. They do not — `changes/<name>/specs/` and
+  `lib/game/specs/` are both three levels down. What differs is the **path**, so
+  no layout that keeps a spec under `changes/` can make one relative specifier
+  resolve in both places; mirroring the destination inside the change folder
+  fails for the same reason, one level further out. The only fix that costs no
+  mechanism is to write the file where it will live, which is what shipped.
+  *Two jobs the folder used to do at once, now done separately.* Keeping a
+  proposal's specs out of the base suite is by **name**, because it has to hold
+  for commands that never heard of a change: those scenarios are red by
+  construction, and a `verify` that swept them up would call every project with
+  a change in flight broken. Deciding which change a spec belongs to is by
+  **id** — a change claims the proposed specs declaring a scenario for an id it
+  ADDs, renames to, or MODIFIEs — because a file name carries no change, and the
+  delta already enumerates what the change is about. That keeps the property the
+  folder had and a `specs: []` list in the delta would have lost: nothing names a
+  path, so nothing can fall out of step with the files. REMOVED ids claim
+  nothing; a file is claimed whole or not at all, because the run scope is a set
+  of files.
+  *What it cost, stated rather than netted off.* A change is no longer one
+  folder a reviewer can read end to end — the delta still enumerates every id and
+  `attest status <name>` still answers what a change contains, but the specs are
+  now found by their marker rather than by looking in one place. And separating
+  the two jobs opened a gap the folder did not have, which is the `Added` entry
+  below. Held by `ATX-45` (excluded by name) and `ATX-46` (claimed by id), split
+  because they fail independently.
+  *Migration, for anyone with an open change directory:* move each spec from
+  `changes/<name>/specs/` to where it will merge, rename it to
+  `*.proposed.spec.ts`, and fix its imports once. That is the rewrite the merge
+  was going to charge anyway, done earlier and once. `first-run.json` is
+  unaffected — it is keyed by requirement id and scenario name, neither of which
+  moves.
+  Gone with the folder: `changeExcludeGlobs`, the sibling-exclusion globs that
+  kept one proposal's specs out of another's gate run. A directory glob could not
+  have told two proposals apart once the specs left `changes/`, and keeping one
+  beside the claim check would be a second scoping rule able to disagree with it.
+
+### Added
+
+- **A change delta now reads as the registry of what it adds.** `delta(…)`
+  returns the delta *and* a record keyed by the ids it ADDs, each carrying the
+  params its author wrote — so a stage-1 scenario reads a proposed param with
+  the expression a merged one uses:
+  ```ts
+  import reqs from '../../changes/add-2fa/requirements.delta.ts';  // ← only this line changes at merge
+  const window = reqs['AUTH-7'].params.totpWindowSec;              // typed at 30, no cast
+  ```
+  Reported by `mine-capablanca`, which hit this on 3 of 8 changes and wrote a
+  throwaway accessor each time, then rewrote every import at merge.
+  **The reason this was a defect and not an ergonomic complaint is which stage
+  it landed on.** Stage 1 is where the scenario must be written and must go red —
+  the entire content of the red-before-implement gate — so the tool pushed the
+  author off `params`, the single source the rest of it exists to reward, at
+  precisely the moment that source is load-bearing, and then billed them the
+  rewrite at merge for having complied. Every hand-written accessor is a second
+  place the value lives, open during the only stage where the assertion is being
+  authored against a value nobody has implemented yet.
+  *Why one value can be both.* A requirement id matches `/^[A-Z]+-\d+$/`, so no
+  id can ever be spelled `added`, `modified`, `removed` or `renamed` — the union
+  is safe by grammar rather than by convention, and neither surface shadows the
+  other. Both readers build it through one function, so the differential suite in
+  `tests/static-registry.spec.ts` still finds them agreeing about what a delta is.
+  *Deliberately not readable this way:* MODIFIED ids and rename targets. A
+  modified requirement's end state is the base entry with the patch applied, the
+  base is not in that file, and a view of the patch alone would answer one key
+  and `undefined` for every other key the requirement has — a shape that reads as
+  the merged requirement and is not one. Still no validation either: a delta
+  carrying an id the registry would refuse stays the gate's verdict (`ATX-41`).
+  Held by `ATX-48`, attested by compiling a fixture — a type has no runtime
+  footprint — with the assertion written as an equality against the merged read,
+  because sameness is the property that makes merging a change of import.
+  *Behaviour change, for whom:* the object `delta()` returns now carries the
+  added ids as own enumerable keys, so `Object.keys(d)` and a deep-equality
+  assertion over a whole delta see them. Nothing in Attest reads a delta that
+  way — `applyDelta` and both registry readers name the four sections — but a
+  consumer that snapshots a delta value will see its snapshot move. Reading
+  `.added`, `.modified`, `.removed` and `.renamed` is unchanged.
+
+- **`added-id-unmerged`: the gate now names why a spec file failed to load,
+  instead of blaming the spec.** Reported by `mine-capablanca`. `archive`
+  applies the delta in memory and gates the result; the suite is a child process
+  that imports `*.reqs.ts` from disk. So implementation code doing what the
+  skill's rule 3 requires — `reqs['FOG-4'].params.modestRisk` for an id the
+  change *adds* — throws at import, every spec transitively importing that module
+  fails to load, and the gate reported `tests-red` plus a `declared-not-run` per
+  scenario, whose message sends the reader to look for a `skip` or an `.only`
+  that is not there. **The change could not be made green by the documented
+  workflow, and the verdict pointed away from the reason.**
+  The gate now carries load failures out of the run alongside the coverage, and
+  when the change adds ids the on-disk registry lacks it reports one ERROR per
+  unloaded file, naming the file and the ids. The `declared-not-run` lines it
+  replaces are dropped — the absence has been explained, and restating it as a
+  guess about a skip costs the reader attention on files that are not at fault.
+  Only in the gate: `verify` keeps reporting them, having no diagnosis to put in
+  their place, and a wrong message still beats silence.
+  **This is the diagnosis and deliberately not the fix.** The way through is to
+  merge the added requirement into the registry before running the gate, which
+  the idempotent ADDED rule makes free — the `added:` entry stays and still
+  documents the intent. The alternative considered was to show the child run the
+  applied registry through an alias or a scratch overlay: it unblocks the
+  workflow and spends the property that the registry the suite ran against is the
+  file on disk, on the one command path that already evaluates project code. That
+  property cannot be given back by a later diagnostic; the convenience can.
+  *The condition is a conjunction and therefore a heuristic* — a module can fail
+  to import for reasons unrelated to any requirement id — so the message states
+  the two facts and the inference between them rather than asserting a cause.
+  Held by `ATX-49` (name the file and the ids) and `ATX-50` (withdraw the lines
+  it replaces), which are two requirements rather than one for the reason
+  `ATX-24` was split out of `ATX-23`: pushing one more issue satisfies the first
+  in full and leaves every misleading line sitting underneath it, so an
+  implementation can pass it and fail the reader exactly as before.
+  *Behaviour change, for whom:* no run goes from green to red — the new ERROR
+  only fires on a run that was already failing, because a file that did not load
+  is a failing run. What does move is what a machine consumer reads: for this
+  case `archive` now emits `added-id-unmerged` where it emitted one
+  `declared-not-run` per scenario. `verify` is untouched, and `declared-not-run`
+  is unchanged everywhere else.
+
+- **`proposed-spec-unclaimed`: a proposed spec no change claims is an ERROR from
+  `attest check`.** This is the cost of the split above, made loud. A file the
+  base suite skips by name and every gate skips by id executes nowhere, and both
+  skips are individually correct, so neither command is positioned to notice.
+  `check` is, because it is the only one that reads the deltas without being
+  about a single change — and reading them is something it already owed, since a
+  change delta is intent and the reporting commands read intent from source
+  (design §5.1). Reported per file, driven off the scanned tree rather than the
+  parsed plan so a proposed spec declaring no scenario at all is caught too. A
+  delta that cannot be read is reported as itself rather than turned into
+  accusations against its specs: not knowing what a change claims is a different
+  finding from knowing it claims nothing. Held by `ATX-47`.
+
+### Fixed
+
+- **`add-invalid` and `modify-invalid` now name the field that failed.** Both
+  quoted the schema's message and dropped the path it came from, so a
+  requirement whose `params` the schema refused reported `Invalid input` and
+  nothing else — no key, no accepted shape. Reported by an adopter who found the
+  failing param by reading `node_modules/@am_shork/attest/dist/core/schema.d.ts`,
+  which is the only place the constraint was written down.
+  *The form is not new, and that is the sharpest part of it.* `troubleshooting.md`
+  has quoted `Added requirement "AUTH-7" is invalid: rationale: Required` since
+  the section was written, and `RegistryValidationError` has spelled paths
+  `a.b.c` since the registry shipped — so the documented sample was one this
+  code could not produce, and the two sites that format the same zod failure
+  disagreed. The fix is the path, in the spelling already documented, from the
+  one function both callers go through. Where there is no path — the id itself,
+  under `introducedIdIssue` — nothing is prefixed rather than `(root)`, because
+  the message's own prefix has already named the thing.
+  Also on the way through: the `params` value union now carries its own message
+  instead of a bare `Invalid input`, so the refusal states what is accepted at
+  the moment it fires, and `registry-invalid` gains the same sentence for free.
+  Message text, so not a behaviour change under this file's own Versioning rule
+  — the codes and the accepted values are untouched, and no existing invocation
+  changes its exit code. Held by `ATX-44`, which states the contract over the
+  *path* rather than the sentence: the separator is the one property a scenario
+  can pin without asserting a word of the wording, which is what keeps
+  `Issue.message` prose while making its information content falsifiable.
+
+## [0.4.3] - 2026-08-01
+
+### Added
+
+- **The README's two getting-started samples are now the fixture the packaging
+  test installs and runs.** `tests/docs-consistency.spec.ts` opened by naming
+  this hole: every `*.md` outside the generated `SPEC.md` is hand-written prose
+  that no mechanism binds to the code, "the framework's own blind spot (design
+  §11)". Every check in that file until now gated a version string or a name;
+  this is the first that gates *meaning* — a registry or a spec on the page that
+  the engine would now reject was undetectable, which for a tool whose whole
+  claim is reporting drift between intent and what the tests execute is the
+  failure that costs the most.
+  The mechanism is a naming split rather than new machinery, and most of it was
+  already there and unnamed: `fixtures/consumer/` imports by bare specifier from
+  `@am_shork/attest` and `@am_shork/attest/define` because it is installed from a
+  real tarball outside the repo — which is exactly what a reader has to be able
+  to paste. So the two files lost their fixture-specific commentary, gained the
+  README's teaching comments, and the README now quotes them; the new assertion
+  is byte-equality between the fenced block and the file, newline-normalised so a
+  CRLF checkout cannot call a clean tree stale. The fixture is the original and
+  the page is the quote: breaking either side fails.
+  *What moved in the README:* the spec sample is now `session.spec.ts` beside
+  `session.ts` rather than `auth/session.spec.ts`, matching the layout the
+  packaging test actually runs, and it shows both of the requirement's scenarios
+  because the installed run asserts `scenarioCount: 2`.
+  *Limits, both deliberate:* the gate covers 2 of the 23 fenced `ts` blocks in
+  the README and `docs/en/**` — the rest are elided, ✓/✗-annotated, or
+  deliberately rejected by the engine, and none of those can equal a runnable
+  file. And the two claims are joined only on a release: this gate runs in
+  `pnpm test` and proves the page and the fixture agree, while the run that
+  proves the fixture still *works* is `pnpm test:consumer`, which needs a network
+  and a tarball. Both remaining halves are in `Planned`.
+
+- **The `docs/en` ↔ `docs/zh` mirror rule is now a gate rather than a paragraph
+  in `CLAUDE.md`.** Two assertions in `tests/docs-consistency.spec.ts`, both
+  scoped to what is comparable without comparing prose. The file set: a page
+  added on one side only is not a stale translation, it is a page that does not
+  exist, and nothing in the repository would have noticed. And the structure of
+  each pair — the heading tree as levels in document order, and the sequence of
+  fence info strings — which catches a section dropped or reordered in
+  translation, a code sample present in one language only, and a ```ts that
+  became ```bash.
+  *The parse is the part with a trap in it.* A `#` at the start of a line inside
+  a ```bash sample is a shell comment, and these pages are full of them, so the
+  reader tracks fences and skips their contents; a closing fence must repeat the
+  character that opened it, or a ``` quoted inside a ~~~ block ends the wrong
+  thing. An unterminated fence is reported rather than ignored, because it hides
+  every heading after it — two documents can agree by being truncated. All three
+  are asserted directly, on the standard this file already applies to its other
+  parses: a check whose parser can silently match nothing is not a check.
+  *One third of the queued entry turned out to be already covered and was not
+  written.* It asked for the `##` issue-code headings of `troubleshooting.md` to
+  be held equal between languages; the roster check that predates it already
+  asserts each language against `ISSUE_CODES` in both directions, so their
+  equality follows and a third assertion would catch nothing they let through.
+  *The limit, stated because it is not small:* a page whose structure held while
+  its meaning went stale passes everything here. Translation is not a diff. Same
+  shape as the limit the History gate carries — it can check that a row cites a
+  real version, not that the row is true.
+
+### Documentation
+
+- **The agent-facing documents gained a diagnosis discipline, a review pass, and
+  a design vocabulary**, adapted from an external skill collection rather than
+  copied from it — the parts that survived are the ones this repository's own
+  defect history had already paid for.
+  *New skill, `.claude/skills/diagnose/`.* Its one rule is that no hypothesis may
+  be formed before a command exists that has been run at least once and can go
+  **red** on the bug in hand. Every defect this repository has recorded failed
+  silently rather than loudly, so that bar is higher here than the phrase
+  suggests, and the skill's local content is the questions that tell a green run
+  apart from one that never happened: read the test count rather than the colour,
+  since a `beforeAll` throw reports a file as *skipped* (`[0.4.2]`); confirm the
+  file you care about actually ran, since a glob that matched nothing is a clean
+  run over code that never loaded; and name which half a command covers before
+  trusting it. The ways that goes wrong are the Gotchas in `CLAUDE.md`, pointed
+  at rather than restated — a second copy of them would only be a second copy to
+  drift. The remainder is the standard loop: minimise until every element is
+  load-bearing, three to five falsifiable hypotheses before testing any,
+  `[DEBUG-…]`-tagged probes, and "no correct seam is itself the finding".
+  *`pre-commit-check` gained §8, a reading pass on two axes*, kept unmerged and
+  unranked against each other because a change can pass either and fail the
+  other. The Spec axis is mostly machine-checked here and nowhere else — `check`,
+  `cover` and `verify` *are* drift detection — so it reads only for what those
+  cannot reach: whether an `ATX-n`'s text states the contract, whether `params`
+  pin the values the scenario should be pinned to, and whether a green scenario
+  attests its requirement or merely passes. The Standards axis carries a twelve-
+  smell baseline (Fowler, *Refactoring* ch.3) as labelled heuristics that any
+  documented rule here overrides, with two weighted for this repository:
+  duplicated path-shaped code means a second copy that did not go through
+  `src/core/paths.ts`, and speculative generality is the other face of §1's rule
+  that every requirement costs a scenario forever.
+  *`CLAUDE.md` gained a design vocabulary* — module, interface, depth, seam,
+  adapter, and the three tests that settle most arguments — which exists because
+  the two structures it names were already these things and had no word for it.
+  `src/core/paths.ts` is the repository's deepest module, and the deletion test
+  is not hypothetical for it: every silent path defect in the Gotchas is what
+  this codebase looked like when that knowledge lived at the call sites. The two
+  registry readers are two adapters at one real seam, which is what makes the
+  differential suite possible — and the entry marks where the analogy stops,
+  since which adapter runs is fixed by the command and never a fallback, that
+  being a security property rather than a design preference.
+  *And a section on where a decision goes*, which is this file. It is stated in
+  `CLAUDE.md` rather than only in `pre-commit-check` because the moment to write
+  one is when the decision happens; a design evaluated and dropped mid-session is
+  what is most likely to be lost, and by commit time the reasoning that killed it
+  is already gone.
+  *The candidate that did not survive is the reason the section exists.* The
+  proposal was a `docs/adr/` directory holding three decisions lifted out of the
+  Gotchas — why `fixtures/nested-spec/` may not be flattened, why `render
+  --check` compares the document rather than the bytes, why one `spawn` helper.
+  All three were already recorded here, in more detail than the proposal would
+  have carried, so the directory's whole effect would have been to split a store
+  this file keeps deliberately single. Recorded rather than filed as work, since
+  no such directory exists: had it been put under `docs/en/`, the mirror gate
+  added above would not have seen it at all — `pages()` is a non-recursive
+  `readdir` filtered to `*.md`, so a subdirectory is invisible to the file-set
+  check, the structure check, and the version-bearing sample scan alike. A
+  documentation subdirectory is therefore an unmirrored one, silently, which is
+  this repository's signature failure shape wearing documentation's clothes.
+
+### Fixed
+
+- **The packaging test installed into a directory Windows spells two ways, and
+  read the result as the package being broken.** `tests/consumer.spec.ts` staged
+  its throwaway project under `os.tmpdir()`, which on Windows reads `TEMP` — set
+  by the OS to the 8.3 short form, `C:\Users\JOHN_C~1\...`. Vite resolves the
+  peer `vitest` from the *long* form of the same directory, so the consumer's
+  spec file and the installed `@am_shork/attest` imported two module instances of
+  it; `describe` ran against an uninitialised runner and the spec died at import
+  with `Cannot read properties of undefined (reading 'config')`, before a
+  scenario executed. What that surfaced as is the part worth recording: `attest
+  verify` reported `tests-red` plus `declared-not-run` for every scenario —
+  a report indistinguishable from a genuinely broken package, produced by a
+  package that is fine. Staging through `realpath` fixes it.
+  This is `CLAUDE.md`'s first failure family one form further out — not a
+  separator inside a path, but two spellings of one directory — and it was
+  unreachable until `[0.4.2]` made this suite run on Windows at all. CI is Linux,
+  where `os.tmpdir()` has one spelling, so the pipeline was never going to say
+  otherwise.
+
+- **The AST parser's own source file was binary, so every change to it since the
+  initial commit was unreviewable.** `src/core/parser.ts` separated the two
+  halves of its param-ref dedupe key with a **raw NUL byte** rather than the
+  `\x00` escape. One character no editor renders reclassified the whole file:
+  `git diff` answered `Binary files a/… and b/… differ` for every change to it,
+  `git grep` and `grep` skipped it in silence, and `.gitattributes`' `eol=lf`
+  never applied, because `text=auto` tests for binary first.
+  *What it cost is the reviewing, not the running.* A string escape is resolved
+  by the compiler, so the key is the same three code units on every platform —
+  no behaviour changes, and no requirement, scenario or schema moves. What was
+  lost is that every text sweep over this repository silently excluded the one
+  module that turns spec source into the plan every command reads. A pre-commit
+  pass grepping `src/` for a rule — a `path.relative` outside `paths.ts`, a
+  stray `spawn` — was answering about 27 of 28 files and reporting no gap, which
+  is worse than not having run it.
+  *And it shipped.* `files` carries `dist`, and `tsc` copies a template
+  literal's contents verbatim, so `dist/core/parser.js` put the byte into every
+  installed copy.
+  Recorded at this length because the defect is not the byte but its invisibility:
+  this is `CLAUDE.md`'s silent-failure shape with no platform in it at all, and
+  the tools anyone would bring to look for it are the ones it disables. The last
+  thing it costs is its own diff — the old side of this commit is still the
+  binary blob, so this entry is the only readable account of the change.
+
 ## [0.4.2] - 2026-07-30
 
 ### Added
@@ -1880,26 +2249,17 @@ feedback reports are triaged into issues or `Unreleased` and deliberately not
 kept in this tree; that rule stands, and holds for anything with a reporter, a
 repro, or a state to track. What is kept here is the narrower thing this file
 already keeps one section of: a **decision with an argument attached**, where
-losing the argument would cost more than losing the task. The first and last
-below came out of reading another repository against this one — `fast-check` and
-`msw` respectively. The middle one came out of building something queued here,
-which is the other way an entry arrives: a gate that finds a defect on its first
-run files the defect.
-
-- **A structural parity gate over `docs/en/**` and `docs/zh/**`.** The mirror
-  rule — one Chinese page per English page, matching down to the comments inside
-  the code samples, both carried by the same commit — is enforced today by a
-  paragraph in `CLAUDE.md` and by whoever remembers to read it. The home is
-  `tests/docs-consistency.spec.ts`, which already enumerates both directories
-  and already says in its own header why it checks only the two couplings tight
-  enough to assert cheaply; this is a third. What is comparable without
-  comparing prose: the heading tree (level, order, count), the count of fenced
-  code blocks, and — for `troubleshooting.md` — the set of `##` issue-code
-  headings, which is machine-derived on both sides and so must be equal
-  exactly. Translation is not a diff and nothing here should pretend otherwise,
-  which is also the limit: a page whose structure held while its meaning went
-  stale passes. Same shape as the limit the History gate already carries — it
-  can check that a row cites a real version, not that the row is true.
+losing the argument would cost more than losing the task. The first below came out
+of building something queued here, which is one way an entry arrives: a gate that
+finds a defect on its first run files the defect. The second came out of reading
+another repository against this one — `msw`. The last came out of an adoption
+report (`mine-capablanca`, 0.4.2, 34 requirements / 56 scenarios / greenfield),
+which is the third way: not a defect, but a shape the tool made an adopter work
+around eight times without ever erroring. Two further entries from that report
+left this section by shipping in `[0.5.0]` — a change's specs moving to their
+merged location, and the delta reading as the registry of what it adds — and
+their arguments are recorded there, including the part of the first one that
+turned out to be wrong.
 
 - **A diagnosable refusal when the resolved compiler has no AST API.**
   Discovered by building the `typescript` matrix (see `[0.4.2]`), which is
@@ -1928,40 +2288,36 @@ run files the defect.
   it yet — a separate decision, with the honest answer for now being that the
   supported range has a ceiling and says so.
 
-- **Fixtures that are also the code samples the documentation shows.**
-  `tests/docs-consistency.spec.ts` opens by naming this exact hole: every `*.md`
-  outside the generated `SPEC.md` is hand-written prose that no mechanism binds
-  to the code — "the framework's own blind spot (design §11)" — and it asserts
-  only the two couplings cheap enough to assert. This is a fourth, after the
-  `docs/en` ↔ `docs/zh` parity gate queued above, and it is the one that reaches
-  meaning rather than structure: a fenced block in `cli-reference.md` or
-  `troubleshooting.md` showing a registry the engine would now reject is
-  undetectable today. For a tool whose entire claim is reporting drift between
-  intent and what the tests execute, its own documentation drifting from what the
-  engine does is the failure that costs the most and is currently reported by
-  nobody.
-  **The shape that makes it cheap is a naming split, not a new mechanism.** `msw`
-  requires every integration test to be two files: a `*.mocks.ts` holding a usage
-  example with *nothing test-specific in it*, and a `*.test.ts` that loads the
-  example and asserts against it — so the example is simultaneously the fixture
-  and a snippet publishable to users unmodified. Here that means promoting a
-  subset of `fixtures/` to that status and having the English page quote the file
-  rather than restate it, with the assertion being byte-equality between the
-  fenced block and the fixture.
-  **Not every fixture is a candidate, and the exclusions are the existing ones.**
-  `fixtures/runner-red` and `fixtures/e2e-bad` are inputs to child runs that
-  assert failure, and `fixtures/nested-spec/` exists to put a separator in a path
-  — none is written to be read as an example, and dressing them up as one would
-  cost the thing they are for.
-  *The cost is the mirror rule, and it caps what can be claimed.* `docs/zh/**`
-  matches `docs/en/**` down to the comments inside its code samples, so
-  byte-equality can hold on one side only; the Chinese block stays translated
-  prose around the same code, which is the parity gate's problem and is why these
-  two entries should land together or in that order. A page whose sample is
-  byte-equal to a living fixture while the paragraph above it describes the old
-  behaviour still passes — the same limit already written down for the History
-  rows, and the same answer: this binds what is machine-derivable and leaves the
-  rest to a reader.
+- **Region-marked samples, so a partial quote can be bound too.** The whole-file
+  half of this shipped in `[0.4.3]`: the README's two getting-started blocks
+  are now byte-equal to `fixtures/consumer/`. That buys 2 of the 23 fenced `ts`
+  blocks in the README and `docs/en/**`, and the ceiling is structural rather
+  than lazy — the other 21 are elided (`{ /* … */ }`), annotated (`// ✓ the single
+  source`, `// ✗ a literal that can drift`), or deliberately rejected by the engine
+  (`params: { maxMb: MAX_MB }`), and none of those can equal a runnable file.
+  **What raises it is marking spans, not a second mechanism.** A
+  `// #region readme:registry` and its close inside the fixture, with the
+  assertion running block against dedented span, lets one file feed several
+  passages and makes a partial quote bindable by construction. Where that
+  actually reaches, counted rather than hoped: `troubleshooting.md`'s
+  single-source pair is two verbatim lines of `fixtures/consumer/session.spec.ts`
+  and its `AUTH-3` block is the registry entry at a different indent — so a
+  handful more, not the remainder. Anything carrying a `✓`/`✗` is authored
+  commentary and stays a fragment; that is what it is for.
+  *The ✗ blocks are a separate question, and worth not conflating.* A sample
+  showing input the engine must reject could be bound to a fixture whose
+  *rejection* is asserted — which is what `fixtures/eval-invalid-registry`
+  already is. Binding those is the more valuable half, because a counterexample
+  that stopped being a counterexample is the one kind of stale sample that
+  actively teaches the wrong thing. It is also the one that needs a fixture per
+  diagnostic, so it is not free the way the regions are.
+  *The mirror rule still caps what can be claimed on the Chinese side.*
+  `docs/zh/**` matches `docs/en/**` down to the comments inside its code samples,
+  so byte-equality holds on one side only and the zh blocks stay translated prose
+  around the same code — the parity gate in `[0.4.3]` is what covers them now,
+  and it covers structure, not meaning. Unchanged from the whole-file half: the residual
+  risk recorded with it in `[0.4.3]` — that the gate and the run proving the
+  fixture still works live in different suites — applies here identically.
 
 ## Under consideration
 
@@ -2001,6 +2357,158 @@ have to gather again.
   someone hits an `EMFILE` from `attest check`, the diagnosis is already written
   down rather than rediscovered.
 
+- **An assertion that recomputes its expectation from the param the code under
+  test just read is a tautology, and nothing says so.** Reported by
+  `mine-capablanca`, which probed it by mutating the registry and running the
+  full gate on each mutation:
+
+  | mutation | who reads it | `check` | `verify` |
+  |---|---|---|---|
+  | `GEN-1.maxCandidatesPerPiece` 64 → 4 | scenario only | ok | **red** |
+  | `BOARD-1.boardSize` 10 → 12 | app + fixtures | ok | **red** |
+  | `BOARD-2.maxMines` 12 → **40** | app + assertion | ok | **green** |
+  | `BOARD-2.minMines` 9 → **1** | app + assertion | ok | **green** |
+
+  The mine-density band — the one number deciding whether that game is playable —
+  moved by 3.3× with the whole suite green, `check` silent, and `possible-drift`
+  correctly not firing, because a covering scenario *does* read the param.
+  **Read the third and fourth rows against the second, because that is the
+  finding.** The reporter's diagnosis was "app and spec both read it", but row 2
+  is app-and-spec and goes red. What distinguishes the green rows is narrower and
+  more useful: the assertion **derives its expectation from the same param the
+  code under test used**, so both sides move together and the comparison has no
+  independent term. Row 2's expectation lives in fixtures, which do not move when
+  the param does, and the mechanism works. So the failing condition is a property
+  of the assertion, not of who reads the value — which matters, because it means
+  the answer is a rule about how to write the assertion, and *not* the detector
+  the reporter proposed.
+  **What this falsifies is written in this file.** The rejection of a committed
+  params snapshot, below, closes on *"the mechanism that guards a param is a
+  scenario reading it, not a file recording it"* — a sufficiency claim, and rows
+  3 and 4 are counterexamples to it. A scenario reading the param is necessary
+  and not sufficient. That entry stays rejected on its own argument, which was
+  never about detection power, but its fallback clause is now known incomplete
+  and is annotated accordingly. The README's §"killer move" has the same shape:
+  it says noticing a param *moved* is `verify`'s job "only when a scenario asserts
+  on the value it read from `params`" — literally a necessary condition, and read
+  by an adopter as a sufficient one, with the very next line (*"Read the param
+  inside the assertion, not beside it"*) being the instruction that produces the
+  tautology.
+  **The framing that probably resolves it: this is `never-red` wearing different
+  clothes.** A tautological assertion is a scenario that cannot fail, which is
+  the exact defect `archive`'s red-before-implement gate exists to catch — and it
+  did catch two of them in this very repo (`CHECK-2`, `FOG-3`, both confirmed
+  correct by the reporter). The reason it did not catch these is structural:
+  **changing the value of an existing param goes through no gate at all.**
+  `archive` gates a change; a param edit is not a change. That is a cleaner
+  statement of the gap than "params can be tautological".
+  *What blocks the decision — three things, all of them real.* **(1)** Every
+  mutation above is synthetic. Across 8 commits touching `*.reqs.ts` in that
+  repo, **no param value was ever modified** — every `params:` line in every diff
+  is an addition. So the hole is proven as a logical property and its frequency is
+  entirely unmeasured, from one greenfield repo. **(2)** The reporter's proposed
+  mechanism — a WARNING when one param id is read from both a spec and a non-spec
+  file — is the wrong shape twice over: it fires on row 2, which is correct usage
+  and goes red, and it would fire on the arrangement the README actively
+  recommends, which is §9's "usually wrong about staleness" failure mode again.
+  It also needs a static sweep of the whole project for `reqs['X'].params.y`,
+  far past the two registry readers' current surface. **(3)** No mechanism is yet
+  known that separates "the assertion pins this independently" from "the assertion
+  echoes it" without executing the scenario twice under different values — which
+  is mutation testing, a much larger thing to own.
+  **The guidance half has shipped; this entry is now only about the detector.**
+  "Read the param inside the assertion" was insufficient and half-wrong as
+  written, and `[0.5.0]` replaces it everywhere it appeared — README, the
+  `init` skill, `possible-drift`, and design §11 — with what the evidence
+  supports: **the expectation must not be a function of the param the code under
+  test consumed**, pinned in a fixture, a literal, or a second independently
+  derived value. Row 2 is the worked example, and the reporter's own
+  `CHECK-2`/`FOG-3` fixes are the same move. It was held back once because
+  rewording the central claim of the tool is not a line appended; that is what
+  was then done, deliberately and in one pass.
+  **What stays undecided is the mechanism**, and all three blockers above are
+  untouched by the rewording: the frequency is still unmeasured from one
+  greenfield repo, the reporter's proposed detector is still the wrong shape
+  twice over, and nothing short of mutation testing separates an independent pin
+  from an echo. What the guidance does not do is close the hole — a tautological
+  assertion is still green, still silent, and still reachable — so this stays
+  here rather than moving to `Considered and rejected`: documenting a trap is
+  not the same as deciding not to detect it.
+
+- **`attest archive <change> --apply`, finishing the merge the gate approved.**
+  `mine-capablanca`'s single loudest item: eight changes, eight hand-written
+  Python scripts, and the report quotes one — it locates the delta's block by
+  `split('added: {', 1)`, trims two spaces of indent per line, and re-terminates
+  the registry on `assert t.endswith('});')`. After the gate goes green the
+  adopter hand-splices the delta into the registry, moves specs into the suite,
+  rewrites their imports, moves the folder to `archive/` and re-renders `SPEC.md`.
+  **The cost is the smaller half of the argument. The hole is that the gate's
+  verdict does not cover the step that acts on it** — `archive` proves the delta
+  is green, covered and drift-free, and then a human transcribes it by hand with
+  nothing checking the transcription. A delta can be spliced in wrong, partially,
+  or twice, and the next `check` sees only whatever ended up in the file.
+  **The objection that has to be answered is the `AGENTS.md` block under
+  `Considered and rejected`.**
+  The `AGENTS.md` block was rejected because "that is a merge tool, and each of
+  its failure modes is destructive on a file the user cannot regenerate". The
+  argument for why it does not transfer, which needs to be right before this
+  ships: there, Attest would edit prose whose grammar it does not own; here the
+  registry is a **literal** Attest defines, statically parseable, with a
+  differential suite already asserting two readers agree on it — so the result of
+  a splice is checkable by re-reading it, and the delta was validated by the gate
+  that just ran. Idempotence is verifiable rather than assumed. That reasoning
+  covers delta→registry, the folder move and the re-render. It used **not** to
+  cover import rewriting, which is editing arbitrary TypeScript and is squarely
+  the rejected shape.
+  *That blocker is gone, and it was removed rather than solved.* Proposed specs
+  now live at their merged location under `*.proposed.spec.ts` (`[0.5.0]`), so
+  the merge step for a spec is a rename in place — there are no specifiers to
+  rewrite, and `--apply` no longer inherits the one part of the job that could
+  not be made safe. What is left for it is the delta→registry splice, the rename,
+  the folder move to `archive/` and the re-render, all of which the paragraph
+  above argues are checkable by re-reading the result.
+  *What still blocks the decision:* two questions with no answer yet — what
+  `--apply` does when the working tree is dirty (`archive` already has a position
+  on this; whether a file-mutating flag takes the same one is not obvious), and
+  whether a partially applied merge is recoverable or whether the flag must be
+  all-or-nothing against a scratch copy.
+  *The frequency blocker has moved.* This entry used to close on "one report, one
+  repo: the cost evidence is strong and the frequency evidence is a single
+  adopter." It is now two. This project's own maintainer proposed the same command
+  independently, without the entry in front of them, having felt the same step by
+  hand — which is the second data point that clause was waiting for. Not
+  conclusive about frequency in the field, and it does not touch either question
+  above, but it removes the reason to keep waiting for someone else to ask.
+
+  *A narrower shape was proposed with it and is rejected — `attest merge <change>`,
+  moving the change folder to `archive/<date>-<name>/` and nothing else.* Three
+  reasons, and the third is the one that decides it.
+  **(1) It targets the cheap half.** The expensive step in the report is the
+  delta→registry splice — the quoted Python locates the block by
+  `split('added: {', 1)`, trims two spaces per line, and re-terminates on
+  `assert t.endswith('});')`. The folder move is `mv`. A new command that saves a
+  shell invocation and leaves the TypeScript-literal surgery is the wrong half to
+  automate. The date it would stamp is real ergonomics but small: `archive/` is
+  named in three places and all three are exclusions (`locate.ts`'s SKIP_DIRS,
+  and the two exclude globs), so nothing reads the directory and a mis-stamped
+  date has no mechanical consequence at all.
+  **(2) It would make two command names mislead instead of one.** `attest archive`
+  archives nothing today — it is purely the gate. Adding a second verb that does
+  the archiving leaves `archive` still lying and `merge` doing its job; `--apply`
+  goes the other way and makes the existing verb finally mean what it says.
+  **(3) A move that does not re-run the gate can file an unfinished change as
+  done.** That is the one thing this tool must not ship: the whole claim is that
+  "done" has a hard definition, and a command able to mark completion around that
+  definition removes it. The alternative is that `merge` re-runs the gate — at
+  which point it *is* `--apply` and should be spelled that way. There is no third
+  option, which is why this is a rejection of the shape rather than of the idea.
+  *Recorded here rather than under `Considered and rejected`,* because nothing
+  was decided against: the idea is this entry, and only the narrow spelling of it
+  died. Also worth stating because it needed no release to ride — a new command
+  changes no exit code, rejects no previously-valid input, and removes no API, so
+  it is additive under this file's own Versioning rule and was never blocked on a
+  version bump.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -2247,6 +2755,21 @@ no scenario caught it, and `possible-drift` was **not** already printing —
 because if it was printing, what failed was reading the report, and a second
 gate does not fix that.
 
+*Annotated after `mine-capablanca` (0.4.2): the last two sentences above are
+wrong and the rejection is not.* "A scenario reading it" is necessary and not
+sufficient — where the assertion recomputes its expectation from the same param
+the code under test consumed, the value moved 3.3× with the suite green and
+`possible-drift` correctly silent, so "the only condition under which a moved
+param goes unnoticed" names one condition out of two. The reopen clause is
+therefore satisfied in substance while failing on its own literal terms, since it
+was written expecting the uncovered case and the demonstrated one has a covering
+scenario. **What that changes here is nothing**: this entry was rejected on the
+population a snapshot fires on — every legitimate param edit, fix a commit with
+no decision in it — and that objection is untouched by the new evidence, which
+concerns detection the snapshot was never denied having. The live question moved
+to `Under consideration` above, where it belongs, because the mechanism now in
+question is a rule about assertions rather than a file beside the registry.
+
 ### Grouping `render`'s output by prefix
 
 The *detection* half of this is already rejected above (every automatic
@@ -2271,7 +2794,44 @@ requirement, and human review at propose is still the whole answer. What is
 rejected is grouping as a way to assist it, and this reopens only on a
 contradiction that grouping would have caught.
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.4.2...main
+### Nested objects in `params`, so a lookup table can be registry-owned
+
+Raised by `mine-capablanca` (0.4.2) and explicitly not as a request, which is
+why it is recorded with its own answer rather than left as a complaint about a
+message. A `params` value is a scalar or a list of scalars; a table — piece kind
+to weight, tier to limit — is refused, and the only way to register one is to
+split it across parallel arrays, which reads worse in the rendered spec than it
+buys. *What rejected it: the two properties a param has, and a table has
+neither.* A param is **rendered into `SPEC.md` as a value a human checks at a
+glance**, and it is **read by a scenario as the one place that value lives**. A
+nested object fails the first by construction — there is no reading of a
+five-row table that a reviewer verifies the way they verify `30`. It fails the
+second more quietly: a table has many readers by definition, so "the one place"
+becomes "the one file", which is what an ordinary module already is. The
+schema's own comment records where the line was drawn and why arrays were let
+in — list constants are the most drift-prone values, and an array still has one
+owner read by one scenario. A table does not clear that bar; the reason arrays
+did is exactly the reason it does not.
+*The reporter's own resolution is the argument's strongest form.* The table went
+to a shared module, is not registry-owned, and **nothing was lost** — because a
+piece-value table is tuning, not a promise. That is the rule design §11 now
+states — *params for promises, plain constants for tuning* — derived
+independently by the same adopter before it was written anywhere. Under it this
+candidate is not a limitation of `params` at all: it is a value that was never a
+requirement's to hold, and §11 carries this rejection's own argument in the same
+paragraph, as the rule stated over the type rather than over the value.
+*What ships instead*, in `[0.5.0]`: the refusal now says what is accepted
+instead of `Invalid input`, and `troubleshooting.md` states the constraint and
+where such a value belongs — the reporter's actual ask, which was for the
+decision to be visible rather than discovered by reading the shipped `.d.ts`.
+The permanent half goes to design §11 with the params rule, not here.
+*This reopens on* a report where the value is genuinely promised — a table an
+adopter owes their users, whose rows a reviewer would want in the rendered spec.
+None has been seen; the one that raised it was tuning.
+
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.5.0...main
+[0.5.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.5.0
+[0.4.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.3
 [0.4.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.2
 [0.4.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.1
 [0.4.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.0