@am_shork/attest 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -13,6 +13,211 @@ 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.9.3] - 2026-08-18
+
+### Added
+
+- **The archive is read back, as `inspectRedEvidence` on `@am_shork/attest/inspect`
+  (`ATX-80`).** `archive --apply` moves each merged change into
+  `archive/<date>-<name>/`, carrying `proposal.md`, the delta and the record of
+  how every one of its scenarios ended the *first* time it ran — and nothing
+  read any of it. The only store here that keeps a decision with its evidence
+  attached was write-only. It now answers, for each scenario a project declares,
+  which of `fail` / `pass` / `unobserved` / `unarchived` the archived records
+  place it in. Promoted from `Planned`, where the blockers were an archive
+  nobody had produced and an entry point nobody had chosen.
+
+  *The question the entry was promoted with was the wrong granularity, and
+  finding that is most of what this change is.* It asked which **requirements**
+  ever had a scenario observed failing. Under the gate as written that is true
+  by construction for every archived id — `neverRedIssues` walks *every*
+  scenario of every ADDED id and blocks on any one without a recorded red, so a
+  change that archived at all archived with the whole set proven. Where the gate
+  genuinely stops is one level down, and it leaks two ways: a scenario grown
+  onto a requirement after it archived can never acquire evidence, because
+  `never-red` fires only on ids a change is currently ADDing and an archived id
+  is ADDed by nothing again; and MODIFIED carries no such obligation at all, so
+  a requirement whose statement is later rewritten keeps evidence only for the
+  form it had when it archived. Both accumulate silently. The report is
+  therefore over `(reqId, file, name)`, which the record already keys by.
+
+  *Four states rather than two, and the two absences are the whole design.*
+  `unarchived` — the id is in no archived change at all — is a requirement
+  written straight into the registry, which is how existing behaviour is
+  described in a brownfield adoption and which design §6 gives no obligation to
+  have been red. `unobserved` — the id **is** archived and this scenario is not
+  in the record — is the drift above. Folding them together would report a
+  design working exactly as intended as though it were a backlog, and on a
+  first-day adoption that is every row. `pass` stays separate from both because
+  the gate cannot produce it, so an archived one means a hand-edited record or a
+  format that moved.
+
+  *Two things it deliberately does not do.* It does not judge: whether an
+  `unobserved` scenario matters is a judgement about that scenario, which is the
+  ground truth §0 refuses to compute for someone else. And it does not hand back
+  the records — the archive read returns rows, because the record is a nested map
+  keyed by ids, paths and scenario names read off disk, and exporting the
+  container would export the prototype hazard `red-record.ts` exists to hold.
+
+  *`proposal.md` is not read, and that is the blocker dissolving rather than
+  being cleared.* The prose half was filed as the one carrying the reasoning.
+  In this repository it carries a link: `CLAUDE.md` makes `CHANGELOG.md` the
+  single decision record, so a proposal restating an argument would be a second
+  store of it with nothing comparing the two. There is nothing in it for an
+  index to offer but its path.
+
+  *The three scan exclusions are untouched.* `locate.ts`, `runner.ts` and
+  `pipeline.ts` each still exclude `archive/`, and they are §7 and §8 — an
+  archived change's requirements and specs must not re-enter a normal run. The
+  new read walks the archive for facts *about* archived changes, never to fold
+  their contents back into a registry or a plan.
+
+  *Blocker **(2)** is settled against the fifth static command, on the roster's
+  own terms.* `ATX-16`'s subject is reading TypeScript *without evaluating it* —
+  its rationale is about a top-level `fetch` in a registry file reaching CI
+  secrets on a fork merge request. `first-run.json` is JSON; joining that roster
+  would quietly turn a security promise into a list of commands that do not run
+  the suite. The trial datum that seemed to point at a command measured demand
+  to read the archive **as prose**, which is a different question. And the
+  direction is reversible: adding a command later is additive, narrowing a
+  requirement's roster back is not. Two things measured while deciding —
+  `archive.ts`'s runtime closure names no `vite`/`vitest`, so `ATX-79`'s
+  peer-free promise holds over the new reachability; and `intent-quality.md`
+  already exists for findings of exactly this kind, where `cli-reference.md`
+  has no place to state one.
+
+  *What it cost elsewhere, because it is the part that does not announce
+  itself.* The fixture that exercises all four states adds a registry, and the
+  judgement tables in `tests/intent-rule-candidates.spec.ts` score the fixtures
+  too — so the corpus moved 87 → 90 and four measurements were re-read rather
+  than re-baselined. `ATX-80` is judged compound (2), and `compound-requirement`
+  flags it correctly; its quantifier ranges over values, the shape that table
+  prefers; `ATX-80.states` is an iterated domain and carries its pin. One new
+  divergence needed judging — `states:ATX-32,ATX-80` — and it is worth a line
+  because of how it arrived rather than how it reads: two reports each naming
+  their own closed set of labels, neither author aware of the other, which is a
+  second generic param name starting the climb `code` made to nineteen members.
+  The count of judgements a shippable `divergent-param` would demand grows with
+  the registry, from nothing anyone did wrong.
+
+  *Mutation-checked, and one assertion did not survive it.* Every new test was
+  run against a deliberately broken implementation. The one pinning archived
+  folder order passed with the sort deleted, because `readdir` returns names
+  already ordered on Windows — the fixture-with-no-separator shape from the
+  `Fixed` entry below, arriving in a new test on the day it was written. Fixed
+  by choosing names where the two orders differ, measured rather than assumed,
+  with the casing called out in the test so it is not tidied away.
+
+  *One more scenario, added before cutting a release, and writing it corrected
+  the reason it was added.* Every state above was read out of a hand-written
+  `first-run.json` at a folder this repository spelled, so the reader had never
+  met an archive the tool itself produced. `self/merge.spec.ts` now runs
+  `--apply` for real and joins the result: the folder is the one the run's own
+  date stamp named, and the report's paths are derived from whatever it picked.
+  Mutation-checked to be worth its runtime — an enumeration that finds nothing,
+  and the two absences folded into one, each fail it and no other scenario in
+  that file.
+
+  **The risk it was written to close turned out not to exist, which is the more
+  useful half.** The reason given for it was the proposed → merged rename: the
+  record is written while the spec is `*.proposed.spec.ts` and `--apply` renames
+  that file, so `fileKey` is what keeps the two meeting. Reading the code to
+  write the assertion showed the archive reader cannot exercise that at all.
+  `recordedOutcome` normalises the **ref**, and the record is keyed in merged
+  spelling from the start — so by the time a change is archived, every ref this
+  reader passes is already post-merge and `fileKey` is the identity on all of
+  them. The translation exists for the gate reading a record mid-flight, and the
+  archive reader is downstream of the point where it can matter. The scenario
+  stays, for what it does cover; the claim it was justified with is written out.
+
+  *A hazard found by running the mutations, worth recording because nothing
+  reports it.* Stubbing `mergedSpecPath` and running the suite **rewrote two
+  committed fixtures** — `fixtures/e2e-archive` and `fixtures/stdout-pollution`
+  each hold a `first-run.json` that a real archive run rewrites in place, so a
+  mutation run leaves the working tree dirty with plausible-looking changes to
+  files nobody edited. Caught by `git status`, not by any gate. It also settles
+  the write half by accident: those records really are produced through
+  `fileKey`, because under the stub they came out keyed by the proposed
+  spelling.
+
+- **The propose stage now asks three questions, where it previously said how to
+  write a delta and nothing about what to check you had thought about.** They sit
+  at the end of Stage 1, immediately before the instruction to present and stop:
+  what pins each expectation, does each statement carry one obligation, and was
+  any of this ever red. Promoted from `Planned`, where the blocker was the
+  selection rather than the idea — spec-kit's `clarify` carries nine generic
+  categories, and copying them wholesale was the specific thing to avoid, because
+  §10's economics put every line of that document into every adopting project's
+  agent context forever.
+
+  *The selection is by what this repository has actually been bitten by*, which
+  is a different list from a product-spec taxonomy. **(1)** is the measured one:
+  the mine-density band moved 3.3× with the whole suite green because the
+  assertion recomputed its expectation from the param the code under test
+  consumed — the entry still under `Under consideration`, whose *guidance* half
+  shipped in `[0.5.0]` as a statement in *The model*. What is new here is asking
+  it as a question at the moment the assertion is being authored, which is a
+  different mechanism from stating the rule 80 lines earlier in the same file.
+  **(2)** is measured too: 34 of this repository's requirements carry more than
+  one obligation, so the question is doing work no shipped diagnostic does — and
+  deliberately names no code, because none exists to name. **(3)** answers what
+  the archive gate structurally cannot ask: `never-red` demands a recorded
+  failing run only for the ids a change ADDs, so a requirement written for
+  behaviour already shipped never had a moment when it should have failed.
+
+  *Two more went to `CLAUDE.md` instead*, and that split is the finding the entry
+  did not anticipate — the checklist wanted two destinations, not one. Crossing a
+  platform boundary, and whether a change leaves `check`, `cover`, `render` and
+  `status` executing nothing, are about this engine's internals; shipping them
+  would have been the dead weight the cost argument was worried about without
+  being able to name.
+
+  *Re-measured before building, per the discipline that section runs on, and the
+  claim held exactly*: the document was 405 lines with Stage 1 at 87–255, still
+  exactly 169. **The cost claim did not hold, and the entry's own number was
+  wrong.** It priced this at "three lines rather than nine" by counting one line
+  per category, which is what nine generic categories would have cost as a bare
+  list. Three questions with the clause each needs to be answerable cost **eight**
+  lines: Stage 1 is now 177 and the document 413. Still under half of what the
+  nine would have been, so the argument survives its own number being off, but the
+  number is corrected here rather than quietly restated.
+
+  *And the question the entry left open is answered: no new `ATX-n`.* The
+  document's content is gated only by `ATX-57`, which asks that every diagnostic
+  code it names be one the engine can emit — and asking *what this makes
+  reachable for the first time* is what that check turned into here: the only
+  hyphenated code-voice token the three questions add is `never-red`, which the
+  document already named. What they earn instead is **one scenario on `ATX-27`**,
+  which already obliges the body to carry the workflow rather than a pointer to
+  it. A requirement of their own would make every rewording of three sentences a
+  registry change; no assertion at all would leave a checklist with no diagnostic
+  behind it able to be dropped in silence — the same decay shape as the fixture
+  assertion fixed below, which is what decided it.
+
+### Fixed
+
+- **The assertion guarding the one fixture that exercises a path separator
+  passed on a corpus with no separator in it.** `CLAUDE.md` says not to flatten
+  `fixtures/nested-spec/`, because its spec is the only one that sits below a
+  root and a relative spec path becomes the child run's `include` glob, where a
+  backslash is an escape character. What stood behind that instruction was
+  `tests/paths.spec.ts` scanning the fixture and asserting that no relative path
+  contains a backslash — and a flat filename contains no backslash either, so
+  flattening the fixture would have left the test green while removing the only
+  thing it was there to exercise. The rule with a written warning against silent
+  decay was guarded by an assertion that decayed silently.
+
+  Now a second assertion requires the scan to find a spec below the root, which
+  is the property the fixture exists for. Checked against a flattened copy
+  before being written: the predicate is true on the fixture as committed and
+  false on the same files laid flat.
+
+  *Found by the `CLAUDE.md` audit filed under `Considered and rejected`*, whose
+  answer to "which of these rules should become requirement ids" was none — this
+  is the one actionable thing it turned up, and it is a plain test rather than an
+  `ATX-n` because it is a property of this repository's fixture corpus and not a
+  promise Attest makes to anyone.
+
 ## [0.9.2] - 2026-08-17
 
 ### Added
