@avi2dg/checks 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.44.0
+
+Released 2026-10-18.
+
+### Features
+
+- split the test suite into parallel unit and e2e CI tiers [#162](https://github.com/avi2d/checks/pull/162)
+- **testing:** hunt flakes with parallel test workers and replay failing workers [#164](https://github.com/avi2d/checks/pull/164)
+- **mutation:** add checks-mutation-scope to limit PR mutation runs to the change [#161](https://github.com/avi2d/checks/pull/161)
+- **quality:** add checks-no-plain-js gate refusing plain JavaScript sources [#163](https://github.com/avi2d/checks/pull/163)
+- **docs:** add checks-copy gate to refuse dashes in declared copy [#160](https://github.com/avi2d/checks/pull/160)
+
+## 0.43.0
+
+Released 2026-10-17.
+
+### Features
+
+- **testing:** run checks-test files in parallel on opt-in [#158](https://github.com/avi2d/checks/pull/158)
+
 ## 0.42.0
 
 Released 2026-10-14.

package/README.md

@@ -170,9 +170,11 @@ The table groups the gates by vector, the part of a repository each one judges.
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | quality | [`checks-effect-scope`](docs/gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
 | quality | [`checks-frontend-syntax`](docs/gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
+| quality | [`checks-no-plain-js`](docs/gates/checks-no-plain-js.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
 | docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
+| docs | [`checks-copy`](docs/gates/checks-copy.md) | the working tree | a repository tracking `copy.json` |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
 | delivery | [`checks-secrets`](docs/gates/checks-secrets.md) | the range | every repository |
@@ -188,6 +190,7 @@ These bins run on their own:
 - [`checks-mutation`](docs/gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
 - [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, saves it on a self-hosted runner's disk in place of an artifact, and deletes superseded baselines after a `main` run.
+- [`checks-mutation-scope`](docs/gates/checks-mutation-scope.md) turns a pull request's diff into the files its mutation runs mutate.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
@@ -207,7 +210,7 @@ oxlint runs through its own tool, as the pages under Related topics say.
 To move a repository to a newer release of the kit:
 
 1. Run the install line again, which moves the kit to its newest release and the peers to the versions it pins.
-   A repository that opted in to `checks-browser` or `checks-frontend-syntax` also reruns the `bun add` line on its page.
+   A repository that opted in to `checks-browser`, `checks-frontend-syntax` or `checks-copy` also reruns the `bun add` line on its page.
 1. Run `bun run build`, whose `checks-effect-scope` rewrites the Effect override and the kit's severities in `tsconfig.json` when a release changes them.
    A severity key the release drops stays in `tsconfig.json` until the repository removes it.
 1. Copy `node_modules/@avi2dg/checks/bunfig.toml` over `bunfig.toml` again, since `checks-test-layout` compares the copy with the installed preset.
@@ -227,7 +230,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `CHANGELOG.md` | every release, and what it changed |
 | `docs/` | a reference page per bin and per shared config, and why the kit is shaped this way |
 | `bunfig.toml` | the bunfig preset a repository copies |
-| `commitlint.config.js` | the shared commitlint config |
+| `commitlint.config.ts` | the shared commitlint config |
 | `dependency-cruiser.config.js` | the kit's dependency-cruiser rules as a base a `.dependency-cruiser.cjs` extends by path, which the build writes |
 | `knip-base.json` | the Knip `include` setting, for a configuration that spreads it |
 | `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect language service severities under `src/quality/presets/` |

package/{commitlint.config.js → commitlint.config.ts}

@@ -1,6 +1,6 @@
 import configConventional from "@commitlint/config-conventional";
 
-const houseTypes = [
+const houseTypes: ReadonlyArray<string> = [
   "theme",
   "herdr",
   "renamer",

package/dist/mutation/mutation-guard-plugin.js

@@ -0,0 +1,40 @@
+// src/testing/mutation-guard-plugin.ts
+import { existsSync } from "node:fs";
+
+// src/testing/mutation-refusal.ts
+var NON_RUNS = ["--help", "-h", "--version"];
+var MUTATE_FLAGS = ["--mutate", "-m"];
+function namesGlob(args) {
+  return args.some((arg, index) => MUTATE_FLAGS.includes(arg) && (args[index + 1] ?? "") !== "" || arg.startsWith("--mutate=") && arg !== "--mutate=");
+}
+function allowedAnyway(args, ci) {
+  return ci === "true" || args.some((arg) => NON_RUNS.includes(arg)) || namesGlob(args);
+}
+function fullRunRefusal(args, ci) {
+  if (allowedAnyway(args, ci) || args.includes("--incremental") && !args.includes("--force"))
+    return;
+  return "refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`";
+}
+function missingReportRefusal(args, ci, incrementalFile, reportExists) {
+  if (allowedAnyway(args, ci) || reportExists(incrementalFile))
+    return;
+  return `refusing a full mutation run outside CI: \`--incremental\` finds no report at ${incrementalFile} to reuse; scope this run with \`--mutate <glob>\`, or start the full baseline in CI with \`gh workflow run mutation\``;
+}
+
+// src/testing/mutation-guard-plugin.ts
+var GUARD_IGNORER = "checks-incremental-report-guard";
+function incrementalReportGuard(options) {
+  const refusal = missingReportRefusal(process.argv.slice(3), process.env.CI ?? "", options.incrementalFile, existsSync);
+  if (refusal !== undefined)
+    throw new Error(refusal);
+  return { shouldIgnore: () => {
+    return;
+  } };
+}
+var strykerPlugins = [
+  { kind: "Ignore", name: GUARD_IGNORER, factory: Object.assign(incrementalReportGuard, { inject: ["options"] }) }
+];
+export {
+  GUARD_IGNORER,
+  strykerPlugins
+};

package/dist/mutation/mutation-refusal.js

@@ -0,0 +1,23 @@
+// src/testing/mutation-refusal.ts
+var NON_RUNS = ["--help", "-h", "--version"];
+var MUTATE_FLAGS = ["--mutate", "-m"];
+function namesGlob(args) {
+  return args.some((arg, index) => MUTATE_FLAGS.includes(arg) && (args[index + 1] ?? "") !== "" || arg.startsWith("--mutate=") && arg !== "--mutate=");
+}
+function allowedAnyway(args, ci) {
+  return ci === "true" || args.some((arg) => NON_RUNS.includes(arg)) || namesGlob(args);
+}
+function fullRunRefusal(args, ci) {
+  if (allowedAnyway(args, ci) || args.includes("--incremental") && !args.includes("--force"))
+    return;
+  return "refusing a full mutation run outside CI; start the same run in CI with `gh workflow run mutation`, or scope this run with `--mutate <glob>` or `--incremental`";
+}
+function missingReportRefusal(args, ci, incrementalFile, reportExists) {
+  if (allowedAnyway(args, ci) || reportExists(incrementalFile))
+    return;
+  return `refusing a full mutation run outside CI: \`--incremental\` finds no report at ${incrementalFile} to reuse; scope this run with \`--mutate <glob>\`, or start the full baseline in CI with \`gh workflow run mutation\``;
+}
+export {
+  fullRunRefusal,
+  missingReportRefusal
+};

package/docs/configs/commit-messages.md

@@ -8,14 +8,14 @@ The shared commitlint config holds each pull request title to the conventional c
 
 ## Config
 
-Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.js` lists, shared from `node_modules/@avi2dg/checks/commitlint.config.js`.
+Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.ts` lists, shared from `node_modules/@avi2dg/checks/commitlint.config.ts`.
 It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-conventional` are dependencies, not peers.
 
 ## Workflow
 
 The lint runs in CI on pull requests, because `jj` never fires a git hook.
 Each repository lints the title in one step of its `ci` job with `bunx checks-commit-title`.
-The workflow lints with the installed kit's `commitlint.config.js`, so every repository holds titles to the same rules.
+The workflow lints with the installed kit's `commitlint.config.ts`, so every repository holds titles to the same rules.
 The `ci` job reports the title step's outcome as a `commitlint` status on every run, so a required `commitlint` status stays while `commitlint.yml` goes away.
 That post needs the workflow's `statuses: write` permission.
 The title lint runs before the docs-only filter, so a change to top-level Markdown and `docs/` Markdown alone still lints its title.

package/docs/design.md

@@ -98,6 +98,7 @@ npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin and each config builder ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
+Stryker loads its config under Node too, so the guard plugin and run-scope helpers the Stryker preset imports ship compiled under `dist/mutation/`.
 oxlint loads `oxlint.config.ts` under Node, so the builders ship as JavaScript beside a `.d.ts` that `tsc` reads.
 `@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`, except `readability/thin-astro`, which `tests/e2e/astro-consumer.test.ts` proves against a consumer tree linked to the checkout.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
@@ -315,6 +316,25 @@ So the runner calls the product's hooks at each visit and holds them to the same
 The runner drives the Chrome a machine already has through `playwright-core`, since Playwright's own browser builds are a separate download of their own.
 GitHub's hosted Ubuntu runners carry Chrome, and `CHROME_PATH` names any other build.
 
+## Copy is judged in the files a site renders
+
+`checks-copy` takes the three separator rules from `src/docs/prose-matchers.ts`, so a doc and a page refuse the same characters in the same words.
+Its Markdown goes through the scanner `checks-docs` uses, so the two gates never disagree about what is code.
+Its HTML goes through html-validate, which the `nesting` check already runs, with one rule of the kit's own.
+No rule html-validate or markdownlint ships refuses a spaced hyphen between words.
+textlint and Vale could each carry the rule, but each adds a package or a binary.
+Each would also hold a second copy of patterns the kit already holds.
+
+The gate reads files rather than strings in source.
+An oxlint rule over string literals and JSX text was run across the repositories that consume the kit.
+It found mostly code inside a string, test fixtures and error messages.
+The few hits that were copy, such as a line a CLI prints, look to a program like `scrollHeight - innerHeight` in a test script.
+A site's strings all reach its built pages, so a glob over the built HTML judges each one where a visitor reads it.
+
+Only a repository knows which of its files are copy, so it opts in by declaring them in `copy.json`.
+The gate judges every line of each declared file, unlike the prose rules in `checks-docs`, which judge only the lines a change edits.
+A visitor reads the whole page, so a dash on a line the change left alone is as wrong as one it added.
+
 ## Related topics
 
 - [checks](../README.md)

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

@@ -11,6 +11,7 @@ audience: consumers
 The kit requires `bunx checks-commit-title` on every pull request.
 A step that calls `bun src/delivery/commit-title.ts` or `./node_modules/.bin/commitlint` directly still satisfies the check.
 It requires `bun run lint`, `bun run build`, `bun run typecheck` and `bun run test` for each of those scripts that `package.json` defines.
+When `package.json` defines both `test:unit` and `test:e2e`, a step for each of `bun run test:unit` and `bun run test:e2e` also satisfies `bun run test`.
 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.
@@ -43,7 +44,7 @@ A file counts as a shell script when its name ends in `.sh` or its first line na
 The call counts as a command of its own or inside a command substitution, never as an argument to another command.
 A here-document that `sh`, `bash`, `dash`, `ksh` or `zsh` reads is a script, and its calls count.
 The text of any other here-document is data, so a call there counts only inside a command substitution when the delimiter is unquoted.
-A mutation job never names `CI_RUNS_ON` directly in `runs-on`, as `vars.CI_RUNS_ON` or `vars['CI_RUNS_ON']`, so an override for an outage cannot send its full sweeps to hosted runners.
+A mutation job never names `CI_RUNS_ON` directly in `runs-on`, as `vars.CI_RUNS_ON` or `vars['CI_RUNS_ON']`, so an override for an outage cannot send its mutation runs to hosted runners.
 Any other job that names `CI_RUNS_ON` in `runs-on` carries exactly the hosted-default expression `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
 In a private repository each mutation job carries exactly the labels `[self-hosted, Linux, X64, winbox]` and every other job exactly the hosted-default expression.
 A public repository may keep `runs-on: ubuntu-latest` on every job, because a pull request from a fork runs its own code on the runner.
@@ -106,7 +107,7 @@ A mutation job that names `CI_RUNS_ON` in `runs-on` produces a report like this:
 
 ```
 ci-wiring: 1 job(s) run on the wrong runner:
-  .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; set runs-on: [self-hosted, Linux, X64, winbox]
+  .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its mutation runs off winbox; set runs-on: [self-hosted, Linux, X64, winbox]
 ```
 
 A reference to a missing workflow produces a report like this:

package/docs/gates/checks-copy.md

@@ -0,0 +1,113 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-copy
+
+`checks-copy` is the opt-in gate that refuses an em dash, an en dash or a hyphen used as a dash in copy a person reads.
+
+## What it checks
+
+It judges every line of each Markdown and HTML file a repository declares as its copy, in any language.
+It holds them to the three separator rules of [The prose rules](checks-docs.md#the-prose-rules):
+
+| Refused | For example | Passes |
+| --- | --- | --- |
+| an em dash | `hexn.io — платформа` | `hexn.io, платформа` |
+| an en dash | `pages 1–5` | `pages 1 to 5` |
+| a hyphen used as a dash | `hexn.io - платформа` or `a -- b` | `well-known`, `kebab-case`, `1-5` and `--flag` |
+
+A hyphen used as a dash is a run of one to three hyphens with white space on both sides and text on both sides.
+So a hyphen inside a word or a number, a flag and a list marker all pass.
+It reads text as a reader sees it, so a line break, a non-breaking space or a run of spaces counts as one space.
+A hyphen that ends one line of a paragraph and is followed by a word on the next still reads as spaced.
+Copy in a table passes a hyphen standing alone in a cell.
+
+In a Markdown file it reads what [checks-docs](checks-docs.md) reads, with the same scanner.
+It skips fenced code, inline code, link destinations, URLs, HTML comments and front matter, and keeps the text of a link.
+Each paragraph and each list item is read whole across its lines, while a heading and a table row are each read on their own.
+
+In an HTML file it reads the page through html-validate, with one rule of the kit's own named `copy/separators`.
+It reads the text of the page, with `<title>` included, and each `alt`, `title`, `placeholder`, `aria-label` and `aria-description` attribute.
+It reads the `value` of an `<input>` whose `type` is `submit`, `button` or `reset`, and the `label` of an `<option>` or an `<optgroup>`, since each shows as a control's label.
+It does not read the `value` of any other `<input>`, which holds what a visitor types.
+It reads the `content` of a `<meta>` whose `name` or `property` is `description`, `og:title`, `og:description`, `twitter:title` or `twitter:description`.
+It decodes a numeric character reference and `&mdash;`, `&ndash;` and `&nbsp;`, so `a &mdash; b` fails as an em dash.
+Text runs across an inline element such as `<a>` or `<strong>`, as `<a href="https://example.com">Example</a> - about` shows, and breaks at a block such as `<p>` or `<li>` and at `<br>`.
+Each of `<code>`, `<kbd>`, `<samp>` and `<var>` stands in as one character the rules never refuse, so a hyphen used as a dash after it still fails.
+It does not read `<script>`, `<style>`, `<template>` or `<pre>`, and reads the text of `<textarea>`, `<noscript>`, `<svg>` and `<math>` like any other.
+It reports a file that does not parse as HTML, since it cannot judge one.
+It fails on each declared input that matches no Markdown or HTML file.
+So an input that a renamed directory or a skipped build leaves empty never passes.
+It also fails on each file an input matches that is neither Markdown nor HTML.
+
+These are outside what it decides:
+
+- A string in TypeScript source, since no program tells copy from code in a string.
+  A site's UI strings reach its built pages, so a glob over the built HTML judges them.
+- What CSS hides or a script changes, since it reads the HTML source rather than a rendered page.
+- A dash in front matter, such as a page title, which a glob over the built HTML judges on the page.
+- Parentheses, semicolons and the other prose rules, which judge only the docs [checks-docs](checks-docs.md) holds.
+
+## What it reads
+
+It reads `copy.json` in the directory it runs in, which lists the inputs as globs:
+
+```json
+{
+  "inputs": ["src/content/**/*.md", "dist/**/*.html"]
+}
+```
+
+A glob over built output, such as `dist/**/*.html`, judges every string a site renders, and needs the build to run first.
+Each glob resolves from that directory, matches only files and skips `node_modules/`.
+It reads each file ending in `.md` or `.html` that a glob matches, and a file two globs match is judged once.
+It reads the working tree, so an uncommitted file is judged like a committed one.
+
+A repository that declares an HTML file installs the optional peer the gate loads for it, at the version the kit pins:
+
+```sh
+bun add -d html-validate@11.16.0
+```
+
+## Arguments
+
+```sh
+checks-copy [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every declared input matches a Markdown or HTML file, and no file carries a refused separator |
+| 1 | a file carries a refused separator or does not parse, a declared input matches no Markdown or HTML file, or an input matches a file of another kind |
+| 2 | `copy.json` is missing or does not decode, its input list is empty, or html-validate cannot load |
+
+## Sample output
+
+```
+copy: 3 problem(s) in 2 file(s) from 3 declared input(s):
+  public/**/*.html: the declared input matches no Markdown or HTML file
+  dist/index.html:102:57 carries `-`, a hyphen used as a dash. End the sentence, or use a comma
+  src/content/home.ru.md:26:33 carries `-`, a hyphen used as a dash. End the sentence, or use a comma
+```
+
+A passing run counts what it judged:
+
+```
+copy: no violation in 2 file(s) from 2 declared input(s)
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks `copy.json` at its root.
+A repository without that file never runs it and needs no html-validate.
+
+## Related topics
+
+- [checks-docs](checks-docs.md)
+- [checks-browser](checks-browser.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-docs-only.md

@@ -41,9 +41,10 @@ docs-only=true
 
 ## When it runs
 
-The `ci` job has a filter step that appends the verdict to `GITHUB_OUTPUT`, and the typecheck and test steps skip when the verdict reads `true`.
+Each of the `static`, `unit` and `e2e` jobs of the `ci` workflow appends the verdict to `GITHUB_OUTPUT` in a filter step.
+Their typecheck and test steps skip when the verdict reads `true`.
 The build, its `git diff --exit-code` and `bun run lint` still run, so `checks-docs` and the generated blocks hold on a docs-only change.
-The job itself always runs and reports, so every required check stays green on a docs-only change.
+Every job still runs and reports, so every required check stays green on a docs-only change.
 
 ## Related topics
 

package/docs/gates/checks-docs.md

@@ -113,6 +113,8 @@ Readability scores and word choice, such as easy, are not checked.
 A sentence over the trial length cap is listed as advisory and never fails the run.
 The cap is 20 words in an ordered list item and 25 words elsewhere.
 
+[checks-copy](checks-copy.md) holds every line of the copy a repository declares to the three separator rules.
+
 `src/docs/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
 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.
@@ -225,4 +227,5 @@ A name the range removes fails wherever a doc still carries it, because the remo
 ## Related topics
 
 - [Why it is shaped this way](../design.md)
+- [checks-copy](checks-copy.md)
 - [checks-lint](checks-lint.md)

package/docs/gates/checks-flake.md

@@ -13,9 +13,38 @@ A green run proves nothing failed in that run, not that no test is flaky.
 `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.
 
+## Parallel hunts
+
+A repository whose `test` script passes `--parallel=<workers>` to [checks-test](checks-test.md#parallel-runs) is hunted with the same worker count, so each run is `bun test --randomize --seed=<seed> --parallel=<workers>`, the mode CI runs in.
+A `test` script without the option keeps the serial hunt.
+
+Under workers a seed fixes the order Bun hands out the files.
+Which worker takes each file is a race between the workers.
+Rerunning a failing seed with the same worker count therefore reproduces the failure only some of the time.
+A failure that hangs on which files share a worker comes back every time from that worker's files.
+They run again in one process, in the order the worker ran them.
+
+So `checks-flake` passes Bun a preload that records which worker ran each file, after the repository's own `[test]` preload in `bunfig.toml`.
+For each failing worker in a failed run, the summary prints a replay command.
+It runs the files that worker ran, up to the last failing one, with the run's seed:
+
+```sh
+bun test --isolate --randomize --seed=2170533150 ./tests/unit/cache.test.ts ./tests/unit/session.test.ts
+```
+
+`--isolate` gives each file a fresh global in one process, as a worker does.
+The seed orders the tests inside each file as the worker ran them, whichever other files run with it.
+Bun also shuffles the files it lists, by a permutation of their positions that the seed and their count fix.
+So `checks-flake` learns that permutation from a run of placeholder files and lists the files so the seed runs them in the worker's order.
+On more than one worker the summary also says that rerunning a seed with the worker count reproduces only some of the time.
+A run whose worker crashed gets a replay of that worker's files up to the crashed one.
+
 ## What it reads
 
 It reads bun's JUnit report of each run.
+It reads the worker count from the `test` script in `package.json`, as [checks-test-layout](checks-test-layout.md) validates that script, and hunts serially when the file is missing.
+Under workers it reads the record its preload writes of which worker ran each file.
+For each replay it reads the order Bun ran its placeholder files.
 Under GitHub Actions it appends its summary to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.
 
 ## Arguments
@@ -27,6 +56,7 @@ 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.
+Under workers the record also holds `parallel`, the worker count and each replay's seed, files in the order the worker ran them, and command.
 
 ## Exit codes
 
@@ -34,7 +64,7 @@ checks-flake [--runs <count> | --seed <seed>...] [--report <file>]
 | --- | --- |
 | 0 | every run passed |
 | 1 | a run failed |
-| 2 | an argument does not parse, or bun passed without writing its report |
+| 2 | an argument does not parse, `package.json` or the worker record does not decode, bun passed without writing its report, or a replay's placeholder files did not each run once |
 
 ## Sample output
 
@@ -48,6 +78,23 @@ checks-flake: 3 of 10 run(s) failed, 1 test(s) failing in them
 Reproduce a failing run with bun test --randomize --seed=<seed>.
 ```
 
+A hunt on workers prints a replay for each failed run:
+
+```
+checks-flake: 2 of 10 run(s) failed on 4 worker(s), 1 test(s) failing in them
+
+| Test | Failed | Seeds |
+| --- | --- | --- |
+| tests/unit/cache.test.ts:6 reads the cache | 2 of 10 runs | 2170533150, 180394251 |
+
+Reproduce a failing run with the files its failing worker ran, listed so the seed runs them in that order:
+
+- seed 2170533150: `bun test --isolate --randomize --seed=2170533150 ./tests/unit/cache.test.ts ./tests/unit/session.test.ts`
+- seed 180394251: `bun test --isolate --randomize --seed=180394251 ./tests/unit/session.test.ts ./tests/unit/cache.test.ts ./tests/unit/pricing.test.ts`
+
+Rerunning a seed with bun test --randomize --seed=<seed> --parallel=4 reproduces a failing run only some of the time, because which worker takes each file is a race.
+```
+
 ## When it runs
 
 Only a schedule the repository writes runs it.
@@ -88,4 +135,5 @@ A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` o
 ## Related topics
 
 - [checks-test](checks-test.md)
+- [checks-test-layout](checks-test-layout.md)
 - [checks-ci-wiring](checks-ci-wiring.md)

package/docs/gates/checks-lint.md

@@ -13,6 +13,7 @@ Gates requiring tracked TypeScript files begin running when the repository track
 `checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
 `checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
+`checks-copy` begins running when the repository tracks `copy.json` at its root.
 All other gates run for every repository.
 
 ## What it reads
@@ -47,7 +48,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 16 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 18 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

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

@@ -181,13 +181,15 @@ It slims the report first, so the artifact holds about 0.5 MB in place of about
 The full upload keeps 30 days, so the newest full baseline outlives the gap between full runs.
 A pull request's scope step loses its coverage when no full baseline outlives the gap.
 
-A pull request's scope step restores the full report with `--full`:
+A pull request's scope step restores the full report with `--full`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
 
 ```yaml
 - name: Select mutation scope
   env:
     GH_TOKEN: ${{ github.token }}
-  run: bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+  run: |
+    bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+    bunx checks-mutation-scope "$(git merge-base HEAD origin/main)" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
 ```
 
 ## Related topics

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

@@ -78,7 +78,7 @@ The shared preset refuses a full `stryker run` outside CI and names that workflo
 
 ## Running it in CI
 
-It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base:
+It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base over the same scope:
 
 ```yaml
 name: mutation-compare
@@ -87,6 +87,9 @@ on:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
     steps:
       - uses: actions/checkout@v5
         with:
@@ -95,28 +98,50 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - run: bunx stryker run
-      - run: |
+      - name: Select mutation scope
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+          echo "BASE_SHA=$base" >> "$GITHUB_ENV"
+          bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+          bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
+      - if: env.SCOPE == ''
+        run: echo "::notice::mutation-compare: nothing in mutation scope changed, so neither Stryker run starts"
+      - if: env.SCOPE != ''
+        run: bunx stryker run --mutate "$SCOPE"
+      - if: env.SCOPE != ''
+        run: |
           base_worktree="$RUNNER_TEMP/mutation-base-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
           echo "BASE_WORKTREE=$base_worktree" >> "$GITHUB_ENV"
           git worktree prune
-          git worktree add "$base_worktree" "$(git merge-base HEAD origin/main)"
-          (cd "$base_worktree" && bun install --frozen-lockfile && bunx stryker run)
-      - run: bun run checks-mutation-compare --advisory "$BASE_WORKTREE/reports/mutation/mutation.json" reports/mutation/mutation.json
+          git worktree add "$base_worktree" "$BASE_SHA"
+          (cd "$base_worktree" && bun install --frozen-lockfile && bunx stryker run --mutate "$SCOPE")
+      - if: env.SCOPE != ''
+        run: bun run checks-mutation-compare --advisory "$BASE_WORKTREE/reports/mutation/mutation.json" reports/mutation/mutation.json
       - if: always() && env.BASE_WORKTREE != ''
         run: |
           git worktree remove --force "$BASE_WORKTREE"
           git worktree prune
 ```
 
-Both Stryker runs are full sweeps, and GitHub sets `CI=true` on every runner, so the preset lets them through.
+The scope step picks the files the pull request changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
+Neither run mutates a file outside that scope, so the job's time follows the size of the change and not the size of the repository.
+Both runs take the same `--mutate "$SCOPE"`, so the two reports hold the same files.
+A scope file the merge base lacks matches nothing there, and Stryker still writes a report.
+An empty scope skips both runs and the comparison, and the notice names the skip on the run's summary.
+A changed unit test with no full baseline on `main` fails the scope step, since no report then says which sources the test covers.
+A changed unit test that `main` edited after that baseline widens the scope to every file the `mutate` globs match.
+Start a full baseline with `gh workflow run mutation`, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
+A run with `--mutate` is scoped, so the preset lets it through without `CI=true`.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
 A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
-A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its full sweeps.
+A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its mutation runs.
 The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 
 ## Related topics
 
 - [checks-mutation](checks-mutation.md)
+- [checks-mutation-scope](checks-mutation-scope.md)
 - [checks-test-layout](checks-test-layout.md)