@descent-vtt/spec-guard 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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
@@ -55,7 +116,7 @@ counts. What can differ, and where this changelog says why:
   `--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](docs/adr/0018-impact.md).
+  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
@@ -85,7 +146,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0017-citations-in-comments.md).
+  [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,
@@ -100,7 +161,7 @@ counts. What can differ, and where this changelog says why:
   `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](docs/adr/0016-rules-seen-to-fail.md).
+  [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
@@ -110,7 +171,7 @@ counts. What can differ, and where this changelog says why:
   `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](docs/adr/0014-configuration-and-watch.md).
+  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
@@ -138,7 +199,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0002-directive-format.md)'s amendment.
+  [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
@@ -163,7 +224,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0015-globs-from-spec-core.md).
+  [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}`
@@ -179,7 +240,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0002-directive-format.md)'s amendment.
+  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
@@ -251,7 +312,7 @@ counts. What can differ, and where this changelog says why:
   `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](docs/adr/0015-globs-from-spec-core.md).
+  [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
@@ -275,7 +336,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0010-spec-status.md)'s amendment says why this word 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
@@ -305,7 +366,7 @@ counts. What can differ, and where this changelog says why:
     `specWarnings` entry in `--json` (run and `prove`), a SARIF notification
     and a `spec-warning` annotation for GitHub and GitLab.
 
-  [ADR-0010](docs/adr/0010-spec-status.md)'s second amendment.
+  [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
@@ -318,7 +379,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0002-directive-format.md)'s amendment says where the
+  [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
@@ -327,7 +388,7 @@ counts. What can differ, and where this changelog says why:
   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](docs/adr/0015-globs-from-spec-core.md).
+  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
@@ -361,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
 
@@ -420,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
 
@@ -469,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
 
@@ -543,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
 
@@ -619,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
 
@@ -684,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
 
@@ -700,13 +761,13 @@ shares, and a cycle rule that can leave lazy loading out.
   - `/>` anywhere else still starts a regular expression, so
     `replace(/>/g, '>')` 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
 
@@ -774,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
 
@@ -796,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
 
@@ -847,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
 
@@ -877,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.
@@ -889,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
@@ -939,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.
@@ -984,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.
@@ -1008,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
 
@@ -1057,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
@@ -1095,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.
@@ -1131,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
 
@@ -1179,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
 
@@ -1218,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.
@@ -1234,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`
@@ -1270,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
 

package/README.md

@@ -331,9 +331,9 @@ These read the dependency rather than the text, in **five languages**:
 No parser and no new dependency. JavaScript gets a full tokenizer because a
 module reference can appear anywhere in an expression; the other four are read
 by masking comments and string literals with the classifier from
-[ADR-0006](docs/adr/0006-comment-classification.md) and then reading statements
+[ADR-0006](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0006-comment-classification.md) and then reading statements
 off what is left. Tree-sitter would have cost 94 MB unpacked against this
-package's 0.33 MB - [ADR-0008](docs/adr/0008-polyglot-imports.md) has the
+package's 0.33 MB - [ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md) has the
 measurements, and the list of things a real parser would genuinely see that
 this does not.
 
@@ -384,7 +384,7 @@ and reported too, so a rule pointed at the wrong tree says "analysed 2 of 3
 files; 1 is in a language whose imports spec-guard cannot read (.razor)" rather than quietly passing - and if *none* of them can be read, the
 assertion fails rather than passing on an empty analysis.
 
-[ADR-0005](docs/adr/0005-import-assertions.md) has the measurements and the
+[ADR-0005](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0005-import-assertions.md) has the measurements and the
 reasoning behind each boundary.
 
 ### `@assert-layers` - dependencies point one way
@@ -546,7 +546,7 @@ did not - a relative path matching no file, or an alias like `@/db` or
 `--strict`. An alias spelled like a real package, `@app/db` through `tsconfig`
 paths, is the one thing it cannot see and cannot report: that would mean
 reading `tsconfig.json`, which is the resolver
-[ADR-0011](docs/adr/0011-layers-and-cycles.md) declines to become, for the
+[ADR-0011](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0011-layers-and-cycles.md) declines to become, for the
 reasons it gives.
 
 ### `@assert-structure` - what files are called, and what comes with them
@@ -639,7 +639,7 @@ src/handlers/invoice.ts (does not exist yet)
       partner: src/handlers/invoice.test.ts
 ```
 
-[ADR-0013](docs/adr/0013-structure-assertions.md) has the design and what it
+[ADR-0013](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0013-structure-assertions.md) has the design and what it
 costs.
 
 ### `@assert-present` - this file exists
@@ -741,7 +741,7 @@ spec-guard docs/adr.md --print-baseline
 ```
 
 prints the attribute that would exempt exactly today's violations, for you to
