@am_shork/attest 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -13,6 +13,727 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
+## [0.7.1] - 2026-08-05
+
+### Added
+
+- **`params` takes any JSON value, and the constraint moved to the place it was
+  actually protecting.** A param was a scalar or a list of scalars. The argument
+  for admitting lists — the values most likely to drift are the composite ones,
+  and rejecting them left exactly those outside the one mechanism built to pin
+  them — does not stop at a list: a `kind -> payload` table drifts harder than a
+  flat list of names, and it was the one shape still excluded. `null` comes with
+  it, because refusing it forces a sentinel (`''`, `-1`) that means something
+  else to every later reader.
+  What the old union was defending was not the registry but the **rendering**:
+  `{payloadKinds}` interpolated into a statement as `[object Object]`, in a
+  document reviewers and audit read as the system's promise. That is a property
+  of the interpolation point, so it is stated there — a new
+  **`non-scalar-interpolation`** ERROR from `check` and `verify`. Narrower and
+  truer: it refuses what actually breaks and admits the data a scenario reads,
+  which the schema rule could not tell apart. What the schema keeps is what does
+  not survive being written down — a function, a `Date`, a class instance, an
+  object whose prototype was swapped.
+  *The part that is not a schema edit.* Depth. Four obligations had exactly one
+  level of reach, which is correct only while a param cannot nest, and none of
+  them fails loudly: the canonical form behind `add-conflict` (an identical copy
+  written with its inner keys in another order would have conflicted with
+  itself), the ATX-58 control-character stripping (nested strings would have
+  gone unsanitised, reopening the hole `[0.7.0]` closed), the key order behind a
+  byte-stable rendering, and `splice.ts`, which writes a requirement back out as
+  TypeScript source and would have committed `[object Object]` into a
+  `*.reqs.ts` through `archive --apply`. Three of the four are ordering, and are
+  now one shared `sortDeep` in `order.ts` rather than three sorts a level deep —
+  they wanted the same guarantee for the same reason, which is what makes it one
+  function and not a helper each.
+  *Two divergences between the readers, which is what the differential suite is
+  for.* `null` is a keyword rather than a literal node, so the AST reader fell
+  off the end of `literalValue` and reported `registry-not-static` for the whole
+  file while the evaluating reader accepted it. And `{ __proto__: … }` swaps the
+  prototype instead of creating a key, so `z.record` copies own keys into a fresh
+  object and the taint is invisible one step later — the static reader refuses
+  that source at any depth, and the schema now refuses the object the evaluator
+  builds from it, both spellings (a literal `__proto__:` and the own key
+  `JSON.parse` produces).
+  *Rendering.* A structured param gets a fenced JSON block below the params
+  table, keys sorted at every depth (ATX-10: the same registry renders the same
+  bytes) with the fence measured against backtick runs in the value, as `code()`
+  already did. It is below the table rather than in it because a fence cannot
+  live in a table cell. And `render` defends the document on its own: it reads
+  the registry with no spec parse, so no `AttestPlan` and no `validateStructure`
+  — `attest render` runs to completion on a registry `check` refuses. Leaning on
+  the diagnostic would have left the document defended by a command nobody is
+  obliged to run first.
+  *The writing side of the `__proto__` rule.* `splice.ts` turns a requirement
+  back into TypeScript source for `--apply`, and it is the only site that does.
+  Extending it to depth meant it would have emitted a `__proto__` key as a bare
+  property — text whose *evaluation* swaps a prototype rather than being the
+  value it was handed. Unreachable through any command (the schema rejects a
+  nested `__proto__` and `z.record` drops a top-level one), and refused anyway
+  with a new `UnwritableValue`, reported as `internal-error` by the merge with
+  its account of what it had already written intact. Quoting is not the repair —
+  a quoted `__proto__` swaps the prototype in a literal exactly as the bare form
+  does, and the bracketed form that would create an own property is a computed
+  key no static reader will read. The reader's guard is worth nothing if the
+  writer can produce the file it exists to refuse.
+  *Not breaking, with one edge worth naming.* No previously-green registry goes
+  red — a structured param was `registry-invalid` before, so nothing that
+  compiled and passed now fails — and an all-scalar registry renders
+  byte-identical, so a committed `render --check` stays green across the
+  upgrade. What did widen is the exported type in a **read** position:
+  `Requirement['params'][string]` is now the recursive JSON value. The const
+  generic is untouched, so `reqs['AUTH-3'].params.idleTimeoutMin` is still the
+  literal `30` and every anti-drift test keeps its narrow type. A consumer only
+  notices if they assign an *undeclared* key to the old scalar-or-list union
+  (`Type 'null' is not assignable`), or wrote their own handler over that type
+  and does `String(v)` in it — which is the `[object Object]` defect this entry
+  fixes in `render` and `splice`, seen from outside.
+  *This overturns a standing rejection, and not on its stated terms.* *Nested
+  objects in `params`* sat under **Considered and rejected** since `[0.4.2]`,
+  raised by `mine-capablanca`, and that entry is removed by this release. Its
+  argument was that a param has two properties a table lacks: rendered as a value
+  a human checks at a glance, and read by a scenario as the one place the value
+  lives. The first is answered rather than waived — `non-scalar-interpolation`
+  keeps a table out of the *sentence*, so what a reader takes in at a glance is
+  still glance-sized, and the table is rendered below it as a block. The second
+  is answered by the criterion that admitted arrays in the first place: a
+  `kind -> payload` table drifts *harder* than a flat list, so the reason arrays
+  were let in is the reason this shape should have been.
+  **The reopening condition it named was never met, and that is worth stating
+  plainly.** The entry said it reopens on "a report where the value is genuinely
+  promised — a table an adopter owes their users"; none has been seen. This
+  shipped on the strength of the argument alone. What changed is the recognition
+  that the schema was answering the wrong question: *params for promises, plain
+  constants for tuning* is the rule, and a type can only ever check shape, so it
+  refused a promised table while admitting a list of tuning knobs. Design §11
+  now carries that as a judgement rather than a type, which is the permanent half
+  — and it is weaker than what it replaces, because nothing enforces a judgement.
+  New requirements: `ATX-7` rewritten, `ATX-63` added.
+
+### Changed
+
+- **Rationale that only a comment held now has a design section, and the comment
+  cites it.** Measured over the diffs in three eras split at `[0.3.0]` and
+  `[0.5.0]`: comment blocks got better by every specificity signal — naming a
+  symbol 50 → 60%, a measured number 3 → 13%, a causal argument 26 → 54% — and
+  roughly doubled per line of code, while the share citing a `§` went 15 → 12 →
+  11% and the design document stopped growing (sixteen sections since `[0.3.0]`,
+  105 lines against `src/`'s 2,862). **The anchoring did not fall; it never
+  scaled**, and a `§` is the only part of a comment any gate reads.
+  Nineteen blocks written since `[0.5.0]` carried the cost — ten lines or more,
+  fully argued, unanchored — and they split three ways. *Six were properties a
+  rewrite would have to preserve*, and now sit in the document: a new **§9.1**
+  for the artifacts Attest writes, an extension to **§8** (`--apply` acts on this
+  run's verdict), and one to **§5.4** (the two readers of one plan must descend
+  the same way). *Four were history* — a quadratic backtrack, a 27–84x constant
+  factor, a 47 MiB peak, an indexing cost filed as invisible — and were
+  compressed to the invariant a maintainer would otherwise re-break; every
+  measurement in them was already under `[0.7.0]`, so this deleted duplicates
+  rather than moving anything. *Ten were correct as they stood and were left
+  alone*, which is the half worth naming: `§` is low because the design document
+  stalled, not because comments are too long, so a pass that shortened comments
+  and left it at one in nine would have moved the wrong quantity and called it
+  done. Net `src/`: 29 lines removed, all of them comments and no code touched,
+  which is also how the deletion was checked.
+  **One of the six corrected the document rather than extending it.** §8
+  summarised a merge as renaming a proposed spec "in place", which is true of its
+  location and not of its imports — the delta it reads its proposed params from
+  is what moves to `archive/`, so the sentence hid the one specifier the merge
+  has to repoint.
+  *What the measurement cost.* A first pass reported the `§` share as halving,
+  25 → 12%, an artefact of bucketing by `git blame` over the current tree: that
+  sees only surviving lines, and `§`-citing comments survive better, being tied
+  to sections that do not move, so the early era was measured on its most durable
+  residue. Re-measuring from the diffs before building is what caught it.
+  The routing test this produced is in `pre-commit-check` §6, and the obligation
+  a new diagnostic code owes the CLI reference is now in §2.
+
+## [0.7.0] - 2026-08-04
+
+### Added
+
+- **A universally quantified statement now has to say what it quantifies over,
+  and the answer is checked.** `tests/intent-rule-candidates.spec.ts` gains a
+  `QUANTIFIED` table beside `OBLIGATIONS`: every statement carrying an open
+  quantifier is hand-judged into one of three kinds, and a statement flagged with
+  no row fails. 23 of the 62 requirements are flagged today.
+  *The shape it exists for.* A universal quantifier in the statement, a finite
+  set of scenarios under it, and nothing holding the two together. It reads as
+  covered — the id has scenarios, `cover` is green, `check` is green — because
+  all three mechanisms this project sells operate *below* the quantifier:
+  coverage asks whether an id has a scenario, never-red asks whether that
+  scenario discriminated, drift asks whether it reads the params. None asks
+  whether the scenarios span what the sentence claims. It had already cost
+  something — `ATX-37` said "everything the CLI writes to a terminal" while
+  `render` built a document by concatenation that never went past the sanitiser,
+  which shipped as a fix earlier under this heading without the *shape* being
+  addressed.
+  **The classification is the part worth keeping, because it predicts which
+  statements carry the risk.** `values` — the quantifier ranges over inputs one
+  site processes, so growth cannot escape it, there being one site. `roster` — it
+  ranges over a set the code itself enumerates and the scenario iterates that
+  same set, so a new member is covered by construction. `sites` — it ranges over
+  places in the implementation, discharged by one hand-written scenario each, and
+  **this is the only kind that can silently stop being true**. Today 14, 2 and 8
+  across 24 rows — one more than the 23 flagged, for the reason two paragraphs
+  down.
+  `ATX-37` was a `sites` row and `render` was the new site, which is the whole
+  argument in one line. The `roster` shape is the one to reach for and the repo
+  had already found it once without naming it — `self/targets.spec.ts` says "a
+  target added without a scenario would otherwise be a target nothing checks".
+  **It found a live hole on its first run, on the requirement written to avoid
+  exactly this.** `ATX-62` names its surfaces rather than quantifying over them
+  ("both commands that execute the suite — `verify` and the archive gate"), and
+  its rationale explains that choice in these words. Of the three sites it names,
+  the archive gate path had **no scenario asserting the diagnosis is emitted** —
+  only one asserting it *stands down* for a file `added-id-unmerged` already
+  claimed, and one asserting the withdrawal it enables. Both negative.
+  *Measured by mutation, because the first statement of this was wrong and the
+  correction is the useful part.* Deleting the `specLoadFailedIssues` call
+  outright does **not** survive: it sits inside `notRunIssues`, which both
+  commands share, so the `verify` scenario kills it. The mutant that isolates the
+  gate is the one that matters — `evaluateGate` filtering the diagnosis out of
+  what it pushes, which is a gate that drops the finding on its own path while
+  `verify` keeps it. That is the *exact* historical shape `ATX-62` exists to
+  answer, its rationale naming "the rule holding on one path and not the other".
+  Against the old spec that mutant runs **green, 0 errors**; against the new one
+  it is red. `self/gate.spec.ts` gains the missing scenario, and the run is now
+  62 requirements / 160 scenarios.
+  *Two design decisions the table fails without.* **Rows are allowed for ids the
+  detector does not flag**, which is why `ATX-62` has one at all: naming the
+  surfaces is the *remedy*, and it takes the statement out of the flagged set, so
+  a table keyed strictly on the detector would drop the binding at the moment the
+  author did the right thing. **Every named scenario is asserted to exist** in
+  the specs, by name, for that id — without it the table is one more hand-written
+  list that goes on reading as covered after a rename, which is the failure mode
+  every other check in that file is written to avoid.
+  *And one deliberate gap, carried rather than hidden.* A site the statement
+  claims that nothing reaches is recorded as `null` and lands in the snapshot,
+  on the same footing as the compound rule's `missed` list. There is one:
+  `ATX-53`'s "some of several specs renamed, the rest not" — a state no fixture
+  can construct, because every change fixture carries a single spec.
+  The detector is the same kind of instrument as `compoundByKeyword` and has the
+  same limit, stated rather than tuned away: it catches the declared universal
+  and misses the article form ("A registry that cannot be read MUST …"), which is
+  a universal too. Two of the 23 rows are the idiom "at all" rather than a
+  quantifier, kept as rows because a regex tuned until it stops flagging is the
+  measurement bending to the corpus.
+  No behaviour change, no new `Issue` code, and no `ATX-n` — repo
+  self-discipline, for the reason at the top of that file: knowing which surface
+  a sentence names is prose judgement, the ground truth §0 refuses to compute for
+  someone else's requirements.
+
+- **The eight `sites` rows re-read against `src/`, which is what the table was
+  built to make possible.** The rows were hand-judged in one pass, and the value
+  of the whole table is concentrated in that kind — so the first use of it is a
+  strict read asking one question per row: *is this list of sites complete?* Five
+  claimed-but-unattested sites came back, one row was retired, and one was wrong
+  in the good direction.
+  **`ATX-15` was short by two.** "Every ordering Attest commits to disk" is wider
+  than the rendering: `red-record.ts` sorts ids and scenario names into
+  `first-run.json`, and `splice.ts` sorts ids and param keys into the registry
+  file `--apply` writes. Both are committed and neither is attested. The property
+  holds everywhere — every `.sort` in `src/` goes through `byCodeUnit` and no
+  `localeCompare` survives — which is precisely the `ATX-37` position: held at
+  every site, enumerated at none.
+  **`ATX-37` was short by three.** `formatStatus`, `formatCoverage` and
+  `formatArchiveVerdict` each interpolate a reqId, a change name or a path taken
+  from the project under test, and the statement says *everything* the CLI
+  writes. All three call `inline()` today; none is attested. That is the state
+  `render` was in on the day `ATX-58` had to be written.
+  **`ATX-58` was recorded as weaker than it is, and the correction is the useful
+  part.** It was filed as four field-sites carrying `ATX-37`'s growth risk.
+  `sanitised()` rebuilds a whole `Requirement` as one typed object literal, so a
+  fifth field on that type is a **compile error**, not a silent gap — the axis is
+  closed by the compiler rather than by anyone remembering. Five sites collapse
+  to two, and this is the strongest of the eight rather than a repeat of the
+  weakest.
+  **`ATX-53`'s open gap was retired by building it.** The recorded `null` was
+  "some of several specs renamed, the rest not", said to be unconstructible
+  because every change fixture carries one spec. Constructing it showed the state
+  does not exist: a renamed spec is no longer a *proposed* spec, so it leaves
+  `claimedSpecs` the moment it is done, and a partial rename re-runs as the state
+  already covered with a shorter list. Measured rather than argued — a two-spec
+  project with one merged by hand passes against a merge mutated to rename only
+  the first claimed spec. So the scenario was **not** kept: it discriminates
+  nothing, and design §11 is explicit that a scenario which cannot fail is worse
+  than the comment recording why. `self/merge.spec.ts` carries that comment, and
+  the two resumption scenarios now share one `spliceByHand` helper instead of two
+  copies of the same insertion literal.
+  `ATX-40`, `ATX-41` and `ATX-60` came back complete. `ATX-60` with a caveat
+  worth its line: every verdict in `src/` goes through `hasError` and the two
+  bare spellings left are not verdicts, so the sites are right — but "never by a
+  second spelling" is a claim about the whole of `src/` discharged by two
+  examples, and nothing sweeps for a fifth.
+  *What the read is actually saying, across five of the eight.* The recurring
+  answer is **a sweep or a type**. `ATX-58` shows what closed looks like: the
+  compiler refuses the new site. `ATX-34` and `ATX-57` show the other closed
+  shape: a scenario iterating the roster the code owns. `ATX-15`, `ATX-37` and
+  `ATX-60` want one and have neither, which is filed under
+  `Under consideration` rather than built here — a rule that fires on correct
+  usage is the shape this file has rejected before.
+  Bookkeeping only: no behaviour change, no new `Issue` code, and the snapshot
+  now carries five unattested sites where it carried one.
+
+- **A sketch in the design document is now bound to the file it says it is
+  from.** `tests/docs-consistency.spec.ts` takes every fenced `ts` block whose
+  first line names a `src/` path — the convention those documents already
+  follow — and asserts that every name the block puts at **module scope** still
+  exists at module scope in that file. Six blocks today, three per language. The
+  scan is over every hand-written page rather than the design document, through
+  the same enumeration the other checks use: a sketch is not something only one
+  file may hold, and a hardcoded list has already stopped covering a page here
+  once, on the day the CLI reference was split out of the README.
+  *Why this one, of the three candidates recorded with the entry.* Deleting the
+  sketches costs the design document the thing it is for; marking them
+  illustrative leaves an argument free to cite state that is gone. The symbol
+  check was the only candidate with a hit rate, and the hit rate is now measured
+  rather than estimated: replaying the pre-`a5899ac` document against today's
+  `src/runtime.ts` reproduces the original failure exactly — `currentReqId`,
+  named at module scope by the sketch and nowhere in the file. That replay is
+  what turned "would have caught it" into something checked.
+  **It found a third instance on its first run**, which is the fourth way this
+  file records an entry arriving. §5.4's `runner.ts` sketch declared
+  `const REQ_SUITE = /^\[(.+)\]$/` and read it with `task.name.match(...)`; the
+  regex moved to `core/req-suite.ts` and `runner.ts` has imported
+  `requirementIdOf` from it since. The sketch was not merely stale, it showed the
+  design document contradicting the module whose entire reason for existing is
+  that *"two spellings of one encoding are two encodings the moment either is
+  edited"* — a reader following §5.4 would have written the second spelling. Both
+  languages are corrected here.
+  *Three scoping decisions, each of which the check fails without.* **Module
+  scope, not every identifier the sketch names**: `runtime.ts` explains the
+  deleted `currentReqId` in two comments, so a substring scan over the source
+  text would have called the stale sketch fine — both sides are reduced to
+  declarations, imports and re-exports through the compiler API. **The `src/`
+  prefix, not file existence**: existence would make a typo'd path a silently
+  skipped block, the failure mode this file guards against everywhere else, so a
+  `src/` path that does not resolve fails instead and `requirements/auth.reqs.ts`
+  is left alone as what it is, a path in the reader's project. **Fenced blocks,
+  not prose**: prose may name a dead symbol legitimately, and §11 now does so on
+  purpose, as history.
+  **What it does not reach, because the honest count is one of two.** §11's
+  ESM-only bullet — the worse of the two instances, since it was an *argument*
+  resting on state that no longer existed — is prose, and stays outside. This
+  catches the sketch; the reader who comes to fix the sketch is what catches the
+  paragraph citing it. A sketch whose module scope survives while its body drifts
+  also passes, which is the same limit the byte-equality check already records
+  about the prose around a sample.
+  No behaviour change, no new `Issue` code, and no `ATX-n`: this is repo
+  self-discipline about this repository's own documentation, in the file that
+  already holds every other coupling cheap enough to assert.
+
+### Changed
+
+- **`parseSpecs` held every spec file in memory at once; it now holds 32.** The
+  read was `Promise.all(files.map(readFile))`, so every source in the project
+  was resolved before the first one was parsed. Each source is now parsed at the
+  point it arrives, through a fixed pool, which makes the peak a constant rather
+  than the size of the input — the merged plan is the only thing that still grows
+  with the tree, and it is the output.
+  *Measured, both before and after.* On a synthetic tree of 6000 spec files the
+  old shape held ~47 MiB of source at once at a realistic 8 KiB per file;
+  `tests/locate-fanout.spec.ts` counts in-flight reads through the filesystem and
+  measures 200 before the change and 32 after, on a 200-file input. That test
+  lives in its own file because it mocks a Node builtin, and it reads the
+  property at `fs` rather than through `parseSpecs`, which is the honest seam:
+  peak in-flight reads is a fact about how the function uses the filesystem.
+  *What is deliberately **not** changed, and why the two halves are not one
+  decision.* `findFiles` fans out over sibling directories with no limit either,
+  and it stays that way. The failure it invites is descriptor exhaustion, and no
+  measurement on either development platform could produce one — on Windows, Node
+  uses Win32 handles rather than POSIX descriptors, so the shell's `ulimit -n`
+  does not govern the process, and the one platform where it is plausible is the
+  one this measurement could not reach. That half stays under
+  `Under consideration` on this file's own standard: no report, and no
+  demonstrated failure anywhere. The memory needed no such evidence — it is
+  arithmetic, and it is portable.
+  No behaviour change and no `ATX-n`: the plan is byte-identical either way, and
+  there is no contract here a consumer could branch on. `check` being the command
+  this project tells people to run first on an untrusted fork MR is what makes it
+  worth doing anyway — the input size is not ours to assume.
+
+- **Every static command loaded the test runner it can never start.**
+  `pipeline.ts` imported `createLoader` from `loader.ts` and
+  `runAndCollect`/`BASE_EXCLUDE` from `runner.ts` at the top level, and
+  `cli/index.ts` imports `pipeline.ts` whole — so `vite`, `vitest/node` and
+  `vitest/config` were resolved and evaluated before `commander` had parsed an
+  argument. `check`, `cover`, `render`, `status` without `--eval`, and `init`
+  call none of them. The three are now reached through `await import()` at the
+  four `createLoader` sites and the two runner sites, all of which were already
+  in `async` functions.
+  *Measured on this repository, before and after, on one machine* — the earlier
+  figures recorded with this as a plan were taken in a different session and are
+  not comparable, which is the whole reason the baseline was re-taken here rather
+  than quoted. Importing `dist/core/pipeline.js`: **2133 ms → 1111 ms**.
+  `attest --version` end to end: 1700–2219 ms → 954–1220 ms. `attest check .`:
+  1991–2215 ms → 1300–1478 ms. Roughly a second, on every invocation of a
+  command that could not have used it.
+  **This is not the core/adapter package split, and does not substitute for
+  one.** `tests/import-boundary.spec.ts` states its own gap in its own words — it
+  gates **direct** imports, not reachability from the static commands, because
+  `pipeline.ts` holds both halves of the engine — and files the answer under the
+  split §11 defers as not earned by one package at this size. That deferral
+  stands and that gap is unchanged: what moved is *when* the cost is paid, not
+  which module holds what.
+  **The one property this could have silently dropped was the boundary itself**,
+  and it did not: that gate reads `import(...)` and `require(...)` from the AST
+  alongside static imports, and has since it was written, precisely so it could
+  not be defeated this way. Both specifiers stay relative, so `ALLOWED` is
+  untouched and the reachability walk still traverses them. The comment there
+  saying dynamic import was unused in `src/` is now false and has been corrected;
+  a gate whose commentary describes a codebase that no longer exists is the
+  defect this file's *"six places where the source states a guarantee it does not
+  provide"* entry is about.
+  *What this does not buy, stated so the next reader does not expect it.* The
+  larger single item is `typescript` at ~936 ms, and `check`, `cover` and
+  `render` genuinely read the AST, so it stays on their real path — visible in
+  `--version` still costing ~1 s. Only `init` and `--version`/`--help` pay it for
+  nothing, and separating those means splitting `pipeline.ts` rather than moving
+  an import. So this closes the avoidable half and leaves the unavoidable one
+  measured.
+  **No behaviour change and no new requirement.** No command's output, exit code
+  or JSON shape moves, and the property worth stating — *a static command must
+  not load the runner* — is deliberately **not** filed as an `ATX-n`: it is not
+  falsifiable from inside the engine today, for the same reason the import
+  boundary gate cannot assert reachability, and a requirement that cannot go red
+  is the defect `archive`'s never-red gate exists to catch. It stays repo
+  discipline, in the gate that already holds it.
+
+### Fixed
+
+- **The workflow `attest init` writes named the special case of a load failure
+  and not the general one.** `spec-load-failed` shipped in this cycle, after the
+  skill body was last edited, so its stage 2 table listed only
+  `added-id-unmerged` — which fires just when the change *also* adds an id the
+  registry lacks. An agent hitting a typo in a specifier therefore met an ERROR
+  absent from the table it was told to branch on, while the row that used to
+  appear, `declared-not-run`, had been withdrawn for exactly that file. The three
+  rows now say how they relate: the general case, the specific case that
+  supersedes it, and the withdrawal that keeps one file to one finding.
+  `ATX-57` could not have caught it. It holds one-directionally — every code the
+  workflow names must be emittable — which refuses a misspelling and is silent
+  about an omission, and that asymmetry is deliberate: the workflow has no
+  business naming every code. The other direction is not a rule anyone can write.
+
+- **`check --eval` started a Vite dev server per change, plus one for the
+  registry.** `unclaimedProposedSpecIssues` reads every change's delta in a loop,
+  and `readDelta` created and closed its own loader on each iteration — so the
+  cost was 1 + N servers for a command that needs one. Measured on a project
+  with six changes: **7 loaders → 1**, and the command went from ~3.3–3.6 s to
+  ~1.7–1.9 s. Both readers now borrow a loader when the caller holds one, and
+  `runCheck` owns exactly one for the whole command through a `withLoader`
+  helper. Ownership sits at the command because neither reader knows how many
+  times it is about to be called.
+  Static `check` is unaffected in the way that matters: with no `--eval` it
+  passes `undefined` down and starts nothing at all, which is the property that
+  command is documented on (design §5.1).
+
+- **`terminal.ts`'s `control` allocated three times the input to sanitise it.**
+  It spread the string into a per-code-point array, mapped, and rejoined, where
+  a character class lets the engine scan and — in the case every real registry
+  is — return the input untouched. Measured over 120,000 characters: **27×**
+  faster on plain ASCII, **54×** with newlines, **84×** on CJK. A payload that
+  is *entirely* control bytes is a wash at 0.9×, since then there is nothing to
+  fast-path and both spellings build a new string; both are linear either way,
+  so this is a constant factor rather than a second `ATX-59`.
+  Worth changing because the call count scales with the registry while the
+  length scales with whatever the registry chose: `render`'s `sanitised` calls
+  it once per statement, rationale, param key, param value and out-of-scope
+  entry, on the same reachable `render --check` path `ATX-59` came off.
+  **Byte-identical to the spelling it replaces**, which is the only thing that
+  mattered here: verified exhaustively over every code unit in the BMP, and over
+  200,000 randomised strings mixing control bytes, CJK, astral characters and
+  lone surrogates — surrogates being the case the spread existed to get right.
+  Newlines survive as they always did, by not being in the class.
+
+- **Four comments describing a property the code beside them did not have.**
+  This repository keeps its decision record in prose, so a comment claiming
+  something the code does not do is the same class of defect as a diagnostic
+  pointing at the wrong line: it is what the next reader believes *instead of*
+  reading. None of these produced a wrong answer today, and each is now true.
+  - `merge.ts`'s `archivePath` is documented as "one function because two places
+    ask … a date computed twice could straddle midnight and disagree with
+    itself", and called `new Date()` on **every** invocation — four times per
+    merge. A merge crossing midnight would have refused against one directory
+    and written to another. The stamp is now read once in `applyMerge` and
+    passed down, which makes `archivePath` a pure function of its arguments —
+    the property that turns "the two cannot disagree" into something the code
+    holds rather than something the clock does.
+  - `pipeline.ts`'s `claimedSpecsOf` is documented as "built from the plan
+    rather than by re-parsing, so the files `--apply` touches are exactly the
+    files the gate ran", and its caller handed it a fresh `parseSpecs` over
+    every proposed spec — the second such parse in that function, with
+    `changeMergedPlan` having done the first. The two agreed because the same
+    two functions ran twice, which is agreement by transcription: the thing this
+    codebase extracts `declaredNotRunIssues` and `uncoveredIssues` to stop
+    relying on. `changeMergedPlan` now hands back the claimed half it already
+    built, so there is one parse, one split and one answer — and the archive
+    path does one less full parse of every proposed spec.
+  - `pipeline.ts`'s `runCover` ordered ids with a bare `.sort()` where the rest
+    of the engine goes through `byCodeUnit`. The result is identical on ids that
+    match the grammar, which is exactly why it was worth changing: `order.ts`
+    exists so ordering has one spelling, and that is a property which survives an
+    edit where an identical result does not.
+  - `status.ts`'s `statusRows` filtered the whole plan once per added id, the
+    pattern `validator.ts`'s `detectPotentialDrift` carries a comment about
+    having removed — O(requirements × scenarios), and the plan here is the
+    *merged* one, so the inner term is the whole repository's scenario count.
+    Indexed once now. The cost was genuinely invisible (20 ids against 2000
+    scenarios is 40k comparisons, well under a millisecond), so this lands as
+    the inconsistency it was rather than as a slow path; scenario order within a
+    row is unchanged, still file then line.
+
+- **`orphan-test`'s fix hint was wrong for the case that produces the most of
+  them.** "Add it to the registry, or fix the id" is right for an id that is
+  genuinely absent and **wrong** for one already sitting in a registry file that
+  failed to load: the id is there, the fix is the load error, and following the
+  advice adds a duplicate. One unreadable `*.reqs.ts` orphans every scenario of
+  every requirement it declared, so the wrong advice was also the loudest thing
+  in the report, with `registry-invalid` — the one true finding — pushed to the
+  top and out of view.
+  **The finding stays; only the advice changes**, and that is the whole of the
+  decision. Suppressing `orphan-test` needs a prefix→file mapping for a file
+  that never parsed, which is exactly the file no ids are available from; the
+  weaker signal (some registry file failed to load, so suppress all of them) is
+  a strictly worse `check` on a multi-file registry where the other files are
+  fine and their orphans are real. Both remain open under *Under consideration*.
+  What is shippable today is that a command which cannot tell the two cases
+  apart should say so rather than guess — so when any registry file fails to
+  load, the hint names the uncertainty and the order to work in. `Issue.message`
+  is prose and never API, so this costs no consumer anything.
+  *"A registry file failed to load" is not "loading produced an ERROR", and the
+  first draft of this had it wrong.* `duplicate-prefix` and
+  `duplicate-requirement` are ERRORs raised **after** a successful read, and the
+  ids they are about are present — so keying the new wording on `hasError` told
+  a project with a prefix collision that a file had failed to load, which is
+  false, about a report where the original advice was correct. `loadRegistry`
+  now answers the question it is the only thing in a position to answer: which
+  files contributed no ids, taken from the outcome it already branches on rather
+  than re-derived from a list of codes a caller would have to keep in step.
+
+- **The Vite logger wrapper reported that it had never warned, however much it
+  had.** `sanitisedLogger` builds its wrapper by spreading the base logger, and
+  `hasWarned` is the one member of Vite's `Logger` that is state rather than
+  behaviour — so the spread copied it **by value** at construction. Measured:
+  after one `warn` through the wrapper, the base reads `true` and the wrapper
+  still reads `false`. An accessor pair makes the wrapper a view of the base
+  rather than a snapshot of it, which is what every other member already was.
+
+- **`render`'s id comparator was non-transitive on an id it could not take
+  apart.** `compareIds` split on `lastIndexOf('-')` with no guard, so an id with
+  no dash silently lost its last character (`AUTH` → prefix `AUT`) and produced
+  `NaN` for its number. The consequence is worse than a wrong tie: measured on
+  `['AUTH-3','AUTH-abc','AUTH-2']` the sort returned `AUTH-3, AUTH-abc, AUTH-2`,
+  which is not a sorted permutation of anything. The comparator is now total by
+  construction, and falls back to the whole id rather than to the engine's sort
+  stability — `renderMarkdown` feeds `--check`, so an order that depends on
+  anything but the ids is a freshness gate that can disagree with the run that
+  wrote the file.
+  **Robustness, not a live defect, and the distinction is worth keeping.** A
+  malformed id cannot reach here through any command: `RequirementIdSchema`
+  rejects it and `render` returns early on a registry that failed to load —
+  confirmed by trying it. What was actually wrong is that two functions held two
+  beliefs about one input space: `locate.ts`'s `idPrefix` handles a dashless id
+  and records why ("this also runs over ids a delta proposed"), and this one
+  did not. They agree now.
+
+- **A spec file that failed to load was reported as a file full of skipped
+  scenarios, and the file itself was named nowhere.** `verify` on a two-file
+  project with one bad import produced three ERRORs: `tests-red`, and one
+  `declared-not-run` per scenario in the broken file, each saying *"skipped, or
+  excluded by an `.only`?"*. That is a guess at a cause and the wrong one — it
+  sends the reader to audit a correct file for a `skip` that is not there, while
+  the import error explaining everything is named in no finding at all. The gate
+  had a diagnosis for one shape of this (`added-id-unmerged`, when the change
+  also adds an unmerged id); every other way a file fails to import had none, on
+  either command.
+  **The obvious repair was the wrong one, and `gate.ts` had already written down
+  why** — three lines from where it would have gone. Suppressing
+  `declared-not-run` for unloaded files produces a red report with nothing
+  pointing at the file: silence in place of a wrong message, and worse than what
+  it replaces. So the replacement comes first. `spec-load-failed` (`ATX-62`)
+  names the file on both commands that run a suite, and stands down where a more
+  specific diagnosis already named it — one file, one finding, and the one
+  carrying a fix wins. It deliberately does **not** restate the import error:
+  the run output above the report already has it, and a copy is a second place
+  for it to be wrong. No `reqId`, because a file that never loaded has no
+  established relation to any requirement.
+  **Both commands now ask one function**, `notRunIssues`, rather than each
+  spelling out the order themselves — the cause before the absences it caused,
+  and never the absences alone. That is how the two came to differ at all: the
+  gate learned to withdraw a misleading line and `verify` did not, so one run
+  produced a different diagnosis depending on which command asked. It is the
+  same argument that extracted `declaredNotRunIssues` from those two commands,
+  arriving one level up, and it is what stops this particular divergence from
+  being re-openable by an edit to either caller.
+  **`ATX-50` reaches `verify` now, and its line did not move.** That requirement
+  withdraws the absences a load-failure diagnosis replaces, and its recorded
+  condition was always *"a correct diagnosis exists for this file"* rather than
+  *"the file failed to load"* — it was scoped to the gate because the gate was
+  the only place that condition could hold. It now holds on both. The "and no
+  further" half is what an over-broad fix would have cost, and is separately
+  attested: a scenario that really was skipped, in a file that loaded, is still
+  reported.
+  **Behaviour change, for a project that has a spec file failing to load.**
+  `verify` and `archive` report one `spec-load-failed` per unloaded file instead
+  of a `declared-not-run` per scenario in it. Both are ERRORs and both runs were
+  already red, so no green becomes red and no red becomes green; what changes is
+  which finding is in the report and what it says. Anything branching on
+  `declared-not-run` for such a file — no consumer is known to — sees the new
+  code instead. Additive to the JSON surface (a new `code` value), so
+  `SCHEMA_VERSION` is unchanged.
+
+- **`attest render` let the registry it was reading write to the terminal
+  reading it.** ATX-37 put every byte the CLI prints through a sanitiser, and
+  the scope line of that requirement says "everything the CLI writes to a
+  terminal" — but `render` builds a *document* by string concatenation that
+  never went past it. The static reader hands back the **cooked** string, so an
+  escape written as an escape in a `*.reqs.ts` is a real control byte by the
+  time it is concatenated. *Measured on the built CLI*, with no `--eval` and no
+  flag at all: a statement carrying `ESC [2K CR` erases the reviewer's line and
+  repaints a verdict, and `ESC ]0;` retitles their window. On a fork merge
+  request the author is not the reviewer, and a registry — not a test, not a
+  script — is the whole payload.
+  **The obvious fix was the wrong one, and the loop said so before it was
+  written.** Sanitising the terminal write would have left `--out` putting the
+  same bytes in a file that is committed, served, and read again later by `cat`,
+  by `less -R`, or by a static site generator. The artifact outlives the run, so
+  the run is the wrong place to defend: the obligation is now over the document
+  (`ATX-58`), which is also what keeps `--check` honest, since both sides of
+  that comparison are built from one function. Newlines survive, because a
+  rendered rationale is Markdown prose that may legitimately span lines — and
+  they are *not* indented the way ATX-37 indents them, because four spaces in
+  Markdown is a code block.
+  **Behaviour change, for one shape of project.** A registry that actually
+  contains a control character renders to different bytes than before, so a
+  committed rendering goes `stale-spec-doc` once and is fixed by regenerating.
+  A registry without one is byte-identical: this repo's own `SPEC.md` changed by
+  insertion only.
+
+- **A statement padded with whitespace cost `render` quadratic time, and
+  `render --check` is the gate people put in CI.** The table cell collapsed a
+  multi-line statement with a pattern whose leading quantifier is followed by a
+  required character, so a whitespace run containing no newline was consumed,
+  failed, and re-tried one character shorter from every position in it.
+  *Measured through the CLI*: 120,000 spaces in one statement cost 8.6 seconds
+  of pure CPU, 320,000 cost 58 — under the **static** reader, so a fork merge
+  request can burn a runner without executing a line of anything.
+  **The first repair measured slower than the defect**, which is the part worth
+  keeping: `[^\S\n]*\n[^\S\n]*`, which stops the class matching the newline,
+  is just as quadratic, because the backtracking was never about which
+  characters the class held — it was about the quantifier having something after
+  it. Matching each maximal whitespace run once and deciding in a callback has
+  nothing after the quantifier to fail into. Byte-identical to the old pattern,
+  asserted over 200,000 randomised inputs and confirmed on the real corpus, and
+  now bounded by `ATX-59` at a budget three orders of magnitude looser than a
+  linear implementation needs — a defect detector, not a machine-speed detector.
+
+- **Grouping scenarios under a `describe` took the whole spec file down, and
+  the static half called that file fully covered.** Vitest defers a nested
+  collector until after the parent's callback returns — measured: at the end of
+  the outer callback the inner one has not run — so the module-level
+  `currentReqId` that `requirement()` set and restored around its body was
+  already back to `null` when a grouped `scenario()` ran. It threw, and a throw
+  during collection is a *file* error: nothing in that file was collected.
+  **The blast radius is the file, not the group.** A correct, ungrouped scenario
+  belonging to a *different* requirement in the same file came back
+  `declared-not-run` too, blamed on "skipped, or excluded by an `.only`?" —
+  sending the reader to audit their spec for something that is not there.
+  **And the static commands were not merely misdirected, they were wrong.**
+  `check` answered `✓ No issues` and `cover` answered `0 uncovered` for a file
+  that could not execute a single line. Those are the two commands documented as
+  the fast pre-check that is safe to run first on an untrusted fork, so a
+  pipeline running only `check` — a use this reference recommends — would pass a
+  change whose specs never run. That is a false green, which is the one failure
+  class this tool exists to prevent.
+  **Fixed at both ends, because it was one seam disagreeing with itself.**
+  `parser.ts` has always recursed to any depth while the task-tree walk counted
+  only *direct* `test` children of a `[reqId]` suite, so even a runtime that
+  stopped throwing would have reported a grouped scenario that ran and passed as
+  never run. The module-level variable is **deleted** rather than repaired — it
+  was a second answer to a question the suite name already answers — and both
+  sides now go through one `req-suite.ts` that owns the `[id]` encoding.
+  **The narrower fix was measured and rejected.** Having the parser refuse a
+  `scenario()` that is not a direct child looked smaller and would have closed
+  the false green too, but a *synchronous* wrapper — `forEach`, or a local
+  helper — works correctly today at both ends, and no static rule separates one
+  from a deferred callback. It would have rejected working code to describe a
+  runtime property.
+  *Behaviour change, two of them.* The nesting contract is now enforced when a
+  scenario **runs** rather than when it is collected, so a scenario genuinely
+  outside any `requirement()` fails as one test instead of taking its file down.
+  Nothing that passed before fails now.
+  The second is smaller and out of contract, and is stated because it is silent:
+  `scenario` used to hand its function to `it` directly, so Vitest called it with
+  the test context, and it is now invoked with no arguments. The declared type
+  has always been `() => void | Promise<void>` and the design document has always
+  shown it that way, so TypeScript rejected any use of that argument; a
+  JavaScript consumer who reached for `ctx.skip()` inside a scenario would find
+  it gone. Preserved deliberately as-declared rather than threaded through: the
+  contract is the zero-argument one, and adding a parameter to keep an
+  undeclared behaviour alive is a hook for a need no requirement has. `docs/*/attest-design.md` §3's runtime sample is
+  updated, as is the ESM-only note in §11, whose stated hazard was the very
+  module-level state this removes.
+
+- **Four verdict predicates that were not `hasError`, one of which would have
+  reported a failed gate after the merge had already written the files.**
+  `types.ts` states the invariant in as many words — `hasError` is "the single
+  predicate the pipeline verdict, the JSON `ok`, and the CLI exit code all read
+  from, so those three can never disagree" — and four sites spelled it by hand:
+  `archive`'s report and its human rendering both asked `blocking.length === 0`,
+  and the merge path asked `issues.some(i => i.level === 'ERROR')` twice.
+  **The `archive` one had a consequence its own neighbour predicts.**
+  `runArchiveApply` deliberately keeps the gate's non-blocking output, with the
+  comment that dropping a WARNING "would make `--apply` quieter than the same
+  command without it" — so a WARNING reaching `blocking` is not hypothetical, it
+  is planned for. The first one to arrive made the report answer `ok: false`, the
+  process exit 1, and the terminal print `✗ Gate failed` **after `--apply` had
+  written the registry, renamed the specs and moved the change folder**.
+  Reporting failure after a destructive step succeeded is the worst shape a
+  verdict can take, and the only thing preventing it was that every issue those
+  paths construct happens to carry a literal `ERROR`.
+  Now `ATX-60`, stated over the predicate rather than over `archive`, because the
+  defect is that the question had more than one spelling and any command could
+  grow a fifth — and stated to cover the human verdict as well as the machine
+  one, since both were wrong here independently and fixing either alone leaves a
+  command whose two surfaces disagree about whether it failed. Distinct from
+  `ATX-5`, which promises the implication one way only: `ok` false whenever there
+  is an ERROR says nothing about `ok` false when there is not, which is the half
+  that broke. No behaviour change today, which is the argument for doing it
+  before something has been reported wrong rather than after. **No
+  `schemaVersion` bump**: the envelope keeps every field it had and the `Issue`
+  interface is untouched — what changed is the value `ok` takes in a case
+  nothing can currently produce, and a consumer branching on `ok` and
+  `issues[].code` as documented reads the same report it always did.
+  *Found by reading, and the count was wrong when it was filed:* the note that
+  queued this named three sites; the rendering in `cli/index.ts` was the fourth,
+  and it is the one a human would actually have seen.
+
+- **Sweeping for a second backtracking site found something that is not
+  backtracking.** Every regex `src/` executes was measured against 21
+  adversarial input shapes at doubling sizes, with the old table-cell pattern
+  left in as a positive control — it was the only superlinear hit, which is what
+  makes the other eighteen being linear evidence rather than silence. The
+  structural reason is worth keeping: that pattern began with a quantifier that
+  can match nothing, so **every index** was a valid start; every other regex here
+  begins with a literal or a required class, which caps the starts at how often
+  that character occurs.
+  What the sweep turned up instead was the code-span fence, which measured the
+  longest run of backticks with `Math.max(0, ...runs)` — one stack argument per
+  run, so a param holding a few hundred thousand of them exhausted it. Same
+  reachable path as the quadratic one (`attest render` and `render --check`,
+  static reader, no `--eval`), same shape of defect — a registry choosing what
+  rendering costs the person reading it — and a different mechanism entirely.
+  `ATX-59` now states both and is counted as two obligations, because a
+  quadratic pattern and an unbounded spread regress independently.
+  A third candidate was measured and **rejected**: a deeply nested literal does
+  overflow the stack, but TypeScript's own parser gives out around depth 1,000
+  and this project's AST walk not until 2,000, so the limit belongs to the
+  compiler Attest is built on. It also lands where the contract already puts it —
+  a well-formed `internal-error` envelope under `--json`, and a sanitised stack
+  on the side people read.
+
 ## [0.6.0] - 2026-08-03
 
 ### Added
@@ -2436,57 +3157,137 @@ feedback reports are triaged into issues or `Unreleased` and deliberately not
 kept in this tree; that rule stands, and holds for anything with a reporter, a
 repro, or a state to track. What is kept here is the narrower thing this file
 already keeps one section of: a **decision with an argument attached**, where
-losing the argument would cost more than losing the task. The one below came out
-of reading another repository against this one — `msw`.
-
-Five entries have left by being built, and the last three left together in
-`[0.6.0]`. `compiler-unsupported` came from building something queued here,
-which is one way an entry arrives: a gate that finds a defect on its first run
-files the defect, and the `typescript` matrix `[0.4.2]` added is what found this
-one.
-`--apply` came from an adoption report (`mine-capablanca`, 0.4.2, 34 requirements
-/ 56 scenarios / greenfield) — a third way an entry arrives: not a defect, but a
-shape the tool made an adopter work around eight times without ever erroring. It
-took `spec-in-change-dir` out with it, by a fourth way worth naming: designing one
-of `--apply`'s checks surfaced a different one, against a migration this file had
-itself shipped. **What a release costs its adopters is not fully known on the day
-it is cut** — and building the entry is what finds out, which is also how
-`--apply` discovered that one clause of its own argument here was wrong. Both are
-recorded under `[0.6.0]`, and two earlier entries from the same report left
-by shipping in `[0.5.0]` — a change's specs moving to their merged location, and
-the delta reading as the registry of what it adds — their arguments recorded
-there, including the part of the first one that turned out to be wrong.
-
-- **Region-marked samples, so a partial quote can be bound too.** The whole-file
-  half of this shipped in `[0.4.3]`: the README's two getting-started blocks
-  are now byte-equal to `fixtures/consumer/`. That buys 2 of the 23 fenced `ts`
-  blocks in the README and `docs/en/**`, and the ceiling is structural rather
-  than lazy — the other 21 are elided (`{ /* … */ }`), annotated (`// ✓ the single
-  source`, `// ✗ a literal that can drift`), or deliberately rejected by the engine
-  (`params: { maxMb: MAX_MB }`), and none of those can equal a runnable file.
-  **What raises it is marking spans, not a second mechanism.** A
-  `// #region readme:registry` and its close inside the fixture, with the
-  assertion running block against dedented span, lets one file feed several
-  passages and makes a partial quote bindable by construction. Where that
-  actually reaches, counted rather than hoped: `troubleshooting.md`'s
-  single-source pair is two verbatim lines of `fixtures/consumer/session.spec.ts`
-  and its `AUTH-3` block is the registry entry at a different indent — so a
-  handful more, not the remainder. Anything carrying a `✓`/`✗` is authored
-  commentary and stays a fragment; that is what it is for.
-  *The ✗ blocks are a separate question, and worth not conflating.* A sample
-  showing input the engine must reject could be bound to a fixture whose
-  *rejection* is asserted — which is what `fixtures/eval-invalid-registry`
-  already is. Binding those is the more valuable half, because a counterexample
-  that stopped being a counterexample is the one kind of stale sample that
-  actively teaches the wrong thing. It is also the one that needs a fixture per
-  diagnostic, so it is not free the way the regions are.
-  *The mirror rule still caps what can be claimed on the Chinese side.*
-  `docs/zh/**` matches `docs/en/**` down to the comments inside its code samples,
-  so byte-equality holds on one side only and the zh blocks stay translated prose
-  around the same code — the parity gate in `[0.4.3]` is what covers them now,
-  and it covers structure, not meaning. Unchanged from the whole-file half: the residual
-  risk recorded with it in `[0.4.3]` — that the gate and the run proving the
-  fixture still works live in different suites — applies here identically.
+losing the argument would cost more than losing the task.
+
+**Where an entry went is recorded under the version that shipped it.** This
+section keeps no ledger of its own departures — one was maintained here by hand
+for several releases, and a count kept in prose with nothing to check it is a
+claim that goes wrong quietly. What is worth keeping is what the section learned
+about itself, which is three things.
+
+**An entry can sit here for releases on the strength of a figure nobody has
+checked.** The discipline aims at keeping the *argument*, not at re-testing the
+evidence under it, so the first act of building one is re-measuring what it
+claims rather than implementing what it proposes. That has paid twice: once
+killing an entry outright, when the spans it rested on turned out not to be
+spans; once correcting an entry's headline number before a line of it was
+written. **What a release costs its adopters is not known on the day it is cut**
+— several entries arrived from one adoption report, about shapes the tool made
+someone work around without ever erroring. And **the fixes with no observable
+symptom are worth batching**: individually none justifies a commit, together they
+cost about an hour, and they are the group no gate could have found, since having
+no symptom is the definition of what a gate cannot see.
+
+- **Binding the `✗` samples to fixtures whose rejection is asserted.** A sample
+  showing input the engine must *reject* can be bound the way a runnable one is,
+  to a fixture whose rejection is the thing under test — which is what
+  `fixtures/eval-invalid-registry` already is. This is the more valuable half of
+  what was once one entry with the region-marking below, because a counterexample
+  that quietly stopped being a counterexample is the one kind of stale sample
+  that actively teaches the wrong thing: a reader shown "this fails" about input
+  the engine now accepts is worse off than one shown nothing. It is also the
+  expensive half, needing a fixture per diagnostic, which is why it was never the
+  free part of that entry and is now the only part left in it.
+  *The mirror rule caps what can be claimed on the Chinese side.* `docs/zh/**`
+  matches `docs/en/**` down to the comments inside its code samples, so
+  byte-equality holds on one side only and the zh blocks stay translated prose
+  around the same code — the parity gate in `[0.4.3]` covers them, and it covers
+  structure, not meaning. The residual risk recorded with the whole-file half in
+  `[0.4.3]` — that the gate and the run proving the fixture still works live in
+  different suites — applies here identically.
+
+- **The child run's stdout is not Attest's, and `--json` promises it is.**
+  `runAndCollect` starts Vitest with the parent's fd 1 inherited, so a spec file
+  in the project under test writes straight to the same stream the report goes
+  to. `quiet: true` does not close it: `silent: true` suppresses Vitest's
+  *console interception*, and a bare `process.stdout.write` in a spec — at
+  collection time or inside a scenario body, both measured — goes past it
+  untouched. Neither `core/terminal.ts` nor `sanitisedLogger` is on that path at
+  all, because no Attest code is.
+  *The machine surface is the half that is actually new.* `cli/index.ts` opens
+  by stating that under `--json` "the only thing written to stdout is one
+  machine-readable report", and §9.1 records that this path "was never exposed —
+  `JSON.stringify` escapes every C0 character". Both hold for `check`, `cover`,
+  `render` and `status`, and neither holds for `verify` or `archive`: measured,
+  a spec writing `{"ok":true,"POLLUTION":"…"}` puts that document **first** on
+  stdout, ahead of the real report, so `JSON.parse` of the whole stream fails
+  (position 46) while anything reading line-wise or taking the first object
+  reads the attacker's verdict. The terminal half is the same hole and the
+  smaller finding — `ESC[2K CR` plus a forged `ERROR` header at column 0 and an
+  `OSC 0` window retitle all arrive intact — but `verify` executes project code
+  by design, so repainting a terminal is not a capability that path lacked.
+  *The fix belongs to `runAction`, not to `runner.ts`.* That function is already
+  the single convergence point for "one output, one exit code", which is the
+  same argument that put `formatCrash` in `cli/report.ts` rather than leaving a
+  copy in each `catch`: `runner.ts` would be made to hold a contract it does not
+  own, while `runAction` is the only place the promise is made.
+
+- **`render`'s document can carry raw HTML and a forged requirement section.**
+  `sanitised` is the entry §9.1 names and it strips control characters and
+  nothing else, so `statement` and `rationale` reach the Markdown by
+  concatenation exactly as written. Measured: a `rationale` containing newlines
+  and `## ATX-999` renders a whole section — heading, statement, `**Why:**` —
+  for a requirement no registry holds, sitting between two real ones and worded
+  identically; `<script>` and `<img onerror>` survive the same way. `check` and
+  `cover` see only the real id, and `render --check` cannot object, because that
+  *is* what the registry renders to now.
+  *Not an accepted risk, which is the part worth pinning.* §9.1 and the
+  reference both scope their guarantee to control characters, and the
+  reference's heading over that paragraph is "Safe to read, and safe to keep",
+  with "a site generator" named in the threat it describes. What *is* a decision
+  is that prose may be marked up — `plain()` escapes a param value precisely
+  because it is data while the statement around it is not — and that decision
+  has never been separated from allowing raw HTML or a heading. So the entry is
+  as much about stating which of the three is intended as about the escaping,
+  and if the answer is that Markdown stays and HTML and headings go, that is a
+  fourth obligation in §9.1 rather than a patch at an emitter.
+
+- **`attest init` follows a symlink out of the project root.** `runInit` does
+  `mkdir(dirname(dest), { recursive: true })` and then `writeAtomic`, and
+  neither asks whether `dest` is still under `root`. A `.claude/skills/attest`
+  planted in the repository as a link to anywhere the user can write is followed
+  by both: measured on Windows with a junction, a file at the target holding
+  `USER OWNED FILE - DO NOT OVERWRITE` came back holding the skill. The report
+  prints the relative path, so nothing on screen says where it went.
+  *`write.ts` is not the gap and neither is `targets.ts`'s content.* The `wx`
+  flag defends the *temporary* path against a planted link and does exactly
+  that; the destination's directory was never in its scope. And `workflowBody()`
+  is a pure function of nothing, so no byte of the checked project reaches the
+  file — the exposure is the path, not the content, which is `targets.ts`'s
+  first rule ("Attest owns the path") being an assumption rather than a check.
+  The check belongs beside `resolveTargets`, which is already all-or-nothing for
+  the same reason: a name known to be unwritable must not leave half a set
+  behind.
+
+- **A deeply nested literal takes `check` down before either reader sees it.**
+  40 KB of `[[[…]]]` in a `params` value exhausts the stack inside
+  `ts.createSourceFile` — TypeScript's own recursive-descent parser, so
+  `literalValue`'s recursion is never reached and hardening it would change
+  nothing. `parser.ts` opens with the same call, so `verify` takes it too, and
+  `loadRegistry` reads with `Promise.all`, so one file ends the whole command.
+  *It fails closed, which is why this is a repair and not an emergency.*
+  Measured: `internal-error`, `ok: false`, exit 1, and a well-formed `--json`
+  envelope. What it costs is that the command this project tells people to run
+  first on an untrusted fork MR can be made to say nothing but that, forever.
+  The shape of the fix is already in `locate.ts`: `unreadableFiles` exists to
+  say "this file could not be read" without ending the run, and a `RangeError`
+  out of a single `read` or `parseSpecFile` is that, so a hostile file scraps
+  only itself and `check`'s breadth contract survives it.
+
+- **`status` prints one line the sanitiser never sees.** `cli/index.ts` writes
+  `Change: ${result.change}` bare, while `formatStatus` puts the same value
+  through `inline` twice, three lines apart in the same output. Measured with a
+  directory named with U+009B — the C1 CSI the class in `control` exists for,
+  and one NTFS permits — the header carried `c2 9b` raw while the closing
+  `Not a verdict:` line carried a space. A change name is a directory name in
+  the repository under test, and the workflow `init` writes tells an agent to
+  run `attest status <name>`, so the value is the project's to choose.
+  *One `inline()` call, and the entry is here for the reason rather than the
+  fix.* §9.1 says a stream has no entry, only writes, so the obligation sits on
+  every write or not at all — and this is the second time a single missed write
+  has been the whole defect, after the two `catch` blocks that printed a raw
+  stack beside sanitised diagnostics. The sweep filed above under `ATX-37` is
+  what would have found it; this is one more measurement in favour of it.
 
 ## Under consideration
 
@@ -2500,6 +3301,41 @@ deletion. What each entry has to carry is the evidence currently blocking the
 decision, because that is what a re-proposal a year from now would otherwise
 have to gather again.
 
+- **A static sweep for the two properties claimed over the whole of `src/`.**
+  The quantifier table's first strict read left three rows wanting the same
+  thing, and the repo already owns the idiom: `tests/import-boundary.spec.ts` is
+  a sweep over the import graph asserting a cross-cutting property no runtime
+  test can see, written for the same reason — "only the graph shows it".
+  *The two candidates, and they are not equally shippable.* `ATX-15` is the easy
+  one: **no `.sort` outside `byCodeUnit`, and no `localeCompare`.** Measured over
+  `src/` today — 21 `.sort` call sites, every one reaching `byCodeUnit`, but only
+  19 naming it on the call line: `render.ts` goes through its own `compareIds`,
+  and `merge.ts` through a comparator that spans two lines. The only four
+  occurrences of `localeCompare` are comments explaining why it is not used. A sweep would have **zero false positives on the current corpus**,
+  which is the bar `divergent-param` failed and `compound-requirement` cleared —
+  and those two exceptions are already the warning that this needs the AST rather
+  than a line-wise regex, plus a rule for a comparator that delegates. `ATX-37` is the hard one: what it needs is "every project-derived
+  string interpolated into a terminal line goes through `inline`", and that is
+  not a token scan. The shape that would work is a scenario driving every
+  exported `format*` in `src/cli/report.ts` with hostile input — a real roster,
+  since the module's exports are what a new formatter joins — but each takes a
+  different argument type, so it needs a hostile fixture per signature rather
+  than one loop.
+  *What blocks the decision.* Two things, one per candidate. The `ATX-15` sweep
+  is cheap and precise and would be **the first rule in this repository that
+  polices how `src/` is written rather than what it does** — a lint rule wearing
+  a scenario's clothes, and the question is whether that belongs in `self/` (as
+  an obligation `ATX-15` already carries) or in `tests/` beside the import
+  boundary. Filing it under `ATX-15` makes it a permanent obligation with a
+  scenario; filing it in `tests/` makes it deletable in a green diff, which
+  `ATX-57`'s rationale argues against in as many words. The `ATX-37` roster is
+  blocked on cost rather than principle: eight formatters, eight fixtures, and
+  the honest count of what it buys is three currently-correct sites.
+  *Why neither is urgent.* Both properties hold everywhere today, verified by
+  reading. What is missing is not correctness but the thing that keeps it — and
+  the measurement above is what a re-proposal would otherwise have to gather
+  again.
+
 - **Bounding the fan-out in `findFiles` and `parseSpecs`.** Both walk the
   project with no concurrency limit: `findFiles` recurses through
   `Promise.all(subdirs.map(walk))`, so every directory in the tree is opened at
