@descent-vtt/spec-graph 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,483 @@
 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
+from its ID column. Found on the same 885-document repository as 0.7.0: 27 of
+232 rows of one issues register were filed under the wrong entity.
+
+A minor rather than a patch, and the baseline is the reason. A baseline is
+fingerprinted on document ids, and the whole of this fix is that those ids move.
+Measured on an unchanged corpus against a baseline recorded by 0.7.0: the
+accepted finding came back as new, its entry was reported as no longer
+occurring, and `check --baseline` went from exit `0` to exit `1`. One
+`--record-baseline` settles it, and the entries it writes are the ones that were
+meant all along. The rule at the top of this file says a patch asks nothing of a
+repository that upgrades, and this asks for that run.
+
+### Fixed
+
+**A title names nothing.** `| OI-V-05 | ADR-040's enforcement point has no
+browser test |` was read as `ADR-040`. Eighteen rows collided with the ADR they
+cite that way, and the collision does not merely mislabel a row: run against a
+corpus holding both, the ADR keeps the id and the issue has no node in the graph
+at all. Nine more opened with a noun phrase, inventing a `STAGE-1`, a
+`GUARDRAIL-5` and a `CLOSED-2026` that nobody had written, each of them open -
+which is what drew the false `ghost-handover` findings the register was reported
+for; two rows collapsed onto one `STAGE-1`.
+
+The identifier a title opens with almost always belongs to the document the
+title is *about*, so a title is read as a name only where nothing else has given
+one - and where it is not the name it registers no alias either, because an
+alias sends every citation of the real document to whatever quoted it.
+`# ADR-0040 considered harmful` at the top of `0007-sharding.md` was registering
+`adr0040` against `ADR-0007`.
+
+Two things count as having given one: a number, from a declaration or a file
+name, and for a register row its id column, whatever shape the id is in. A whole
+file keeps the looser reading and its H1 can still name it, because there
+nothing separates a title about another document from a title about this one:
+`slug:` holds a URL segment rather than an id, so `slug: sharding` in
+`sharding.md` under `# ADR-0007: Sharding` has to stay `ADR-0007`. A declaration
+and the file name are still weighed together rather than ranked, so
+`slug: sharding-the-write-path` in `0007-sharding.md` is `ADR-0007` as before.
+
+**A region no longer reads a number out of the file it sits in.** Every row of
+a register kept in `0042-open-issues.md` answered to `ADR-0042`, and so did the
+file. ADR-0009 already said a region does not claim the file's *path*, for the
+reason that two nodes answering to one name make every link to it ambiguous; the
+file's name is that same claim spelled differently, and the rule was written
+down as two.
+
+**A file's own title heading is matched by its number, not its spelling.**
+`# ADR-040` at the top of `0040-enforce.md` was read as a region *inside* the
+file it names: one decision, two nodes, a split lifecycle, and a citation
+arriving at whichever padding it happened to use. Padding is not part of an
+identity anywhere else - `ADR-40`, `ADR-040` and `ADR-0040` all resolve to one
+document - and now it is not part of this comparison either.
+
+### Verified
+
+`npm run lint`, 950 tests and `npm run selfcheck`. Thirteen of the fifteen new
+tests fail against the unfixed source; the other two are the guards on the
+layouts that must not move, which have to pass both ways. `identity.ts` and
+`sections.ts` were measured on their own before and after: 72.77% and 66.89%
+became 75.18% and 71.93%, and no mutant on the new lines survived, so nothing
+was masked. ADR-0004 carries the rule as a
+fifth asymmetry, with the hyphenated-prefix question declined under it, and
+ADR-0009 is amended in place.
+
 ## 0.7.0
 
 Three ways a run handed back something other than what it said it was: a