@avi2dg/checks 0.13.0 → 0.15.0

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

@@ -0,0 +1,63 @@
+# checks-commit-identity
+
+`checks-commit-identity` is the gate that refuses a commit carrying an identity other than the repository owner's, and a reader looks it up to allow another author.
+
+## What it checks
+
+It walks every commit in a range and fails when one carries an identity outside the allowlist, naming the offending commit and the reason.
+It refuses a commit whose author or committer is outside the allowlist.
+It refuses a commit whose trailer block carries a `Co-authored-by:` trailer, as git parses it.
+Other trailers, and prose in the body that mentions an address, are left alone.
+`GitHub <noreply@github.com>` is allowed as committer only, since that is who writes a squash merge.
+
+## What it reads
+
+It reads the author, the committer and the trailers of each commit in the range, and `commitIdentity.authors` from `quality.json`.
+The allowlist is `avi2d <avi2dg@gmail.com>` when `quality.json` declares none.
+
+## Arguments
+
+```sh
+checks-commit-identity <base-ref> <head-ref>
+checks-commit-identity <ref>
+```
+
+With two arguments it checks every commit the head holds and the base does not.
+With one it checks that commit alone.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every commit carries only allowed identities |
+| 1 | a commit carries a foreign identity |
+| 2 | a ref does not resolve, the arguments do not parse, or `quality.json` does not decode |
+
+## Sample output
+
+```
+commit-identity: 1 of 1 commit(s) in HEAD carry a foreign identity:
+  79fa94f9f027 feat: foreign
+    author someone <someone@example.com>
+    committer someone <someone@example.com>
+  allowed: avi2d <avi2dg@gmail.com>
+  allowed as committer only: GitHub <noreply@github.com>
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+A repository with other owners restates the allowlist in `quality.json`:
+
+```json
+"commitIdentity": {
+  "authors": [{ "name": "avi2d", "email": "avi2dg@gmail.com" }]
+}
+```
+
+`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+
+## Related topics
+
+- [The commit message lint](../configs/commit-messages.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-docs.md

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

package/docs/gates/checks-feature-owners.md

@@ -0,0 +1,113 @@
+# checks-feature-owners
+
+`checks-feature-owners` is the gate that holds each declared feature to a runnable proof and lists the feature owners a change touches, and a reader looks it up to declare a feature.
+
+## What it checks
+
+A repository opts a feature in by declaring, in `quality.json`, the directory it owns, the files code outside it imports it through, the files that may reach past those, and the end-to-end test that proves it runs:
+
+```json
+"features": [
+  {
+    "name": "billing",
+    "root": "src/billing",
+    "entries": ["src/billing/index.ts"],
+    "allowFrom": ["src/main.ts", "src/cli/*.ts"],
+    "proof": "tests/e2e/billing.test.ts"
+  }
+],
+"changeSignal": "advisory"
+```
+
+`root` is a directory and `entries` are files under it, both without globs.
+`allowFrom` holds globs of the same shape as `sources`.
+`proof` is a `.test.ts` or `.test.tsx` file under `tests/e2e/`.
+Nothing moves, since a root is wherever the feature already lives.
+`quality.json` refuses an entry outside its root, a name used twice, and two features sharing a root or one root inside another, so a file has at most one owner.
+
+The gate fails when a feature's proof cannot prove it:
+
+- the proof or an entry is not in the head commit
+- the proof does not parse
+- the proof imports none of the feature's entries
+
+An import counts when it is a runtime `import`, `export ... from` or `export * from` of a relative path that names an entry.
+It names the entry by its own name, by the `.js`, `.jsx`, `.mjs` or `.cjs` spelling of it, or without an extension, the way a directory `index` is imported.
+`.js` names a `.tsx` entry as well as a `.ts` one.
+`import type` does not count, and neither does a path alias.
+The proof runs in `bun run test` like any end-to-end test, which is what shows it passes.
+
+With `changeSignal` set to `advisory` it also lists each owner the range touches, with the paths it touched under the owner's root or at its proof, and still passes.
+Whether a change that spans owners is one coherent slice is for a reviewer to judge.
+A rename counts at both of its paths.
+
+## What it reads
+
+It reads `features` and `changeSignal` from `quality.json`, each proof and entry from the head commit, and the paths the range touches.
+
+## Arguments
+
+```sh
+checks-feature-owners <base-ref> <head-ref>
+checks-feature-owners <ref>
+```
+
+With two arguments the range starts where the head branched from the base, at their merge-base.
+With one it is that commit against its parent, or against the empty tree for a repository's first commit.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every feature's proof imports one of its entries |
+| 1 | a feature's proof cannot prove it |
+| 2 | `quality.json` does not decode, which is where a proof outside `tests/e2e/` is refused, or a ref does not resolve |
+
+## Sample output
+
+```
+feature-owners: 1 problem(s) with the features' runnable proofs:
+  billing: proof tests/e2e/billing.test.ts imports none of its entries, src/billing/index.ts
+```
+
+With `changeSignal` set to `advisory`:
+
+```
+feature-owners: advisory, the range touches 2 feature owner(s); a reviewer judges whether they make one slice:
+  billing: src/billing/charge.ts, src/billing/tax.ts
+  invoices: src/invoices/tax.ts, tests/e2e/invoices.test.ts
+```
+
+## Opting out
+
+A repository that declares no feature passes.
+`quality.json` refuses a `changeSignal` without features, which would map a change to no owner.
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+
+## Import boundary
+
+`dist/feature-rules.js` compiles `features` into one dependency-cruiser rule per feature, which `.dependency-cruiser.cjs` spreads beside its own:
+
+```js
+const { featureRules } = require("@avi2dg/checks/dist/feature-rules.js");
+
+module.exports = {
+  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
+  forbidden: [...featureRules(require("./quality.json"))],
+};
+```
+
+A module outside a feature's root that imports a file inside it must import one of the feature's `entries`.
+Modules under `tests/` and the files `allowFrom` matches, such as a CLI or a harness, may import any file in it:
+
+```
+error feature-billing-entries: src/report.ts → src/billing/charge.ts
+```
+
+`featureRules` decodes its argument with the schema the bins use and throws the schema's refusal when it does not decode, which stops the cruise.
+It is an ES module, as `effect` is, so a `.cjs` config loads it through `require`, which needs node 20.19, 22.12 or later.
+
+## Related topics
+
+- [The dependency rules](../configs/dependency-rules.md)
+- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-flake.md

@@ -0,0 +1,88 @@
+# 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.
+
+## What it checks
+
+A green run proves nothing failed in that run, not that no test is flaky.
+`checks-flake` runs the whole suite several times, each with its own `--seed`, and records per failing test the seeds it failed with.
+`bun test --randomize --seed=<seed>` puts the suite in the same order, so a seed reproduces a failure that hangs on order.
+A run that fails with no failing test, such as a test file that throws while loading, is listed with its seed on its own line.
+
+## What it reads
+
+It reads bun's JUnit report of each run.
+Under GitHub Actions it appends its summary to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.
+
+## Arguments
+
+```sh
+checks-flake [--runs <count> | --seed <seed>...] [--report <file>]
+```
+
+`--runs` sets the number of runs on random seeds, 10 when absent.
+`--seed`, given once per run, replays chosen seeds, such as the ones a report recorded.
+`--report` writes the record as JSON, holding every run's seed and failing tests and every failing test's seeds.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every run passed |
+| 1 | a run failed |
+| 2 | an argument does not parse, or bun passed without writing its report |
+
+## Sample output
+
+```
+checks-flake: 3 of 10 run(s) failed, 1 test(s) failing in them
+
+| Test | Failed | Seeds |
+| --- | --- | --- |
+| tests/cache.test.ts:6 reads the cache | 3 of 10 runs | 2170533150, 4046124386, 180394251 |
+
+Reproduce a failing run with bun test --randomize --seed=<seed>.
+```
+
+## Opting out
+
+Nothing runs it but a schedule the repository writes.
+A repository that stops scheduling it also drops it from `gates.scheduled`, which `checks-ci-wiring` otherwise fails on.
+
+## Running it on a schedule
+
+A repository runs it on a schedule and keeps the record as an artifact:
+
+```yaml
+on:
+  schedule:
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+jobs:
+  flake:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx checks-flake --runs 10 --report flake-report.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: flake-report
+          path: flake-report.json
+```
+
+It declares the step in `gates.scheduled`, so `checks-ci-wiring` fails once the schedule stops running it:
+
+```json
+"gates": {
+  "ci": ["bun run lint", "bun run typecheck", "bun run test"],
+  "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
+}
+```
+
+## Related topics
+
+- [checks-test](checks-test.md)
+- [checks-ci-wiring](checks-ci-wiring.md)

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

@@ -0,0 +1,49 @@
+# 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.
+
+## 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.
+
+## 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.
+
+## Arguments
+
+It takes none.
+
+## Exit codes
+
+| 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 |
+
+## Sample output
+
+```
+lint-coverage: oxlint skips 1/3 tracked .ts/.tsx files; missing:
+ignored/b.ts
+```
+
+A passing run counts the files:
+
+```
+lint-coverage: 71/71 tracked .ts/.tsx files
+```
+
+## Opting out
+
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+A repository that tracks one keeps it.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [The Effect rules](../configs/effect-rules.md)

package/docs/gates/checks-lint.md

@@ -0,0 +1,136 @@
+# checks-lint
+
+`checks-lint` is the entry point that runs every lint gate of the kit over one range, and a reader looks it up to learn which range it resolves and how a repository selects its gates.
+
+## What it checks
+
+It runs each gate the table under [What runs](../../README.md#what-runs) lists, in that table's order, and names every one that fails rather than stopping at the first.
+Each gate runs as its own bin in a child process, with its output passed straight through, so a gate behaves the same called alone or through `checks-lint`.
+`checks-ci-wiring` always runs, so a repository on `checks-lint` declares `gates.ci`, as [checks-ci-wiring](checks-ci-wiring.md) says.
+It holds the test layout unless the selection leaves out `checks-test-layout`.
+
+## What it reads
+
+It reads `quality.json` for `defaultBranch` and `gates.lint`, and resolves the range once, handing the same one to every range gate.
+A tree gate reads the working tree and is handed no range.
+
+Locally, and on any event other than a pull request, the range ends at `HEAD` and starts where `HEAD` branched from the origin default branch.
+That branch is `origin/HEAD`.
+When `origin/HEAD` is not set, as in an `actions/checkout` clone, it is `origin/<defaultBranch>` from `quality.json`, and `origin/main` when that is not declared.
+
+In a GitHub Actions pull request, where `GITHUB_EVENT_NAME` is `pull_request`, the range ends at the event's head sha and starts where that branched from `origin/<base branch>`, so GitHub's merge commit is never in it.
+The base branch is read from the fetch, not from the event's recorded base sha, which GitHub leaves stale once the base branch advances after the pull request opens.
+
+The range always starts at the merge base, never at the base branch's tip, since commits the base branch gained after the head branched off would otherwise count against the head.
+When the head is the merge base, as on a push to the default branch or a local run on it, the range would be empty.
+Each range gate is then handed that tip commit alone, and checks it against its parent, or against the empty tree when it is a repository's first commit:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+```
+
+A clone with no remote-tracking refs at all has no default branch to start from, such as a freshly initialised repository with no remote or one whose remote was never fetched.
+Each range gate is then handed `HEAD` alone the same way:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD alone, as the clone has no remote-tracking refs
+```
+
+Once any ref sits under `refs/remotes/`, a missing `origin/<default branch>` exits 2 instead.
+That is the shape of a shallow CI checkout, where `HEAD` alone would leave the commits before it unchecked.
+
+## Arguments
+
+```sh
+checks-lint
+checks-lint <base-ref> <head-ref>
+```
+
+With no arguments it resolves the range as What it reads says.
+A base and a head override that resolution.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every gate passed |
+| 1 | a gate found a violation |
+| 2 | the range or the selection does not resolve, or no failing gate could decide |
+
+## Sample output
+
+It prints the range, the declared selection if there is one, each gate's own report, then its verdict:
+
+```
+checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+...
+checks-lint: 3 of 10 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+```
+
+## Opting out
+
+A repository leaves out a gate that does not apply to it, as Gate selection says.
+A repository that runs its gates without `checks-lint` calls each gate's bin in its own CI step and declares each command in `gates.ci`.
+
+## Gate selection
+
+A repository with no TypeScript source gives `checks-lint-coverage`, `checks-test-layout`, `checks-size-budget` and `checks-feature-owners` nothing to check, and test-layout would still refuse its missing `bun test` script and `bunfig.toml`.
+It declares the gates `checks-lint` runs as `gates.lint`:
+
+```json
+"gates": {
+  "ci": ["bun run lint"],
+  "lint": [
+    "checks-commit-identity",
+    "checks-comment-gate",
+    "checks-suppressions-ratchet",
+    "checks-ci-wiring",
+    "checks-docs",
+    "checks-quality"
+  ]
+}
+```
+
+`checks-lint` runs exactly those, in the order of the table under What runs, and every gate when `gates.lint` is absent.
+A selection in `quality.json` always keeps `checks-quality`, since the file it sits in is what makes that gate apply.
+A step running `checks-lint` then counts only for a declared gate that `gates.lint` keeps.
+
+A selection may leave out only a gate that does not apply, and the Runs in column of the table under What runs says where each gate applies.
+Both `checks-lint` and `checks-ci-wiring` exit 2 on a `gates.lint` that names an unknown gate or leaves out one that applies to every repository.
+`checks-ci-wiring` exits 1 when the selection leaves out a gate the repository's tracked files make applicable, and names the gate and the files:
+
+```
+ci-wiring: quality.json gates.lint leaves out 4 gate(s) this repository's contents make applicable:
+  checks-lint-coverage: the repository tracks TypeScript source (src/widget.ts)
+  checks-test-layout: the repository tracks TypeScript source (src/widget.ts)
+  checks-size-budget: the repository tracks TypeScript source (src/widget.ts)
+  checks-feature-owners: the repository tracks TypeScript source (src/widget.ts)
+```
+
+It reads the files tracked at the checkout, so the pull request that adds the first TypeScript file is the one refused.
+
+## Running it in CI
+
+CI runs it through `lint`.
+The checkout fetches the whole history, which the merge base needs:
+
+```yaml
+on:
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+```
+
+## Related topics
+
+- [What runs](../../README.md#what-runs)
+- [checks-ci-wiring](checks-ci-wiring.md)
+- [The quality file](../configs/quality-file.md)