@descent-vtt/spec-graph 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,281 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 0.4.0
+
+Ten open questions across the ADR suite, answered. Five shipped, three declined
+with a reason, one settled by measuring it, and one withdrawn because it turned
+out not to be true.
+
+### Added
+
+**A repository can write its own rules.** `rules` in `.spec-graph.json` takes a
+selector, a message, a hint and a severity, and runs it beside the built-ins:
+
+```json
+"rules": {
+  "no-draft-dependency": {
+    "query": "document[phase=active] -depends-on-> document[phase=draft]",
+    "message": "{0} depends on {1}, which is still a draft",
+    "hint": "wait for {1} to be accepted, or drop it from {0.path}",
+    "severity": "error"
+  }
+}
+```
+
+[ADR-0005](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
+gap and stopped at the same sentence - a query needs a severity and a message
+before it is a rule.
+
+The id is the name with `project:` in front, and a built-in id can never contain
+a colon. That one fact is why `--rule`, `--strict`, `--record-baseline`, the
+severity table, the record exemption, the sort order and the SARIF `ruleId` all
+carry a user-defined rule without being taught what one is.
+
+Messages interpolate over the path the query already numbers: `{0}` and `{1}`
+for node ids, `{1.phase}` and `{0.fm.owner}` for anything a selector can read. A
+selector that does not parse, a `{2}` no query can reach, or an attribute
+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).
+
+**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
+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).
+
+**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
+about the defect - and the ordinary way to produce one is to narrow an include
+pattern. Both still trip `--ratchet`, but the verdict now says how many entries
+name documents the run did not see and asks a team to check their patterns,
+rather than congratulating them for losing sight of a problem.
+
+**Stale entries are named in the JSON report**, under `baseline.entries`, each
+with its label. A count is enough to know the file has slack and never enough to
+strike it.
+
+**`--verbose` lists what configuration silenced.** Every reference
+`ignoreReferences` or `ignoreFamilies` suppressed, grouped by target and naming
+which of the two did it; the JSON report carries every site under `suppressed`
+without the flag. A single over-broad glob looks exactly like a clean repository
+from the outside, and nothing said otherwise. Not listed: a bare identifier
+spec-graph read as prose on its own - that was nobody's decision.
+
+**A NUL byte is reported as a parse problem.** Not a finding: nothing about the
+graph is wrong and it never fails a build. It earns the line because spec-graph
+is likely the only tool that read the file at all - grep, diff and every review
+interface treat it as binary - and the message names the usual cause, which is
+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:
+
+- 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
+  left to suggest. Removed before it shipped rather than after.
+- Hand-mutating each remaining gate found two that no test could kill. One was
+  genuinely equivalent code and is now one line shorter; the other was masked by
+  a length floor, and the test now writes a number long enough to clear it.
+
+### Not added
+
+- **SARIF `fixes`.** Counted the findings with a fix that is an edit rather than
+  a judgement, and there is one. Everything else has to be *inserted*, into front
+  matter that may not exist, at a position only a human can choose. The new
+  near-miss suggestions made the case weaker rather than stronger: they are
+  deliberately a guess, and promoting a guess to a machine-applicable edit throws
+  away the restraint that makes it worth printing.
+- **Hybrid documents** - a specification with a changelog section. The premise
+  turned out to be wrong: regions cannot express it, because `record` is decided
+  once per file and inherited by everything in it. Making it work means a second
+  source of truth for `record`, traded against a free workaround - put the
+  changelog in its own file, which is where it belongs.
+- **Cross-repository references.** Every way of doing it puts network or
+  discovery underneath a pipeline whose test strategy rests on being a pure
+  function of text.
+- **A guard for `~=`.** Probing confirmed `[title~=(a+)+$]` never returns. The
+  hang has been reachable from `query` since 0.1.0; what 0.4.0 changes is that it
+  now lives in a file that runs on every build. Rejecting nested quantifiers
+  catches `(a+)+` and misses `(a|a)+`, and a guard that is incomplete and says it
+  is safe is worse than no guard. Documented instead, with the alternatives
+  weighed in ADR-0016.
+
+### Measured
+
+**The near-miss gate for front-matter keys stays at one edit**, and this is the
+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)
+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
+tool is pointed at.
+
+### Verified
+
+| | |
+|---|---|
+| `npm run lint` | pass |
+| `npm test` | 754 passing, 20 files |
+| `npm run selfcheck` | pass, over 19 documents and 124 relations |
+| `npm run test:mutation` | 79.41% over 8,585 mutants, 64m30s |
+| hosted full run, which governs | **75.40%**, 102m48s |
+| `break` | unchanged at 70 |
+
+79.69% over 8,126 mutants at 0.3.0 against 79.41% over 8,585 here, on the same
+machine. The new code carries itself: `project-rules.ts` at **99.50%** with one
+survivor - a genuinely equivalent `<` against `<=` in a comparator whose inputs
+are object keys and therefore never equal.
+
+That 99.50% is what reading the survivor list bought. The first full run put the
+module at 86.89%, a targeted re-measurement with `coverageAnalysis all` agreed at
+86.41% - so the gap was real and not `perTest` mis-attribution - and sixteen of
+those survivors turned out to be tests nobody had written. The whole-corpus
+figure moved 0.38 points for it.
+
+The hosted number is the one that actually governs, because it is where the build
+fails: **75.40%**, up from 75.14% at 0.3.0. Lose every timeout on a loaded runner
+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
+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
+incremental run took 110 minutes to the rebuild's 103, because a change this wide
+leaves it nothing to reuse.
+
+### Withdrawn
+
+[ADR-0013](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
+executed it. One corpus through `\n`, `\r\n` and `\r` now produces identical
+items, findings and line numbers, as a test.
+
+### Changed
+
+For anyone using the programmatic API: `Diagnostic.rule` is now `AnyRuleId`,
+which is `RuleId` plus the `project:` namespace. An exhaustive `switch` over the
+built-ins needs a default arm. `BaselineOutcome.stale` carries `reason`, and
+`ResolvedCorpus` carries `suppressed`.
+
+## 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
+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.
+
+### Fixed
+
+**A reference-style link was read as a citation of its own label.**
+
+```md
+This depends on [ADR-0001][one].
+
+[one]: 0001-target.md
+```
+
+Every renderer reads that as a link to `0001-target.md`. spec-graph read it as a
+citation of the word `one`, which resolved to nothing - so those two lines
+produced a false `broken-reference` **and** no `depends-on` edge at all. The
+missing half is the worse one: an absent edge is invisible in a report that says
+everything is consistent.
+
+Definitions are now the destination table the labelled forms are read through. A
+label nothing defines is prose, because `[design][one]` renders verbatim when
+nothing says what `one` is. A broken one is reported at the definition, which is
+the line that fixes it, however many places use the label.
+
+**A `@spec-node` directive inside `<script>` or `<pre>` was honoured**, so a page
+explaining how to annotate a document could annotate itself. The four elements
+whose content is not Markdown are masked now, which is the CommonMark reading.
+`<div>` and `<details>` keep their content: a decision written inside a collapsed
+section is still a decision.
+
+**A document could take an id that was not a name.** `id=\"ADR-9\"` inside a
+JavaScript string parses its bare value as a lone backslash, and the document
+then collided with itself, reported a duplicate id against its own file,
+contained itself, and exported as invalid Mermaid. A declared id must carry a
+letter or a digit.
+
+**A percent-escaped destination resolved to nothing.**
+`[Design](docs/my%20design.md)` is what a renderer, a documentation site and
+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).
+
+**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
+dependents wrote the inverse spelling and got no edge, no warning, and a graph
+that reported itself as consistent. Every directional kind is spelled both ways
+now - twenty-five keys became fifty-six - and a test holds the invariant.
+`relates-to` is symmetric and exempt.
+
+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).
+
+**`--verbose --format json` printed human lines onto stdout beside the JSON.**
+
+### Added
+
+- **`unknown-relation-key`** (warn). A front-matter key one edit from a relation,
+  carrying something that could name a document, is reported rather than
+  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).
+- **`--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
+  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.
+- **`--format sarif`**. SARIF 2.1.0, for `check`, so
+  `github/codeql-action/upload-sarif` can turn findings into annotations on the
+  diff with no integration on either side. The `partialFingerprints` are the
+  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).
+
+### Not added
+
+**`--watch`.** A full run is 60 ms, so the loop is one line of shell in whatever
+the developer already uses. A resident process, a debounce timer and `fs.watch`
+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).
+
+### 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
+incremental run read 3.18 points *high* against a full rebuild of the same
+commit, so the claim that incremental errs low was wrong.
+
 ## 0.2.3
 
 ### Fixed

package/README.md

@@ -78,6 +78,7 @@ npx @descent-vtt/spec-graph "docs/**/*.md"
 | `ambiguous-reference` | warn | A citation matching more than one document |
 | `unreciprocated-supersession` | warn | A retired document that never says what replaced it |
 | `state-conflict` | warn | An item whose two state signals disagree about whether work remains |
+| `unknown-relation-key` | warn | A front-matter key one edit from a relation, carrying what looks like a citation |
 | `self-reference` | info | A document delegating to, or depending on, itself |
 
 Override any of them:
@@ -266,6 +267,38 @@ still a relation in the graph no matter what you exclude — not even
 `--ignore-ref "*"` can delete one. See
 [ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
 
+#### A gap that is deliberate
+
+Real filing histories have holes: an ADR number reserved and then withdrawn, a
+document that was folded into another before it was ever committed. Something
+still cites it, and the citation is not a mistake.
+
+There are two mechanisms and the difference is what you are declaring.
+
+**The target is never going to exist** — `ADR-0006` was withdrawn before filing.
+That is a fact about the repository, so declare it once in
+`.spec-graph.json`:
+
+```json
+{ "ignoreReferences": ["ADR-0006"] }
+```
+
+Every citation of it stays quiet, wherever it is written, forever. A glob is
+available and rarely what you want here: `ADR-0006` names one target exactly.
+
+**This particular citation is accepted for now** — it should resolve, one day it
+will, and until then the build should not stop. That is debt, not a fact, and it
+belongs in the baseline, keyed to the one document and the one target:
+
+```json
+{ "rule": "broken-reference", "document": "ADR-0004", "subject": "docs/plans/x.md", "count": 1 }
+```
+
+The same citation from a different document is still reported, and `--ratchet`
+makes the entry disappear the day it is paid. Reach for the first when the
+absence is permanent, the second when it is temporary — and if you cannot say
+which, it is the second.
+
 ### Relations
 
 Relations are read from front matter, from link context, and from explicit
@@ -330,6 +363,9 @@ gate without writing any code:
     ! npx spec-graph query 'document[path^=docs/prd] -depends-on-> document[phase=draft]'
 ```
 
