From 9933125feaa86eb2765c1e638392ff26a5342da4 Mon Sep 17 00:00:00 2001
From: Joris Wouter Jonkers <info@jorisjonkers.dev>
Date: Mon, 14 Sep 2026 08:56:09 +0200
Subject: [PATCH 1/3] test: hold README and CONTRIBUTING to the repository they
 describe

Extract every npm script, backtick path, coverage percentage and Node
version the two documents name, and check each against package.json,
the tree, vitest.config.ts and .nvmrc. The link lint already resolves
Markdown links and anchors; this covers the claims that never sit
inside one.

README's Node and coverage lines were vague enough to dodge drift by
never stating a number. Made them concrete so there is something to
hold, and corrected the coverage sentence to say verify enforces the
ratchet rather than test.
---
 README.md                  |   6 +-
 scripts/lint-docs.ts       | 219 +++++++++++++++++++++++
 test/docs-contract.test.ts | 347 +++++++++++++++++++++++++++++++++++++
 3 files changed, 570 insertions(+), 2 deletions(-)
 create mode 100644 scripts/lint-docs.ts
 create mode 100644 test/docs-contract.test.ts

diff --git a/README.md b/README.md
index ee13883..dae14d7 100644
--- a/README.md
+++ b/README.md
@@ -79,13 +79,15 @@ business. The parked direction work is in
 ## Local checks
 
 ```bash
-nvm use             # the exact Node version in .nvmrc
+nvm use             # Node 24.21.0, pinned in .nvmrc
 npm ci
 npm run verify      # lint, format, typecheck, ADR contract, tests + coverage
 ```
 
 `npm run lint:adrs` alone runs the decision-record contract, and `npm test`
-runs the suite without the coverage thresholds.
+runs the suite without enforcing coverage. `npm run test:coverage` (part of
+`npm run verify`) enforces the ratchet in `vitest.config.ts`: statements
+96.9%, branches 86.52%, functions 100%, lines 96.59%.
 
 ## Conventions
 
