@avi2dg/checks 0.25.0 → 0.27.0

package/docs/gates/checks-docs.md

@@ -4,35 +4,40 @@ 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.
-The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
+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
-cp node_modules/@avi2dg/checks/templates/how-to.md docs/add-a-supplier.md
+cp node_modules/@avi2dg/checks/dist/templates/how-to.md docs/add-a-supplier.md
 ```
 
+A host resolves a template as `@avi2dg/checks/templates/how-to.md`, which keeps pointing at it wherever the package holds the templates.
+
 <!-- generated doc-kinds: bun run build writes it from src/docs/doc-rules.ts, src/docs/doc-templates.ts and scripts/doc-blocks.ts -->
 
 | File | Kind | Template |
 | --- | --- | --- |
-| `README.md` | readme | `templates/readme.md` |
-| `CHANGELOG.md` | changelog | `templates/changelog.md` |
-| `AGENTS.md` | agents | `templates/agents.md` |
-| `CLAUDE.md` | claude | `templates/claude.md` |
-| `CONTRIBUTING.md` | how-to | `templates/how-to.md` |
-| each file in `docs/adr/` but its generated index, `README.md` | adr | `templates/adr.md` |
-| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+| `README.md` | readme | `dist/templates/readme.md` |
+| `CHANGELOG.md` | changelog | `dist/templates/changelog.md` |
+| `AGENTS.md` | agents | `dist/templates/agents.md` |
+| `CLAUDE.md` | claude | `dist/templates/claude.md` |
+| `CONTRIBUTING.md` | how-to | `dist/templates/how-to.md` |
+| each file in `docs/adr/` but its generated index, `README.md` | adr | `dist/templates/adr.md` |
+| a page with `kind` in front matter | tutorial, how-to, reference or explanation | `dist/templates/<mode>.md` |
 
 <!-- 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
@@ -41,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 -->
 
@@ -87,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 |
@@ -94,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
 ---
@@ -125,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
 
@@ -145,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

@@ -0,0 +1,104 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-exports
+
+`checks-exports` is the gate that refuses an exported value or type nothing imports.
+
+## What it checks
+
+It runs Knip with the repository's own configuration and names each exported value and type no file imports.
+It reads only the exports and types issue types, so an unreferenced file or an unused dependency never fails it.
+It asks Knip for those issue types itself, so a configuration that narrows `include` or excludes them still has its exports judged.
+A configuration that turns the exports or types rules off silences those symbols, so keep both rules on.
+It holds each reported symbol against `exports-baseline.json`, and fails on any symbol the baseline does not hold.
+It fails on any baseline entry the range adds unless Knip reports that same symbol unused at the base, so the baseline records debt that already existed and never debt the range creates.
+It fails on any baseline entry Knip no longer reports, so the baseline only shrinks.
+It fails when the repository tracks no TypeScript source, since an empty scan would pass without judging anything.
+It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead export from a public one.
+
+## What it reads
+
+It runs Knip over the working tree, so an uncommitted file is judged like a committed one.
+It reads the repository's Knip configuration, which names the entries.
+It reads `exports-baseline.json` in the repository root, which holds each accepted unused export as a file, kind and name triple.
+It reads `exports-baseline.json` again at the base of the range, where a commit without the file counts as empty.
+When the range adds baseline entries, it runs Knip again on a temporary checkout of the base and removes the checkout when it ends.
+That checkout links the repository's `node_modules`, so a configuration importing the kit's base loads there too.
+Knip configurations do not extend a package file, so the consumer configuration imports the kit's base and spreads it:
+
+```ts
+import base from "@avi2dg/checks/knip-base.json";
+
+export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
+```
+
+The base in `knip-base.json` reports only unreferenced files.
+The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
+
+## Arguments
+
+```sh
+checks-exports <base-ref> <head-ref>
+checks-exports <ref>
+checks-exports --write
+```
+
+With two arguments the base is where the head branched off, at their merge-base.
+When the checked-out commit is a merge of the head ref and one other commit, as a pull request's default checkout is, the base is that other commit instead.
+So under `checks-lint` a pull request's merge checkout is judged against the base branch tip it merges, and a symbol that branch already baselined does not count as added.
+With one the base is that commit's parent, or the empty tree for a repository's first commit, where nothing counts as already unused.
+With `--write` it records every unused export and type Knip reports into `exports-baseline.json`, the way `oxlint --suppress-all` seeds `oxlint-suppressions.json`.
+
+## Seeding a baseline
+
+A repository adopting the gate runs `checks-exports --write` on a branch that changes no source and commits the file it writes.
+The gate passes that range, since Knip reports every seeded symbol unused at the base too.
+A seed written after the range adds a dead export, or after it removes the last import of one, fails on that symbol.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no reported symbol is unlisted, no baseline entry is added or stale, or `--write` recorded the baseline |
+| 1 | a reported symbol is unlisted, a baseline entry is added or stale or the repository holds no Knip configuration |
+| 2 | a ref does not resolve, the repository tracks no TypeScript source, Knip cannot run, or a report or baseline does not parse |
+
+## Sample output
+
+```
+exports: 2 unused export(s) not in exports-baseline.json:
+  src/used.ts: unusedExport (export)
+  src/used.ts: UnusedOptions (type)
+```
+
+A baseline entry the range adds fails when Knip does not report its symbol unused at the base:
+
+```
+exports: 1 exports-baseline.json export(s) the range adds that its base did not leave unused, remove the export instead:
+  src/used.ts: unusedExport (export)
+```
+
+A passing run with a held baseline counts what it holds:
+
+```
+exports: 2 unused export(s) in exports-baseline.json, and no new ones
+```
+
+A passing run with an empty baseline says so:
+
+```
+exports: no unused exports or types
+```
+
+## When it runs
+
+`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
+
+- [checks-lint](checks-lint.md)
+- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
+- [checks-unused](checks-unused.md)

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

@@ -40,15 +40,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 11 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