@descent-vtt/spec-guard 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -5,6 +5,416 @@ All notable changes to this project are documented here. Versions follow
 may change in a minor release — each such change is listed under **Changed**
 with the flag that restores the previous behaviour.
 
+## 0.12.1
+
+The query is fast again. A warm `query` in the MCP server took 27 ms over this
+repository's specs after 0.12.0 moved to spec-core's scanner, past the 20 ms
+ADR-0012 set; it now takes about 6 ms, faster than 0.11.0. The scanner makes
+only what it is asked for, and the server parses a spec again only when its
+bytes change. The shipped README and changelog link to the ADRs by address,
+so the links lead somewhere on npmjs.com and inside `node_modules`.
+
+### Added
+
+- **`createDocumentMemo`, and `documents` on `runSpecGuard`, `loadRuleSet`,
+  `queryRules` and `impactOf`**: parsed spec documents kept from one call to
+  the next, for a process that reads the specs on every request. Every spec
+  is still found and read, so an edit is seen by the next call; a document is
+  parsed again only when its bytes change. It holds one parse of each
+  document the spec set read last names, and forgets one removed, left out or
+  edited at the next read. The MCP server keeps one for its lifetime; a
+  command run once takes none, and parses every document and hashes none, as
+  before.
+
+### Fixed
+
+- **The README's and the changelog's links to the ADRs lead somewhere on
+  npmjs.com and in node_modules.** They were relative, and the package ships
+  neither `docs/` nor `.github/`, so outside the repository the 66 links to
+  ADRs and the one to the release workflow led nowhere. Each is an absolute
+  URL to the file on GitHub now, and a link to a file the package ships stays
+  relative. `tests/package.test.ts` holds every Markdown document the package
+  ships to that, and each absolute link to a file the repository holds.
+
+### Changed
+
+- `npm publish` in a checkout refuses to run outside GitHub Actions, so a
+  version cannot reach npm from a workstation by mistake, without provenance;
+  spec-harness 0.1.0 did. The release never runs it: it stages a tarball it
+  packed.
+- **spec-core is copied again, from `8840d36`**, `markdown` alone, and
+  verified by hash. Its scanner makes links, list items and the directives
+  mask the first time each is read, and keeps them, where every scan made all
+  three; spec-guard reads the directives mask and neither of the others. It
+  also lists an image inside a link's text - a badge wrapped in a link - as a
+  link of its own, after the link. Nothing here reads links: over the 145
+  Markdown files of the five spec-* repositories every directive, error,
+  status, title and warning reads as it did, and a run, `prove` and `cites` of
+  this repository answer as they did.
+  [ADR-0015](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0015-globs-from-spec-core.md).
+- **A warm query in the MCP server meets its 20 ms budget again**, over
+  this repository's 19 specs as over its 18 ADRs. 0.12.0 had lost it to
+  spec-core's scanner, which costs about three times what the parser it
+  replaced did. Measured together in one process, a query of one path took a
+  median of 6.3 ms, against 23.8 ms with `8840d36`'s lazy scan alone,
+  27.4 ms for 0.12.0 and 7.9 ms for 0.11.0; over the ADRs alone, 6.0 ms
+  against 18.7, 22.4 and 6.3 ms. The lazy scan takes 13 to 21% off, run to
+  run; the rest is the server parsing only a document whose bytes changed. A server's first
+  request, and one after an edit, still parse what they read: 24.3 ms for a
+  first request here. The 23 ms recorded for 0.12.0 was most likely measured
+  over the ADRs alone; over the specs this repository names it was 29 ms.
+  [ADR-0012](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0012-query-and-mcp.md)'s
+  amendment has both measurements.
+
+## 0.12.0
+
+The family's core, and three commands. Patterns and Markdown are read through
+spec-core, copied in and checked by hash: a pattern that cannot be read is
+refused rather than matched as a literal, a glob no longer backtracks, and
+directives are found as CommonMark finds code, comments and front matter.
+`prove` shows every rule in force catching a violation, `cites` holds code
+comments to the specs they cite, and `impact` names who depends on a path.
+`archived` withholds a document.
+
+### Upgrading
+
+Run this release beside the one it replaces, each with `--json`, and compare
+`summary.total` before trusting a green run - and, if the totals differ, each
+result's `spec` file and line, which say which rule moved. A rule that stops
+running reads exactly like one that passes. On a consumer of 114 specs and 301
+assertions, both releases ran the same 301 at the same places with the same
+counts. What can differ, and where this changelog says why:
+
+- **A run that exits 2**, or a directive that is invalid, where one ran: a
+  pattern that cannot be read - `**` inside a name (`docs/**.md`), an
+  extended glob, an unclosed `[` or `{` - in `specs`, `exclude`, `--spec`,
+  `--exclude` or a directive's attributes.
+- **`summary.total` moving** because a directive moved between prose and code:
+  the shapes under Fixed. Every directive-shaped comment left in code, raw
+  HTML or front matter is on one line of the report and in `maskedDirectives`.
+- **`summary.inactive` moving**: `archived` withholds a document; a
+  front-matter `status` the reader cannot read - text after a closing quote,
+  `: ` in a plain value - keeps its document in force with a warning, where
+  0.11.0 took its first word, and nothing below the front matter is read in
+  its place; and an invalid directive in a draft is counted once, as invalid.
+- **Warnings that fail nothing**, in `specWarnings`: a front-matter status
+  that cannot be read, a block never closed.
+- **`impact` exits 2** when no spec matched, as `query` does.
+
+### Added
+
+- **`spec-guard impact <paths...>`: who depends on this?** For each path, the
+  files that import it, transitively, each with its distance and the import
+  that takes it one step closer, and the rules in force that govern the path or
+  any of them, by `query`'s arithmetic. The import graph is ADR-0011's, read
+  backwards over the whole tree: relative JavaScript and TypeScript imports by
+  its resolution table, and relative Python imports, which name a module
+  beside the importing file. Go, Rust, C# and absolute Python references name
+  modules and are counted rather than followed; a path in one of those
+  languages says its dependents are not computed. An import naming no file, an
+  alias or a dynamic `import(name)` is listed, never guessed. `--depth <n>`,
+  `--ignore-status`, and `--json` with `formatVersion`. A path that does not
+  exist is exit 2, and so is a run in which no spec matched, as for `query`:
+  the dependents are written, and `--allow-empty` exits 0 with them. `impactOf`
+  is the API. [ADR-0018](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0018-impact.md).
+- **`get_dependents` on the MCP server**, a third tool beside
+  `get_architectural_rules` and `check_architecture`: `impact` for a list of
+  paths, with `depth` and `include_inactive`. Its structured content is the
+  document `impact --json` writes and its text the command's report, and it is
+  annotated read-only, as the other two are. Its description, and the server's
+  instructions, tell an agent to call it before changing a file others import.
+  A path that does not exist is a tool error the model can read. A client
+  that pinned the tool list sees three. `impactDocument` is the API for the
+  document both answer with. ADR-0018's amendment.
+- **`spec-guard cites`: do the comments cite decisions in force?** A comment
+  such as `// ADR-0011: the domain imports no infrastructure` is a claim, and it
+  goes stale when the document is never written or is superseded. `cites` reads
+  the comment text of every source file - by the classifier's reading, so never
+  a string - for the ids of the families a project names in a new `cites`
+  option, `[{ "id": "ADR-{n}", "files": "docs/adr/{n}-*.md" }]`, where `{n}` is
+  a number (`ADR-7`, `ADR-007` and `0007-x.md` are one document). Without it, a
+  directory of numbered specs whose titles all begin with one id and their own
+  number is read as a family; anything less is a note and exit 0, not a guess.
+  A **ghost** citation, of no document, is an error with the nearest ids as its
+  hint. A **stale** one, of a document superseded, deprecated, rejected or
+  archived, is a warning (an error under `--strict`) that names the successor
+  the document's status line gives, followed to the one in force. Ids another
+  project qualifies - `spec-core's ADR-0005` - are counted and not checked,
+  and so are ids in a link: after a `/`, `#`, `=` or `?`, or past a `://`,
+  as in `https://github.com/org/repo/blob/main/docs/adr/ADR-0042.md`.
+  Markdown, spec files, excluded paths and files in no known language are not
+  read, and are counted. Human, `--json` (with `formatVersion`), SARIF, GitHub
+  and GitLab output; exit 1 on a ghost, 2 for a family whose files match no
+  document. `findCitations` is the API.
+  [ADR-0017](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0017-citations-in-comments.md).
+- **`spec-guard prove`: can each rule actually fail?** A passing rule cannot
+  say whether the code holds or the rule cannot see the code. `prove` shows
+  each rule in force a violation of itself - a file holding the forbidden text,
+  a file importing the forbidden module, a cycle, an import across layers, a
+  misnamed file, a required entry or a partner taken away, a required file
+  removed - and runs the rule over it, in memory, through the door every read
+  goes through: nothing is written to disk and nothing touches git. Each rule
+  is `killed`, `survived` (the finding, with the violation shown) or
+  `unprovable` (with the reason). Exit 1 when a rule survived, and under
+  `--strict` when one is unprovable; `--json` is versioned by `formatVersion`,
+  and `--format sarif` puts a survivor on its directive.
+  `proveSpecGuard` is the same for a caller of the API. The first proof of
+  this repository's own rules found one that could not fail as written, and
+  CI now proves every rule the repository states on each change.
+  [ADR-0016](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0016-rules-seen-to-fail.md).
+- **`RunOptions.io`: a run over a tree that is not on disk.** `runSpecGuard`
+  reads through the `Io` it is given - finding and reading the specs, checking
+  targets exist, walking them, scanning files, reading imports and listing
+  directories - and through `nodeIo` when it is given none, as before. The run
+  had the door all along and handed the filesystem to every reader itself.
+  ripgrep reads the disk in a process of its own, where no door reaches, so
+  `engine: 'ripgrep'` with an `io` is refused with a message that says so, and
+  `auto` with one searches with the built-in scanner. A search that fails
+  outright through the door fails the run, rather than falling back to the
+  scanner that reads the disk. [ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md).
+- **`--format gitlab` and `--format github`**, for the run, `prove` and
+  `cites`. `gitlab` writes a GitLab Code Quality report - `description`,
+  `check_name`, a `fingerprint`, a `severity` and a `location` - which a
+  merge request shows beside its changes. The fingerprint is the SHA-256 of
+  what a finding is about - a rule's document, kind, subject and targets, as
+  SARIF's is; a citation's file, family and id; a document's path - and never
+  of its message, which holds the count of matches and the directive's line:
+  one more match, or a line added above a directive, would otherwise have
+  closed every open issue and opened a new one. Findings that share an
+  identity, one ghost cited on two lines, are numbered in order. `github` writes one workflow command per finding, which a job's log
+  turns into an annotation on the pull request with no upload step. Both place
+  the findings SARIF places: a failing assertion or a surviving rule is
+  `critical`, a directive that could not be read `major`, a rule `prove` could
+  make no violation for `minor`, and a document not in force is named, as
+  `info`, on its first line. `formatGitlab`, `formatGithub`, `runAnnotations`,
+  `proveAnnotations` and `citesAnnotations` are the API.
+- **What was not run is counted.** A comment shaped like a directive in code,
+  raw HTML or front matter is not run, and a report now says how many and
+  where: one dim line in the human report - "7 directive-shaped comments in
+  code, raw HTML or front matter were not run: README.md:120, ..." - naming
+  the first five, or every one under `--verbose`, and `maskedDirectives` in
+  the `--json` of a run and of `prove`, each with what hid it. Most are
+  examples; the ones that are not are rules 0.11.0 ran that this release does
+  not, such as a directive in an indented line or under a leading `---` read
+  as front matter. Warnings about how a document was read - a front-matter
+  status that cannot be read, a block never closed - are `specWarnings`.
+  Both fields are added, so no `formatVersion` moves.
+  [ADR-0002](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0002-directive-format.md)'s amendment.
+- **`formatVersion: 1` on the run's `--json` and on `query --json`**, as
+  `prove --json` has had from the start: a field removed or renamed moves it,
+  a field added does not. Both documents are otherwise unchanged; this is one
+  field more, first in each.
+- **`io` on `loadRuleSet` and `queryRules`, too.** A query found and read the
+  specs, and asked whether each path exists, through the filesystem whatever
+  the caller had; it now goes through the door it is given, as a run does, so
+  a query over a tree in memory sees that tree.
+
+### Fixed
+
+- **An invalid directive in a document not in force was counted twice**, as
+  invalid and again as a rule not in force, so one bad directive in a draft
+  read "1 invalid · 1 not in force". It is counted once, as invalid, in the
+  summary, in the document's own line, and in the `inactive` of every JSON
+  report: it is no rule the document would run in force.
+- **A glob could take a minute to fail one file name.** Every pattern was
+  compiled to a `RegExp`, and `*-*-*-*-*-*x` against a name of 121 dashes made
+  V8 try every way of dividing the name between six `[^/]*` groups: 55 seconds,
+  measured. Patterns are now read by the glob engine the spec-* tools share,
+  spec-core's, whose automaton keeps a set of live states and cannot backtrack:
+  the same match takes under a millisecond. spec-core is copied into
+  `src/vendor/spec-core` and verified by hash, so `dependencies` stays empty,
+  and its MIT notice ships in the package at `src/vendor/spec-core/LICENSE`.
+  [ADR-0015](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0015-globs-from-spec-core.md).
+- **ripgrep and the scanner still read some patterns differently**, so the same
+  rule could count differently on either side of the tree size at which `auto`
+  changes engine. ripgrep anchored every alternative of `{src/*.ts,*.md}`
+  because one held a `/`, dropped the empty one in `{,src/}a.ts`, matched
+  nothing for `src/./a.ts`, and failed on a `}` that closes nothing. It is now
+  handed each alternative as a glob of its own, spelled as the scanner reads
+  it. And ripgrep applies no glob to a path named on its command line, so a
+  rule whose target is a file its `glob` does not match, or a directory its
+  `exclude` does, counted under ripgrep what the scanner left out; its list of
+  files is now held to the same filters. ADR-0015.
+- **What is code in a spec is what CommonMark says it is.** Directives inside
+  code never execute, and what counted as code was decided by `maskCode`'s own
+  rules. It is now decided by spec-core's Markdown scanner, which every spec-*
+  tool reads documents with, copied into `src/vendor/spec-core` from `cbe2223`
+  and verified by hash; `maskCode` is still exported, and is the scanner's
+  mask. [ADR-0002](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0002-directive-format.md)'s amendment.
+
+  Directives that were hidden, and now execute:
+  - **A backtick fence's info string may not hold a backtick.** A line that
+    reads ```` ```js`x ```` is prose that opens with a code span. Read as a
+    fence, it hid every line under it, a real directive included, until
+    something closed it - and nothing said a rule had gone quiet.
+  - **A code span ends with its paragraph.** A backtick that closes nothing
+    there, as in ``press ` to open the console``, paired with the next
+    backtick anywhere in the document and hid every directive between the
+    two. An escaped backtick opens nothing.
+  - **A fence shown inside a comment opens nothing.** A template that showed
+    one hid every directive after it.
+  - **A fence line shown as code in a list item opens nothing.** Four columns
+    past an item's text is indented code, so a fence line written there - six
+    spaces under a `-` item, seven under `1.`, deeper in a nested item - is a
+    line of code. The first copy of the scanner read no indented code inside a
+    list, took the line for an opener that nothing closed, and hid every
+    directive after it.
+
+  And a code fence or a `<pre>`, `<script>`, `<style>` or `<textarea>`
+  block that is never closed, and runs to the end of the document, is a
+  warning on its opening line (`specWarnings`), since no directive after it
+  runs. It fails nothing: it is read as every renderer shows it, as code.
+
+  Directives that executed, and are now code:
+  - **A closing fence has no info string.** Inside a block opened by three
+    backticks, a line of three backticks followed by `js` is a line of the
+    block. It used to close it, and a directive shown after it executed.
+  - **A fence may be indented with the list item it sits in.** CommonMark
+    counts its three spaces from the item, so a fence in a `1.` item nested in
+    a `-` item is five or more spaces from the margin. It was not recognised,
+    and a directive shown inside it executed: always behind `~~~`, and behind
+    backticks whenever the prose above mentioned one, since the two fence lines
+    otherwise paired as a code span by accident. An opener may sit at any
+    indentation outside indented code, and a closer at most three columns
+    deeper than its opener.
+  - **Indented code, raw-text HTML and front matter are not read.** Four
+    columns past the margin, or past the text of the list item a line sits
+    in, after a blank line, are code in every renderer;
+    `<script>`, `<pre>`, `<style>` and `<textarea>` hold no Markdown; front
+    matter is metadata. `<details>` and `<div>` hold Markdown, and are read.
+
+  And a backtick inside a comment is a character, so a directive holding one
+  keeps it: ``symbol="`eval`"`` is searched for as written, where the two
+  backticks paired and the rule searched for six spaces.
+
+  This repository's own specs execute the same assertions, at the same lines,
+  and every directive in the 143 Markdown files of the five spec-* repositories
+  is read as before. A test holds the scanner to 0.11.0's masking on every
+  Markdown file here, and on random documents built from lines both read alike,
+  and shows it parting from 0.11.0 on each shape above.
+
+### Changed
+
+- **Mutation testing in CI runs in eight shards**, not four. Three of the four
+  took 23 to 28 minutes on the sweep that merged this release's code, and the
+  fourth was cancelled at the 30-minute job limit. ADR-0003 has the per-file
+  minutes and the split; the longest of the eight took 16m16s.
+- **A pattern that cannot be read is refused.** An unclosed `[` or `{`, an
+  extended glob such as `+(a|b)` (a group holding a `|`: `C++(notes).md` and
+  `*(2017).md` are names with parentheses), a `..`, or a range that runs
+  backwards, in `glob`, `exclude`, `module`, `order`, `pattern`, `dirs` or
+  `required`, makes the directive invalid; in `exclude` in the configuration or `--exclude`, or in
+  a spec pattern, it is exit 2. Each used to be read as a literal or as whatever
+  its `RegExp` happened to mean, which is a filter that matches nothing and
+  passes. So is an alternative that names no path, as in `{dist/**,}`, whose
+  empty alternative matched the empty string. A brace group with a comma in it
+  in a directive is one more case: a list attribute splits on commas, so
+  `glob="*.{ts,tsx}"` was always the two patterns `*.{ts` and `tsx}`, and the
+  message now says so. A configuration's `exclude` is a JSON array, where braces
+  keep their commas. Nothing restores the old readings.
+  [ADR-0015](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0015-globs-from-spec-core.md).
+- **`**` inside a name is refused**: `docs/**.md`, `src/**.ts`, `**.ts`,
+  `a**b`. The message says what `**` means and gives the two ways to write
+  what was meant, `docs/**/*.md` for any depth and `*.md` for one level. It
+  used to cross directories under the scanner and not under ripgrep, so a rule
+  counted differently by engine; read as `*`, as `.gitignore` reads it,
+  `"specs": ["docs/**.md"]` would quietly have stopped finding every nested
+  document. In a directive the directive is invalid, in a draft as in a
+  document in force. A spec pattern is refused before any command starts: in
+  the configuration's `specs`, naming the file, and on the command line or in
+  `--spec`, for `query`, `impact`, `cites`, `prove` and `mcp` as for a run -
+  exit 2, as `exclude` in the configuration and `--exclude` are.
+  `specPatternError` is the check, for a caller of the API.
+- **A `.` or empty segment is no segment** (`src/./a.ts` is `src/a.ts`), and
+  **a leading `/` anchors a `glob`** at the root, as it anchors an `exclude`.
+  Both matched nothing in the scanner before; ripgrep already anchored.
+- **`archived` withholds a document**, a sixth word beside `draft`,
+  `proposed`, `rejected`, `deprecated` and `superseded`. `spec-brief` closes a
+  task brief's round by setting `status: archived` and moving the brief to an
+  archive directory. Its directives stated the round's premises and goals,
+  which are history once the round is closed, and executed anyway they failed.
+  An archived document is still parsed, validated and named in every output
+  format. `--ignore-status` executes it as before. The list stays closed:
+  `done`, `closed`, `archive` and every other near word stay in force, and
+  [ADR-0010](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0010-spec-status.md)'s amendment says why this word and
+  no other.
+- **A status is found by the scanner's headings and front-matter reader.**
+  The three spellings, their order and the words are unchanged, and every
+  status in the five spec-* repositories reads as it did. Where the scanner
+  reads a document differently, the status follows it:
+  - A `## Status` kept in a comment - a template not yet filled in - no longer
+    withholds the document, and a `##` in a comment or in code no longer ends
+    the preamble where the `**Status:**` label is read.
+  - An underlined heading is a heading. An underlined `Status` is the section,
+    and an underlined section ends the preamble, so a `status: draft` line with
+    `---` directly under it is a heading, as every renderer shows it, and not a
+    label.
+  - Front matter is read by spec-core's reader, the family's: a quoted value
+    to its closing quote and a plain one to a comment, as before. A value it
+    refuses declares nothing - a `: ` in a plain value, text after a closing
+    quote, a value continued on the next line, `*Draft*`, which YAML reads as
+    an alias - and a `status` nested under another key is that key's. Front
+    matter behind a byte-order mark, or closed by `...`, is read as front
+    matter.
+  - A front-matter `status` decides even when it cannot be read. A value the
+    reader refuses, an empty one, one with no word or a list leaves the
+    status unrecognised and the document in force, and the `## Status`
+    section and the `Status:` label are not read in its place: under 0.11.0
+    `status: "accepted" (2024-05-01)` was accepted, and falling through to a
+    section still saying `Proposed` would have withheld its rules. Every
+    format says so, on the key's line: a warning in the human report, a
+    `specWarnings` entry in `--json` (run and `prove`), a SARIF notification
+    and a `spec-warning` annotation for GitHub and GitLab.
+
+  [ADR-0010](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0010-spec-status.md)'s second amendment.
+- **A title is the first level-one heading as the scanner reads it.** An
+  underlined one (`===`) is a title and one kept in a comment is not; a code
+  span in it is kept as written, where it was blanked, and a comment in it is
+  dropped. A first level-one heading with no text leaves the document
+  untitled rather than promoting the next. In this repository one title
+  changed: ADR-0009's keeps its `` `--fix` ``.
+- **`maskCode` keeps a carriage return inside code**, where it blanked one:
+  every line terminator stays where it was, a lone `\r` included.
+- **Reading a spec costs about four times what it did**: 17 ms against 4 ms
+  over this repository's 18 ADRs, and 23 ms against 9 ms for a warm query of
+  one path, past the 20 ms ADR-0012 set out to meet. The scanner finds list
+  items, links and tables that nothing here reads.
+  [ADR-0002](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0002-directive-format.md)'s amendment says where the
+  remedy lies.
+- **The MCP server speaks the protocol through spec-core.** Classifying each
+  request, the two eras, dispatch, result shapes and the stdio framing are
+  spec-core's `jsonrpc` module, copied from `f085f29` and verified by hash;
+  `src/mcp.ts` keeps the instructions, the tools and the resources. What a
+  client sees is unchanged, and every test of the server passes as it was
+  written. One edge moved: a last line cut inside a UTF-8 character when stdin
+  closes is read as far as it goes rather than dropped. The protocol's names
+  are still exported from the package. [ADR-0015](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0015-globs-from-spec-core.md).
+- **API:**
+  - `createGlobMatcher`, `createExcludeMatcher` and `expandSpecPatterns` throw
+    for a pattern spec-core refuses - an unclosed `[` or `{`, an extended
+    glob, a `..`, `**` inside a name - naming the pattern, where they read it
+    as a literal or as whatever its `RegExp` meant. `globPatternError` and the
+    new `specPatternError` say why without throwing.
+  - `Annotation` has a required `identity`, which the GitLab fingerprint is
+    made of. `SpecSet` and `RunPlan` have required `warnings` and `masked`;
+    `RunReport` and `ProveReport` have optional `specWarnings` and
+    `maskedDirectives`, and `ParseResult` optional `warnings` and `masked`.
+    An `InactiveSpec`'s `directives` counts only those that resolve.
+  - New: `proveSpecGuard`, `PROVE_NAME`, `overlayIo` and `readOnce`;
+    `findCitations`, `findDocuments`, `deriveFamilies`, `scanCitations`,
+    `inComments`, `qualified`, `isStale`, `numberKey`, `documentNumber`,
+    `parseIdTemplate`, `parseFilesTemplate`, `citeIdError`, `citeFilesError`,
+    `CitesError` and `NUMBER`; `impactOf`, `impactDocument`, `dependentsOf`,
+    `buildReverseGraph`, `resolvePython`, `formatImpact`, `formatImpactJson`
+    and `ImpactError`; `formatProve`, `formatProveJson`, `formatProveSarif`,
+    `formatCites`, `formatCitesJson`, `formatCitesSarif`, `formatGitlab`,
+    `formatGithub`, `runAnnotations`, `proveAnnotations` and
+    `citesAnnotations`; `RUN_FORMAT_VERSION`, `QUERY_FORMAT_VERSION`,
+    `PROVE_FORMAT_VERSION`, `CITES_FORMAT_VERSION` and
+    `IMPACT_FORMAT_VERSION`; `globPatternError` and `specPatternError`; and
+    the types that go with them, `SpecWarning`, `MaskedDirective` and
+    `MaskedContext` among them.
+
 ## 0.11.0
 
 The literal this lexer never read. A JavaScript or TypeScript regular
@@ -12,7 +422,7 @@ expression can hold a quote — `/'/`, `/["']/`, `replace(/\/\//g, '')` — and
 without a rule for `/`, that quote opened a string that closed somewhere else
 entirely. Every text rule over a TypeScript project reads through this
 classifier, and this repository's own `src/parser.ts` was one of the files it
-lost its place in. [ADR-0006](docs/adr/0006-comment-classification.md).
+lost its place in. [ADR-0006](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0006-comment-classification.md).
 
 ### Fixed
 
@@ -44,9 +454,11 @@ lost its place in. [ADR-0006](docs/adr/0006-comment-classification.md).
   code from there. It used to run to the end of the file. This is what JSX text
   costs as well: `<p>Don't click</p>` opens a literal nothing closes, and it
   now costs that line rather than everything after it.
-- **`.sh`, `.bash` and `.zsh` report their profile as `shell`,** not
-  `shell-like`; `.yaml` and `.yml` report `yaml`. The name appears in
-  `--json` as each result's comment syntax.
+- **The `shell-like` profile split in two.** `.sh`, `.bash` and `.zsh` are
+  read as `shell`, `.yaml` and `.yml` as `yaml`, because their quoting
+  differs: a shell's quotes open mid-word and YAML's open only where a value
+  starts. The names themselves are internal — no output reports them — so what
+  changed for a caller is the reading, described above.
 
 Counts may move on a project that has any of these. A text rule over `.ts`,
 `.tsx`, `.yaml` or `.yml` can now see code it could not see before, and can
@@ -69,8 +481,8 @@ question asked per character has to be paid for per character.
 Fixes from running 0.10.2 over a Rust and .NET monorepo, where an import rule
 missed five `use` declarations in one crate and said nothing, and from probing
 every other language profile for the same mistake.
-[ADR-0006](docs/adr/0006-comment-classification.md),
-[ADR-0008](docs/adr/0008-polyglot-imports.md).
+[ADR-0006](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0006-comment-classification.md),
+[ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md).
 
 ### Fixed
 
@@ -118,8 +530,8 @@ regular expression literal holding a quote, `/["']/` - is recorded in ADR-0006.
 Fixes from running 0.10.1 over a .NET solution, where a layer rule passed while
 the domain imported the application, and from reading C# as it is written in
 2026 while fixing that.
-[ADR-0011](docs/adr/0011-layers-and-cycles.md),
-[ADR-0008](docs/adr/0008-polyglot-imports.md).
+[ADR-0011](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0011-layers-and-cycles.md),
+[ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md).
 
 ### Fixed
 
@@ -192,7 +604,7 @@ the domain imported the application, and from reading C# as it is written in
 
 Fixes from running 0.10.0 over a large monorepo, and from testing each exclude
 shape under both engines while making them.
-[ADR-0014](docs/adr/0014-configuration-and-watch.md).
+[ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md).
 
 ### Fixed
 
@@ -268,8 +680,8 @@ shape under both engines while making them.
 Improvements from running 0.9.2 over a large polyglot monorepo: a
 configuration a Rust, Go or .NET root can hold, exclusions a whole project
 shares, and a cycle rule that can leave lazy loading out.
-[ADR-0014](docs/adr/0014-configuration-and-watch.md),
-[ADR-0011](docs/adr/0011-layers-and-cycles.md).
+[ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md),
+[ADR-0011](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0011-layers-and-cycles.md).
 
 ### Added
 
@@ -333,7 +745,7 @@ shares, and a cycle rule that can leave lazy loading out.
     unanalysable, as does `/*` inside JSX text.
   - Tracking JSX text in general was turned down: a TypeScript cast or a
     generic arrow read as markup would skip real code without a word.
-    [ADR-0005](docs/adr/0005-import-assertions.md).
+    [ADR-0005](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0005-import-assertions.md).
 
 ## 0.9.1
 
@@ -349,13 +761,13 @@ shares, and a cycle rule that can leave lazy loading out.
   - `/>` anywhere else still starts a regular expression, so
     `replace(/>/g, '&gt;')` reads as before.
 
-  [ADR-0005](docs/adr/0005-import-assertions.md).
+  [ADR-0005](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0005-import-assertions.md).
 
 ## 0.9.0
 
 A project's policy can live in its `package.json`, and `spec-guard --watch`
 reports again as the tree changes, re-executing only the rules a change
-affected. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
+affected. [ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md).
 
 ### Added
 
@@ -423,7 +835,7 @@ affected. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
     reported every other shard's files with the previous sweep's verdicts. The
     merge refused that sweep.
   - No mutants were left out, the per-mutant timeout is unchanged, and the gate
-    is unchanged. [ADR-0003](docs/adr/0003-mutation-testing.md).
+    is unchanged. [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md).
 
 ### Fixed
 
@@ -445,7 +857,7 @@ affected. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
 
 An architecture document can now state conventions about names and layout: what
 the files in a directory are called, what every package holds, and which files
-come in pairs. [ADR-0013](docs/adr/0013-structure-assertions.md).
+come in pairs. [ADR-0013](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0013-structure-assertions.md).
 
 ### Added
 
@@ -496,7 +908,7 @@ come in pairs. [ADR-0013](docs/adr/0013-structure-assertions.md).
   had, less one in `glob.ts` that the new tests turned into a genuine hang. A
   local sweep had reported four survivors in the new listing cache as killed; CI
   found them, and they are tested. See
-  [ADR-0003](docs/adr/0003-mutation-testing.md).
+  [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md).
 
 ## 0.7.0
 
@@ -526,7 +938,7 @@ than every release, and it is fixed below.
   `types="ignore"` asks the runtime question. JavaScript and TypeScript only,
   because a cycle needs to know which file an import *is*; imports that should
   have become an edge and did not are reported, and fail under `--strict`.
-  See [ADR-0011](docs/adr/0011-layers-and-cycles.md) for the resolution table,
+  See [ADR-0011](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0011-layers-and-cycles.md) for the resolution table,
   and for why the other four languages are not in the graph.
 - `buildGraph`, `resolveReference`, `stronglyConnected`, `cyclicComponents`,
   `witness`, `checkLayers` and `referenceForms` are exported, with their types.
@@ -538,7 +950,7 @@ than every release, and it is fixed below.
   scripts. Rules in documents that are not in force are counted and named, and
   listed with `--ignore-status`. The arithmetic behind it is tested against the
   files a real run searches, under both engines and on random trees; see
-  [ADR-0012](docs/adr/0012-query-and-mcp.md) for the three things it cannot see.
+  [ADR-0012](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0012-query-and-mcp.md) for the three things it cannot see.
 - **`spec-guard mcp`** - a Model Context Protocol server on stdio, with no
   dependency on the MCP SDK. Tools `get_architectural_rules` (the query) and
   `check_architecture` (a run, narrowed to the rules governing given paths, each
@@ -588,7 +1000,7 @@ than every release, and it is fixed below.
   mutated build against the real one on thousands of random inputs. The query
   and the server (`query.ts`, `rules.ts`, `mcp.ts`, `specs.ts`) are all at 100%;
   most of the survivors found on the way were code nothing could observe, and it
-  was deleted. See [ADR-0003](docs/adr/0003-mutation-testing.md) for both
+  was deleted. See [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md) for both
   accounts, and for why one sweep's count is good to about three.
 - `version(manifest?)` takes the manifest to read, so its fallback for a broken
   install - `0.0.0` rather than a crash - is tested.
@@ -633,7 +1045,7 @@ making sure a rule that stops running can never look like a rule that passed.
   are still checked for typos, bad attributes and unresolvable values, so a
   draft's mistake is found on the day it is written rather than on the day
   everyone agrees the rule is right and stops looking at it.
-  See [ADR-0010](docs/adr/0010-spec-status.md), which also records why there is
+  See [ADR-0010](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0010-spec-status.md), which also records why there is
   no per-directive `if-status` attribute.
 - `--ignore-status` executes every directive whatever its document declares -
   how to ask whether a draft would pass if you accepted it today.
@@ -657,7 +1069,7 @@ making sure a rule that stops running can never look like a rule that passed.
   the whole suite per mutant, so on a loaded machine an unrelated test timing
   out is scored as a kill. Those patterns are now verified by applying every
   mutant by hand, `scripts/mutation-regex.mjs`, and the account is in
-  [ADR-0003](docs/adr/0003-mutation-testing.md).
+  [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md).
 
 ## 0.5.1
 
@@ -706,7 +1118,7 @@ new features, and nothing a user has to change.
   individually and produce byte-identical output, so that figure is the ceiling
   rather than a way-point — and 29 that were assumed equivalent turned out not
   to be, and are now tested. See
-  [ADR-0003](docs/adr/0003-mutation-testing.md), which also records a Stryker
+  [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md), which also records a Stryker
   limitation found on the way: a mutant that stops a test file *loading* is
   reported as survived even though the suite is killing it.
 - **`src/imports.ts` went from 73.74% to 95.89%.** The tokenizer was tested as a
@@ -744,13 +1156,13 @@ scope holds no files at all.
   Not four new tokenizers: the comment and string lexer from ADR-0006 masks the
   source and the readers work on what is left. Tree-sitter measured 94 MB
   unpacked against this package's 0.33 MB. See
-  [ADR-0008](docs/adr/0008-polyglot-imports.md).
+  [ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md).
 - **`baseline` and `ratchet`** on the absence assertions, for adopting a strict
   rule on a codebase that already breaks it. `baseline="src/legacy/a.ts:2"`
   names the debt by file and count. The ratchet is two-sided: new violations
   fail, and so does an entry the code no longer supports, because a baseline
   that only grows is an `exclude` with extra steps. `ratchet="one-way"` relaxes
-  the second half. See [ADR-0009](docs/adr/0009-debt-baselines.md).
+  the second half. See [ADR-0009](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0009-debt-baselines.md).
 - **`--print-baseline`** prints the attribute that would exempt today's
   violations, for a human to paste. It prints; it does not edit. That is the
   whole answer to `--fix`, and ADR-0009 argues it.
@@ -780,7 +1192,7 @@ scope holds no files at all.
   starts finding dependencies it previously reported as unanalysable.
 - **Mutation testing in CI runs in two tiers**: incremental on branches,
   a full authoritative sweep on `main` and nightly. The gate stays at 85 in
-  both. See [ADR-0003](docs/adr/0003-mutation-testing.md).
+  both. See [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md).
 
 ### Fixed
 
@@ -828,7 +1240,7 @@ found two and ripgrep found four, and neither said anything about the rest.
 - **The engines are one implementation.** ripgrep now answers only *which files
   contain this text*; the scanner does all counting, comment classification,
   binary handling and reporting for both. `--engine` changes how long a run
-  takes, not what it concludes. See [ADR-0007](docs/adr/0007-search-scope.md).
+  takes, not what it concludes. See [ADR-0007](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0007-search-scope.md).
 
 ### Added
 
@@ -867,7 +1279,7 @@ found two and ripgrep found four, and neither said anything about the rest.
   directions. A zero-dependency tokenizer resolves `import`, `export … from`,
   `import type`, dynamic `import()` with a literal, and `require()`. Module
   references it cannot resolve statically are reported, never counted as clean.
-  See [ADR-0005](docs/adr/0005-import-assertions.md).
+  See [ADR-0005](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0005-import-assertions.md).
 - **`comments` attribute.** See Changed, below.
 - **`--allow-missing-targets`** to restore the previous handling of a `target`
   path that does not exist.
@@ -883,7 +1295,7 @@ found two and ripgrep found four, and neither said anything about the rest.
   uncertain the text counts as code, and every run reports how many matches it
   excluded — a pass caused by comment exclusion is never silent.
   `comments="include"` restores counting per assertion.
-  See [ADR-0006](docs/adr/0006-comment-classification.md).
+  See [ADR-0006](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0006-comment-classification.md).
 - **A `target` path that does not exist now fails the run** instead of warning
   and searching what remained. An assertion pointed at a renamed directory used
   to search nothing, find nothing, and report success. `--allow-missing-targets`
@@ -919,9 +1331,9 @@ first published 0.3.0.
   enough for the JavaScript scanner to beat a ripgrep process spawn. The probe
   is the work — the enumeration it performs is reused by the scanner, so
   choosing costs nothing when the scanner wins.
-  See [ADR-0004](docs/adr/0004-adaptive-engine.md).
+  See [ADR-0004](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0004-adaptive-engine.md).
 - **Mutation testing** with Stryker, wired into CI on every push, plus the tests
-  that closed the gaps it exposed. See [ADR-0003](docs/adr/0003-mutation-testing.md).
+  that closed the gaps it exposed. See [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md).
 
 ### Changed