@am_shork/attest 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -5,92 +5,300 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Versioning
+
+Under 0.x SemVer a breaking change bumps the **minor**. "Breaking" means it
+changes the exit code of an existing valid setup, rejects previously-valid
+input, removes/renames a public API or `--json` field, or changes a default
+runtime behavior an existing invocation relies on — diagnostic message text is
+not API.
+
 ## [Unreleased]
 
-### Under consideration (non-breaking, not implemented)
+## [0.2.0] - 2026-07-26
+
+Three things that could each end a run with the wrong verdict: a registry read
+by executing it, a green that attested nothing, and a red about code Attest was
+never pointed at.
+
+### Security
+
+- **`attest check` described itself as static validation while executing every
+  `*.reqs.ts` it found.** Reading a registry meant evaluating the module, via
+  Vite, anywhere under the project root — the same threat model as
+  `vitest run`, behind wording ("static structural validation (fast CI
+  pre-check)") that is exactly what gets a command scheduled ahead of, or
+  outside, whatever sandbox the test run is given. On a fork MR, a `*.reqs.ts`
+  with a top-level `fetch` was enough to reach CI secrets.
+  `check`, `cover` and `render` now read the registry from the **AST** — the
+  compiler API was already the parser layer's tool — and run no line of the
+  project. `verify` and `archive` still evaluate: they run the whole suite
+  anyway, so declining to run one more module would buy them nothing.
+  The extracted object literal is handed to the same `RegistrySchema`
+  `defineRequirements` calls, so a literal registry keeps its behaviour, its
+  codes and its diagnostic wording unchanged. That equivalence is not an
+  assertion: a differential suite reads every `*.reqs.ts` in the repo, and every
+  literal form that could be misread (`-1`, `1_000`, `0x10`, `30.0`, `1e3`, a
+  template literal with no substitution, `as const`, `satisfies`), through both
+  readers and requires the two registries to be deeply equal — down to key
+  order.
+  It also turns `render`'s purity from a convention into a structural
+  guarantee: a registry can no longer contain a `Date.now()` that makes
+  `render --check` fail forever.
+
+### Changed
+
+- **BREAKING: a registry must be a literal.** A registry `check`, `cover` or
+  `render` cannot read from the source is a new `registry-not-static` ERROR,
+  pointing at the line that stopped it. There is deliberately no fallback to
+  evaluation — a reader that quietly runs the file when extraction fails
+  guarantees nothing — and deliberately no warning period, which would spend
+  the whole transition still evaluating. `--eval` is the named way back, on all
+  three commands, and restores the old behaviour exactly.
+  This makes "a registry is a literal" a design contract rather than a tooling
+  limitation: `params: { maxMb: MAX_MB }` imported from application code already
+  violates the single-source rule the framework exists to enforce, because the
+  value's real owner is elsewhere. Affected repos have two migrations, and
+  inlining the value is the one that fixes the underlying problem.
+  A registry file may still be written as `const reqs = defineRequirements({…});
+  export default reqs;`, and may import `defineRequirements` under any alias or
+  through a namespace.
+  The `--json` envelope is unchanged: `registry-not-static` is a new `code` on
+  the existing `Issue` shape, which is additive, so `schemaVersion` stays `1`.
+  `vite` remains a peer dependency — `verify` and `archive` run the suite through
+  it — but `check`, `cover` and `render` no longer start a Vite server at all.
+- **BREAKING: a vacuous green stops passing.** `attest verify` on a root with no
+  requirements printed `✓ No issues.` and exited `0`, because `passed` is "no
+  failing tests" and a run with nothing in it has none. It is now an `empty-spec`
+  ERROR, so `ok` becomes false and the exit code follows the existing `hasError`
+  path. The empty directory is the harmless version; the one that matters is the
+  repo whose registry stopped being found — a renamed folder, a moved root — where
+  the tests still run, still pass, and the report is indistinguishable from a real
+  green. Deliberately narrower than "no scenario executed": with at least one
+  requirement, a missing scenario is already `uncovered-requirement` and a declared
+  scenario that never ran is already `declared-not-run`, so firing on those would
+  only double-report a run that is red anyway. *Breaking:* a root that attests
+  nothing flips from exit 0 to exit 1 — which is the point, since it attested
+  nothing.
+- **BREAKING: a run executes only the spec files that declare a `requirement()`.**
+  `verify` swept every `*.spec.ts` under the root into a child run with no
+  aliases, no DOM and no plugins, so pointing it at the root of a repo that
+  already had a suite produced a guaranteed red about code Attest was never asked
+  to attest. That was the first thing a mid-project adopter saw, and it was not a
+  finding about their intent layer at all. The run scope is now derived from the
+  static plan, which already records which files declare intent. `archive` gets
+  the same scope, for the same reason: a change must not fail its gate because an
+  unrelated suite shares its root. *Breaking:* a repo relying on the sweep to run
+  requirement-less specs sees a different set execute — and `attest` was never the
+  right thing to run them with. Unchanged for `check`, `cover` and `render`, which
+  only ever counted `requirement()`/`scenario()` calls and so never had the bug.
+
+### Added
+
+- **`verify` reports what it looked at.** The human summary leads with
+  `— 20 requirements / 41 scenarios, 0 error, …` and is preceded by the run
+  scope (`Running 12 spec files`, plus how many were located and skipped for
+  declaring no `requirement()`). `--json` carries the same four numbers under
+  `counts`. This is the companion the change above needs: scoping the run means a
+  file whose `requirement()` the parser fails to see is now dropped from the run
+  rather than failing in it, and the gap between "located" and "in scope" is where
+  that would show. It is also a second line of defence against a vacuous green — a
+  report that says `0 requirements` cannot be misread as a full pass. `counts` is
+  a new optional field on an existing envelope, so `schemaVersion` stays `1`.
+
+### Fixed
+
+- **The design document described three anti-drift mechanisms; two exist.**
+  §6's mechanism 2, "red/green expectation tracking" — a new requirement's
+  scenarios must be red while a change is in progress and green at archive time,
+  with the framework blocking on a mismatch — was written as shipped behaviour,
+  with a strength rating, next to two mechanisms that are real. It was never
+  built. What ships is the weaker half: §8's gate requires green at archive time,
+  but nothing records or requires the earlier red, so a scenario that was green
+  from the start — asserting nothing — passes it. Anyone who budgeted their own
+  review against three mechanisms was covered by two. Now marked
+  **(not implemented)** inline, with the gap named. Same treatment for
+  `/atx:propose` and `/atx:apply` in §9, which are likewise designed and unbuilt;
+  the manual path (`changes/<name>/` + `attest archive`) is spelled out beside
+  them.
+- **Documentation described an API that does not exist.** §1's architecture
+  diagram — the first thing a reader meets — showed `@covers('AUTH-3')` and a
+  `covers(id)` back-link, an early spelling of what shipped as
+  `requirement(id)` / `scenario(name)`, with coverage reconstructed from the
+  `[reqId]` suite name. §5.4 already described the real mechanism, so the
+  document contradicted itself. The registry and spec samples also imported from
+  a bare `'attest'`, and §10 declared the package as `attest` exporting only
+  `.` — the published package is `@am_shork/attest` and has exported `./define`
+  since 0.1.2, which is the import path README tells users to write. These are
+  samples meant to be copied, and this repo's docs are also fed to agents, so a
+  stale name becomes generated code.
+- **Smaller documentation corrections.** §1 called its own three-row table "the
+  two core reports"; the Coverage row attributed coverage to runtime collection
+  alone, when `check`/`cover` read it statically. §4 listed the SHALL/MUST rule
+  under structural validation, where it is enforced by the schema one layer up.
+  §5.3's `Issue` sample omitted the `reqId` field the same snippet sets. §7
+  cited "§6" for a section of OpenSpec's analysis, not this document's §6.
+  The README's `--json` sample claimed `"version": "0.1.2"`, and its
+  prerequisites section was headed "Requirements" — a term this project already
+  uses for the intent layer.
+- **The feedback template and the GitLab issue template each claimed to be the
+  other.** They are not identical, and should not be: `outcome:` is for
+  maintainer-authored reports and `verdict:` for outside ones, so the issue form
+  is deliberately the outside-reporter subset. Both now say so, the key rule is
+  stated where it can be read, and the issue form gained the mid-project
+  follow-up its own `adoption: brownfield` field was asking for and never posed.
+
+Two checks now hold the parts of this that can be held mechanically, in
+`tests/docs-consistency.spec.ts`: the source cites design sections by number in
+58 places, and every citation must resolve in both languages, so inserting a
+section can no longer silently repoint them; and any JSON sample in the README
+that identifies itself as attest output must carry the current `version` and
+`schemaVersion`. Neither can catch a section that describes something unbuilt —
+that is what the inline marker is for.
+
+## Considered and rejected
+
+Decisions **not** to build something, kept where they can be found before the
+same candidate is proposed again. Nothing here shipped, so nothing here belongs
+to a release — this section is deliberately outside the version history and does
+not move when one is cut.
 
 - **Two gaps in the intent layer: nothing resists a bloated requirement, and
