@avi2dg/checks 0.26.0 → 0.28.0

package/docs/gates/checks-ci-wiring.md

@@ -49,9 +49,9 @@ ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
     no run step invokes it
 ```
 
-## Opting out
+## When it runs
 
-Every repository runs this gate through `checks-lint`.
+`checks-lint` runs it in every repository.
 
 ## Related topics
 

package/docs/gates/checks-comment-gate.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-comment-gate
 
-`checks-comment-gate` is the gate that refuses a banned comment on a line a change adds, and a reader looks it up to learn which comments it refuses.
+`checks-comment-gate` is the gate that refuses a banned comment on a line a change adds.
 
 ## What it checks
 
@@ -53,10 +53,9 @@ comment-gate: 2 violation(s):
   src/a.ts:2 carries the machine-read directive `eslint-disable-next-line`. Fix what the tool is reporting, or stop running the tool on this file
 ```
 
-## Opting out
+## When it runs
 
-It applies to every repository, so no selection leaves it out.
-`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+`checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 
 ## Related topics
 

package/docs/gates/checks-commit-identity.md

@@ -48,10 +48,10 @@ commit-identity: 1 of 1 commit(s) in HEAD carry a foreign identity:
   allowed: avi2d <avi2dg@gmail.com>
 ```
 
-## Opting out
+## When it runs
 
-This gate runs on every repository through `checks-lint`.
-The repository adds owners through `package.json` rather than omitting the gate.
+`checks-lint` runs it over each pull request's range in every repository.
+A repository allows another author by adding them to `author` or `contributors` in `package.json`.
 
 ## Related topics
 

package/docs/gates/checks-docs.md

@@ -4,13 +4,17 @@ audience: consumers
 ---
 # checks-docs
 
-`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.
+`checks-docs` is the gate that holds a repository's doc files to the kit's templates and prose rules.
+It also fails when a doc names a file, a heading or a script that does not exist, or a name the range removed from every file outside the docs.
 
 ## 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 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 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.
+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 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:
 
 ```sh
@@ -33,8 +37,7 @@ A host resolves a template as `@avi2dg/checks/templates/how-to.md`, which keeps
 
 <!-- end generated doc-kinds -->
 
-A file the table names on its own, such as `README.md`, sits at the repository root.
-No other Markdown file is judged, save a page under `docs/`, which needs a mode.
+Each file the table names by name sits at the repository root.
 A page under `docs/` declares its mode in front matter:
 
 ```yaml
@@ -43,24 +46,28 @@ kind: tutorial
 ---
 ```
 
-A template decides a file's structure, and the template file itself is the reference for each kind:
+No other Markdown file is held to a template.
+A template decides a file's structure, and the template file itself is the reference for its kind:
 
 - A file opens with one `# ` title on its first line and has text before its first section.
   It skips no heading level, and no heading is Overview, Introduction or How it works.
-- Its sections are the template's headings in the template's order.
+- Its sections are the template's headings, in the template's order.
   A heading in angle brackets is one the writer names.
-  One marked verb first is left to review, since no program tells a verb from a noun there.
-  A heading the template does not have, in that place, is refused.
+  A heading the template marks verb first is left to review, because no program tells a verb from a noun.
+  A heading the template does not have in that place is refused.
 - A record in `docs/adr/` is named for its four-digit number, and its title opens with the same number.
-  A `Date: YYYY-MM-DD` line follows the title, the first word under Status is Proposed, Accepted, Rejected, Deprecated, Superseded or Retired, and no other record holds its number.
-- A changelog lists its releases newest first, each opening with a `Released YYYY-MM-DD.` line.
+  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 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.
-  It is a fixed agent pointer rather than a living doc, so it takes only the prose rules for agent files.
+  It is a fixed pointer to `AGENTS.md` 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.
+The prose rules judge each line a change adds or edits in a living doc or an agent file.
+A line the change leaves alone is not judged, so a repository needs no cleanup pass before it runs them.
 
 <!-- generated living-docs: bun run build writes it from src/docs/prose-matchers.ts and scripts/doc-blocks.ts -->
 
