@avi2dg/checks 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.15.0
+
+Released 2026-09-25.
+
+### Features
+
+- **scripts:** hold living docs to prose rules and resolvable references in checks-docs (#42)
+
 ## 0.14.0
 
 Released 2026-09-25.

package/CONTRIBUTING.md

@@ -81,7 +81,7 @@ To place a change:
 
 This repository holds itself to the kit, with two exceptions of its own.
 Its `.dependency-cruiser.cjs` redeclares `no-orphans` with the plugin entry added to its `pathNot`.
-Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, the one file under its Effect path that a host loads without `node_modules`.
+Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, whose synchronous `refused()` a host loads without `node_modules`.
 
 ## Related topics
 

package/dist/feature-rules.js

@@ -40,6 +40,12 @@ var PathGlob = Schema2.String.check(Schema2.isPattern(new RegExp(`^${SEGMENT}(?:
   identifier: "PathGlob",
   description: "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./"
 });
+var DocGlob = Schema2.String.check(Schema2.isPattern(new RegExp(`^(?:${SEGMENT}/)*${FILE}$`), {
+  expected: "a glob from the repository root such as README.md or docs/**/*.md: * within a segment, ** as a whole one, a file name with an extension last"
+})).annotate({
+  identifier: "DocGlob",
+  description: "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last"
+});
 var LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
 var DirectoryPath = Schema2.String.check(Schema2.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
   expected: "a directory from the repository root such as src/billing, with no glob and no trailing slash"
@@ -133,6 +139,9 @@ var Docs = Schema2.Struct({
     explanation: pagesIn("an explanation, which says why")
   }).annotate({
     description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+  })),
+  forConsumers: Schema2.optionalKey(Schema2.Array(DocGlob).annotate({
+    description: "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json"
   }))
 });
 var Quality = Schema2.Struct({

package/docs/configs/quality-file.md

@@ -52,6 +52,7 @@ The kit's bins find the file at the git root and read it there:
 | `agentRules.on` | agent Rule selection, not the kit | catalogued Rules switched on for this repository |
 | `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched off for this repository |
 | `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob, as [checks-docs](../gates/checks-docs.md) says |
+| `docs.forConsumers` | `checks-docs` | the living docs that speak to a repository installing this one, by glob, whose `bun run` commands name that repository's scripts |
 
 <!-- end generated quality-keys -->
 

package/docs/design.md

@@ -25,7 +25,8 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A bump not newer than the release before it is a revert: it cancels every release above the version it returns to, and a tag only keeps a reverted release that was already published.
   The committed changelog is the record of what was released: a version older than the newest it lists and absent from it was never published, and its commits go into the next release.
   A section keeps the date it was written with, since the squash merge that lands the release commit may fall on another day.
-  Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format; the bodies are the branch's own messages, which nothing lints.
+  Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format.
+  The bodies are the branch's own messages, which nothing lints.
   The release path needs no `contents: write`: the changelog arrives in the release commit's pull request, not from a workflow that pushes.
 - `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a hook running without `node_modules`, a `.cjs` or `.mjs` config and `jq` all parse it with nothing installed, and nobody runs a repository's own code to learn its policy.
   It holds declarations only.
@@ -71,6 +72,22 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A repository adopts the templates as its files change, and an untouched file is listed as advisory rather than failing a change that never read it.
 - A task heading is verb first, and review holds it there rather than the check.
   No word list tells `Test layout` from `Test the layout`, and a check that passes the noun is worse than none.
+- The prose rules judge only the lines a change adds or edits, the way `checks-comment-gate` judges comments.
+  Text nobody touched never turns a change red, a record keeps the words it was written in, and a repository needs no cleanup pass before the gate runs.
+- A living doc takes one sentence per line, so a changed line is a changed sentence.
+  Under a hard wrap a one-word edit reflows a paragraph, and the gate would then demand fixes to sentences the edit never touched.
+- An agent file such as `AGENTS.md` takes the separator rules and no other prose rule.
+  One sentence per line serves the people who review a doc's diffs, and an agent file keeps each entry to one line however many sentences it holds.
+- `scripts/prose-matchers.ts` imports nothing, so the gate and a write-time hook run one matcher and refuse in the same words.
+  A hook bundle ships without `node_modules`, so a matcher that needed Vale or a package could not refuse at write time.
+- Readability grades and words such as easy stay out of the prose rules.
+  A score cannot fail a change without failing correct prose, and a suggestion nobody runs an editor for is never seen.
+- A path, link or command on a line the range leaves alone fails when the range broke it, as by deleting the file it names.
+  A reference goes stale when the code it names moves far more often than when its own line is edited, so a gate on edited lines alone would miss the usual break.
+- A path under a top directory the repository lacks names a file in another repository, such as a consumer's, and no program tells that from a typo.
+  A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
+- The command check passes over the docs a repository declares under `docs.forConsumers`.
+  This kit's README and reference pages speak to a consuming repository, whose scripts are not this one's, and no program tells an example for a consumer from an instruction for a contributor.
 
 ## Related topics
 

package/docs/gates/checks-docs.md

@@ -1,10 +1,12 @@
 # checks-docs
 
-`checks-docs` is the gate that holds each doc file a change touches to the template for its kind, and a reader looks it up to learn which template a file answers to.
+`checks-docs` is the gate that holds each doc file a change touches to the template for its kind, each line a change adds to a living doc or an agent file to the prose rules, and each path, link and command a living doc names to what the repository holds, and a reader looks it up to learn what a doc file answers to.
 
 ## What it checks
 
 It holds each doc file a change touches to the template for its kind, and lists every other doc file that does not conform yet without failing.
+It holds each line a change adds or edits in a living doc or an agent file to the prose rules, as [The prose rules](#the-prose-rules) says.
+It fails when a living doc names a path, link or command that does not resolve, and the range added it or broke it, as [Paths, links and commands](#paths-links-and-commands) says.
 The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
 
 ```sh
@@ -51,12 +53,81 @@ A template decides a file's structure, and the template file itself is the refer
 - A changelog lists its releases newest first, each opening with a `Released YYYY-MM-DD.` line.
 - A how-to or tutorial page numbers its steps.
 - `CLAUDE.md` is its template word for word.
-  It is a fixed agent pointer rather than a people doc, so the separator ban does not apply to it: people docs take no em dash, en dash, parenthesis or hyphen used as a dash, and no semicolon, and `checks-docs` does not check separators.
+  It is a fixed agent pointer rather than a living doc, so it takes only the prose rules for agent files.
+
+## The prose rules
+
+A line a change adds or edits in a living doc or an agent file is held to the prose rules, and a line the change leaves alone is not, so a repository needs no cleanup pass before it runs them.
+
+<!-- generated living-docs: bun run build writes it from scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+
+A living doc is one of these:
+
+- a `README.md` or `CONTRIBUTING.md` in any directory
+- a Markdown page under `docs/`
+
+An agent file is a `AGENTS.md` or `CLAUDE.md` in any directory, and takes only the rules the table below marks for agent files.
+
+These are records, and take no prose rule:
+
+- a file in `docs/adr/`
+- a file whose name opens with four digits, as in `0001-` or `2026-05-08-`
+- a `CHANGELOG.md`
+
+<!-- end generated living-docs -->
+
+<!-- generated prose-rules: bun run build writes it from PROSE_RULES in scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+
+| Refused | For example | Write instead | In agent files |
+| --- | --- | --- | --- |
+| an em dash | `—` | End the sentence, or use a comma | yes |
+| an en dash | `–` | End the sentence, or use a comma | yes |
+| a parenthesis other than the plural `(s)` | `(` | Make the aside its own sentence, or set it off with commas | yes |
+| a hyphen used as a dash | `a - b` or `a -- b` | End the sentence, or use a comma | yes |
+| a semicolon | `;` | Use two sentences | yes |
+| a promise about the future | `until #11`, `is planned`, `will soon`, `coming soon`, `in a future release` | Say what is true now | no |
+| a sentence that opens by talking about the page | `This page explains` | Talk directly about the subject | no |
+| a second sentence on one line | `It builds. It ships.` | Start it on its own line | no |
+| a sentence that runs across lines | `It builds` with `and ships.` on the next line | Join the sentence onto one line | no |
+
+<!-- end generated prose-rules -->
+
+A line holds one sentence, so a changed line is a changed sentence.
+A bold label that opens a line, as in `**Status.**`, heads the sentence after it rather than counting as one.
+Fenced code, inline code, link destinations, URLs, HTML comments and front matter are not prose, so no rule reads them.
+Readability scores and word choice, such as easy, are not checked.
+
+`scripts/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
+A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/prose-matchers.ts`, to refuse the same lines at write time.
+
+## Paths, links and commands
+
+Each reference a living doc names has to resolve at the head commit:
+
+- A path in inline code that ends in a file extension, such as `scripts/lint.ts`, names a file from the root or from the doc's directory.
+- A relative Markdown link names a file or a directory, and its anchor names a heading in the file it links, as GitHub derives the anchor, or an explicit `id`.
+- A `bun run` command in code names a script in the nearest `package.json`, a bin in `node_modules/.bin`, or a file that exists.
+
+A reference that does not resolve fails when it sits on a line the range adds or edits.
+It fails on any other line when the range broke it, as by deleting the file it names or renaming the heading it links, and is listed as advisory when it was broken before the range.
+A path under a top directory the repository lacks at both ends of the range names another repository's file, such as a consumer's, and is passed over.
+So is a path git ignores, since a clean checkout lacks a generated file by design.
+
+A doc that speaks to a repository installing this one is declared under `docs.forConsumers` in `quality.json`, and its commands are not held to this repository's `package.json`:
+
+```json
+"docs": {
+  "forConsumers": ["README.md", "docs/gates/*.md"]
+}
+```
 
 ## What it reads
 
 It reads each Markdown file from the head commit, and `docs.pages` from `quality.json`.
 A file the range adds, changes or renames is held to its template, and a file it deletes is not.
+It reads the lines the range adds or edits from the diff, with renames detected, so a renamed doc is judged only on the lines the rename changed.
+It reads the files tracked at both ends of the range, the `scripts` of each `package.json` a living doc sits under, and `docs.forConsumers` from `quality.json`.
+From the working tree it reads the ignore files git reads, and `node_modules/.bin`.
 
 ## Arguments
 
@@ -72,24 +143,30 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template |
-| 1 | a doc file the range touches does not |
-| 2 | `quality.json` does not decode, or a ref does not resolve |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules, and it adds or breaks no reference that does not resolve |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule, or the range adds or breaks a reference that does not resolve |
+| 2 | `quality.json` or a `package.json` does not decode, or a ref does not resolve |
 
 ## Sample output
 
 ```
-docs: 2 violation(s) in the doc files the range touches:
+docs: 4 violation(s):
   README.md:1: lacks `## Where things are`
+  README.md:12: carries `;`, a semicolon. Use two sentences
+  README.md:20: names `scripts/bild.ts`, which is not in the repository
   docs/parts.md: is a page under docs/ with no mode; declare it under docs.pages in quality.json as tutorial, how-to, reference, explanation
 docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
   docs/adr/0001-quality-gates.md: 5 violation(s)
+docs: advisory, 1 path(s), link(s) or command(s) the living docs name were broken before the range:
+  docs/parts.md:9: links to `suppliers.md#prices`, and `docs/suppliers.md` has no heading with that anchor
 ```
 
 ## Opting out
 
 It applies to every repository, so no selection leaves it out.
 A file the range leaves alone is only listed as advisory, so a repository adopts the templates as its files change.
+A line the range leaves alone takes no prose rule, so a repository adopts the prose rules as its lines change.
+A doc listed under `docs.forConsumers` holds no `bun run` command to this repository's `package.json`.
 `checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
 
 ## Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "scripts/mutation-compare.ts",
     "scripts/ci-wiring.ts",
     "scripts/comment-matchers.ts",
+    "scripts/prose-matchers.ts",
     "scripts/comments.ts",
     "scripts/comment-gate.ts",
     "scripts/suppressions-ratchet.ts",
@@ -44,6 +45,8 @@
     "scripts/docs.ts",
     "scripts/doc-outline.ts",
     "scripts/doc-rules.ts",
+    "scripts/doc-references.ts",
+    "scripts/doc-snapshot.ts",
     "scripts/doc-templates.ts",
     "templates/",
     "presets/effect.oxlint.json",
@@ -68,6 +71,7 @@
     "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
     "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
     "./scripts/comment-matchers.ts": "./scripts/comment-matchers.ts",
+    "./scripts/prose-matchers.ts": "./scripts/prose-matchers.ts",
     "./scripts/comments.ts": "./scripts/comments.ts",
     "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
     "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",

package/quality.schema.json

@@ -285,6 +285,13 @@
           },
           "additionalProperties": false,
           "description": "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+        },
+        "forConsumers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DocGlob"
+          },
+          "description": "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json"
         }
       },
       "additionalProperties": false,
@@ -382,6 +389,11 @@
     "RuleName": {
       "type": "string",
       "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "DocGlob": {
+      "type": "string",
+      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)\\/)*(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
+      "description": "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last"
     }
   }
 }

