@descent-vtt/spec-graph 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,430 @@
 Notable changes, newest first. Versions follow [semver](https://semver.org):
 a patch fixes behaviour without asking anything of a repository that upgrades.
 
+## 0.5.0
+
+One shipped feature turned out to have shipped a false positive, and the
+predicate that was documented as dangerous is now an automaton that cannot
+backtrack. Four of the ADR suite's open questions answered by building the
+thing, seven directions declined with a reason, one deferred with its design
+settled so it is not re-litigated.
+
+### Fixed
+
+**A register's decisions answer for the front matter above them.** This was a
+false positive in the feature 0.4.0 led with, and the worst kind: confident and
+unanswerable. A region answered *nothing* for `fm.owner`, `!=` against an absent
+value is a mismatch, so a repository writing
+
+```json
+"rules": { "owned": { "query": "document[fm.owner!=platform]" } }
+```
+
+was told twice that a register saying `owner: platform` is not owned by
+platform — with the message rendering `{0.fm.owner}` as the literal placeholder,
+because there was nothing to put there.
+
+A region now carries its file's front matter minus two kinds of key. A
+**relation** key stays behind: `supersedes:` at the top of a register supersedes
+on behalf of the register, not of each decision in it. So does a key the region
+**answers for itself** — its identifier, status, title and aliases, which are
+precisely the things a register exists to vary row by row.
+[ADR-0009](docs/adr/0009-a-specification-is-a-region.md) carried this as a
+narrowed open question and called it a gap. It was a defect, and it was found by
+pointing the binary at a register rather than by reading the code.
+
+Read from the other side, this can *add* findings: a rule phrased positively,
+`document[fm.deprecated]`, now matches a register's decisions as well as the
+register. That is the same correction - the decisions really are described by
+the front matter above them - and worth knowing before upgrading a repository
+that keeps registers and writes rules about front matter.
+
+### Added
+
+**`~=` is matched by an automaton that cannot backtrack.**
+[ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md) documented this hazard
+with `(a+)+$`, which nobody writes, and priced the fix at "worth it only if a
+real repository hangs". Both were wrong. `^([A-Za-z0-9_]+[ ]?)+$` is what
+somebody writes to check that a title is words separated by single spaces:
+
+| subject | `RegExp` | now |
+| --- | ---: | ---: |
+| `the quick brown fox jumps over the lazy dog!` | 0.9s | 11us |
+| `... over the lazy dog and!` | 5.4s | 12us |
+| `... over the lazy dog and keeps!` | 103s | 13us |
+
+A word of k letters can be cut into pieces 2^(k-1) ways and a backtracking
+engine tries the product, so a sixty-character title does not finish this year —
+unattended, on every build, against a corpus whose titles the author of the rule
+has not read. The work is now exactly O(pattern x subject), and **no stage of
+this pipeline can take longer than its input.**
+
+It costs a dialect. Backreferences and lookaround are not regular, so they are
+refused while the selector is read, with the character pointed at — as are three
+things `RegExp` accepts and should not: an unknown letter escape, which `RegExp`
+reads as the letter, so a pattern meant as an anchor silently matches a capital
+A; a Unicode property escape, which needs a table this package will not carry;
+and octal escapes. Everything else works, and a pattern that does not parse is
+now a usage error rather than a pattern that silently matches nothing.
+
+Verified against the engine it replaces: **1.33 million pattern-subject pairs,
+zero disagreements**, 19,000 of them committed as a gate. It earned that twice
+over, on one clause of the language specification read backwards in two
+different places - the word characters `` recognises, and whether a character
+whose upper case is ASCII may match `[A-Z]`. The second was found by the
+mutation score pointing at a corpus with a blind spot in it rather than at a
+test. See [ADR-0017](docs/adr/0017-a-predicate-must-finish.md) and
+[ADR-0007](docs/adr/0007-mutation-testing.md).
+
+**Configuration is discovered upward, and the file holding it is the root.**
+
+```bash
+cd packages/auth && spec-graph check     # the repository's rules, the
+                                         # repository's patterns, the
+                                         # repository's paths
+```
+
+[ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md) worried
+that discovery would make a run depend on where it started. Reading the working
+directory already did, and silently: a check from a package directory found no
+configuration, ran no project rules, used the default include patterns, and
+printed a verdict in the same shape as the real one. Because the directory
+holding the file becomes the root, and every path here is relative to the root,
+a run from anywhere inside the repository now produces **byte-identical** output
+to a run from the top. The walk stops at the repository — a directory holding
+`.git` — so a stray file in a home directory cannot reach it. `--root` names the
+root yourself and turns discovery off, and a path typed on the command line
+stays relative to where you typed it. See
+[ADR-0018](docs/adr/0018-the-configuration-file-is-the-root.md).
+
+**`spec-graph query project:<rule>` runs a registered rule by name.** The rule
+is already compiled by the time the command runs, and the alternative was
+copying its selector back out of the configuration file by hand. Several
+selectors are deduped the way the check dedupes them, so this prints the set the
+check reports on; `--verbose` names them, which is the question a team
+calibrating a convention is actually asking. Built-in rules are deliberately not
+addressable this way: a project rule *is* its selector, while a built-in is a
+selector plus judgement, and printing a set that differs from the findings would
+invite the wrong conclusion.
+
+**`spec-graph rules <rule-id> --explain` names the ADR that decided it.** A rule
+that fires is a claim about somebody's repository, and the reasoning behind the
+claim was in a document nobody could find from the message. The table holds a
+pointer rather than a paraphrase, because a second copy of the reasoning would
+drift from the first — and a test holds every pointer to a file this corpus
+checks, so a renamed ADR breaks the link in the same run that breaks the
+reference.
+
+**`--format markdown`** writes the same facts as a GitHub-flavoured table, for
+`$GITHUB_STEP_SUMMARY` or a pull-request comment:
+
+```yaml
+- run: npx spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
+```
+
+SARIF puts a finding on the line that caused it, which is where somebody fixing
+one wants it, and says nothing at all to the person deciding whether to merge.
+This leads with the verdict, counts the corpus, gives every finding its hint,
+and *names* the stale baseline entries rather than counting them — on a pull
+request a count is the one thing a reader cannot act on. No environment
+detection: a format that changed because a variable was set would be a format
+nobody controls.
+
+### Changed
+
+Four behaviours move, none of them a rule. Three can turn a run that passed
+into a usage error, which is the point in each case; the fourth changes what a
+run from a subdirectory reports.
+
+- **A `~=` pattern that does not parse is a usage error**, with the character
+  pointed at, rather than a pattern that matches nothing. The old silence was
+  indistinguishable from a rule that ran and found none.
+- **A `~=` pattern using a backreference, lookaround, `\p{...}`, an octal
+  escape or an unknown letter escape is refused**, for the reasons above. If
+  you have one, the message says which construct and why; `^=`, `$=` and `*=`
+  cover the fixed-prefix, suffix and substring cases without a pattern at all.
+- **A run from a subdirectory now finds the repository's configuration**, and
+  reports repository-relative paths because the configuration's directory is
+  the root. A script that read paths out of a nested run will see them change.
+  `--root` keeps the old behaviour exactly.
+- **`spec-graph rules <word>` reads the word as a rule id** and reports one
+  that names nothing. It used to be collected as an include pattern, which the
+  command has no use for.
+
+### Declined
+
+Each with its reasoning in the ADR that owns the question, rather than in a
+roadmap nobody reads:
+
+- **An MCP server.** The capability is already here — `analyseSources()` takes
+  text, `--format json` is the answer — so what is left is a protocol
+  implementation, hand-written to keep the dependency count at zero, tracking a
+  specification that is still moving, to expose three tools that are three shell
+  commands an agent can already run.
+- **A language server.** The right shape for editor feedback and a second
+  package's worth of work, and SARIF already reaches the problems pane. Two of
+  the three hard parts are done — `analyseSources()` needs no file on disk, and
+  every finding carries a span — so it should start when somebody wants hover
+  and go-to-definition, not as a way of delivering diagnostics that already
+  arrive.
+- **A `--watch` daemon.** Declined again, with a better reason than last time:
+  the incremental half of it cannot work. Whether a bare `ADR-0099` in prose is
+  a citation depends on which families exist elsewhere, and a near-miss
+  suggestion is computed against every sibling — touch one file and the honest
+  set to recompute is all of them. Which is fine, because the pipeline is a pure
+  function and 60 ms long. And then the resident index buys nothing, and the
+  feature is a loop.
+- **Code frames in the terminal.** The report already prints
+  `file:line:column`, which every terminal in use turns into a click, and
+  `renderMatch` already prints the shape of a multi-hop path.
+- **Provenance and attestation metadata.** A timestamp in the output means no
+  two reports of one corpus are ever byte-identical, which is the property every
+  format here is built to have. The commit is something CI already knows.
+- **An interactive SVG.** A layout engine or a vendored library is a runtime
+  dependency wherever it sits in the tarball, and its bytes depend on a layout
+  pass. `dot` and `mermaid` hand layout to tools built for it, and both are
+  text. The other half of that ask - phase styling and typed edges in the
+  Mermaid export - has been there since the first release. What is left is a
+  `subgraph` per directory, which changes the shape of an export somebody's
+  documentation build is parsing, to group a corpus that is one directory in
+  most repositories.
+- **Definition lists as a register form.** Two unrelated syntaxes behind one
+  name: raw `<dl>`, which the scanner leaves as prose deliberately because
+  ADR-0001's masking guarantee is what keeps a code fence quiet, and the
+  PHP-Markdown-Extra form, which is not CommonMark and which no corpus here
+  contains. Either would need a new parser for a convention nobody has written
+  down.
+
+One is deferred rather than declined, with half its design recorded so it is not
+re-litigated: a **relational diff** between two states of the graph, taken
+between two `--graph-format json` exports rather than between two git revisions,
+because revisions mean spawning a binary underneath a pipeline that is a pure
+function of text. See
+[ADR-0015](docs/adr/0015-feedback-goes-where-the-tools-already-look.md).
+
+### Verified
+
+| | |
+|---|---|
+| `npm run lint` | pass |
+| `npm test` | 833 passing, 21 files |
+| `npm run selfcheck` | pass, over 21 documents and 159 relations |
+| `npm run test:mutation` | 80.54% over 9,697 mutants, 74m27s |
+| hosted full run, which governs | **76.83%**, 168m06s |
+| hosted incremental run, same commit | 76.43%, 64m27s |
+| `break` | unchanged at 70 |
+
+79.41% over 8,585 mutants at 0.4.0 against 80.54% over 9,697 here, on the same
+machine: 1,112 more mutants and a point higher. The new code carries itself -
+`regex.ts` at **90.61%**, `config.ts` at 92.37%, `project-rules.ts` still at
+99.50% - and lose all 343 timeouts and the figure reads 77.00%.
+
+The first full run of this release read 80.35%, and its survivor list is where
+the last defect came from. A mutant on the line stepping past `^` in a negated
+class survived 1.33 million differential comparisons, because the corpus only
+ever tested classes against two-character subjects; one-character subjects
+killed it and then caught `[A-Z]` matching U+017F. `report.ts` went from 66.30%
+to 70.84% on the same pass, once the Markdown tests asserted the table's
+structure - rectangular rows, a blank line before every block, every summary
+number present - rather than fragments of its text. What remains there is
+mostly the older formatters.
+
+Between those two runs `rules.ts` moved from 79.42% to 76.02% and
+`directives.ts` from 77.92% to 74.03%, with neither file touched: the tests added
+in between changed which tests `perTest` believes cover which mutants.
+[ADR-0007](docs/adr/0007-mutation-testing.md) has recorded that shape for two
+releases, and it is why a per-file drop is a question and not an answer.
+
+The hosted number is the one that governs, because it is where the build fails:
+**76.83%**, up from 75.40% at 0.4.0. Lose every timeout and it reads 73.31%, the
+first time the pessimistic figure has cleared the guard by more than three
+points.
+
+The incremental run on the same commit read 0.40 points low - the third
+observation after 3.18 high at 0.3.0 and 1.29 low at 0.4.0, and the reason
+[ADR-0007](docs/adr/0007-mutation-testing.md) calls it a signal rather than a
+figure. The tag's run also saved its own report to the cache, which is the first
+time the cache-key fix from 0.4.0 has been seen doing its job.
+
+**The rebuild took 168 of its 180 minutes.** 13% more mutants than 0.4.0, and 63%
+longer on the hosted runner against 15% longer locally. At 0.4.0's old cap of
+120 it would have been cancelled with nothing reported. The cause is not yet
+attributed - runner variance and the new differential test are both candidates -
+and the choice between raising the cap again and cutting per-mutant cost is left
+open in ADR-0007 until it is.
+
+## 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
@@ -99,11 +523,12 @@ text. Reasoning in
 
 ### Measured
 
-684 tests, and a mutation score of **79.69% over 8,126 mutants** - up from
-77.16% over 7,720. The guard stays at `break: 70`, because the same source
-measured twice on the same machine, with only test cases added between the runs,
-moved nine untouched files by more than a point each in both directions. See
-[ADR-0007](docs/adr/0007-mutation-testing.md).
+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
 

package/README.md

@@ -363,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
@@ -383,6 +386,83 @@ 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.
 
+`~=` is a regular expression matched by an automaton that cannot backtrack, so a
+predicate is linear in the subject whatever the pattern — `^([A-Za-z0-9_]+[ ]?)+$`
+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. See [ADR-0017](docs/adr/0017-a-predicate-must-finish.md).
+
+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
+the keys a region owns itself, its identifier and status and title, and any key
+that declares a relation, stay on the file. See
+[ADR-0009](docs/adr/0009-a-specification-is-a-region.md).
+
+## 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.
+
+To see what a rule matches without copying its selector back out of the file:
+
+```bash
+spec-graph query project:no-draft-dependency --verbose
+```
+
+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.
@@ -523,10 +603,24 @@ command. spec-graph reads the first of `.spec-graph.json`,
   "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"
+    }
+  }
 }
 ```
 
+The file is looked for in the working directory and then upward, as far as the
+repository — a directory holding `.git` — and **the directory holding it becomes
+the root**. So a run from `packages/auth` reports what a run from the top
+reports, byte for byte, because every path here is relative to the root. The
+nearest file wins, `--root` names the root yourself and turns discovery off, and
+a path typed on the command line stays relative to where you typed it. See
+[ADR-0018](docs/adr/0018-the-configuration-file-is-the-root.md).
+
 A flag always wins over the file, and list flags **add** to it rather than
 replacing it — a `--ignore-ref` on the command line is one more exclusion, not a
 decision to discard what the repository already declared. `--verbose` prints
@@ -554,6 +648,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.
@@ -563,10 +671,14 @@ already exists in the corpus.
 ```text
 spec-graph [check] [patterns...]     Validate the graph. The default.
 spec-graph query <selector>          Run a selector, print matching paths.
