@descent-vtt/spec-guard 0.11.0 → 0.12.0

package/README.md

@@ -158,8 +158,21 @@ can never exclude anything:
 - **a drive path** such as `C:/repo/dist`.
 - **`.` or `/`**, the root itself.
 
-In a directive a refused pattern is an invalid directive; in the configuration
-or `--exclude` it is exit 2.
+So is any pattern the glob engine cannot read - an unclosed `[` or `{`, an
+extended glob such as `+(a|b)`, a range that runs backwards, `**` inside a
+name - rather than being read as a literal that excludes nothing. The same goes
+for `glob`, `module`, `order` and the structure rules' patterns, and for a spec
+pattern.
+
+`**` means any number of directories only as a whole segment. `docs/**.md` is
+refused, with the two ways to say what was meant: `docs/**/*.md` for any depth,
+`*.md` for one level. The tools it could have come from read it three ways,
+and a spec pattern read the narrow way drops every nested document without a
+word.
+
+In a directive a refused pattern is an invalid directive, whether or not its
+document is in force; in the configuration's `specs` or `exclude`, a spec
+pattern on the command line or `--spec`, or `--exclude`, it is exit 2.
 
 List attributes accept commas or whitespace, so both of these work:
 
@@ -169,7 +182,10 @@ List attributes accept commas or whitespace, so both of these work:
 ```
 
 (A path containing a space therefore cannot be written; there is no quoting
-inside an attribute value.)
+inside an attribute value. Nor can a brace group with a comma in it:
+`glob="*.{ts,tsx}"` is the two patterns `*.{ts` and `tsx}`, and is refused with a
+message that says so. Write `glob="*.ts, *.tsx"`. A configuration's `exclude` is
+a JSON array, where a brace group keeps its commas.)
 
 ### `comments` - the note about a deletion is not the deletion
 
@@ -736,8 +752,11 @@ long before anyone deletes it - because deleting it deletes the reason a
 decision was made.
 
 spec-guard reads that status from the document and honours it. A document whose
-status is `draft`, `proposed`, `rejected`, `deprecated` or `superseded` is
-parsed, validated, reported - and not executed.
+status is `draft`, `proposed`, `rejected`, `deprecated`, `superseded` or
+`archived` is parsed, validated, reported - and not executed. `archived` is what
+`spec-brief` writes when it closes a task brief's round: the brief is kept as
+the record, and its directives, which stated the round's premises and goals,
+are history.
 
 Three spellings are recognised, because three are in use:
 
@@ -760,7 +779,13 @@ Accepted (0.3.0).
 ```
 
 Front-matter wins, then the `## Status` section, then the bold label (which is
-only read above the first `##`). Anything else - `Provisional`, `In review`, a
+only read above the first section heading). A front-matter `status` wins even
+when its value cannot be read - `status: "accepted" (2024-05-01)`, text after
+a closing quote - and then the document stays in force, the section and the
+label are not read in its place, and the report warns on the key's line with
+the reason. Headings are read as CommonMark reads them, so an underlined
+`Status` is the section and a `## Status` kept in a comment is not. Anything
+else - `Provisional`, `In review`, a
 misspelled `Supersedded`, or no status at all - keeps enforcing. That asymmetry
 is deliberate: an unanticipated word that keeps enforcing is a visible failure
 with an obvious fix, while one that stops enforcing is a green build over a rule
@@ -872,6 +897,12 @@ to its checks.
 | --- | --- |
 | `get_architectural_rules(path, include_inactive?)` | The query above, as text and as structured content |
 | `check_architecture(paths?)` | A run. Given paths, only the rules that govern them, each over its whole scope, with every violation marked as in those paths or not |
