@am_shork/attest 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -13,6 +13,592 @@ 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.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,11 +3022,30 @@ 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,
+losing the argument would cost more than losing the task. The one entry left
+below came out of reading another repository against this one — `msw`.
+
+Eleven entries have left by being built: three together in `[0.6.0]`, and six
+under `[0.7.0]` — the verdict predicates, the nested `describe`, the runner
+the static commands loaded and could not start, the diagnosis for a spec file
+that failed to load, the six comments describing a property the code lacked, and
+the sketches now bound to the files they name — which are the first to leave by
+being **read** rather than by being reported or gated. The last of those left
+from `Under consideration` rather than from here, which is the move this file
+describes as going up before going out, and it went up on the strength of one
+thing: of its three candidates, exactly one could be measured against instances
+that had already happened.
+The second of those left *partially*: one of its three parts came back here as an
+entry of its own, because implementing the other two showed the estimate on it
+was wrong. An entry leaving is not evidence that all of it shipped, and this is
+the first time that has mattered. That returned part has now shipped as well, and
+it closed the way it said it would: the estimate was wrong because the fix was a
+new `Issue` code rather than a suppression, and what made it so was a decision
+recorded three lines from where the suppression would have gone. **The thing that
+cost the most was the thing already written down** — which is an argument for
+this section, since the note that corrected the estimate survived only because
+someone had filed the reasoning next to the code.
+`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.
@@ -2456,37 +3061,61 @@ 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.
+The entries added after `[0.6.0]` arrived a **fifth** way, and it is the
+one with no external input at all: a strict read of `src/` with nothing failing.
+Every gate in this repository was green while all three were true, which is the
+whole of what that way is for — a defect no test is shaped to ask about is
+reachable only by someone reading for it. **All three have now shipped under
+`[0.7.0]`**, and each closed having found something a strict read is
+apparently good for and a gate is not. The runner one: the gate that would have
+had to catch it *already* looked for the shape, so what the read bought was not a
+missing gate but a cost nobody had priced. The load-failure diagnosis: every gate
+was green because the report was *complete* — three ERRORs on a red run — and
+what was wrong was which three, a judgement no assertion in this repository is
+shaped to make. The third, eight items under one heading: six comments naming a
+property the code lacked and two costs beside them.
+
+**One entry has now left this section the other way — by being rejected** — and
+it is the first, which is why it is worth a line. The region-marked samples were
+decided *yes*, and building the count they rested on is what killed them: the two
+spans the entry named are not spans, and both carry a mark the entry's own rule
+excludes. It moved down with that measurement attached. The lesson is not about
+regions. **An entry can sit in `Planned` for releases on the strength of a figure
+nobody has checked**, because the section's discipline is aimed at keeping the
+*argument* rather than at re-testing the evidence under it — so the first act of
+building one should be re-measuring what it claims, not implementing what it
+proposes. That is what happened here, and it cost an hour instead of a mechanism.
+
+*What the fifth way cost and returned, now that all of it is spent.* Sixteen
+items, no external input, and nothing in the suite shaped to catch any of them.
+The returns were not evenly distributed and the split is the useful part: two
+defects a user could hit today (a report that misdiagnosed a load failure, a
+merge crossing midnight), two costs worth a second each on a real command
+(`check --eval` at 1 + N Vite servers, `control` at 27–84x), one fixed toll on
+every static invocation (~1 s), and the rest true-but-unobservable — identical
+output either way. Only the last group is genuinely optional, and it is also the
+group that would never have been found any other way, because *no observable
+symptom* is precisely the definition of what a gate cannot see. The transferable
+lesson is the batching: individually none of the unobservable ones justifies a
+commit, and together they cost about an hour.
+
+- **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.
 
 ## Under consideration
 
@@ -2500,6 +3129,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 +3268,126 @@ 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.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -2614,6 +3398,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
@@ -2924,7 +3747,8 @@ The permanent half goes to design §11 with the params rule, not here.
 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.0...main
+[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