@@ -5134,6 +5339,10 @@ have to gather again.
   **changing the value of an existing param goes through no gate at all.**
   `archive` gates a change; a param edit is not a change. That is a cleaner
   statement of the gap than "params can be tautological".
+  **That observation is now its own entry at the foot of this section**, split
+  out and measured on 2026-08-18, because it asks what happens when a value
+  moves rather than whether an assertion is a real comparison, and neither
+  answer settles the other. What stays here is the detector.
   *What blocks the decision — three things, all of them real.* **(1)** Every
   mutation above is synthetic. Across 8 commits touching `*.reqs.ts` in that
   repo, **no param value was ever modified** — every `params:` line in every diff
@@ -5279,7 +5488,7 @@ have to gather again.
   pass and separating them is the finding.
 
 - **Whether a requirement can ever be retired, and what it costs that none can.**
-  The registry is at **69 requirements and 192 scenarios, 2.78 each**, and
+  The registry is at **79 requirements and 221 scenarios, 2.80 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
@@ -5324,6 +5533,19 @@ have to gather again.
   the ratio: 2.56 → 2.78. The cost of a requirement is not flat and it is not
   falling, which is the premise the whole entry rests on, and it is the first
   time this file has had two measurements of it to compare.
+  *A third measurement, on 2026-08-18, and it points the other way from the
+  second.* **79 requirements and 221 scenarios**, counted the way `verify self`
+  prints them, which is the control the 2026-08-08 restatement established. The
+  ratio runs 2.56 → 2.78 → **2.80**, so the step that carried the argument was
+  the first one and the second is **+0.015**, which is flat. The premise this
+  entry rests on now has one measurement for it and one against, and the honest
+  statement is the narrower one: per-requirement cost has held at about 2.8
+  scenarios across ten days and ten requirements. What is unchanged is the
+  absolute total, which only rises — that half of the argument is untouched, and
+  it was always the half about permanence rather than about acceleration. What is
+  no longer supported is the acceleration. **Reopening on cost needs the ratio to
+  move again**; reopening on the three meanings of "retire" needs none of these
+  figures, and that is still the part nobody has separated.
 
 - **Running `verify` over a subset of the scenarios, and what a partial run may
   be allowed to say.** `verify` is all-or-nothing and `check` executes nothing,
@@ -5549,6 +5771,191 @@ have to gather again.
   follows; if it comes back different, `inspect` was the whole answer and the
   schema never needs to exist.
 
