@am_shork/attest 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -15,6 +15,441 @@ not API.
 
 ## [Unreleased]
 
+## [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
 
 A wall of identical diagnostics now says once that it is one cause, and the
@@ -361,66 +796,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 +1116,164 @@ 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.
+
+- **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.
+
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.3.0...main
+[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