diff --git a/scripts/lint-docs.ts b/scripts/lint-docs.ts
new file mode 100644
index 0000000..f6526bf
--- /dev/null
+++ b/scripts/lint-docs.ts
@@ -0,0 +1,219 @@
+// Docs contract: holds README.md and CONTRIBUTING.md to the repository they
+// describe. Prose goes stale silently, and each of the four claims below
+// reads exactly as well wrong as right: a renamed script, a coverage
+// threshold that moved, a pinned Node version that changed, a path that no
+// longer exists.
+//
+// The link lint (lint-links.ts) already proves that a Markdown link and its
+// heading anchor resolve. This gate covers what that one cannot see: names,
+// numbers and versions, most of which are never inside a link at all.
+//
+// A library first: tests call lintDocs() in-process against fixture trees,
+// and `node scripts/lint-docs.ts [root]` is the command.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isEntrypoint } from "./lib/entrypoint.ts";
+import { processOutput, type GateOutput } from "./lib/output.ts";
+
+const REPOSITORY = join(import.meta.dirname, "..");
+
+// The documents this gate holds to the repository. Any other file that
+// quotes a script, a number or a path is somebody else's problem.
+const DOCUMENTS = ["README.md", "CONTRIBUTING.md"] as const;
+
+const COVERAGE_METRICS = [
+  "statements",
+  "branches",
+  "functions",
+  "lines",
+] as const;
+type CoverageMetric = (typeof COVERAGE_METRICS)[number];
+
+export type ClaimKind = "script" | "number" | "version" | "path";
+
+/** How many claims of each kind the documents made, across both files. */
+export type ClaimCounts = Readonly<Record<ClaimKind, number>>;
+
+export interface DocsLintResult {
+  readonly claims: number;
+  readonly byKind: ClaimCounts;
+  readonly errors: readonly string[];
+}
+
+/** Every `npm run <script>` and bare `npm test` a document names, deduplicated. */
+export function scriptClaims(text: string): readonly string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(/npm run ([a-zA-Z0-9:_-]+)/g))
+    found.add(match[1] ?? "");
+  if (/\bnpm test\b/.test(text)) found.add("test");
+  return [...found];
+}
+
+/**
+ * Whether a backtick-quoted span reads as a file or directory reference
+ * worth checking, rather than a command, a YAML field, or a bare word like a
+ * package name. It must be a single token of path characters, and it must
+ * carry a `/` or a `.`: `deploy-config-schema` is a repository name, not a
+ * path, and this is what tells the two apart without a hand-kept list.
+ */
+export function isPathLike(candidate: string): boolean {
+  if (!/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*\/?$/.test(candidate))
+    return false;
+  return candidate.includes("/") || candidate.includes(".");
+}
+
+/**
+ * Every backtick-quoted path a document names, deduplicated. A fenced code
+ * block is stripped first: its triple backticks are not a pair, and reading
+ * them as one would pair each one with a wrong partner for the rest of the
+ * file, the same hazard lint-links.ts strips prose for before it reads links.
+ */
+export function pathClaims(text: string): readonly string[] {
+  const prose = text.replace(/^```[\s\S]*?^```/gm, "");
+  const found = new Set<string>();
+  for (const match of prose.matchAll(/`([^`]+)`/g)) {
+    const candidate = match[1] ?? "";
+    if (isPathLike(candidate)) found.add(candidate);
+  }
+  return [...found];
+}
+
+/** Every coverage percentage a document quotes, one entry per metric named. */
+export function coverageClaims(
+  text: string,
+): readonly { readonly metric: CoverageMetric; readonly value: number }[] {
+  const claims: { metric: CoverageMetric; value: number }[] = [];
+  for (const metric of COVERAGE_METRICS) {
+    const match = new RegExp(`\\b${metric}\\s+([\\d.]+)%`, "i").exec(text);
+    const value = match?.[1];
+    if (value !== undefined) claims.push({ metric, value: Number(value) });
+  }
+  return claims;
+}
+
+/** Every `Node <semver>` a document names, deduplicated. */
+export function nodeVersionClaims(text: string): readonly string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(/\bNode\s+v?(\d+\.\d+\.\d+)\b/g))
+    found.add(match[1] ?? "");
+  return [...found];
+}
+
+function packageScripts(root: string): Readonly<Record<string, string>> {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+    scripts?: Record<string, string>;
+  };
+  return pkg.scripts ?? {};
+}
+
+/** The coverage ratchet in `vitest.config.ts`, parsed from its source text. */
+function coverageThresholds(
+  root: string,
+): Readonly<Partial<Record<CoverageMetric, number>>> {
+  const text = readFileSync(join(root, "vitest.config.ts"), "utf8");
+  const block = /thresholds:\s*{([^}]*)}/s.exec(text)?.[1] ?? "";
+  const thresholds: Partial<Record<CoverageMetric, number>> = {};
+  for (const metric of COVERAGE_METRICS) {
+    const value = new RegExp(`\\b${metric}:\\s*([\\d.]+)`).exec(block)?.[1];
+    if (value !== undefined) thresholds[metric] = Number(value);
+  }
+  return thresholds;
+}
+
+function nvmrcVersion(root: string): string {
+  return readFileSync(join(root, ".nvmrc"), "utf8").trim();
+}
+
+/**
+ * Check every claim README.md and CONTRIBUTING.md make about `root`'s own
+ * repository: every script exists, every path exists, every quoted coverage
+ * number matches the ratchet, every quoted Node version matches `.nvmrc`.
+ */
+export function lintDocs(root: string): DocsLintResult {
+  const errors: string[] = [];
+  const byKind: Record<ClaimKind, number> = {
+    script: 0,
+    number: 0,
+    version: 0,
+    path: 0,
+  };
+
+  const scripts = packageScripts(root);
+  const thresholds = coverageThresholds(root);
+  const nvmrc = nvmrcVersion(root);
+
+  for (const document of DOCUMENTS) {
+    let text: string;
+    try {
+      text = readFileSync(join(root, document), "utf8");
+    } catch {
+      // Neither document is required to exist for this gate to run; a
+      // repository missing one of them fails elsewhere.
+      continue;
+    }
+
+    for (const script of scriptClaims(text)) {
+      byKind.script += 1;
+      if (!(script in scripts))
+        errors.push(
+          `${document}: names \`npm run ${script}\`, which is not a script in package.json`,
+        );
+    }
+
+    for (const path of pathClaims(text)) {
+      byKind.path += 1;
+      if (!existsSync(join(root, path)))
+        errors.push(`${document}: names \`${path}\`, which does not exist`);
+    }
+
+    for (const { metric, value } of coverageClaims(text)) {
+      byKind.number += 1;
+      const configured = thresholds[metric];
+      if (configured === undefined)
+        errors.push(
+          `${document}: quotes ${metric} coverage as ${value}%, but ` +
+            "vitest.config.ts sets no such threshold",
+        );
+      else if (configured !== value)
+        errors.push(
+          `${document}: quotes ${metric} coverage as ${value}%, but ` +
+            `vitest.config.ts sets it to ${configured}%`,
+        );
+    }
+
+    for (const version of nodeVersionClaims(text)) {
+      byKind.version += 1;
+      if (version !== nvmrc)
+        errors.push(
+          `${document}: names Node ${version}, but .nvmrc pins ${nvmrc}`,
+        );
+    }
+  }
+
+  const claims = byKind.script + byKind.number + byKind.version + byKind.path;
+  return { claims, byKind, errors };
+}
+
+/** Lint the tree named by argv[0], or this repository, and say what was found. */
+export function main(
+  argv: readonly string[],
+  output: GateOutput = processOutput,
+): number {
+  const { claims, byKind, errors } = lintDocs(argv[0] ?? REPOSITORY);
+  if (errors.length > 0) {
+    output.err(
+      `docs lint: ${errors.length} error(s)\n` +
+        errors.map((e) => `  - ${e}\n`).join(""),
+    );
+    return 1;
+  }
+  output.out(
+    `docs lint: ${claims} claim(s) clean ` +
+      `(scripts ${byKind.script}, numbers ${byKind.number}, ` +
+      `versions ${byKind.version}, paths ${byKind.path})\n`,
+  );
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url, process.argv[1]))
+  process.exitCode = main(process.argv.slice(2));
diff --git a/test/docs-contract.test.ts b/test/docs-contract.test.ts
new file mode 100644
index 0000000..6bc0312
--- /dev/null
+++ b/test/docs-contract.test.ts
@@ -0,0 +1,347 @@
+// The docs contract, executed.
+//
+// README.md and CONTRIBUTING.md are the first documents a reader opens, and
+// prose goes stale silently: a renamed script, a moved coverage threshold, a
+// pinned Node version that changed, a path that no longer exists all read
+// exactly as well wrong as right. lint-docs.ts extracts each of those claims
+// and checks it against the file that is actually true; these fixtures prove
+// it fires, on a tree where only one thing is deliberately wrong.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  coverageClaims,
+  isPathLike,
+  lintDocs,
+  main,
+  nodeVersionClaims,
+  pathClaims,
+  scriptClaims,
+} from "../scripts/lint-docs.ts";
+import { collect } from "./support/collect.ts";
+import { temporary } from "./setup.ts";
+
+const REPOSITORY = join(import.meta.dirname, "..");
+
+interface Thresholds {
+  readonly statements?: number;
+  readonly branches?: number;
+  readonly functions?: number;
+  readonly lines?: number;
+}
+
+const DEFAULT_SCRIPTS = {
+  test: "vitest run",
+  verify: "npm run test",
+  "lint:adrs": "node scripts/lint-adrs.ts",
+};
+const DEFAULT_THRESHOLDS = {
+  statements: 96.55,
+  branches: 86.05,
+  functions: 100,
+  lines: 96.53,
+};
+const DEFAULT_NVMRC = "24.21.0";
+
+/** A `vitest.config.ts` source text whose thresholds block carries `thresholds`. */
+function vitestConfig(thresholds: Thresholds): string {
+  const entries = Object.entries(thresholds)
+    .map(([metric, value]) => `        ${metric}: ${value ?? 0},`)
+    .join("\n");
+  return [
+    "export default {",
+    "  test: {",
+    "    coverage: {",
+    "      thresholds: {",
+    entries,
+    "      },",
+    "    },",
+    "  },",
+    "};",
+    "",
+  ].join("\n");
+}
+
+/**
+ * A fixture repository: package.json, vitest.config.ts and .nvmrc holding
+ * what is actually true, plus whichever of README.md and CONTRIBUTING.md the
+ * caller supplies claiming things about it. `docs/adr/` and `CHANGELOG.md`
+ * exist in every fixture, so a document can make a true path claim about
+ * them without every test having to create its own.
+ */
+function repo(options: {
+  readme?: string;
+  contributing?: string;
+  scripts?: Readonly<Record<string, string>>;
+  thresholds?: Thresholds;
+  nvmrc?: string;
+  noThresholdsBlock?: boolean;
+}): string {
+  const root = mkdtempSync(join(temporary(), "docs-lint-"));
+  writeFileSync(
+    join(root, "package.json"),
+    JSON.stringify({
+      name: "fixture",
+      version: "0.0.0",
+      scripts: options.scripts ?? DEFAULT_SCRIPTS,
+    }),
+  );
+  writeFileSync(
+    join(root, "vitest.config.ts"),
+    options.noThresholdsBlock
+      ? "export default { test: { coverage: {} } };\n"
+      : vitestConfig({ ...DEFAULT_THRESHOLDS, ...options.thresholds }),
+  );
+  writeFileSync(join(root, ".nvmrc"), options.nvmrc ?? DEFAULT_NVMRC);
+  mkdirSync(join(root, "docs", "adr"), { recursive: true });
+  writeFileSync(join(root, "CHANGELOG.md"), "# Changelog\n");
+  if (options.readme !== undefined)
+    writeFileSync(join(root, "README.md"), options.readme);
+  if (options.contributing !== undefined)
+    writeFileSync(join(root, "CONTRIBUTING.md"), options.contributing);
+  return root;
+}
+
+// One document naming a real claim of every kind lintDocs checks.
+const README_ALL_CLAIMS = [
+  "# Fixture",
+  "",
+  "`npm run verify` runs the gates.",
+  "",
+  "See `docs/adr/` for the decision record.",
+  "",
+  "Coverage: statements 96.55%, branches 86.05%, functions 100%, lines 96.53%.",
+  "",
+  "Install Node 24.21.0, pinned in `.nvmrc`.",
+  "",
+].join("\n");
+
+describe("scriptClaims", () => {
+  it("reads npm run <script>, deduplicated", () => {
+    expect(
+      scriptClaims("`npm run verify` and again `npm run verify`"),
+    ).toStrictEqual(["verify"]);
+  });
+
+  it("reads bare npm test as the test script", () => {
+    expect(scriptClaims("run `npm test` first")).toStrictEqual(["test"]);
+  });
+
+  it("finds nothing in prose naming no script", () => {
+    expect(scriptClaims("nothing to see here")).toStrictEqual([]);
+  });
+});
+
+describe("isPathLike", () => {
+  it("accepts a file with an extension", () => {
+    expect(isPathLike("CHANGELOG.md")).toBe(true);
+  });
+
+  it("accepts a directory with a trailing slash", () => {
+    expect(isPathLike("docs/adr/")).toBe(true);
+  });
+
+  it("refuses a bare word with neither a slash nor a dot", () => {
+    expect(isPathLike("deploy-config-schema")).toBe(false);
+  });
+
+  it("refuses a span with a space", () => {
+    expect(isPathLike("npm run verify")).toBe(false);
+  });
+
+  it("refuses a span with a colon", () => {
+    expect(isPathLike("normative:")).toBe(false);
+  });
+});
+
+describe("pathClaims", () => {
+  it("reads only the backtick spans that look like paths", () => {
+    expect(
+      pathClaims(
+        "See `docs/adr/` and `deploy-config-schema`, run `npm run verify`.",
+      ),
+    ).toStrictEqual(["docs/adr/"]);
+  });
+
+  // A fenced block's opening and closing triple backtick are not a pair.
+  // Reading them as one swallows the block whole, and then pairs every
+  // backtick after it with the wrong partner for the rest of the document:
+  // this fixture reproduces the real README.md, which has one such fence.
+  it("does not let a fenced code block's triple backticks reshuffle every pairing after it", () => {
+    const text = [
+      "```bash",
+      "npm run verify",
+      "```",
+      "",
+      "See `docs/adr/` for detail.",
+      "",
+    ].join("\n");
+    expect(pathClaims(text)).toStrictEqual(["docs/adr/"]);
+  });
+});
+
+describe("coverageClaims", () => {
+  it("reads every metric a document quotes", () => {
+    expect(
+      coverageClaims("statements 96.55%, branches 86.05%, functions 100%"),
+    ).toStrictEqual([
+      { metric: "statements", value: 96.55 },
+      { metric: "branches", value: 86.05 },
+      { metric: "functions", value: 100 },
+    ]);
+  });
+
+  it("finds nothing when no metric is named", () => {
+    expect(coverageClaims("coverage is good")).toStrictEqual([]);
+  });
+});
+
+describe("nodeVersionClaims", () => {
+  it("reads a semver following the word Node", () => {
+    expect(nodeVersionClaims("Install Node 24.21.0 first")).toStrictEqual([
+      "24.21.0",
+    ]);
+  });
+
+  it("finds nothing when no version is named", () => {
+    expect(nodeVersionClaims("Install the version in .nvmrc")).toStrictEqual(
+      [],
+    );
+  });
+});
+
+describe("lintDocs", () => {
+  it("passes a document naming a real claim of every kind, and counts them", () => {
+    const result = lintDocs(repo({ readme: README_ALL_CLAIMS }));
+    expect(result.errors).toStrictEqual([]);
+    expect(result.claims).toBeGreaterThan(0);
+    expect(result.byKind).toStrictEqual({
+      script: 1,
+      number: 4,
+      version: 1,
+      path: 2,
+    });
+  });
+
+  it("has real claims to check, not an empty list, on a clean tree", () => {
+    const result = lintDocs(repo({ readme: README_ALL_CLAIMS }));
+    expect(result.claims).toBe(8);
+  });
+
+  it("fails a renamed script, naming the document and the claim", () => {
+    const root = repo({
+      readme: "`npm run verify` runs the gates.\n",
+      scripts: { test: "vitest run" },
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: names `npm run verify`, which is not a script in package.json",
+    ]);
+  });
+
+  it("fails a path the document names that does not exist", () => {
+    const root = repo({ readme: "See `nowhere/at/all.md` for detail.\n" });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: names `nowhere/at/all.md`, which does not exist",
+    ]);
+  });
+
+  it("fails a coverage number that no longer matches the ratchet", () => {
+    const root = repo({
+      readme: "Coverage: statements 96.55%.\n",
+      thresholds: { statements: 97.1 },
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: quotes statements coverage as 96.55%, but vitest.config.ts sets it to 97.1%",
+    ]);
+  });
+
+  it("fails a coverage number for a metric the config no longer thresholds", () => {
+    const root = repo({
+      readme: "Coverage: branches 86.05%.\n",
+      noThresholdsBlock: true,
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: quotes branches coverage as 86.05%, but vitest.config.ts sets no such threshold",
+    ]);
+  });
+
+  it("fails a Node version that no longer matches .nvmrc", () => {
+    const root = repo({
+      readme: "Install Node 24.21.0 first.\n",
+      nvmrc: "22.10.0",
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: names Node 24.21.0, but .nvmrc pins 22.10.0",
+    ]);
+  });
+
+  it("checks CONTRIBUTING.md too, and independently of README.md", () => {
+    const root = repo({
+      readme: "# Fine\n",
+      contributing: "`npm test` is how a change is checked.\n",
+      scripts: { verify: "npm run test" },
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "CONTRIBUTING.md: names `npm run test`, which is not a script in package.json",
+    ]);
+  });
+
+  it("passes a tree with neither document, since that failure belongs elsewhere", () => {
+    const result = lintDocs(repo({}));
+    expect(result).toStrictEqual({
+      claims: 0,
+      byKind: { script: 0, number: 0, version: 0, path: 0 },
+      errors: [],
+    });
+  });
+
+  it("passes this repository's own README.md and CONTRIBUTING.md", () => {
+    const result = lintDocs(REPOSITORY);
+    expect(result.errors).toStrictEqual([]);
+    expect(result.claims).toBeGreaterThan(0);
+  });
+});
+
+describe("the command", () => {
+  it("says how many claims were clean, broken down by kind, and exits 0", () => {
+    const output = collect();
+    expect(main([repo({ readme: README_ALL_CLAIMS })], output)).toBe(0);
+    expect(output.text()).toBe(
+      "docs lint: 8 claim(s) clean (scripts 1, numbers 4, versions 1, paths 2)\n",
+    );
+  });
+
+  it("lists every broken claim under a count, and exits 1", () => {
+    const output = collect();
+    const root = repo({ readme: "`npm run gone` runs nothing.\n" });
+    expect(main([root], output)).toBe(1);
+    expect(output.text()).toBe(
+      "docs lint: 1 error(s)\n" +
+        "  - README.md: names `npm run gone`, which is not a script in package.json\n",
+    );
+  });
+
+  it("checks this repository when no tree is named", () => {
+    expect(main([], collect())).toBe(0);
+  });
+
+  it("runs when Node starts the script, which is how CI runs it", () => {
+    const run = spawnSync(
+      process.execPath,
+      [
+        join(REPOSITORY, "scripts", "lint-docs.ts"),
+        repo({ readme: "`npm run gone` runs nothing.\n" }),
+      ],
+      { encoding: "utf8" },
+    );
+    expect(run.status).toBe(1);
+    expect(run.stderr).toContain("names `npm run gone`");
+  });
+});

