@avi2dg/checks 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.45.0
+
+Released 2026-10-18.
+
+### Breaking changes
+
+- **quality:** hold CSS to the stylelint rule families set in stylelint.config.ts [#167](https://github.com/avi2d/checks/pull/167)
+
+## 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.

package/README.md

@@ -1,7 +1,7 @@
 # checks
 
 `@avi2dg/checks` is the kit of deterministic checks a TypeScript repository installs to hold its code, tests, commits, CI wiring and docs to one shared standard.
-It ships the lint gates `checks-lint` runs over each pull request, the test runners, and a `defineConfig` for oxlint, Knip and dependency-cruiser.
+It ships the lint gates `checks-lint` runs over each pull request, the test runners, and a `defineConfig` for oxlint, Knip, dependency-cruiser and stylelint.
 It also ships the configs a repository extends for tsc, commitlint, bun and Stryker.
 Each repository owns its workflows and native tool configs, as [Native settings](docs/configs/native-settings.md) maps.
 
@@ -26,6 +26,8 @@ Each repository owns its workflows and native tool configs, as [Native settings]
   - `playwright-core` 1.63.0
   - `postcss-html` 2.0.0
   - `stylelint` 17.16.0
+  - `stylelint-config-standard` 40.0.0
+  - `stylelint-plugin-use-baseline` 1.4.7
 
 <!-- end generated prerequisites -->
 
@@ -170,9 +172,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 +192,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 +212,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,11 +232,11 @@ 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/` |
-| `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip` and `@avi2dg/checks/dependency-cruiser` resolve to, and the doc templates, one template per kind of doc file |
+| `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip`, `@avi2dg/checks/dependency-cruiser` and `@avi2dg/checks/stylelint` resolve to, and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint `base` as a config a `.oxlintrc.json` extends by path, which the build writes |
 | `stryker.preset.js` | the Stryker mutation-testing preset, which refuses a full run outside CI |
 | `tsconfig.effect.json` | the tsconfig fragment with the shared compiler options and the Effect language-service block |

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/dist/presets/stylelint.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from "stylelint";
+type Globs = readonly [string, ...string[]];
+export type BaselineTarget = "widely" | "newly" | number;
+export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
+    readonly baseline: BaselineTarget;
+    readonly tokens: Globs | false;
+};
+export declare const MARKUP: readonly ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
+export declare function defineConfig({ baseline, tokens, rules, overrides, ...rest }: ChecksStylelintConfig): Config;
+export {};

package/dist/presets/stylelint.js

@@ -0,0 +1,73 @@
+// src/quality/presets/stylelint.ts
+import { fileURLToPath } from "node:url";
+var HTML_AND_ASTRO = ["**/*.html", "**/*.astro"];
+var MARKUP = [...HTML_AND_ASTRO, "**/*.vue", "**/*.svelte"];
+function peer(name) {
+  return fileURLToPath(import.meta.resolve(name));
+}
+var CONVENTION_CHANGES = {
+  "no-descending-specificity": null,
+  "property-no-vendor-prefix": [true, { disableFix: true, ignoreProperties: ["-webkit-user-select"] }]
+};
+var SELECTOR_COMPLEXITY = {
+  "selector-max-specificity": "0,3,2",
+  "selector-max-compound-selectors": 3
+};
+var COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"];
+var DESIGN_TOKENS = {
+  "color-no-hex": true,
+  "color-named": "never",
+  "function-disallowed-list": COLOUR_FUNCTIONS.map((name) => `/^${name}$/i`),
+  "declaration-property-value-allowed-list": { "/^font-size$/i": ["/^var\\(\\s*--[^\\s,()]+\\s*\\)$/i", "/^inherit$/i"] }
+};
+var REFUSED_BASELINE = '@avi2dg/checks/stylelint: set baseline to "widely", "newly" or a year such as 2024';
+var REFUSED_TOKENS = "@avi2dg/checks/stylelint: set tokens to the globs of the token files, or false to leave the design token rules off";
+function baselineTarget(baseline) {
+  if (baseline === "widely" || baseline === "newly")
+    return baseline;
+  if (typeof baseline === "number" && Number.isInteger(baseline))
+    return baseline;
+  throw new TypeError(REFUSED_BASELINE);
+}
+function isGlobList(value) {
+  return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");
+}
+function tokenFiles(tokens) {
+  if (tokens === false)
+    return [];
+  if (isGlobList(tokens) && tokens.length > 0)
+    return tokens;
+  throw new TypeError(REFUSED_TOKENS);
+}
+function designTokens(files) {
+  if (files.length === 0)
+    return { rules: {}, overrides: [] };
+  const off = Object.fromEntries(Object.keys(DESIGN_TOKENS).map((rule) => [rule, null]));
+  return { rules: DESIGN_TOKENS, overrides: [{ files: [...files], rules: off }] };
+}
+function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }) {
+  const available = baselineTarget(baseline);
+  const tokenRules = designTokens(tokenFiles(tokens));
+  return {
+    ...rest,
+    extends: [peer("stylelint-config-standard")],
+    plugins: [peer("stylelint-plugin-use-baseline")],
+    rules: {
+      ...CONVENTION_CHANGES,
+      ...SELECTOR_COMPLEXITY,
+      "plugin/use-baseline": [true, { available }],
+      ...tokenRules.rules,
+      ...rules
+    },
+    overrides: [
+      { files: [...MARKUP], customSyntax: peer("postcss-html") },
+      { files: [...HTML_AND_ASTRO], rules: { "declaration-block-single-line-max-declarations": null } },
+      ...tokenRules.overrides,
+      ...overrides
+    ]
+  };
+}
+export {
+  MARKUP,
+  defineConfig
+};

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/configs/native-settings.md

@@ -13,9 +13,11 @@ A consuming repository puts each setting in the file its tool reads, and no mani
 | `.github/workflows/*.yml` | Pull request commands, scheduled commands, runner labels | GitHub Actions and `checks-ci-wiring` |
 | `oxlint.config.ts` | Effect paths and their exemptions, ignore patterns, and any rule or budget the repository sets over the kit's defaults | oxlint and `checks-effect-scope` |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
+| `stylelint-suppressions.json` | The existing violations stylelint suppresses, per file and rule | stylelint, `checks-frontend-syntax` and `checks-suppressions-ratchet` |
 | `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
 | `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
 | `knip.config.ts` | The `entry` globs Knip traces unreferenced files from | Knip, `checks-unused` and `checks-exports` |
+| `stylelint.config.ts` | The Baseline target, the token files, and any stylelint rule the repository sets over the kit's families | `checks-frontend-syntax` |
 | `dependency-cruiser.config.ts` | Entry points nothing imports, paths that may import dev dependencies, and import boundaries, when the kit's defaults do not fit | `checks-imports` |
 | `tsconfig.json` | Compiler options, and the Effect language service plugin whose `overrides` and kit severities `checks-effect-scope` writes, keeping every other key | TypeScript and Effect language service |
 | `package.json` | `scripts` with the `checks-vendor` arguments in `prepare`, `author` and `contributors` | Bun, `checks-commit-identity` and `checks-vendor` |
@@ -29,7 +31,7 @@ A page whose front matter sets `audience: consumers` names commands that a consu
 
 ## The config builders
 
-The kit ships a `defineConfig` for oxlint, Knip and dependency-cruiser.
+The kit ships a `defineConfig` for oxlint, Knip, dependency-cruiser and stylelint.
 Each takes the tool's own config type, less the keys the kit owns, and returns the whole config with a default for every kit rule.
 A key only the repository knows has no default, so `tsc` refuses a config that leaves it out.
 The builder throws when the tool loads such a config anyway.
@@ -39,6 +41,7 @@ The builder throws when the tool loads such a config anyway.
 | `@avi2dg/checks/oxlint` | `effect` | `extends`, `plugins`, `jsPlugins` and `categories` |
 | `@avi2dg/checks/knip` | `entry`, where `[]` means the package scripts and tests name every entry | `include` |
 | `@avi2dg/checks/dependency-cruiser` | nothing | `extends` |
+| `@avi2dg/checks/stylelint` | `baseline` and `tokens`, where `false` leaves the design token rules off | `extends` and `plugins` |
 
 A repository whose sources are Effect programs writes `oxlint.config.ts`:
 
@@ -75,7 +78,16 @@ export default defineConfig({ devOnly: ["^(?:evals|tests)/"] });
 ```
 
 [The dependency rules](dependency-rules.md) lists its keys.
-`tsconfig.json` keeps the three config files in its program, so `bun run typecheck` holds them to the builders' types.
+
+A repository that declares `frontend-syntax.json` writes `stylelint.config.ts`, which [checks-frontend-syntax](../gates/checks-frontend-syntax.md) loads and describes:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/stylelint";
+
+export default defineConfig({ baseline: "widely", tokens: false });
+```
+
+`tsconfig.json` keeps the config files in its program, so `bun run typecheck` holds them to the builders' types.
 
 ## Size limits
 
@@ -108,4 +120,5 @@ overrides: [{ files: ["src/lib/server.ts"], rules: { "max-lines": ["error", { ma
 - [The dependency rules](dependency-rules.md)
 - [checks-ci-wiring](../gates/checks-ci-wiring.md)
 - [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md)
+- [checks-frontend-syntax](../gates/checks-frontend-syntax.md)
 - [checks-docs](../gates/checks-docs.md)

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.
@@ -301,7 +302,12 @@ So a product opts in by declaring `browser-checks.json`, `checks-lint` never sta
 `checks-frontend-syntax` needs no browser and runs inside `checks-lint`, but only where `frontend-syntax.json` declares its inputs, since a repository with no interface has no CSS to hold to it.
 
 Each check wraps a detector that already works rather than a rule of the kit's own.
-The syntax gate runs two of stylelint's built-in rules, `axe` runs axe-core and `nesting` runs one html-validate rule.
+The syntax gate runs two of stylelint's built-in rules and the stylelint team's shared configs, `axe` runs axe-core and `nesting` runs one html-validate rule.
+Its Baseline family runs `stylelint-plugin-use-baseline`, the one stylelint rule that judges against the Baseline data rather than a browser list.
+Its design token family is stylelint's own colour and value rules, applied outside the files a repository names as its tokens.
+A check of the rendered page against declared tokens would need a token format of the kit's own.
+The repository's `stylelint.config.ts` sets the Baseline target and the token files, since only the repository knows either.
+The gate imports that file itself, because stylelint's config loader calls `typescript.findConfigFile`, which TypeScript 7 lacks, and a JavaScript config is what [checks-no-plain-js](gates/checks-no-plain-js.md) refuses.
 The `layout`, `keyboard` and `motion` probes are the website's own browser tests, generalized after they held on its English and Russian pages.
 A zoom-disabling viewport is judged by axe on the rendered page, because stylelint reads only CSS and html-validate has no rule for the viewport's content.
 
@@ -315,6 +321,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-comment-gate.md

@@ -10,6 +10,8 @@ audience: consumers
 
 It fails when an added line carries a banned comment.
 It refuses a machine-read directive, a record or ticket pointer, a doc block, and a file opening with a rationale block over three lines, licence headers excepted.
+The directives are `@ts-expect-error`, `@ts-ignore`, `biome-ignore`, `prettier-ignore`, and every directive that begins `eslint-disable` or `stylelint-disable`, such as `stylelint-disable-next-line`.
+A stylesheet keeps its count of existing stylelint problems in `stylelint-suppressions.json` instead, as [checks-frontend-syntax](checks-frontend-syntax.md) says.
 Each refusal says what to write instead.
 Only added lines are checked, so a violation in a file the diff never touches stays silent.
 A refusal counts when any line of the comment carrying it was added.

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)