@descent-vtt/spec-graph 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -3,6 +3,451 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 0.9.1
+
+Nothing to do on upgrading. The same documents give the same findings, in
+every format, and the same graph exports as they did under 0.9.0; the one
+difference a program that imports spec-graph can see is a badge wrapped in a
+link, which `ScannedDocument.links` now lists. The scanner is spec-core
+8840d36, the README's and this changelog's links to the ADRs work on
+npmjs.com and in `node_modules`, and `npm publish` refuses to run from a
+checkout.
+
+### Changed
+
+- **spec-core 8840d36.** An image inside a link's text, a badge wrapped in a
+  link such as `[![build](badge.svg)](actions)`, is listed in
+  `ScannedDocument.links` after the link around it, where CommonMark renders
+  it; the scan used to skip it. spec-graph reads no image as a reference but a
+  wiki embed, so no finding and no edge moves: run over the same documents,
+  this repository's, its fixtures' and the rest of the family's, every `check`
+  format and every graph export is byte for byte what 0.9.0 wrote. A program
+  that reads `links` for images sees the badges it missed. `links`,
+  `listItems` and `masks.directives` are made the first time they are read,
+  and kept, rather than for every document; they hold what they held.
+- `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.
+
+### Fixed
+
+- The README's and this changelog's links to the ADRs and to `CLAUDE.md` were
+  relative, and the package ships neither, so on npmjs.com and inside
+  `node_modules` they led nowhere. They are GitHub URLs now. A test holds
+  every link in a shipped document to a file the package ships or to an
+  absolute URL, and every URL into this repository to a file it holds.
+
+## 0.9.0
+
+Versions are staged by CI from a `v*` tag, through npm's trusted
+publishing, and released by a maintainer with a second factor, no longer
+published from a workstation
+([ADR-0021](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0021-releases-are-published-by-ci.md)). There is no
+publish token anywhere, and every version from here on carries a provenance
+attestation naming the repository, the commit and the run that built the
+tarball. `npm audit signatures` checks it without taking anyone's word for
+anything. 0.2.0 to 0.8.0 have none and never will.
+
+**What to expect on upgrading.** More findings rather than fewer, and nearly
+all of them from one change: a code span ends with its paragraph. Over a large
+repository of hand-written decisions and logs that 0.8.0 checked, almost every
+difference was a `broken-reference`. Bare identifiers that a lone backtick
+earlier in a paragraph or a table had hidden are read now, and many name
+nothing; a few that 0.8.0 read out of real code spans, its backticks out of
+step, are code again and go. Text read for the first time can hold a relation,
+and bring a `stale-premise` or a `ghost-handover` with it, and a relation read
+out of code can take an `unreciprocated-supersession` away with it. A
+paragraph indented four columns past its list item's text after a blank line
+is code now, as CommonMark reads it, and as GitHub renders it: eleven of this
+repository's ADRs had answers written that way, and they are re-indented as
+paragraphs of their items. The glob, `archived` and front-matter
+changes are narrower, and each is described below; a pattern the dialect
+refuses stops the run with exit `2` and says how to write it. Under
+`--ratchet`, expect to record the baseline once; "What a baseline sees", under
+Changed, lists the entries that go stale.
+
+### Added
+
+**`--format gitlab`**, the Code Quality report a GitLab merge request reads,
+so the family is not GitHub's alone. `check` only, like SARIF. One issue per
+finding: the rule as `check_name`, message and hint as `description`, the file
+and line as `location`, and a `fingerprint` that is a SHA-256 of the rule,
+the specification and what within it - the identity a baseline counts by. No
+line, so moving a paragraph does not make a finding new, and no message, whose
+counts move when one of three boxes is ticked; a second finding identical in
+all three is told apart by its order.
+`error` is `critical`, or `major` when only `--strict` made it an error;
+`warn` is `minor` and `info` is `info`. The README has the job to add. See
+[ADR-0015](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+
+### Breaking (library API)
+
+The command line changes only as the sections below describe. A program that
+imports spec-graph sees these as well:
+
+- **`ScannedDocument.masked` is gone.** `ScannedDocument` is spec-core's
+  `MarkdownScan`, and the masked copy is `masks.structure`, beside
+  `masks.prose` and `masks.directives`.
+- **`ScannedDocument.lines` holds the front matter's lines**, flagged
+  `frontMatter`, where it began at the body. Code that numbers or reads body
+  lines from it skips those.
+- **`ScannedDocument.links` holds images**, flagged `Link.image`. Code that
+  reads it for citations filters them out, as the analysis does but for a wiki
+  embed.
+- **Required fields are new**, so an object built by hand needs them:
+  `ScannedLine` has `frontMatter`, `html` and `comment`; `FrontMatter` has
+  `kind` and `closeLine`; `Link` has `image` and `targetEnd`; `Heading` has
+  `form`, `anchor`, `textStart`, `textEnd` and `endLine`; `ListItem` has
+  `endLine` and `quoteDepth`; `HtmlComment` has `closed`; `DocumentNode` has
+  `history`.
+- **An error from `compilePattern` is named `RegexError`.** `PatternError` is
+  the same class, so `instanceof` holds; a check of `error.name` against
+  `'PatternError'` does not.
+- **`createReferenceFilter` throws on a blank pattern**, which it used to drop,
+  and `compileGlob`, `createGlobMatcher` and `walkFiles` throw on every
+  pattern the dialect refuses.
+
+`ParseProblem` has `unread`, and it is optional.
+
+### Changed
+
+**The matcher behind `~=` is spec-core's.** It moved, unchanged, to spec-core -
+the library the spec-* tools share - and is copied back into
+`src/vendor/spec-core/`, byte for byte and checked against the SHA-256 it was
+copied with, so spec-graph still installs nothing. The package carries the
+copies compiled, and spec-core's MIT notice with them, as
+`src/vendor/spec-core/LICENSE`. A selector reads exactly as
+before. `compilePattern` and `PatternError` are still exported and are the same
+function and class; a caught error's `name` is now `RegexError`. The tests that
+hold the matcher to `RegExp` moved with it, and the copy is left out of this
+repository's mutation sweep and coverage, which spec-core's measure instead.
+See [ADR-0017](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0017-a-predicate-must-finish.md).
+
+**Globs are the dialect every spec-* tool reads.** The patterns to check,
+`--ignore`, `--history` and `historyPatterns` are compiled by spec-core's glob
+engine, in the `path` dialect spec-brief and spec-guard read too, so a scope
+means the same thing to each of them. Where that reading differs from
+spec-graph's old one, a repository will see it:
+
+- **Case is respected on every host.** `Docs/**` matched `docs/a.md` on Windows
+  and nowhere else, so one repository gave one answer on a Windows checkout and
+  another in CI. And a pattern with no glob syntax was compared lower-cased on
+  every host, Linux included: `README.md` also took `readme.md`. Neither folds
+  now, and `compileGlob`'s `ignoreCase` is off unless asked for on any host.
+- **`**` inside a name is refused.** `docs/**.md`, `**.ts` and `a**b` crossed
+  directories wherever the `**` was written. `**` means any number of
+  directories only as a whole segment now, and the error says so: write
+  `docs/**/*.md` for any depth, as it always read, or `*.md` for one level.
+- **An extended glob is refused.** `+(a|b)` was the literal text `+(a|b)`, a
+  scope that matched nothing; the error says to write `{a,b}`, and `[(]` for a
+  parenthesis. A group is an extended glob only when it holds a `|`, so
+  `C++(notes).md` and `books/*(2017).md` are names with parentheses in them,
+  as they were.
+- **An unclosed `[` is an error**, like an unclosed `{` always was. It was a
+  literal `[`, which made the pattern a scope that matched nothing. The run
+  stops with exit `2` and names the pattern, from the command line or from the
+  configuration file.
+- **A trailing `/` means the directory's contents.** It was normalised away, so
+  `drafts*/` named a file called `drafts`, and `docs/` took `docs` itself.
+- **Braces expand to literals.** `{docs,specs}` was a glob matching two names
+  exactly; it is two literals now, each a directory and what it holds.
+- **A class never matches `/`**, and **`[^a]` negates**, as `[!a]` does. `a[!b]c`
+  took `a/c`, and `[^a]` was the class of `^` and `a`.
+- **A pattern must name a path under the root.** `.` and `./` are refused
+  rather than read as nothing, and so is a `..` anywhere in a pattern:
+  `docs/../specs` was resolved to `specs`, and `../other/**` walked outside
+  the root. A `.` segment inside a pattern is dropped, as it was. A `..` typed
+  below the root is resolved against where it was typed, so
+  `spec-graph "../*.md"` in `docs/deep` still means `docs/*.md`.
+- **An empty pattern is refused**, in every list: the patterns to check,
+  `--ignore`, `--history`, `--ignore-ref` and their keys in the configuration
+  file. Each was read as nothing, or dropped - an unset variable in
+  `--history "$LOGS"` checked the logs as specifications, and nothing said
+  why. A pattern of spaces is empty to `--ignore-ref`, which trims what it
+  reads, and a name to the others.
+- **The walk finds a directory only as it is spelled on disk.** It starts at a
+  pattern's literal prefix, and on a filesystem that ignores case `Docs/` found
+  `docs/` and reported its files as `Docs/...`. A pattern rooted at `/` is not
+  walked under the root either, where it reported paths like `/docs/a.md`.
+
+`--ignore-ref` runs on the same engine and keeps its own reading, since a
+reference target is not a path: a bare pattern matches one target exactly, case
+is ignored on every host, `.` and `..` are the text of the link, and a `\`
+escapes the next character rather than being matched as itself. The glob
+changes above apply to it otherwise, and three more come with the syntax: a `\`
+before a letter or digit, or at the end, is refused, as is a leading `!` - both
+were literals, and `--ignore-ref` has no list to take a pattern back out of -
+and `a//b` reads as `a/b`.
+
+`globToRegExp` is deprecated, and stays as the old reading that the test of
+every difference above runs against; it no longer folds case on Windows. See
+[ADR-0022](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0022-globs-are-the-family-path-dialect.md).
+
+**Documents are read by spec-core's scanner.** It moved to spec-core, built on
+this repository's scanner as its model, and is copied back into
+`src/vendor/spec-core/` and checked by hash, so spec-graph still installs
+nothing. It follows CommonMark wherever CommonMark decides what is code or a
+comment, and where that reads a document differently from before, spec-graph
+follows it. Over this repository, its test corpora and spec-core's documents,
+the graph and the findings are what they were. A repository sees a difference
+where it wrote one of these:
+
+- **A code span ends with its paragraph.** A lone backtick hid everything up to
+  the next run of its length, however many paragraphs on, citations included.
+- **A heading reads as a renderer shows it.** A comment on its line is not part
+  of its text, and `# C#` is about `C#`: a closing run of `#` needs a space
+  before it. That text is a document's title, a section's name and the slug in
+  the id of every item under it, so an item under `## Notes <!-- x -->` moves
+  from `ADR-0001#notes----x---.1` to `ADR-0001#notes.1`, and
+  `## Open Questions <!-- short -->` holds obligations at last. A baseline does
+  not notice the move: an entry names the specification and what within it,
+  never an item.
+- **A link to GitHub's anchor for a repeated heading resolves.** GitHub renders
+  the second `## Notes` as `#notes-1`, and a link to it was a
+  `broken-reference`. The slug still names the first heading, and `#notes-2`
+  beside two headings is still broken.
+- **Nothing inside `<pre>`, `<script>`, `<style>` or `<textarea>` is
+  structure.** Their links were masked already; now no heading, list item, table
+  or `Status:` line is read from one either, so `- [ ] example` in a `<pre>`
+  block is not an open obligation, and a status section that opens with one
+  declares no status. A `@spec-item` above one does not reach an item below it,
+  as it never reached across a fence.
+- **Nothing inside a comment opens a block.** A fence inside a comment opened
+  one, and with no closer everything after it was code; a list marker inside one
+  decided whether an indented block after it was code. Neither does now. A
+  comment that opens a line and never closes runs to the end of the document, as
+  it renders, and a parse problem says where it opened; no directive is read from
+  it, so a stray `<!-- @spec-ignore` does not drop the file.
+- **Headings, rules and list items as CommonMark reads them.** A setext underline
+  is not used twice - `Title`, `===`, `---` is one heading and a rule, not a
+  second heading called `===` - and does not underline a line in a block quote.
+  `* * *` is a rule, not a list item. A list item ends at a fence or a block
+  quote no deeper than its marker, so a relation written after an unindented
+  fence is the document's and not the item's. And a heading closes every list,
+  so an item indented under a list a heading closed is at depth 0, and an
+  obligation when its section holds them.
+- **Links as CommonMark reads them.** `[a](b c)` is text, not a link to `b`.
+  `[foo](not a link)` is the shortcut `[foo]` when `foo` is defined, not a link
+  to `not`. A footnote `[^1]: text` and a line `[Note]: prose` are not
+  definitions, so `[^1]` and `[Note]` are no longer links to the first word
+  after them, which were broken references. A link inside brackets that are not
+  one, `[see [ADR-7](0007.md) here]`, is read. Labels match with case and
+  whitespace folded, so `[Two  Words][]` finds `[TWO WORDS]:`. A finding on
+  `[a](<b c.md>)` points inside the angle brackets, a column later than it did.
+- **A table needs a delimiter row with as many cells as its header.** One
+  without was read as a table, and as a register when its columns said so.
+- **A fence ends with its block quote.** One opened in a quote and never closed
+  made the rest of the document code.
+- **Indented code is four columns past its container**: the margin, or the text
+  of the list item the line is in. Inside a list four columns were never code,
+  so a link or a checkbox in an example indented under an item was read as one.
+  Under `- item`, six columns after a blank line are code now, and four are
+  still the item's text. A fence line that deep opens no fence - after a blank
+  line it is indented code, and under a paragraph it is text - where it used to
+  open one at any depth and, unclosed, run to the end of the document.
+- **Front matter opens on exactly `---` or `+++`, and closes on exactly
+  `---`, `...` or `+++`.** `----` is a rule. And `----` or `....` under an
+  opening `---` closed the block, and now leaves it open: a block that never
+  closes is read as a rule and Markdown, none of its keys are read, and a parse
+  problem says where it opened.
+
+**What a baseline sees.** A finding the scan no longer produces leaves its
+entry no longer occurring, which fails a run under `--ratchet`. These go: the
+first word of a footnote `[^1]: See ...` or a line `[Note]: prose`, which was
+a broken reference; the `b` of `[a](b c)` and the `not` of
+`[foo](not a link)`; a link to GitHub's `#notes-1`, which was an unknown
+anchor; an `orphaned-obligation` made of boxes held in `<pre>` or in a
+comment; a link inside a code span that a lone backtick earlier in the document
+had knocked out of step, so that it read as text; and a link in an example
+indented under a list item. One `--record-baseline` settles them. What the scan
+sees now and did not - a citation a lone backtick hid, an obligation under a
+heading with a comment on its line, what followed a fence indented under a
+paragraph, the shortcut `[foo]` - is a new finding, as any other is.
+
+For the library API, the scanner's types are spec-core's, exported under the
+names they had, and what that breaks is listed under
+[Breaking (library API)](#breaking-library-api). Beside it, `blocks`,
+`codeSpans` and `bom` are new on `ScannedDocument`, and
+`isMasked(offset, mask?)` asks any of its three masks. The analysis leaves
+images out but for wiki embeds. `parseDirectives` skips a comment whose
+`closed` is `false`. `createLineIndex` is spec-core's, the same table. See
+[ADR-0023](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0023-the-scanner-is-the-familys.md).
+
+**Front matter is read by spec-core's reader, and what it does not read says
+why.** Keys are compared in lower case and one level of nesting is read as
+`parent.child`, as before. Where the reader and YAML part from the old one:
+
+- **A value YAML does not say is not read.** A plain value holding `: ` -
+  `title: ADR-7: Sharding`, which YAML reads as an error - a value continued onto
+  the next line, which was read as its first line, a block scalar, an anchor and
+  a tag are left out rather than guessed at. Quote the value and it is read. An
+  inline list on the line under its key, `translators:` over an indented `[]`,
+  is left out too, with the advice to write it after the colon, since quoting it
+  would make it a string. Each is a parse problem at the value, under
+  `--verbose` and in `--format json`, naming the reason; so are a line that is
+  not `key: value`, a key written twice, of which the last still wins, and TOML
+  front matter, which was read as nothing in silence. A status left out this way
+  is looked for in a `## Status` section, as a missing one always was.
+- **What the graph lost is counted without `--verbose`.** A status, an id, an
+  alias or a relation left out - or a block never closed, or a line that belongs
+  to no key - can turn a failing check into a passing one:
+  `status: Superseded by ADR-3: see notes` reads as unknown, and the
+  supersession finding 0.8.0 reported is gone. So a run without `--verbose` prints one
+  line above its verdict, `! 2 front-matter values not read - see --verbose`, in
+  the terminal and in `--format markdown`. It is not a finding and does not
+  change the exit code. A title or a description left out is not counted.
+  `ParseProblem` says which problems count, as `unread`.
+- **A key indented under nothing is not read.** `status: accepted` indented on
+  the first line of front matter is valid YAML, and 0.8.0 read it. It is a line
+  that belongs to no key now, so the document reads as `unknown`, and the count
+  of values not read includes it. Write the key at the margin.
+- **A list written at its key's own indentation is a list.** `deps:` over
+  `- ADR-1` was an empty value.
+- **Quoted values are YAML's.** `'it''s'` is `it's`, and `"a\tb"` holds a tab.
+
+`parseFrontMatter` keeps its signature and reads with spec-core's reader, so it
+leaves out what the reader does not read. See
+[ADR-0023](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0023-the-scanner-is-the-familys.md).
+
+**`archived` is a record, not a retired decision.** spec-brief closes a round
+of work by writing `status: archived` and moving the brief to an archive
+directory, and every spec-* tool reads that word as a finished round which it
+is normal to depend on. spec-graph read it as retired: a live brief that
+depended on an archived one was reported as a `stale-premise`, and an archived
+brief with a task left unticked as an `orphaned-obligation`. It is the `record`
+phase now, as a file declared by `historyPatterns` is - its links are still
+checked, its unticked boxes are nobody's work and leave the open count, and
+live work handed to it is still a `ghost-handover`, which says it is archived.
+So is the status word `archive`.
+
+It is a closed round and not a log, so that is all that changes. The claims an
+archived document makes are still checked as they were when it read as
+retired: a supersession it declares (`live-supersession` on what it
+supersedes), a cycle it closes (`circular-delegation`) and a link to itself
+(`self-reference`). What it hands on and what it rests on are still not held
+against it. An archived document that something supersedes and that never
+says so is an `unreciprocated-supersession`, whose hint is now to make its
+status `archived, superseded by X` - which retires it, so what depends on it
+is a `stale-premise` again. A document declared by `historyPatterns` or
+`<!-- @spec-history -->` is exempt from all of it, as before; `DocumentNode`
+says which kind of record a document is, as `history`.
+
+A document still retires by saying `superseded`, `deprecated` or `retired`,
+and `archived, superseded by B-7` is retired, since a retirement word wins
+wherever it is written. A document under an `archive/` directory that declares
+no status is retired as before. A repository that wrote `archived` for a
+retired decision loses the `stale-premise` findings on documents that depend
+on it, and the `orphaned-obligation` findings on its open items, and a baseline
+that accepted one reports that entry as no longer occurring, which fails a run
+under `--ratchet`. See
+[ADR-0011](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0011-a-record-is-not-a-specification.md).
+
+### Fixed
+
+**A code span that mentions a comment is code.** ``Use `<!--` to open one``
+opened an HTML comment at the `<!--`, and it ran to the next `-->` anywhere in
+the document: every heading, citation and link in between went into it, and a
+link to a file that does not exist went unreported. Comments were found first
+and code spans after, so the span never had a say. Both are now found in one
+pass, left to right, and whichever opens first wins, which is how CommonMark
+reads them: a `<!--` inside a span is text, and so is a backtick inside a
+comment. A span still closes only on a run of its own length, and an escaped
+backtick still opens none.
+
+The same defect read a directive quoted in inline code as a directive. This
+repository's README and ADR-0011 both write `` `<!-- @spec-history -->` `` in a
+sentence, and both were being checked as historical records. They are a
+document and an accepted decision again, and `selfcheck` counts one more open
+obligation than it did, because ADR-0011's open question is no longer exempt. A document quoting `<!-- @spec-ignore -->` that way was skipped whole,
+and is checked now.
+
+**Unclosed backtick runs cost the document's length once, not once each.** Each
+searched the rest of the document for its closer, so a line of runs of different
+lengths made the scan grow as the length to the power 1.5: 2 MB took fifteen
+seconds. The first search that fails now keeps what it saw, and the same 2 MB
+takes about sixty milliseconds.
+
+**What a comment holds is not structure.** Headings, list items and tables are
+read from lines, and none of them asked whether the line was inside a comment.
+`## Hidden` in `<!-- -->` was a heading and started a section, a checklist
+commented out was a list of open obligations nobody could see, and
+`<!-- note -->` over `---` was a heading called "<!-- note -->". A line whose
+first character is inside a comment is now none of these, and cannot end a list
+item either; `ScannedLine` says so as `comment`. Directives are read out of
+comments exactly as before.
+
+Nor is a status read out of one. Under `## Status`, a template's
+`<!-- proposed | accepted -->` was taken as the status - which no vocabulary
+knows, so the phase was `unknown` with `Accepted` on the next line - and a
+commented-out `Status: proposed` gave a register's section the second signal it
+needs to become a specification.
+
+An obligation that was only ever inside a comment is gone on upgrade, with any
+finding about it, so a baseline that accepted one reports that entry as no
+longer occurring under `--ratchet`. An item under a heading that was only inside
+a comment is numbered under the heading above it instead.
+
+### Verified
+
+`npm run lint`, 987 tests, `npm run build` and `npm run selfcheck`. Fifteen of
+the 25 new tests fail against the unfixed source; the other ten hold the one pass
+to what the two it replaced already got right - fences, escapes, runs that never
+close, a `<` that is not `<!--`. Measured on their own with
+`--coverageAnalysis all`, before and after: `markdown.ts` went from 69.30% to
+72.97%, the status readers in `sections.ts` from 52.63% to 59.49%, and
+`statusSectionBody` in `extract.ts` from 60.00% to 73.08%. The mutants left alive
+on the new lines change how long an answer takes, or compare offsets that cannot
+be equal. 600,000 generated documents read the same through the one pass as
+through a naive left-to-right reading of the same rule, and this repository's
+documents scan no slower than before.
+
+Then spec-core, the record phase and GitLab: `npm run lint`, 1,010 tests,
+`npm run build` and `npm run selfcheck`. The 30 tests of `tests/regex.test.ts`
+went to spec-core with the matcher, where they run with only its names
+changed. Every glob change listed above has a test that fails against the
+0.8.0 matcher - the host-dependent ones on Windows, where the defect was - and
+the differential in `tests/glob.test.ts` requires each of them to occur and
+nothing else to; five of the eight tests for `archived` fail without its table
+entry, and the other three hold what must not move. Measured on their own with
+`--coverageAnalysis all`, before and after: `glob.ts` from 73.74% to 77.22%,
+`cli.ts` from 81.11% to 83.45%, `report.ts` from 69.03% to 70.17% and
+`lifecycle.ts` from 53.10% to 53.26%. `select.ts`, whose only change is an
+import, read 74.01% and then 71.08%: sixteen selector-parsing mutants that no
+assertion kills in either run timed out in the first and survived in the
+second. Of the mutants left alive on new lines, seven are equivalent and say
+so where they are; the rest are on the ignore filter, whose reading did not
+change, and on the symlink branch of the walk, which no test reaches, as
+before.
+
+Then spec-core's scanner and front-matter reader: `npm run lint`, 1,041 tests,
+`npm run build` and `npm run selfcheck`. Of the 27 new tests, 23 fail against
+the source before the move; the other four hold what must not move - an embed's
+edge, the last of a key written twice, no directive from a comment that never
+closes, and no suffix for a heading that is not repeated. The binaries before
+and after read this repository, its seven fixture corpora and spec-core's
+documents into identical graph exports and identical findings. Over a corpus
+written to hit each difference above, every difference in their output was one
+of them. The scanner's own mutants, 72% to 77% here, are spec-core's sweep's
+now, at 98% there; what the move left here is measured by CI's sweep.
+
+Then the review of those rounds: `npm run lint`, 1,053 tests, `npm run build`
+and `npm run selfcheck`, with spec-core copied again at cbe2223. Every new test
+fails against the source the review read but one, which holds what an archived
+document is still exempt from. They cover spec-core's licence in the package,
+`**` inside a name and an extended glob, code past a list item's text, an empty
+`--ignore` and `--ignore-ref`, what an archived document still answers for, the
+count of front-matter values not read, front matter that never closes, and a
+GitLab fingerprint across a ticked box. A baseline recorded by 0.8.0 over a
+corpus holding each scanner difference, run under `--ratchet`, accepted the
+finding on a moved item and went stale only on findings the scan no longer
+produces. Against 0.8.0 over the review's corpora for `archived`, the difference
+is the stale premise and the orphaned obligation the change is for. Over the
+large repository above, this branch and the one reviewed report identical
+findings. spec-core's documents and the seven fixture corpora read into the same
+graph export as before the copy; this repository's lost the seven relations
+above.
+
 ## 0.8.0
 
 A register row took its identifier from the first thing its *title* said, not
@@ -107,7 +552,7 @@ the file - `--verbose` now says when it read nothing. Unreadable, as opposed to
 absent, is an error wherever the path was written. A baseline that cannot be
 *parsed* is still reported and ignored: it only ever suppresses, so a row that
 is dropped is a finding reported. See
-[ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+[ADR-0012](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0012-a-baseline-is-a-ratchet.md).
 
 ### Fixed
 
@@ -117,7 +562,7 @@ selector under `query`, went to stdout above the report. With `--format json`
 that made the output unparseable; with `--format sarif` it made a file the
 code-scanning uploader rejects over a schema rather than over the command that
 was run. Both now go to stderr, with everything else a run says about itself.
-[ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md) already
+[ADR-0015](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md) already
 had the rule - rows "cannot go on stdout beside a JSON document without
 breaking the parse" - and these two lines were the places that did not follow
 it.
@@ -179,7 +624,7 @@ matched against targets read out of documents, which nothing limits the length
 of. Every glob - the patterns to check, `--ignore`, `--ignore-ref`, `--history` -
 now runs on the same automaton as `~=`, verified against the `RegExp` it
 replaces on every glob and path in a differential corpus. See
-[ADR-0017](docs/adr/0017-a-predicate-must-finish.md).
+[ADR-0017](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0017-a-predicate-must-finish.md).
 
 - **An invalid glob names itself.** `docs/{a` used to report
   `Invalid regular expression: /^docs\/(?:a$/i: Unterminated group`, about a
@@ -210,7 +655,7 @@ report a closed question as reopened when nobody touched it. An obligation is
 paired only by a declared id, or by its document, section and title when nothing
 else shares them; anything unpaired is reported as having appeared or
 disappeared. Human, `--format json` or `--format markdown`, and exit 0 either
-way. See [ADR-0020](docs/adr/0020-a-diff-names-what-it-can-tell-apart.md).
+way. See [ADR-0020](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0020-a-diff-names-what-it-can-tell-apart.md).
 
 - The JSON graph export names its `generator`, so a diff can warn when two
   exports came from different versions, and each item says whether its id was
@@ -244,8 +689,8 @@ kills no assertion made: tests writing to fixed paths deleted each other's files
 under Stryker's parallel workers. Race-free, the sweep read 73.42% before
 `spec-graph diff` and 75.25% with this release: `diff.ts` at 98.35%, and
 `directives.ts` from 66.88% to 78.01%. Lose every timeout and it reads 71.89%.
-See [ADR-0007](docs/adr/0007-mutation-testing.md) and
-[ADR-0019](docs/adr/0019-the-sweep-runs-in-shards.md).
+See [ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) and
+[ADR-0019](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0019-the-sweep-runs-in-shards.md).
 
 The sweep after the directive fix moved `extract.ts` down 0.18 points, among the
 usual movement in files nobody touched, and this one was real. Four mutants
@@ -282,7 +727,7 @@ A region now carries its file's front matter minus two kinds of key. A
 on behalf of the register, not of each decision in it. So does a key the region
 **answers for itself** — its identifier, status, title and aliases, which are
 precisely the things a register exists to vary row by row.
-[ADR-0009](docs/adr/0009-a-specification-is-a-region.md) carried this as a
+[ADR-0009](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md) carried this as a
 narrowed open question and called it a gap. It was a defect, and it was found by
 pointing the binary at a register rather than by reading the code.
 
@@ -295,7 +740,7 @@ that keeps registers and writes rules about front matter.
 ### Added
 
 **`~=` is matched by an automaton that cannot backtrack.**
-[ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md) documented this hazard
+[ADR-0016](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0016-a-query-needs-a-sentence.md) documented this hazard
 with `(a+)+$`, which nobody writes, and priced the fix at "worth it only if a
 real repository hangs". Both were wrong. `^([A-Za-z0-9_]+[ ]?)+$` is what
 somebody writes to check that a title is words separated by single spaces:
@@ -326,8 +771,8 @@ over, on one clause of the language specification read backwards in two
 different places - the word characters `\b` recognises, and whether a character
 whose upper case is ASCII may match `[A-Z]`. The second was found by the
 mutation score pointing at a corpus with a blind spot in it rather than at a
-test. See [ADR-0017](docs/adr/0017-a-predicate-must-finish.md) and
-[ADR-0007](docs/adr/0007-mutation-testing.md).
+test. See [ADR-0017](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0017-a-predicate-must-finish.md) and
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md).
 
 **Configuration is discovered upward, and the file holding it is the root.**
 
@@ -337,7 +782,7 @@ cd packages/auth && spec-graph check     # the repository's rules, the
                                          # repository's paths
 ```
 
-[ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md) worried
+[ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md) worried
 that discovery would make a run depend on where it started. Reading the working
 directory already did, and silently: a check from a package directory found no
 configuration, ran no project rules, used the default include patterns, and
@@ -348,7 +793,7 @@ to a run from the top. The walk stops at the repository — a directory holding
 `.git` — so a stray file in a home directory cannot reach it. `--root` names the
 root yourself and turns discovery off, and a path typed on the command line
 stays relative to where you typed it. See
-[ADR-0018](docs/adr/0018-the-configuration-file-is-the-root.md).
+[ADR-0018](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0018-the-configuration-file-is-the-root.md).
 
 **`spec-graph query project:<rule>` runs a registered rule by name.** The rule
 is already compiled by the time the command runs, and the alternative was
@@ -453,7 +898,7 @@ re-litigated: a **relational diff** between two states of the graph, taken
 between two `--graph-format json` exports rather than between two git revisions,
 because revisions mean spawning a binary underneath a pipeline that is a pure
 function of text. See
-[ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+[ADR-0015](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
 
 ### Verified
 
@@ -485,7 +930,7 @@ mostly the older formatters.
 Between those two runs `rules.ts` moved from 79.42% to 76.02% and
 `directives.ts` from 77.92% to 74.03%, with neither file touched: the tests added
 in between changed which tests `perTest` believes cover which mutants.
-[ADR-0007](docs/adr/0007-mutation-testing.md) has recorded that shape for two
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) has recorded that shape for two
 releases, and it is why a per-file drop is a question and not an answer.
 
 The hosted number is the one that governs, because it is where the build fails:
@@ -495,12 +940,12 @@ points.
 
 The incremental run on the same commit read 0.40 points low - the third
 observation after 3.18 high at 0.3.0 and 1.29 low at 0.4.0, and the reason
-[ADR-0007](docs/adr/0007-mutation-testing.md) calls it a signal rather than a
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) calls it a signal rather than a
 figure. The tag's run also logged a cache save, which this entry first read as
 the cache-key fix from 0.4.0 doing its job. *Corrected 2026-09-13:* it saved a
 copy of the stale report it had restored, because the full step never wrote one,
 and an entry saved under a tag cannot be restored on `main` in any case. See
-[ADR-0007](docs/adr/0007-mutation-testing.md).
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md).
 
 **The rebuild took 168 of its 180 minutes.** 13% more mutants than 0.4.0, and 63%
 longer on the hosted runner against 15% longer locally. At 0.4.0's old cap of
@@ -531,7 +976,7 @@ selector, a message, a hint and a severity, and runs it beside the built-ins:
 }
 ```
 
-[ADR-0005](docs/adr/0005-rules-are-queries.md) claimed for three releases that
+[ADR-0005](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0005-rules-are-queries.md) claimed for three releases that
 the selector language was expressive enough for a team to write the equivalent
 of a built-in rule. It was only true at a prompt: `spec-graph query` could find
 the thing, and nothing could make finding it fail. Three ADRs recorded the same
@@ -550,7 +995,7 @@ nothing answers to is reported when the file is read - a rule that cannot work
 has to say so, because silence from a linter is indistinguishable from health.
 `query` also takes a list, read as a union.
 
-See [ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md).
+See [ADR-0016](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0016-a-query-needs-a-sentence.md).
 
 **A broken reference suggests the document it was probably meant to name.**
 `ARD-0015` gets `did you mean ADR-0015?`; `0002-cacheing.md` gets its sibling
@@ -558,7 +1003,7 @@ one letter away. `ADR-0003` in a repository of two ADRs gets nothing, and that
 restraint is the design rather than a limitation of it: a family name is a word
 people misremember, a number *is* the identity, and every number sits one edit
 from its neighbours. Each gate ends the same way - exactly one candidate, or
-silence. See [ADR-0004](docs/adr/0004-reference-resolution.md).
+silence. See [ADR-0004](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0004-reference-resolution.md).
 
 **A stale baseline entry says `paid` or `gone`.** `paid` is the ratchet working.
 `gone` means the document was not in this corpus at all, so nothing is known
@@ -587,7 +1032,7 @@ UTF-16 read as UTF-8 rather than anybody's keystroke.
 ### Fixed
 
 Nothing that a corpus had hit. Two findings came out of probing rather than out
-of the suite, which is the practice [CLAUDE.md](CLAUDE.md) asks for:
+of the suite, which is the practice [CLAUDE.md](https://github.com/DescentVTT/spec-graph/blob/main/CLAUDE.md) asks for:
 
 - A near-miss gate that suggested a file which had moved **never fired**.
   Resolution already binds a path by its basename, so the suggestion had nothing
@@ -625,7 +1070,7 @@ of the suite, which is the practice [CLAUDE.md](CLAUDE.md) asks for:
 first time anybody checked. Across 73 keys that Jekyll, Hugo, Docusaurus, Astro,
 MADR, KEP, the IETF datatracker and Obsidian actually write, one edit reads
 *none* of them as a near-miss and two edits reads exactly one: `rfc`, which it
-would tell an author to spell `refs`. [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md)
+would tell an author to spell `refs`. [ADR-0014](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0014-a-relation-is-spelled-both-ways.md)
 said two edits would catch `dependancies`; one edit already did, along with
 every other typo anybody produced to argue the case. Two buys nothing and costs
 a false positive on a key that carries citations in exactly the corpora this
@@ -658,7 +1103,7 @@ fails: **75.40%**, up from 75.14% at 0.3.0. Lose every timeout on a loaded runne
 and it reads 71.76%, which is the most margin `break: 70` has ever had.
 
 That run also caught the other half of a claim
-[ADR-0007](docs/adr/0007-mutation-testing.md) narrowed at 0.3.0. The `main` push
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) narrowed at 0.3.0. The `main` push
 and the `v0.4.0` tag were the same commit on the same runner, and the incremental
 read **1.29 points low** against the rebuild - having read 3.18 points *high* at
 0.3.0. Two observations, opposite signs. The direction is not a property, and the
@@ -667,7 +1112,7 @@ leaves it nothing to reuse.
 
 ### Withdrawn
 
-[ADR-0013](docs/adr/0013-the-scanner-hands-back-prose.md) said a lone `\r` was
+[ADR-0013](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0013-the-scanner-hands-back-prose.md) said a lone `\r` was
 not treated as a line ending. It always was - `createLineIndex` has recognised
 all three terminators since 0.1.0 and says so in its own doc comment. The claim
 came from reading the scanner and not the table underneath it, and nobody had
@@ -684,7 +1129,7 @@ built-ins needs a default arm. `BaselineOutcome.stale` carries `reason`, and
 ## 0.3.0
 
 Found by writing a corpus designed to break the scanner and reading the edges it
-produced, which is the practice [CLAUDE.md](CLAUDE.md) asks for and the reason
+produced, which is the practice [CLAUDE.md](https://github.com/DescentVTT/spec-graph/blob/main/CLAUDE.md) asks for and the reason
 it is there. The mutation score could not have found any of it: a mutant is a
 change to code that exists, and a construct nobody parsed has no code to mutate.
 
@@ -727,7 +1172,7 @@ GitHub's own copy-link all produce for a file with a space in its name. The
 escapes are read as a fallback, so a filename that genuinely contains one keeps
 resolving by the spelling it was written with, and a stray `100%` is left alone.
 
-See [ADR-0013](docs/adr/0013-the-scanner-hands-back-prose.md).
+See [ADR-0013](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0013-the-scanner-hands-back-prose.md).
 
 **Front matter knew half of each relation.** `depends-on` was a key and
 `depended-on-by` was not, so a repository whose filing convention records
@@ -738,7 +1183,7 @@ now - twenty-five keys became fifty-six - and a test holds the invariant.
 
 Keys also fold on separators and case, so `depends-on`, `depends_on` and
 `dependsOn` are one key rather than the two that happened to be written out.
-See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
+See [ADR-0014](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0014-a-relation-is-spelled-both-ways.md).
 
 **`--verbose --format json` printed human lines onto stdout beside the JSON.**
 
@@ -749,11 +1194,11 @@ See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
   ignored. Both halves of that gate matter: `deprecated: true` is one edit from
   `deprecates` and a boolean is not a citation. It says what is true - *"the key
   declares no relation"* - and offers the near spellings rather than asserting
-  one. See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
+  one. See [ADR-0014](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0014-a-relation-is-spelled-both-ways.md).
 - **`--ratchet`**, and `"ratchet": true` in the configuration. The other side of
   a baseline: with it, a declared finding that no longer occurs fails the build,
   named, with `--record-baseline` as the fix. Off by default, because
-  [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md) is right that failing a
+  [ADR-0012](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0012-a-baseline-is-a-ratchet.md) is right that failing a
   build because somebody fixed something is a strange way to encourage them -
   and on for a team that has decided its debt only moves one way, because a note
   on a green build is a line that scrolls past.
@@ -763,7 +1208,7 @@ See [ADR-0014](docs/adr/0014-a-relation-is-spelled-both-ways.md).
   same rule/specification/citation identity a baseline is keyed on, so an
   annotation survives a reformat. Deterministic and timestamp-free like every
   other output here. See
-  [ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+  [ADR-0015](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
 
 ### Not added
 
@@ -773,14 +1218,14 @@ semantics that differ on all three platforms would be the one part of this
 program that could not honour byte-determinism, inside a codebase whose whole
 test strategy rests on everything between the edges being a pure function of
 text. Reasoning in
-[ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+[ADR-0015](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
 
 ### Measured
 
 684 tests, and a mutation score of **75.14% on the hosted runner** - the figure
 that governs, up from 73.32% at v0.2.0 - against 79.69% over 8,126 mutants on a
 developer machine. The guard stays at `break: 70`. See
-[ADR-0007](docs/adr/0007-mutation-testing.md), which 0.3.0 also amended: an
+[ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md), which 0.3.0 also amended: an
 incremental run read 3.18 points *high* against a full rebuild of the same
 commit, so the claim that incremental errs low was wrong.
 
@@ -795,7 +1240,7 @@ spellings held one id per key. A second claimant therefore did not make the link
 ambiguous; it overwrote the first, and the link went to whichever file was
 indexed last.
 
-[ADR-0004](docs/adr/0004-reference-resolution.md) has always said two candidates
+[ADR-0004](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0004-reference-resolution.md) has always said two candidates
 is worse than none, and a reference matching several documents is reported as
 ambiguous rather than bound to whichever was indexed first. That now holds for
 paths too.
@@ -820,7 +1265,7 @@ keeps no registers is unaffected, and one that does needs no change beyond the
 upgrade.
 
 Since 0.1.3 a register has yielded one specification per row or per section
-([ADR-0009](docs/adr/0009-a-specification-is-a-region.md)), and every one of
+([ADR-0009](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md)), and every one of
 those carried the file's path into the resolver's path index. That index keeps
 whichever entry was written last, so the file's own entry was overwritten by its
 final region, and:
@@ -866,12 +1311,12 @@ requirements table headed `Status` was enough to trigger it.
   `historyPatterns` in the configuration or by `<!-- @spec-history -->`, and
   never guessed from a filename. Its links are still checked and work handed
   *into* it is still a ghost handover; its own obligations and lifecycle are
-  not. See [ADR-0011](docs/adr/0011-a-record-is-not-a-specification.md).
+  not. See [ADR-0011](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0011-a-record-is-not-a-specification.md).
 - **Baselines.** `--record-baseline` writes today's findings as accepted debt;
   `--baseline` reports only what is new since. Keyed on the specification and
   the citation rather than on a line number, so it survives edits, reordering
   and renames. Paid debt is reported, not failed. See
-  [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+  [ADR-0012](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0012-a-baseline-is-a-ratchet.md).
 
 ### Fixed
 
@@ -886,10 +1331,10 @@ requirements table headed `Status` was enough to trigger it.
 - **A specification is a region of a file, not a file.** A register kept as
   headings or as a table yields one specification per decision, each with its
   own lifecycle, obligations and relations. See
-  [ADR-0009](docs/adr/0009-a-specification-is-a-region.md).
+  [ADR-0009](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md).
 - **Repository configuration.** `.spec-graph.json`, `spec-graph.config.json`, or
   a `"spec-graph"` key in `package.json`, with family allow and deny rules. See
-  [ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md).
+  [ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md).
 
 ## 0.1.2
 
@@ -897,7 +1342,7 @@ requirements table headed `Status` was enough to trigger it.
 
 - `--ignore-ref`, for repositories where `[[...]]` tags a concept rather than
   naming a file. See
-  [ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
+  [ADR-0008](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0008-wiki-links-carry-no-path.md).
 
 ## 0.1.1