From 1e7f167e63816b82ac059d0bc857480b23d7d7f5 Mon Sep 17 00:00:00 2001
From: Joris Wouter Jonkers <info@jorisjonkers.dev>
Date: Mon, 14 Sep 2026 10:08:39 +0200
Subject: [PATCH 2/3] ci: wire the docs contract into CI, verify and the
 behaviour ledger

The gate landed in #69 but was left unwired while #23 split CI into
one job per gate; per ADR 0102, a gate's script and its CI job belong
in the same pull request, and test/pipeline-wiring.test.ts now proves
it. lint:docs runs in the Contracts job beside the other document
checks and in npm run verify.

Refreshes README's coverage line, stale since the ratchet moved
under it, and adds REQ-011 to the behaviour ledger. Coverage moved
with lint-docs.ts entering the measured set: its three unreachable
regex-capture fallbacks became one cast instead of dead branches, its
one real fallback (a package.json with no scripts field) is now
tested, and every threshold rose with what the suite reaches.
---
 .github/workflows/ci.yml   |  8 ++++++++
 README.md                  |  2 +-
 docs/architecture.md       |  6 ++++--
 docs/requirements.md       |  3 ++-
 package.json               |  3 ++-
 scripts/lint-docs.ts       | 17 ++++++++++++++---
 test/docs-contract.test.ts | 30 +++++++++++++++++++++++++++++-
 vitest.config.ts           | 24 +++++++++++++-----------
 8 files changed, 73 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9ad54ac..8c4cca0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -127,6 +127,14 @@
       - 'name': 'Requirements ledger'
         'run': 'npm run lint:requirements'
 