+- **A registry cannot say a value is deliberately undecided, and an agent that
+  cannot determine one will invent it.** From a read of GitHub's spec-kit
+  against this design — the first time another SDD toolkit has been compared
+  here rather than OpenSpec, and the source of this entry and the three that
+  followed it — of which two have since been decided: the audit of this
+  repository's own rules is rejected below, and the propose-stage coverage scan
+  shipped under `[0.9.3]`, as three questions rather than nine categories.
+  spec-kit marks an unresolved decision inline as `[NEEDS CLARIFICATION: …]`,
+  greppable, with a command whose whole job is converging them. Attest's
+  registry has two states: schema-valid, or an ERROR. There is no third.
+  *Why that matters here specifically, rather than as a general nicety.* The
+  workflow is written for an agent to follow — that is what `init` writes — and
+  an agent drafting a delta that cannot determine a timeout does not leave the
+  field out, because the schema will not let it. It picks a number. A fabricated
+  `params` value, then pinned by a scenario written to match it, is exactly the
+  drift this project exists to prevent, arriving through the mechanism meant to
+  stop it: the single source is perfectly consistent and describes a promise
+  nobody made.
+  *A precedent that is not one, recorded because it reads like one.*
+  `rationale-placeholder` already warns about authoring sloppiness in a prose
+  field, and the `init` document already teaches it — but it is about
+  interpolation syntax written into the wrong field, not about a value nobody
+  has decided. The engine's willingness to warn on prose is the precedent; the
+  diagnostic is not the feature.
+  *The gap is narrower than "the registry cannot express doubt".* `changes/` is
+  already the place where a whole proposal is undecided, and the archive gate is
+  what settles it. What has no expression is **one field** of an otherwise
+  well-formed requirement.
+  *Shape, if it is built:* an additive `open?: string[]`, naming the fields or
+  questions still unresolved; a WARNING from `check`, so a proposal may be
+  legitimately half-finished, and an ERROR at the archive gate, so "done" is not
+  diluted. The same asymmetry `never-red` already runs on.
+  *What blocks the decision — three things.* **(1)** The frequency is entirely
+  unmeasured. No adoption report has recorded an agent inventing a param; the
+  argument above is structural, and this project has twice been wrong about a
+  hazard it reasoned to rather than measured. **(2)** The cheap half already
+  works: writing the uncertainty into `rationale` as prose costs nothing, and
+  the propose stage is human-reviewed regardless. What that does not buy is a
+  gate, which is the whole question. **(3)** It is permanent surface — a schema
+  field, a code, two troubleshooting sections, a History row, an `ATX-n` and its
+  scenarios forever — for a hazard nobody has yet reported.
+
+- **Prefix ownership is inferred rather than declared, and the cost arrives only
+  when adoption succeeds.** Design §11 records that the id grammar has no level
+  above the requirement: the prefix is a convention, nothing allocates it, and
+  `duplicate-prefix` can only report a collision that already happened.
+  spec-kit's answer is a roadmap table — a stable id, an intent, a scope
+  boundary, dependencies — authored above the specs it decomposes into.
+  *Two things have changed since that reading, and they point opposite ways.*
+  The proposal is **smaller** than it looked: the mechanism partly exists.
+  `loadRegistry` returns `prefixOwners` — first claim in sorted file order —
+  `merge.ts` uses it to decide which file an ADDED id belongs in, and
+  `apply-no-prefix-owner` already refuses a prefix nobody owns. So what is
+  proposed is declaration replacing inference, not a new layer. And it is
+  **weaker**: `/inspect` shipped in `[0.9.2]`, so the cross-repository half —
+  the one §11 says no command can see across — is now something an adopter
+  computes from two registries in about ten lines. Attest does not have to own
+  it to make it possible.
+  *What blocks the decision:* nobody has the problem. §11 states the cost
+  arrives "exactly when adoption succeeds: two teams sharing a registry have
+  someone owning prefix allocation by hand", and no such adoption has been
+  reported. Building the declared form now would be deciding prefix semantics
+  for everyone from one repository whose five prefixes — `ATX` and the four
+  fixture ones — are each declared by exactly one file, so the allocation
+  question this would answer has never been asked here.
+
+
+- **A merged requirement carries no trace of the change that produced it, and
+  the rename chain is the part actually lost.** `RequirementSchema` is
+  `statement`, `rationale`, `params`, `outOfScope`; the splice writes those and
+  nothing else, so after `--apply` no field and no sidecar records which change
+  introduced an id, which modified it, or that one id used to be another. The
+  delta that knew is in `archive/`, which nothing reads. Proposed from
+  OpenViking's `.relations.json`: links between memories live in a
+  directory-level sidecar, deliberately kept out of the content, and are
+  rendered on demand at retrieval time (`docs/design/memory-link-design.md`).
+  *The argument for the sidecar over a field is in their competitor analysis
+  rather than their design.* The same document reads GBrain, which writes links
+  into the page body, and records what that costs: rename a page and every
+  inbound link still points at the old slug, with fuzzy matching at the read end
+  as the only mitigation. A `supersedes:` or `introducedBy:` field on a
+  requirement would be that mistake in this repository's terms — the registry is
+  a literal and a single source (§2), and a field naming a folder that a later
+  rename can move is a second source with nothing comparing it against the
+  first. A derived index has no such copy to go stale: it is recomputed from the
+  archived deltas every time it is read.
+  *What blocks the decision:* the empty archive — the subject of the entry that
+  shipped under `[0.9.3]`, whose promotion this one does **not** inherit,
+  because the two changes that produced that corpus were ADDED-only and
+  exercised no rename at all — which makes a backlink index testable only
+  against fixtures; and one question the OpenViking reading
+  does not answer, which is whether the chain is wanted at all. §7 applies
+  `RENAMED` to a `Map<id, Requirement>` and the old id is then simply gone —
+  deliberately, as far as anything written says. The case for recovering it is an
+  external reference that outlives the rename, a ticket or a commit message
+  naming a retired id, and nobody has reported one.
+
+- **The instruction document says how to write intent and nothing about how to
+  read the record back.** §10's one-document-many-targets file is entirely about
+  authoring, and the moment anything reads `archive/` — the entry above, and the
+  one that shipped under `[0.9.3]` — an
+  agent is holding prose from a proposal agreed on some past date against a
+  registry that is current, with no stated order between them. OpenViking states
+  one for its own store in the skill it ships to coding agents
+  (`agent-plugins/skills/openviking-memory/SKILL.md`): retrieved memory is
+  advisory, and the order is system and developer instructions, then the current
+  request, then current environment and tool evidence, then memory — with "prior
+  success never authorizes a destructive action now", and "store conclusions,
+  not scrollback".
+  *Here the same rule has a harder form, because the authoritative half is
+  machine-checked.* The registry and the gate's verdict are evidence; an
+  archived proposal is testimony about a decision taken once. Where they
+  disagree, the disagreement is a finding — the exact thing this tool exists to
+  report — and not something for a reader to reconcile quietly in favour of
+  whichever it read last. That is a property of the design rather than of a
+  file, so if it is taken it lands in design §11 first and in the instruction
+  document second.
+  *What blocks the decision:* it is a rule for reading a store nothing reads yet,
+  so on its own it would document a hazard that cannot currently arise. It is the
+  cheapest of the three and could ship first, at the price of being the only
+  paragraph in that file describing a workflow the tool does not have — and §10's
+  economics make that price the same in every adopter's agent instructions at
+  once.
+  **That blocker is retired, and what replaced it is narrower than the entry
+  assumed.** Something reads `archive/` as of `[0.9.3]`, so the hazard can
+  now arise. But what shipped reads the **typed** half — `first-run.json`, whose
+  every value is an `Outcome` in a schema-validated envelope — and evidence that
+  parses cannot disagree with the registry in the way testimony can: a scenario
+  either is in the record or is not. The rule this entry wants is about the prose
+  half, and the prose half is still read by nothing. So the store is no longer
+  write-only and the entry's own subject is still hypothetical, which is a
+  different blocker from the one it was filed with rather than none.
+
+- **Changing the value of an existing param passes no gate, and for seven of
+  them there is no record either.** Split out of the tautology entry at the
+  head of this section on 2026-08-18, where it was one sentence inside the
+  reframing paragraph. It is a different question: that entry asks whether an
+  assertion is a real comparison, this one asks what happens when the number
+  itself moves, and neither answer settles the other. `archive` gates a
+  **change** — a delta, proposed specs, a recorded failing run — and a param edit
+  is none of those. It is one literal in a merged `*.reqs.ts`, and every gate
+  reads it as fine: `check` finds it schema-valid, because a param is any JSON
+  value; `possible-drift` is quiet by construction, since `ATX-8` makes it ask
+  whether *any* covering scenario reads the params at all rather than whether a
+  value moved; and `verify` stays green wherever the assertion derives its
+  expectation from the same param, which is the pair of green rows measured in
+  the entry this was split from.
+  *What is left is `render`, and it was measured here rather than assumed.*
+  Across **89 params on 59 of this repository's 79 requirements, 82 — 92.1% —
+  are interpolated into their own statement**, so editing one changes
+  `self/requirements/SPEC.md` and `render --check` fails until the document is
+  regenerated. That is a review surface and not a gate: the new value lands in a
+  committed generated file where a reader can see it, and nothing anywhere asks
+  whether the move was intended.
+  *The other seven leave no trace outside the line that was edited, and which
+  seven they are is the finding rather than the count.* Five are **structurally
+  uninterpolatable**: `ATX-7.payloadKinds` and `ATX-63.payloadKinds` are
+  kind → payload tables, and `ATX-15.sortMethods`, `ATX-15.bannedApis` and
+  `ATX-72.quotes` are lists. A statement cannot carry any of them —
+  `non-scalar-interpolation` is the diagnostic that refuses it — so the params
+  with no record are disproportionately the shape §2 widened the params rule to
+  cover **precisely because lists and tables are the most drift-prone constants
+  there are**. The remaining two, `ATX-15.comparator` and `ATX-26.code`, are
+  scalars their author simply did not interpolate.
+  *What this is not.* It is not a re-proposal of the committed params snapshot
+  rejected below. That was rejected on the argument that the mechanism guarding a
+  param is a scenario reading it rather than a file recording it, and nothing
+  here disputes that or needs a second copy of the values. The observation is
+  narrower: the **edit** is unremarkable to every gate, which is a different
+  claim from the values being unguarded.
+  *What blocks the decision — and the first is the one that blocks the entry this
+  came from.* **(1)** Frequency is unmeasured, and the one corpus anybody has
+  looked at points at zero: across 8 commits touching `*.reqs.ts` in the
+  reporting repository, no param value was ever modified — every `params:` line
+  in every diff is an addition. A defect nobody has committed is a hazard rather
+  than a report. **(2)** No shape is obvious. A param edit is not a change, so
+  `archive` is the wrong place; making `check` notice one needs a previous value
+  to compare against, which is the rejected snapshot wearing a different hat. The
+  only mechanism needing no stored copy is review, and review already sees the
+  `SPEC.md` diff for 82 of the 89. **(3)** What is left after that is seven
+  params in one repository, and the right answer for the five that matter may be
+  nothing more than a line in `intent-quality.md` — the four things no gate is
+  looking at already being that page's subject, and this being a fifth of the
+  same kind.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -6282,6 +6689,180 @@ 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.
 
