@avi2dg/checks 0.21.0 → 0.23.0

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

@@ -1,122 +1,59 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-ci-wiring
 
-`checks-ci-wiring` is the gate that fails when a command the repository's CI must run no longer runs on pull requests to the default branch, and a reader looks it up to learn which workflow step counts.
+`checks-ci-wiring` verifies that required commands run in the repository's own pull request workflows.
 
 ## What it checks
 
-No local check sees a gate drop out of CI, since a workflow whose lint step became a no-op leaves `bun run lint` green.
-The repository declares its gates once, in `quality.json`:
+The kit requires `./node_modules/.bin/commitlint` on every pull request.
+It requires `bun run lint`, `bun run build`, `bun run typecheck` and `bun run test` for each of those scripts that `package.json` defines.
+A `build` script also requires `git diff --exit-code`.
+The target branch is the pull request base in CI, else the branch `refs/remotes/origin/HEAD` names, else the default branch of the repository in GitHub's event, else `main`.
+A `pull_request` trigger without a branch filter covers every target branch.
 
-```json
-"gates": {
-  "ci": ["bun run lint", "bun run typecheck", "bun run test"]
-}
-```
-
-It looks, for each gate, for a `run:` step that is the gate command alone on one line, optionally followed by plain arguments.
-Plain arguments are words, quoted strings, and `$VAR` or `${VAR}` expansions.
-`bun run lint --quiet` and `bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"` count.
-`bun run lint:deps`, `echo bun run lint` and a step `name:` do not.
-
-A step never counts when its script has a second line or any of these, because each can run the gate without its failure failing the step:
-
-- `|`, `||`, `&&`, `;` or `&`
-- `$(...)` or backticks
-- `<` or `>` redirection
-- a comment
-- a leading `NAME=value`
-
-The report names such a gate and says to give it its own step with nothing else in it.
-A gate step counts only when all of these hold:
-
-- Its workflow triggers on `pull_request`.
-  Any `branches` or `branches-ignore` filter there keeps the default branch, any `types` filter keeps `opened` and `synchronize`, and it sets no `paths` or `paths-ignore` filter, which would let some pull requests skip the gate.
-- Neither the step nor its job sets `if: false` or `continue-on-error: true`, bare or as `${{ false }}` and `${{ true }}`.
-- Its job needs no job, directly or through a chain, that sets `if: false`, unless a job on that chain has an `if:` calling `always()`, `failure()` or `cancelled()`.
-  GitHub prefixes every other `if:`, including `true` and `success()`, with `success()`, so a job whose needed job was skipped is skipped too.
-
-A job calling a local reusable workflow, such as `uses: ./.github/workflows/x.yml`, passes its own trigger and `if:` down to the called workflow's steps.
-A remote reusable workflow, such as `uses: owner/repo/...@ref`, is not a supported way to wire a gate.
-It is not read, so a gate must run as a `run:` step in the repository's own workflows, such as `bunx checks-comment-gate`.
-
-A step running `checks-lint` also counts for a declared gate that calls one of the gates `checks-lint` runs by its bare bin name, when the step calls `checks-lint` the same way.
-`bunx checks-lint` counts for `bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"`.
-A step running `bun run lint` counts only for the `bun run lint` gate, since the check never reads what a package script runs.
-So once `lint` runs `checks-lint`, the per-gate entries can leave `gates.ci` along with the workflows that ran them.
-
-A command a schedule must run, such as the flake run, goes in `gates.scheduled`:
-
-```json
-"gates": {
-  "ci": ["bun run lint", "bun run typecheck", "bun run test"],
-  "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
-}
-```
-
-Each counts only as a step of the same plain shape in a workflow whose `on` carries `schedule` with at least one `cron`, under the same `if: false`, `continue-on-error: true` and `needs` rules as a gate.
-
-It also checks `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+Each command needs its own plain `run` step.
+A step can call a path command through `bun run`.
+The check follows local reusable workflows but not remote reusable workflows.
+It refuses a step or job with `if: false` or `continue-on-error: true`.
+It also refuses a workflow that does not trigger on both `opened` and `synchronize` pull requests to the target branch.
+A path filter cannot cover every pull request and therefore cannot satisfy the check.
 
 ## What it reads
 
-It reads the working tree: `quality.json` for `defaultBranch`, `gates.ci`, `gates.scheduled` and `gates.lint`, and every `.github/workflows/*.yml` and `*.yaml`.
-The default branch is `main` when `quality.json` declares none.
-It parses each workflow with `Bun.YAML` and never runs it.
+The bin reads `.github/workflows/*.yml`, `*.yaml` and the `scripts` in `package.json` from the working tree.
+It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
+It parses the workflows with `Bun.YAML` without executing them.
 
 ## Arguments
 
-It takes none.
+It takes no arguments.
 
 ## Exit codes
 
-| Code | When |
+| Code | Result |
 | --- | --- |
-| 0 | every declared command runs where it must |
-| 1 | a gate does not run on pull requests to the default branch, a scheduled command runs on no schedule, or `gates.lint` leaves out a gate that applies |
-| 2 | `quality.json` declares no `gates.ci` or does not decode, a gate or scheduled command is not one plain command, or a workflow does not parse |
-
-Whether a workflow is well formed is actionlint's question, not this one's.
+| 0 | Every required command has a reachable step. |
+| 1 | A required command is missing or blocked. |
+| 2 | A workflow or `package.json` cannot be decoded. |
 
 ## Sample output
 
-It names each gap, with every step that runs the gate and why that step does not count:
-
-```
-ci-wiring: 1 of 8 gate(s) do not run on pull requests to main:
-  bun run lint
-    .github/workflows/release.yml job publish step 7: .github/workflows/release.yml does not trigger on pull_request
-```
-
-It names each scheduled command no schedule runs:
+A missing step produces a report like this:
 
 ```
-ci-wiring: 1 of 1 scheduled command(s) do not run on a schedule:
-  bunx checks-flake --runs 10 --report flake-report.json
-    .github/workflows/ci.yml job checks step 5: .github/workflows/ci.yml does not trigger on a schedule
+ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
+  bun run test
+    no run step invokes it
 ```
 
 ## Opting out
 
-It applies to every repository, so no selection leaves it out.
-It runs inside `lint`, through `checks-lint`, because deleting the step that runs a check is the violation it catches:
-
-```json
-"scripts": {
-  "lint": "oxlint --type-aware && checks-lint"
-}
-```
-
-## Limits
-
-The check reads workflow files and never runs them, so it deliberately does not evaluate these:
-
-- an `if:` expression other than a constant `true` or `false`, which counts as running
-- a `strategy.matrix` `include` or `exclude`, so a matrix that drops every combination still counts as running its steps
-- a remote reusable workflow, whose steps are never read
-- anything that happens at run time on the runner, such as what the gate command itself does, the shell's options, and a step or job that fails or times out before the gate step
+Every repository runs this gate through `checks-lint`.
 
 ## Related topics
 
 - [checks-lint](checks-lint.md)
-- [checks-flake](checks-flake.md)
-- [The quality file](../configs/quality-file.md)
+- [Native settings](../configs/native-settings.md)

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.

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

@@ -1,19 +1,25 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.
+`checks-commit-identity` checks a commit's author and committer against the owners in `package.json` and refuses coauthor trailers.
 
 ## 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.
+The author and committer of each commit must be allowed.
+A commit whose trailer block carries a `Co-authored-by` trailer, as git parses it, is refused.
+`GitHub <noreply@github.com>` is allowed as committer only.
 
 ## 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.
+`package.json` uses its standard `author` and `contributors` fields for allowed authors.
+Each person can be any form npm allows, an object with `name` and optional `email` and `url`, or a string such as `Avi <avi@example.com> (https://example.com)`.
+A person with both a name and an email is an allowed author.
+A person without an email is ignored.
+When no person carries an email, the kit allows `avi2d <avi2dg@gmail.com>`.
+The bin reads commits from git and parses their trailer blocks.
 
 ## Arguments
 
@@ -22,16 +28,16 @@ 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.
+With two arguments, the bin checks every commit the head holds and the base does not.
+With one argument, it checks that commit alone.
 
 ## Exit codes
 
-| Code | When |
+| Code | Result |
 | --- | --- |
-| 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 |
+| 0 | Every commit carries an allowed identity. |
+| 1 | A commit carries a foreign identity. |
+| 2 | A ref, argument or `package.json` cannot be decoded. |
 
 ## Sample output
 
@@ -39,25 +45,15 @@ With one it checks that commit alone.
 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.
+This gate runs on every repository through `checks-lint`.
+The repository adds owners through `package.json` rather than omitting the gate.
 
 ## Related topics
 
-- [The commit message lint](../configs/commit-messages.md)
+- [Native settings](../configs/native-settings.md)
 - [checks-lint](checks-lint.md)

package/docs/gates/checks-docs.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.
@@ -13,7 +17,7 @@ The package ships one template per kind under `templates/`, and a repository sta
 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 -->
+<!-- generated doc-kinds: bun run build writes it from scripts/doc-rules.ts, scripts/doc-templates.ts and scripts/doc-blocks.ts -->
 
 | File | Kind | Template |
 | --- | --- | --- |
@@ -23,21 +27,18 @@ cp node_modules/@avi2dg/checks/templates/how-to.md docs/add-a-supplier.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` |
+| a page with `kind` in front matter | 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 page under `docs/` declares its mode in front matter:
+
+```yaml
+---
+kind: tutorial
+---
 ```
 
 A template decides a file's structure, and the template file itself is the reference for each kind:
@@ -113,20 +114,21 @@ It fails on any other line when the range broke it, as by deleting the file it n
 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`:
+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`:
 
-```json
-"docs": {
-  "forConsumers": ["README.md", "docs/gates/*.md"]
-}
+```yaml
+---
+kind: reference
+audience: consumers
+---
 ```
 
 ## What it reads
 
-It reads each Markdown file from the head commit, and `docs.pages` from `quality.json`.
+It reads each Markdown file from the head commit and uses its path or front matter to choose a mode.
 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`.
+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`.
 
 ## Arguments
@@ -145,7 +147,7 @@ With one it is that commit against its parent, or against the empty tree for a r
 | --- | --- |
 | 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 |
+| 2 | a `package.json` does not decode, or a ref does not resolve |
 
 ## Sample output
 
@@ -154,7 +156,7 @@ 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/parts.md: is a page under docs/ with no mode; add kind: tutorial, how-to, reference, explanation in YAML front matter
 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:
@@ -166,7 +168,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs name were broke
 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`.
+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.
 
 ## Related topics

package/docs/gates/checks-flake.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.
@@ -47,7 +51,6 @@ 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
 
@@ -73,15 +76,6 @@ jobs:
           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)

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.
@@ -40,7 +44,7 @@ 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.
+`checks-lint` runs this gate only when the repository tracks `.ts` or `.tsx` files.
 A repository that tracks one keeps it.
 
 ## Related topics

package/docs/gates/checks-lint.md

@@ -1,43 +1,25 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.
+`checks-lint` runs every applicable kit lint gate over one range and reports each failure.
 
 ## 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`.
+It runs the gates under [What runs](../../README.md#what-runs) in table order, each in its own process.
+Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+All other gates run for every repository.
 
 ## 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.
+The range ends at `HEAD` and starts at the merge base with `origin/HEAD` for a local run.
+If remote HEAD is absent, the range starts at the default branch GitHub's event names in CI, or at `origin/main`.
+A local run with `GITHUB_BASE_REF` set starts at that branch on `origin` instead.
+A clone with no remote tracking refs checks `HEAD` alone.
+On a pull request the range ends at the event's head commit and starts at its merge base with the event's base branch.
+Tree gates read the working tree rather than the range.
 
 ## Arguments
 
@@ -46,93 +28,29 @@ 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.
+With two arguments, the base and head override range discovery.
 
 ## Exit codes
 
-| Code | When |
+| Code | Result |
 | --- | --- |
-| 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 |
+| 0 | Every applicable gate passed. |
+| 1 | At least one gate found a violation. |
+| 2 | The range could not resolve or no failed 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 12 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+checks-lint: 1 of 9 gate(s) failed: checks-comment-gate
 ```
 
 ## 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`, `checks-repetition` 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-quarantine-clock",
-    "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 5 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-repetition: 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
-```
+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.
 
 ## Related topics
 
 - [What runs](../../README.md#what-runs)
 - [checks-ci-wiring](checks-ci-wiring.md)
-- [The quality file](../configs/quality-file.md)

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+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.