-paste in. It prints; it does not edit. [ADR-0009](docs/adr/0009-debt-baselines.md)
+paste in. It prints; it does not edit. [ADR-0009](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0009-debt-baselines.md)
 explains why that distinction is the whole design, and why there is no `--fix`
 for architecture rules.
 
@@ -806,7 +806,7 @@ found on the day it is written rather than on the day it is accepted.
 `--ignore-status` runs everything, which is how you ask whether a draft would
 pass if you accepted it today.
 
-[ADR-0010](docs/adr/0010-spec-status.md) has the full reasoning, including why
+[ADR-0010](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0010-spec-status.md) has the full reasoning, including why
 there is no per-directive `if-status` attribute.
 
 ## Asking before writing - `query` and the MCP server
@@ -863,7 +863,7 @@ project's does not.
 
 The arithmetic that decides whether a rule governs a path is tested against the
 walk a real run makes, file for file, under both engines and on randomly
-generated trees. [ADR-0012](docs/adr/0012-query-and-mcp.md) lists the three
+generated trees. [ADR-0012](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0012-query-and-mcp.md) lists the three
 things it cannot see: file content (binary, oversized, unreadable), symbolic
 links, and letter case on case-insensitive filesystems.
 
@@ -958,7 +958,7 @@ 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
+file imports `./db.js`. [ADR-0016](https://github.com/DescentVTT/spec-guard/blob/main/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`
@@ -1026,7 +1026,7 @@ 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
+[ADR-0017](https://github.com/DescentVTT/spec-guard/blob/main/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`
@@ -1063,7 +1063,7 @@ src/db/client.ts
 ```
 
 - **Followed**: relative JavaScript and TypeScript imports, by the table the
-  cycle rule uses ([ADR-0011](docs/adr/0011-layers-and-cycles.md)), and relative
+  cycle rule uses ([ADR-0011](https://github.com/DescentVTT/spec-guard/blob/main/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`,
@@ -1081,7 +1081,7 @@ force, which are otherwise counted, as `query` does. `--json` is versioned by
 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.
+[ADR-0018](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0018-impact.md) has the table and what it leaves out.
 
 ## CLI
 
@@ -1220,7 +1220,7 @@ pure function of a file's bytes - tokenizing, comment masking, scanning - is
 remembered by the bytes' hash. Each of those is a way to report a tree that no
 longer exists, so a test changes trees at random and requires every report a
 session gives to equal a fresh run's, with six deliberately broken sessions
-that it has to catch. [ADR-0014](docs/adr/0014-configuration-and-watch.md) has
+that it has to catch. [ADR-0014](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0014-configuration-and-watch.md) has
 the design, the measurements and the limits.
 
 On this repository, from a change to the report, in the quietest of four runs
@@ -1403,7 +1403,7 @@ exceeds a budget, in which case ripgrep takes over. The crossover above sits
 between 500 and 1,000 files, which is what the Windows budget of 512 encodes;
 on Linux it is far lower, because what is really being measured is process
 spawn cost. `scripts/bench-engines.mjs` reproduces this, and
-[ADR-0004](docs/adr/0004-adaptive-engine.md) has the full tables.
+[ADR-0004](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0004-adaptive-engine.md) has the full tables.
 
 Treat single measurements from one machine with suspicion. On the development
 machine used here, an absence assertion over 2,000 files measures 303 ms with
@@ -1514,6 +1514,13 @@ and is there for a caller who wants to try a change of its own.
 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.
 
+A process that reads the specs again for every request, as the MCP server
+does, can keep what it parsed: pass one `createDocumentMemo()` as `documents`
+to `runSpecGuard`, `loadRuleSet`, `queryRules` or `impactOf`, every time. Every
+spec is still found and read, so an edit is seen by the next call; a document
+whose bytes have not changed is not parsed again, and the memo holds only the
+documents of the spec set read last. A single run gains nothing from one.
+
 ## Design decisions
 
 This tool was specified loosely and built opinionatedly. Where the
@@ -1539,7 +1546,7 @@ 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
+stay exact. [ADR-0002](https://github.com/DescentVTT/spec-guard/blob/main/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 -
@@ -1587,7 +1594,7 @@ 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)).
+automaton reads it ([ADR-0015](https://github.com/DescentVTT/spec-guard/blob/main/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.
@@ -1604,11 +1611,11 @@ forbidden symbol sat in `.github/workflows/ci.yml`; the scanner and ripgrep also
 disagreed with each other, finding two matches and four on the same tree. Scope
 is now one policy that both engines are driven by, the skip list is four names
 long, and anything spec-guard could not inspect is reported rather than assumed
-clean ([ADR-0007](docs/adr/0007-search-scope.md)).
+clean ([ADR-0007](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0007-search-scope.md)).
 
 **Comments are excluded by default, and the exclusion is reported.** Counting
 the note that records a deletion as an occurrence of the thing deleted punishes
-the documentation this tool exists to keep honest ([ADR-0006](docs/adr/0006-comment-classification.md)).
+the documentation this tool exists to keep honest ([ADR-0006](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0006-comment-classification.md)).
 The reverse risk — a rule that quietly stops checking anything because every
 match now sits in a comment — is why every run says how many matches it dropped.
 
@@ -1625,19 +1632,19 @@ comment and string lexer that already existed, masking the source with it, and
 reading statements off what is left. Tree-sitter would have been the modern
 answer and costs 94 MB unpacked against this package's 0.33 MB; the four things
 a real parser would genuinely see that this cannot are listed in
-[ADR-0008](docs/adr/0008-polyglot-imports.md) rather than glossed over.
+[ADR-0008](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0008-polyglot-imports.md) rather than glossed over.
 
 **There is no `--fix`.** Every edit a machine can make to a failing boundary
 assertion is an edit that records the rule no longer holding: widen the bound,
 add an exclusion, append to the baseline, insert an ignore comment. A one-flag
 path from red to green is a bad button for a person and a much worse one for an
 agent whose loop terminates on a green build. `--print-baseline` prints what you
-could paste; it does not paste it ([ADR-0009](docs/adr/0009-debt-baselines.md)).
+could paste; it does not paste it ([ADR-0009](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0009-debt-baselines.md)).
 
 ## spec-guard checks itself
 
-The invariants in [`docs/adr/0001-invariants.md`](docs/adr/0001-invariants.md)
-and [`docs/adr/0002-directive-format.md`](docs/adr/0002-directive-format.md) are
+The invariants in [`docs/adr/0001-invariants.md`](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0001-invariants.md)
+and [`docs/adr/0002-directive-format.md`](https://github.com/DescentVTT/spec-guard/blob/main/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
@@ -1671,13 +1678,13 @@ 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.20%** of 11,537 mutants are killed in CI, with 89 survivors and
+**100%**, and **99.20%** of 11,549 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.
 Each release since has replayed the survivors its own code added before it
 shipped: they were killed, deleted as dead code, or shown equivalent and
-recorded in [ADR-0003](docs/adr/0003-mutation-testing.md) with the evidence.
+recorded in [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md) with the evidence.
 
 That gap is the point. The first run scored 77.23%, and the weakest file was the
 reporter at 65.48% - not because it lacked tests, but because its tests were
@@ -1706,7 +1713,7 @@ applied one at a time and run through a fingerprint of 4,176 observations, and
 that only matters when a second statement follows, a type-only test that marks
 `import A, { B } from 'x'` type-only when loosened, a comment check that opens a
 block comment on `2*3`. All 29 are now tested and all 29 die. All of it is in
-[ADR-0003](docs/adr/0003-mutation-testing.md), including a Stryker limitation
+[ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md), including a Stryker limitation
 found on the way: a mutant that stops a test file *loading* is reported as
 survived even though the suite is in fact killing it.
 
@@ -1734,7 +1741,7 @@ suite takes hours against 43 minutes of hosted time, and it scores *higher*,
 because far more mutants hang there and Stryker counts a hang as a kill. Linux
 CI is the measurement.
 
-Eight cautionary tales are in [ADR-0003](docs/adr/0003-mutation-testing.md): a
+Eight cautionary tales are in [ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md): a
 run whose score was pure fiction because the mutants were never activated, a
 tuning knob that lifted the score six points without adding a test, the platform
 gap above, the baseline being re-anchored when a tokenizer arrived, and a score
@@ -1757,7 +1764,7 @@ 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:
+[`release.yml`](https://github.com/DescentVTT/spec-guard/blob/main/.github/workflows/release.yml) then:
 
 1. refuses the release unless the tag, `package.json` and a `## <version>`
    heading in `CHANGELOG.md` all agree;

package/dist/index.d.ts

@@ -50,8 +50,8 @@ export type { Listing, StructureCheck, StructureRequest, StructureViolation, Tre
 export { lineStarts, locate, maskRanges } from './text.js';
 export { maskCode, parseAttributes, parseDirectives, parseDocument, parseStatus, parseTitle, INACTIVE_STATUSES } from './parser.js';
 export type { ParseContext, ParsedDocument } from './parser.js';
-export { readSpecs, specPath } from './specs.js';
-export type { SpecDocument, SpecSet } from './specs.js';
+export { createDocumentMemo, readSpecs, specPath } from './specs.js';
+export type { DocumentMemo, SpecDocument, SpecSet } from './specs.js';
 export { governs, layerPosition, leftOutByOwnExclude, viewRule, within } from './rules.js';
 export type { DocumentView, LayerPosition, PathShape, QueryPath, RuleView } from './rules.js';
 export { answerQuery, formatQuery, formatQueryJson, inQueriedPaths, loadRuleSet, queryRules, resolveQueryPath, viewDocument, QueryPathError, QUERY_FORMAT_VERSION, } from './query.js';