@descent-vtt/spec-graph 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,416 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 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](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](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](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](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](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](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](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

package/README.md

@@ -123,12 +123,28 @@ onto four phases, chosen so one question can be answered from the phase alone:
 | `draft` | `proposed`, `provisional`, `wip`, `in-review`, `experimental`, … | yes |
 | `active` | `accepted`, `implementable`, `implemented`, `merged`, `adopted`, … | yes |
 | `frozen` | `final`, `ratified`, `locked`, `published`, … | **no** |
-| `retired` | `superseded`, `deprecated`, `rejected`, `withdrawn`, `archived`, … | **no** |
+| `retired` | `superseded`, `deprecated`, `rejected`, `withdrawn`, … | **no** |
 
 The status is found wherever your team writes it — front matter (`status:`,
 `state:`, `stage:`), a `## Status` section, `**Accepted** (2026-03-01) ✅`, or a
 `docs/adr/archive/` directory. `Accepted, later superseded by ADR-0009` is
-retired: retirement is terminal, so a retirement word anywhere wins.
+retired: retirement is terminal, so a retirement word anywhere wins. Front
+matter is read as YAML reads it, and a value YAML would not read -
+`status: Superseded by ADR-9: see notes`, where a plain value cannot hold `: ` -
+is left out rather than guessed at. Every run says how many statuses, ids and
+relations it left out that way, and `--verbose` says where and why: quote the
+value and it is read.
+
+`archived` is none of the four. It is what spec-brief writes on a round of work
+it has closed, and every spec-* tool reads it as a **record**: depending on it
+is normal, its unticked boxes are not anyone's work, its links are still
+checked, and new work handed to it is still a ghost handover. See
+[Journals, changelogs and minutes](#journals-changelogs-and-minutes). Unlike a
+journal, it still answers for what it claims: a supersession it declares, a
+cycle it closes and a link to itself are reported as they would be anywhere.
+To retire a decision, say `superseded` or `deprecated` -
+`archived, superseded by ADR-0009` is retired - and a document under an
+`archive/` directory that says nothing about itself is still retired.
 
 An unrecognised status becomes `unknown`, and rules treat it permissively. It
 never guesses.
@@ -399,10 +415,11 @@ against a fifty-four-character title takes `RegExp` 103 seconds and this 13
 microseconds. It reads the usual syntax minus backreferences and lookaround,
 which are not regular; both are refused when the selector is read, with the
 character pointed at. Globs - the patterns to check, `--ignore`, `--ignore-ref`,
-`--history` - are matched by the same automaton, because a glob with three stars
-in it is
-enough to keep `RegExp` busy for two minutes over a long reference target. See
-[ADR-0017](docs/adr/0017-a-predicate-must-finish.md).
+`--history` - are matched by an automaton too, because a glob with three stars
+in it is enough to keep `RegExp` busy for two minutes over a long reference
+target. See [ADR-0017](docs/adr/0017-a-predicate-must-finish.md). Both automata
+are spec-core's, the library the spec-* tools share, copied into this package
+rather than installed.
 
 On a register, a region answers its file's front matter for every descriptive
 key — `fm.owner` on a decision inside a register is the register's owner — while
@@ -508,7 +525,10 @@ had:
 { "historyPatterns": ["**/JOURNAL_*.md", "archive/**"] }
 ```
 
-or, for one file, `<!-- @spec-history -->` at the top of it.
+or, for one file, `<!-- @spec-history -->` at the top of it. A brief whose
+status is `archived` is a record already, with nothing declared, though not a
+log: the supersessions, cycles and self-references it declares are still
+checked.
 
 |  |  |
 | --- | --- |
@@ -599,9 +619,34 @@ without drifting, because the `partialFingerprints` spec-graph writes are the
 same identity a baseline is keyed on — the rule, the specification, and the
 citation, with no line number in it (ADR-0012).
 
-`--format json` is the other machine-readable output, and the one to parse if
-you are building something of your own: it carries the baseline note, the
-summary and the per-file detail that SARIF has nowhere to put.
+On GitLab, `--format gitlab` writes the Code Quality report a merge request
+reads, and the merge request shows which findings it introduced and which it
+resolved:
+
+```yaml
+spec-graph:
+  script:
+    - npx spec-graph --format gitlab > gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json
+```
+
+Each finding is an issue with its rule as `check_name`, its message and hint as
+`description`, and its file and line as `location`. Severities map as `error`
+to `critical` - or `major` when only `--strict` made it an error - `warn` to
+`minor` and `info` to `info`. The `fingerprint` is a SHA-256 of the rule, the
+specification and what within it - a citation's target, or the document at the
+other end - which is what a baseline counts by. There is no line in it, so a
+finding a paragraph moved is not reported as new, and no message, so ticking
+one of three open boxes does not make an `orphaned-obligation` new either; the
+second of two findings identical in all three is told apart by its order. `when: always` keeps the report when the job fails, which
+it does, with exit `1`, whenever there is an error to report.
+
+`--format json` is the machine-readable output to parse if you are building
+something of your own: it carries the baseline note, the summary and the
+per-file detail that SARIF and Code Quality have nowhere to put.
 
 **There is no `--watch`.** A full run on this repository takes 60 ms, so the
 loop that would justify a resident process is one line of shell, and it belongs
@@ -661,6 +706,39 @@ all — a silently ignored `ignoreReference` is a configuration that looks appli
 and is not. `--no-config` checks on defaults instead, and the exit code then
 says which run it was.
 
+### Patterns
+
+The patterns to check, `--ignore`, `--history` and `historyPatterns` are the
+glob dialect every spec-* tool reads, so a scope means the same to spec-graph
+as to the tool that wrote it. They are matched against the whole
+repository-relative path, **case-sensitively on every host** — a baseline
+recorded on a Windows checkout holds in Linux CI:
+
+| pattern | matches |
+| --- | --- |
+| `docs/**/*.md` | Markdown anywhere under `docs`; `**` is whole directories, none or more |
+| `docs/**.md` | refused: `**` is whole directories or nothing, so write `docs/**/*.md` or `docs/*.md` |
+| `docs` | a file called `docs`, or everything under the directory |
+| `docs/` | everything under `docs`, and not `docs` itself |
+| `{docs,specs}` | two literals, so both directories and what they hold |
+| `adr/[0-9]*.md`, `adr/[!0-9]*.md` | a class, and a negated one; `[^0-9]` negates too |
+| `!docs/drafts/**` | takes back what an earlier pattern matched; the last to match wins |
+| `docs\adr\*.md` | the same as `docs/adr/*.md`: a `\` is a separator |
+
+A class never matches a `/`, and a pattern that cannot mean a path under the
+root — an unclosed `[` or `{`, `..`, a lone `.`, an empty one — stops the run
+with exit `2` and names the pattern, wherever it was written. So does an
+extended glob, `+(a|b)`: write `{a,b}`. A parenthesis with no `|` in its group
+is itself, so `C++(notes).md` names that file. A `..` typed below the root,
+`spec-graph "../*.md"` from `docs/deep`, is resolved against where you typed
+it. A bare `--ignore` name, `--ignore drafts`, still prunes that directory at
+any depth.
+
+`--ignore-ref` is matched against reference targets rather than paths: a bare
+pattern names one target exactly, case is ignored on every host, a `\` escapes
+the next character, and `.` and `..` are the text of the link. See
+[ADR-0022](docs/adr/0022-globs-are-the-family-path-dialect.md).
+
 ### Family rules
 
 Every specification cites RFC 2119. In a repository that also keeps its own
@@ -720,7 +798,8 @@ spec-graph diff <before> <after>     Compare two JSON graph exports.
 --record-baseline <f>   Write today's findings as accepted debt, exit 0
 --ratchet               Also fail when a baseline entry no longer occurs
 --no-config             Ignore .spec-graph.json and the package.json key
---format <fmt>          human | json | sarif (check) | markdown (check, diff)
+--format <fmt>          human | json | sarif (check) | gitlab (check)
+                        | markdown (check, diff)
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -838,7 +917,7 @@ exported. Reporters, editor extensions and custom rules are all first-class.
 
 ## Design
 
-Twenty ADRs, which `spec-graph` validates on every CI run:
+Twenty-three ADRs, which `spec-graph` validates on every CI run:
 
 - [ADR-0001 — A hand-written Markdown scanner](docs/adr/0001-hand-written-markdown-scanner.md)
 - [ADR-0002 — A four-phase lifecycle lattice](docs/adr/0002-lifecycle-lattice.md)
@@ -860,17 +939,23 @@ Twenty ADRs, which `spec-graph` validates on every CI run:
 - [ADR-0018 — The configuration file is the root](docs/adr/0018-the-configuration-file-is-the-root.md)
 - [ADR-0019 — The sweep runs in shards](docs/adr/0019-the-sweep-runs-in-shards.md)
 - [ADR-0020 — A diff names only what it can tell apart](docs/adr/0020-a-diff-names-what-it-can-tell-apart.md)
+- [ADR-0021 — Releases are published by CI, with provenance](docs/adr/0021-releases-are-published-by-ci.md)
+- [ADR-0022 — Globs are the family's path dialect](docs/adr/0022-globs-are-the-family-path-dialect.md)
+- [ADR-0023 — The scanner is the family's](docs/adr/0023-the-scanner-is-the-familys.md)
 
 **Zero runtime dependencies.** Node 22+, native ESM, TypeScript strict with
 `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The Markdown
 scanner, the front-matter reader, the glob matcher, the query parser and the
-regular-expression matcher behind `~=` are all written here, so the whole
-package is auditable in an afternoon — and nothing in the pipeline can take
-longer than its input.
+regular-expression matcher behind `~=` are all written here or in
+[spec-core](https://github.com/DescentVTT/spec-core), the library the spec-*
+tools share, whose code is copied into `src/vendor/` and checked by hash rather
+than installed. So the whole package is auditable in an afternoon — and nothing
+in the pipeline can take longer than its input.
 
-**Verified, not just covered.** 411 tests; 94.2% statement and 96.9% line
+**Verified, not just covered.** 1,053 tests; 96.8% statement and 98.2% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation
-score - 74.05% over 6,150 mutants - because a vocabulary entry or a boundary
+score - 76.73% over 8,400 mutants at 0.9.0, measured incrementally in CI -
+because a vocabulary entry or a boundary
 condition can be weakened by an ordinary-looking refactor without a single test
 going red. [ADR-0007](docs/adr/0007-mutation-testing.md) is straight about what
 that number is and is not.