+spec-graph query project:<rule>      Run a registered rule by its id.
 spec-graph graph [patterns...]       Export for Graphviz, Mermaid or JSON.
-spec-graph rules [--explain]         List the diagnostics.
+spec-graph rules [rule-id]           List the diagnostics; --explain adds
+                                     each selector and the ADR behind it.
 
---root <dir>            Directory patterns resolve against
+--root <dir>            Directory patterns resolve against, and the root of the
+                        run. Without it the config file is discovered upward and
+                        its directory is the root
 --ignore <glob>         Skip paths (repeatable)
 --ignore-ref <glob>     Do not report these reference targets (repeatable)
 --family <name>         Families a bare identifier may name (repeatable)
@@ -576,7 +688,7 @@ spec-graph rules [--explain]         List the diagnostics.
 --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
+--format <fmt>          human | json | sarif | markdown
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -599,6 +711,19 @@ rather than a silent success.
   run: npx spec-graph "docs/**/*.md" --format json > spec-graph.json
 ```
 
+`--format markdown` writes the same facts as a table, for the place reviewers
+actually look:
+
+```yaml
+- name: Summarise the specification graph
+  if: always()
+  run: npx spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
+```
+
+It leads with the verdict, counts the corpus, gives every finding its hint, and
+*names* the baseline entries that no longer occur rather than counting them —
+on a pull request a count is the one thing a reader cannot act on.
+
 The JSON report is versioned, flat, and carries start and end positions for
 every finding, so a bot can annotate a diff:
 
@@ -658,7 +783,7 @@ exported. Reporters, editor extensions and custom rules are all first-class.
 
 ## Design
 
-Twelve ADRs, which `spec-graph` validates on every CI run:
+Eighteen 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)
@@ -675,11 +800,16 @@ Twelve ADRs, which `spec-graph` validates on every CI run:
 - [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)
+- [ADR-0016 — A query needs a sentence before it is a rule](docs/adr/0016-a-query-needs-a-sentence.md)
+- [ADR-0017 — A predicate must finish](docs/adr/0017-a-predicate-must-finish.md)
+- [ADR-0018 — The configuration file is the root](docs/adr/0018-the-configuration-file-is-the-root.md)
 
 **Zero runtime dependencies.** Node 22+, native ESM, TypeScript strict with
 `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The Markdown
-scanner, the front-matter reader, the glob matcher and the query parser are all
-written here, so the whole package is auditable in an afternoon.
+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.
 
 **Verified, not just covered.** 411 tests; 94.2% statement and 96.9% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation