@am_shork/attest 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -13,6 +13,550 @@ 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.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
+README again — the reference it had grown into has a page of its own, in both
+languages, saying which version each part of it arrived in. No behaviour a CI
+step branches on changed; the human report gains one line per issue.
+
+### Added
+
+- **A troubleshooting document, with one section per issue code — and every
+  diagnostic links to its own.** A diagnostic names a rule and states a fix in
+  one line, which is the right size for a reader who already knows the rule and
+  the wrong size for the one who does not — and the second reader is the one
+  adopting Attest, who meets six codes at once on their first run. The knowledge
+  was not missing so much as filed where nobody looks during a failure: the
+  cross-platform traps (a backslash is an escape in a glob; Vitest's 5-second
+  default against a scenario that starts a subprocess) lived in `CLAUDE.md`,
+  which ships with no release, and the rationale lived in a 450-line README
+  nobody greps mid-failure. Both languages, as always
+  (`docs/{en,zh}/troubleshooting.md`).
+
+  What makes this cheap to keep true is that `code` was already the
+  machine-readable name of a rule, so the section heading is the code verbatim
+  and the link is *derived*: there is no second string to keep in step, and so
+  no way to ship a diagnostic pointing at the wrong section. The remaining
+  failure mode — a section that does not exist — is closed from the other end:
+  `Issue.code` is narrowed from `string` to the roster in `core/docs.ts`, which
+  the suite asserts against both documents. An undocumented diagnostic is now a
+  compile error. (That narrowing found two families of codes a regex over the
+  source had missed, because they are built through a helper rather than written
+  at the issue site.) The two readers that restate a *subset* of the roster —
+  `StaticReadCode`, `DeltaReadCode` — are now asserted to be subsets of it in
+  `tests/issue-code-types.spec-d.ts`. That was already caught, but downstream
+  and by accident: the failure surfaced where the code is assigned into an
+  `Issue`, several files from the two lines that disagree.
+
+  Links are pinned to `v<version>` — the tag of the build that printed the
+  diagnostic — not to `main`. The two failure modes are not the same size. An
+  unresolved tag exists only between a release commit and its push, which is a
+  version nobody has installed, so no build in anyone's `node_modules` prints
+  those links. An unpinned link is dereferenced by every installed copy forever,
+  and the first breaking change to a code turns years of shipped builds into
+  links that miss — or worse, land on a section confidently describing a rule
+  that has since been redefined. (`main` remains the fallback for the one case
+  where pinning is impossible rather than imprecise: an unreadable manifest.)
+
+- **`docsUrl` on every issue in `--json`.** Additive, so no `schemaVersion`
+  bump. It is attached in the one envelope every report is built through —
+  including the `internal-error` crash path — rather than at the ~26 sites that
+  construct an `Issue`, for the same reason `hasError` is one function. It is
+  for the human reading a CI log; a consumer should still branch on `code`,
+  which is the more precise form of the same information.
+
+### Changed
+
+- **Every issue in the human report gains a line: `→ <docs url>`, dim, under the
+  message.** The one behaviour change an existing invocation can notice. No exit
+  code moves, no verdict moves, no input that passed now fails, and `--json` is
+  untouched by it — but a snapshot test over `attest`'s stdout will need
+  re-recording. That report is prose for humans by the same rule that makes
+  `Issue.message` prose (see *Versioning* above); the machine surface is
+  `--json`, which is where a CI step should have been looking.
+
+- **`Issue.code` is typed `IssueCode`, not `string`.** Breaking only for code
+  that *constructs* an `Issue` — reading one, which is what `--json` consumers
+  do, gets strictly more type information than before. Nothing in the CLI
+  surface, the report shape or the exit codes changes.
+
+  `SCHEMA_VERSION` stays at 1 for this too, not only for `docsUrl`: the emitted
+  values are the same strings they always were, so nothing on the wire changed
+  and no consumer can tell the difference. The narrowing is a compile-time
+  constraint on this repository, not a report-shape change.
+
+- **The README is a README again; the reference moved to
+  `docs/{en,zh}/cli-reference.md`.** It had become four documents wearing one
+  hat — a pitch, a tutorial, a CLI reference and a running design argument — at
+  470 lines, which is long past the point where a newcomer reads it and well
+  past where anyone looks up a flag in it. It is now 199: the pitch, a
+  five-minute start, and a table of where everything else lives. Nothing was
+  deleted. Per-command behaviour, `--eval`, `--vitest-config`, the run scope and
+  the whole `--json` shape are in the new reference; the rationale for the
+  diagnostics that were argued through in the README (`registry-not-static`,
+  `duplicate-prefix`, `empty-spec`, `stale-spec-doc`) already had a better home
+  in the troubleshooting document, so the reference states the rule and links to
+  it rather than restating the argument a third time.
+
+  Each section of the reference that has changed since it first shipped now
+  carries a collapsed **History** table. Attest is 0.x and moves fast enough
+  that a page describes the latest build to a reader who installed an earlier
+  one, with nothing to tell them which half applies — `--vitest-config` has
+  existed since 0.1.5, the run has been scoped to attesting spec files only
+  since 0.2.0, and the registry has had to be a literal only since 0.2.0. The
+  rows were written from this file. A gate checks that every version they name
+  is a heading in it, so a row cannot cite a version that was never cut; it
+  cannot check that a row is *true*, which still needs a reader with the
+  changelog open. `Unreleased` counts as a heading while one exists — and stops
+  counting when a release removes it, which is what makes renumbering those rows
+  part of cutting the release rather than something to remember.
+
+  The two documentation gates widened with it: they scanned `README.md` alone,
+  and the JSON sample they exist to catch had just moved out from under them.
+  They now enumerate `README.md` plus every `*.md` in both language directories,
+  so a page added later is covered by default rather than by remembering.
+
+- **`packageVersion()` moved from `src/cli/version.ts` to `src/core/version.ts`.**
+  It answers "which build is this", which `core/docs.ts` now has to ask in order
+  to pin a link — not a CLI concern. Neither path is in the `exports` map, so
+  nothing installable can have been importing either.
+
 ## [0.4.0] - 2026-07-28
 
 Reading a registry no longer opens a port or lets the repository under test write
@@ -1319,6 +1863,144 @@ 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 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.
+
+- **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.
+
+- **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.
+
+## 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
@@ -1329,231 +2011,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 `[Unreleased]`), 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.0...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.2...main
+[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
 [0.2.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.2