+      # README.md and CONTRIBUTING.md, held to the repository they describe:
+      # every named script exists, every backtick-quoted path exists, every
+      # quoted coverage number matches vitest.config.ts, every quoted Node
+      # version matches .nvmrc. The link contract above proves a link and its
+      # anchor resolve; this proves the prose around them is still true.
+      - 'name': 'Docs contract'
+        'run': 'npm run lint:docs'
+
   'tests':
     'name': 'Tests'
     'runs-on': 'ubuntu-latest'
diff --git a/README.md b/README.md
index dae14d7..55a2c22 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ npm run verify      # lint, format, typecheck, ADR contract, tests + coverage
 `npm run lint:adrs` alone runs the decision-record contract, and `npm test`
 runs the suite without enforcing coverage. `npm run test:coverage` (part of
 `npm run verify`) enforces the ratchet in `vitest.config.ts`: statements
-96.9%, branches 86.52%, functions 100%, lines 96.59%.
+97.71%, branches 89.78%, functions 100%, lines 97.51%.
 
 ## Conventions
 
diff --git a/docs/architecture.md b/docs/architecture.md
index cffbbd4..513c06e 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -207,13 +207,15 @@ proves the two never drift apart.
 | links | `npm run lint:links` | relative links and heading anchors across every tracked Markdown file |
 | manifests | `npm run lint:manifests` | every rendered example object against pinned Kubernetes and CRD schemas |
 | requirements | `npm run lint:requirements` | a behaviour ledger row that no longer parses, names a missing or empty test, drifts from its stated count, or is cited by an id no row carries |