-  nothing resists a duplicated one.** Recorded as a design note, with the
-  evidence that currently blocks each candidate fix.
-  *Against bloat, what already works:* `uncovered-requirement` being an ERROR is
-  the real mechanism — every requirement costs an executable scenario, so "the
-  system should be maintainable" cannot be written and left standing. That is a
-  genuine cost function on the intent layer, which prose SDD does not have.
-  *What doesn't:* coverage is binary (≥1 scenario), so five sharp requirements
-  cost five mandatory scenarios while one requirement lumping five obligations
-  together costs one. **The rule as designed rewards lumping**, and the engine
-  has no notion of "one requirement = one obligation". Attest's own registry
-  shows it: `ATX-5` carries two obligations under one SHALL, `ATX-9` three
-  clauses, `ATX-10` two.
-  *Against duplication and contradiction:* effectively nothing. Every
-  cross-requirement check in the engine is keyed on the **id** —
-  `duplicate-requirement` (same id in two registry files), `rename-target-exists`,
-  and `add-conflict`, which content-compares only when ids collide. Two
-  requirements under different ids that contradict each other (`AUTH-3` expires a
-  session after 30 minutes, `SESS-7` says sessions never expire) pass schema,
-  `check`, `verify` and the archive gate, each green under its own scenario.
-  `params` does not help, and the reason is structural: it is an
-  **intra-requirement** mechanism. It pins one requirement's statement to its own
-  assertions; two requirements may each own a `params` entry of the same name with
-  different values and both stay green. Design §11 admits semantic drift needs
-  human review — semantic *duplication* is the same category and is not mentioned
-  at all. This matters most in the workflow the package exists for: an agent asked
-  for a new behaviour is additive by default, and will add `SESS-7` rather than
-  `modified: { 'AUTH-3': … }`. The delta workflow provides the correct path; it
-  does not force it, and the one counter-pressure (a new requirement costs a
-  scenario) does not deter an agent that will happily write one.
-  *Candidate 1 — `divergent-param` (WARNING):* the same param name declared in
-  more than one requirement with different values, scoped to a shared id prefix
-  (`AUTH-*` vs `AUTH-*`) to limit collisions between unrelated domains. It would
-  not detect abstract contradiction, only its most common concrete form: one named
-  constant pinned twice, differently. **Blocked, and by this repo's own registry:**
-  `idleTimeoutMin` is `15` in `ATX-3` and `30` in `ATX-10`, both under the same
-  prefix, and both legitimate — unrelated illustrative fixtures. So the false
-  positive is not hypothetical, and prefix scoping does not save a repo that uses
-  one prefix throughout. The mechanism needs a way to declare two params
-  independent before it can ship, and that escape hatch is undesigned.
-  *Candidate 2 — `compound-requirement` (WARNING):* more than one RFC-2119
-  keyword in a single `statement` is objectively more than one obligation, which
-  directly opposes the lumping incentive above. Cheap and deterministic, but its
-  reach is narrow: over the 12 self requirements it flags exactly one (`ATX-10`,
-  `SHALL … and MUST …`) and misses both `ATX-5` and `ATX-9`, which pack multiple
-  clauses under a single keyword.
-  *Explicitly rejected:* similarity matching between statements (token overlap,
-  embeddings). That reintroduces the fuzzy AI comparison design §0 exists to
-  remove. Real semantic duplication needs judgement and belongs to human review
-  at the propose stage; the engine should not pretend to prove it.
-  Both candidates are WARNING-level, so neither would change the exit code of an
-  existing valid setup (only ERROR fails a run) — they are listed here rather than
-  under 0.2.0 for that reason.
-
-The breaking items below are held for **0.2.0** (under 0.x SemVer a breaking
-change bumps the minor). "Breaking" means it changes the exit code of an existing
-valid setup, rejects previously-valid 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.
-
-### Planned for 0.2.0 (breaking)
-
-- **A vacuous green stops passing.** Today `attest verify` on a spec that ran no
-  scenarios (an empty or requirement-less directory) prints
-  `✓ No issues. — 0 error, …` and exits `0`, because `runAndCollect` reads "no
-  failing tests" as `passed`. `verify` will instead emit a new `empty-spec`
-  ERROR when zero scenarios executed (or the registry has zero requirements),
-  so `ok` becomes `false` and the exit code follows the existing `hasError`
-  path. Wires up `hasSpecs()` (present in `pipeline.ts`, never called today).
-  *Breaking:* an "empty directory → exit 0" run flips to exit 1 — which is the
-  point, since that run attests nothing. *Non-breaking companion (may land
-  earlier in 0.1.x):* requirement/scenario counts in the summary line
-  (`— 33 requirements / 59 scenarios, 0 error, …`).
-- **Default spec discovery ignores files with no `requirement()`.** `verify` at
-  a repo root currently sweeps every `**/*.spec.ts` — including a pre-existing
-  suite — into a runner with no aliases/DOM, a guaranteed red unrelated to the
-  code. The default will change to run only spec files that declare at least one
-  `requirement()`, so an incumbent suite is left untouched without forcing a
-  directory layout. *Breaking:* a repo relying on the root scan to pick up
-  requirement-less specs sees a different set run. *Non-breaking companion (may
-  land earlier in 0.1.x):* a pre-run report of how many spec files were located
-  and how many contain a `requirement()` call.
+  nothing resists a duplicated one.** The gaps themselves are described in design
+  §11, which is where a permanent property of the design belongs. What is kept
+  here is the list of mechanisms tried and what killed each, so the same three
+  are not proposed again without new evidence. All three were scored against
+  every registry this repo ships *before* any was written into the engine — the
+  order `divergent-param` was originally designed in the wrong way round. The
+  measurement is runnable in `tests/intent-rule-candidates.spec.ts` and fails
+  when a requirement is added without a hand-labelled obligation count, because
+  the reach figure once quoted here went stale exactly that way.
+  *`compound-requirement` (WARNING) — rejected.* More than one RFC-2119 keyword
+  in one `statement` is objectively more than one obligation. Measured: of the 6
+  requirements in the corpus carrying more than one, it flags 1 (`ATX-10`) and
+  misses `ATX-5`, `ATX-9`, `ATX-13`, `ATX-14`, `ATX-17` — every one that packs
+  clauses under a single keyword, which is the form the coverage incentive
+  actually rewards. A wider variant (keyword plus a coordinating `and`/`while`/
+  `;`) reaches 5 of 6 with one wrong hit, so reach is not the deciding argument.
+  This is: both variants are silenced by deleting the word that triggered them,
+  and neither can tell that deletion from a real split. `SHALL do A and MUST do
+  B` clears the warning as `SHALL do A and do B` — same two obligations, one
+  fewer normative keyword. A rule whose cheapest fix degrades the artifact it
+  protects does not ship.
+  *`divergent-param` (WARNING) — rejected.* One param name declared with
+  different values in two requirements sharing an id prefix. Measured: it fires
+  twice on this repo and both firings are wrong — `idleTimeoutMin` (`15` in
+  `ATX-3`, `30` in `ATX-10`), unrelated illustrative fixtures, and `code`
+  (`registry-not-static` in `ATX-17`, `empty-spec` in `ATX-18`), two diagnostics
+  that could not possibly agree. The second arrived on its own when `ATX-18` was
+  added, which is the more damning half: a generic param name collides more often
+  as a registry grows, so the false-positive rate rises with adoption — the
+  opposite of what a shippable rule does. Still zero true positives across 24
+  requirements. The escape hatch it was blocked on has since been designed
+  and does not rescue it: with no config file the only workable shape is an
+  additive `independentParams?: string[]` on the requirement (a CLI flag is
+  per-invocation for what is a permanent property of two requirements; changing
+  the `params` shape rejects every existing registry). Viable, but it is
+  permanent schema surface for a rule with no demonstrated true positive, and in
+  practice it would be written *after* the warning fires — a one-line silencer.
+  *Countable obligations (breaking) — rejected.* An `obligations: string[]` per
+  requirement, with coverage counted per obligation, removing the lumping
+  incentive at the source instead of detecting it afterwards. Rejected because
+  the **id is already that unit**: splitting into two ids costs two scenarios and
+  buys the same incentive with no new concept (`ATX-11`/`ATX-12` are exactly that
+  split). It would touch the parser, coverage, `render`, `SPEC.md`, delta apply
+  and the `--json` schema, and it relocates the incentive rather than removing
+  it — nothing can force the array to be complete.
+  *Not considered:* similarity matching between statements (token overlap,
+  embeddings). That reintroduces the fuzzy comparison design §0 exists to remove;
+  real semantic duplication needs judgement and belongs to human review at the
+  propose stage.
+
+## [0.1.7] - 2026-07-26
+
+A change name, a prototype key and a collation quirk each got to decide a
+verdict; none of them do now.
+
+### Security
+
+- **`attest archive <change>` validated the change name only by using it.** The
+  name was interpolated straight into
+  `changes/<name>/requirements.delta.ts`, and that module is *executed* — while
+  path joining normalises `..`, so `attest archive '../../../tmp/evil'` loaded
+  and ran a module from outside `changes/` entirely. Harmless when you type it
+  yourself; not harmless the moment the name comes from a branch name or an MR
+  title, which is the natural way to wire the gate into CI. The name is now
+  checked **before a loader is even created** — a name already known to be
+  invalid must not cause a single resolution attempt — and rejected with a new
+  `invalid-change-name` ERROR.
+  The test is path safety, not a character whitelist: empty, `.`, `..`, or
+  anything containing a path separator or NUL is refused, and every other name a
+  directory may legitimately carry is admitted. A whitelist would have cost
+  adopters real change directories (`feat(auth)`, a name with a space) to buy no
+  additional safety, because the change name never reaches a glob.
+- **A sibling proposal with a glob metacharacter in its name silently widened
+  the archive gate.** The globs that keep *other* proposals out of a gate run
+  were built by pasting directory names read from disk straight into
+  `**/changes/<name>/**`. A change called `feat(auth)` is a *pattern*, so it
+  matched nothing, and that proposal's specs joined the run — quietly enlarging
+  the scope of the single check that decides whether a change is done. Sibling
+  names are now escaped.
+
+### Fixed
+
+- **A statement placeholder could bind to a prototype method instead of a
+  param.** Both the validator and the renderer probed with `name in req.params`,
+  and `'toString' in {}` is `true`. So `{toString}` in a statement looked bound:
+  the `unbound-param` ERROR that exists to stop an undeclared placeholder never
+  fired, and `render` then interpolated
+  `function toString() { [native code] }` into the document that reviewers and
+  audit read as the system's promise. Both now use `Object.hasOwn`, so the
+  intent layer resolves only to what an author actually wrote. An own param
+  whose name happens to shadow a prototype key keeps working.
+  *Behaviour change:* a registry with such a statement newly fails `check`, and
+  its rendering changes (the placeholder is now left verbatim), which
+  `render --check` reports as stale. Both are the reports that should always
+  have been there.
+- **The canonical form used for content comparison encoded the order params
+  happened to be written in.** `applyDelta` sorted param keys with
+  `localeCompare` before comparing, and `localeCompare` returns `0` for strings
+  that are *distinct* — a precomposed `ä` against its combining-mark spelling.
+  `Array#sort` is stable, so keys it called equal kept their insertion order,
+  and two requirements with identical content but differently ordered params
+  canonicalised differently: `add-conflict` reporting a requirement as
+  conflicting with an identical copy of itself. Which strings collate equal is
+  ICU-dependent on top of that, so the answer also varied with the Node build.
+  Ordering now goes through one shared code-unit comparator (`src/core/order.ts`),
+  which `render`'s id ordering — already code-unit for the same reason — now
+  shares.
+- **The loader never removed its scratch directory.** Every `attest`
+  invocation created one under the OS temp dir to hold the vitest stub, and
+  `close()` shut the Vite server without deleting it: one directory per CI
+  build, accumulating forever. `close()` now removes it, and is idempotent.
+
+### Changed
+
+- **`check` walked the project tree twice and `archive` four times**, over a
+  tree that cannot change in between. One traversal now collects registry and
+  spec files together (`scanProject`). Directory recursion, spec reads, and
+  registry module evaluation all run concurrently; results are folded in sorted
+  file order, so reports stay byte-identical regardless of I/O timing. The
+  drift heuristic indexes scenarios once instead of re-filtering the whole plan
+  per requirement, which was the product that grows fastest in exactly the repos
+  where `check` needs to stay fast.
+- **`verify` and `archive` now share one `declared-not-run` implementation.**
+  Each owned a verbatim copy, so the two verdicts agreed only by transcription —
+  in a tool whose entire argument is that agreement should be structural rather
+  than clerical.
+- `attest <cmd> [dir]` now resolves `[dir]` to an absolute path. A relative one
+  previously worked only because Vite happens to default its own root to the
+  current directory.
+- `render --out` writes through a temporary file and renames, so an interrupted
+  write can no longer leave a truncated document in a file that is meant to be
+  committed.
+
+No `schemaVersion` change: the report envelope and the `Issue` shape are
+untouched, and `invalid-change-name` is a new `code` value, which is additive.
 
 ## [0.1.6] - 2026-07-25
 