@@ -89,6 +96,7 @@ These are records, and take no prose rule:
 | 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 report about the past | `formerly`, `previously`, `as before`, `used to`, `was replaced`, `moved from`, `new owner` | Say what is true now, and leave what changed to the changelog, a commit message or a decision record | yes |
 | 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 |
@@ -96,27 +104,36 @@ These are records, and take no prose rule:
 <!-- 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.
+A bold label that opens a line, as in `**Status.**`, heads the sentence after it and is not a sentence of its own.
+No rule reads fenced code, inline code, link destinations, URLs, HTML comments or front matter.
 Readability scores and word choice, such as easy, are not checked.
 
 `src/docs/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.
+The package exports it as `@avi2dg/checks/scripts/prose-matchers.ts`.
+A host such as a write-time hook can copy that one file into a directory with no `node_modules`, and refuse the same lines.
 
 ## Paths, links and commands
 
-Each reference a living doc names has to resolve at the head commit:
+Each reference a living doc or an agent file names has to resolve at the head commit:
 
 - A path in inline code that ends in a file extension, such as `src/core/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 relative Markdown link names a file or a directory.
+  Its anchor names a heading in that file, 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 code span fails when some tracked file outside the docs held that exact text at the base, and none holds it at the head.
+  A span the path check already fails on is not reported again.
+  A name an installed direct dependency still holds counts as present.
+  A span with a space, a placeholder or a leading dash names a command or a flag, and is skipped.
+  A span that opens with the repository's own package name and a slash, `node_modules/`, `./` or `~/` reads as the file it names.
 
 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.
+On any other line, it fails when the range broke it, for example by deleting the file it names or renaming the heading it links.
+A reference that was broken before the range is listed as advisory.
+A path whose top directory the repository lacks at both ends of the range names another repository's file, such as a consumer's, and is skipped.
+A path git ignores is skipped too, because a clean checkout lacks a generated file by design.
 
-A living doc that speaks to a consuming repository sets `audience: consumers` in its front matter, so no `bun run` command it names is held to a `package.json`:
+A page that speaks to a consuming repository sets `audience: consumers` in its front matter.
+No `bun run` command on such a page is looked up in a `package.json`:
 
 ```yaml
 ---
@@ -127,11 +144,14 @@ audience: consumers
 
 ## What it reads
 
-It reads each Markdown file from the head commit and uses its path or front matter to choose a mode.
+It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
 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 and the `scripts` of each `package.json` a living doc sits under.
-From the working tree it reads the ignore files git reads, and `node_modules/.bin`.
+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.
+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`.
 
 ## Arguments
 
@@ -147,31 +167,31 @@ 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, 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 | a `package.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, 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 |
+| 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
 
 ```
-docs: 4 violation(s):
+docs: 6 violation(s):
   README.md:1: lacks `## Where things are`
   README.md:12: carries `;`, a semicolon. Use two sentences
+  README.md:14: carries `former`, a report about the past. Say what is true now, and leave what changed to the changelog, a commit message or a decision record
   README.md:20: names `scripts/bild.ts`, which is not in the repository
   docs/parts.md: is a page under docs/ with no mode; add kind: tutorial, how-to, reference, explanation in YAML front matter
+  docs/parts.md:9: names `gates.lint`, which the range removed from every file outside the docs. Say what holds now, or drop the line
 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: advisory, 1 path(s), link(s) or command(s) the living docs or agent files 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
+## When it runs
 
-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 living doc with `audience: consumers` in its front matter holds no `bun run` command to a `package.json`.
-`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+`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.
+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-exports.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-exports
 
-`checks-exports` is the gate that refuses an exported value or type nothing imports, and a reader looks it up when Knip names a symbol no file reaches.
+`checks-exports` is the gate that refuses an exported value or type nothing imports.
 
 ## What it checks
 
@@ -92,10 +92,10 @@ A passing run with an empty baseline says so:
 exports: no unused exports or types
 ```
 
-## Opting out
+## When it runs
 
-`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
-A repository that tracks one names its entries in a Knip configuration.
+`checks-lint` runs it over each pull request's range when the repository tracks a `.ts` or `.tsx` file.
+Such a repository names its entries in a Knip configuration.
 
 ## Related topics
 