+| docs | `npm run lint:docs` | a script, path, coverage number or Node version README.md or CONTRIBUTING.md name that no longer matches the repository |
 | tests | `npm run test:coverage` | behaviour, plus the coverage ratchet |
 | package contents | `node scripts/check-package-contents.ts` | `npm pack` shipping a file outside `docs/adr/` and `spec/`, the boundary the package's `files` field states but does not enforce on its own |
 | actionlint | a pinned `actionlint` binary | invalid workflow syntax, an undefined `${{ }}` expression, a shellcheck finding inside a `run:` step |
 | secret scan | a pinned `gitleaks` binary | a committed secret matching the default ruleset, or this repository's own allowlist entries |
 
-Decisions, links, manifests and requirements share one CI job, `contracts`:
-all four check a document against a rule rather than code against a graph.
+Decisions, links, manifests, requirements and docs share one CI job,
+`contracts`: all five check a document against a rule rather than code
+against a graph.
 Boundaries runs alone as `architecture`, because it is the one gate that
 speaks for `docs/architecture.md` itself rather than for a document beside it.
 
diff --git a/docs/requirements.md b/docs/requirements.md
index 8e8e6f7..52dfd43 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -20,7 +20,7 @@ test file and holds at least one test; ids are unique; the count this
 document states matches the number of rows it holds; and every id cited
 anywhere in the tracked tree resolves to a row here.
 