@@ -326,7 +534,9 @@ Initial release.
   (MIT), whose four-stage engine and diff-first change model Attest's
   architecture is adapted from (re-implemented from scratch, no source copied).
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.1.6...main
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.2.0...main
+[0.2.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.2.0
+[0.1.7]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.7
 [0.1.6]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.6
 [0.1.5]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.5
 [0.1.4]: https://gitlab.com/Pseudorca/attest/-/tags/v0.1.4

package/README.md

@@ -4,7 +4,7 @@ A TDD-native spec framework. **Tests are the source of truth for verification;
 ID-bound requirements are the source of truth for intent.** Attest binds the two
 by a stable ID and continuously detects drift.
 
-- **Coverage** — does every requirement have ≥1 scenario? (from runtime coverage)
+- **Coverage** — does every requirement have ≥1 scenario? (statically, or from the run)
 - **Result** — is every test green? (from the test runner)
 - **Drift** — do intent and assertions still agree? (static + runtime cross-check)
 
@@ -16,7 +16,7 @@ sets) get the same single source as a lone number.
 
 See the authoritative design — [English](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) · [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) — and the rest of the [docs](https://gitlab.com/Pseudorca/attest/-/tree/main/docs).
 
-## Requirements
+## Prerequisites
 
 - Node ≥ 20.19
 - pnpm, plus `vitest` + `vite` (peer dependencies)
@@ -30,7 +30,9 @@ pnpm add -D @am_shork/attest vitest vite
 ```
 
 **1. Declare a requirement** (`requirements/auth.reqs.ts`) — import the intent API
-from the vitest-free `/define` subpath so registry loading never touches the runtime:
+from the vitest-free `/define` subpath so registry loading never touches the runtime.
+A registry is a **literal**: every value is written where you can read it (see
+[A registry is a literal](#a-registry-is-a-literal)):
 
 ```ts
 import { defineRequirements } from '@am_shork/attest/define';
@@ -67,12 +69,52 @@ requirement('AUTH-3', () => {
 
 ```bash
 attest check    # static: orphan tests, uncovered requirements, unbound params
+                # (reads your registry; runs none of your code)
 attest verify   # run tests + coverage + drift, graded report
+                # (runs only the spec files that declare a requirement())
 attest cover    # which requirements lack a scenario
 attest render   # the requirements as Markdown, for people who don't read TS
 attest archive <change>   # gate a proposed change: green + covered + no drift
 ```
 
+`<change>` names one directory inside `changes/` — it cannot be empty, `.`,
+`..`, or contain a path separator, since the gate loads and runs that change's
+delta. Any other directory name is fine.
+
+### A registry is a literal
+
+`check`, `cover` and `render` read your `*.reqs.ts` files from their **source**,
+with the TypeScript compiler API. They never execute them. That is what makes
+`attest check` safe to run where its description implies you can — first in the
+pipeline, on an untrusted fork MR, outside whatever sandbox you give the tests.
+(`verify` and `archive` do run your suite, so they read the registry by
+evaluating it: there is nothing left to protect at that point.)
+
+The cost is a contract: every value in a registry must be written in the
+registry.
+
+```ts
+import { MAX_MB } from '../src/config.js';
+
+export default defineRequirements({
+  'UP-1': {
+    statement: 'An upload SHALL be rejected above {maxMb} MB.',
+    rationale: 'Protect the storage tier from unbounded writes.',
+    params: { maxMb: MAX_MB }, // ✗ registry-not-static
+  },
+});
+```
+
+This is reported as a `registry-not-static` ERROR pointing at the line. It is
+not only a tooling limit: the single-source rule says the requirement owns that
+number, and importing it says the application owns it. Inline the value and read
+it from the registry in your code — that is the fix. If you need the old
+behaviour instead, `--eval` restores it on all three commands:
+
+```bash
+attest check --eval    # reads the registry by executing every *.reqs.ts
+```
+
 ### A readable spec for humans (`attest render`)
 
 The intent layer lives in TypeScript, which means a reviewer, a QA engineer, or
@@ -110,6 +152,31 @@ Three properties this deliberately keeps:
 The Markdown is prose for humans and its formatting is not a stable contract —
 don't parse it. `--json` is the machine surface.
 
+### What a run actually runs
+
+`verify` executes **only the spec files that declare a `requirement()`**. A repo
+that already has a test suite keeps it: those files are located, reported, and
+left alone — Attest is not a general test runner, and running someone's suite in
+a child process with no aliases and no DOM only ever produced a red about code it
+was never pointed at. `archive` uses the same scope.
+
+Every run says so, before the issues:
+
+```
+Running 12 spec files (30 without a requirement(), not run)
+✓ No issues.
+— 20 requirements / 41 scenarios, 0 error, 0 warning, 0 info
+```
+
+The gap between the two numbers is worth watching: a spec file whose
+`requirement()` call Attest cannot see statically is skipped rather than failed,
+and that is where it shows. The same four numbers are in `--json` under `counts`.
+
+A run with **no requirements** under the root is an `empty-spec` ERROR, not a
+pass. "No failing tests" is not the same claim as "the requirements hold", and
+the case that matters is not the empty directory — it is the repo whose registry
+quietly stopped being found, where the tests still run and still go green.
+
 ### Framework code (`.vue`, DOM, path aliases)
 
 The child run isolates from any ambient config by default, so specs run in a bare
@@ -141,7 +208,7 @@ attest check --json
 {
   "tool": "attest",
   "schemaVersion": 1,
-  "version": "0.1.2",
+  "version": "0.2.0",
   "command": "check",
   "ok": false,
   "summary": { "error": 1, "warning": 0, "info": 0 },
@@ -159,7 +226,8 @@ attest check --json
 ```
 
 `verify` adds `passed` (was the test run itself green, independent of the
-overall verdict); `cover` adds `coverage[]` — one `{ reqId, covered,
+overall verdict) and `counts` (`requirements`, `scenarios`, `specFiles`,
+`attesting`); `cover` adds `coverage[]` — one `{ reqId, covered,
 scenarioCount }` row per requirement — plus a `requirements` roll-up;
 `archive` adds `change`; `render` adds `outFile` (and never the document itself).
 `schemaVersion` is bumped on any breaking change to