+### An append-only writer for `status`, following spec-kit's `converge`
+
+spec-kit's `converge` assesses the codebase against a feature's artifacts and
+appends the remaining work as new tasks, under a strict contract: its only write
+is a new section at the foot of `tasks.md`, and it may not rewrite, renumber,
+reorder or delete anything already there. Proposed here as the shape `status`
+would need if it ever produced todos rather than a report, on the grounds that
+append-only is the safe way to write into a file a human owns.
+
+*Rejected because this repository already has a strictly finer instrument, and
+the first reading missed it by comparing the wrong pair.* `ATX-76`: with
+`--apply`, a MODIFIED requirement is written back by replacing the source span
+of **each value that changed** — never the entry holding them — and the whole
+merge is refused, with nothing written, when a span it would overwrite carries a
+comment. That is a smaller unit than "append at the foot", and it solves the
+harder problem: editing in place without destroying what a person wrote around
+it. Append-only avoids the question by never touching existing text; `--apply`
+answers it. The comparison that produced the proposal was `converge` against
+`status`, and it never looked at what the command that actually writes already
+does.
+
+*And the premise is unbuilt anyway.* `status` is a report, deliberately — it
+answers what the gate still wants, from the delta, the specs and the record,
+running nothing. No adoption report, and nobody here, has asked it to become a
+writer. A write discipline for a command that does not write is a solution
+looking for its problem, which is what `Speculative Generality` names.
+
+*Reopening this needs `status` to have a reason to write at all* — and if that
+ever happens, the discipline to reach for is `ATX-76`'s, not this one.
+
+### A Sync Impact Report at the head of a governance document
+
+spec-kit's `constitution.md` opens with a comment block recording what a change
+to it touched: the version bump and its rationale, the principles defined, and a
+checklist of every downstream template reviewed for alignment, each carrying a
+note on what was checked. Proposed here as a general form of the rule that a `docs/en` change
+carries its `docs/zh` counterpart in the same commit — a persisted record, per
+change, of what was checked downstream.
+
+*Rejected because `pre-commit-check` already produces exactly that, per commit,
+and produces it where it is useful.* The skill's opening instruction is to
+report which items applied and which did not, saying plainly when something was
+skipped and why, because "a silent omission is the failure mode this exists to
+prevent". That output is a Sync Impact Report under another name, produced at
+the moment of the change rather than pinned to the head of a file, and it covers
+more than one document's downstream — packaging, the `Issue` code contract,
+`SCHEMA_VERSION`, both language trees.
+
+*What persisting a second copy would cost is the thing this project has been
+most consistent about avoiding:* it splits a store deliberately kept single. The
+same argument keeps decisions in this file rather than an ADR directory, and it
+applies with more force here, because the two copies would disagree the first
+time a commit's report says something the header block does not.
+
+*The other half of the constitution reading* — that this repository's
+load-bearing rules have no ids and nothing reads them — survived the rejection of
+the document that carried it and was filed under `Under consideration`. Its audit
+was done on 2026-08-18 and it is now rejected too, in the section directly below
+this one, on an argument neither half of the reading predicted.
+
+### Promoting this repository's own rules in `CLAUDE.md` to requirement ids
+
+The audit this entry was filed for was done on 2026-08-18 and its answer is
+**none**. The entry named its own first step — an audit whose primary output is a
+rejection list — and asked which `CLAUDE.md` rules should become ids, on the
+observation that rules whose violation has already produced silent defects are
+gated by nothing.
+
+*Three were already ids, which the entry knew.* `ATX-28` is the path-spelling
+rule, `ATX-29` the line-endings rule in the form that matters (the freshness
+check compares the document rather than its bytes), and `ATX-16` with `ATX-17`
+the two-readers rule: the four-command static roster, and the refusal to fall
+back to evaluating a registry that will not read.
+
+*One is already gated and the entry did not know it.* `docs/zh/**` mirroring
+`docs/en/**` one-for-one is asserted twice in `tests/docs-consistency.spec.ts` —
+every English page has exactly one Chinese counterpart, and each pair shares a
+heading tree and a code-sample sequence. What has no gate is whether the two
+still *say* the same thing, which is what `CLAUDE.md` and `pre-commit-check` §6
+both mean by "checked by eye only": the structural half is held, the semantic
+half cannot be.
+
+*The rest fall into three groups and none of them wants an id.* **Six are
+working habits** — `vitest run` does not run `self/`; it also runs the type
+tests; `bin/attest.js` loads `dist/`; some fixtures fail on purpose; a scenario
+starting a child run needs an explicit timeout; a package manager is spawned only
+through the one helper in `tests/consumer.spec.ts`. Each is about how to work in
+this repository rather than what Attest promises anyone, and §1 is decisive:
+a requirement costs a mandatory scenario forever, so these would be six scenarios
+asserting facts about a maintainer's habits. **Two are the design vocabulary and
+the filing rule**, which are definitions and a destination — there is nothing to
+assert. **And one constrains a consumer rather than the engine**, which is the
+finding worth keeping.
+
+*`Issue.message` is prose, never API — the most load-bearing ungated rule in the
+file, and no id can hold it.* The promise is that a consumer may branch on `code`
+and `reqId` and must not branch on wording, so the obligation falls on the
+consumer's tests and not on any behaviour a run of this engine can exhibit. The
+checkable half is already structural: `code` is typed to the roster in
+`src/core/docs.ts`, and `ATX-40` obliges every code to carry a troubleshooting
+section in both languages. A requirement stating the rest would either restate a
+type or assert something no run can observe. **This is the audit's general
+result rather than one rule's exception** — the file is mostly a working
+agreement with this repository's maintainers, and the three rules in it that were
+contracts Attest owes an adopter had all been promoted before the question was
+asked.
+
+*The same argument retires the entry's own sharpener.* `[0.9.2]` edited
+`.claude/skills/pre-commit-check/SKILL.md` with no gate having an opinion about
+its contents, and that is true — but measured, the machine-checkable surface of
+that document is **one token**: it names exactly one issue code,
+`spec-load-failed`, and that code exists. An `ATX-57` analogue over it would gate
+a roster of one. Everything else in the document is judgement, which is both what
+a gate cannot hold and the reason the document is prose.
+
+*One actionable finding survives, and it is not an id.* `CLAUDE.md` says not to
+flatten `fixtures/nested-spec/`, because its spec is the only one below a root
+and therefore the only thing exercising a separator. The guard is
+`tests/paths.spec.ts`, which scans that fixture and asserts that no relative path
+contains a backslash — **and that assertion passes on a flattened corpus**,
+because a flat filename contains no backslash either. The rule carrying a written
+warning against silent decay is guarded by an assertion that decays silently. The
+fix is one line in that test, requiring at least one scanned path to sit below the
+root, and it is a plain test rather than a requirement for the same reason as
+everything else here: it is a property of this repository's fixture corpus, not a
+promise about Attest's behaviour. **Done under `[0.9.3]`**, and the guard
+was checked against a flattened copy of the fixture before it was written — the
+predicate reads true on `fixtures/nested-spec/` and false on the same files laid
+flat, which is the difference the old assertion could not see.
+
+*Worth reopening only for a rule that is a contract* — one Attest owes an
+adopter, added to that file later. It belongs in the registry when it is written,
+not in a second sweep of prose.
+
+### Semantic retrieval over the intent layer
+
+Priced on 2026-08-18 while reading OpenViking (volcengine/OpenViking, AGPL-3.0,
+at `87d5142e`) for what a context database for agents has that this repository
+does not. The proposal was its retrieval path
+(`docs/en/concepts/07-retrieval.md`): embed requirements, specs and archived
+proposals, then answer a question with an LLM intent analysis that emits zero to
+five typed queries, a priority-queue recursion down the directory tree with
+score propagation, and a rerank pass over the survivors.
+
+Rejected on what that machinery is *for*. Every part of it is a way to find
+things in a corpus that has lost its structure — free text, no ids, no grammar,
+tens of thousands of entries. This one has 79 requirements in a single file,
+each with an id matching `/^[A-Z]+-\d+$/`, grouped by a prefix, carrying a
+statement written to contain SHALL or MUST. Lookup by id is exact and free;
+`grep` over the statements answers the rest. Ranking is what you reach for when
+you cannot address; addressing is the thing this design already has, and §5.4
+extends it to evidence by keying the red record on requirement id, spec file and
+scenario name.
+
+The second reason is the one that would survive a bigger corpus. A retriever of
+that shape puts a non-deterministic, network-dependent, unfalsifiable scorer
+beside four commands whose defining property is that they execute nothing and
+whose output is a verdict a reader has to be able to reproduce. Their own
+document specifies the degradation frankly — "if rerank returns an invalid
+result or the API call fails, retrieval falls back to vector scores" — and a
+silent fallback to a weaker mechanism is precisely what §5.1 refuses when it
+makes a non-static registry a `registry-not-static` ERROR rather than a
+fallback to evaluation. The same answer applies here for the same reason.
+
+Worth reopening if an adopter's registry reaches a size where prefix grouping
+and `grep` genuinely stop working — but the first thing to try then is the
+declared prefix ownership already under consideration above, which addresses,
+rather than a scorer, which ranks.
+
+## Releases
+
+[0.9.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.3
+[0.9.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.2
+[0.9.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.1
 [0.9.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.0
 [0.8.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.8.0
 [0.7.4]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.4

package/README.md

@@ -167,7 +167,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.2/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.3/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/core/archive.d.ts

@@ -0,0 +1,59 @@
+import type { RedRecord } from './red-record.js';
+/** One archived change folder, as this module found it. */
+export interface ArchivedChange {
+    /** The folder name, `<YYYY-MM-DD>-<changeName>` as `--apply` spelled it. */
+    readonly name: string;
+    /**
+     * The folder relative to the project root, through `relativePath`.
+     *
+     * Not `join`ed by a caller from {@link ArchivedChange.name}: a value derived
+     * from the root is spelled one way here or it becomes a report field and a
+     * comparison key that depends on the host platform (`paths.ts`).
+     */
+    readonly path: string;
+    /**
+     * What this change's `first-run.json` holds, or an empty record.
+     *
+     * Empty covers both "the folder carries no record" and "the record did not
+     * validate", which `readRedRecordIn` does not distinguish — deliberately, and
+     * the same way round as the gate: an unreadable record is exactly as strict
+     * as a missing one. Kept per change rather than only merged so a caller can
+     * say which folders contributed nothing, which is the difference between a
+     * report and an assertion about an archive nobody counted.
+     */
+    readonly firstRun: RedRecord;
+}
+/** Everything `archive/` says about first runs, and where it said it. */
+export interface ArchivedEvidence {
+    /** Every archived change folder, in folder-name order. */
+    readonly changes: readonly ArchivedChange[];
+    /** Their records merged. See {@link keepOutcome} for the precedence. */
+    readonly firstRun: RedRecord;
+}
+/**
+ * Read every archived change folder under `root`.
+ *
+ * A missing `archive/` is an empty list rather than an error: a project that has
+ * archived nothing is the normal state, and it is the state every project starts
+ * in. Directories only — a symbolic link is not followed, because this walks a
+ * tree to report on it and following one would let a link decide which files a
+ * report describes.
+ *
+ * Ordered by folder name, which is `<date>-<name>` and so is chronological, and
+ * through the same code-unit comparator as everything else this tool commits or
+ * compares — the report is then a function of the input rather than of the order
+ * a filesystem happened to hand back.
+ */
+export declare function readArchivedChanges(root: string): Promise<ArchivedChange[]>;
+/**
+ * The archive's first-run evidence, merged across every archived change.
+ *
+ * One `RedRecord` rather than a list to search, because the three questions a
+ * caller has of it are the three `recordedOutcome` already answers, at the
+ * granularity the gate leaves open: this scenario was observed failing; this
+ * scenario's id never came through the workflow; this id did and this scenario
+ * is not in it. Merging costs nothing else — the reader, the validator and the
+ * accessors are the ones the gate uses, unchanged.
+ */
+export declare function readArchivedEvidence(root: string): Promise<ArchivedEvidence>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/core/archive.js

@@ -0,0 +1,142 @@
+// The read side of `archive/`, which until now had none.
+//
+// `--apply` moves a change folder whole into `archive/<date>-<name>/`
+// (`merge.ts`), carrying `proposal.md`, the delta and `first-run.json` — why the
+// change was agreed, every id it touched, and the recorded failing run behind
+// each one it ADDed. Nothing read any of it back: `archive` is in `locate.ts`'s
+// scan exclusions, in `runner.ts`'s child-run exclusions and in `pipeline.ts`'s.
+//
+// **Those exclusions stay exactly as they are.** They are design §7 and §8 — an
+// archived change's requirements and specs must not re-enter a normal run — and
+// nothing here relaxes them. This module walks `archive/` on its own terms, for
+// facts *about* archived changes rather than to fold their contents back into a
+// registry or a plan.
+//
+// **Only `first-run.json` is read, and that is a selection rather than a first
+// instalment.** It is the typed half: a `RedRecord` in a versioned envelope,
+// schema-validated on read and discarded whole if it does not parse
+// (`red-record.ts`). `proposal.md` is prose, and in this repository it is a
+// pointer — `CLAUDE.md` makes `CHANGELOG.md` the single decision record, so a
+// proposal restating an argument would be a second store of it with nothing
+// comparing the two. There is nothing in the prose half for an index to offer
+// but its path.
+//
+// **What the merged record is for.** Design §11 records that the never-red
+// guarantee is a property of the `changes/` workflow, not of the registry as a
+// whole, so nothing else in the tool can say across a project which scenarios
+// were ever observed failing. Note the granularity: the gate blocks on *every*
+// scenario of an ADDED id (`gate.ts`), so asking this per requirement comes back
+// yes for every archived id and answers nothing. Where the gate genuinely stops
+// is one level down — a scenario grown onto a requirement after it archived
+// carries no obligation, because `never-red` fires only on ids a change is
+// currently ADDing, and MODIFIED carries no such obligation at all. Those are
+// the absences this record makes visible, and a `RedRecord` answers them
+// directly: an id absent from it never came through the workflow, while an id
+// present without a given scenario is one that did and then drifted.
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { byCodeUnit } from './order.js';
+import { relativePath } from './paths.js';
+import { keepOutcome, readRedRecordIn } from './red-record.js';
+/** The directory archived changes are moved into, under the project root. */
+const ARCHIVE_DIR = 'archive';
+/**
+ * Read every archived change folder under `root`.
+ *
+ * A missing `archive/` is an empty list rather than an error: a project that has
+ * archived nothing is the normal state, and it is the state every project starts
+ * in. Directories only — a symbolic link is not followed, because this walks a
+ * tree to report on it and following one would let a link decide which files a
+ * report describes.
+ *
+ * Ordered by folder name, which is `<date>-<name>` and so is chronological, and
+ * through the same code-unit comparator as everything else this tool commits or
+ * compares — the report is then a function of the input rather than of the order
+ * a filesystem happened to hand back.
+ */
+export async function readArchivedChanges(root) {
+    const dir = join(root, ARCHIVE_DIR);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const names = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort(byCodeUnit);
+    return Promise.all(names.map(async (name) => {
+        const path = join(dir, name);
+        return { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
+    }));
+}
+/**
+ * The archive's first-run evidence, merged across every archived change.
+ *
+ * One `RedRecord` rather than a list to search, because the three questions a
+ * caller has of it are the three `recordedOutcome` already answers, at the
+ * granularity the gate leaves open: this scenario was observed failing; this
+ * scenario's id never came through the workflow; this id did and this scenario
+ * is not in it. Merging costs nothing else — the reader, the validator and the
+ * accessors are the ones the gate uses, unchanged.
+ */
+export async function readArchivedEvidence(root) {
+    const changes = await readArchivedChanges(root);
+    return { changes, firstRun: mergeRecords(changes.map((c) => c.firstRun)) };
+}
+/**
+ * Fold records into one, `fail` winning.
+ *
+ * The precedence is `keepOutcome`'s and is order-independent, so nothing here
+ * depends on the order `readArchivedChanges` returned — which matters because
+ * one id can legitimately appear in two archived changes (removed, then added
+ * again) and neither folder's date makes its observation the truer one.
+ *
+ * Built into prototype-free maps at every level for the reason `red-record.ts`
+ * gives at length: the keys are requirement ids, paths and scenario names read
+ * off disk, and evidence that can be inherited is not evidence. The records
+ * being merged already have no prototype; the container this builds must not
+ * reintroduce one.
+ */
+function mergeRecords(records) {
+    const merged = Object.create(null);
+    for (const record of records) {
+        for (const [reqId, byFile] of Object.entries(record)) {
+            const files = (merged[reqId] ??= Object.create(null));
+            for (const [file, outcomes] of Object.entries(byFile)) {
+                const kept = (files[file] ??= Object.create(null));
+                for (const [name, outcome] of Object.entries(outcomes)) {
+                    kept[name] = keepOutcome(kept[name], outcome);
+                }
+            }
+        }
+    }
+    return sortRecord(merged);
+}
+/**
+ * Rebuild the record in key order at every level.
+ *
+ * The same byte-stability rule `mergeRedRecord` and `render` follow: two
+ * machines reading one archive produce one document, so key order has to be a
+ * function of the data rather than of insertion. `sortDeep` is not used because
+ * it would have to be told these containers must stay prototype-free.
+ */
+function sortRecord(record) {
+    const sorted = Object.create(null);
+    for (const reqId of Object.keys(record).sort(byCodeUnit)) {
+        const byFile = record[reqId];
+        const files = Object.create(null);
+        for (const file of Object.keys(byFile).sort(byCodeUnit)) {
+            const outcomes = byFile[file];
+            const names = Object.create(null);
+            for (const name of Object.keys(outcomes).sort(byCodeUnit))
+                names[name] = outcomes[name];
+            files[file] = names;
+        }
+        sorted[reqId] = files;
+    }
+    return sorted;
+}
+//# sourceMappingURL=archive.js.map

package/dist/core/red-record.d.ts

@@ -1,5 +1,19 @@
 import type { AttestPlan, Outcome, RunResult, ScenarioRef } from './types.js';
-/** Where the record lives, relative to the project root. */
+/**
+ * Where the record lives inside a change folder, wherever that folder is.
+ *
+ * **The unit is the folder, not the project plus a name**, because `--apply`
+ * moves the folder whole into `archive/<date>-<name>/` (`merge.ts`) and this
+ * file travels inside it. An archived record is therefore the same file at a
+ * different path, not a different format — so a reader spelled `root` +
+ * `changeName` could not reach it, and that is exactly where the reading side
+ * stopped: the archive is written and nothing reads it back.
+ *
+ * The two spellings below are the two places a change folder is, and they are
+ * the whole of the difference.
+ */
+export declare function redRecordPathIn(changeDir: string): string;
+/** Where the record lives for a change still in flight, from the project root. */
 export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
@@ -34,6 +48,16 @@ export type RedRecord = Record<string, Record<string, Record<string, Outcome>>>;
  * the whole one.
  */
 export declare function readRedRecord(root: string, changeName: string): Promise<RedRecord>;
+/**
+ * The same read, against a change folder given directly.
+ *
+ * Every rule in the comment above is this function's; `readRedRecord` is the
+ * in-flight spelling of it. Split out rather than parameterised on a directory
+ * name because an archived folder is not a variant of `changes/` — it is the
+ * same folder after `--apply` moved it, and naming the folder says so where a
+ * `'changes' | 'archive'` argument would invite a caller to pick.
+ */
+export declare function readRedRecordIn(changeDir: string): Promise<RedRecord>;
 /**
  * What the record says about one scenario, or undefined if it never saw it.
  *
@@ -54,6 +78,21 @@ export declare function recordedOutcome(record: RedRecord, ref: ScenarioRef): Ou
  * `uncoveredIssues` from the commands that had a copy each.
  */
 export declare function hasRecordedRed(record: RedRecord, ref: ScenarioRef): boolean;
+/**
+ * Which of two observations of one scenario the record keeps.
+ *
+ * **Monotonic toward `fail`**: a recorded fail is final, a recorded pass can
+ * still be corrected by a real one. The reasoning is at the top of this file;
+ * what is here is the one place it is decided, because two callers now decide
+ * on it — a run being folded into a change's record, and two records being
+ * merged. A second spelling of `=== 'fail'` would let them disagree about what
+ * the same pair of observations means, which is the argument that gave
+ * `hasRecordedRed` its single definition.
+ *
+ * Order-independent by construction — `keepOutcome(a, b)` and `keepOutcome(b, a)`
+ * agree — so a caller merging many records owes no sequencing rule.
+ */
+export declare function keepOutcome(existing: Outcome | undefined, incoming: Outcome): Outcome;
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.

package/dist/core/red-record.js

@@ -97,9 +97,35 @@ function fileKey(file) {
 function emptyMap() {
     return Object.create(null);
 }
-/** Where the record lives, relative to the project root. */
+/**
+ * Where the record lives inside a change folder, wherever that folder is.
+ *
+ * **The unit is the folder, not the project plus a name**, because `--apply`
+ * moves the folder whole into `archive/<date>-<name>/` (`merge.ts`) and this
+ * file travels inside it. An archived record is therefore the same file at a
+ * different path, not a different format — so a reader spelled `root` +
+ * `changeName` could not reach it, and that is exactly where the reading side
+ * stopped: the archive is written and nothing reads it back.
+ *
+ * The two spellings below are the two places a change folder is, and they are
+ * the whole of the difference.
+ */
+export function redRecordPathIn(changeDir) {
+    return join(changeDir, RED_RECORD_FILE);
+}
+/** Where the record lives for a change still in flight, from the project root. */
 export function redRecordPath(root, changeName) {
-    return join(root, 'changes', changeName, RED_RECORD_FILE);
+    return redRecordPathIn(inFlightChangeDir(root, changeName));
+}
+/**
+ * The folder a change occupies before it is archived.
+ *
+ * One spelling, because both public entry points below would otherwise carry a
+ * copy of `'changes'` and they must not be able to disagree about where a
+ * record is read from versus where a diagnostic says it is.
+ */
+function inFlightChangeDir(root, changeName) {
+    return join(root, 'changes', changeName);
 }
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export const RED_RECORD_FILE = 'first-run.json';
@@ -132,9 +158,21 @@ const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.record(z.str
  * the whole one.
  */
 export async function readRedRecord(root, changeName) {
+    return readRedRecordIn(inFlightChangeDir(root, changeName));
+}
+/**
+ * The same read, against a change folder given directly.
+ *
+ * Every rule in the comment above is this function's; `readRedRecord` is the
+ * in-flight spelling of it. Split out rather than parameterised on a directory
+ * name because an archived folder is not a variant of `changes/` — it is the
+ * same folder after `--apply` moved it, and naming the folder says so where a
+ * `'changes' | 'archive'` argument would invite a caller to pick.
+ */
+export async function readRedRecordIn(changeDir) {
     let raw;
     try {
-        raw = await readFile(redRecordPath(root, changeName), 'utf8');
+        raw = await readFile(redRecordPathIn(changeDir), 'utf8');
     }
     catch {
         return emptyMap();
@@ -218,6 +256,23 @@ export function recordedOutcome(record, ref) {
 export function hasRecordedRed(record, ref) {
     return recordedOutcome(record, ref) === 'fail';
 }
+/**
+ * Which of two observations of one scenario the record keeps.
+ *
+ * **Monotonic toward `fail`**: a recorded fail is final, a recorded pass can
+ * still be corrected by a real one. The reasoning is at the top of this file;
+ * what is here is the one place it is decided, because two callers now decide
+ * on it — a run being folded into a change's record, and two records being
+ * merged. A second spelling of `=== 'fail'` would let them disagree about what
+ * the same pair of observations means, which is the argument that gave
+ * `hasRecordedRed` its single definition.
+ *
+ * Order-independent by construction — `keepOutcome(a, b)` and `keepOutcome(b, a)`
+ * agree — so a caller merging many records owes no sequencing rule.
+ */
+export function keepOutcome(existing, incoming) {
+    return existing === 'fail' ? 'fail' : incoming;
+}
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.
@@ -259,11 +314,10 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
             continue;
         const forId = (record[s.reqId] ??= emptyMap());
         const forFile = (forId[fileKey(s.file)] ??= emptyMap());
-        // Monotonic toward `fail`: a recorded fail is final, a recorded pass can
-        // still be corrected by a real one. See the note at the top of this file.
-        if (forFile[s.name] === 'fail' || forFile[s.name] === outcome)
+        const kept = keepOutcome(forFile[s.name], outcome);
+        if (kept === forFile[s.name])
             continue;
-        forFile[s.name] = outcome;
+        forFile[s.name] = kept;
         changed = true;
     }
     // Sort within each requirement, and within each file, for the same

package/dist/core/skill.js

@@ -318,6 +318,14 @@ blocks the gate with the suite fully green; so does a spec file that will not
 import, or a proposed spec no delta claims. A clean table plus green tests is
 still not a verdict — \`attest archive\` is the only thing that decides.
 
+**Three questions before you present it**, each a category no diagnostic reports:
+
+- **What pins each expectation** — a fixture, a literal, an independently
+  derived value; never the param the code under test consumed?
+- **Does each statement carry one obligation**, or several under one SHALL?
+- **Was any of this ever red**, or does part of it already work? \`never-red\`
+  asks for a recorded failing run only on the ids you ADD.
+
 Then present the proposal, the ids, and the red output, and **stop**. Wait for
 agreement before implementing.
 

package/dist/inspect.d.ts

@@ -51,4 +51,96 @@ export interface Inspection {
  * not ours to choose.
  */
 export declare function inspectProject(root: string): Promise<Inspection>;
+/**
+ * What the archived first-run records say about one scenario a spec declares.
+ *
+ * Four values, not two, and the two absences are the reason. `'fail'` and
+ * `'pass'` are the record's own outcomes, spelled the same so a caller
+ * comparing against `'fail'` is comparing against the string the gate compares
+ * against. The other two are both "no observation", and folding them together
+ * would report a design working as intended as if it were a defect:
+ *
+ * - `'unarchived'` — this scenario's requirement appears in no archived change
+ *   at all. It was written straight into the registry, which is how existing
+ *   behaviour is described in a brownfield adoption, and it carries **no**
+ *   obligation to have been red. Nothing is wrong.
+ * - `'unobserved'` — the requirement *is* archived and this scenario is not in
+ *   the record. It was added after the change was archived, and nothing will
+ *   ever require it to have failed first: the gate raises `never-red` only for
+ *   ids a change is currently ADDing, and an archived id is ADDed by nothing
+ *   again. This is the one no gate can see.
+ *
+ * `'pass'` is a state the gate cannot produce — it blocks a change whose
+ * scenario passed on its first run — so an archived `'pass'` means the record
+ * was hand-edited or written by a format that has since moved. Reported rather
+ * than folded into the absences, because the fix is different.
+ *
+ * Attest computes which of the four holds and stops there. Whether an
+ * `'unobserved'` scenario matters is a judgement about that scenario, which is
+ * the caller's (design §0).
+ */
+export type ScenarioEvidence = 'fail' | 'pass' | 'unobserved' | 'unarchived';
+/** One declared scenario, and what the archive records about it. */
+export interface EvidenceRow {
+    readonly reqId: string;
+    /** The spec file, relative to the root and POSIX-spelled, as {@link ParsedScenario} spells it. */
+    readonly file: string;
+    readonly name: string;
+    readonly line: number;
+    readonly evidence: ScenarioEvidence;
+}
+/** An archived change folder the evidence was read from. */
+export interface ArchivedChangeRef {
+    /** The folder name, `<YYYY-MM-DD>-<change>`, as `archive --apply` spelled it. */
+    readonly name: string;
+    /** The folder relative to the root, POSIX-spelled. */
+    readonly path: string;
+}
+/** What {@link inspectRedEvidence} answers. */
+export interface RedEvidenceInspection {
+    /**
+     * One row per scenario declared under the root, in the order
+     * {@link Inspection.scenarios} lists them.
+     *
+     * Rows for *declared* scenarios rather than for recorded ones: the question is
+     * what today's suite can show about itself, so a record naming a scenario no
+     * spec declares any more contributes nothing here. It is not lost — the folder
+     * it came from is in {@link RedEvidenceInspection.archived} — but a row about
+     * a scenario that no longer exists is not something a caller can act on.
+     */
+    readonly scenarios: readonly EvidenceRow[];
+    /**
+     * Every archived change folder that was read, in folder-name order.
+     *
+     * Provenance, and it is load-bearing: an empty list means the project has
+     * archived nothing, in which case every row is `'unarchived'` and the report
+     * says nothing about the project rather than something bad about it.
+     */
+    readonly archived: readonly ArchivedChangeRef[];
+    /** Everything that stopped a file being read, exactly as {@link Inspection.issues}. */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export declare function inspectRedEvidence(root: string): Promise<RedEvidenceInspection>;
 //# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -24,7 +24,9 @@
 // `tests/import-boundary.spec.ts` gates that rather than leaving it to review —
 // this module is on the short list of entry points whose closure is walked.
 import { resolve } from 'node:path';
+import { readArchivedEvidence } from './core/archive.js';
 import { loadRegistry, parseSpecs, scanProject, staticReader } from './core/locate.js';
+import { recordedOutcome } from './core/red-record.js';
 /**
  * Read the requirements and scenarios declared under `root`, executing nothing.
  *
@@ -65,4 +67,57 @@ export async function inspectProject(root) {
         issues: [...loaded.issues, ...parsed.issues],
     };
 }
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export async function inspectRedEvidence(root) {
+    const projectRoot = resolve(root);
+    // Sequential rather than concurrent, unlike the two reads inside
+    // `inspectProject`: this is one tree walk after another over the same disk,
+    // and the archive holds only the folders of changes already merged — so
+    // overlapping them buys nothing worth a second fan-out.
+    const inspection = await inspectProject(projectRoot);
+    const { changes, firstRun } = await readArchivedEvidence(projectRoot);
+    const scenarios = [];
+    for (const [reqId, declared] of inspection.scenarios) {
+        // Own property only, and the distinction the two absences rest on: an id
+        // the archive never mentions is a different fact from an id it mentions
+        // without this scenario.
+        const archived = Object.hasOwn(firstRun, reqId);
+        for (const s of declared) {
+            const outcome = recordedOutcome(firstRun, { reqId, file: s.file, name: s.name });
+            scenarios.push({
+                reqId,
+                file: s.file,
+                name: s.name,
+                line: s.line,
+                evidence: outcome ?? (archived ? 'unobserved' : 'unarchived'),
+            });
+        }
+    }
+    return {
+        scenarios,
+        archived: changes.map((c) => ({ name: c.name, path: c.path })),
+        issues: inspection.issues,
+    };
+}
 //# sourceMappingURL=inspect.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {