@avi2dg/checks 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.30.0
+
+Released 2026-09-28.
+
+### Features
+
+- **testing:** refuse full mutation runs outside CI [#106](https://github.com/avi2d/checks/pull/106)
+- **docs:** refuse a decision-record revision link named on one side only [#105](https://github.com/avi2d/checks/pull/105)
+
+## 0.29.0
+
+Released 2026-09-28.
+
+### Breaking changes
+
+- **docs:** hold agent files to a 3,000-character router where every entry points [#101](https://github.com/avi2d/checks/pull/101)
+
+### Fixes
+
+- **testing:** run checks-test with CI=true so focused tests fail locally [#100](https://github.com/avi2d/checks/pull/100)
+
 ## 0.28.0
 
 Released 2026-09-28.

package/README.md

@@ -124,7 +124,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
-| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
+| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
 | dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
@@ -135,6 +135,7 @@ These bins run on their own:
 
 - [`checks-test`](docs/gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip without a reason at its test site.
 - [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
+- [`checks-mutation`](docs/gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds every mutant in a pull request to no regression.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
@@ -174,7 +175,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect rule blocks under `src/quality/presets/` |
 | `dist/` | the compiled oxlint plugins and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
-| `stryker.preset.js` | the Stryker mutation-testing preset |
+| `stryker.preset.js` | the Stryker mutation-testing preset, which refuses a full run outside CI |
 | `tsconfig.effect.json` | the tsconfig fragment with the shared compiler options and the Effect language-service block |
 | `ts-reset.d.ts` | the two ts-reset rules `tsconfig.effect.json` lists in `files` |
 

package/dist/templates/agents.md

@@ -7,11 +7,3 @@
 <Leave this section out when the lead holds every constraint.>
 
 - <A constraint an agent cannot infer from the code, and the file that holds its detail.>
-
-## Maintaining this file
-
-Keep this file for knowledge useful to almost every future agent session in this project.
-Do not repeat what the codebase already shows.
-Point to the authoritative file or command instead.
-Prefer rewriting or pruning existing entries over appending new ones.
-When updating this file, preserve this bar for all agents and keep entries concise.

package/docs/design.md

@@ -86,6 +86,7 @@ npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
+`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
 CI runs `git diff --exit-code` over the whole tree after `bun run build`.
@@ -140,7 +141,8 @@ That flag reports a repeated block as new once its text changes, so a change tha
 ## checks-test runs the suite itself
 
 `checks-test` runs bun itself rather than reading a report that another run left.
-A skip taken only on CI shows only in CI's own run, and an earlier run's report may be stale or narrowed.
+A `"ci"` skip gated on a daemon or tool that CI lacks shows in CI's own run, and an earlier run's report may be stale or narrowed.
+When the same resource is also absent locally, the test skips there too, and its `"ci"` declaration leaves that skip undeclared, so the local run fails.
 It reads the JUnit report bun writes to a temporary directory, because bun has no other per-test output meant for a program.
 
 ## Quarantine has one limit
@@ -175,7 +177,8 @@ A repository adopts the templates as its files change, and an untouched file is
 The prose rules judge only the lines a change adds or edits.
 A report about the past is refused the way a promise about the future is, because history on a living page reads as current fact.
 Text nobody touched never breaks the templates or the prose rules, and a record keeps the words it was written in.
-A repository needs no cleanup pass before the gate runs.
+A repository needs no cleanup pass before the gate runs, except on its agent files.
+The ceiling, the rule against a `## Maintaining this file` section and the entry rule judge every agent file at the head commit, because an agent reads the whole file every session, touched or not.
 Review, not the check, keeps a task heading verb first.
 No word list tells `Test layout` from `Test the layout`, and a check that passes the noun would be worse than none.
 

package/docs/gates/checks-docs.md

@@ -13,6 +13,8 @@ It holds each doc file a change touches to the template for its kind.
 It lists every other doc file that does not match its template yet, and does not fail on it.
 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 or an agent file names a path, link or command that does not resolve, and the range added or broke it.
+It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
+It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
 It fails when a living doc or an agent file names a code span the range removed from every file outside the docs, on any line.
 [Paths, links and commands](#paths-links-and-commands) says how each reference resolves.
 The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
@@ -59,6 +61,7 @@ A template decides a file's structure, and the template file itself is the refer
   A `Date: YYYY-MM-DD` line follows the title.
   The first word under Status is Proposed, Accepted, Rejected, Deprecated, Superseded or Retired.
   No other record holds its number.
+  A Status that amends, narrows or supersedes another record names it, and the other record names it back.
 - A changelog lists its releases newest first, and each opens with a `Released YYYY-MM-DD.` line.
 - A how-to or tutorial page numbers its steps.
 - `CLAUDE.md` is its template word for word.
@@ -142,6 +145,24 @@ audience: consumers
 ---
 ```
 
+## Agent files
+
+An agent file holds the router its template sketches, and the rules below hold its shape whatever the range touches.
+A file over 3,000 characters fails.
+Move each part's notes into the people doc that covers that part, and delete what a check or the code already holds.
+A file that holds a `## Maintaining this file` section fails, because this gate holds the shape the section asked for.
+Each entry names at least one of these, or it fails:
+
+- A path in inline code that git tracks at the head commit, a file or a directory, such as `package.json`, `LICENSE` or `.gitignore`.
+  It resolves from the root or from the file's directory, `./` and `../` included, and a path that ends in `/` or `/.` names a directory, never a file.
+- A Markdown link written `[text](target)` with a destination and a closing parenthesis, and not an image.
+- A `bun run` command.
+
+Whether the link or the command resolves is the reference rule's call, as [Paths, links and commands](#paths-links-and-commands) says, and it fails when the range adds or breaks one.
+An entry is any list item a reader sees, the items above the first section included.
+A list item inside an HTML comment, an HTML block or an indented code block is not an entry.
+A fresh file passes the ceiling, and its entries pass once each names the file that holds its detail.
+
 ## What it reads
 
 It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
@@ -150,6 +171,7 @@ It reads the lines the range adds or edits from the diff, with renames detected,
 It reads the files tracked at both ends of the range, and the `scripts` of each `package.json` a living doc or an agent file sits under.
 It compares each code span a living doc or an agent file names with the text git tracks outside the docs at both ends of the range.
 It reads the repository's own name and its direct dependencies from the root `package.json` at the head commit.
+It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
 
@@ -167,8 +189,8 @@ 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, every line it adds to a living doc or an agent file holds to the prose rules, it adds or breaks no reference that does not resolve, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 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, the range adds or breaks a reference that does not resolve, or the range removes a name a living doc or an agent file still carries |
+| 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, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 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, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
@@ -191,6 +213,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files
 
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository adopts the templates as its files change, and the prose rules as its lines change, because an untouched file or line never fails those checks.
+It reshapes its agent files when it adopts the gate, because [Agent files](#agent-files) judges each one whatever the range touches.
 A name the range removes fails wherever a doc still carries it, because the removal is what turned the line stale.
 
 ## Related topics

package/docs/gates/checks-mutation-compare.md

@@ -69,12 +69,18 @@ mutation-compare: REGRESSION (1 mutant(s))
 
 Only a CI step the repository writes runs it.
 A repository runs it with `--advisory` for its first month, then drops the flag so it blocks.
+A full sweep runs in CI and never on a laptop.
+Start a baseline with `gh workflow run mutation` and keep its report as an artifact.
+The shared preset refuses a full `stryker run` outside CI and names that workflow command instead, as [checks-mutation](checks-mutation.md) says.
 
 ## Running it in CI
 
-It runs on pull requests, comparing the head report against a report built at the merge-base:
+It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base:
 
 ```yaml
+name: mutation-compare
+on:
+  pull_request:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
@@ -86,12 +92,25 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bunx stryker run
       - run: |
-          base="$(git merge-base HEAD origin/main)"
-          git worktree add /tmp/mutation-base "$base"
-          (cd /tmp/mutation-base && bun install --frozen-lockfile && bunx stryker run)
-      - run: bun run checks-mutation-compare --advisory /tmp/mutation-base/reports/mutation/mutation.json reports/mutation/mutation.json
+          base_worktree="$RUNNER_TEMP/mutation-base-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          echo "BASE_WORKTREE=$base_worktree" >> "$GITHUB_ENV"
+          git worktree prune
+          git worktree add "$base_worktree" "$(git merge-base HEAD origin/main)"
+          (cd "$base_worktree" && bun install --frozen-lockfile && bunx stryker run)
+      - run: bun run checks-mutation-compare --advisory "$BASE_WORKTREE/reports/mutation/mutation.json" reports/mutation/mutation.json
+      - if: always() && env.BASE_WORKTREE != ''
+        run: |
+          git worktree remove --force "$BASE_WORKTREE"
+          git worktree prune
 ```
 
+Both Stryker runs are full sweeps, and GitHub sets `CI=true` on every runner, so the preset lets them through.
+The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
+A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` instead.
+With `CI_RUNS_ON` unset, the job then runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+
 ## Related topics
 
+- [checks-mutation](checks-mutation.md)
 - [checks-test-layout](checks-test-layout.md)

package/docs/gates/checks-mutation.md

@@ -0,0 +1,98 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-mutation
+
+`checks-mutation` runs Stryker and refuses a full run outside CI.
+
+## What it checks
+
+It refuses a full mutation run when `CI` is not `true`.
+A full run is one with no `--mutate <glob>` and no `--incremental` flag.
+A `--mutate` without a glob, `--incrementalFile` alone or `--incremental` with `--force` is still a full run.
+Its refusal names `gh workflow run mutation` as the command that starts the same run in CI.
+A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because pull request comparisons scope to named files.
+An incremental run stays allowed locally only when its incremental report exists, because it reuses the results of mutants that did not change.
+That report is the `incrementalFile` Stryker resolves from the command line and the config file, else `reports/stryker-incremental.json`.
+With no report there, the refusal says to pass `--mutate <glob>`, or to start the full baseline in CI with `gh workflow run mutation`.
+`--help`, `-h` and `--version` are not runs, so they pass straight through to Stryker.
+A laptop with `CI=true` set opts in to a full run on purpose, and the refusal lets it through.
+
+The shared Stryker preset makes the same decision from `process.argv` when a `stryker run` loads it.
+So a bare `bunx stryker run` in a repository whose `stryker.conf.mjs` spreads the preset is refused the same way, and `checks-mutation` is a thin wrapper over that decision.
+The preset also registers an ignore plugin that checks the incremental report once Stryker has resolved its options, because a config file can set `incrementalFile` after the preset loads.
+A config that replaces `plugins` or `ignorers` must keep the preset's entries, or that check does not run.
+
+## What it reads
+
+It reads `CI` from the environment.
+It forwards every argument to `stryker run` through `bun x stryker run`.
+
+## Arguments
+
+```sh
+checks-mutation [--mutate <glob>] [--incremental] [<stryker args>...]
+```
+
+Every argument after the bin name forwards to `stryker run`.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | Stryker exited 0 |
+| 1 | Stryker exited nonzero, including an incremental run refused for a missing report |
+| 2 | a full run outside CI was refused, or Stryker could not start |
+
+## Sample output
+
+A full run outside CI prints its refusal and exits 2:
+
+```
+checks-mutation: refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`
+```
+
+A bare `bunx stryker run` fails to load its config with the same refusal as the error and exits 1.
+An `--incremental` run with no report stops before instrumenting with the missing-report refusal as the error and exits 1.
+
+## When it runs
+
+A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
+Run scoped checks locally during development.
+A scheduled run never starts one, because a baseline costs a full Stryker run.
+
+## Running it in CI
+
+A repository starts a baseline by hand from a workflow named `mutation` and keeps its report as an artifact:
+
+```yaml
+name: mutation
+on:
+  workflow_dispatch:
+jobs:
+  mutation:
+    runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutation-report
+          path: reports/mutation/mutation.json
+```
+
+With `CI_RUNS_ON` unset, the job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+A repository sets `CI_RUNS_ON` only to name a different runner.
+The `name: mutation` line is what `gh workflow run mutation` looks up.
+GitHub sets `CI=true` on every runner, so the preset lets the full run through there.
+
+## Related topics
+
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-subsumed-tests](checks-subsumed-tests.md)

package/docs/gates/checks-repetition.md

@@ -12,6 +12,7 @@ The gate runs jscpd at 50 tokens and 5 lines against the base and head revisions
 It compares repeated lines for each file, so a decrease in another file never offsets a rise.
 It follows an edited rename back to the original file.
 A file that repeats lines without a rise is advisory.
+A block two bins need goes into a module both import, as `rangeFromArgs` and `checkoutFiles` in `src/core/git.ts` show.
 
 ## What it reads
 

package/docs/gates/checks-subsumed-tests.md

@@ -30,6 +30,8 @@ Build a bail-off report with this command:
 bunx stryker run --disableBail
 ```
 
+It is a full sweep, so outside CI the shared preset refuses it unless `--mutate <glob>` scopes it, as [checks-mutation](checks-mutation.md) says.
+
 The report records each killer as a test index, so it names each test by its file and its name from the report's `testFiles` table.
 
 ## Arguments

package/docs/gates/checks-test.md

@@ -9,6 +9,7 @@ audience: consumers
 ## What it checks
 
 It runs the default suite with `bun test --randomize` and reads Bun's JUnit report from that run.
+It runs Bun with `CI=true`, so `test.only` fails the run in every environment.
 Bun exits zero when tests skip, so `checks-test` checks every skipped test against its source declaration.
 A test that `test.skip`, `test.skipIf`, `test.if`, `test.todo` or an enclosing `describe.skip` skips fails unless the test declares its reason.
 
@@ -33,6 +34,8 @@ A skip is declared on the test itself and only there.
 Add `"ci"` or `"local"` as the third `skipReason` argument when a declaration applies to one environment.
 Omit the third argument when it applies in both environments.
 A declaration for the other environment is not judged in the current run.
+Bun sees `CI` set in every `checks-test` run, so a `"ci"` skip whose condition reads `process.env.CI` also skips in a local run and fails there as undeclared.
+Gate a `"ci"` skip on what CI lacks, such as a daemon or a tool, and never on `process.env.CI`.
 
 A declaration whose test passes or does not register fails a CI run.
 A local run warns about the same declaration because a condition can depend on the machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,9 @@
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
     "src/delivery/commit-identity.ts",
+    "src/testing/mutation.ts",
+    "src/testing/mutation-scope.js",
+    "src/testing/mutation-guard-plugin.js",
     "src/testing/mutation-compare.ts",
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
@@ -57,6 +60,7 @@
     "src/dependencies/advisories.ts",
     "src/dependencies/advisory-rules.ts",
     "src/dependencies/osv-scanner.ts",
+    "src/docs/doc-agents.ts",
     "src/docs/doc-outline.ts",
     "src/docs/doc-rules.ts",
     "src/docs/doc-references.ts",
@@ -94,6 +98,7 @@
     "checks-test": "src/testing/test.ts",
     "checks-flake": "src/testing/flake.ts",
     "checks-commit-identity": "src/delivery/commit-identity.ts",
+    "checks-mutation": "src/testing/mutation.ts",
     "checks-mutation-compare": "src/testing/mutation-compare.ts",
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",

package/src/complexity/knip.ts

@@ -27,7 +27,7 @@ const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
   const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
     Effect.flatMap((text) =>
       Effect.try({
-        try: () => JSON.parse(text),
+        try: (): unknown => JSON.parse(text),
         catch: () => new KnipError({ message: "package.json does not parse as JSON" }),
       })
     ),

package/src/core/gates.ts

@@ -19,6 +19,7 @@ export type KitGate = {
   readonly vector: Vector;
   readonly file: string;
   readonly reads: "tree" | "range";
+  readonly alsoReads?: string;
   readonly args?: readonly string[];
   readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
 };
@@ -40,7 +41,7 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },

package/src/docs/doc-agents.ts

@@ -0,0 +1,106 @@
+import { commandNames, type Snapshot } from "./doc-references.ts";
+import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
+
+export const AGENT_CEILING = 3000;
+
+const LIST_ITEM = /^(?:\s*>)*\s*(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
+const INDENT = /^[ \t]*/;
+const CODE_INDENT = 4;
+const INLINE_LINK =
+  /(?<![!\\])\[(?:[^[\]\\]|\\.|\[[^\]]*\])*\]\(\s*(?:<[^<>\n]+>|[^\s()<>]+(?:\([^\s()]*\)[^\s()<>]*)*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+const MAINTAINING = /^\s{0,3}#{1,6}\s+Maintaining this file(?:\s+#+)?\s*$/;
+
+export type AgentFinding = {
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+export function isAgentFile(repositoryPath: string): boolean {
+  return AGENT_NAMES.includes(repositoryPath.slice(repositoryPath.lastIndexOf("/") + 1));
+}
+
+export function ceilingFinding(text: string): AgentFinding | undefined {
+  if (text.length <= AGENT_CEILING) return undefined;
+  return {
+    line: undefined,
+    message: `is ${text.length} characters, over the 3,000-character ceiling for agent files. Keep what nearly every session needs plus one pointer per part, move each part's notes into the people doc that covers that part, and delete what a check already holds`,
+  };
+}
+
+export function maintainingFinding(text: string): AgentFinding | undefined {
+  const heading = scanMarkdown(text).find(({ kind, raw }) => kind === "heading" && MAINTAINING.test(raw));
+  if (heading === undefined) return undefined;
+  return {
+    line: heading.line,
+    message: "holds `## Maintaining this file`, which a router leaves out. Delete the section, since checks-docs holds the file's shape",
+  };
+}
+
+function indentOf(raw: string): number {
+  return (INDENT.exec(raw)?.[0] ?? "").replaceAll("\t", "    ").length;
+}
+
+export function entries(text: string): readonly MarkdownLine[] {
+  let inList = false;
+  let afterBlank = true;
+  return scanMarkdown(text).filter((line) => {
+    const blank = line.raw.trim() === "";
+    const indented = !blank && indentOf(line.raw) >= CODE_INDENT && !line.raw.trimStart().startsWith(">");
+    const listItem = line.kind === "prose" && LIST_ITEM.test(line.prose) && (inList || !indented);
+    if (listItem) inList = true;
+    else if (!blank && !indented && (afterBlank || line.kind !== "prose")) inList = false;
+    afterBlank = blank;
+    return listItem;
+  });
+}
+
+type Tracked = Pick<Snapshot, "files" | "directories">;
+
+const STAYS = new Set(["", "."]);
+
+function joined(directory: string, segment: string): string {
+  return directory === "" ? segment : `${directory}/${segment}`;
+}
+
+function enter(directory: string, segment: string, tracked: Tracked): string | undefined {
+  if (STAYS.has(segment)) return directory;
+  if (segment === "..") return directory === "" ? undefined : directory.slice(0, Math.max(directory.lastIndexOf("/"), 0));
+  const next = joined(directory, segment);
+  return tracked.directories.has(next) ? next : undefined;
+}
+
+function resolvesFrom(directory: string, span: string, tracked: Tracked): boolean {
+  const segments = span.split("/");
+  const last = segments.pop() ?? "";
+  const walked = segments.reduce<string | undefined>((at, segment) => (at === undefined ? undefined : enter(at, segment, tracked)), directory);
+  if (walked === undefined) return false;
+  if (!STAYS.has(last) && last !== ".." && tracked.files.has(joined(walked, last))) return true;
+  const end = enter(walked, last, tracked);
+  return end !== undefined && end !== "" && end !== directory;
+}
+
+function namesTrackedPath(agentFile: string, span: string, tracked: Tracked): boolean {
+  const directory = agentFile.includes("/") ? agentFile.slice(0, agentFile.lastIndexOf("/")) : "";
+  const fromFile = resolvesFrom(directory, span, tracked);
+  return fromFile || (!span.startsWith("./") && !span.startsWith("../") && resolvesFrom("", span, tracked));
+}
+
+function namesLink({ raw, prose }: MarkdownLine): boolean {
+  return [...raw.matchAll(INLINE_LINK)].some(({ index }) => prose.charAt(index) === "[");
+}
+
+function points(agentFile: string, line: MarkdownLine, tracked: Tracked): boolean {
+  return line.code.some((span) => namesTrackedPath(agentFile, span, tracked)) || namesLink(line) || commandNames(line).length > 0;
+}
+
+export function entryFindings(agentFile: string, text: string, tracked: Tracked): readonly AgentFinding[] {
+  return entries(text).flatMap((line) => {
+    if (points(agentFile, line, tracked)) return [];
+    return [
+      {
+        line: line.line,
+        message: "names no tracked path, link or `bun run` command. Name the file, link or command that holds the detail",
+      },
+    ];
+  });
+}

package/src/docs/doc-references.ts

@@ -131,6 +131,10 @@ function commandsOn({ kind, raw, code }: MarkdownLine): readonly string[] {
   return texts.flatMap((text) => [...text.matchAll(RUN)].map(([, name = ""]) => name.replace(/[),.;:]+$/, "")));
 }
 
+export function commandNames(line: MarkdownLine): readonly string[] {
+  return commandsOn(line).filter((name) => !NOT_A_NAME.test(name));
+}
+
 export type Judging = { readonly commands: boolean };
 
 export function unresolvedIn(doc: string, text: string, snapshot: Snapshot, { commands }: Judging): readonly Unresolved[] {

package/src/docs/doc-rules.ts

@@ -8,6 +8,7 @@ import {
   ruleProblem,
   type Heading,
   type Outline,
+  type Section,
   type Violation,
   VERSION,
 } from "./doc-outline.ts";
@@ -93,8 +94,76 @@ function recordNumber(path: string): number | undefined {
   return name === undefined ? undefined : Number(name);
 }
 
+const REVISION_CLAUSE = /\b(?:amend(?:s|ed)|narrow(?:s|ed)|supersede[sd])\b(?:[^.]|\.(?=\S))*/gi;
+const RECORD_REFERENCE = /\b(\d{4})\b/g;
+
+function numbersIn(text: string): ReadonlySet<number> {
+  return new Set(Array.from(text.matchAll(RECORD_REFERENCE), (match) => Number(match[1])));
+}
+
+function revisedIn(status: string): ReadonlySet<number> {
+  return new Set((status.match(REVISION_CLAUSE) ?? []).flatMap((clause) => [...numbersIn(clause)]));
+}
+
+function padded(number: number): string {
+  return String(number).padStart(4, "0");
+}
+
+function outlineOf(text: string): Outline {
+  return parseOutline(text.slice(frontMatterOf(text).text.length));
+}
+
+function statusSection(outline: Outline): Section | undefined {
+  return outline.sections.find(({ heading }) => heading.title === "Status");
+}
+
+type StatusLinks = {
+  readonly cited: ReadonlySet<number>;
+  readonly revised: ReadonlySet<number>;
+};
+
+function statusLinks(section: Section): StatusLinks {
+  const text = section.body.map(({ text: body }) => body).join("\n");
+  return { cited: numbersIn(text), revised: revisedIn(text) };
+}
+
+export type Records = {
+  readonly paths: readonly string[];
+  readonly links: ReadonlyMap<number, StatusLinks>;
+};
+
+export function recordsOf(records: readonly Doc[]): Records {
+  const links = new Map<number, StatusLinks>();
+  for (const { path, text } of records) {
+    const number = recordNumber(path);
+    const section = number === undefined || links.has(number) ? undefined : statusSection(outlineOf(text));
+    if (number !== undefined && section !== undefined) links.set(number, statusLinks(section));
+  }
+  return { paths: records.map(({ path }) => path), links };
+}
+
+function pairProblems(filed: number, own: Section, mine: StatusLinks, number: number, other: StatusLinks): readonly Violation[] {
+  if (number === filed) return [];
+  if (mine.revised.has(number) && !other.cited.has(filed)) {
+    const line = own.body.find(({ text: body }) => body.includes(padded(number)))?.line ?? own.heading.line;
+    return [{ line, message: `\`## Status\` names ${padded(number)} without ${padded(number)} naming ${padded(filed)} back` }];
+  }
+  if (other.revised.has(filed) && !mine.cited.has(number)) {
+    return [{ line: own.heading.line, message: `\`## Status\` is named by ${padded(number)} without naming ${padded(number)} back` }];
+  }
+  return [];
+}
+
+function revisionLinkProblems(path: string, outline: Outline, links: ReadonlyMap<number, StatusLinks>): readonly Violation[] {
+  const filed = recordNumber(path);
+  const own = filed === undefined ? undefined : statusSection(outline);
+  if (filed === undefined || own === undefined) return [];
+  const mine = statusLinks(own);
+  return [...links].flatMap(([number, other]) => pairProblems(filed, own, mine, number, other));
+}
+
 function statusProblem(outline: Outline): Violation | undefined {
-  const status = outline.sections.find(({ heading }) => heading.title === "Status");
+  const status = statusSection(outline);
   if (status === undefined) return undefined;
   const opening = firstText(status.body);
   const word = opening?.text.trim().split(/\s+/, 1)[0]?.replace(/[.,;:]+$/, "");
@@ -126,7 +195,7 @@ function sharedNumberProblem(path: string, filed: number | undefined, records: r
   return sharing.length === 0 ? undefined : { line: 1, message: `shares number ${filed} with ${sharing.join(", ")}` };
 }
 
-function adrProblems(path: string, outline: Outline, records: readonly string[]): readonly Violation[] {
+function adrProblems(path: string, outline: Outline, records: Records): readonly Violation[] {
   const filed = recordNumber(path);
   const misnamed: Violation | undefined =
     filed === undefined
@@ -137,7 +206,8 @@ function adrProblems(path: string, outline: Outline, records: readonly string[])
     recordTitleProblem(outline, filed),
     recordDateProblem(outline),
     statusProblem(outline),
-    sharedNumberProblem(path, filed, records),
+    sharedNumberProblem(path, filed, records.paths),
+    ...revisionLinkProblems(path, outline, records.links),
   ].filter((violation) => violation !== undefined);
 }
 
@@ -167,7 +237,7 @@ function stepsProblems(kind: Kind, { prose }: Outline): readonly Violation[] {
   return [{ line: 1, message: `numbers no steps, which a ${kind} page lists as \`1.\` items` }];
 }
 
-function kindProblems(kind: Kind, doc: Doc, outline: Outline, records: readonly string[]): readonly Violation[] {
+function kindProblems(kind: Kind, doc: Doc, outline: Outline, records: Records): readonly Violation[] {
   if (kind === "adr") return adrProblems(doc.path, outline, records);
   if (kind === "changelog") return changelogProblems(outline);
   if (kind === "how-to" || kind === "tutorial") return stepsProblems(kind, outline);
@@ -182,7 +252,7 @@ function exactProblems(kind: Kind, expected: string, actual: string): readonly V
   return [{ line, message: `differs from ${templateFile(kind)}, which it holds word for word` }];
 }
 
-export function judge(kind: Kind, doc: Doc, records: readonly string[]): readonly Violation[] {
+export function judge(kind: Kind, doc: Doc, records: Records): readonly Violation[] {
   const template = TEMPLATES[kind];
   if (template.shape === "exact") return exactProblems(kind, template.text, doc.text);
   const frontMatter = frontMatterOf(doc.text).text;

package/src/docs/doc-templates.ts

@@ -57,14 +57,6 @@ const BEFORE_YOU_BEGIN = fixed("Before you begin", REQUIRED, ["- <each prerequis
 
 const STEPS = ["To <do the task>:", "", "1. <step>", "1. <step>"];
 
-const MAINTAINING = [
-  "Keep this file for knowledge useful to almost every future agent session in this project.",
-  "Do not repeat what the codebase already shows.",
-  "Point to the authoritative file or command instead.",
-  "Prefer rewriting or pruning existing entries over appending new ones.",
-  "When updating this file, preserve this bar for all agents and keep entries concise.",
-];
-
 export const CHANGE_GROUPS = ["Breaking changes", "Features", "Fixes", "Performance", "Reverts"] as const;
 export type ChangeGroup = (typeof CHANGE_GROUPS)[number];
 
@@ -122,7 +114,6 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
       open("<A topic an agent needs>", "any", optional("the lead holds every constraint"), [
         "- <A constraint an agent cannot infer from the code, and the file that holds its detail.>",
       ]),
-      fixed("Maintaining this file", REQUIRED, MAINTAINING),
     ],
   },
   claude: {

package/src/docs/docs.ts

@@ -1,7 +1,8 @@
 #!/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, speaksToConsumers, type Placement } from "./doc-rules.ts";
+import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "./doc-agents.ts";
+import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
+import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
 import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
@@ -18,6 +19,7 @@ type Judged = {
   readonly held: readonly string[];
   readonly edited: { readonly docs: number; readonly lines: number };
   readonly named: number;
+  readonly agents: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
   readonly brokenBefore: readonly Finding[];
@@ -38,7 +40,7 @@ const NAME = "docs";
 const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
 const MARKDOWN = [":(glob)**/*.md"];
 
-function templateFindings(path: string, text: string, placement: Placement, records: readonly string[]): readonly Finding[] {
+function templateFindings(path: string, text: string, placement: Placement, records: Records): readonly Finding[] {
   const misplaced = placementProblem(placement);
   if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
   if (placement.type !== "judged") return [];
@@ -89,13 +91,13 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   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 proseDocs = present.flatMap((path) => {
     const reader = readerOf(path);
     return reader === undefined ? [] : [{ path, reader }];
   });
   const texts = yield* readTexts(root, head, [...new Set([...present.filter((path) => path.endsWith(".md")), ...proseDocs.map(({ path }) => path)])]);
   const text = (path: string): string => texts.get(path) ?? "";
+  const records = recordsOf(present.filter((path) => path.startsWith(ADR_DIRECTORY)).map((path) => ({ path, text: text(path) })));
   const judged = present.map((path) => ({ path, placement: placementOf(path, text(path)) })).filter(({ placement }) => placement.type !== "unjudged");
 
   const templated = judged.flatMap(({ path, placement }) => templateFindings(path, text(path), placement, records));
@@ -109,13 +111,27 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const referenced = new Map(proseDocs.map(({ path }) => [path, text(path)]));
   const references = yield* referenceFindings({ root, base, head, roots, changed, renamedFrom }, referenced, judging);
   const vanished = yield* vanishedNames(root, base, head, referenced, references.failed);
+  const agents = proseDocs.filter(({ path }) => isAgentFile(path));
+  const tracked = snapshotOf(yield* pathsAt(head, [], root), new Map(), new Map());
+  const shapes = agents.flatMap(({ path }) =>
+    [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
+  );
+  const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
   const advisory = new Map<string, number>();
   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)),
     edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
     named: referenced.size,
-    findings: [...templated.filter((finding) => touched.has(finding.path)), ...prose, ...references.failing, ...vanished].toSorted(inPathOrder),
+    agents: agents.length,
+    findings: [
+      ...templated.filter((finding) => touched.has(finding.path)),
+      ...prose,
+      ...references.failing,
+      ...vanished,
+      ...shapes,
+      ...entries,
+    ].toSorted(inPathOrder),
     advisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
@@ -125,13 +141,14 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, findings, advisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, agents, findings, advisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
           `${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 ${named} living doc(s) or agent file(s) name`,
+          `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =

package/src/testing/mutation-guard-plugin.js

@@ -0,0 +1,13 @@
+import { missingReportRefusal } from "./mutation-scope.js";
+
+export const GUARD_IGNORER = "checks-incremental-report-guard";
+
+// An ignorer is built before instrumentation from the resolved options, so a throw here stops the run before any mutant.
+function incrementalReportGuard(options) {
+  const refusal = missingReportRefusal(process.argv.slice(3), process.env.CI ?? "", options.incrementalFile);
+  if (refusal !== undefined) throw new Error(refusal);
+  return { shouldIgnore: () => undefined };
+}
+incrementalReportGuard.inject = ["options"];
+
+export const strykerPlugins = [{ kind: "Ignore", name: GUARD_IGNORER, factory: incrementalReportGuard }];

package/src/testing/mutation-scope.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+
+const NON_RUNS = ["--help", "-h", "--version"];
+const MUTATE_FLAGS = ["--mutate", "-m"];
+
+function namesGlob(args) {
+  return args.some(
+    (arg, index) =>
+      (MUTATE_FLAGS.includes(arg) && (args[index + 1] ?? "") !== "") ||
+      (arg.startsWith("--mutate=") && arg !== "--mutate="),
+  );
+}
+
+function allowedAnyway(args, ci) {
+  return ci === "true" || args.some((arg) => NON_RUNS.includes(arg)) || namesGlob(args);
+}
+
+export function fullRunRefusal(args, ci) {
+  if (allowedAnyway(args, ci) || (args.includes("--incremental") && !args.includes("--force"))) return undefined;
+  return "refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`";
+}
+
+// Only the resolved options know the incrementalFile a consumer config sets, so this runs after config load.
+export function missingReportRefusal(args, ci, incrementalFile, reportExists = existsSync) {
+  if (allowedAnyway(args, ci) || reportExists(incrementalFile)) return undefined;
+  return `refusing a full mutation run outside CI: \`--incremental\` finds no report at ${incrementalFile} to reuse; scope this run with \`--mutate <glob>\`, or start the full baseline in CI with \`gh workflow run mutation\``;
+}

package/src/testing/mutation.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+import { Config, Effect, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { runMain } from "../core/main.ts";
+import { fullRunRefusal } from "./mutation-scope.js";
+
+export class MutationError extends Schema.TaggedError<MutationError>()("MutationError", {
+  message: Schema.String,
+}) {}
+
+const readCi = Config.String("CI").pipe(
+  Config.withDefault(""),
+  Effect.mapError((cause) => new MutationError({ message: `cannot read CI: ${cause.message}` })),
+);
+
+const runStryker = Effect.fn("runStryker")(function* (args: readonly string[]) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const exitCode = yield* spawner.exitCode(
+    ChildProcess.make(process.execPath, ["x", "stryker", "run", ...args], {
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+    }),
+  );
+  return exitCode === ChildProcessSpawner.ExitCode(0);
+});
+
+const mutation = Effect.gen(function* () {
+  const args = process.argv.slice(2);
+  const refusal = fullRunRefusal(args, yield* readCi);
+  if (refusal !== undefined) return yield* new MutationError({ message: refusal });
+  return yield* runStryker(args);
+});
+
+if (import.meta.main) runMain("checks-mutation", mutation);

package/src/testing/test.ts

@@ -118,7 +118,13 @@ const runSuite = Effect.fn("runSuite")(function* (outfile: string, tier: TestTie
   const tierArgs = tier === undefined ? [] : ["--path-ignore-patterns", "", `./tests/${tier}`];
   const args = ["test", "--randomize", ...tierArgs, ...reporterArgs(outfile)];
   return yield* spawner.exitCode(
-    ChildProcess.make(process.execPath, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }),
+    ChildProcess.make(process.execPath, args, {
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { CI: "true" },
+      extendEnv: true,
+    }),
   );
 });
 

package/stryker.preset.js

@@ -1,6 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { GUARD_IGNORER } from "./src/testing/mutation-guard-plugin.js";
+import { fullRunRefusal } from "./src/testing/mutation-scope.js";
+
+const [, , command, ...args] = process.argv;
+const refusal = command === "run" ? fullRunRefusal(args, process.env.CI ?? "") : undefined;
+if (refusal !== undefined) throw new Error(refusal);
+
 export default {
   packageManager: "npm",
-  plugins: ["@stryker-mutator/*", "@hughescr/stryker-bun-runner"],
+  plugins: [
+    "@stryker-mutator/*",
+    "@hughescr/stryker-bun-runner",
+    fileURLToPath(new URL("./src/testing/mutation-guard-plugin.js", import.meta.url)),
+  ],
+  ignorers: [GUARD_IGNORER],
   testRunner: "bun",
   bun: { timeout: 60000 },
   inPlace: true,