+| `get_dependents(paths, depth?, include_inactive?)` | [`impact`](#who-depends-on-this---impact): the files that import each path, however far away, with the import that leads there, the imports that could not be followed, and the rules in play. The structured content is the document `impact --json` writes |
+
+All three are marked read-only, idempotent and closed-world. The server's
+instructions tell an agent when to call each: the rules before creating or
+changing a file, the dependents before changing a file others import, and the
+check after changing files.
 
 | Resource | What it holds |
 | --- | --- |
@@ -884,6 +915,174 @@ version on every request and probe with `server/discover`. Nothing is cached, so
 an ADR edited mid-session is read as edited. ADR-0012 has the shapes, the
 sources they follow, and what is deliberately not implemented.
 
+## Can each rule fail? - `prove`
+
+A passing rule says one of two things, and the report cannot tell which: the
+code holds, or the rule cannot see the code. A `glob="*.js"` over a codebase
+written in TypeScript passes, and would pass whatever the code did.
+
+```bash
+spec-guard prove
+```
+
+`prove` shows each rule in force a violation of itself and runs the rule over
+it: a file holding the forbidden text beside the files the rule reads, a file
+importing the forbidden module, two files importing each other, a file in a
+lower layer importing a higher one, a misnamed file, a required entry or a
+partner taken away, a file the rule requires removed. The violation is made **in
+memory**, through the same door every read goes through. Nothing is written to
+disk, and nothing touches git.
+
+```text
+spec-guard prove 3 specs · 12 rules
+
+✖ docs/adr/0004-legacy.md:12  @assert-absence  passed with a violation in place
+    "LegacyClient" must not appear in src
+    maximum: added src/spec-guard-prove.ts holding "LegacyClient", beside the code under src, none of which the rule reads, and it still passed: expected no matches, found 0
+
+○ docs/adr/0009-queue.md:8  @assert-absence  no violation could be made
+    "enqueueRaw" must not appear in src/queue
+    it fails on the tree as it stands (expected no matches, found 1), so no change can be shown to be what fails it
+
+10 seen to fail · 1 survived · 1 unprovable · 1.10s
+✖ 1 rule passed with a violation of itself in place
+```
+
+Each rule is **killed** (it failed on the violation), **survived** (it still
+passed, and the violation is shown), or **unprovable** (no violation could be
+made, and the reason is given). Both bounds of a count are probed. `prove`
+exits 1 when a rule survived, and under `--strict` when one is unprovable. It
+takes the run's `--root`, `--spec`, `--exclude`, `--ignore-status`, `--json`
+and `--format sarif|github|gitlab`, and the configuration's specs, exclusions
+and strictness.
+
+A kill means the rule can fail, not that it catches the way the code is
+written: `module="src/db.ts"` is killed by `import 'src/db.ts'` though every
+file imports `./db.js`. [ADR-0016](docs/adr/0016-rules-seen-to-fail.md) has the
+violations for each kind of rule, and what `unprovable` means.
+
+## Do the comments cite decisions in force? - `cites`
+
+Code comments cite decisions - `// ADR-0011: the domain imports no
+infrastructure`, `# see ADR-7`, `/* Q-172 */` - and the claim goes stale the
+way code does: the document was never written, or it has since been superseded.
+`spec-guard cites` reads the comment text of every source file for the ids a
+project names, and reports each citation of a document that does not exist or
+is no longer in force:
+
+```bash
+spec-guard cites
+```
+
+```text
+spec-guard cites ADR-{n} (10 documents matching docs/adr/{n}-*.md); RFC-{n} (2 documents matching docs/rfcs/rfc-{n}.md)
+
+⚠ crates/ledger/src/journal.rs:1 cites ADR-0007, which is superseded - cite ADR-0009 instead  stale-citation
+    hint: docs/adr/0007-async-journal.md says "superseded by ADR-0009"
+✖ crates/ledger/src/lib.rs:28 cites ADR-0011, which no document defines  ghost-citation
+    hint: no document matching docs/adr/{n}-*.md has the number 11; the nearest is ADR-0010
+
+3 citations in 2 files · 1 ghost · 1 stale · 22ms
+✖ 1 citation names a document that does not exist
+```
+
+The families of documents are named in the configuration, one entry each - an
+id with `{n}` for the number, and a path glob naming the documents with `{n}`
+in the file name:
+
+```json
+{
+  "cites": [
+    { "id": "ADR-{n}", "files": "docs/adr/{n}-*.md" },
+    { "id": "RFC-{n}", "files": "docs/rfcs/rfc-{n}.md" }
+  ]
+}
+```
+
+- **The number is a number**: `ADR-7`, `ADR-007` and `docs/adr/0007-x.md` are
+  one document. An id has a word boundary on each side, so `XADR-1` and
+  `ADR-12a` are not citations, and one id on one line is one finding however
+  often it is written there.
+- **Without `cites`**, a directory of specs whose names begin with a number, and
+  whose titles all begin with one id and that number (`# ADR-0007: ...` in
+  `0007-x.md`), is read as a family. Anything less is not guessed at: the
+  command exits 0 with a note saying to name the documents.
+- **Comment text only**, as the comment classifier reads it: an id in a string,
+  a raw string or a YAML value is not a citation. Markdown is spec-graph's and
+  is not read, nor are the spec files, the project's `exclude`, and the default
+  skips. Files in a language whose comments spec-guard does not know are
+  counted by extension, and a file read in part - binary, unreadable, or a scan
+  that lost its place - is named.
+- **Another project's ids are not checked**: `spec-core's ADR-0005`,
+  `spec-graph ADR-0017` or `its ADR-12` name a document in another repository,
+  and are counted instead.
+- **Stale** is `superseded`, `deprecated`, `rejected` or `archived`; a draft or
+  proposal cited from the code implementing it is not. The successor is read
+  from the document's status line - `Superseded by ADR-0014` - and followed to
+  the one in force.
+
+A ghost exits 1. A stale citation is a warning, and exits 1 under `--strict`,
+as does a file read in part or a check that looked for nothing. A family whose
+files match no document exits 2. `--json` (versioned by `formatVersion`),
+`--format sarif`, `--format github` and `--format gitlab` carry the same
+findings; `spec-guard cites src lib/a.ts` reads only those paths.
+[ADR-0017](docs/adr/0017-citations-in-comments.md) has the design, and what is
+out of scope: links to symbols, which need a parser the family does not ship.
+
+## Who depends on this? - `impact`
+
+Before changing a file, the question after "which rules govern it" is "what
+else does it reach". `spec-guard impact` reads the import graph backwards: for
+each path, the files that import it, and the files that import those, with how
+far each is and the import that takes it one step closer; then the rules in
+force that govern the path or any of them:
+
+```bash
+spec-guard impact src/db/client.ts --depth 3
+```
+
+```text
+src/db/client.ts
+  4 files depend on it, 2 directly, up to 3 imports away
+    1  src/app/service.ts  imports src/db/client.ts (line 2)
+    1  src/db/index.ts     imports src/db/client.ts (line 1)
+    2  src/app/cache.ts    imports src/app/service.ts (line 1)
+    3  src/ui/view.tsx     imports src/app/cache.ts (line 1)
+
+3 rules govern these files, from 1 document
+
+  ADR-0001: Layers  (docs/adr/0001-layers.md)
+    :3 @assert-layers  src must keep its layers in order, src/db < src/app < src/ui
+      governs: src/db/client.ts, src/app/service.ts, src/db/index.ts, src/app/cache.ts, src/ui/view.tsx
+    ...
+
+3 imports could not be resolved, and may depend on these paths:
+  src/ui/view.tsx:3  ./gone.js (names no file)
+  src/ui/view.tsx:4  @/db (names no file)
+  src/ui/view.tsx:7  import(name)
+```
+
+- **Followed**: relative JavaScript and TypeScript imports, by the table the
+  cycle rule uses ([ADR-0011](docs/adr/0011-layers-and-cycles.md)), and relative
+  Python imports, which name a module beside the importing file.
+- **Counted, not followed**: Go imports, Rust `use`s, C# `using`s and absolute
+  Python imports name modules, and which file a module is depends on `go.mod`,
+  the crate's module tree, the compiler or `sys.path`. A path in one of those
+  languages says its dependents are not computed, rather than showing an empty
+  list.
+- **Listed, never guessed**: an import naming no file, an alias such as `@/db`,
+  a dynamic `import(name)`. Any of them may depend on the path.
+
+A directory asks about every file under it. `--depth <n>` stops `n` imports
+away; cycles are safe. `--ignore-status` lists rules from documents not in
+force, which are otherwise counted, as `query` does. `--json` is versioned by
+`formatVersion`. A path that does not exist exits 2, and so does a run of
+`impact` in which no spec matched, as `query` does: the dependents are still
+written, but "no rules" over no specs is nothing measured. `--allow-empty`
+asks for the dependents alone, and exits 0. The MCP server answers the same
+question as `get_dependents`, with the same document.
+[ADR-0018](docs/adr/0018-impact.md) has the table and what it leaves out.
+
 ## CLI
 
 ```bash
@@ -891,6 +1090,9 @@ spec-guard [patterns...] [options]     # execute the directives
 spec-guard --watch [patterns...]       # execute them again whenever the tree changes
 spec-guard query <paths...> [options]  # the rules in force for files or directories
 spec-guard mcp [options]               # serve the rules over MCP on stdio
+spec-guard prove [patterns...]         # show each rule a violation of itself, in memory
+spec-guard cites [paths...]            # check each spec a code comment cites exists and is in force
+spec-guard impact <paths...>           # the files that depend on each path, and the rules in play there
 ```
 
 | Option | Description |
@@ -900,8 +1102,8 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 | `-v, --verbose` | Print passing assertions too |
 | `--watch` | Report, then report again as the tree changes, until Ctrl+C |
 | `--fail-fast` | Stop at the first failing assertion |
-| `--json` | Machine-readable report on stdout (same as `--format json`) |
-| `--format <human\|json\|sarif>` | Output format. `sarif` uploads to GitHub code scanning |
+| `--json` | Machine-readable report on stdout (same as `--format json`), versioned by `formatVersion` |
+| `--format <human\|json\|sarif\|github\|gitlab>` | Output format. `sarif` uploads to GitHub code scanning, `github` annotates a pull request from the job's log, `gitlab` is a GitLab Code Quality report |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
 | `--strict` / `--no-strict` | Treat analysis that could not be completed as a failure |
 | `--allow-missing-targets` / `--no-allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
@@ -909,11 +1111,12 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 | `--print-baseline` | Print the `baseline="..."` that would exempt today's violations, and exit |
 | `--no-default-skips` / `--default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
 | `--exclude <globs>` | Paths no assertion looks at, beside each directive's own `exclude`. Repeatable; replaces the configuration's list, and `--exclude=` clears it |
-| `--ignore-status` / `--no-ignore-status` | Execute directives in draft, proposed and superseded documents too |
+| `--ignore-status` / `--no-ignore-status` | Execute directives in documents not in force too: draft, proposed, rejected, deprecated, superseded or archived |
 | `--include-specs` / `--no-include-specs` | Also count matches inside the spec files themselves |
 | `--max-snippets <n>` | Failure snippets per assertion (default 5) |
 | `--concurrency <n>` | Search passes in flight at once (default 8) |
-| `--allow-empty` | Exit 0 when no spec file matched the patterns (about the run, not an assertion) |
+| `--depth <n>` | `impact` only: follow dependents at most `n` imports away (default: all) |
+| `--allow-empty` | Exit 0 when no spec file matched the patterns, for a run, `prove` or `impact` (about the run, not an assertion) |
 | `--color` / `--no-color` | Force colour on or off (`NO_COLOR` honoured) |
 
 Patterns are expanded by spec-guard itself, so quoted globs behave identically
@@ -958,6 +1161,7 @@ same options, at the top level, in `.spec-guard.json`:
 | `strict`, `allowMissingTargets`, `allowEmptyScope`, `ignoreStatus`, `includeSpecs`, `defaultSkips` | the flag of that name | `true` or `false` |
 | `maxSnippets` | `--max-snippets` | an integer, 0 or more |
 | `concurrency` | `--concurrency` | an integer, 1 or more |
+| `cites` | none; `spec-guard cites` reads it | a non-empty array of `{ "id": "ADR-{n}", "files": "docs/adr/{n}-*.md" }`, and no other key |
 
 - **Only the root's files** are read: the `--root` directory, or the working
   directory. Nothing is inherited from a parent directory.
@@ -1045,8 +1249,8 @@ symbolic link, and anything outside the root. CI stays the authority.
 | Code | Meaning |
 | --- | --- |
 | `0` | Every assertion held |
-| `1` | An assertion failed, or a directive was malformed |
-| `2` | spec-guard could not run: bad usage, a malformed configuration, no spec files matched, `--engine rg` with no ripgrep, a watch that could not start |
+| `1` | An assertion failed, or a directive was malformed; for `prove`, a rule survived; for `cites`, a comment cites a document that does not exist |
+| `2` | spec-guard could not run: bad usage, a malformed configuration, no spec files matched, `--engine rg` with no ripgrep, a watch that could not start, a `cites` family whose files match no document |
 | `130` | A `--watch` session was stopped |
 
 ## CI integration
@@ -1104,6 +1308,43 @@ where the fix goes. Alerts carry a fingerprint derived from what the assertion
 is about rather than where its matches landed, so inserting a line above a
 violation does not close the alert and open a new one.
 
+Two formats need no upload step. `--format github` writes one GitHub Actions
+workflow command per finding, which the job's log turns into an annotation on
+the diff:
+
+```text
+::error file=src/a.ts,line=2,title=assert-absence::"Legacy" must not appear in src: expected no matches, found 2 (docs/adr/0004-legacy.md:12)
+```
+
+`--format gitlab` writes a
+[GitLab Code Quality](https://docs.gitlab.com/ci/testing/code_quality/) report,
+which a merge request shows beside its changes:
+
+```yaml
+spec-guard:
+  script:
+    - npx @descent-vtt/spec-guard --format gitlab > gl-code-quality-report.json || true
+  artifacts:
+    reports:
+      codequality: gl-code-quality-report.json
+```
+
+Every format places the same findings, and `prove` and `cites` write all three:
+
+| Finding | GitHub | GitLab severity |
+| --- | --- | --- |
+| a failing assertion, on its first offending line or its directive | `error` | `critical` |
+| a rule that survived `prove`, on its directive | `error` | `critical` |
+| a ghost citation (`cites`), on its comment | `error` | `critical` |
+| a directive that could not be read | `error` | `major` |
+| a stale citation (`cites`) | `warning`; `error` under `--strict` | `minor`; `critical` under `--strict` |
+| a rule `prove` could make no violation for | `notice` | `minor` |
+| a file `cites` could read only in part | `notice` | `info` |
+| a document not in force, on its first line | `notice` | `info` |
+
+A GitLab issue's `fingerprint` is the SHA-256 of its rule, file and message,
+which GitLab compares across pipelines to tell a new finding from an old one.
+
 **There is no language server, and that is a decision rather than a gap.**
 spec-guard's claims are about a whole repository - "this symbol appears nowhere
 in `src`" - and a language server is handed one buffer at a time. Answering a
@@ -1121,9 +1362,11 @@ parser  ──▶ Directive[] ──▶ runner ──▶ Assertion[] ──▶ e
 (pure)                      (I/O)                     (rg | js)                        (pure)
 ```
 
-1. **Parse.** Markdown is scanned for `<!-- @assert-* -->` comments. Fenced code
-   blocks and inline code spans are masked first, so documentation that shows
-   the syntax (like this README) never executes it.
+1. **Parse.** Markdown is scanned for `<!-- @assert-* -->` comments. Code -
+   fenced and indented blocks, code spans, and the HTML elements whose content
+   is not Markdown - and front matter are masked first, by the Markdown scanner
+   every spec-* tool shares, so documentation that shows the syntax (like this
+   README) never executes it.
 2. **Resolve.** Each directive becomes a typed assertion. Bad numbers, unknown
    booleans, unknown attributes and paths escaping `--root` are rejected here,
    before any I/O.
@@ -1238,6 +1481,39 @@ observed count, match locations, warnings and timings. The parser
 (`parseDirectives`) and reporter (`formatReport`, `formatJson`) are pure
 functions you can use on their own.
 
+A run reads the tree through one interface, `Io` - list a directory, `stat` a
+path, read a file, resolve a real path - and `nodeIo` is the filesystem. Pass
+your own as `io` and every read the run makes goes through it: finding and
+reading the specs, checking targets exist, walking them, scanning files, reading
+imports and listing directories. That is how to run the rules over a tree that
+is not on disk, or not as the disk has it:
+
+```ts
+import { nodeIo, runSpecGuard, type Io } from '@descent-vtt/spec-guard';
+
+// The disk, except for one file edited in memory.
+const edited: Io = {
+  ...nodeIo,
+  readFile: async (file) =>
+    file === '/repo/src/pay.ts' ? Buffer.from('new LegacyGateway();\n') : nodeIo.readFile(file),
+};
+
+const report = await runSpecGuard({ patterns: ['docs/**/*.md'], root: '/repo', io: edited });
+```
+
+ripgrep reads the disk itself, in a process of its own, so no `io` can reach
+it: `engine: 'ripgrep'` with an `io` is an error, and `auto` with one searches
+with the built-in scanner.
+
+`proveSpecGuard` is `spec-guard prove` for a caller: it takes the options that
+decide whether a rule passes, and an `io` too, and returns each rule's outcome
+with the violations it was shown. `overlayIo` is the door it makes them behind,
+and is there for a caller who wants to try a change of its own.
+
+`findCitations` and `impactOf` are `spec-guard cites` and `spec-guard impact`,
+and take an `io` as well; so do `loadRuleSet` and `queryRules`. Each command's
+JSON is the report its function returns, with a `formatVersion` in front.
+
 ## Design decisions
 
 This tool was specified loosely and built opinionatedly. Where the
@@ -1252,11 +1528,27 @@ themselves stay uncounted, because a directive is an HTML comment and a rule
 whose own text trips it can never be satisfied. `comments="include"` counts even
 those.
 
-**Fenced code and inline code are masked before parsing.** A README documenting
-the syntax must not execute it. Masking preserves byte offsets, so reported line
-numbers stay exact. (This is subtle: pairing backtick runs the naive way
-desynchronises after a stray unmatched run and un-masks real prose. spec-guard
-uses CommonMark's equal-length pairing rule, and there is a regression test.)
+**Code is masked before parsing.** A README documenting the syntax must not
+execute it. What is code is what CommonMark says it is, decided by
+[spec-core](https://github.com/DescentVTT/spec-core)'s Markdown scanner, which
+every spec-* tool reads documents with and which is copied into
+`src/vendor/spec-core` and verified by hash: fenced and indented code, code
+spans, `<script>`, `<pre>`, `<style>` and `<textarea>` blocks, and front matter.
+Comments and code spans are resolved left to right in one pass, so a backtick
+inside a comment is a character and `<!--` inside a code span is code, and a
+code span ends with its paragraph, so a stray backtick cannot hide the
+directives after it. A fence may be indented with the list item it sits in.
+Masking preserves every offset and line terminator, so reported line numbers
+stay exact. [ADR-0002](docs/adr/0002-directive-format.md)'s amendment lists
+where this differs from 0.11.0.
+
+What is masked is still counted. A comment shaped like a directive -
+`<!-- @assert-...` - in code, raw HTML or front matter is not run, and the
+report says how many there were and where, on one line (every one under
+`--verbose`, and in `maskedDirectives` in JSON), so text read as code by
+accident is not a rule gone quiet without a word. A code fence or raw-text
+block that is never closed, which makes the rest of its document code, is a
+warning on its opening line.
 
 **A document's lifecycle status is read; a directive's is not.** Status is
 document-level and visible in every rendered Markdown view. A per-directive
@@ -1290,6 +1582,13 @@ anything - it answers only *which files contain this text*, and the scanner
 counts each pattern separately over the shared file contents. The batching
 checks were deleted along with the risk they guarded.
 
+**Globs are matched by an automaton, not a regular expression.** Every
+pattern - `glob`, `exclude`, `module`, a layer, a spec pattern - is read by the
+glob engine the spec-* tools share, copied from spec-core and checked by hash.
+A `RegExp` backtracks: `*-*-*-*-*-*x` took 55 seconds to fail one long file
+name. The automaton cannot, and ripgrep is handed each pattern spelled as the
+automaton reads it ([ADR-0015](docs/adr/0015-globs-from-spec-core.md)).
+
 **Exit code 2 exists.** "Your specs failed" and "spec-guard could not run" are
 different facts, and CI should be able to tell them apart.
 
@@ -1342,7 +1641,9 @@ and [`docs/adr/0002-directive-format.md`](docs/adr/0002-directive-format.md) are
 executed against this repository on every CI run. The CLI never calls
 `console.log`, nothing outside the engine spawns a process, and the parser and
 reporter never touch the filesystem - because those documents say so, and the
-build fails if they stop being true.
+build fails if they stop being true. CI proves every one of those rules can
+fail, and `spec-guard cites` holds every ADR a comment in the code cites to
+existing and being in force.
 
 This README is executable too:
 
@@ -1370,7 +1671,7 @@ prebuilt binary and is never a runtime dependency.
 
 Coverage says a line ran. It does not say an assertion would notice if the line
 behaved differently. This repository measures the difference: line coverage is
-**100%**, and **99.01%** of 8,644 mutants are killed in CI, with 83 survivors and
+**100%**, and **99.20%** of 11,537 mutants are killed in CI, with 89 survivors and
 no file below 95%. The second number is the one worth reading, and what was done
 about the survivors matters more than the score. At 0.5.1 every surviving mutant
 was checked individually, and the 101 left then produced byte-identical output.
@@ -1446,6 +1747,60 @@ mutants" sounded like judgement rather than an unchecked assumption - along with
 the real bugs that chasing the gate uncovered, and a class of mutant the runner
 reports as survived while the suite is in fact killing it.
 
+### Releasing
+
+A release is a tag push. Nothing is published from a laptop, and there is no
+npm token in this repository or in its secrets.
+
+```bash
+npm version minor   # or patch / major - writes package.json and makes the tag
+git push origin main --follow-tags
+```
+
+[`release.yml`](.github/workflows/release.yml) then:
+
+1. refuses the release unless the tag, `package.json` and a `## <version>`
+   heading in `CHANGELOG.md` all agree;
+2. type checks, builds, runs the suite and executes this repository's own ADRs.
+   A tag push does not run CI, so the release job runs those steps itself;
+3. `npm pack`s the tarball, prints its file list and its SHA-256, and hands that
+   exact file to the publishing job. Nothing is rebuilt in between, so what
+   reaches the registry is the artifact the tests ran against;
+4. stages it with `npm stage publish --provenance`. The job authenticates with a
+   short-lived OIDC token that GitHub mints for `release.yml` running in the
+   `npm` environment, and npmjs.com accepts it only for that combination - npm's
+   trusted publishing, so there is no credential to leak or to rotate.
+
+The publishing job installs no dependencies and checks nothing out. Everything
+that runs third-party code - `npm ci`, a postinstall that downloads a ripgrep
+binary, the test suite - happens in the earlier job, which has no token.
+
+Staging is not publishing. The version sits on npmjs.com visible to maintainers
+and installable by nobody until:
+
+```bash
+npm stage list @descent-vtt/spec-guard
+npm stage view <stage-id>
+npm stage approve <stage-id>   # asks for a second factor
+```
+
+`npm stage reject <stage-id>` discards it instead, and the tag can be deleted
+and remade. Approving needs 2FA and therefore a person: CI can build a release,
+but it cannot decide to publish one.
+
+Two repository settings hold the other end of this. The `npm` environment
+accepts deployments only from `main` and from `v*` tags, so no branch can reach
+the publishing job. A `Release tags` ruleset lets only repository admins create,
+move or delete a `v*` tag - under this workflow, pushing one is the release, and
+an accidental push should not be able to start it.
+
+`Actions -> Release -> Run workflow` with `dry_run` left on verifies, packs and
+hands the tarball to npm without spending a version number. It stops at the
+registry's version check - a dispatch runs from `main`, whose version is already
+published - and it does not exercise authentication, because the OIDC exchange
+happens only on a publish that intends to write. The first real tag is what
+proves that end.
+
 ## Requirements
 
 - Node.js 22 or newer (native ESM)