package/scripts/comment-gate.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, Option } from "effect";
 import { refused, syntaxOf } from "./comments.ts";
-import { git, parentOrEmptyTree } from "./git.ts";
+import { changedLines, git, parentOrEmptyTree } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 
 export type GateResult = {
@@ -16,64 +16,21 @@ function readable(path: string): boolean {
   return syntaxOf(path) !== undefined;
 }
 
-function newPathOf(line: string): string | undefined {
-  const path = line.startsWith("+++ b/") ? line.slice("+++ b/".length) : line.slice("+++ ".length);
-  return path === "/dev/null" ? undefined : path;
-}
-
-const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
-
-export function parseAddedLines(diff: string): Map<string, Set<number>> {
-  const added = new Map<string, Set<number>>();
-  let path: string | undefined;
-  let line = 0;
-  let inHunk = false;
-  for (const row of diff.split("\n")) {
-    if (row.startsWith("+++ ")) {
-      path = newPathOf(row);
-      inHunk = false;
-      continue;
-    }
-    const hunk = HUNK.exec(row);
-    if (hunk !== null) {
-      line = Number(hunk[1]);
-      inHunk = true;
-      continue;
-    }
-    if (!inHunk || path === undefined) continue;
-    if (row.startsWith("+")) {
-      let lines = added.get(path);
-      if (lines === undefined) {
-        lines = new Set<number>();
-        added.set(path, lines);
-      }
-      lines.add(line);
-      line += 1;
-    } else if (row.startsWith("-")) {
-      continue;
-    } else {
-      line += 1;
-    }
-  }
-  return added;
-}
-
 const show = (rev: string, path: string, root: string) =>
   git(["show", `${rev}:${path}`], root).pipe(Effect.option);
 
 export const runRange = Effect.fn("runRange")(function* (root: string, base: string, head: string) {
-  const diff = yield* git(["-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", base, head], root);
-  const added = parseAddedLines(diff);
+  const added = yield* changedLines(base, head, [], root);
   const violations: string[] = [];
-  let addedLines = 0;
+  let lineCount = 0;
   for (const [path, lines] of added) {
-    addedLines += lines.size;
+    lineCount += lines.size;
     if (!readable(path)) continue;
     const source = yield* show(head, path, root);
     if (Option.isNone(source)) continue;
     violations.push(...(yield* refused(path, source.value, lines)));
   }
-  return { files: added.size, addedLines, violations };
+  return { files: added.size, addedLines: lineCount, violations };
 });
 
 export function report({ files, addedLines, violations }: GateResult): string {

package/scripts/doc-references.ts

@@ -0,0 +1,190 @@
+import { scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
+
+export type ReferenceKind = "path" | "link" | "command";
+
+export type Unresolved = {
+  readonly kind: ReferenceKind;
+  readonly line: number;
+  readonly named: string;
+  readonly message: string;
+  readonly missing:
+    | { readonly type: "file"; readonly path: string }
+    | { readonly type: "script"; readonly name: string; readonly packageDirectory: string }
+    | { readonly type: "anchor" };
+};
+
+export type Snapshot = {
+  readonly files: ReadonlySet<string>;
+  readonly directories: ReadonlySet<string>;
+  readonly roots: ReadonlySet<string>;
+  readonly anchors: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly scripts: ReadonlyMap<string, ReadonlySet<string>>;
+};
+
+export const PACKAGE_MANIFEST = "package.json";
+
+export function rootsOf(files: readonly string[]): readonly string[] {
+  return files.flatMap((file) => (file.includes("/") ? [file.slice(0, file.indexOf("/"))] : []));
+}
+
+export function snapshotOf(
+  files: readonly string[],
+  anchors: ReadonlyMap<string, ReadonlySet<string>>,
+  scripts: ReadonlyMap<string, ReadonlySet<string>>,
+  alsoRoots: readonly string[] = [],
+): Snapshot {
+  const directories = new Set<string>([""]);
+  for (const file of files) for (let at = file.indexOf("/"); at >= 0; at = file.indexOf("/", at + 1)) directories.add(file.slice(0, at));
+  return { files: new Set(files), directories, roots: new Set([...rootsOf(files), ...alsoRoots]), anchors, scripts };
+}
+
+function directoryOf(path: string): string {
+  return path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+}
+
+function normalize(path: string): string | undefined {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part !== "..") parts.push(part);
+    else if (parts.pop() === undefined) return undefined;
+  }
+  return parts.join("/");
+}
+
+function within(directory: string, path: string): string | undefined {
+  return normalize(directory === "" ? path : `${directory}/${path}`);
+}
+
+function exists(snapshot: Snapshot, path: string): boolean {
+  return snapshot.files.has(path) || snapshot.directories.has(path);
+}
+
+const PARENT = /^\.\.\//;
+const PATH = /^((?:\.{1,2}\/)*(?:[\w.@-]+\/)+[\w.@-]+\.(?:ts|tsx|mts|cts|js|jsx|cjs|mjs|md|mdx|json|jsonc|sh|bash|zsh|toml|nix|lua|ya?ml|txt|py|rs|go|css|html))(?::\d+(?::\d+)?)?$/;
+
+function unresolvedPath(doc: string, line: number, span: string, snapshot: Snapshot): Unresolved | undefined {
+  const named = PATH.exec(span)?.[1];
+  if (named === undefined) return undefined;
+  const fromDoc = within(directoryOf(doc), named);
+  const fromRoot = PARENT.test(named) ? undefined : normalize(named);
+  if ([fromRoot, fromDoc].some((path) => path !== undefined && exists(snapshot, path))) return undefined;
+  const checked = fromRoot ?? fromDoc;
+  // A path whose top directory this repository lacks names a file in another one, such as a consumer's.
+  if (checked === undefined || (fromRoot !== undefined && !snapshot.roots.has(fromRoot.split("/")[0] ?? ""))) return undefined;
+  return { kind: "path", line, named, message: `names \`${named}\`, which is not in the repository`, missing: { type: "file", path: checked } };
+}
+
+const SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const ASCII_ESCAPE = /%([0-7][0-9a-f])/gi;
+
+function unresolvedLink(doc: string, line: number, target: string, snapshot: Snapshot): Unresolved | undefined {
+  if (target === "" || SCHEME.test(target)) return undefined;
+  const hash = target.indexOf("#");
+  const written = (hash < 0 ? target : target.slice(0, hash)).split("?", 1)[0] ?? "";
+  const decoded = written.replace(ASCII_ESCAPE, (_, code: string) => String.fromCharCode(Number.parseInt(code, 16)));
+  const path = decoded === "" ? doc : decoded.startsWith("/") ? normalize(decoded) : within(directoryOf(doc), decoded);
+  if (path === undefined) return undefined;
+  const named = target;
+  if (!exists(snapshot, path)) {
+    return { kind: "link", line, named, message: `links to \`${named}\`, which is not in the repository`, missing: { type: "file", path } };
+  }
+  const anchor = hash < 0 ? "" : target.slice(hash + 1);
+  const anchors = snapshot.anchors.get(path);
+  if (anchor === "" || anchors === undefined || anchors.has(anchor) || anchors.has(anchor.toLowerCase())) return undefined;
+  return { kind: "link", line, named, message: `links to \`${named}\`, and \`${path}\` has no heading with that anchor`, missing: { type: "anchor" } };
+}
+
+const RUN = /\bbun run\s+([^\s`'"]+)/g;
+const RUNS_A_FILE = /\/|\.[cm]?[jt]sx?$/;
+const NOT_A_NAME = /^[-$<{]/;
+
+function packageOf(doc: string, snapshot: Snapshot): string | undefined {
+  for (let directory: string | undefined = directoryOf(doc); directory !== undefined; directory = directory === "" ? undefined : directoryOf(directory)) {
+    if (snapshot.files.has(directory === "" ? PACKAGE_MANIFEST : `${directory}/${PACKAGE_MANIFEST}`)) return directory;
+  }
+  return undefined;
+}
+
+function unresolvedCommand(doc: string, line: number, name: string, snapshot: Snapshot): Unresolved | undefined {
+  const packageDirectory = packageOf(doc, snapshot);
+  if (packageDirectory === undefined || NOT_A_NAME.test(name)) return undefined;
+  const named = `bun run ${name}`;
+  if (RUNS_A_FILE.test(name)) {
+    const path = within(packageDirectory, name);
+    if (path === undefined || exists(snapshot, path)) return undefined;
+    return { kind: "command", line, named, message: `runs \`${named}\`, and \`${path}\` is not in the repository`, missing: { type: "file", path } };
+  }
+  if (snapshot.scripts.get(packageDirectory)?.has(name) === true) return undefined;
+  const manifest = packageDirectory === "" ? PACKAGE_MANIFEST : `${packageDirectory}/${PACKAGE_MANIFEST}`;
+  return {
+    kind: "command",
+    line,
+    named,
+    message: `runs \`${named}\`, and \`${name}\` is not a script in \`${manifest}\``,
+    missing: { type: "script", name, packageDirectory },
+  };
+}
+
+function commandsOn({ kind, raw, code }: MarkdownLine): readonly string[] {
+  const texts = kind === "code" ? [raw] : code;
+  return texts.flatMap((text) => [...text.matchAll(RUN)].map(([, name = ""]) => name.replace(/[),.;:]+$/, "")));
+}
+
+export type Judging = { readonly commands: boolean };
+
+export function unresolvedIn(doc: string, text: string, snapshot: Snapshot, { commands }: Judging): readonly Unresolved[] {
+  return scanMarkdown(text).flatMap((markdown) => {
+    const { line } = markdown;
+    const prose = markdown.kind === "code" || markdown.kind === "front-matter" ? [] : markdown.code.map((span) => unresolvedPath(doc, line, span, snapshot));
+    const links = markdown.links.map((target) => unresolvedLink(doc, line, target, snapshot));
+    const runs = commands && markdown.kind !== "front-matter" ? commandsOn(markdown).map((name) => unresolvedCommand(doc, line, name, snapshot)) : [];
+    return [...prose, ...links, ...runs].filter((found) => found !== undefined);
+  });
+}
+
+export function anchoredTargets(doc: string, text: string): readonly string[] {
+  return scanMarkdown(text).flatMap(({ links }) =>
+    links.flatMap((target) => {
+      const hash = target.indexOf("#");
+      if (hash < 0 || SCHEME.test(target)) return [];
+      const written = target.slice(0, hash);
+      const path = written === "" ? doc : written.startsWith("/") ? normalize(written) : within(directoryOf(doc), written);
+      return path?.endsWith(".md") === true ? [path] : [];
+    }),
+  );
+}
+
+export function packagesOf(docs: readonly string[], snapshot: Snapshot): readonly string[] {
+  return [...new Set(docs.flatMap((doc) => packageOf(doc, snapshot) ?? []))];
+}
+
+const EXPLICIT_ANCHOR = /<a\s[^>]*\b(?:id|name)="([^"]+)"/g;
+const HEADING_MARKERS = /^\s{0,3}#{1,6}\s*|\s+#+\s*$/g;
+
+function headingText(raw: string): string {
+  return raw
+    .replace(HEADING_MARKERS, "")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/[`*]/g, "")
+    .trim();
+}
+
+export function anchorsOf(text: string): ReadonlySet<string> {
+  const anchors = new Set<string>();
+  const seen = new Map<string, number>();
+  for (const { kind, raw } of scanMarkdown(text)) {
+    if (kind === "code" || kind === "front-matter") continue;
+    for (const [, id = ""] of raw.matchAll(EXPLICIT_ANCHOR)) anchors.add(id);
+    if (kind !== "heading") continue;
+    const slug = headingText(raw)
+      .toLowerCase()
+      .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
+      .replaceAll(" ", "-");
+    const count = seen.get(slug) ?? 0;
+    anchors.add(count === 0 ? slug : `${slug}-${count}`);
+    seen.set(slug, count + 1);
+  }
+  return anchors;
+}

package/scripts/doc-rules.ts

@@ -11,6 +11,7 @@ import {
   VERSION,
 } from "./doc-outline.ts";
 import { ADR_STATUSES, TEMPLATES, templateFile, type Kind, type Title } from "./doc-templates.ts";
+import { ADR_DIRECTORY, DOCS_DIRECTORY } from "./prose-matchers.ts";
 import { MODES, type Docs, type Mode } from "./quality-file.ts";
 
 export type Placement =
@@ -24,10 +25,9 @@ export type Doc = {
   readonly text: string;
 };
 
-export const ADR_DIRECTORY = "docs/adr/";
+export { ADR_DIRECTORY };
 // A generated index takes its shape from its generator.
 export const ADR_INDEX = `${ADR_DIRECTORY}README.md`;
-const DOCS_DIRECTORY = "docs/";
 
 export const ROOT_FILES: ReadonlyMap<string, Kind> = new Map<string, Kind>([
   ["README.md", "readme"],

package/scripts/doc-snapshot.ts

@@ -0,0 +1,70 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { anchoredTargets, anchorsOf, PACKAGE_MANIFEST, packagesOf, snapshotOf, type Unresolved } from "./doc-references.ts";
+import { git, pathsAt } from "./git.ts";
+
+export class ManifestUnreadable extends Schema.TaggedError<ManifestUnreadable>()("ManifestUnreadable", {
+  message: Schema.String,
+}) {}
+
+const Scripts = Schema.fromJsonString(Schema.Struct({ scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)) }));
+const decodeScripts = Schema.decodeUnknownEffect(Scripts);
+
+export const readTexts = Effect.fn("readTexts")(function* (root: string, rev: string, paths: readonly string[]) {
+  const texts = yield* Effect.forEach(paths, (path) => git(["show", `${rev}:${path}`], root), { concurrency: 8 });
+  return new Map(paths.map((path, index) => [path, texts[index] ?? ""]));
+});
+
+function manifestIn(directory: string): string {
+  return directory === "" ? PACKAGE_MANIFEST : `${directory}/${PACKAGE_MANIFEST}`;
+}
+
+const scriptsAt = Effect.fn("scriptsAt")(function* (root: string, rev: string, directory: string) {
+  const manifest = manifestIn(directory);
+  const { scripts = {} } = yield* git(["show", `${rev}:${manifest}`], root).pipe(
+    Effect.flatMap(decodeScripts),
+    Effect.mapError((cause) => new ManifestUnreadable({ message: `${manifest} at ${rev}: ${cause.message}` })),
+  );
+  return new Set(Object.keys(scripts));
+});
+
+export const snapshotAt = Effect.fn("snapshotAt")(function* (
+  root: string,
+  rev: string,
+  docs: ReadonlyMap<string, string>,
+  alsoRoots: readonly string[],
+) {
+  const files = yield* pathsAt(rev, [], root);
+  const tracked = snapshotOf(files, new Map(), new Map());
+  const targets = [...new Set([...docs].flatMap(([doc, text]) => anchoredTargets(doc, text)))].filter((path) => tracked.files.has(path));
+  const read = yield* readTexts(root, rev, targets.filter((path) => !docs.has(path)));
+  const anchors = new Map(targets.map((path) => [path, anchorsOf(docs.get(path) ?? read.get(path) ?? "")]));
+  const packages = packagesOf([...docs.keys()], tracked);
+  const scripts = yield* Effect.forEach(packages, (directory) => scriptsAt(root, rev, directory), { concurrency: 8 });
+  return snapshotOf(files, anchors, new Map(packages.map((directory, index) => [directory, scripts[index] ?? new Set<string>()])), alsoRoots);
+});
+
+const ignored = (root: string, path: string) =>
+  git(["check-ignore", "-q", "--no-index", "--", path], root).pipe(
+    Effect.as(true),
+    Effect.catchTag("GitFailure", () => Effect.succeed(false)),
+  );
+
+// A script bun runs from an installed dependency's bin names no entry in package.json.
+const installedBin = Effect.fn("installedBin")(function* (root: string, directory: string, name: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const bins = [...new Set([directory, ""])].map((from) => path.join(root, from, "node_modules", ".bin", name));
+  const found = yield* Effect.forEach(bins, (bin) => fs.exists(bin).pipe(Effect.orElseSucceed(() => false)));
+  return found.some(Boolean);
+});
+
+// A path git ignores is generated or fetched, so a clean checkout lacks it by design.
+const stillBroken = Effect.fn("stillBroken")(function* (root: string, { missing }: Unresolved) {
+  if (missing.type === "file") return !(yield* ignored(root, missing.path));
+  if (missing.type === "script") return !(yield* installedBin(root, missing.packageDirectory, missing.name));
+  return true;
+});
+
+export const stillMissing = Effect.fn("stillMissing")(function* (root: string, unresolved: readonly Unresolved[]) {
+  return yield* Effect.forEach(unresolved, (one) => stillBroken(root, one), { concurrency: 8 });
+});

package/scripts/docs.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
+import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, type Placement } from "./doc-rules.ts";
-import { changedPaths, git, pathsAt, rangeEnds } from "./git.ts";
+import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
+import { changedLines, changedPaths, git, pathsAt, rangeEnds } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
+import { isLivingDoc, proseFindings, readerOf } from "./prose-matchers.ts";
 import { readQuality } from "./quality-file.ts";
 
 type Finding = {
@@ -13,46 +16,111 @@ type Finding = {
 
 type Judged = {
   readonly held: readonly string[];
+  readonly edited: { readonly docs: number; readonly lines: number };
+  readonly living: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
+  readonly brokenBefore: readonly Finding[];
 };
 
+type Range = {
+  readonly root: string;
+  readonly base: string;
+  readonly head: string;
+  readonly roots: readonly string[];
+  readonly changed: ReadonlyMap<string, ReadonlySet<number>>;
+  readonly renamedFrom: ReadonlyMap<string, string>;
+};
+
+type Located = Unresolved & { readonly path: string };
+
 const NAME = "docs";
 const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
 const MARKDOWN = [":(glob)**/*.md"];
 
-const judgeFile = Effect.fn("judgeFile")(function* (
-  root: string,
-  head: string,
-  path: string,
-  placement: Placement,
-  records: readonly string[],
-) {
+function templateFindings(path: string, text: string, placement: Placement, records: readonly string[]): readonly Finding[] {
   const misplaced = placementProblem(placement);
   if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
   if (placement.type !== "judged") return [];
-  const text = yield* git(["show", `${head}:${path}`], root);
   return judge(placement.kind, { path, text }, records).map(({ line, message }) => ({ path, line, message }));
+}
+
+function inPathOrder(a: Finding, b: Finding): number {
+  return a.path === b.path ? (a.line ?? 0) - (b.line ?? 0) : a.path < b.path ? -1 : 1;
+}
+
+function locate(path: string, text: string, snapshot: Parameters<typeof unresolvedIn>[2], judging: Judging): readonly Located[] {
+  return unresolvedIn(path, text, snapshot, judging).map((unresolved) => ({ ...unresolved, path }));
+}
+
+const keyOf = ({ path, kind, named }: Located): string => `${path}\0${kind}\0${named}`;
+
+// A reference on a line the range leaves alone fails only when the range broke it, as by deleting the file it names.
+const brokenBeforeRange = Effect.fn("brokenBeforeRange")(function* (range: Range, found: readonly Located[], judging: (path: string) => Judging) {
+  const earlier = new Set(yield* pathsAt(range.base, MARKDOWN, range.root));
+  const docs = [...new Set(found.map(({ path }) => path))]
+    .map((path) => ({ path, from: range.renamedFrom.get(path) ?? path }))
+    .filter(({ from }) => earlier.has(from));
+  const texts = yield* readTexts(range.root, range.base, docs.map(({ from }) => from));
+  const snapshot = yield* snapshotAt(range.root, range.base, texts, range.roots);
+  return new Set(docs.flatMap(({ path, from }) => locate(from, texts.get(from) ?? "", snapshot, judging(path)).map((one) => keyOf({ ...one, path }))));
+});
+
+const referenceFindings = Effect.fn("referenceFindings")(function* (range: Range, texts: ReadonlyMap<string, string>, judging: (path: string) => Judging) {
+  const snapshot = yield* snapshotAt(range.root, range.head, texts, range.roots);
+  const unresolved = [...texts].flatMap(([path, text]) => locate(path, text, snapshot, judging(path)));
+  const missing = yield* stillMissing(range.root, unresolved);
+  const found = unresolved.filter((_, index) => missing[index] === true);
+  const onChangedLines = (one: Located): boolean => range.changed.get(one.path)?.has(one.line) === true;
+  const elsewhere = found.filter((one) => !onChangedLines(one));
+  const before = elsewhere.length === 0 ? new Set<string>() : yield* brokenBeforeRange(range, elsewhere, judging);
+  const finding = ({ path, line, message }: Located): Finding => ({ path, line, message });
+  return {
+    failing: found.filter((one) => onChangedLines(one) || !before.has(keyOf(one))).map(finding),
+    brokenBefore: elsewhere.filter((one) => before.has(keyOf(one))).map(finding),
+  };
 });
 
 const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head: string) {
   const { quality } = yield* readQuality(root);
-  const touched = new Set(
-    (yield* changedPaths(base, head, MARKDOWN, root)).flatMap((change) => (change.kind === "deleted" ? [] : [change.path])),
-  );
+  const changes = yield* changedPaths(base, head, MARKDOWN, root);
+  const touched = new Set(changes.flatMap((change) => (change.kind === "deleted" ? [] : [change.path])));
+  const renamedFrom = new Map(changes.flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from] as const] : [])));
+  const changed = yield* changedLines(base, head, MARKDOWN, root);
   const present = yield* pathsAt(head, MARKDOWN, root);
   const records = present.filter((path) => path.startsWith(ADR_DIRECTORY));
-  const placed = present.map((path) => ({ path, placement: placementOf(path, quality.docs) }));
-  const judged = placed.filter(({ placement }) => placement.type !== "unjudged");
-  const findings = (yield* Effect.forEach(judged, ({ path, placement }) => judgeFile(root, head, path, placement, records), {
-    concurrency: 8,
-  })).flat();
+  const judged = present.map((path) => ({ path, placement: placementOf(path, quality.docs) })).filter(({ placement }) => placement.type !== "unjudged");
+  const living = present.filter(isLivingDoc);
+  const proseDocs = present.flatMap((path) => {
+    const reader = readerOf(path);
+    return reader === undefined ? [] : [{ path, reader }];
+  });
+  const texts = yield* readTexts(root, head, [...new Set([...judged.map(({ path }) => path), ...proseDocs.map(({ path }) => path)])]);
+  const text = (path: string): string => texts.get(path) ?? "";
+
+  const templated = judged.flatMap(({ path, placement }) => templateFindings(path, text(path), placement, records));
+  const edited = proseDocs.filter(({ path }) => changed.has(path));
+  const prose = edited.flatMap(({ path, reader }) =>
+    proseFindings(text(path), reader, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
+  );
+  const forConsumers = (quality.docs?.forConsumers ?? []).map((glob) => new Bun.Glob(glob));
+  const judging = (path: string): Judging => ({ commands: !forConsumers.some((glob) => glob.match(path)) });
+  // A directory the range deletes still belongs to this repository, so a path under it is stale rather than another repository's.
+  const roots = rootsOf(yield* pathsAt(base, [], root));
+  const references = yield* referenceFindings(
+    { root, base, head, roots, changed, renamedFrom },
+    new Map(living.map((path) => [path, text(path)])),
+    judging,
+  );
   const advisory = new Map<string, number>();
-  for (const { path } of findings.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
+  for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
     held: judged.map(({ path }) => path).filter((path) => touched.has(path)),
-    findings: findings.filter((finding) => touched.has(finding.path)),
+    edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
+    living: living.length,
+    findings: [...templated.filter((finding) => touched.has(finding.path)), ...prose, ...references.failing].toSorted(inPathOrder),
     advisory,
+    brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
 });
 
@@ -60,19 +128,27 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, findings, advisory }: Judged): string {
+export function report({ held, edited, living, findings, advisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
-      ? [`${NAME}: ${held.length} doc file(s) the range touches hold to their templates`]
-      : [`${NAME}: ${findings.length} violation(s) in the doc files the range touches:`, ...findings.map(describe)];
-  const notice =
+      ? [
+          `${NAME}: ${held.length} doc file(s) the range touches hold to their templates`,
+          `${NAME}: ${edited.lines} line(s) the range adds or edits in ${edited.docs} living doc(s) or agent file(s) hold to the prose rules`,
+          `${NAME}: the range breaks no path, link or command the ${living} living doc(s) name`,
+        ]
+      : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
+  const unconformed =
     advisory.size === 0
       ? []
       : [
           `${NAME}: advisory, ${advisory.size} doc file(s) the range leaves alone do not hold to their templates yet:`,
           ...[...advisory].map(([path, count]) => `  ${path}: ${count} violation(s)`),
         ];
-  return [...verdict, ...notice].join("\n");
+  const broken =
+    brokenBefore.length === 0
+      ? []
+      : [`${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs name were broken before the range:`, ...brokenBefore.map(describe)];
+  return [...verdict, ...unconformed, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {

package/scripts/git.ts

@@ -71,6 +71,70 @@ export const changedPaths = Effect.fn("changedPaths")(function* (
   return parseNameStatus(yield* git(["diff", "--name-status", "-z", "-M", base, head, "--", ...pathspecs], cwd));
 });
 
+const ESCAPES: Readonly<Record<string, string>> = { a: "\x07", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v" };
+
+// Git quotes a path holding a quote, a backslash or a control character, and ends one holding a space with a tab.
+function newPathOf(line: string): string | undefined {
+  const named = line.slice("+++ ".length).replace(/\t$/, "");
+  const path = named.startsWith('"')
+    ? named.slice(1, -1).replace(/\\(?:([0-7]{3})|(.))/g, (_, octal: string | undefined, char: string) =>
+        octal === undefined ? (ESCAPES[char] ?? char) : String.fromCharCode(Number.parseInt(octal, 8)),
+      )
+    : named;
+  return path === "/dev/null" ? undefined : path;
+}
+
+const HUNK = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+
+// A hunk's header counts its lines, so an added line reading `++ x` is not taken for the next file's `+++` header.
+export function parseAddedLines(diff: string): Map<string, Set<number>> {
+  const added = new Map<string, Set<number>>();
+  let path: string | undefined;
+  let line = 0;
+  let oldLeft = 0;
+  let newLeft = 0;
+  for (const row of diff.split("\n")) {
+    if (oldLeft > 0 || newLeft > 0) {
+      if (row.startsWith("+")) {
+        if (path !== undefined) added.set(path, (added.get(path) ?? new Set<number>()).add(line));
+        line += 1;
+        newLeft -= 1;
+      } else if (row.startsWith("-")) {
+        oldLeft -= 1;
+      } else if (row.startsWith(" ")) {
+        line += 1;
+        oldLeft -= 1;
+        newLeft -= 1;
+      }
+      continue;
+    }
+    if (row.startsWith("+++ ")) {
+      path = newPathOf(row);
+      continue;
+    }
+    const hunk = HUNK.exec(row);
+    if (hunk !== null) {
+      oldLeft = Number(hunk[1] ?? 1);
+      line = Number(hunk[2]);
+      newLeft = Number(hunk[3] ?? 1);
+    }
+  }
+  return added;
+}
+
+export const changedLines = Effect.fn("changedLines")(function* (
+  base: string,
+  head: string,
+  pathspecs: readonly string[],
+  cwd?: string,
+) {
+  const diff = yield* git(
+    ["-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--no-prefix", "-M", base, head, "--", ...pathspecs],
+    cwd,
+  );
+  return parseAddedLines(diff);
+});
+
 const emptyTree = (cwd?: string) => git(["hash-object", "-t", "tree", "/dev/null"], cwd).pipe(Effect.map((sha) => sha.trim()));
 
 export const pathsAt = Effect.fn("pathsAt")(function* (rev: string, pathspecs: readonly string[], cwd?: string) {

package/scripts/prose-matchers.ts

@@ -0,0 +1,380 @@
+export type ProseFinding = { readonly line: number; readonly message: string };
+
+export type LineKind = "prose" | "heading" | "table" | "html" | "definition" | "break" | "blank" | "code" | "front-matter";
+
+export type MarkdownLine = {
+  readonly line: number;
+  readonly kind: LineKind;
+  readonly raw: string;
+  readonly prose: string;
+  readonly code: readonly string[];
+  readonly links: readonly string[];
+};
+
+export type Reader = "people" | "agents";
+
+export type ProseRule = {
+  readonly readers: readonly Reader[];
+  readonly refuses: string;
+  readonly example: string;
+  readonly instead: string;
+};
+
+type MatchedRule = ProseRule & { readonly find: RegExp };
+
+export const ADR_DIRECTORY = "docs/adr/";
+export const DOCS_DIRECTORY = "docs/";
+export const LIVING_NAMES: readonly string[] = ["README.md", "CONTRIBUTING.md"];
+export const AGENT_NAMES: readonly string[] = ["AGENTS.md", "CLAUDE.md"];
+export const HISTORY_NAMES: readonly string[] = ["CHANGELOG.md"];
+export const DATED_RECORD_EXAMPLES: readonly string[] = ["0001-", "2026-05-08-"];
+const DATED_RECORD = /^\d{4}-/;
+
+export function isLivingDoc(repositoryPath: string): boolean {
+  const name = repositoryPath.slice(repositoryPath.lastIndexOf("/") + 1);
+  if (HISTORY_NAMES.includes(name) || AGENT_NAMES.includes(name) || DATED_RECORD.test(name) || repositoryPath.startsWith(ADR_DIRECTORY)) return false;
+  return LIVING_NAMES.includes(name) || (repositoryPath.startsWith(DOCS_DIRECTORY) && name.endsWith(".md"));
+}
+
+export function readerOf(repositoryPath: string): Reader | undefined {
+  if (isLivingDoc(repositoryPath)) return "people";
+  return AGENT_NAMES.includes(repositoryPath.slice(repositoryPath.lastIndexOf("/") + 1)) ? "agents" : undefined;
+}
+
+// Masking keeps each line's length, so a column in the masked prose is the same column in the raw line.
+const HIDDEN = "\0";
+const BLANK = " ";
+
+type Masked = { readonly prose: string; readonly code: string[]; readonly links: string[]; readonly inComment: boolean };
+
+const AUTOLINK = /^<(?:[A-Za-z][A-Za-z0-9+.-]{1,31}:[^\s<>]*|[^\s@<>]+@[^\s<>]+)>/;
+const HTML_TAG = /^<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?\/?>/;
+const BARE_URL = /^https?:\/\/[^\s<>]*[^\s<>.,:;!?'")\]]/;
+const ENTITY = /^&(?:#\d+|#x[0-9a-f]+|[a-z][a-z0-9]*);/i;
+const WORD = /\w/;
+
+function hiddenAt(raw: string, at: number, rest: string): { readonly length: number; readonly fill: string } | undefined {
+  const char = raw.charAt(at);
+  const url = char === "h" && !WORD.test(raw.charAt(at - 1)) ? BARE_URL.exec(rest) : null;
+  const visible = url ?? (char === "&" ? ENTITY.exec(rest) : null) ?? (char === "<" ? AUTOLINK.exec(rest) : null);
+  if (visible !== null) return { length: visible[0].length, fill: HIDDEN };
+  const tag = char === "<" ? HTML_TAG.exec(rest) : null;
+  return tag === null ? undefined : { length: tag[0].length, fill: BLANK };
+}
+
+function runOf(raw: string, at: number, char: string): number {
+  let end = at;
+  while (raw[end] === char) end += 1;
+  return end - at;
+}
+
+function closingRun(raw: string, from: number, length: number): number {
+  for (let at = raw.indexOf("`", from); at >= 0; at = raw.indexOf("`", at + 1)) {
+    const run = runOf(raw, at, "`");
+    if (run === length) return at;
+    at += run - 1;
+  }
+  return -1;
+}
+
+function destinationEnd(raw: string, open: number): number {
+  let depth = 0;
+  for (let at = open + 1; at < raw.length; at += 1) {
+    const char = raw[at];
+    if (char === "\\") at += 1;
+    else if (char === "(") depth += 1;
+    else if (char === ")") {
+      if (depth === 0) return at;
+      depth -= 1;
+    }
+  }
+  return -1;
+}
+
+function targetOf(destination: string): string {
+  const trimmed = destination.trim();
+  if (trimmed.startsWith("<")) return trimmed.slice(1, Math.max(trimmed.indexOf(">"), 1));
+  return trimmed.split(/\s/, 1)[0] ?? "";
+}
+
+function mask(raw: string, startsInComment: boolean): Masked {
+  const out = raw.split("");
+  const code: string[] = [];
+  const links: string[] = [];
+  const hide = (from: number, to: number, fill: string): void => {
+    for (let at = from; at < to; at += 1) out[at] = fill;
+  };
+  let inComment = startsInComment;
+  let at = 0;
+  while (at < raw.length) {
+    if (inComment) {
+      const close = raw.indexOf("-->", at);
+      const end = close < 0 ? raw.length : close + 3;
+      hide(at, end, BLANK);
+      inComment = close < 0;
+      at = end;
+      continue;
+    }
+    const rest = raw.slice(at);
+    if (rest.startsWith("<!--")) {
+      hide(at, at + 4, BLANK);
+      inComment = true;
+      at += 4;
+      continue;
+    }
+    if (rest.startsWith("`")) {
+      const run = runOf(raw, at, "`");
+      const close = closingRun(raw, at + run, run);
+      if (close >= 0) {
+        code.push(raw.slice(at + run, close).trim());
+        hide(at, close + run, HIDDEN);
+        at = close + run;
+      } else at += run;
+      continue;
+    }
+    if (rest.startsWith("](")) {
+      const end = destinationEnd(raw, at + 1);
+      if (end >= 0) {
+        links.push(targetOf(raw.slice(at + 2, end)));
+        hide(at + 1, end + 1, HIDDEN);
+        at = end + 1;
+        continue;
+      }
+    }
+    const hidden = hiddenAt(raw, at, rest);
+    if (hidden !== undefined) {
+      hide(at, at + hidden.length, hidden.fill);
+      at += hidden.length;
+      continue;
+    }
+    at += 1;
+  }
+  return { prose: out.join(""), code, links, inComment };
+}
+
+const FENCE = /^\s*(`{3,}|~{3,})(.*)$/;
+const DEFINITION = /^\s{0,3}\[[^\]]+\]:\s*(\S+)/;
+const HEADING = /^\s{0,3}#{1,6}(?:\s|$)/;
+const BREAK = /^\s{0,3}(?:[-*_](?:\s*[-*_]){2,}|=+|-+)\s*$/;
+const UNDERLINE = /^\s{0,3}(?:=+|-+)\s*$/;
+const HTML_BLOCK = /^\s{0,3}<[A-Za-z/!?]/;
+
+function fenceOpener(raw: string): string | undefined {
+  const match = FENCE.exec(raw);
+  if (match === null) return undefined;
+  const [, fence = "", info = ""] = match;
+  return fence.startsWith("`") && info.includes("`") ? undefined : fence;
+}
+
+function fenceCloses(raw: string, opener: string): boolean {
+  const closer = FENCE.exec(raw);
+  return closer !== null && closer[1]?.[0] === opener[0] && (closer[1]?.length ?? 0) >= opener.length && closer[2]?.trim() === "";
+}
+
+function kindOf(raw: string, prose: string): LineKind {
+  if (raw.trim() === "") return "blank";
+  if (HEADING.test(raw)) return "heading";
+  if (BREAK.test(raw)) return "break";
+  if (raw.trimStart().startsWith("|")) return "table";
+  if (HTML_BLOCK.test(raw) && !AUTOLINK.test(raw.trimStart())) return "html";
+  return prose.trim() === "" ? "blank" : "prose";
+}
+
+function unread(line: number, raw: string, kind: LineKind): MarkdownLine {
+  return { line, kind, raw, prose: BLANK.repeat(raw.length), code: [], links: [] };
+}
+
+function settext(lines: MarkdownLine[]): MarkdownLine[] {
+  return lines.map((line, index) => {
+    const next = lines[index + 1];
+    return line.kind === "prose" && next?.kind === "break" && UNDERLINE.test(next.raw) ? { ...line, kind: "heading" } : line;
+  });
+}
+
+export function scanMarkdown(text: string): readonly MarkdownLine[] {
+  const raws = text.split("\n").map((raw) => raw.replace(/\r$/, ""));
+  const lines: MarkdownLine[] = [];
+  let fence: string | undefined;
+  let inComment = false;
+  let inHtmlBlock = false;
+  let frontMatter = raws[0] === "---";
+  for (const [index, raw] of raws.entries()) {
+    const line = index + 1;
+    if (frontMatter) {
+      frontMatter = index === 0 || (raw !== "---" && raw !== "...");
+      lines.push(unread(line, raw, "front-matter"));
+      continue;
+    }
+    if (fence !== undefined) {
+      if (fenceCloses(raw, fence)) fence = undefined;
+      lines.push(unread(line, raw, "code"));
+      continue;
+    }
+    const opener = inComment ? undefined : fenceOpener(raw);
+    if (opener !== undefined) {
+      fence = opener;
+      lines.push(unread(line, raw, "code"));
+      continue;
+    }
+    const definition = inComment ? null : DEFINITION.exec(raw);
+    if (definition !== null) {
+      lines.push({ ...unread(line, raw, "definition"), links: [targetOf(definition[1] ?? "")] });
+      continue;
+    }
+    const masked = mask(raw, inComment);
+    inComment = masked.inComment;
+    const kind = kindOf(raw, masked.prose);
+    // An HTML block runs to the next blank line, whatever its later lines open with.
+    inHtmlBlock = kind === "html" || (inHtmlBlock && kind !== "blank");
+    lines.push({ line, kind: inHtmlBlock ? "html" : kind, raw, prose: masked.prose, code: masked.code, links: masked.links });
+  }
+  return settext(lines);
+}
+
+const LEADING_MARKERS = /^(?:\s*>)*\s*(?:#{1,6}\s+|(?:[-*+]|\d{1,9}[.)])\s+(?:\[[ xX]\]\s+)?)?/;
+
+function bodyOf({ prose }: MarkdownLine): string {
+  const markers = LEADING_MARKERS.exec(prose)?.[0] ?? "";
+  return BLANK.repeat(markers.length) + prose.slice(markers.length);
+}
+
+const SEPARATOR_INSTEAD = "End the sentence, or use a comma";
+
+const PROMISES: readonly (readonly [shows: string, pattern: string])[] = [
+  ["until #11", String.raw`until \[?(?:[\w.-]+\/[\w.-]+)?#\d+`],
+  ["is planned", "(?:is|are) planned"],
+  ["will soon", "will soon"],
+  ["coming soon", "coming soon"],
+  ["in a future release", "in a future (?:release|version)"],
+];
+
+const code = (text: string): string => `\`${text}\``;
+const EVERY_READER: readonly Reader[] = ["people", "agents"];
+const PEOPLE: readonly Reader[] = ["people"];
+
+const RULES: readonly MatchedRule[] = [
+  { readers: EVERY_READER, refuses: "an em dash", example: code("—"), instead: SEPARATOR_INSTEAD, find: /—/g },
+  { readers: EVERY_READER, refuses: "an en dash", example: code("–"), instead: SEPARATOR_INSTEAD, find: /–/g },
+  {
+    readers: EVERY_READER,
+    refuses: "a parenthesis other than the plural `(s)`",
+    example: code("("),
+    instead: "Make the aside its own sentence, or set it off with commas",
+    find: /\((?!s\))/g,
+  },
+  {
+    readers: EVERY_READER,
+    refuses: "a hyphen used as a dash",
+    example: `${code("a - b")} or ${code("a -- b")}`,
+    instead: SEPARATOR_INSTEAD,
+    find: /(?<=[^\s|]) -{1,3} (?=[^\s|])/g,
+  },
+  { readers: EVERY_READER, refuses: "a semicolon", example: code(";"), instead: "Use two sentences", find: /;/g },
+  {
+    readers: PEOPLE,
+    refuses: "a promise about the future",
+    example: PROMISES.map(([shows]) => code(shows)).join(", "),
+    instead: "Say what is true now",
+    find: new RegExp(PROMISES.map(([, pattern]) => String.raw`\b${pattern}\b`).join("|"), "gi"),
+  },
+  {
+    readers: PEOPLE,
+    refuses: "a sentence that opens by talking about the page",
+    example: code("This page explains"),
+    instead: "Talk directly about the subject",
+    find: /(?<=^\s*|[.!?:]\s+)(?:this|the following|in this) (?:page|topic|section|document|doc|guide|tutorial|article|readme|file|chapter)\b(?: \w+)?/gi,
+  },
+];
+
+const SECOND_SENTENCE: ProseRule = {
+  readers: PEOPLE,
+  refuses: "a second sentence on one line",
+  example: code("It builds. It ships."),
+  instead: "Start it on its own line",
+};
+
+const RUN_ON: ProseRule = {
+  readers: PEOPLE,
+  refuses: "a sentence that runs across lines",
+  example: `${code("It builds")} with ${code("and ships.")} on the next line`,
+  instead: "Join the sentence onto one line",
+};
+
+export const PROSE_RULES: readonly ProseRule[] = [
+  ...RULES.map(({ readers, refuses, example, instead }) => ({ readers, refuses, example, instead })),
+  SECOND_SENTENCE,
+  RUN_ON,
+];
+
+const JUDGED_KINDS: ReadonlySet<LineKind> = new Set(["prose", "heading", "table", "html"]);
+
+function ruleFindings(line: MarkdownLine, reader: Reader): ProseFinding[] {
+  const body = bodyOf(line);
+  return RULES.filter(({ readers }) => readers.includes(reader)).flatMap(({ refuses, instead, find }) =>
+    [...body.matchAll(find)].map(([match]) => ({ line: line.line, message: `carries \`${match.trim()}\`, ${refuses}. ${instead}` })),
+  );
+}
+
+const SENTENCE_BREAK = /(?<=[^\s.!?])[.!?]["'”’)\]*_]*\s+(?=[A-Z"“*_[\0])/g;
+const ABBREVIATION = /\b(?:e\.g|i\.e|etc|vs|cf|approx|Mr|Mrs|Ms|Dr|St|No|Fig)$/i;
+const SENTENCE_END = /[.!?:]["'”’)\]*_]*\s*$/;
+const LIST_ITEM = /^(?:\s*>)*\s*(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
+const QUOTE_DEPTH = /^(?:\s*>)*/;
+
+// A bold label that opens a line, as in **Status.**, heads the sentence after it rather than being one.
+const RUN_IN_LABEL = /^\s*(\*\*|__)(?:(?!\1).)+?[.!?:]\1\s/;
+
+function secondSentence(line: MarkdownLine): ProseFinding | undefined {
+  const body = bodyOf(line);
+  const label = RUN_IN_LABEL.exec(body)?.[0].length ?? 0;
+  for (const match of body.matchAll(SENTENCE_BREAK)) {
+    if (match.index < label || ABBREVIATION.test(body.slice(0, match.index))) continue;
+    const opening = line.raw.slice(match.index + match[0].length).split(/\s+/, 3).join(" ").replace(/[.!?,:]+$/, "");
+    return { line: line.line, message: `carries ${SECOND_SENTENCE.refuses}, which opens with \`${opening}\`. ${SECOND_SENTENCE.instead}` };
+  }
+  return undefined;
+}
+
+const OPENS_LOWERCASE = /^\s*[a-z]/;
+
+// A sentence may end inside the code or link that closes its line, so only a lowercase next line proves it runs on.
+function endsMidSentence(line: MarkdownLine, next: MarkdownLine): boolean {
+  const body = bodyOf(line).trimEnd();
+  if (SENTENCE_END.test(body) || line.raw.endsWith("  ") || line.raw.endsWith("\\")) return false;
+  return !body.endsWith(HIDDEN) || OPENS_LOWERCASE.test(bodyOf(next));
+}
+
+function continues(earlier: MarkdownLine | undefined, later: MarkdownLine | undefined): boolean {
+  if (earlier?.kind !== "prose" || later?.kind !== "prose" || LIST_ITEM.test(later.raw)) return false;
+  return QUOTE_DEPTH.exec(earlier.raw)?.[0].split(">").length === QUOTE_DEPTH.exec(later.raw)?.[0].split(">").length;
+}
+
+function spansLines(lines: readonly MarkdownLine[], index: number): ProseFinding | undefined {
+  const line = lines[index];
+  if (line === undefined) return undefined;
+  const next = lines[index + 1];
+  const previous = lines[index - 1];
+  const forward = next !== undefined && continues(line, next) && endsMidSentence(line, next);
+  const back = previous !== undefined && continues(previous, line) && endsMidSentence(previous, line);
+  if (!forward && !back) return undefined;
+  return { line: line.line, message: `carries ${RUN_ON.refuses}. ${RUN_ON.instead}` };
+}
+
+export function proseFindings(text: string, reader: Reader, within?: ReadonlySet<number>): readonly ProseFinding[] {
+  const lines = scanMarkdown(text);
+  return lines.flatMap((line, index) => {
+    if ((within !== undefined && !within.has(line.line)) || !JUDGED_KINDS.has(line.kind)) return [];
+    const prose = line.kind === "prose";
+    const sentences = [
+      prose && SECOND_SENTENCE.readers.includes(reader) ? secondSentence(line) : undefined,
+      prose && RUN_ON.readers.includes(reader) ? spansLines(lines, index) : undefined,
+    ];
+    return [...ruleFindings(line, reader), ...sentences.filter((finding) => finding !== undefined)];
+  });
+}
+
+export function proseRefused(repositoryPath: string, text: string, within?: ReadonlySet<number>): string[] {
+  const reader = readerOf(repositoryPath);
+  if (reader === undefined) return [];
+  return proseFindings(text, reader, within).map(({ line, message }) => `${repositoryPath}:${line} ${message}`);
+}

package/scripts/quality-file.ts

@@ -20,6 +20,16 @@ const PathGlob = Schema.String.check(
     "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./",
 });
 
+// Only checks-docs reads a doc glob, matching it from the root, so a file at the root names itself.
+const DocGlob = Schema.String.check(
+  Schema.isPattern(new RegExp(`^(?:${SEGMENT}/)*${FILE}$`), {
+    expected: "a glob from the repository root such as README.md or docs/**/*.md: * within a segment, ** as a whole one, a file name with an extension last",
+  }),
+).annotate({
+  identifier: "DocGlob",
+  description: "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last",
+});
+
 const LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
 
 const DirectoryPath = Schema.String.check(
@@ -166,6 +176,11 @@ const Docs = Schema.Struct({
       description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one",
     }),
   ),
+  forConsumers: Schema.optionalKey(
+    Schema.Array(DocGlob).annotate({
+      description: "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json",
+    }),
+  ),
 });
 export type Docs = typeof Docs.Type;