@am_shork/attest 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -13,6 +13,607 @@ 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.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
+
+- **The engine ↔ runner boundary is now a gate over the import graph, and it
+  had already been crossed.** Design §11 records the widest limit this design
+  has: `typescript` is a runtime dependency and `vite`/`vitest` are hard peers,
+  so the addressable set of repositories is a subset of one ecosystem's. The
+  answer that escapes it is a package split — a core that does not know a runner
+  exists plus one thin adapter per runner — and **that split is deliberately not
+  done**: a monorepo's build matrix, version coupling and CI fan-out are not
+  earned by one package at 0.4.x, and the dogfooding loop is what would pay,
+  since `bin/attest.js` loads `dist/` and `self/` is verified through it.
+  What ships is the cheap half. `tests/import-boundary.spec.ts` asserts that
+  exactly three modules may name `vite`/`vitest` — `src/runtime.ts` (the shipped
+  runtime, which is Vitest's `describe`/`it` under Attest's names and executes
+  *inside* the child run), `src/core/loader.ts` (the Vite loader) and
+  `src/core/runner.ts` (the only module that starts Vitest). It reads the
+  specifiers from the AST rather than matching text, so a comment naming
+  `vitest/node` is not an import and a dynamic `import()` is one.
+  **The boundary was not intact when the gate was written**, which is the whole
+  argument for having it: `pipeline.ts` imported `configDefaults` from
+  `vitest/config` for one exclude list, putting the peer dependency on the module
+  every static command goes through — `check`, `cover` and `render` included.
+  Nothing was wrong with the behaviour and no behavioural test could have been
+  wrong about it. Only the graph shows it, and a boundary is lost exactly this
+  way: one convenient import, in a module nobody thought of as being on the
+  runner's side of the line.
+  *What it cannot do:* gate **reachability** from the static commands, which is
+  not assertable today — `pipeline.ts` holds both halves of the engine, so it
+  reaches `runner.ts` unconditionally. That is the same fact the deferred split
+  would fix. A second test narrows the reachability claim to where it is both
+  meaningful and true: no path from `static-registry.ts` or `parser.ts` — the two
+  modules that must read a file without executing it — reaches a runner through
+  any module.
+
+- **A positive control on the non-execution tests, which were passing without
+  one.** The tests asserting that `check`, `cover`, `render` and `status` never
+  execute the project work by writing a sentinel file at a registry's module
+  scope and expecting it *absent* afterwards. Every one of those assertions is
+  equally satisfied by an instrument that never worked: a `writeFileSync` to a
+  path that could not be written, or a registry the loader never reached, reads as
+  "absent" — indistinguishable from the guarantee being kept. `runVerify` now
+  runs last against the same project and the same sentinel, and the sentinel must
+  be *present*, which is what turns four absences into evidence. Added in the
+  default suite (`tests/pipeline.spec.ts`) and dogfooded under `ATX-16`
+  (`self/registry-reader.spec.ts`), since `vitest run` does not run `self/`.
+  *Not a new requirement:* this states nothing new about behaviour, it makes
+  `ATX-16`'s existing claim falsifiable — so it belongs to that scenario as its
+  control rather than to an `ATX-n` of its own.
+  *What is still not covered:* `archive` has no positive control of its own. It
+  evaluates the delta through the same `loader.load` the `--eval` escape hatch
+  uses, and that path is controlled under `ATX-32`, but nothing asserts that
+  `archive` specifically would notice if it stopped evaluating.
+
+- **The `typescript` range is now run at both ends.** `[0.4.0]` collapsed the
+  peer range to `vite ^8` / `vitest ^4` on the argument that advertising a
+  version no job runs end to end moves the failure into the adopter's
+  repository. That test had never been applied to the third dependency it fits:
+  `typescript` is a runtime `dependencies`, and the range was a claim about every
+  5.x while CI resolved exactly one of them — 5.9.3, four minors above the floor
+  the manifest advertised, which had therefore never been run at all.
+  It matters more here than for the peers, because a caret on a direct
+  dependency is not this repo's to resolve: a package manager may dedupe it
+  against the adopter's own `typescript`, so `parser.ts` and `static-registry.ts`
+  — the only two import sites, and both on the path that must read an AST and
+  never evaluate it — execute on whichever compiler in the range that project
+  already had. TypeScript is also not distributed under SemVer but as
+  `{marketing}.{major}.{minor}`, so a "minor" inside a major is free to change
+  parse behaviour.
+  The new `typescript-matrix` job installs each end and re-runs the differential
+  suite (`tests/static-registry.spec.ts`, the one extractor changes were already
+  required to go through) plus `tests/parser.spec.ts`. With the lockfile at 5.9.3
+  that is three points: 5.5.4, 5.9.3, 6.0.3. **Measured green at all three**, and
+  the floor is the one that had never been checked.
+  *What it cannot do:* prove the extractor against syntax this repo's corpus does
+  not contain — the same limit the History gate carries.
+  *No scheduled `typescript@rc` job*, which the queued entry had asked for. It is
+  rejected on measurement rather than skipped: `rc` and `latest` are 7.x, which
+  exposes no compiler API (see `Planned`), so the job would be red forever — the
+  decoration the `audit` job's comment refuses.
+
+- **The README's dependency versions are now asserted against the manifest.**
+  Found by running the pre-commit list over this change rather than by reading the
+  diff: the Prerequisites section makes version claims about all three
+  dependencies, the manifest is the only place any of them is true, and nothing
+  bound the two. The existing gates in `tests/docs-consistency.spec.ts` pin
+  Attest's *own* version into samples and pinned docs URLs; the peer range had
+  been unbound prose since `[0.4.0]` collapsed it, which means the sentence
+  claiming the range is "exactly the one CI runs" was the one line in it nothing
+  ran. This change would have widened that hole by adding a second such claim, so
+  it closes it instead.
+  The coupling to wording is the cost, and it is narrower than it looks: the
+  string matched **is** the claim, unlike an `Issue.message`, which is prose
+  precisely so it can be reworded. Rephrasing the sentence is free as long as the
+  version stays in it, which is what the failure says.
+
+### Changed
+
+- **`typescript` widened to `^5.5.0 || ^6.0.0`, and stays a `dependency`.** The
+  open question the queued entry raised was whether it should be a **peer**
+  instead: a runtime dependency is what buys determinism in principle, dedupe is
+  what removes it in practice, so the manifest stated a guarantee the resolver
+  does not honour. Measuring it answered the question in the opposite direction
+  from the way it was posed.
+  **A peer is not available, because the API is not.** TypeScript's `latest` is
+  now 7.x, whose npm package is the native port: its main export is
+  `{ version, versionMajorMinor }` and the AST moved behind
+  `typescript/unstable/ast*` — explicitly unstable. A peer range would therefore
+  either exclude 7 and so warn every adopter on the current release into
+  installing an older compiler explicitly, or admit one that cannot parse
+  anything. Bundling is the only shape that guarantees the API exists at all, so
+  what looked like a hedge is the load-bearing decision. Recorded under
+  `Considered and rejected` with the measurement.
+  The ceiling moved because 6.0.3 measures green on the full API surface the two
+  readers use and on both typecheck projects, and because the ceiling had become
+  a claim about a major that has since shipped and works. A TS-6 adopter now
+  dedupes to one copy running the compiler that matches their own syntax instead
+  of installing a second 5.9.
+  *Not a bump under this file's Versioning rule, and the reason is worth being
+  exact about.* No input that was valid is rejected and no exit code moves. An
+  already-installed adopter is untouched, because their lockfile pins what they
+  resolved. A **fresh** install genuinely can differ — in a repository already on
+  TypeScript 6 the resolver may now dedupe there where it previously fetched a
+  5.x of its own, so the compiler behind the AST readers changes. That is a real
+  change and not a hidden one: it is the entire purpose of widening the range,
+  both ends are gated by the job above, and the widening only ever admits a
+  compiler this repo runs the differential suite against. What would make it a
+  breaking change is a range whose ends are *asserted* rather than run, which is
+  the state this entry ends. This repo's own resolution did not move: the lockfile
+  still holds 5.9.3.
+
+- **`pipeline.ts` no longer imports `vitest/config`.** `runArchive` needed
+  Vitest's default exclusions to compose its own exclude set; the list is now
+  re-exported as `BASE_EXCLUDE` from `runner.ts`, which already had the import
+  and is one of the three modules allowed to. *Not a behaviour change* — the
+  composed exclude set is identical, and `BASE_EXCLUDE` is internal, not part of
+  the package's exports.
+
+### Documentation
+
+- **§11's language-binding bullet now records an answer deferred rather than no
+  answer.** It stated the limit — one ecosystem's repositories, no more — and
+  said nothing about what holds the line in the meantime. It now says that the
+  dependency is confined to three modules and that the confinement is gated on
+  the import graph rather than left to review, that the confinement had already
+  failed once, and that the package split which actually escapes the limit is
+  deferred on cost grounds rather than unconsidered.
+  It also states the part of the binding that is **narrower** than "an
+  ecosystem", and which has already moved: the AST layer needs the TypeScript
+  *compiler API*, and TypeScript 7 does not ship one. So what Attest installs
+  into is a repository whose compiler is of a particular generation — which is
+  why the range has a ceiling and why the compiler is bundled rather than a peer.
+  §0 bought the parse layer with a dependency on one vendor's internal API, and
+  "never regex" is what makes that worth paying; the point now written down is
+  that the bill arrives again every time the API moves, on a schedule nobody here
+  controls. Both languages.
+
+- **The README says which TypeScript versions are supported, and that yours is
+  not involved.** Prerequisites already explained the peer range and why it is
+  exactly what CI runs; the bundled compiler was not mentioned at all, so an
+  adopter on TypeScript 7 seeing a second `typescript` in their tree had nothing
+  to read. It now states the range, that both ends run in CI, that a TypeScript
+  5-or-6 project dedupes to one copy, and that their own compiler version stays
+  their choice.
+
+- **Said out loud that the archive gate trusts `first-run.json` and cannot check
+  it.** The reasoning had been written down since 0.3.0 — in a comment at the top
+  of `red-record.ts`, where no adopter reads it. What they read instead was that
+  `archive` is an executable gate and that this file is "the evidence", which
+  over-sells what running it buys: `hasRecordedRed` compares against `'fail'` and
+  nothing else, so a hand-written record clears `never-red` having proved
+  nothing.
+  The distinction worth stating, and now stated, is between the two kinds of file
+  Attest writes. The workflow document and a rendering are *derivable* — a pure
+  function of nothing, and a pure function of the registry — so a checker can
+  regenerate them and compare, which is exactly what `render --check` does. The
+  first-run record is not, and cannot be: it records that a scenario failed
+  **once**, and by the time a change is archivable everything is green, so there
+  is nothing left to recompute it from. That is inherent to what the file is
+  rather than a gap left open — if the state could be derived at archive time,
+  the record would not need to exist at all. So it is the one thing Attest writes
+  that cannot be checked by regenerating it, and what stands in for that check is
+  a reviewer. (The workflow document has no gate either, but that is a decision —
+  `init --check` was rejected, see below — not an impossibility.)
+  Landed in `troubleshooting.md#never-red` and under `attest archive` in the CLI
+  reference (both languages), and in the workflow document `attest init` writes —
+  where it also became a fourth entry in "things you must not do", beside editing
+  a scenario to match the implementation. Hand-writing the record belongs in that
+  list on the list's own terms: it turns the gate green without changing the
+  system. **Re-run `attest init` to pick it up.**
+  *Not in the README*, which links to the reference for this and stays the pitch
+  and the five-minute start. *Not a behaviour change*: nothing about what the
+  gate accepts moved, and binding the record to a CI run — the fix that would
+  make it checkable — is a separate decision, because it would stop `archive`
+  being a command that works offline.
+
+### Fixed
+
+- **The packaging test could not run on Windows, and said so by reporting eleven
+  skipped tests.** `pnpm test:consumer` is the only thing that exercises the
+  published surface — the `files` allowlist, the `exports` map, the `bin` launcher,
+  peer resolution from a foreign `node_modules` — and it is what stops another
+  0.1.1-style "green in-repo, broken on install" release. On Windows it had never
+  run at all. Three separate defects, each of which had to be fixed to see the
+  next one:
+  - *`npm` cannot be spawned by that name.* The file is `npm.cmd`, so `npm` is
+    ENOENT — and `npm.cmd` is EINVAL, because Node stopped spawning `.cmd` directly
+    when it closed the argument-injection hole in 22.x. The same applies to the
+    `.bin/attest` shim the install writes, so both the package manager and the CLI
+    under test were unspawnable. Both now go through one `spawn` helper that adds a
+    shell on win32 only, so POSIX — the platform CI gates on — spawns exactly as it
+    did before, and quotes its arguments where the shell is used.
+  - *The tarball path was substituted raw into JSON.* A Windows path's backslashes
+    are escape characters there, so `npm install` refused the generated manifest
+    with EJSONPARSE before reading a single dependency. This is the "path crossing
+    a boundary" shape `CLAUDE.md` already records, with JSON as the boundary rather
+    than a glob — so the fix is the one that rule already prescribes: the spec now
+    goes through `relativePath`, which answers both halves at once, POSIX
+    separators and a path short enough to have none. Spelling the `../` by hand
+    would have worked and was the first attempt, but it encodes the staging layout
+    as a constant: move the consumer project one level deeper and the literal is
+    wrong *while still being valid JSON and a valid specifier*, so the next failure
+    would arrive as a mystery ENOENT somewhere else.
+  - *The `bin` launcher's absence was untestable.* A missing shim surfaced only as
+    a spawn error from the helper, which reads as a broken test rather than a
+    broken `bin` field, so it now has an assertion of its own.
+  **The failure shape is the reason this survived four releases.** The throw was in
+  `beforeAll`, so Vitest reported the file's tests as *skipped* — the run said
+  nothing was wrong while executing none of it, and CI is Linux, so the pipeline
+  was never going to disagree. A third defect shape is now recorded in `CLAUDE.md`
+  beside the two it already carried.
+  *What is verified where:* all eleven tests pass on Windows, running the real
+  `npm` and the real `.bin/attest.cmd`. The POSIX branch is unchanged by
+  construction — no shell, same command name, arguments passed through untouched —
+  and its one new behaviour is the relative `file:` spec; that half is left to CI,
+  which runs this job on Linux on every push.
+
+- **The crash path printed the checked project's text to the terminal with
+  nothing removed.** 0.4.0 closed terminal injection by putting every diagnostic
+  through a sanitiser, and left the two `catch` blocks in the CLI printing
+  `err.stack` raw beside it. That is not a lesser path: under `verify`,
+  `archive` or `--eval` the thing that throws is a module out of the repository
+  under test, so the message on that stack is that repository's text — and
+  throwing is the cheapest thing a hostile registry can do, cheaper than getting
+  a scenario name into a report. On a fork merge request the reader is not the
+  author, and the payload is the same one as before: erase the lines above,
+  repaint a red verdict green, retitle the window.
+  **Both `catch` blocks now go through one formatter**, which is `block` — the
+  same function the diagnostics use, so a stack's frames indent by four more
+  spaces and no line of an injected message can occupy the column a real `ERROR`
+  header sits in. One function rather than a copy each, because a copy each is
+  how the first one came to be missed; ATX-37 is restated over everything the
+  CLI prints rather than over "the report", since the narrow wording is what the
+  narrow implementation matched. `--json` is untouched and was never exposed —
+  serialising escapes the same characters, which is exactly why this had to be
+  fixed on the side people read.
+  **And the loader, which prints before Attest ever sees the error.** Driving
+  the built CLI at a registry that throws escape sequences is what turned this
+  up, after the `catch` blocks were already fixed: `logLevel: 'error'` quiets
+  Vite's chatter and not its errors, and when a `*.reqs.ts` throws, Vite writes
+  `Error when evaluating SSR module …: <the message>` to stderr on its own
+  account. So the `registry-invalid` diagnostic built from that very exception
+  was being sanitised while the raw bytes had already gone past it — a forged
+  `ERROR` header at column 0 and a `\r` to erase the line above it, from a file
+  the reviewer only ran. The loader now passes a `customLogger` that puts every
+  message through the same function. The whole message is treated as untrusted,
+  which costs Vite its own colour on that path: by the time it arrives the
+  project's text has been interpolated into it, so there is no half left to
+  trust.
+  *Where the sanitiser lives changed with it.* `block` / `inline` / `control`
+  moved from `cli/report.ts` to `core/terminal.ts`, because the loader is below
+  the CLI and cannot import from it — and a second copy of this decision is
+  precisely what the crash path had been.
+
+- **A failed write left a scratch file in a version-controlled directory, and
+  named it something another process could take first.** `writeAtomic` is what
+  keeps a rendering, the agent skill and a change's first-run record from ever
+  being committed half-written, and the temporary file it renames from was doing
+  damage on both of the paths it could fail on. Nothing removed it when the
+  rename failed, so `.attest.<pid>.tmp` stayed next to the file it failed to
+  become — either committed, or a dirty working tree in `archive`, the one
+  command that takes care not to produce one. And the pid it was named for
+  separates two *runs*, not two *writes*: `init` writing several targets is the
+  second shape, and it was safe only by happening to be sequential, which makes
+  the safety a property of that loop rather than of the write.
+  **The scratch file now takes a random name, is created with `wx`, and is
+  removed when anything between the write and the rename throws.** `wx` is
+  `O_CREAT | O_EXCL`, so an existing path at that name — a symlink included — is
+  refused rather than followed; with an unpredictable name nothing can aim at
+  the path in the first place, and `wx` is what makes a guess useless rather
+  than merely unlikely. No `mode` is set: the temporary file *becomes* the
+  destination, so tightening it would quietly change the permissions of a
+  document the user commits and serves. (ATX-43)
+  *What ATX-43 does not state.* The exclusive creation is in the code and not in
+  the requirement, because an unpredictable name means no scenario can
+  pre-create the path to observe it — and a requirement whose scenario cannot
+  fail is worse than the comment that records it (design §11). The two
+  properties that *are* observable, and are stated, are that no scratch file
+  survives either outcome and that two writes into one directory cannot collide.
+
+  *Behaviour change.* Neither entry changes an exit code, a `--json` field or a
+  diagnostic. The visible differences are that a stack printed on stderr is
+  indented under its first line, that a `*.reqs.ts` which throws under `--eval`
+  now has Vite's report of it printed without colour, and that a temporary file
+  is named `.attest.<uuid>.tmp` rather than `.attest.<pid>.tmp` — anything
+  matching the old name in a `.gitignore` should become `.attest.*.tmp`, though
+  after this there is nothing left for it to match.
+
+- **A delta could bring a requirement into the registry under an id the registry
+  itself would refuse, and one spelling of that id was not a key at all.** A
+  delta introduces an id in two places — an ADDED key, and the target of a
+  RENAME — and `applyDelta` checked neither: it validated the requirement a
+  delta adds while never looking at the key it files it under, and it called
+  `map.set(to, …)` without looking at `to`. So `^[A-Z]+-\d+$` — the grammar
+  `defineRequirements` holds every registry key to — did not apply on the one
+  other path that creates them. The mild form is an inconsistency: a change
+  could archive under `auth-7`, an id nobody could then write into the
+  `*.reqs.ts` the change is supposed to merge into, so the gate passed on an end
+  state the intent layer cannot represent.
+  The form that made it a defect is `__proto__`. Added ids do not stop at the
+  registry — `addedIds` carries them into the first-run record — and there
+  `record[id] ??= {}` never fired for that name, because reading it yields the
+  shared prototype rather than `undefined`. The outcome was then written onto
+  `Object.prototype`: one spec file in one change, and every object in the
+  process carries the key.
+  **Every id a delta introduces now goes through the registry's own schema
+  first, in one function both sites call.** ADDED reuses `add-invalid`, because
+  the reader's situation and the file to go and edit are unchanged and a second
+  code would ask them to learn a distinction that alters nothing they do. RENAME
+  gets a new one, `rename-target-invalid`, because the existing pair are both
+  about *existence* — a target that is taken, a source that is gone — and
+  neither can say the id is unusable; it is reported ahead of the source so a
+  delta with both ends wrong names the half the author has to retype. (ATX-41)
+  *This repository's own example was one of the offenders.* `renamed: [{ from:
+  'AUTH-2', to: 'AUTH-2-login' }]` stood in both design documents, in the
+  workflow document `attest init` writes into every adopter's repo, and in these
+  tests — so the shape being refused is the shape we had been teaching. All of
+  them now read `to: 'SESSION-1'`, which is the better example anyway: it shows
+  why a rename happens at all (re-homing an id under its own prefix, per
+  `duplicate-prefix`) rather than decorating the old one.
+
+- **The archive gate could be satisfied by evidence that was never recorded.**
+  `changes/<name>/first-run.json` is read into a plain object, and `JSON.parse`
+  makes `__proto__` an ordinary own property — so a record carrying that key
+  re-pointed the *record's* prototype, and `hasRecordedRed` then answered `true`
+  for a requirement the file says nothing about. The file serialises back as
+  `{}`, so the never-red obligation — the one mechanism whose entire purpose is
+  to hold a fact about history — was met by a file containing no history, and
+  the diff a reviewer reads showed an empty record. Reaching it needed nothing
+  but a text editor.
+  **The record is now built and read as a map with no prototype**, at both
+  levels, and `recordedOutcome` looks up own properties only rather than
+  `record[reqId]?.[scenario]` — so the guarantee does not depend on who
+  constructed the object the gate was handed. Prototype-free rather than a check
+  for the handful of names that misbehave: a blocklist is a second answer to
+  "is this a data key", and having no prototype is the first one. This also
+  stops the answer from resting on how the schema library happens to treat
+  `__proto__`, which today is what was discarding it before the gate saw it.
+  (ATX-42)
+
+  *Behaviour change, and who it turns red.* The first entry rejects input that
+  used to pass, on both halves: a delta that ADDs an id outside `^[A-Z]+-\d+$`
+  now fails `archive` with `add-invalid`, and one whose rename target is outside
+  it fails with `rename-target-invalid`, where both previously merged. The
+  second half is the one likelier to bite, because the pattern it refuses is the
+  one our own documentation showed. Both are real CI breaks for anyone who has
+  such a delta in flight, and both are deliberate — the alternative is archiving
+  a state that cannot be written back into a registry. The fix is to retype the
+  id in `requirements.delta.ts`; nothing else in the change moves, and a
+  requirement already merged under a bad id is unaffected, since this checks
+  deltas rather than registries. The second entry loosens nothing and tightens
+  nothing a well-formed record could notice: a record whose keys are real ids
+  reads and serialises exactly as before.
+  `rename-target-invalid` is a new `code` value and therefore additive — no
+  `SCHEMA_VERSION` bump, and a consumer branching on `issues[].code` sees a code
+  it has not heard of exactly as it would any other new diagnostic.
+
+- **The package shipped 54 source maps and none of the sources they point at.**
+  `sourceMap` and `declarationMap` have both been on since the first build, and
+  every map tsc emits names its origin as `../../src/*.ts` — a path outside
+  everything the `files` allowlist carried, which was `dist`, `bin` and this
+  document. So each map in an installed copy resolved to nothing: a debugger
+  that will not step into the engine, and a *Go to Definition* that stops at the
+  `.d.ts` instead of the declaration behind it. Nothing errored, which is how it
+  survived four minors — every tool that reads a map ignores an unresolvable one
+  rather than failing on it, so this was a feature quietly not working rather
+  than a thing anyone could notice breaking.
+  **The maps are now excluded from the package rather than repaired.** `files`
+  grows a negation (`!dist/**/*.map`); they stay in `dist/` for this repo's own
+  use, where `src/` is present and they resolve, and the tarball drops to
+  119.7 kB across 59 files — smaller than the 147 kB that shipped broken.
+  *Why not the other two shapes.* Adding `src` to `files` also works and was
+  the first fix written: it makes both maps resolve, at 195 kB and 148 files, to
+  serve stepping into the engine from an adopter's `node_modules` — which
+  nothing has asked for, and which anyone auditing the reader would do from the
+  repository instead. This file has rejected `init --check`, `divergent-param`
+  and countable obligations for costing more than a demonstrated need, and that
+  standard does not bend for a packaging decision. Turning the two compiler
+  options off is the cleanest published output, since it leaves no dangling
+  `sourceMappingURL` comment, but it also removes the maps from `dist/` here,
+  where `verify self` runs through the built CLI and they are the only thing
+  that maps a crash back to a line of source. (`inlineSources` is not a third
+  option: it embeds text into the `.js.map` and does nothing for the
+  `.d.ts.map`.)
+  *What is gated, and where.* `tests/consumer.spec.ts` asserts the installed
+  tree carries no `*.map` and no `.ts`. The pairing is the thing that can come
+  apart silently — drop the negation, and the package is back to shipping maps
+  that resolve to nothing — and the installed tree is the only place the
+  question exists, since in-repo `src/` is always there. Reversing the decision
+  means inverting that assertion, not deleting it, which the test says in
+  place.
+
+- **`build` never removed `dist/`, so a module deleted from `src/` kept being
+  emitted.** `tsc` overwrites its outputs and deletes nothing, so a renamed or
+  removed module leaves its last emit behind indefinitely. Found by the check
+  above rather than by looking: `dist/cli/version.js` and `dist/core/guide.js`
+  were still present, both orphaned by `[0.4.1]`, one of them by the
+  `packageVersion()` move that release records.
+  **What it was not is a correctness hazard, and the distinction is worth
+  keeping.** `dist/` mirrors the import graph of `src/`, and a dangling import
+  in `src/` fails `tsc`, so an orphan is unreachable by construction — dead
+  weight rather than something `bin/attest.js` could load. No published tarball
+  carried one either: `dist/` is gitignored and the publish job builds from a
+  fresh checkout. What is left is a working tree where `dist/` is not the output
+  of any single build, which is worth one line to remove given that every
+  `attest …` command in this repo runs from it, and `CLAUDE.md` already has to
+  warn that those commands reflect the last build rather than `src/`.
+  `build` now runs a `clean` script first. `tsc -b --clean` was tried and does
+  not do this job — it deletes the outputs it can derive from the current
+  sources, which is every file except the orphan. The remaining shape without a
+  new dependency is a `node -e` one-liner; `rimraf` would read better in the
+  manifest and pulls a transitive tree in exchange, which is the trade the
+  `audit` job and the `brace-expansion` override exist to keep an eye on.
+
 ## [0.4.1] - 2026-07-29
 
 Every diagnostic now links to a section that explains it, and the README is a
@@ -1428,6 +2029,124 @@ 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).
 
+## Planned
+
+Decisions **to** build something, not yet built. The mirror of `Considered and
+rejected` at the foot of this file, and the three sections from here down live
+together for the same two reasons: nothing in them has shipped, so nothing in
+them belongs to a release, and a block pinned above the version history sinks
+one release deeper every time one is cut. They run by decreasing commitment —
+decided yes, undecided, decided no. An entry leaves this one by being
+implemented — at which point it is rewritten as an `Added` bullet under its
+version — or by being rejected, at which point it moves down with what killed
+it. Neither move is a deletion.
+
+This is not the issue tracker and does not replace it. `[0.1.6]` records that
+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 last below came out
+of reading another repository against this one — `msw`. The first 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 diagnosable refusal when the resolved compiler has no AST API.**
+  Discovered by building the `typescript` matrix (see `[0.4.2]`), which is
+  what a matrix is for. `typescript@7` is the native port: its npm package's main
+  export is `{ version, versionMajorMinor }`, and the AST moved behind
+  `typescript/unstable/ast*` — so `ts.createSourceFile` and every `ts.isX` guard
+  the two readers call is `undefined`. Measured: `attest check` on it dies with
+  `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
+  stack, on the crash path this release just finished sanitising. No issue code,
+  no fix hint, and nothing saying which compiler it wanted.
+  **The range excludes 7, and that is not the same as being safe from it.** A
+  caret is a request, not a constraint the adopter cannot override: `pnpm.overrides`
+  and Yarn `resolutions` both pin a transitive dependency across the whole tree,
+  and a repo standardising on one compiler is exactly the repo that uses them —
+  this one has an `overrides` block of its own. So the reachable case is a
+  deliberate, reasonable act by an adopter, answered with a stack trace.
+  What is planned is a check of the API surface where the readers are entered,
+  reported as an ERROR naming the resolved version and the supported range. Cheap,
+  and it converts the one dependency failure this tool cannot survive from a crash
+  into a diagnosis. *Deliberately not folded into the matrix commit*: a new ERROR
+  is a behaviour change, it needs an issue code, a troubleshooting section in both
+  languages and an `ATX-n` with a scenario, and none of that belongs in a commit
+  whose whole claim is that nothing about behaviour moved.
+  *What it cannot do:* make Attest work on TypeScript 7. That is a migration to
+  `typescript/unstable/ast`, against an API whose own name says not to depend on
+  it yet — a separate decision, with the honest answer for now being that the
+  supported range has a ceiling and says so.
+
+- **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
+
+Candidates with **no decision yet**, between the two sections either side of it
+and at the foot of the file for the reason both of those are: nothing here has
+shipped, so nothing here belongs to a release, and an open question filed under
+a version reads as something that version settled. An entry leaves by being
+decided — up into `Planned` and then into an `Added` bullet under its version,
+or down into `Considered and rejected` with what killed it. Neither move is a
+deletion. What each entry has to carry is the evidence currently blocking the
+decision, because that is what a re-proposal a year from now would otherwise
+have to gather again.
+
+- **Bounding the fan-out in `findFiles` and `parseSpecs`.** Both walk the
+  project with no concurrency limit: `findFiles` recurses through
+  `Promise.all(subdirs.map(walk))`, so every directory in the tree is opened at
+  once, and `parseSpecs` does `Promise.all(files.map(readFile))`, which reads
+  every spec file into memory before parsing any of them. Neither is bounded by
+  anything, and `check` is the command this repository tells people to run first
+  in a pipeline on an untrusted fork MR — so the input size is not ours to
+  assume.
+  *The evidence, and why it is not enough to act on.* Measured on a synthetic
+  tree of 6000 spec files: the fan-out is real and unbounded — peak in-flight
+  `readFile` calls came back as exactly 6000 — and `attest check` finished in
+  1.99 s without erroring. It could not be made to fail. Windows is why: Node
+  uses Win32 handles there rather than POSIX descriptors, so the `ulimit -n` of
+  3200 that the shell reports does not govern the process, and the one platform
+  where descriptor exhaustion is plausible is the one CI runs and this
+  measurement could not reach (`CLAUDE.md`'s two-platform rule, pointing the
+  unusual way round). What *is* portable is the memory: `parseSpecs` holds every
+  source at once, which at a realistic 8 KiB per spec file is ~47 MiB at this
+  count — noticeable, not fatal.
+  So the fix is known and cheap — a concurrency limit of ~32 at both sites, and
+  parsing each source as it arrives rather than after all of them, which makes
+  the peak constant — and it is held back by this file's own standard: no report,
+  and no demonstrated failure on any platform. Recorded here so that the day
+  someone hits an `EMFILE` from `attest check`, the diagnosis is already written
+  down rather than rediscovered.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -1438,231 +2157,269 @@ it sat between 0.2.0 and 0.1.7 for two releases, where standing still meant
 sinking one version deeper each time a release was cut above it, and a rejection
 filed under a version reads as belonging to it.
 