-This ledger holds **10** rows. The compiler's behaviours join it as they land.
+This ledger holds **11** rows. The compiler's behaviours join it as they land.
 
 | id | a contributor or a consumer can rely on | proved by |
 |---|---|---|
@@ -34,3 +34,4 @@ This ledger holds **10** rows. The compiler's behaviours join it as they land.
 | REQ-008 | Coverage is a ratchet: no `v8`, `c8` or `istanbul` ignore comment exempts a line from it | [test/harness.test.ts](../test/harness.test.ts) |
 | REQ-009 | The npm package ships nothing outside `docs/adr/` and `spec/`, checked against what npm would really pack rather than the advisory `files` field | [test/package-contents-contract.test.ts](../test/package-contents-contract.test.ts) |
 | REQ-010 | A gate's npm script and the CI job that runs it land in the same pull request, so neither can drift from the other unnoticed | [test/pipeline-wiring.test.ts](../test/pipeline-wiring.test.ts) |
+| REQ-011 | Every script, path, coverage number and Node version README.md and CONTRIBUTING.md name matches the repository they describe | [test/docs-contract.test.ts](../test/docs-contract.test.ts) |
diff --git a/package.json b/package.json
index ac9f5b1..213da26 100644
--- a/package.json
+++ b/package.json
@@ -19,12 +19,13 @@
     "lint:manifests": "node scripts/lint-manifests.ts",
     "lint:boundaries": "node scripts/lint-boundaries.ts",
     "lint:requirements": "node scripts/lint-requirements.ts",
