@avi2dg/checks 0.21.0 → 0.22.0

package/docs/design.md

@@ -1,32 +1,30 @@
+---
+kind: explanation
+---
 # Why it is shaped this way
 
 Each entry below is a choice in the kit's shape and the constraint that forced it.
 
 - Every config in an oxlint `extends` chain brings its own `plugins`, and one that sets none brings oxlint's default plugins, whose category rules the base's `categories` then turn on across the tree.
   `rules`, `categories` and `jsPlugins` inherit as expected.
-  That is why the consumer snippet restates `plugins` and nothing else, and why the generated fragment always sets them.
+  That is why the consumer config and each override restate `plugins`.
 - `node_modules/` is excluded through the consumer's `.gitignore`, not `ignorePatterns`: oxlint still walks the installed package when only `ignorePatterns` names it.
 - `files` in package.json is the published surface: `tests/`, `AGENTS.md` and the `.ts` plugin source never reach an install.
   npm adds `package.json`, `README` and `LICENSE` to the tarball whatever `files` says.
   `bun pm pack` builds the same tarball the registry serves, which is what the packed-tarball consumer e2e test installs.
 - The plugin ships compiled as `dist/index.js`, built with `bun build effect-channel/index.ts --outdir dist --target node --format esm`.
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
-- `featureRules` ships compiled as `dist/feature-rules.js` for the same reason, with `effect` left out of the bundle so it resolves the consumer's own copy.
-  dependency-cruiser uses a config's export as it is and never awaits it, so the declaration decodes synchronously, and `quality.json` exempts that one file from the Effect rules.
-- `checks-size-budget` writes the head commit's files to a temporary directory and runs oxlint there.
-  Its configuration loads the kit's own plugin bundle for the complexity rule and turns every category off.
-  The consumer's own `.oxlintrc.json`, its ignore files and its other rules never reach the count.
-- `checks-size-budget` ratchets against the base of the range rather than a committed baseline such as `oxlint-suppressions.json`.
-  A suppression file stores a count of sites per file and rule, and `max-lines` reports a file once however long it grows, so the count stays at one while the file doubles.
-  The gate sums how far each site runs over its limit instead, which grows with the file.
-  The base commit already holds that sum, so nothing is generated, committed or pruned.
-- `checks-repetition` writes the production files of both ends of the range to temporary directories and runs jscpd in each, so the consumer's `.jscpd.json` and ignore files never reach the count.
+- The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
+  A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
+  The kit runs no size script of its own, since restating how oxlint reads its config and compares sites left corners the native rules never had.
+  The suppression count lets a file or function already over its limit grow without a new site, which was accepted in exchange for dropping that script, and each repository is to work its counts down to zero.
+- `checks-repetition` writes both ends of the range to temporary directories and runs jscpd in each with the head's `.jscpd.json`, so its `path` and `ignore` globs decide the files at both ends.
   It compares each file's count of repeated lines rather than using jscpd's `--baseline-from-ref`.
   That flag reports a repeated block as new once its text changes, so a change that shortens a grandfathered block would fail.
 - `dist/` is committed.
   No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
   Rebuild it after pulling with `bun run build`.
-  `bun run build` also emits `quality.schema.json`, `templates/` and `CHANGELOG.md`, which are committed the same way.
+  `bun run build` also emits `templates/` and `CHANGELOG.md`, which are committed the same way.
   CI runs `git diff --exit-code` over the whole tree after the build, because a test that compares a generated file with its source passes on the copy the build just rewrote.
 - `CHANGELOG.md` is generated, so a release commit carries it and the tarball ships it.
   The commit that bumps package.json `version` closes its release, and the `v*` tag goes on that commit, so commits merged after it wait for the next release.
@@ -36,12 +34,13 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A section keeps the date it was written with, since the squash merge that lands the release commit may fall on another day.
   Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format.
   The bodies are the branch's own messages, which nothing lints.