package/docs/gates/checks-flake.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-flake
 
-`checks-flake` is the scheduled run that finds flaky tests and records the seeds each one fails with, and a reader looks it up to reproduce a flaky failure.
+`checks-flake` is the scheduled run that finds flaky tests and records the seeds each one fails with.
 
 ## What it checks
 
@@ -48,9 +48,9 @@ checks-flake: 3 of 10 run(s) failed, 1 test(s) failing in them
 Reproduce a failing run with bun test --randomize --seed=<seed>.
 ```
 
-## Opting out
+## When it runs
 
-Nothing runs it but a schedule the repository writes.
+Only a schedule the repository writes runs it.
 
 ## Running it on a schedule
 

package/docs/gates/checks-lint-coverage.md

@@ -4,18 +4,23 @@ audience: consumers
 ---
 # checks-lint-coverage
 
-`checks-lint-coverage` is the gate that fails when oxlint silently skips a tracked TypeScript file, and a reader looks it up when a file seems never to be linted.
+`checks-lint-coverage` is the gate that fails when oxlint skips a tracked TypeScript file, or when the program `tsconfig.json` builds drops the ts-reset rules, without saying so.
 
 ## What it checks
 
 It fails when oxlint skips a tracked `.ts` or `.tsx` file, for example through a stray `.gitignore` entry.
 It compares `git ls-files` against oxlint's own file walk and names the missing files.
 
+It fails when the program `tsconfig.json` builds leaves out the `is-array` or the `json-parse` rule of `@total-typescript/ts-reset`, which `tsconfig.effect.json` lists.
+A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or that sets both `files` and `include`, leaves both rules out.
+[The TypeScript rules](../configs/typescript-rules.md) says what the two rules refuse.
+
 ## What it reads
 
 It reads the working tree: the `*.ts` and `*.tsx` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
 It walks without naming a path, since an explicit path bypasses the ignore files whose skips it looks for.
-oxlint must be on `PATH`, as it is under a package script.
+It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the root holds no `tsconfig.json`.
+oxlint and tsc must be on `PATH`, as they are under a package script.
 
 ## Arguments
 
@@ -25,29 +30,32 @@ It takes none.
 
 | Code | When |
 | --- | --- |
-| 0 | oxlint walks every tracked `.ts` and `.tsx` file, or the repository tracks none |
-| 1 | oxlint skips a tracked file |
-| 2 | oxlint cannot walk the tree, as when it is not on `PATH` or its config does not parse |
+| 0 | the repository tracks no `.ts` or `.tsx` file, or oxlint walks each one and the program holds both ts-reset rules or the root holds no `tsconfig.json` |
+| 1 | oxlint skips a tracked file, or the program drops a ts-reset rule |
+| 2 | oxlint cannot walk the tree, or tsc cannot list the program after oxlint walks every tracked file, as when either is not on `PATH` or a config does not parse |
 
 ## Sample output
 
 ```
 lint-coverage: oxlint skips 1/3 tracked .ts/.tsx files; missing:
 ignored/b.ts
+lint-coverage: the program tsconfig.json builds drops the ts-reset rules: is-array json-parse
+  extend @avi2dg/checks/tsconfig.effect.json, and set files or include in tsconfig.json but not both
 ```
 
-A passing run counts the files:
+A passing run counts the files and names the rules:
 
 ```
 lint-coverage: 71/71 tracked .ts/.tsx files
+lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-array and json-parse
 ```
 
-## Opting out
+## When it runs
 
-`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
-A repository that tracks one keeps it.
+`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file.
 
 ## Related topics
 
 - [checks-lint](checks-lint.md)
 - [The Effect rules](../configs/effect-rules.md)
+- [The TypeScript rules](../configs/typescript-rules.md)

package/docs/gates/checks-lint.md

@@ -10,6 +10,7 @@ audience: consumers
 
 It runs the gates under [What runs](../../README.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+`checks-advisories` begins running when the repository tracks `bun.lock`.
 All other gates run for every repository.
 
 ## What it reads
@@ -40,15 +41,19 @@ With two arguments, the base and head override range discovery.
 
 ## Sample output
 
+<!-- generated lint-sample: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->
+
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 9 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
 ```
 