+    "lint:docs": "node scripts/lint-docs.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "verify": "npm run lint && npm run format:check && npm run typecheck && npm run lint:adrs && npm run lint:links && npm run lint:manifests && npm run lint:requirements && npm run lint:boundaries && npm run test:coverage"
+    "verify": "npm run lint && npm run format:check && npm run typecheck && npm run lint:adrs && npm run lint:links && npm run lint:manifests && npm run lint:requirements && npm run lint:docs && npm run lint:boundaries && npm run test:coverage"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
diff --git a/scripts/lint-docs.ts b/scripts/lint-docs.ts
index f6526bf..74eebc2 100644
--- a/scripts/lint-docs.ts
+++ b/scripts/lint-docs.ts
@@ -40,11 +40,22 @@ export interface DocsLintResult {
   readonly errors: readonly string[];
 }
 
+/**
+ * The text a regex's first capture group matched. TypeScript types every
+ * group as possibly absent regardless of quantifier, but a `+`-quantified
+ * group that `matchAll` actually yielded a match for cannot itself be empty:
+ * the whole match would not exist otherwise. The cast says so once, rather
+ * than `?? ""` guessing at a case none of these regexes can reach.
+ */
+function requiredGroup(match: RegExpMatchArray): string {
+  return match[1] as string;
+}
+
 /** Every `npm run <script>` and bare `npm test` a document names, deduplicated. */
 export function scriptClaims(text: string): readonly string[] {
   const found = new Set<string>();
   for (const match of text.matchAll(/npm run ([a-zA-Z0-9:_-]+)/g))
-    found.add(match[1] ?? "");
+    found.add(requiredGroup(match));
   if (/\bnpm test\b/.test(text)) found.add("test");
   return [...found];
 }
