@am_shork/attest 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -13,7 +13,645 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
-## [Unreleased]
+## [0.4.0] - 2026-07-28
+
+Reading a registry no longer opens a port or lets the repository under test write
+to the reader's terminal, the id prefix finally has something that notices two
+files claiming it, and the peer range now says what CI actually proves rather
+than what the tool was hoped to work on.
+
+### Added
+
+- **Two registry files claiming one id prefix is now an ERROR.** The id grammar
+  is one flat space, `^[A-Z]+-\d+$`, and the prefix inside it was habit rather
+  than scope: nothing allocated it, reserved it, or noticed that two files had
+  picked the same one (design §11). Every cross-file check there was keys on the
+  whole id, so `AUTH-3` in `auth.reqs.ts` and `AUTH-9` in `session.reqs.ts` was
+  a clean `check` — two owners of one space, and the first anyone would hear of
+  it is the `duplicate-requirement` on the day the counters happen to meet, by
+  which point both files have a history. `loadRegistry` (`locate.ts`) already
+  held the `(file, id)` pair in the fold where `duplicate-requirement` is
+  raised, so the whole mechanism is a prefix→file map in that same loop, and
+  because it is that fold, every command that reads intent gets the diagnostic:
+  `check`, `cover`, `render`, `status`, `verify`, `archive`.
+  **What the issue carries.** `file` is the file that arrived *second* in sorted
+  order, matching `duplicate-requirement`, which also files against the file
+  being folded — and the file that claimed the prefix first is named in the
+  message, because a collision is a fact about a pair, an `Issue` carries one
+  path, and an error naming only one end leaves its reader grepping the
+  repository to find the other. There is **no `reqId`**: the ids involved are
+  individually valid and it is the space above them that has two owners, so
+  there is no single requirement the issue is about. It is raised **once per
+  colliding prefix per file**, not once per requirement — a registry with forty
+  ids under a taken prefix reports one sentence, not forty. Where a duplicate id
+  is also present both fire, which is not a restatement: sharing `A-1` implies
+  sharing `A-`, and the converse — the case this exists for — does not hold.
+  Now a requirement (ATX-39).
+  **Not a behaviour change for anything that passes today**, and that was
+  checked rather than assumed: all six `*.reqs.ts` in this repo sit in six
+  separate project roots holding one registry file each, so no root has two
+  files to collide. It is still a new ERROR on input that used to pass, so an
+  adopter whose registries share a prefix goes red on upgrade with nothing else
+  changing — deliberately, since that is the state the rule exists to report,
+  and the fix is a prefix rather than a migration. `SCHEMA_VERSION` stays 1: a
+  new `code` value is additive, and neither the envelope nor the `Issue`
+  interface moved.
+  The other half of the rule this was cut from — that a prefix must match its
+  file's name — was **rejected**; see "Considered and rejected".
+
+### Security
+
+- **Reading a registry opened a network port.** The loader borrows Vite to
+  transform and evaluate a `*.reqs.ts`, and `middlewareMode` suppresses Vite's
+  HTTP server but not its HMR WebSocket server — so `verify`, `archive`, and any
+  read command under `--eval` bound port 24678 on *every* interface for the
+  length of the run, on developer machines and CI runners alike, for a channel
+  nothing here subscribes to. `server.ws` is now `false`, which is the option
+  that actually closes it: `hmr: false` does not, because the socket is created
+  before the HMR option is consulted. The visible symptom was two concurrent
+  runs colliding and printing `WebSocket server error: Port is already in use`
+  into the middle of a report, through a log level that was supposed to have
+  silenced the loader. Now a requirement (ATX-36), asserted as a count of
+  listening handles rather than a port number, because the port is Vite's to
+  change and the property Attest needs is that reading intent is not a network
+  operation.
+- **The human report let the repository under test write to the reader's
+  terminal.** Scenario names and file paths are quoted verbatim into
+  `orphan-test`, `declared-not-run` and `never-red`, and the parser hands back
+  the *cooked* string — so an escape written in a spec file arrived at the
+  terminal as a real control byte. On a fork merge request the author of that
+  string is not the person reading the report, and the payload erases lines,
+  repaints a red verdict green, or retitles the window. Every control character
+  except the newline is now replaced with a space, in the message, the file
+  path, the code, and the ids and change name a `status` report prints. The
+  newline survives, because `registry-invalid` legitimately carries a list of
+  field errors — but the continuation is indented, so injected text cannot
+  occupy the column a genuine header does. `--json` was never affected
+  (serialising escapes the same characters), which is exactly why this had to be
+  fixed on the side people read. Now a requirement (ATX-37).
+- **Dependency advisories, and a gate so the next ones are not found by hand.**
+  The dev toolchain moved to Vite 8 and Vitest 4, clearing a high-severity
+  `server.fs.deny` bypass on Windows alternate paths, an NTLMv2 hash disclosure
+  via UNC path handling, two moderate path-traversal/dev-server advisories, and
+  a critical Vitest UI advisory that this tool never reached but shipped in its
+  lockfile regardless. `brace-expansion` is pinned past its DoS advisory through
+  a `pnpm.overrides` entry, since it arrives only through ESLint. A new `audit`
+  CI job runs `pnpm audit --audit-level=high`, not `allow_failure`: it is the
+  one job here that can go red on a commit that changed nothing, which is the
+  point — a dependency becomes vulnerable on the day it is disclosed, not on the
+  day someone next edits `package.json`. This also closes a real coverage gap:
+  `peerDependencies` has claimed Vite 8 and Vitest 4 since 0.3.0 while CI only
+  ever ran Vite 5 and Vitest 2.
+
+### Fixed
+
+- **`--eval` crashed on a registry the reading path diagnoses properly.** The
+  evaluating reader called a module's default export a registry because it was
+  an object — an assertion standing in for a check, on the one path where the
+  value has not already been through `defineRequirements`. A file that
+  default-exports a plain literal instead of calling it therefore arrived at the
+  validator unchecked, where reading `.statement` off a number threw: `--eval`
+  answered with an `internal-error` carrying a raw TypeError, for a file the
+  static reader reports with a code, a line and a fix hint — and that fix hint
+  is "pass `--eval`", so the documented way out of one diagnostic led into a
+  crash. The evaluating path now hands what it loaded to the same
+  `RegistrySchema`, so both readers refuse the same file. Behaviour change for
+  anyone branching on the code: this input used to produce `internal-error` and
+  now produces `registry-invalid`; both are ERRORs, so no exit code moves. It is
+  also a stricter read than before — a registry that `--eval` accepted only
+  because nothing looked at it is now rejected, and unknown fields are stripped
+  by the schema exactly as `defineRequirements` already strips them. Now a
+  requirement (ATX-38), kept apart from ATX-17: that one promises the escape
+  hatch exists and is honest about its cost, and a reader can satisfy it
+  completely while validating nothing it evaluates — which is the state this
+  was in.
+- **A corrupt first-run record leaked a value that is not an outcome into the
+  report.** Reading `changes/<name>/first-run.json` asserted its contents rather
+  than checking them: the guard tested that `firstRun` was an object and was
+  *declared* to return the record type, so a hand-edited or half-written file
+  put an arbitrary string where `pass`/`fail` is the whole domain. It travelled
+  — out through `status`'s `progress[].scenarios[].firstRun`, whose declared
+  type is `Outcome | null`, into the `--json` contract, and into a human row
+  whose hint matched neither "passed first" nor "never run" and so printed
+  blank. The archive gate was never at risk, because `hasRecordedRed` compares
+  against `fail` and anything unrecognised blocks exactly like a missing record;
+  this closes the report, not the gate. A record that does not validate is now
+  discarded whole, which is the existing "no more permissive than a missing
+  file" rule one step further: the cost is a stage-1 run to re-observe, and
+  keeping the entries that happened to parse would present a partial history as
+  if it were the whole one. Behaviour change confined to corrupt files: that
+  `--json` field now reads `null` where it used to echo whatever was on disk.
+- **The test verdict could fail open.** `runAndCollect` read the failure count
+  through `getCountOfFailedTests?.() ?? 0`, but the method is required on
+  Vitest's state — so the guard was dead at the type level, and had it ever
+  become live it defaulted the wrong way, reading a missing API as zero failures
+  and turning a red suite green. Latent rather than observed: no released
+  version reported a wrong verdict because of it. This is the one boolean in the
+  engine that may never fail open.
+- **`archive` answered `internal-error` for a file `status` diagnoses
+  properly.** A `requirements.delta.ts` that loads but default-exports nothing
+  reached `applyDelta` as `undefined`, where reading `.renamed` off it threw a
+  TypeError — so the gate crashed out through the `--json` envelope's crash path
+  instead of reporting `change-not-found`, and the fix hint went with it.
+  `archive` now makes the same check `status` already made. Behaviour change for
+  anyone branching on the code: this input used to produce `internal-error` and
+  now produces `change-not-found`. Both are ERRORs, so no exit code moves.
+- **A sibling change directory containing a backslash silently widened the
+  archive gate.** `escapeGlob` escaped every glob metacharacter except
+  glob's *own* escape character, so a name like `a\b` — legal on POSIX — did not
+  merely go unescaped: the backslash escaped the character after it, and
+  `**/changes/a\b/**` matched `ab` and never the directory. That proposal's
+  specs then joined the run of the one check that decides whether a change is
+  done. Covered by ATX-13, which already stated the property.
+- **A self scenario that compiled a TypeScript program had no explicit
+  timeout**, so it fit inside Vitest's 5-second isolated-run default until the
+  toolchain moved and then failed as `tests-red` with no assertion behind it —
+  the failure mode the repo's other long scenarios already carry a timeout to
+  avoid.
+
+### Changed
+
+- **BREAKING: the peer range is now `vite ^8` and `vitest ^4`, down from six
+  majors.** `^5 || ^6 || ^7 || ^8` and `^2 || ^3 || ^4` was a claim about six
+  combinations that no job ever ran end to end. What it looked like from inside
+  the repo — the security entry above says as much — was that the *top* was
+  untested; the fixture told a different story. `fixtures/consumer` pinned
+  `vitest ^2.0.0` / `vite ^5.4.0`, and the consumer job is the **only** thing in
+  this pipeline that resolves peers at all, so the two ends were each proven by
+  one job apiece and `vite ^6`/`^7` and `vitest ^3` were proven by nothing.
+  Advertising a version nobody runs is the same defect the `audit` job was added
+  to close, one layer out: the failure surfaces in an adopter's repository, not
+  here.
+  **Two of them had already stopped being merely untested.** `verify` reads
+  `startVitest` as `Promise<Vitest>` — the dead null guard removed above was
+  there for the older signature — and ATX-36 asserts a listening-handle count
+  against whichever Vite is installed, so on any other major the socket
+  guarantee is a claim rather than a measurement. Neither is a defect that would
+  announce itself; both fail in the direction of looking fine.
+  `fixtures/consumer` moves to `vitest ^4` / `vite ^8` with the range, because
+  npm refuses an unmet peer and the fixture exists to install the way a user
+  does. That does cost something real and it is worth naming: the consumer job
+  no longer exercises a second Vite/Vitest pair, so this trades a spot-check of
+  one old combination for a claim that matches the tested one. A matrix is what
+  buys the breadth back, and nothing here pretends this is that.
+  **Who this breaks:** anyone on Vite 5–7 or Vitest 2–3 fails to install on
+  upgrade, with no deprecation window. Under this file's Versioning rule that is
+  a minor, which is what 0.4.0 is. The engine may well still work on some of
+  them — that is precisely the claim there is no evidence for, and `0.3.x`
+  remains the version whose manifest makes it.
+
+- **Type-aware linting, and `exactOptionalPropertyTypes`.** The three defects
+  above are one shape — an assertion standing in for a check — and the untyped
+  ESLint preset cannot see any of them, because deciding whether an `as` or a
+  `?.` is doing work needs the checker. `recommendedTypeChecked` now runs over
+  `src`, `tests` and `self`, with `no-unnecessary-condition` promoted out of the
+  strict preset; the rest of that preset is deliberately not adopted, since its
+  bulk is `no-non-null-assertion`, and here `!` is the counterpart of
+  `noUncheckedIndexedAccess` — banning it would trade a compiler-enforced
+  guarantee for a lint-enforced style. `fixtures/**` stays on the untyped preset
+  because several fixtures are invalid on purpose. Turning the rules on removed
+  a double cast that hid Vitest's task-tree shape from the compiler, a redundant
+  assertion in the delta reader that made an unvalidated value look checked, and
+  a dead `startVitest` null guard left over from an older Vitest signature.
+  `exactOptionalPropertyTypes` is now on as well: the codebase already followed
+  it by hand — the `...(x === undefined ? {} : { key: x })` idiom appears in
+  every Issue builder — so this makes an existing discipline the compiler's job
+  rather than review's. No `--json` shape changed, so `SCHEMA_VERSION` stays 1.
+
+## [0.3.0] - 2026-07-27
+
+The workflow half now reaches the agent that will read it, the archive gate can
+tell a test that ever discriminated from one that never could, and a change in
+flight has a reportable state between "not started" and "done". Underneath all
+three: every path Attest derives from a project root now has one spelling on
+every platform, which is what makes them work on Windows at all.
+
+### Added
+
+- **The workflow reached one agent, and every other agent got the engine without
+  it.** `attest init` wrote `.claude/skills/attest/SKILL.md` and nothing else —
+  the gap `init` exists to close, still open for every tool but one. It now takes
+  `--target`, repeatable, and writes the same document for Claude Code (the
+  default), Cursor (`.cursor/rules/attest.mdc`) and GitHub Copilot
+  (`.github/instructions/attest.instructions.md`).
+  **Two rules decide what may be a target, and the first was already permanent.**
+  *Attest owns the path*: each file above exists because Attest exists, is
+  written whole, and reads nothing of the user's — which is why an `AGENTS.md` or
+  `CLAUDE.md` marked block stays rejected outright (see "Considered and
+  rejected"), and why the answer for an agent that reads only such a file is a
+  one-line pointer the user writes themselves. *The instructions load on demand*
+  is the second, and it was the open question when this was queued: a skill body
+  is fetched when its description matches, a Cursor rule when the agent asks for
+  it (`alwaysApply: false`, and deliberately no `globs`, which is the auto-attach
+  trigger and a different thing), a Copilot instructions file when the open path
+  matches its `applyTo`. A carrier that is unconditionally resident charges every
+  unrelated request in the repository for a workflow it will not use.
+  **One document, three frontmatters, and that split is a requirement (ATX-34).**
+  Each target carries the same body byte for byte; only the frontmatter differs,
+  because that is the part the tool parses rather than the part the agent
+  follows. A copy per tool would be two agents told different things about one
+  engine — the drift this framework exists to report, occurring where nothing
+  reports it, since no command reads these files back. The requirement is written
+  over *every* target rather than over a list of them, so adding one cannot
+  satisfy it by being left out. What it costs falls on the targets with no
+  description-triggered mode: Copilot's trigger is the path, and `applyTo` names
+  the registries, the specs and `changes/`, so the instructions arrive when the
+  agent is editing intent and not when it is editing an implementation to make a
+  scenario pass — which is exactly when "do not edit the scenario instead" would
+  be worth reading. Widening that glob to `**` buys the missing case at the price
+  rule 2 declines to pay.
+  **Naming no target writes what it wrote before; an unknown name writes nothing
+  at all (ATX-35).** Writing every target by default would scatter configuration
+  for editors nobody in the project uses. Refusing the whole set on an
+  unrecognised name is the ATX-13 argument under a different name: a name already
+  known to be unusable must not cause a single write, or a failing run leaves a
+  repository carrying instructions for some agents and no statement of which.
+  Two requirements rather than one, for the ATX-23/ATX-24 reason — an
+  implementation that writes every known target on every run carries one document
+  faithfully, and one that gets the requested set right can still fail on an
+  unknown name after writing half of it. `unknown-target` is a new `code` on the
+  existing `Issue` shape.
+  **Codex was evaluated and is not a target**, because the tool offers no path
+  Attest can own: `AGENTS.md`, or prompts under `~/.codex/prompts`, outside the
+  project root entirely. Recorded under "Considered and rejected", where it stays
+  findable once this release is history.
+  **It shipped without the evidence the queued candidate demanded.** That
+  candidate named one line in one adoption report naming a tool as its trigger,
+  and no such line arrived: the three targets are a judgement about which tools
+  adopters use, and should be read as one. What limits the cost of being wrong is
+  that the guess is now priced per row — the document, the writer and the CLI are
+  general over the table, so a target is a path, a frontmatter and a scenario —
+  and that the two rules above are what keep the table from growing into a
+  distribution tail. The measurement behind that phrase, kept because it is the
+  argument for where the next effort goes: OpenSpec 1.6.0 publishes 25,733 lines
+  of `dist/` against this package's 2,513 lines of `src/`, roughly four fifths of
+  it distribution rather than engine (29 per-tool adapters, 1,169 lines of
+  `init.js` and `update.js`, three shell-completion installers) — while its engine
+  is the weaker half on every axis this project was built to win: a `verify` that
+  asks the agent for "reasonable inference" where §8's gate takes a set
+  difference against the Vitest task tree, a requirement primary key that is the
+  Markdown header text, and a Markdown reader carrying a visible repair history
+  that an AST does not pay. The gap was never engine quality; it was that
+  `openspec init` is one command and this was a paste. Twenty-nine adapters
+  against three targets is what remains of that comparison, and widening it needs
+  a named tool with a reader blocked on it, not a count of tools that exist.
+  *Additive:* `attest init` with no flags writes the same bytes to the same path
+  as before. `--json` gains `outFiles` — every file written, since a run can now
+  write several — and keeps `outFile` whenever exactly one was, which the default
+  invocation still is, so `schemaVersion` stays `1`. The only new exit-1 path is
+  reached through a flag that did not exist before this release.
+  Two measurements moved. `divergent-param` collected a **seventh** member on
+  `code` (ATX-35), still with zero true positives. And `compound-requirement`'s
+  reach passed its blind spot for the first time: the suite asserted
+  `missed.length >= correct.length`, and ATX-35 falsified it by arriving, like
+  ATX-33, with both obligations declared under two keywords. `missed` lost no
+  member — the rule sees no further, and what moved is how carefully the corpus
+  was written. Rewriting that assertion to fit would have been the measurement
+  bending to the corpus, so it now asserts what actually blocks the rule (the
+  blind spot never empties), with the movement in the inline snapshot.
+
+- **A change had one touchpoint, and it only ever answered "not yet".**
+  `attest archive <change>` decides whether a change is done; between "not
+  started" and "archivable" there was no reportable state at all, so asking what
+  remained meant reading the delta, cross-referencing the specs and inferring —
+  work an agent redoes on every turn and a person does badly. `attest status
+  <change>` reports each requirement the change ADDs as one of three states:
+  `no-scenario`, `unproven` (a scenario exists but has never been seen failing)
+  or `proven`. It runs nothing, reading the delta, the specs and
+  `changes/<name>/first-run.json`.
+  **Its blocker was that there was nothing to report, and mechanism 2 removed
+  it.** This was queued under "Under consideration" with exactly that objection:
+  Attest has no artifact graph and should not grow one, so the only progress
+  signal worth printing is per-id — which added requirements have a scenario, and
+  whether that scenario has been red — and the red half did not exist. Shipping
+  mechanism 2 in this same release made `first-run.json` precisely that per-id
+  state, which reduced the entry to a presentation question. What decided it is
+  that the fork the entry named is now cheap on one side: a `status` that runs the
+  suite is `verify` with a filter, and the one that does not is a small file read
+  plus a static plan.
+  **It is a projection of the gate, not a second gate.** Each state is named
+  after the issue `archive` will raise — `no-scenario` is
+  `uncovered-requirement`, `unproven` is `never-red` — and the decision runs
+  through the gate's own predicate, extracted as `hasRecordedRed`, for the reason
+  `declaredNotRunIssues` and `uncoveredIssues` were extracted before it:
+  agreement between two verdicts should be structural, not clerical. The plan and
+  the added-id set come from the same two functions `archive` uses, so a progress
+  report cannot be computed over a different spec set than the gate's.
+  **Progress never reaches `ok`, and that is a requirement rather than a
+  detail.** The cheapest implementation is to push the existing `uncovered-` and
+  `never-red` issues into `issues[]` — which satisfies the reporting obligation
+  completely while putting them in `summary.error`, where the shared `hasError`
+  verdict turns them into `ok: false` and exit 1. That is the normal state of
+  every change in flight, so a CI step or an agent loop wrapping `status` would
+  read "failing" for the change's whole life. Split across two self-requirements
+  (ATX-32, ATX-33) for the same reason ATX-23/ATX-24 were: the wrong
+  implementation passes the first and needs a scenario, not a clause, to catch.
+  The one thing that does make it fail is intent it could not read — a missing or
+  unreadable delta — because a command that answered ok over an empty table would
+  be the vacuous green ATX-18 and ATX-26 each closed elsewhere.
+  **What it cannot answer is `tests-red`**, and the human rendering closes by
+  saying so (`Not a verdict: run attest archive <name>`). A column of green ticks
+  here means the readable obligations are met, and a report that can be mistaken
+  for a verdict is worse than no report.
+  **It reads the delta from source, so `status` joins ATX-16's static commands.**
+  That requirement's `staticCommands` param grows to four and its statement now
+  says "the intent they report on, whether a registry or a change delta" — the
+  registry extractor was generalised over the authoring function's name rather
+  than copied, so `delta({ … })` goes through the same one walker that decides
+  whether a value is fixed by the source text. A delta that is not a literal is
+  `registry-not-static` and a file that exports no delta is `change-not-found`:
+  both are codes `archive` already emits, so no consumer learns new vocabulary.
+  `--eval` is the same named way back it is everywhere else. The exposure this
+  closes is worse than the registry's, not better — `changes/` holds a proposal
+  still under review, and a reporting command is the last thing that should
+  execute it.
+  The design document carries it in the four places that were describing the old
+  set rather than only in §9: §2 and §5.1 name the reading commands, §7 states
+  for the first time that a delta is a literal on the same terms as a registry —
+  an authoring rule that existed the moment `status` read one — and §8 says which
+  of its own four checks the projection covers, and which one only the suite can
+  answer. §11's "Attest's own 29 requirements" was the kind of live count that
+  goes stale in silence, and is now phrased so it cannot. The README carried the
+  same three-command list in two places and an "all three commands" that had
+  become four, both now corrected, and it states the delta rule where it states
+  the registry one.
+  *Additive only:* a new `command` value and the new optional `progress` /
+  `added` fields, so `schemaVersion` stays `1`. No existing command's output
+  changes. The skill `attest init` writes gains the command, which re-running
+  `init` adopts.
+  One measurement moved with this change, recorded because it is evidence about a
+  *rejected* rule: `divergent-param` collected a **sixth** member on `code`
+  (ATX-33 joining ATX-18, ATX-21, ATX-25, ATX-26 and ATX-31), still with zero
+  true positives, and `compound-requirement`'s reach reached parity with its
+  blind spot for the first time (5 correct, 5 missed) — not because the rule
+  improved, since `missed` lost no member, but because ATX-33 was written with
+  both of its obligations declared. A rule whose score rises when the corpus is
+  written more carefully is measuring the authors, which is the objection to
+  shipping it, now stated by the measurement rather than in prose.
+
+- **The archive gate certified that a change's tests pass, never that they ever
+  discriminated.** §6 describes three anti-drift mechanisms; mechanism 2 —
+  red/green expectation tracking — was written as shipped behaviour and had
+  never been built (0.2.0 corrected the document and named the gap). The gate
+  required green at archive time and nothing else, so a scenario that asserts
+  nothing has been green since the commit that added it and cleared the gate
+  exactly like one that drove an implementation. It ships now, and the anti-drift
+  budget is three mechanisms rather than two.
+  What made it buildable is that **the observation already existed and was being
+  thrown away**. The workflow has stage 1 run `attest archive <name>` and *expect*
+  `tests-red` — the skill `attest init` writes says so, and then says "nothing in
+  the engine will catch that later. This paragraph is the mechanism." A paragraph
+  asking a reader to be diligent is the thing this framework exists to replace,
+  and the engine had seen every one of those reds. `archive` now records how each
+  of a change's scenarios ended on its first run, into
+  `changes/<name>/first-run.json`, and blocks with a `never-red` ERROR on any
+  requirement the delta ADDs whose scenarios have no recorded failing run.
+  **A committed generated file, which this project otherwise treats as a
+  liability** — the argument against `init --check`, the reason `render` takes no
+  formatting options. The difference is lifetime: `changes/<name>/` is temporary
+  by construction and goes away when the change is archived, so this file has
+  exactly the change's lifetime and never becomes a permanent asset that can
+  drift. It is committed rather than kept in a scratch directory because the gate
+  has to reach the same verdict on a CI runner's fresh checkout as on the
+  author's machine — and because it is evidence, which belongs in the diff a
+  reviewer reads.
+  **The record is monotonic toward failure, and both halves of that are
+  load-bearing.** A recorded failure is permanent: by the time a change is
+  archivable everything is green, so a record that kept the latest outcome would
+  say "green" about a scenario that spent the whole change red. A recorded *pass*
+  is deliberately not permanent — plain first-write-wins was the first design
+  here, and it makes the defect this mechanism exists to catch unrecoverable,
+  since the fix for a scenario that asserts nothing is to give it a real
+  assertion and watch it fail, an observation that could then never be recorded.
+  The only way out would have been deleting the evidence by hand, which would
+  equally delete a genuine red. A later failure replacing an earlier pass cannot
+  be abused, because producing one requires the scenario to actually fail.
+  **Scoped to ADDED requirements only, and §11 now records what that leaves.** A
+  requirement written straight into the base registry describes behaviour that
+  already exists — the brownfield adoption, and most of this repo — so there was
+  never a moment when its scenario should have failed; blocking those would make
+  the mechanism fire hardest on the honest case. The guarantee is therefore a
+  property of the `changes/` workflow, not of the registry as a whole.
+  *Behaviour change, for a project mid-change:* a change whose scenarios were
+  never observed failing flips from archivable to blocked, which is the point,
+  since nothing had shown its tests could fail. The remedy is one gate run before
+  implementing. `never-red` is a new `code` on the existing `Issue` shape, and
+  `--json` gains no field, so `schemaVersion` stays `1`. Two self-requirements
+  (ATX-30, ATX-31) rather than one: a recorder that writes a perfect history and
+  never blocks satisfies the first completely while leaving the gate exactly as
+  weak as it was, and a gate can equally block on an absent record without
+  recording anything.
+  The rejected `divergent-param` rule gained a **fifth** member on `code` and,
+  for the first time, a collision on a **second** param name (`file`, ATX-27's
+  skill path against ATX-30's record path) — see "Considered and rejected", where
+  that second name is what closes off "pick a less generic name" as a workaround.
+
+- **`attest init` — the workflow half of the framework had no entry point.**
+  Everything the engine does has been reachable from the CLI since 0.1.0. The
+  workflow — agree on intent, write the delta, drive the scenarios red, implement
+  to green — was a document (`docs/*/using-attest.prompt.md`) the user had to
+  find and paste into their agent themselves. Everything downstream of that paste
+  worked; nothing led to it. `attest init` writes one file,
+  `.claude/skills/attest/SKILL.md`, carrying that workflow as a **skill** — its
+  description sits in the agent's context, so the agent loads it when the work
+  starts rather than waiting to be handed something. That is the difference that
+  closes the gap: a file the user must remember to invoke would only replace
+  "find the document" with "know what to type". `init` is idempotent — re-run it
+  after upgrading, which is the entire update mechanism.
+
+  **The freshness contract, which the queued entry said had to be designed rather
+  than assumed: there isn't one, and that is the design.** A committed
+  instruction file is a function of the installed version, so it does go stale on
+  upgrade — but staleness only *costs* anything if the tool also ships a gate to
+  turn red about it, and `init --check` is rejected on its own terms under
+  "Considered and rejected", together with the exposure that leaves and the
+  backstop that keeps it small. What belongs here is what the absence of a gate
+  bought: with none to serve there is no reason to keep the prose out of the file
+  either, so it lives in the skill, where an agent reads it with no extra call,
+  and a skill body is loaded on demand — a long document costs context only when
+  it is actually needed.
+
+  **`init` deliberately scaffolds nothing else:** no `requirements/*.reqs.ts`, no
+  `package.json` scripts, no `changes/` skeleton. A generated registry can only
+  be empty — which since 0.2.0 is an `empty-spec` ERROR handed to the user on day
+  one — or invented, and invented intent is worse than none in the one layer
+  whose value is that it is real. What belongs there is the agent's judgement,
+  with the project in front of it, which is what the skill describes.
+  **This is the one thing Attest does not dogfood, and saying otherwise would
+  have been the wrong kind of reassurance.** The skill exists for a project
+  *adopting* Attest — an agent meeting a registry it did not write, needing to be
+  told what a delta is and why its scenarios must be red. This repo is the
+  framework, not an adopter: its requirements describe behaviour that already
+  exists and go straight into the base registry, so it does not run the
+  `changes/` workflow the skill teaches, and a committed copy here would be a
+  file nothing reads. What guards the text instead is `tests/skill.spec.ts`,
+  which asserts the shape an agent depends on — that it parses as a skill, that
+  the description names `*.reqs.ts` so it loads at the right moment, and that the
+  body still teaches the codes a reader will actually hit. That is a weaker
+  guarantee than dogfooding and is named as such: nothing here proves the
+  workflow is followable, only that the file describing it is well-formed.
+  **One correction to the queued entry:** it predicted a `files` allowlist change
+  and therefore a `pnpm run test:consumer` obligation. There is none — the text
+  is a TypeScript module compiled into `dist/`, not a template file, so the
+  published surface is unchanged. `--json` gains `init` as a `command` value and
+  widens the existing `outFile` field to it; both are additive, so
+  `schemaVersion` stays `1`.
+
+- **`scenario` accepts a timeout.** `scenario(name, fn, timeoutMs)`, passed
+  straight through to Vitest's `it`. `verify` runs the suite isolated (design
+  §5.4) — no `vitest.config.ts` unless `--vitest-config` names one — so every
+  scenario got Vitest's 5-second default and a scenario that drives a
+  subprocess, a container or a build had no way to say otherwise. Attest's own
+  suite is the demonstration: two `self/` scenarios each start four child Vitest
+  runs, and they fit inside 5 seconds on Linux and not on Windows. The
+  alternatives are both worse — raising the default for everyone hides a
+  genuinely hung test, and a config file sets one number for what is a property
+  of one scenario — the same shape of objection that rules a CLI flag out as
+  `divergent-param`'s escape hatch under "Considered and rejected", where a
+  per-invocation switch is asked to carry a permanent property of the source.
+  Additive: existing two-argument calls are unchanged. Deliberately **no
+  self-requirement**: the contract here is Vitest's
+  own signature and this is one argument forwarded to it, and the only scenario
+  that would truly discriminate — one that outlives the default — would spend
+  five seconds of every run proving a number Attest does not own. Its absence is
+  observable anyway, as the two `self/` scenarios above.
+
+### Changed
+
+- **BREAKING: `cover` reported a registry it could not read as a registry with
+  nothing in it — and nothing is fully covered.** It was the one reader that
+  discarded the issues from loading the registry (`runCheck` and `runRender`
+  both keep them), so a `registry-not-static` file, a renamed `requirements/`
+  folder, or a moved root left an empty registry behind, and an empty registry
+  has no uncovered requirement in it. The command answered `✓`, `ok: true`,
+  `0 requirements, 0 uncovered`, exit `0` — on precisely the repo whose intent
+  layer had stopped being readable, and in the command a pipeline is most likely
+  to run first, because it neither runs the suite nor executes project code.
+  `attest check` on the same project reported the ERROR correctly, which is what
+  made the gap survivable and also what made it invisible: the two commands
+  disagreed about whether the project was in a reportable state at all.
+  `cover` now carries the load issues, so the verdict follows `hasError` like
+  every other command, and it emits **no rows at all** when the registry failed
+  to load. The second half is deliberate and is the reason this is one change
+  rather than a one-line fix: reporting the error while still printing a table
+  built from whichever registry files did parse would let a partial read pass
+  for the whole. `render` already refuses to emit a document under the same
+  condition, for the same reason — a report computed from a half-loaded registry
+  is a lie, and a lie shaped like a pass is the worst form it can take.
+  *Breaking:* a project whose registry does not read flips from exit `0` to exit
+  `1` — which is the point, since it was never coverable. The human output for
+  that project changes from `(the registry contains no requirements)` to the
+  load error itself; every project whose registry does read is byte-identical.
+  `--json` gains no field (`issues` and `summary` already exist), so
+  `schemaVersion` stays `1`.
+
+### Removed
+
+- **`docs/en/using-attest.prompt.md` and `docs/zh/using-attest.prompt.md`.** The
+  workflow half of these is what `attest init` now writes into the project; the
+  adoption half is the README's Getting started, which npm publishes regardless
+  of the `files` allowlist and so reaches a reader who has installed nothing.
+  Deleted rather than left as a page pointing at either, because a stub is still
+  a file two languages have to keep in sync, and the delivery problem was never
+  the prompt's wording — it was that the prompt lived in the docs directory of a
+  repository the reader may never have cloned. Nothing in the package linked to
+  them. Documentation only: no package surface, and no `files` change (they were
+  never in the tarball).
+
+### Fixed
+
+- **A spec file below the project root never ran on Windows.** `verify` and
+  `archive` derive the child run's `include` globs from the plan's file paths
+  (0.2.0), and those paths came from `path.relative` — so on Windows they were
+  spelled `deep\er\x.spec.ts`. A backslash is an **escape character** in glob
+  syntax, so the pattern matched nothing and the file was dropped from the run.
+  The scenarios in it then surfaced as `declared-not-run`, which is at least
+  loud rather than a false green, but the practical effect was that only a flat
+  layout worked at all — and a flat layout is not what a real project has.
+  The reason it survived this long is a sampling accident: every fixture in this
+  repo keeps its specs at the project root, and so does `self/`, so the relative
+  paths had no separator in them. The single exception —
+  `fixtures/e2e-archive/changes/add-totp/specs/totp.spec.ts` — was the one
+  failing test, which is why this read as "`archive` is broken on Windows"
+  rather than as what it was.
+  Every path derived from the project root now has one spelling (`/`) on every
+  platform, normalised once where it is produced rather than where it is
+  consumed, because the same relative path is also what a report carries: a
+  diagnostic that differs by operating system makes two CI runs impossible to
+  diff. The conversion is conditional on the host separator, never
+  unconditional — a backslash is a legal filename character on POSIX, and
+  rewriting it there would rename a file that exists.
+  *For anyone parsing `--json` on Windows:* `issues[].file` changes from
+  `deep\er\x.spec.ts` to `deep/er/x.spec.ts`. No exit code changes except the
+  ones that were wrong; nothing previously valid is rejected; no field is
+  removed. `schemaVersion` stays `1`. New fixture `fixtures/nested-spec/`, whose
+  only spec is two directories down, is the end-to-end guard (ATX-28).
+- **`render --check` was permanently red on a Windows checkout.** `render`
+  writes `\n`; Git hands the file back as `\r\n` wherever `core.autocrlf` is
+  enabled, which is the installer default on Windows. The freshness check
+  compared bytes, so a fresh clone reported `stale-spec-doc` against a registry
+  nobody had touched, and the fix hint named a command that regenerates a file
+  which is already correct. Any adopter committing a rendering hit this the
+  first time a second machine — or a CI runner — checked the repo out.
+  The check now compares the *document*: a difference of line endings alone is
+  not staleness. This is the same standard 0.1.6 set when it gave `render` no
+  formatting options at all — a gate that can be wrong about staleness is worse
+  than no gate — and it costs nothing, because no carriage return in that file
+  ever came from the registry. Content drift is still reported, CRLF or not
+  (ATX-29). This repo also gained a `.gitattributes` pinning the working tree to
+  LF, so a regeneration is not a whole-file diff on one platform and no diff on
+  the other.
+- **Three of this repo's own tests could not pass on Windows, and one could not
+  fail.** `tests/locate.spec.ts` took basenames with `split('/')`, which returns
+  the whole path when the separator is a backslash.
+  `tests/docs-consistency.spec.ts` filtered source files with
+  `path.startsWith(`${root}src/`)`, splicing a forward slash onto a native root
+  — it matched nothing, so the check that every `§n` citation resolves was
+  passing on an empty set. `self/registry.spec.ts` compared a native path
+  against `ts.Diagnostic.file.fileName`, which TypeScript normalises to forward
+  slashes, so the type-level assertion measured zero diagnostics. Same class of
+  bug as the two above, in the tests rather than the engine.
+  `tests/loader.spec.ts` was separately fragile on every platform: it counted
+  `attest-loader-*` directories in the OS temp dir, making its verdict a
+  function of every other loader alive at that moment. It now asserts against
+  the loader's own `scratchDir`, and a third case pins that concurrent loaders
+  do not share one.
+
+- **`cover --json` could answer `ok: false` with an empty `issues` array.** Three
+  places state one rule for machine consumers — `src/cli/json.ts`'s header, the
+  README, and 0.1.2's entry below — and all three say the same thing: branch on
+  `ok` and `issues[].code`, never on `message`. `cover` was the one command that
+  broke it. Its verdict was computed from the coverage rows
+  (`covered === rows.length`) while its envelope carried no issue at all, so a
+  consumer that followed the documented rule got a failing verdict, a summary of
+  three zeroes, and nothing saying what to fix; recovering the reason meant
+  knowing to read `coverage[]` instead — the out-of-band knowledge the contract
+  exists to make unnecessary. An uncovered requirement now reaches the report
+  twice, as a row and as an `uncovered-requirement` ERROR.
+  **The issue comes from the function `check` already uses.** `uncoveredIssues`
+  is extracted from `validateStructure` and called by both, so the two commands
+  cannot state one fact in two shapes — the same reason `declaredNotRunIssues`
+  was extracted in 0.1.7, and the same argument: agreement between two verdicts
+  should be structural, not clerical. `cover`'s `ok` now derives from the shared
+  `hasError` predicate like every other command, rather than from a second rule
+  that happened to agree with it.
+  *Behaviour change, for anyone already parsing `cover --json`:* a report on a
+  registry with uncovered requirements gains `issues[]` entries and a non-zero
+  `summary.error` where both were empty. `ok` and the exit code are unchanged for
+  every input — an uncovered requirement is the only issue this command produces,
+  so the new predicate returns the boolean the old one did. The human output is
+  also unchanged: the coverage table already renders each uncovered requirement
+  as a red `✗` row, and printing the same fact again underneath it would be noise
+  for the one reader who can see it. No shape change either — `issues` and
+  `summary` are existing envelope fields — so `schemaVersion` stays `1`.
+  The rejected `divergent-param` rule grew a **fourth** member on this change
+  (`code`, shared at that point by ATX-17, ATX-18, ATX-21 and ATX-25), which is
+  the measurement its entry under "Considered and rejected" predicted: a generic
+  param name collides more often as the registry grows, so the rule's
+  false-positive rate rises with adoption. Still zero true positives. ATX-26,
+  later in this same release, then pushed ATX-17 *out* of the set by naming the
+  same diagnostic — the sharper version of the same point, recorded in full
+  under "Considered and rejected" rather than restated here.
 
 ## [0.2.2] - 2026-07-26
 
@@ -361,66 +999,6 @@ that identifies itself as attest output must carry the current `version` and
 `schemaVersion`. Neither can catch a section that describes something unbuilt —
 that is what the inline marker is for.
 
-## Considered and rejected
-
-Decisions **not** to build something, kept where they can be found before the
-same candidate is proposed again. Nothing here shipped, so nothing here belongs
-to a release — this section is deliberately outside the version history and does
-not move when one is cut.
-
-- **Two gaps in the intent layer: nothing resists a bloated requirement, and
-  nothing resists a duplicated one.** The gaps themselves are described in design
-  §11, which is where a permanent property of the design belongs. What is kept
-  here is the list of mechanisms tried and what killed each, so the same three
-  are not proposed again without new evidence. All three were scored against
-  every registry this repo ships *before* any was written into the engine — the
-  order `divergent-param` was originally designed in the wrong way round. The
-  measurement is runnable in `tests/intent-rule-candidates.spec.ts` and fails
-  when a requirement is added without a hand-labelled obligation count, because
-  the reach figure once quoted here went stale exactly that way.
-  *`compound-requirement` (WARNING) — rejected.* More than one RFC-2119 keyword
-  in one `statement` is objectively more than one obligation. Measured: of the 7
-  requirements in the corpus carrying more than one, it flags 2 (`ATX-10`,
-  `ATX-21`) and misses `ATX-5`, `ATX-9`, `ATX-13`, `ATX-14`, `ATX-17` — every
-  one that packs clauses under a single keyword, which is the form the coverage
-  incentive actually rewards. A wider variant (keyword plus a coordinating
-  `and`/`while`/`;`) reaches 6 of 7 with one wrong hit, so reach is not the
-  deciding argument.
-  This is: both variants are silenced by deleting the word that triggered them,
-  and neither can tell that deletion from a real split. `SHALL do A and MUST do
-  B` clears the warning as `SHALL do A and do B` — same two obligations, one
-  fewer normative keyword. A rule whose cheapest fix degrades the artifact it
-  protects does not ship.
-  *`divergent-param` (WARNING) — rejected.* One param name declared with
-  different values in two requirements sharing an id prefix. Measured: it fires
-  twice on this repo and both firings are wrong — `idleTimeoutMin` (`15` in
-  `ATX-3`, `30` in `ATX-10`), unrelated illustrative fixtures, and `code`
-  (`registry-not-static` in `ATX-17`, `empty-spec` in `ATX-18`,
-  `rationale-placeholder` in `ATX-21`), diagnostics that could not possibly
-  agree. The second arrived on its own when `ATX-18` was added and grew a third
-  member on its own again when `ATX-21` was, which is the more damning half: a
-  generic param name collides more often as a registry grows, so the
-  false-positive rate rises with adoption — the opposite of what a shippable rule
-  does. Still zero true positives across 25 requirements. The escape hatch it was blocked on has since been designed
-  and does not rescue it: with no config file the only workable shape is an
-  additive `independentParams?: string[]` on the requirement (a CLI flag is
-  per-invocation for what is a permanent property of two requirements; changing
-  the `params` shape rejects every existing registry). Viable, but it is
-  permanent schema surface for a rule with no demonstrated true positive, and in
-  practice it would be written *after* the warning fires — a one-line silencer.
-  *Countable obligations (breaking) — rejected.* An `obligations: string[]` per
-  requirement, with coverage counted per obligation, removing the lumping
-  incentive at the source instead of detecting it afterwards. Rejected because
-  the **id is already that unit**: splitting into two ids costs two scenarios and
-  buys the same incentive with no new concept (`ATX-11`/`ATX-12` are exactly that
-  split). It would touch the parser, coverage, `render`, `SPEC.md`, delta apply
-  and the `--json` schema, and it relocates the incentive rather than removing
-  it — nothing can force the array to be complete.
-  *Not considered:* similarity matching between statements (token overlap,
-  embeddings). That reintroduces the fuzzy comparison design §0 exists to remove;
-  real semantic duplication needs judgement and belongs to human review at the
-  propose stage.
-
 ## [0.1.7] - 2026-07-26
 
 A change name, a prototype key and a collation quirk each got to decide a
@@ -741,7 +1319,243 @@ Initial release.
   (MIT), whose four-stage engine and diff-first change model Attest's
   architecture is adapted from (re-implemented from scratch, no source copied).
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.2.2...main
+## Considered and rejected
+
+Decisions **not** to build something, kept where they can be found before the
+same candidate is proposed again. Nothing here shipped, so nothing here belongs
+to a release — this section is deliberately outside the version history and does
+not move when one is cut. It lives at the **foot** of the file for that reason:
+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
+[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
 [0.2.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.1
 [0.2.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.0