-  The release path needs no `contents: write`: the changelog arrives in the release commit's pull request, not from a workflow that pushes.
-- `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a hook running without `node_modules`, a `.cjs` or `.mjs` config and `jq` all parse it with nothing installed, and nobody runs a repository's own code to learn its policy.
-  It holds declarations only.
-  The kit's bins read it directly.
-  oxlint and tsc read nothing but their own JSON, so they extend generated fragments, which `checks-quality --check` holds to the declarations.
-- `quality.json` refuses a key its schema does not name, so a kit that cannot enforce a newer key refuses it rather than let the repository believe it enforced.
+  The changelog still arrives in the release commit's pull request, not from a workflow that pushes.
+  The release path writes to the repository only through the `github-release` job's `contents: write`, which creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+- Workflow YAML owns CI execution, and the kit owns the required commands, but a repository is held only to the commands its own `package.json` can run.
+  `checks-ci-wiring` requires `bun run` with each of `lint`, `build`, `typecheck` and `test` that `package.json` defines as a script, `git diff --exit-code` when a `build` script exists, and commitlint always.
+  The target branch comes from git's own record in `refs/remotes/origin/HEAD`, or in CI from the pull request base or the default branch GitHub's event names, and never from a guess at the workflow files, and `checks-lint` starts its local range from the same branch.
+  Oxlint and TypeScript read their own overrides directly, so the consumer can change a rule where its tool reads it.
+  The Effect scopes occur in two native files, and the installed consumer test checks both independently.
 - The base parses with swc because typescript 7, which is tsgo, has no compiler API for dependency-cruiser to use.
   Without `@swc/core` installed the cruise silently skips every `.ts` file, so this repo's test asserts its own TypeScript is cruised.
 - `bunfig.toml` has no `extends` and no include: bun ignores an unknown top-level key in silence, so a preset cannot be inherited and the consumer's copy is compared key by key against the installed one instead.
@@ -55,8 +54,8 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugin that node loads.
 - `checks-lint` runs each gate as its own bin in a child process rather than importing it, so a gate behaves the same called alone or through the entry point, and `lint-coverage.sh` stays a shell script.
   The gates run one at a time with their output passed straight through, so each report reads whole and in the table's order.
-- A gate selection is checked against the repository's contents rather than trusted, so it cannot skip a gate that applies.
-  ci-wiring does that check, which is why a selection without it, or without another gate that applies everywhere, is refused as `checks-lint` reads it: nothing would check the selection otherwise.
+- `checks-lint` determines applicable gates from tracked files instead of accepting a repository selection.
+  A TypeScript gate starts running as soon as TypeScript source is tracked.
 - `checks-test` runs bun itself rather than reading a report some other run left: a skip taken only on CI is visible only in CI's own run, and an earlier run's report may be stale or narrowed.
   It reads the JUnit report bun writes to a temporary directory, since bun has no other per-test output meant for a program.
 - `checks-ci-wiring` runs inside `lint`, not in a workflow of its own: deleting the step that runs a check is the violation it catches, so the local `lint` is where it has to fail.
@@ -75,9 +74,9 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   That is the entry-point and layer recipe under Boundaries in [The dependency rules](configs/dependency-rules.md).
 - The templates in `templates/` are rendered from `scripts/doc-templates.ts`, the spec `checks-docs` reads.
   A template written by hand beside the check agrees with it only until someone edits one of them.
-- A page's Diátaxis mode is declared in `quality.json` rather than read from the page.
-  Whether a page teaches, walks a task, describes or explains is a judgment no program makes, so the repository states it once and the check holds the page to it.
-- `checks-docs` holds a doc file to its template when a change touches it, the way `checks-size-budget` holds a file to its budget.
+- A page's Diátaxis mode comes from `kind` front matter on the page, whatever directory holds it.
+  The repository makes the judgment beside the page, and the check holds it to that template.
+- `checks-docs` holds a doc file to its template when a change touches it, the way `checks-comment-gate` judges the comments a change adds.
   A repository adopts the templates as its files change, and an untouched file is listed as advisory rather than failing a change that never read it.
 - A task heading is verb first, and review holds it there rather than the check.
   No word list tells `Test layout` from `Test the layout`, and a check that passes the noun is worse than none.
@@ -95,8 +94,8 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A reference goes stale when the code it names moves far more often than when its own line is edited, so a gate on edited lines alone would miss the usual break.
 - A path under a top directory the repository lacks names a file in another repository, such as a consumer's, and no program tells that from a typo.
   A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
-- The command check passes over the docs a repository declares under `docs.forConsumers`.
-  This kit's README and reference pages speak to a consuming repository, whose scripts are not this one's, and no program tells an example for a consumer from an instruction for a contributor.
+- The command check passes over a page whose front matter sets `audience: consumers`.
+  Such a page speaks to a consuming repository, whose scripts are not this one's.
 
 ## Related topics
 

package/docs/gates/checks-backtest.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-backtest
 
 `checks-backtest` is the report of what the comment check would have refused at each recent commit, and a reader looks it up to measure a repository's own history before adopting the check.

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