-- **A requirement's id prefix must match its registry file's name.** The other
-  half of the rule that shipped as `duplicate-prefix` (see `[0.4.0]`), and
-  the half that does not pay for itself. What killed it is that the corpus
-  already conforms: every fixture registry matches (`auth.reqs.ts` → `AUTH-`,
-  `core.reqs.ts` → `CORE-`), so the rule would detect nothing anywhere it was
-  measured except one file — `self/requirements/attest.reqs.ts`, which holds
-  `ATX-*`. Its first act would therefore be to rename this repo's own registry
-  and every `self/*.spec.ts` that imports it, and its first act in an adopter's
-  repository would be the same thing to theirs. That is rejecting input valid
-  today, a minor bump under this file's Versioning rule, in exchange for making
-  the prefix *guessable from the path* — which matters only to a reader already
-  looking at the file, and who could have read the ids in it. The collision rule
-  delivers what the gap is actually about, which is two owners of one space, and
-  it delivers it without a rename because it fires on a relationship between
-  files rather than on a spelling. Reconsider only with evidence that a reader or
-  a tool needs the prefix before opening the file — a naming *convention* stays
-  the right shape for this, and the convention is what `init` and the docs
-  already teach.
-  What is not a reason to revisit it: the objection that stalled the collision
-  rule while both were queued together — that it guards a convention nothing had
-  yet violated — was answered by shipping it, since a rule that costs no
-  migration and no concept is worth having before the first collision rather
-  than after it. That argument does not transfer here, because this rule's cost
-  is a migration by construction.
-
-- **Two gaps in the intent layer: nothing resists a bloated requirement, and
-  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. The guard makes
-  the *suite* re-count; it cannot make this file re-read, so every figure below
-  is a quotation of that snapshot and is only ever as fresh as the last edit
-  here — read the snapshot when the number is what matters.
-  *`compound-requirement` (WARNING) — rejected.* More than one RFC-2119 keyword
-  in one `statement` is objectively more than one obligation. Measured (figures
-  re-read from the suite, which is the only place they are not prose): of the 8
-  requirements in the corpus carrying more than one, it flags 3 (`ATX-10`,
-  `ATX-21`, `ATX-26`) 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 7 of 8, at 3 wrong hits (`ATX-6`,
-  `ATX-22`, `ATX-23`) rather than the 1 recorded when it was first scored — so
-  reach is not the deciding argument, and the precision it trades away grows
-  with the registry.
-  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, then `ATX-25`, then `ATX-26`, 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. `ATX-26` added the sharper version of the same
-  point: it names the *same* diagnostic as `ATX-17`, so the two now agree by
-  coincidence and `ATX-17` drops out of the set the rule reports — a rule that
-  reads agreement as safety falls silent on a pair it had been flagging, for a
-  reason that has nothing to do with either requirement.
-  **A second param name now collides, and that is what closes the last defence
-  of the rule.** `file` names a path Attest writes — the agent skill in `ATX-27`,
-  a change's first-run record in `ATX-30` — two unrelated constants, a third
-  wrong firing. Until it appeared, every false positive had been on the single
-  name `code`, which left "pick a less generic param name" open as a repo-side
-  workaround and therefore left the rule arguably salvageable. It is not the
-  word: two requirements owning unrelated constants of the same *kind* is the
-  structure, and any registry large enough to be worth linting has it.
-  Still zero true positives, now across a 34-entry corpus (the `corpus` figure in
-  the suite's snapshot, which counts a fixture id once per registry file that
-  declares it).
-  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.
-
-- **A freshness gate on the file `attest init` writes (`init --check`).**
-  `render --check` is the obvious precedent and is the opposite case. A rendering
-  is a function of the *user's registry*, so its staleness means the user moved
-  intent without regenerating — a real signal, with the fix in their hands. The
-  skill is a function of the *installed version*, so a gate on it turns red on a
-  change the user did not make, and is cleared by a commit containing no
-  decision. That is a chore wearing a diagnostic's clothes, and a gate that
-  cannot be about anything the reader did is worse than no gate — the same
-  standard 0.1.6 set when it gave `render` no formatting options at all.
-  An earlier draft of `attest init` spent a second command, this gate and a
-  second self-requirement on it. What that would have bought is immunity to one
-  honest and small exposure: an old file describes an old workflow to an agent
-  that trusts it. The backstop is that every mistake it can cause is already a
-  diagnostic with a fix hint — a registry written the old way is
-  `registry-not-static` — so the agent corrects itself from the report, and
-  `init` is idempotent, which makes re-running it the entire update mechanism.
-  Recorded here rather than left in the 0.3.0 entry that shipped `init`, because
-  the queue above depends on it: a gate is the first thing proposed each time a
-  new agent target is considered, and the answer must not need re-deciding per
-  target.
-
-- **A marked block in the adopter's `AGENTS.md` / `CLAUDE.md`.** The cross-tool
-  convention Codex, Cursor and Copilot read, and the reason it looks like the
-  obvious next target after the skill is that it reaches the most agents per unit
-  of work. Rejected on three counts, none of which is about effort.
-  **It is the only file `init` would write that Attest does not own.**
-  `.claude/skills/attest/SKILL.md` exists because Attest exists; `AGENTS.md`
-  exists because the *project* does, and what is in it is prose its maintainer
-  wrote and curated. Writing a block into it means an idempotent
-  read-modify-write on someone else's document — find the markers, preserve
-  everything outside them, and then handle the markers being absent, duplicated,
-  hand-edited, moved, the file missing, the file being `CLAUDE.md` instead, or
-  both existing. That is a merge tool, and each of its failure modes is
-  destructive on a file the user cannot regenerate.
-  **It would remove the property that makes `init` safe to automate.**
-  `skillContent()` takes no argument — the content is a pure function of nothing
-  at all — so `init` is one atomic write and its idempotence holds *by
-  construction*, which is what lets "re-run it after upgrading" be the whole
-  update mechanism and be safe in a script. A marked block makes the output a
-  function of the file already there, demoting idempotence from a property of the
-  design to a behaviour that needs test coverage, on the one path where being
-  wrong destroys input.
-  **It is a worse carrier for the same text.** An `AGENTS.md` block is
-  unconditionally resident in the agent's context, where a skill body is loaded
-  when its description matches — so every unrelated request in that repo pays for
-  a workflow it will not use. It was never a port of the skill; it is a second,
-  weaker capability wearing the same words.
-  The interaction with the entry above is what settles it: a user-edited block
-  cannot be replaced on upgrade without discarding the edit, so this shape needs
-  either the freshness gate rejected above or a three-way merge. *What replaces
-  it*, for an adopter whose agent reads `AGENTS.md`: one line they add
-  themselves, pointing at the skill file. A pointer is cheap enough to be
-  resident, it is their edit in their file, and it cannot go stale — the file it
-  names is the one `init` keeps current.
-
-- **A Codex target for `attest init`.** Evaluated when `init` grew `--target` and
-  shipped for Claude Code, Cursor and Copilot; rejected because the tool offers
-  nothing to write, not because of what writing it would cost. Codex's
-  project-scoped instruction surface is `AGENTS.md`, which the entry above
-  rejects permanently, and its custom prompts live in `~/.codex/prompts` — per
-  machine, outside the project root `init` is pointed at, and not a thing a
-  project can commit or a CI checkout can carry. That leaves no path that is both
-  **Attest's own** and **read by the tool**, so the two rules a target has to
-  satisfy are not merely unmet here, they are unmeetable with what exists: any
-  Codex-shaped implementation would be either the rejected merge or a file
-  nothing reads, and the second is worse, because it looks like coverage.
-  Filed here rather than queued as a candidate, since nothing about the effort
-  or the evidence is what is holding it — the pointer line above is the whole
-  answer for a Codex user, and this reopens only if Codex grows a project-scoped
-  path of its own.
-
-- **A committed snapshot of the params, to give `check` detection power over a
-  value that moves.** Design §11 records the measurement this answers: editing a
-  param (`'main'` → `'trunk'`, one entry dropped from a nine-element list) leaves
-  `attest check` at `✓ No issues`, because the single source makes a value
-  impossible to *diverge*, which is not the claim that it is flagged when it
-  *moves*. The candidate was the shape `render --check` already proves — a
-  `params.lock` beside the registry, or `check --params-check` — and the
-  mechanism would have worked.
-  *What rejected it: the precedent is the objection.* §9 states when a freshness
-  gate earns its place, and a rendering earns it because it is a function of the
-  *user's registry*, so staleness means the user moved intent without
-  regenerating — a real signal with the fix in their hands. A params snapshot is
-  a function of the registry too, but the population it fires on is different:
-  **every legitimate param edit turns it red, and the fix is a commit containing
-  no decision.** That is precisely the chore §9 declined to ship for `init`, and
-  it is worse here because of frequency — intent is rendered rarely, while params
-  move whenever a value moves, which is the entire reason they are params. The
-  gate would spend its whole life red about correct edits, and a gate that is
-  usually wrong about staleness is the failure mode §9 names as worse than no
-  gate.
-  *What the gap keeps instead.* §6's mechanism 3 already exists to make this
-  exact absence visible: `possible-drift` fires when a requirement owns params
-  that no covering scenario reads, which is the only condition under which a
-  moved param goes unnoticed. The mechanism that guards a param is a scenario
-  reading it, not a file recording it. This reopens only on an adoption report
-  where a param moved, 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.
-
-- **Grouping `render`'s output by prefix, so a reviewer sees contradicting
-  requirements together.** The *detection* half of this is already rejected above
-  (every automatic candidate either saw almost nothing or was a similarity
-  matcher, which is what §0 exists to remove), leaving human review at propose
-  (§7) as the answer — and the idea was to help that review by putting
-  requirements about one subject side by side in the one document a human reads
-  end to end.
-  *What rejected it: the ordering already ships, and the adjacency it buys is not
-  where the gap is.* `compareIds` (`render.ts`) has ordered the document by
-  prefix first and number second since `render` shipped, so same-prefix
-  requirements are **already** adjacent; the candidate was never an ordering
-  change, only a heading over an ordering that already holds. And §11's own
-  example of the gap is `AUTH-3` expiring a session against `SESS-7` saying
-  sessions never expire — a contradiction **across** prefixes, which prefix
-  grouping pushes further apart rather than closer. What remains is a reader aid
-  for same-prefix contradictions, which are the pairs already adjacent and
-  therefore the ones review is least likely to miss, bought at the price of
-  changing the bytes of every committed rendering and turning `render --check`
-  red across every adopting repo on upgrade — for a change the user did not make.
-  *The gap itself stays open* and stays where it belongs, in design §11: nothing
-  resists a duplicated or contradictory 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.1...main
+### `typescript` as a peer dependency instead of a bundled one
+
+The open question the matrix entry was queued to settle (see `[0.4.2]`), and
+it is worth keeping because the reasoning that made it attractive is sound and
+still wrong. A runtime `dependencies` on a caret is a guarantee the resolver does
+not honour — a package manager may dedupe it against the adopter's own compiler,
+so the version that actually parses their registry is not this repo's to choose.
+A peer makes that explicit instead of pretending otherwise, which is the shape
+this repository chose for `vite` and `vitest` in `[0.4.0]` for exactly that
+reason.
+
+**What killed it is that the API a peer would supply does not exist.**
+TypeScript's `latest` is 7.x, whose npm package is the native port: the main
+export is `{ version, versionMajorMinor }` and the compiler API moved behind
+`typescript/unstable/ast*`. So a peer range has two spellings and both are worse
+than bundling. Admit 7 and the peer is satisfiable by a package with no
+`createSourceFile` at all — the dependency declaration would state a requirement
+it cannot check, and the failure lands as a crash inside the reader that decides a
+security property. Exclude 7 and every adopter on the current TypeScript release
+gets a peer warning telling them to install an older compiler *explicitly*, in
+service of a tool that could have carried its own — which is the ceiling-hurting-
+adopters failure `msw` reached the no-upper-bound answer from, arriving here from
+the opposite direction.
+
+The asymmetry with `vite`/`vitest` is the whole of it, and it is not about
+stability: those two are peers because Attest must run *inside the adopter's own
+runner* — a second copy would be a second test run, which is not a thing that
+works. Nothing about reading an AST needs the adopter's compiler; the reader wants
+*a* parser for TypeScript syntax, not *theirs*. A bundled one is therefore the
+only shape that can guarantee the API exists, and the duplicate install on a
+TypeScript 7 project is a real cost paid knowingly, not an oversight — one extra
+`node_modules` entry, against a tool that otherwise cannot start.
+
+Reconsider only if the compiler API becomes something a peer range can honestly
+describe again: `typescript/unstable/ast` reaching stability under a name that is
+not `unstable`, with a version range across which the AST shape is contractual.
+Until then the ceiling is the honest statement, and the range is run at both ends
+rather than asserted. *Not a reason to revisit:* an adopter reporting two copies of
+`typescript` in their tree. That is the decision working, and the README says so
+under Prerequisites.
+
+### A requirement's id prefix must match its registry file's name
+
+The other half of the rule that shipped as `duplicate-prefix` (see `[0.4.0]`),
+and the half that does not pay for itself. What killed it is that the corpus
+already conforms: every fixture registry matches (`auth.reqs.ts` → `AUTH-`,
+`core.reqs.ts` → `CORE-`), so the rule would detect nothing anywhere it was
+measured except one file — `self/requirements/attest.reqs.ts`, which holds
+`ATX-*`. Its first act would therefore be to rename this repo's own registry and
+every `self/*.spec.ts` that imports it, and its first act in an adopter's
+repository would be the same thing to theirs. That is rejecting input valid
+today, a minor bump under this file's Versioning rule, in exchange for making
+the prefix *guessable from the path* — which matters only to a reader already
+looking at the file, and who could have read the ids in it. The collision rule
+delivers what the gap is actually about, which is two owners of one space, and
+it delivers it without a rename because it fires on a relationship between files
+rather than on a spelling. Reconsider only with evidence that a reader or a tool
+needs the prefix before opening the file — a naming *convention* stays the right
+shape for this, and the convention is what `init` and the docs already teach.
+What is not a reason to revisit it: the objection that stalled the collision
+rule while both were queued together — that it guards a convention nothing had
+yet violated — was answered by shipping it, since a rule that costs no migration
+and no concept is worth having before the first collision rather than after it.
+That argument does not transfer here, because this rule's cost is a migration by
+construction.
+
+### Nothing resists a bloated requirement, and nothing resists a duplicated one
+
+These two gaps in the intent layer are themselves 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. The guard makes the
+*suite* re-count; it cannot make this file re-read, so every figure below is a
+quotation of that snapshot and is only ever as fresh as the last edit here —
+read the snapshot when the number is what matters. *`compound-requirement`
+(WARNING) — rejected.* More than one RFC-2119 keyword in one `statement` is
+objectively more than one obligation. Measured (figures re-read from the suite,
+which is the only place they are not prose): of the 8 requirements in the corpus
+carrying more than one, it flags 3 (`ATX-10`, `ATX-21`, `ATX-26`) 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
+7 of 8, at 3 wrong hits (`ATX-6`, `ATX-22`, `ATX-23`) rather than the 1 recorded
+when it was first scored — so reach is not the deciding argument, and the
+precision it trades away grows with the registry. 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,
+then `ATX-25`, then `ATX-26`, 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. `ATX-26` added the
+sharper version of the same point: it names the *same* diagnostic as `ATX-17`,
+so the two now agree by coincidence and `ATX-17` drops out of the set the rule
+reports — a rule that reads agreement as safety falls silent on a pair it had
+been flagging, for a reason that has nothing to do with either requirement. **A
+second param name now collides, and that is what closes the last defence of the
+rule.** `file` names a path Attest writes — the agent skill in `ATX-27`, a
+change's first-run record in `ATX-30` — two unrelated constants, a third wrong
+firing. Until it appeared, every false positive had been on the single name
+`code`, which left "pick a less generic param name" open as a repo-side
+workaround and therefore left the rule arguably salvageable. It is not the word:
+two requirements owning unrelated constants of the same *kind* is the structure,
+and any registry large enough to be worth linting has it. Still zero true
+positives, now across a 34-entry corpus (the `corpus` figure in the suite's
+snapshot, which counts a fixture id once per registry file that declares it).
+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.
+
+### A freshness gate on the file `attest init` writes (`init --check`)
+
+`render --check` is the obvious precedent and is the opposite case. A rendering
+is a function of the *user's registry*, so its staleness means the user moved
+intent without regenerating — a real signal, with the fix in their hands. The
+skill is a function of the *installed version*, so a gate on it turns red on a
+change the user did not make, and is cleared by a commit containing no decision.
+That is a chore wearing a diagnostic's clothes, and a gate that cannot be about
+anything the reader did is worse than no gate — the same standard 0.1.6 set when
+it gave `render` no formatting options at all. An earlier draft of `attest init`
+spent a second command, this gate and a second self-requirement on it. What that
+would have bought is immunity to one honest and small exposure: an old file
+describes an old workflow to an agent that trusts it. The backstop is that every
+mistake it can cause is already a diagnostic with a fix hint — a registry
+written the old way is `registry-not-static` — so the agent corrects itself from
+the report, and `init` is idempotent, which makes re-running it the entire
+update mechanism. Recorded here rather than left in the 0.3.0 entry that shipped
+`init`, because the queue above depends on it: a gate is the first thing
+proposed each time a new agent target is considered, and the answer must not
+need re-deciding per target.
+
+### A marked block in the adopter's `AGENTS.md` / `CLAUDE.md`
+
+The cross-tool convention Codex, Cursor and Copilot read, and the reason it
+looks like the obvious next target after the skill is that it reaches the most
+agents per unit of work. Rejected on three counts, none of which is about
+effort. **It is the only file `init` would write that Attest does not own.**
+`.claude/skills/attest/SKILL.md` exists because Attest exists; `AGENTS.md`
+exists because the *project* does, and what is in it is prose its maintainer
+wrote and curated. Writing a block into it means an idempotent read-modify-write
+on someone else's document — find the markers, preserve everything outside them,
+and then handle the markers being absent, duplicated, hand-edited, moved, the
+file missing, the file being `CLAUDE.md` instead, or both existing. That is a
+merge tool, and each of its failure modes is destructive on a file the user
+cannot regenerate. **It would remove the property that makes `init` safe to
+automate.** `skillContent()` takes no argument — the content is a pure function
+of nothing at all — so `init` is one atomic write and its idempotence holds *by
+construction*, which is what lets "re-run it after upgrading" be the whole
+update mechanism and be safe in a script. A marked block makes the output a
+function of the file already there, demoting idempotence from a property of the
+design to a behaviour that needs test coverage, on the one path where being
+wrong destroys input. **It is a worse carrier for the same text.** An
+`AGENTS.md` block is unconditionally resident in the agent's context, where a
+skill body is loaded when its description matches — so every unrelated request
+in that repo pays for a workflow it will not use. It was never a port of the
+skill; it is a second, weaker capability wearing the same words. The interaction
+with the entry above is what settles it: a user-edited block cannot be replaced
+on upgrade without discarding the edit, so this shape needs either the freshness
+gate rejected above or a three-way merge. *What replaces it*, for an adopter
+whose agent reads `AGENTS.md`: one line they add themselves, pointing at the
+skill file. A pointer is cheap enough to be resident, it is their edit in their
+file, and it cannot go stale — the file it names is the one `init` keeps
+current.
+
+### A Codex target for `attest init`
+
+Evaluated when `init` grew `--target` and shipped for Claude Code, Cursor and
+Copilot; rejected because the tool offers nothing to write, not because of what
+writing it would cost. Codex's project-scoped instruction surface is
+`AGENTS.md`, which the entry above rejects permanently, and its custom prompts
+live in `~/.codex/prompts` — per machine, outside the project root `init` is
+pointed at, and not a thing a project can commit or a CI checkout can carry.
+That leaves no path that is both **Attest's own** and **read by the tool**, so
+the two rules a target has to satisfy are not merely unmet here, they are
+unmeetable with what exists: any Codex-shaped implementation would be either the
+rejected merge or a file nothing reads, and the second is worse, because it
+looks like coverage. Filed here rather than queued as a candidate, since nothing
+about the effort or the evidence is what is holding it — the pointer line above
+is the whole answer for a Codex user, and this reopens only if Codex grows a
+project-scoped path of its own.
+
+### A committed snapshot of the params
+
+Design §11 records the measurement this answers: editing a param (`'main'` →
+`'trunk'`, one entry dropped from a nine-element list) leaves `attest check` at
+`✓ No issues`, because the single source makes a value impossible to *diverge*,
+which is not the claim that it is flagged when it *moves*. The candidate was the
+shape `render --check` already proves — a `params.lock` beside the registry, or
+`check --params-check` — and the mechanism would have worked. *What rejected it:
+the precedent is the objection.* §9 states when a freshness gate earns its
+place, and a rendering earns it because it is a function of the *user's
+registry*, so staleness means the user moved intent without regenerating — a
+real signal with the fix in their hands. A params snapshot is a function of the
+registry too, but the population it fires on is different: **every legitimate
+param edit turns it red, and the fix is a commit containing no decision.** That
+is precisely the chore §9 declined to ship for `init`, and it is worse here
+because of frequency — intent is rendered rarely, while params move whenever a
+value moves, which is the entire reason they are params. The gate would spend
+its whole life red about correct edits, and a gate that is usually wrong about
+staleness is the failure mode §9 names as worse than no gate. *What the gap
+keeps instead.* §6's mechanism 3 already exists to make this exact absence
+visible: `possible-drift` fires when a requirement owns params that no covering
+scenario reads, which is the only condition under which a moved param goes
+unnoticed. The mechanism that guards a param is a scenario reading it, not a
+file recording it. This reopens only on an adoption report where a param moved,
+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.
+
+### Grouping `render`'s output by prefix
+
+The *detection* half of this is already rejected above (every automatic
+candidate either saw almost nothing or was a similarity matcher, which is what
+§0 exists to remove), leaving human review at propose (§7) as the answer — and
+the idea was to help that review by putting requirements about one subject side
+by side in the one document a human reads end to end. *What rejected it: the
+ordering already ships, and the adjacency it buys is not where the gap is.*
+`compareIds` (`render.ts`) has ordered the document by prefix first and number
+second since `render` shipped, so same-prefix requirements are **already**
+adjacent; the candidate was never an ordering change, only a heading over an
+ordering that already holds. And §11's own example of the gap is `AUTH-3`
+expiring a session against `SESS-7` saying sessions never expire — a
+contradiction **across** prefixes, which prefix grouping pushes further apart
+rather than closer. What remains is a reader aid for same-prefix contradictions,
+which are the pairs already adjacent and therefore the ones review is least
+likely to miss, bought at the price of changing the bytes of every committed
+rendering and turning `render --check` red across every adopting repo on upgrade
+— for a change the user did not make. *The gap itself stays open* and stays
+where it belongs, in design §11: nothing resists a duplicated or contradictory
+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.3...main
+[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
 [0.3.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.3.0