-## Opting out
+<!-- end generated lint-sample -->
+
+## When it runs
 
-A repository runs `checks-lint` in a pull request workflow with the full git history fetched.
-The gate automatically omits TypeScript gates when no TypeScript file is tracked.
+A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
+It leaves out the TypeScript gates while the repository tracks no TypeScript file.
 
 ## Related topics
 

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

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-mutation-compare
 
-`checks-mutation-compare` is the gate that holds every mutant in a pull request to no regression rather than an absolute score, and a reader looks it up to wire mutation testing into CI.
+`checks-mutation-compare` is the gate that fails a pull request when any mutant regresses, rather than judging an absolute score.
 
 ## What it checks
 
@@ -65,9 +65,9 @@ mutation-compare: REGRESSION (1 mutant(s))
   moved src/loader.ts:4:1 ClassDeclaration "class {}": Killed -> RuntimeError
 ```
 
-## Opting out
+## When it runs
 
-Nothing runs it but a CI step the repository writes.
+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.
 
 ## Running it in CI

package/docs/gates/checks-quarantine-clock.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-quarantine-clock
 
-`checks-quarantine-clock` is the gate that fails a test left in `tests/quarantine/` past 30 days, and a reader looks it up when a quarantined test went red.
+`checks-quarantine-clock` is the gate that fails a test left in `tests/quarantine/` past 30 days.
 
 ## What it checks
 
@@ -12,7 +12,6 @@ It fails naming each test that entered `tests/quarantine/` more than 30 days bef
 `checks-test-layout` pins `tests/quarantine/` out of every default run, so a test there protects nothing until it moves back.
 Each failure names the file, the day it entered quarantine, and what to do, which is to fix it and move it back, or delete it.
 The limit is 30 days for every test, with no setting to raise it.
-GitLab quarantines fast for 3 days and long term for at most 3 months, then opens a deletion merge request automatically.
 
 ## What it reads
 
@@ -46,11 +45,10 @@ quarantine-clock: 1 test(s) in tests/quarantine/ is past 30 days; fix each and m
   tests/quarantine/unit/billing.test.ts entered quarantine on 2026-08-01 (45 days ago)
 ```
 
-## Opting out
+## When it runs
 
-It applies to every repository, so no selection leaves it out.
+`checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository with no test file under `tests/quarantine/` passes with nothing checked.
-`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
 
 ## Related topics
 

package/docs/gates/checks-release-notes.md

@@ -95,7 +95,7 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
-A repository that never publishes to npm releases with this workflow instead, since only `checks` publishes a package:
+A repository that never publishes to npm releases with this workflow instead:
 
 ```yaml
 name: release
@@ -130,10 +130,10 @@ jobs:
 Cut a release by merging a pull request that holds only the version bump and the built changelog, then tagging the merge commit on the target branch and pushing the tag.
 The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
 
-## Opting out
+## When it runs
 
-Nothing runs it but the release workflow of a repository that publishes GitHub releases.
-A repository with no versioned releases leaves it out.
+Only the release workflow of a repository that publishes GitHub releases runs it.
+A repository with no versioned releases does not need it.
 
 ## Related topics
 

package/docs/gates/checks-release-report.md

@@ -53,10 +53,10 @@ A history with nothing to release prints one line:
 release-report: no unreleased changes since v0.1.0
 ```
 
-## Opting out
+## When it runs
 
-Nothing runs it but a person or a scheduler deciding when to cut a release.
-A repository with no versioned releases leaves it out.
+Only a person or a scheduler deciding when to cut a release runs it.
+A repository with no versioned releases does not need it.
 
 ## Related topics
 

package/docs/gates/checks-repetition.md