@@ -2604,6 +3440,161 @@ have to gather again.
   here rather than moving to `Considered and rejected`: documenting a trap is
   not the same as deciding not to detect it.
 
+- **Whether `check` and `verify` should refuse a half-loaded registry the way
+  `cover` and `render` do.** Those two return early on `hasError(loadIssues)`,
+  and the argument is recorded at both call sites: a report computed from a
+  half-loaded registry is a lie, and a lie that reads as a pass is the worst
+  shape it can take — `cover` in particular used to answer `ok: true` on a repo
+  whose intent layer had stopped being readable, because an empty registry is
+  fully covered. `check` and `verify` carry on regardless.
+  *What that produces, measured* on a project with one unreadable `*.reqs.ts`:
+  a `registry-invalid`, then an `orphan-test` for **every** scenario belonging to
+  that file's requirements, plus `empty-spec`, `tests-red` and a
+  `declared-not-run` per scenario — six derived findings from one cause. Worse,
+  `orphan-test`'s fix hint ("Add it to the registry, or fix the id") is *wrong*
+  for an id already sitting in the registry that failed to load, so the loudest
+  advice in the report points at work that must not be done. In a multi-file
+  registry it scales with the broken file's scenario count, and the one true
+  finding is at the top where a wall of red pushes it out of view.
+  *Why it is not simply the same call as `cover` and `render`.* Each of those
+  produces exactly **one** artifact, and refusing to produce it is the whole of
+  the decision. `check` is the command a pipeline runs first and its contract is
+  breadth — returning three findings instead of nine because one of the nine was
+  a load failure makes it quieter about problems it can still see perfectly well,
+  which is the opposite of what it is for. `verify` has the same shape with a run
+  attached.
+  *What blocks the decision.* The narrower move — keep reporting everything
+  except the findings **derived from** the missing registry, i.e. suppress
+  `orphan-test` for ids whose prefix belongs to a file that failed to load —
+  needs a prefix→file mapping for a file that never parsed, and that is exactly
+  the file `loadRegistry` has no ids from. Recovering the mapping means reading
+  the prefix out of something other than the registry's own keys (the file name,
+  or a partial AST read that survives the failure), and whether either is
+  trustworthy enough to gate a suppression on is unmeasured. Suppressing on the
+  weaker signal "some registry file failed to load, so suppress all
+  `orphan-test`" is the other candidate and is a strictly worse `check` on a
+  multi-file registry, where the other files are fine and their orphans are real.
+  **The wrong *advice* has been separated out and fixed; the noise has not.**
+  `[0.7.0]` changes `orphan-test`'s fix hint when any registry file failed
+  to load, so the loudest line in that report stops telling the reader to add an
+  id that already exists. That needed no mapping, because it claims nothing about
+  *which* orphans came from the broken file — only that the command cannot tell,
+  and what order to work in. It is worth separating because the two halves were
+  filed as one problem and are not: **being wrong** was fixable today at the cost
+  of a sentence, and **being loud** is the part still blocked on the mapping
+  above. The entry stays open on exactly that, with one blocker retired: the
+  measured six derived findings from one cause are still six, and only one of
+  them has stopped pointing at work that must not be done.
+
+- **A statement that quantifies over a surface, with scenarios covering only the
+  part that existed when it was written.** Found by reading, and it had already
+  cost something: `ATX-37` says "**everything** the CLI writes to a terminal —
+  a report, and the stack of a crash — MUST replace every control character",
+  and `self/report.spec.ts` covers `formatIssues` and `formatCrash`. Those were
+  the two functions that existed when it was written. `render` builds a document
+  by concatenation that never went past the sanitiser, and a registry could drive
+  the reviewer's terminal from `attest render` with no flag at all — shipped
+  under `[0.7.0]` as the fix, but the *shape* is not fixed and is not
+  specific to that requirement.
+  The shape: a universal quantifier in the statement, a finite set of scenarios,
+  and nothing anywhere that holds the two together. It reads as covered — the id
+  has scenarios, `cover` is green, `check` is green — and the quantifier is the
+  part no gate is looking at. Every one of the three mechanisms this project
+  sells operates *below* it: coverage asks whether an id has a scenario,
+  never-red asks whether that scenario discriminated, drift asks whether it reads
+  the params. None asks whether the scenarios span what the sentence claims.
+  *What blocks the decision.* Detecting it means knowing which surface a
+  statement names, which is prose judgement — the same judgement
+  `tests/intent-rule-candidates.spec.ts` records as the reason obligation
+  counting can never be an engine rule ("asserting a ground truth Attest cannot
+  compute for someone else's requirements, which is exactly what §0 refuses").
+  So the shippable form may not exist.
+  **The repo half has shipped, and this entry is now only about the engine
+  half.** `[0.7.0]` adds the `QUANTIFIED` table it described — hand-judged,
+  a row per flagged statement, every named scenario asserted to exist — and it
+  closed the way an entry built from a strict read is supposed to: it found a
+  live hole on `ATX-62`, the one requirement written specifically to avoid this
+  shape, where the archive gate path was claimed by the statement and asserted by
+  nothing. Two things came back that the entry did not predict. The useful one is
+  that "names a surface" splits three ways rather than two — `values`, `roster`,
+  `sites` — and only `sites` carries the risk, because a `roster` scenario
+  iterates the set the code owns and grows with it. That is a sharper statement
+  of the defect than "the scenarios do not span the sentence", and it is a rule
+  an author can act on: **prefer a quantifier a scenario can iterate.** The other
+  is that the remedy — rewriting the statement to name its surfaces, as `ATX-62`
+  did — takes it out of the flagged set, so the table has to allow rows for ids
+  the detector does not flag or it loses the binding exactly when the author does
+  the right thing.
+  *What stays open is the engine half, and nothing above touches it.* The three
+  kinds are prose judgement, the detector misses the article form ("A registry
+  that cannot be read MUST …") which is a universal too, and no rule can tell
+  which surface a sentence claims without being told. The repo half is a
+  counter-pressure, not a detector, and it holds for one registry whose authors
+  agreed to maintain it.
+
+- **Whether a requirement can ever be retired, and what it costs that none can.**
+  The registry is at 62 requirements and 160 scenarios, roughly 2.6 each, and
+  every one is a permanent obligation: `uncovered-requirement` is an ERROR, so a
+  requirement without a scenario cannot exist, and nothing ever removes one.
+  `delta.removed` exists and `applyDelta` applies it, but `--apply` refuses to
+  write it back, deliberately and with the reason recorded — REMOVED "cannot say
+  which comments belonged to the entry it deletes". So retiring one is a manual
+  registry edit, which is fine as a mechanism and says nothing about whether it
+  is ever the right move.
+  *What the growth actually costs, measured on this session rather than
+  estimated.* One small fix took: a requirement, its scenarios, a hand-judged
+  row in the `OBLIGATIONS` table, two inline snapshots, a `[Unreleased]` entry,
+  History rows in two languages, and a regenerated `SPEC.md`. That is
+  proportionate for a spec framework that has to dogfood — the ceremony *is* the
+  product being used on itself — and it is also a number that only goes up.
+  *What blocks the decision, and it is not the mechanism.* It is that "retire"
+  has at least three meanings this file has never had to separate: a requirement
+  that turned out **wrong** (which should leave a record of being wrong, and
+  `Considered and rejected` is where that already goes); one still **true** but
+  no longer worth a permanently-run scenario; and one **subsumed** by a later
+  requirement, where the scenario should move rather than go. Only the second is
+  really about cost, and it is the one where deleting the intent to save the
+  scenario inverts what the whole tool claims — that intent outlives its tests.
+  Nothing here is urgent while the number is 61. It is filed now because the
+  moment to write the argument down is while the reasoning is available, and
+  because a project whose requirement count only rises should have decided in
+  advance what would make one leave.
+
+- **The `cmd.exe` quoting in `tests/consumer.spec.ts` guards one character of
+  several.** `shellArg` asserts the argument holds no `"` and then quotes only
+  when it holds whitespace, so an argument with none goes to the shell bare —
+  and `&`, `|`, `^`, `<`, `>`, `(` are metacharacters there that the assertion
+  does not name. The fix is one character class, which is why the entry is not
+  about the fix.
+  *What blocks the decision is that no input reaches it.* Both arguments are
+  either a literal flag or a path from `mkdtemp`, `NEEDS_SHELL` is win32 only
+  and CI is Linux, and the one path an attacker could plausibly influence — the
+  checkout directory on a fork MR pipeline — comes from a GitLab project path,
+  whose character set excludes every metacharacter above. So this is an
+  observation with no attack path, and the honest question is not whether to
+  widen the class but whether the comment above it should stop claiming more
+  than the assertion covers: it says "the assertion keeps that true" about
+  arguments generally, where what it checks is one character. Widening the class
+  and leaving the prose is the change that would look like a fix and settle
+  nothing.
+
+- **A loader that fails to start leaves its scratch directory behind.**
+  `createLoader` calls `mkdtempSync` and writes the stub *before* `createServer`,
+  and the only `rm` of that directory is inside the `close` of the object
+  `createServer` returns — so a throw from it leaks one `attest-loader-*` per
+  invocation, which on a CI runner is one per build. That is the exact failure
+  shape the comment on `close` records as already fixed, surviving on the other
+  path.
+  *What blocks it is that nothing has been made to throw there.* With
+  `configFile: false` Vite still reads the `package.json` at the root to decide
+  `type`, so a malformed one in the checked project is the obvious candidate and
+  it is the project's to write — but it was not tried, and an entry claiming a
+  trigger it has not seen is the thing this section exists to not accumulate.
+  The repair is three lines (a `try` around the two calls that `rm`s and
+  rethrows) and is not what the decision turns on; measuring whether the throw
+  is reachable at all is, because if it is not, this is a leak with no input
+  that produces it.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -2614,6 +3605,45 @@ 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.
 
+### Region-marked samples, so a partial quote could be bound too
+
+Decided **yes** and filed under `Planned`, then killed by building the count it
+rested on. The whole-file half shipped in `[0.4.3]` — the README's two
+getting-started blocks are byte-equal to `fixtures/consumer/` — and the proposal
+was to raise that with `// #region readme:registry` markers inside the fixture,
+asserting a doc block against the dedented span rather than the whole file. The
+mechanism is sound and cheap. What it has no supply of is spans to bind.
+
+**The entry named its own two candidates, and both fail on inspection.** It said
+`troubleshooting.md`'s single-source pair is "two verbatim lines of
+`fixtures/consumer/session.spec.ts`": they are lines 8 and 11, so no span
+contains them, and line 8 reads `// single source, typed \`30\` — no cast` in the
+fixture against `// ✓ the single source` on the page. It said the `AUTH-3` block
+is "the registry entry at a different indent": the fixture wraps `statement:`
+onto a second line and the page does not, and the page's comment carries a `✓`
+the fixture has no reason to. **Both candidates carry a `✓`, which the same entry
+excludes by rule** — "anything carrying a `✓`/`✗` is authored commentary and
+stays a fragment". The entry's estimate contradicted the entry's own rule, and
+neither half was checked against the files until now.
+
+Swept the rest rather than stopping at the two: of the 23 fenced `ts` blocks in
+the README and `docs/en/**`, 2 are already bound whole, 3 are `src/` sketches the
+module-scope check in `[0.7.0]` covers, and the remaining 18 are elisions
+(`{ /* … */ }`), `✓`/`✗` fragments, input the engine must reject, or teaching
+sketches of the *reader's* project carrying inline commentary that is the point
+of them. **Zero spans.** So building it would ship a gate binding nothing, which
+this project treats as worse than the comment recording it — the argument §11
+makes and `ATX-43` and `ATX-44` both decline a promise on.
+
+What that leaves is the honest general form: **the reach of a byte-equality gate
+over documentation is set by how the documentation is written, not by the
+granularity the gate can address.** Raising it would mean rewriting the pages to
+be quotable, which is the tail wagging the dog — those `✓`/`✗` annotations and
+elisions are what makes a sample teach. The counterexample half was never
+dependent on this and stays under `Planned` as its own entry. If a passage is
+ever written that *is* a verbatim span of a fixture, this is three lines of
+`fencedBlocks` away and the reasoning above is what to re-read first.
+
 ### `typescript` as a peer dependency instead of a bundled one
 
 The open question the matrix entry was queued to settle (see `[0.4.2]`), and
@@ -2889,42 +3919,9 @@ 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.
 
-### Nested objects in `params`, so a lookup table can be registry-owned
-
-Raised by `mine-capablanca` (0.4.2) and explicitly not as a request, which is
-why it is recorded with its own answer rather than left as a complaint about a
-message. A `params` value is a scalar or a list of scalars; a table — piece kind
-to weight, tier to limit — is refused, and the only way to register one is to
-split it across parallel arrays, which reads worse in the rendered spec than it
-buys. *What rejected it: the two properties a param has, and a table has
-neither.* A param is **rendered into `SPEC.md` as a value a human checks at a
-glance**, and it is **read by a scenario as the one place that value lives**. A
-nested object fails the first by construction — there is no reading of a
-five-row table that a reviewer verifies the way they verify `30`. It fails the
-second more quietly: a table has many readers by definition, so "the one place"
-becomes "the one file", which is what an ordinary module already is. The
-schema's own comment records where the line was drawn and why arrays were let
-in — list constants are the most drift-prone values, and an array still has one
-owner read by one scenario. A table does not clear that bar; the reason arrays
-did is exactly the reason it does not.
-*The reporter's own resolution is the argument's strongest form.* The table went
-to a shared module, is not registry-owned, and **nothing was lost** — because a
-piece-value table is tuning, not a promise. That is the rule design §11 now
-states — *params for promises, plain constants for tuning* — derived
-independently by the same adopter before it was written anywhere. Under it this
-candidate is not a limitation of `params` at all: it is a value that was never a
-requirement's to hold, and §11 carries this rejection's own argument in the same
-paragraph, as the rule stated over the type rather than over the value.
-*What ships instead*, in `[0.5.0]`: the refusal now says what is accepted
-instead of `Invalid input`, and `troubleshooting.md` states the constraint and
-where such a value belongs — the reporter's actual ask, which was for the
-decision to be visible rather than discovered by reading the shipped `.d.ts`.
-The permanent half goes to design §11 with the params rule, not here.
-*This reopens on* a report where the value is genuinely promised — a table an
-adopter owes their users, whose rows a reviewer would want in the rendered spec.
-None has been seen; the one that raised it was tuning.
-
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.6.0...main
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.7.1...main
+[0.7.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.1
+[0.7.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.0
 [0.6.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.6.0
 [0.5.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.5.0
 [0.4.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.3