+That shell line is a rule wearing a disguise. Give it a name and a sentence and
+it becomes one — see [your own rules](#your-own-rules) below.
+
 **Grammar**
 
 ```text
@@ -350,6 +386,64 @@ Items inherit their document's lifecycle, so `item[phase=retired]` means what yo
 expect. A query evaluates to **paths**, not endpoints, which is why a finding can
 name both ends and the line that connects them.
 
+## Your own rules
+
+A convention spec-graph never anticipated is a selector plus a sentence. Write
+both in the config file and it becomes a rule like any other:
+
+```json
+{
+  "rules": {
+    "no-draft-dependency": {
+      "query": "document[phase=active] -depends-on-> document[phase=draft]",
+      "message": "{0} depends on {1}, which is still a draft",
+      "hint": "wait for {1} to be accepted, or drop it from {0.path}",
+      "severity": "error"
+    }
+  }
+}
+```
+
+```text
+x docs/adr/0002-delivery.md:4:13  project:no-draft-dependency
+    ADR-0002 depends on ADR-0001, which is still a draft
+    > wait for ADR-0001 to be accepted, or drop it from docs/adr/0002-delivery.md
+```
+
+The finding points at the line that *declares* the relation, because that is
+where a human goes to change the answer — the same discipline every built-in
+follows.
+
+| Field | |
+|---|---|
+| `query` | One selector, or a list of them read as a union. |
+| `message` | The headline. `{0}` is the first node on the path, `{1}` the next; `{1.phase}` and `{0.fm.owner}` read any selector attribute. |
+| `hint` | The next action. Optional, templated the same way. |
+| `severity` | `error`, `warn`, `info` or `off`. Defaults to `warn`. |
+
+It defaults to `warn` on purpose: a rule a team has just written has not yet
+earned the right to fail their build, and the first run of a new convention is
+when it is most likely to be wrong.
+
+The id is the name with `project:` in front, which is why it can never collide
+with a built-in — and why everything else already works. It is baselined by
+`--record-baseline`, silenced by `--rule project:no-draft-dependency=off`,
+escalated by `--strict`, listed by `spec-graph rules`, exempted on journals like
+every other rule about obligations, and emitted as a first-class `ruleId` in
+SARIF, where a project rule describes itself by the selector it is.
+
+Mistakes are reported when the file is read, not discovered as a rule that
+quietly finds nothing:
+
+```text
+spec-graph: .spec-graph.json: rules.no-drafts: mismatched arrow: use -kind-> for
+  one hop or =kind=> for transitive (at character 10)
+spec-graph: .spec-graph.json: rules.owner: "{1.phse}" asks for an attribute
+  nothing has
+```
+
+See [ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md).
+
 ## Directives
 
 Inference covers almost everything, but inference you cannot override is a trap.
@@ -426,7 +520,54 @@ A baseline that expires when somebody reformats a paragraph is worse than none,
 so the entry survives edits, reordering, and the file being renamed — because
 `ADR-0004` is the decision's name, not its location. Repeats are counted rather
 than told apart, which is the deliberate cost of a key with no position in it.
-See [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+
+By default that line is a note and the build stays green: failing because
+somebody fixed something is a strange way to encourage them. But a note in CI
+is a line that scrolls past, and an exemption nobody strikes outlives the defect
+it was written for. A team that has decided its debt only moves one way turns on
+the other side of the ratchet:
+
+```bash
+spec-graph check --baseline .spec-graph-baseline.json --ratchet
+```
+
+Now an undeclared finding fails **and** a declared one that no longer occurs
+fails, each named, with `--record-baseline` as the fix — and the diff of that
+file is the record of what was paid off. See
+[ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+
+## In CI
+
+The exit code is the contract: `0` clean, `1` findings, `2` the tool could not
+run. That is all most pipelines need.
+
+For annotations on the diff rather than a line in a log, emit SARIF and hand it
+to the uploader that already exists:
+
+```yaml
+- run: npx spec-graph --format sarif > spec-graph.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: spec-graph.sarif
+```
+
+Findings land as comments on the changed lines, and they persist across commits
+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.
+
+**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
+to whatever the developer already uses rather than to this tool:
+
+```bash
+npx spec-graph --format json | jq -r '.summary'
+```
 
 ## Configuration
 
@@ -441,8 +582,15 @@ command. spec-graph reads the first of `.spec-graph.json`,
   "ignoreFamilies": ["RFC"],
   "historyPatterns": ["**/JOURNAL_*.md"],
   "baseline": ".spec-graph-baseline.json",
+  "ratchet": true,
   "severities": { "self-reference": "off" },
-  "strict": true
+  "strict": true,
+  "rules": {
+    "no-draft-dependency": {
+      "query": "document[phase=active] -depends-on-> document[phase=draft]",
+      "message": "{0} depends on {1}, which is still a draft"
+    }
+  }
 }
 ```
 
@@ -473,6 +621,20 @@ resolves to your local RFC-0001 with `RFC` on the ignore list. No configuration
 can delete an edge. See
 [ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md).
 
+`--verbose` lists everything they silenced, so one over-broad glob cannot quietly
+turn the check off and look like a clean repository:
+
+```text
+i docs/adr/0001-traps.md:15:3   ignored reference: trap 55 (2 times)
+i docs/rfcs/0002-transport.md:7:69  ignored family: RFC 2119
+```
+
+The JSON report carries the same rows under `suppressed`, without needing the
+flag. What is deliberately *not* listed is a bare identifier spec-graph read as
+prose on its own — `T-1000` was nobody's decision, and listing it would bury the
+entries that were. See
+[ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
+
 Prose like `Phase 1`, `R69`, `Q-120`, `Table 2` and `Step 4` has never needed
 this: an identifier found in prose is only read as a citation when its family
 already exists in the corpus.
@@ -493,8 +655,9 @@ spec-graph rules [--explain]         List the diagnostics.
 --history <glob>        Files that log decisions rather than making them
 --baseline <file>       Accept these findings; report only what is new
 --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 human|json     Report format
+--format <fmt>          human | json | sarif
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -590,6 +753,9 @@ Twelve ADRs, which `spec-graph` validates on every CI run:
 - [ADR-0010 — Configuration belongs to the repository](docs/adr/0010-configuration-belongs-to-the-repository.md)
 - [ADR-0011 — A historical record is not a specification](docs/adr/0011-a-record-is-not-a-specification.md)
 - [ADR-0012 — A baseline is a ratchet, keyed on identity](docs/adr/0012-a-baseline-is-a-ratchet.md)
+- [ADR-0013 — When the scanner is unsure, it hands back prose](docs/adr/0013-the-scanner-hands-back-prose.md)
+- [ADR-0014 — A relation is spelled in both directions](docs/adr/0014-a-relation-is-spelled-both-ways.md)
+- [ADR-0015 — Feedback goes where the tools already look](docs/adr/0015-feedback-goes-where-the-tools-already-look.md)
 
 **Zero runtime dependencies.** Node 22+, native ESM, TypeScript strict with
 `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The Markdown

package/dist/baseline.d.ts

@@ -14,12 +14,12 @@
  * the same reason extraction never touches a disk.
  */
 import type { SpecGraph } from './graph.js';
-import type { Diagnostic, RuleId } from './types.js';
+import { type AnyRuleId, type Diagnostic } from './types.js';
 /** The current file format. Bumped only for a change old files cannot survive. */
 export declare const BASELINE_VERSION = 1;
 /** One class of accepted finding, and how many of it there were. */
 export interface BaselineEntry {
-    readonly rule: RuleId;
+    readonly rule: AnyRuleId;
     /** The specification the finding is about, not the file it was found in. */
     readonly document: string;
     /** What within it: a citation target, or the document at the other end. */
@@ -70,18 +70,32 @@ export interface ParsedBaseline {
 }
 /** Parses a baseline file. Never throws; an unusable file yields an empty one. */
 export declare function parseBaseline(raw: string, source: string): ParsedBaseline;
+/**
+ * An entry the run did not spend, and why.
+ *
+ * The distinction is the whole value of the label. `paid` is the ratchet
+ * working: the defect was fixed and the exemption can be struck. `gone` is not
+ * an achievement at all - the document the entry is about was not in this
+ * corpus, so nothing whatever is known about the defect. Both make the file
+ * stale and both need it re-recorded, but only one of them is good news, and a
+ * report that says "paid" over a narrowed `patterns` glob is congratulating a
+ * team for losing sight of the problem.
+ */
+export interface StaleEntry extends BaselineEntry {
+    readonly reason: 'paid' | 'gone';
+}
 export interface BaselineOutcome {
     /** Findings the baseline does not account for. These are the report. */
     readonly kept: readonly Diagnostic[];
     /** How many were accounted for. Reported as a number, not as a list. */
     readonly suppressed: number;
     /**
-     * Entries whose debt has been paid, wholly or partly.
+     * Entries whose debt was not spent, wholly or partly.
      *
      * The ratchet: once a repository is clean of something, saying so in the file
      * stops it coming back unnoticed.
      */
-    readonly stale: readonly BaselineEntry[];
+    readonly stale: readonly StaleEntry[];
 }
 /**
  * Removes the findings a baseline accounts for.

package/dist/baseline.js

@@ -14,6 +14,7 @@
  * the same reason extraction never touches a disk.
  */
 import { RULE_IDS } from './rules.js';
+import { isProjectRule } from './types.js';
 /** The current file format. Bumped only for a change old files cannot survive. */
 export const BASELINE_VERSION = 1;
 export const EMPTY_BASELINE = Object.freeze({ version: BASELINE_VERSION, findings: [] });
@@ -128,7 +129,12 @@ function readEntry(row, where, problems) {
     }
     const fields = row;
     const rule = fields['rule'];
-    if (typeof rule !== 'string' || !RULE_IDS.includes(rule)) {
+    // A project rule is accepted on its namespace alone, because the baseline is
+    // read before the configuration that defines it has any say - and an entry
+    // rejected here would silently un-accept debt a team had already signed off.
+    // A name nothing defines suppresses nothing and is reported as stale, which
+    // is the same answer by a route that keeps the file readable.
+    if (typeof rule !== 'string' || !(RULE_IDS.includes(rule) || isProjectRule(rule))) {
         problems.push(`${where}: unknown rule ${JSON.stringify(rule)}`);
         return null;
     }
@@ -177,7 +183,13 @@ export function applyBaseline(graph, diagnostics, baseline) {
         const unspent = budget.get(key) ?? 0;
         if (unspent <= 0)
             continue;
-        stale.push({ ...entry, count: Math.min(unspent, entry.count) });
+        // Asked of the graph rather than of the filesystem, because the graph is
+        // what this run looked at. A document that still exists on disk and fell
+        // outside the include patterns is gone for the purposes of the answer, and
+        // that is the case worth telling apart - it is the one a team reaches by
+        // editing a glob rather than by fixing anything.
+        const reason = graph.document(entry.document) === undefined ? 'gone' : 'paid';
+        stale.push({ ...entry, count: Math.min(unspent, entry.count), reason });
         // An entry counted once; a duplicate key in a hand-edited file must not
         // claim the same surplus twice.
         budget.set(key, 0);