@@ -48,8 +48,9 @@ repetition: 1 file(s) .jscpd.json holds repeat more lines than where the range s
   src/copy.ts: 10 repeated line(s), up from 0
 ```
 
-## Opting out
+## When it runs
 
+`checks-lint` runs it over each pull request's range when the repository tracks a `.ts` or `.tsx` file.
 When the head holds no `.jscpd.json`, the gate reports that no file was measured.
 
 ## Related topics

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

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-subsumed-tests
 
-`checks-subsumed-tests` is the report that lists each test another test subsumes in a Stryker mutation run, and a reader looks it up to judge whether the suite carries tests it no longer needs.
+`checks-subsumed-tests` is the report that lists each test in a Stryker mutation run that one other test subsumes, by killing every mutant it kills.
 
 ## What it checks
 
@@ -63,9 +63,9 @@ greedy cover: 3 of 6 test(s) keep all 6 kill(s)
   cover "tests/mul.test.ts > mul checks its guard"
 ```
 
-## Opting out
+## When it runs
 
-Nothing runs it but a person who wants the figures.
+Only a person who wants the figures runs it.
 
 ## Related topics
 

package/docs/gates/checks-suppressions-ratchet.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-suppressions-ratchet
 
-`checks-suppressions-ratchet` is the gate that holds oxlint's bulk-suppression baseline to counts that only fall, and a reader looks it up when a change raised a count.
+`checks-suppressions-ratchet` is the gate that fails when a change raises a count in `oxlint-suppressions.json`.
 
 ## What it checks
 
@@ -43,11 +43,10 @@ suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; f
   src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
 ```
 
-## Opting out
+## When it runs
 
-It applies to every repository, so no selection leaves it out.
+`checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository with no `oxlint-suppressions.json` passes, since both ends count as empty.
-`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
 
 ## Related topics
 

package/docs/gates/checks-test-layout.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-test-layout
 
-`checks-test-layout` is the gate that holds a repository's tests to one layout, and a reader looks it up to learn where a test file goes and what it may import.
+`checks-test-layout` is the gate that holds a repository's tests to one layout, which says where a test file goes and what it may import.
 
 ## What it checks
 
@@ -83,10 +83,10 @@ test-layout: 4 violation(s)
   bunfig.toml: bunfig.toml is missing; bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml
 ```
 
-## Opting out
+## When it runs
 
-`checks-lint` runs this gate when the repository tracks TypeScript, so a repository without TypeScript needs neither the test script nor bunfig.
-A repository that tracks one keeps it.
+`checks-lint` runs it when the repository tracks TypeScript.
+A repository without TypeScript needs neither the `checks-test` script nor `bunfig.toml`.
 
 ## Related topics
 

package/docs/gates/checks-test.md

@@ -96,9 +96,10 @@ A run with no skipped tests ends with:
 checks-test: no test skipped
 ```
 
-## Opting out
+## When it runs
 
-A repository that tracks no TypeScript source does not need `checks-test`, as [checks-test-layout](checks-test-layout.md) says.
+The repository's `test` script runs it.
+A repository that tracks no TypeScript source does not need it, as [checks-test-layout](checks-test-layout.md) says.
 
 ## Related topics
 

package/docs/gates/checks-unused.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-unused
 
-`checks-unused` is the gate that refuses a TypeScript file no entry point reaches, and a reader looks it up when a file seems dead but every other check passes.
+`checks-unused` is the gate that refuses a TypeScript file no entry point reaches.
 
 ## What it checks
 
@@ -54,10 +54,10 @@ A passing run counts the files it judged:
 unused: no unreferenced files among 110 tracked .ts/.tsx file(s)
 ```
 
-## Opting out
+## When it runs
 
-`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
-A repository that tracks one names its entries in a Knip configuration.
+`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file.
+Such a repository names its entries in a Knip configuration.
 
 ## Related topics
 

package/docs/gates/checks-vendor.md

@@ -102,10 +102,10 @@ A consumer whose `tsconfig.json` has no explicit `include` keeps the trees out w
 { "exclude": ["node_modules", "repos"] }
 ```
 
-## Opting out
+## When it runs
 
-It pins sources only for the libraries its arguments name.
-A run with no arguments reports nothing to pin and changes nothing.
+The repository's `prepare` script runs it, as [Wiring](#wiring) shows.
+It pins only the libraries its arguments name, and a run with no arguments changes nothing.
 A repository that pins no library needs no `prepare` entry for it.
 
 ## Related topics