@@ -72,7 +83,7 @@ export function pathClaims(text: string): readonly string[] {
   const prose = text.replace(/^```[\s\S]*?^```/gm, "");
   const found = new Set<string>();
   for (const match of prose.matchAll(/`([^`]+)`/g)) {
-    const candidate = match[1] ?? "";
+    const candidate = requiredGroup(match);
     if (isPathLike(candidate)) found.add(candidate);
   }
   return [...found];
@@ -95,7 +106,7 @@ export function coverageClaims(
 export function nodeVersionClaims(text: string): readonly string[] {
   const found = new Set<string>();
   for (const match of text.matchAll(/\bNode\s+v?(\d+\.\d+\.\d+)\b/g))
-    found.add(match[1] ?? "");
+    found.add(requiredGroup(match));
   return [...found];
 }
 
diff --git a/test/docs-contract.test.ts b/test/docs-contract.test.ts
index 6bc0312..bffdfd3 100644
--- a/test/docs-contract.test.ts
+++ b/test/docs-contract.test.ts
@@ -6,6 +6,10 @@
 // exactly as well wrong as right. lint-docs.ts extracts each of those claims
 // and checks it against the file that is actually true; these fixtures prove
 // it fires, on a tree where only one thing is deliberately wrong.
+//
+// REQ-011 (docs/requirements.md): every script, path, coverage number and
+// Node version README.md and CONTRIBUTING.md name matches the repository
+// they describe.
 import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -77,6 +81,7 @@ function repo(options: {
   thresholds?: Thresholds;
   nvmrc?: string;
   noThresholdsBlock?: boolean;
+  noScriptsField?: boolean;
 }): string {
   const root = mkdtempSync(join(temporary(), "docs-lint-"));
   writeFileSync(
@@ -84,7 +89,9 @@ function repo(options: {
     JSON.stringify({
       name: "fixture",
       version: "0.0.0",
-      scripts: options.scripts ?? DEFAULT_SCRIPTS,
+      ...(options.noScriptsField
+        ? {}
+        : { scripts: options.scripts ?? DEFAULT_SCRIPTS }),
     }),
   );
   writeFileSync(
@@ -293,6 +300,27 @@ describe("lintDocs", () => {
     ]);
   });
 
+  it("treats a package.json with no scripts field as naming none", () => {
+    const root = repo({
+      readme: "See `docs/adr/` for detail.\n",
+      noScriptsField: true,
+    });
+    const result = lintDocs(root);
+    expect(result.errors).toStrictEqual([]);
+    expect(result.byKind.script).toBe(0);
+  });
+
+  it("fails a script the document names against a package.json with no scripts field", () => {
+    const root = repo({
+      readme: "`npm run verify` runs the gates.\n",
+      noScriptsField: true,
+    });
+    const { errors } = lintDocs(root);
+    expect(errors).toStrictEqual([
+      "README.md: names `npm run verify`, which is not a script in package.json",
+    ]);
+  });
+
   it("passes a tree with neither document, since that failure belongs elsewhere", () => {
     const result = lintDocs(repo({}));
     expect(result).toStrictEqual({
diff --git a/vitest.config.ts b/vitest.config.ts
index 39339f9..2b4df6c 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -22,19 +22,21 @@ export default defineConfig({
       // A ratchet, per docs/adr/architecture/0101-coverage-is-a-ratchet.md:
       // set from what the suite reaches, and only ever raised.
       //
-      // Measured 2026-09-14, after the requirements ledger gate's own tests
-      // covered its citation-ordering branches (and, like the other gates,
-      // left only its bottom-of-file entrypoint guard uncovered), two runs
-      // of one tree, identical both times: statements 390/400, branches
-      // 214/241, functions 62/62, lines 356/366. What is left uncovered
-      // elsewhere is mostly the one-line command guard at the bottom of each
-      // other gate and the branches for a tool that cannot be started at
-      // all.
+      // Measured 2026-09-14, after the docs contract gate's own tests
+      // covered it (its `?? ""` capture-group fallbacks were replaced by one
+      // cast, since a `+`-quantified group cannot be absent when `matchAll`
+      // yields a match for it; the missing-scripts-field branch is real and
+      // is tested) and, like the other gates, left only its bottom-of-file
+      // entrypoint guard uncovered, two runs of one tree, identical both
+      // times: statements 470/481, branches 246/274, functions 74/74, lines
+      // 432/443. What is left uncovered elsewhere is mostly the one-line
+      // command guard at the bottom of each other gate and the branches for
+      // a tool that cannot be started at all.
       thresholds: {
-        statements: 97.5,
-        branches: 88.79,
+        statements: 97.71,
+        branches: 89.78,
         functions: 100,
-        lines: 97.26,
+        lines: 97.51,
       },
     },
   },

From a6f99842fed5ef012620fd732f537af9514f3d46 Mon Sep 17 00:00:00 2001
From: Joris Wouter Jonkers <info@jorisjonkers.dev>
Date: Mon, 14 Sep 2026 10:10:32 +0200
Subject: [PATCH 3/3] docs: count the gates the table actually lists

---
 docs/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 513c06e..7f3d94c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -188,7 +188,7 @@ clean tree is untested: nothing proves it would fail.
 
 ## Gates
 
-Nine gates hold the structure, and each exists because its absence has already
+Thirteen gates hold the structure, and each exists because its absence has already
 cost something in the generation this compiler replaces. Each runs as its own
 CI job, aggregated by one required check that fails when any gate job fails,
 is cancelled, or is skipped