@avi2dg/checks 0.63.1 → 0.65.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.65.0
+
+Released 2026-11-03.
+
+### Features
+
+- **ci-wiring:** one CI run per pull request, refuse schedules and long jobs [#41](https://github.com/avi2d/checks/pull/41)
+
+## 0.64.0
+
+Released 2026-11-03.
+
+### Features
+
+- **testing:** shard the night mutation run and file each missing report [#27](https://github.com/avi2d/checks/pull/27)
+
 ## 0.63.1
 
 Released 2026-11-03.

package/docs/bins.md

@@ -44,15 +44,14 @@ The night-run workflow runs them with `checks-lint --night`, which hands each ra
 These bins run on their own:
 
 - [`checks-test`](gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip without a reason at its test site.
-- [`checks-flake`](gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
+- [`checks-flake`](gates/checks-flake.md) runs the suite when started by hand and records the seeds a flaky test fails with.
 - [`checks-mutation`](gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
 - [`checks-mutation-baseline`](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`](gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
 - [`checks-subsumed-tests`](gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
-- [`checks-night-run`](gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell, each failing test, and each failed nightly gate.
-  It closes the issue of a test or gate that a later night no longer reports.
-  It comments on a mutation issue a later night no longer reports, and leaves it open.
+- [`checks-night-run`](gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell, each failing test, each failed nightly gate, and each missing mutation report.
+  It closes the issue of a test, a gate or a missing mutation report that a later night no longer reports, and it comments on a mutation issue it no longer reports without closing it, but only when a previous night exists and every requested mutation report is present.
 - [`checks-changelog`](gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.

package/docs/design.md

@@ -204,7 +204,8 @@ A daily release pull request would leave each merged change unpublished until a
 Only then does it move `main` to it without a force, so `main` only ever gains a release commit whose checks passed.
 It tags the commit it landed and nothing else.
 A repository that is no package keeps the release pull request, and it opens only when someone runs the workflow.
-No release runs on a schedule, in a package or not, since a schedule cuts releases no one asked for.
+Only a public package that publishes to npm may release on a schedule, at most once a day.
+A schedule elsewhere cuts releases no one asked for.
 `checks-release-pr` writes only to the `release/<branch>` branch it owns, and rebuilds that branch on `main` rather than merging `main` into it, so the changelog it carries is the one the build writes.
 `checks-release-tag` writes only the `v*` tag of a release commit that already landed.
 The `github-release` job's `contents: write` creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
@@ -281,7 +282,7 @@ A group or other write bit fails the run, because another user could have edited
 
 `checks-advisories` compares the advisories at both ends of a range instead of failing on every advisory at the head.
 An advisory published against a package that landed a month earlier would otherwise fail every open pull request, including one that touches only docs.
-The scheduled `--all` run finds those advisories, and `advisory-acks.json` carries the ones a repository accepts for a while.
+The weekly `--all` run finds those advisories, and `advisory-acks.json` carries the ones a repository accepts for a while.
 
 The gate runs OSV-Scanner rather than Trivy, Grype or `bun audit`.
 Trivy 0.74.0 reads a nested `bun.lock` entry such as `mkdirp/minimist` under a name no advisory carries, so it misses every package bun nests.

package/docs/gates/checks-advisories.md

@@ -14,7 +14,7 @@ It ignores aliases, because two live advisories can list each other as aliases.
 An advisory published against a package the base already held shows at both ends, so it fails no range, and `--all` reports it instead.
 Each failure names the package, its version, the advisory id, its severity and its summary.
 A range that leaves `bun.lock` unchanged runs no scan.
-A run `checks-lint` starts defers the scan to the scheduled `--all` run instead, so the desk and the pull request neither fetch the database nor scan.
+A run `checks-lint` starts defers the scan to the weekly `--all` run instead, so the desk and the pull request neither fetch the database nor scan.
 It also holds `advisory-acks.json` to the rules in [The acknowledgement file](#the-acknowledgement-file) on every run.
 
 ## What it reads
@@ -63,7 +63,7 @@ An entry whose `until` falls more than 30 days after that moment fails the run a
 Once that moment passes `until`, the entry fails every run until it is deleted or renewed with a later `until`, whether or not the range touches `bun.lock`.
 Delete it once the package is upgraded.
 When a scan runs, an entry that matches no advisory at the head fails, so the file holds only live entries.
-A deferred run still holds each entry to its day, while an entry that matches nothing waits for the scheduled run.
+A deferred run still holds each entry to its day, while an entry that matches nothing waits for the weekly run.
 A file that does not decode as that list exits 2.
 
 ## Arguments
@@ -99,18 +99,20 @@ advisories: 1 acknowledgement(s) in advisory-acks.json do not hold:
 ## When it runs
 
 `checks-lint` runs it over each pull request's range in a repository that tracks `bun.lock`, as [checks-lint](checks-lint.md) says.
-That run defers the scan to the scheduled run, so it fetches no database and reports the deferral instead of a verdict.
+That run defers the scan to the weekly run, so it fetches no database and reports the deferral instead of a verdict.
 A range that leaves `bun.lock` unchanged runs in under a second, and a direct run over a range that changes `bun.lock` scans for about 10 seconds on a warm cache.
 
 ## Running it on a schedule
 
-A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those.
-A consuming repository pins advisories between 05:00 and 06:00 UTC at a minute chosen so repositories do not start together:
+A range never fails on an advisory published after its package landed, so a weekly `--all` run finds those.
+Only a public repository that publishes its package to npm runs it on a schedule, as [checks-ci-wiring](checks-ci-wiring.md#schedules) requires.
+Any other repository starts the same workflow by hand with `gh workflow run`, with no `schedule` trigger.
+A package scans on Monday between 05:00 and 06:00 UTC, at a minute chosen so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "15 5 * * *"
+    - cron: "15 5 * * 1"
   workflow_dispatch:
 jobs:
   advisories:

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

@@ -86,7 +86,8 @@ Each refusal names the workflow file and line, the version found and where it wa
 
 ### Release schedule
 
-It refuses a workflow that triggers on `schedule` and releases, in every repository, whether or not it publishes to npm.
+It refuses a workflow that triggers on `schedule` and releases, unless the repository is a public package that publishes to npm.
+That release runs at most once a day.
 A workflow releases when a run step calls `checks-release-pr`, `checks-release-push`, `checks-release-tag` or `checks-release-publish`.
 A call counts directly, through `bunx`, or through `bun` or `bun run` with the bin's path or its source file.
 A call through a `package.json` script counts, as `bun run <script>` where the named script releases.
@@ -94,12 +95,34 @@ A call through a local reusable workflow counts, as a job that uses a file under
 A call through a repository shell script counts, as a path inside the repository whose file releases.
 A workflow also releases when a run step publishes to npm, as [checks-release-preflight](checks-release-preflight.md) reads it, directly or through one of those paths.
 Text that only names a release bin, such as an `echo`, never counts.
-A release runs when someone starts it, as [checks-release-pr](checks-release-pr.md#when-it-runs) says.
-Each refusal names the workflow file and the line of its `schedule` trigger.
+A repository publishes to npm when one of its workflows runs `npm publish` or `checks-release-publish`, the same ways a release call counts, and its `package.json` does not set `private` to `true`.
+A run outside CI cannot read whether the repository is private, so there it refuses only for the `package.json` field or the missing publish step.
+A daily release has one `cron` entry with one minute and one hour.
+Any other release runs when someone starts it, as [checks-release-pr](checks-release-pr.md#when-it-runs) says.
+Each refusal names the workflow file, the line of its `schedule` trigger and what to change.
+
+### Schedules
+
+It refuses every other workflow that triggers on `schedule`, since a test, mutation, flake, browser or night run starts only by hand, with `gh workflow run`.
+The one schedule it keeps is a weekly advisory scan in a public repository whose `package.json` does not set `private` to `true`.
+A workflow scans advisories when a run step calls `checks-advisories`, the same ways a release call counts, and every other run step is a `bun install`.
+A weekly scan has one `cron` entry with one minute, one hour and one weekday, and `*` for the day of the month and the month.
+It refuses an advisory scan that runs more often, and any scheduled advisory scan in a private repository or a package that sets `private`.
+A run outside CI cannot read whether the repository is private, so it refuses a scan there only for the `package.json` field or the cron.
+A workflow that releases on a schedule is judged only by the release rule above.
+Each refusal names the workflow file, the line of its `schedule` trigger and what to change.
+
+### Job timeouts
+
+Every job sets `timeout-minutes` to a number of at most 60, so no job runs for hours.
+A job without one would hold its runner for GitHub's 360-minute default when a step hangs.
+It refuses a job that sets no `timeout-minutes`, sets more than 60, or sets an expression it cannot read before the run.
+A job that calls a reusable workflow with `uses` sets no timeout, and the called workflow's jobs are judged in their own file.
+Each refusal names the workflow file, the job and the limit.
 
 ## What it reads
 
-The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
+The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts`, `private` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
 It reads each file a setup-bun step names for its version.
 It reads the fleet pin from the kit's own `.bun-version`.
 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.
@@ -115,7 +138,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, or a workflow that releases runs on a schedule. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, or a job can run for more than 60 minutes. |
 | 2 | A workflow or `package.json` cannot be decoded, or the kit's own `.bun-version` is missing, unreadable or blank. |
 
 ## Sample output
@@ -142,11 +165,26 @@ ci-wiring: 1 reference(s) name a missing workflow or job:
   .github/workflows/daily-release.yml line 31: names missing workflow commitlint.yml
 ```
 
-A workflow that releases on a schedule produces a report like this:
+A workflow that releases on a schedule in a repository that publishes nothing to npm produces a report like this:
 
 ```
 ci-wiring: 1 workflow(s) release on a schedule:
-  .github/workflows/daily-release.yml line 3: drop the schedule, so a release runs only when someone starts it
+  .github/workflows/daily-release.yml line 3: only a public package that publishes to npm releases on a schedule; drop the schedule, so a release runs only when someone starts it
+```
+
+A scheduled test run and a daily advisory scan produce a report like this:
+
+```
+ci-wiring: 2 workflow(s) run on a schedule:
+  .github/workflows/advisories.yml line 3: the advisory scan runs more than once a week; keep one cron at a minute, an hour and a weekday, such as "15 5 * * 1"
+  .github/workflows/night-run.yml line 4: drop the schedule, so it runs only when someone starts it with gh workflow run
+```
+
+A job that sets no timeout produces a report like this:
+
+```
+ci-wiring: 1 job(s) can run for hours:
+  .github/workflows/ci.yml job checks: the job sets no timeout-minutes, so a hung run holds its runner for GitHub's 360 minute default; set timeout-minutes to a number of at most 60
 ```
 
 ## When it runs

package/docs/gates/checks-flake.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-flake
 
-`checks-flake` is the scheduled run that finds flaky tests and records the seeds each one fails with.
+`checks-flake` is the run someone starts by hand that finds flaky tests and records the seeds each one fails with.
 
 ## What it checks
 
@@ -100,21 +100,20 @@ Rerunning a seed with bun test --randomize --seed=<seed> --parallel=4 reproduces
 
 ## When it runs
 
-Only a schedule the repository writes runs it.
+Only a workflow the repository starts by hand runs it.
 
-## Running it on a schedule
+## Running it by hand
 
-A repository runs it on a schedule and keeps the record of a failed run as an artifact.
-A repository schedules it at minute 27 of its tier's 30 minute night window, so repositories do not start together:
+A repository runs it from a workflow someone starts with `gh workflow run`, and keeps the record of a failed run as an artifact.
+The workflow holds no schedule, since [checks-ci-wiring](checks-ci-wiring.md#schedules) refuses one:
 
 ```yaml
 on:
-  schedule:
-    - cron: "27 22 * * *"
   workflow_dispatch:
 jobs:
   flake:
     runs-on: ubuntu-latest
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2

package/docs/gates/checks-lint.md

@@ -18,7 +18,7 @@ A test file classifies as TypeScript, so its change runs every applicable gate t
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 `checks-lint-coverage` and `checks-graphwalk` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
-`checks-lint` defers its scan to the scheduled run, so the desk and the pull request fetch no database.
+`checks-lint` defers its scan to the weekly run, so the desk and the pull request fetch no database.
 `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.
 `checks-css-size` begins running when the repository tracks a `*.css` file.

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

@@ -38,7 +38,7 @@ Stryker writes no source without mutants into the report, so a mutated source th
 When a unit test changed, each such source that exists at `HEAD` enters the scope.
 A change under `tests/e2e/` changes no unit test, so it needs no baseline report.
 The scope trusts the coverage edges of the latest full baseline.
-So a helper, fixture or preload changed on `main` since that baseline can hide a lost kill until the scheduled full baseline refreshes.
+So a helper, fixture or preload changed on `main` since that baseline can hide a lost kill until the next full baseline refreshes.
 
 ## What it reads
 

package/docs/gates/checks-mutation.md

@@ -98,6 +98,7 @@ jobs:
       contents: read
       actions: read
     runs-on: [self-hosted, gpu, x64]
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v5
         with:

package/docs/gates/checks-night-run.md

@@ -4,13 +4,13 @@ audience: consumers
 ---
 # checks-night-run
 
-`checks-night-run` turns a night run on `main` into GitHub issues, one for each file whose mutation score fell, one for each failing test, and one for each failed nightly gate.
-It closes the issue of a test or gate that a later night no longer reports.
-It comments on a mutation issue a later night no longer reports, and leaves it open.
+`checks-night-run` turns each finding of a night run on `main` into a GitHub issue.
+A finding is a file whose mutation score fell, a failing test, a failed nightly gate or a missing mutation report.
+It closes the issue of a test, gate or missing mutation report that a later night no longer reports, and it comments on a mutation issue it no longer reports without closing it, but only when a previous night exists and every requested mutation report is present.
 
 ## What it checks
 
-It scores each file of tonight's Stryker report as Stryker does, the `Killed` and `Timeout` mutants over every mutant but the `Ignored`, `CompileError`, `RuntimeError` and `Pending` ones.
+It scores each file of tonight's Stryker reports as Stryker does, the `Killed` and `Timeout` mutants over every mutant but the `Ignored`, `CompileError`, `RuntimeError` and `Pending` ones.
 It compares each file's score with the same file's score from the previous night.
 A file whose score is lower than the previous night's is a finding.
 A file only one night holds is no finding, since it lacks one of the two scores.
@@ -22,7 +22,10 @@ A log where every named gate is undecided files `checks-lint` itself, with no pe
 A log with no passing run and no named gate files `checks-lint` itself, so a gate run that never finished still reaches an issue.
 A file whose test worker crashed is one finding, since Bun reports none of its tests.
 With no previous night it compares no score and still files each failing test.
+Each mutation report `--mutation` names that does not exist is a finding, since the mutation job that writes it failed, timed out or was cancelled.
 With no mutation report it compares and records no score and still files each failing test.
+With some mutation reports missing it compares the files the others hold and records no score.
+The next night then compares every file with the last night that scored them all.
 
 Each finding has a key that stays the same from night to night:
 
@@ -32,6 +35,7 @@ Each finding has a key that stays the same from night to night:
 | a failing test | `test:<file> > <describe> > <name>` |
 | a file whose test worker crashed | `test:<file>` |
 | a nightly gate that failed | `gates:<gate>` |
+| a missing mutation report | `mutation-report:<path>` |
 
 ## How it files a finding
 
@@ -42,15 +46,14 @@ Any other finding opens one issue labelled `night-run`.
 The issue and the comment name tonight's run, the file and the test, the score of both nights or the failed gate.
 The body holds the file, the full test name or the failed gate, and the finding key.
 A title longer than GitHub's 256 characters is cut to at most 256 and ends in `…`.
-A night with no finding creates no label and opens no issue.
-It still reads the open issues, to close or comment on each one whose finding is gone.
+A night with no finding creates no label and writes no issue, and only reads the open issues to close any test, gate or mutation-report issue whose finding is gone and, when a previous night exists and every requested mutation report is present, to comment on any mutation issue whose finding is gone.
 Closing an issue ends it, and the same finding on a later night opens a new one.
 
 ## How it closes an issue
 
-An open test or gate issue whose key tonight's findings lack gets one comment naming tonight's run and the key.
+An open test, gate or mutation-report issue whose key tonight's findings lack gets one comment naming tonight's run and the key.
 It then closes as completed.
-An open mutation issue whose key tonight's findings lack gets one comment that names tonight's run and the key, and stays open.
+When a previous night exists and every requested mutation report is present, an open mutation issue whose key tonight's findings lack gets one comment that names tonight's run and the key, and stays open.
 A closed issue is no longer read, so a later night without the finding comments on it no more.
 A comment that reports the finding carries a reported marker, and a note that a mutation finding is gone carries a noted marker.
 A mutation issue whose latest marked comment already notes the finding gone gets no further note.
@@ -63,13 +66,14 @@ It judges a key only from a report it read tonight:
 | `test:<file> > <describe> > <name>` | tonight read a JUnit report, the test is not failing, and `<file>`'s worker did not crash |
 | `test:<file>` | tonight read a JUnit report and `<file>`'s worker did not crash |
 | `gates:<gate>` | tonight read a lint log that passes or names its failed gates, and `<gate>` is not among them |
+| `mutation-report:<path>` | tonight read the mutation report at `<path>` |
 | `mutation:<file>` | never |
 
 A crashed worker loses every result of its file, so the issue of a test in that file stays open.
 A lint log that is undecided or never finished says nothing of any one gate, so every gate issue stays open.
 A mutation finding is a fall from one night to the next.
 A later night that does not fall again still holds the lower score.
-A night that compared scores comments on the mutation issue without closing it, since a score can recover and drop again.
+Only a night that compared scores with every requested mutation report present comments on the mutation issue without closing it, since a score can recover and drop again.
 So a person closes a mutation issue once the score is back.
 An issue with no key in its body is never read, so a person's issue under the `night-run` label is never commented on or closed.
 A run off `main` comments on and closes no issue.
@@ -78,24 +82,24 @@ A run on any ref but `refs/heads/main` files no issue and records no score, and
 
 ## What it reads
 
-It reads tonight's Stryker `mutation.json` report, when the mutation run left one, and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
+It reads tonight's Stryker `mutation.json` reports and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
 It reads the lint log `--gates` names for the `gate(s) failed:` line `checks-lint --night` prints.
 It scans the newest 30 successful runs of the same workflow on `main` from newest to oldest.
 It takes the first run whose `night-run` artifact still exists as the previous night.
 That artifact holds `night-run.json`, the scores the run recorded.
 When no scanned run holds the artifact it compares no score.
 A run on another branch never becomes the previous night.
-On `main` with a mutation report it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
+On `main` with every mutation report present it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
 It reads the run from `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_RUN_ID`, `GITHUB_WORKFLOW_REF` and `GITHUB_REF`, so it runs only inside a GitHub Actions job.
 It calls `gh` with the job's `GH_TOKEN`, which needs `actions: read` for the previous night and `issues: write` for the issues.
 
 ## Arguments
 
 ```sh
-checks-night-run [--mutation <mutation-report>] [--tests <junit-report>]... [--gates <lint-log>]
+checks-night-run [--mutation <mutation-report>]... [--tests <junit-report>]... [--gates <lint-log>]
 ```
 
-`--mutation` names tonight's Stryker report and is given at most once.
+`--mutation` names one of tonight's Stryker reports and is given once per report the workflow's mutation jobs write, whether or not each job wrote it.
 `--tests` names one JUnit report and is given once per report.
 `--gates` names tonight's `checks-lint --night` log and is given at most once.
 At least one report is given.
@@ -123,15 +127,14 @@ checks-night-run: recorded 42 file score(s) in reports/night-run.json
 
 Only a night workflow the repository writes runs it, after that workflow's full mutation run, its long test tiers and its nightly lint gates.
 
-## Running it at night
+## Running it by hand
 
-A repository runs it from a workflow named `night-run` on a schedule, and starts the same workflow by hand with `gh workflow run night-run`:
+A repository runs it from a workflow named `night-run`, which someone starts with `gh workflow run night-run`.
+The workflow holds no schedule, since [checks-ci-wiring](checks-ci-wiring.md#schedules) refuses one:
 
 ```yaml
 name: night-run
 on:
-  schedule:
-    - cron: "7 22 * * *"
   workflow_dispatch:
 permissions:
   contents: read
@@ -156,6 +159,7 @@ jobs:
           retention-days: 1
   tests:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
@@ -172,6 +176,7 @@ jobs:
           retention-days: 1
   gates:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v5
         with:
@@ -190,6 +195,7 @@ jobs:
     needs: [mutation, gates, tests]
     if: ${{ !cancelled() && needs.tests.result == 'success' }}
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: read
       actions: read
@@ -200,10 +206,9 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - if: needs.mutation.result == 'success'
-        uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v4
         with:
-          name: night-run-mutation
+          pattern: night-run-mutation
           path: reports/mutation
       - if: needs.gates.result == 'success'
         uses: actions/download-artifact@v4
@@ -216,7 +221,7 @@ jobs:
           path: reports/night-run-tests
       - env:
           GH_TOKEN: ${{ github.token }}
-        run: bunx checks-night-run ${{ needs.mutation.result == 'success' && '--mutation reports/mutation/mutation.json' || '' }} --tests reports/night-run-tests/live.xml --tests reports/night-run-tests/pixel.xml ${{ needs.gates.result == 'success' && '--gates reports/night-run-gates/gates.log' || '' }}
+        run: bunx checks-night-run --mutation reports/mutation/night-run-mutation/mutation.json --tests reports/night-run-tests/live.xml --tests reports/night-run-tests/pixel.xml ${{ needs.gates.result == 'success' && '--gates reports/night-run-gates/gates.log' || '' }}
       - uses: actions/upload-artifact@v4
         with:
           name: night-run
@@ -225,22 +230,23 @@ jobs:
           retention-days: 90
 ```
 
-The cron starts the run at 22:07 UTC, inside the kit's own night window from 22:00 to 22:30 UTC.
-A repository takes minute 7 of its own tier's 30 minute night window, so repositories do not start together.
 The tests job runs each long tier the repository holds, `live` and `pixel` as [checks-test](checks-test.md#test-tiers) names them, and keeps each JUnit report.
 Each `|| true` lets the job go on to the upload after a failing test, since that test becomes an issue.
 A tier that writes no report fails the report job, because `checks-night-run` cannot read it.
 The gates job runs the nightly lint gates and keeps the log, since a failing gate becomes an issue.
 The report job runs whenever the tests job succeeds, so a failing test that also stops Stryker still becomes an issue.
-It passes `--mutation` only when the mutation job succeeded, and the failed mutation job still fails the run.
+It always passes `--mutation`, so a mutation job that failed or timed out leaves a missing report that becomes an issue.
+The download names the artifact by `pattern`, which downloads nothing rather than failing when the artifact is missing.
+A full run too long for one job splits into a matrix of shards.
+Each shard uploads its own artifact under the one pattern, and each report gets its own `--mutation`.
 It passes `--gates` only when the gates job succeeded, and the failed gates job still fails the run.
-The concurrency group queues a run started by hand behind the scheduled one, so two runs never file the same finding twice.
+The concurrency group queues a run behind one already going, so two runs never file the same finding twice.
 A dispatch on a branch runs both jobs and lists its findings in the report job's log, and `if-no-files-found: ignore` lets that run upload no record.
 `issues: write` on the report job is the one permission beyond reading the repository and its runs.
 A public repository keeps `runs-on: ubuntu-latest` on every job.
 A private repository sets `runs-on` on the mutation job to the labels declared under `checks.mutationRunner` in `package.json`, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the tests, gates, and report jobs.
-A successful run uploads `night-run`, so the next night compares with it, and a failed run uploads nothing a later night reads.
+A successful run with every mutation report present uploads `night-run`, so the next night compares with it, and a run that failed or missed a report uploads nothing a later night reads.
 The artifact keeps 90 days, so a gap of nights still leaves a previous night to compare with.
 
 ## Related topics

package/docs/gates/checks-release-notes.md

@@ -62,6 +62,7 @@ permissions:
 jobs:
   preflight:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: read
     steps:
@@ -77,6 +78,7 @@ jobs:
   publish:
     needs: preflight
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v5
         with:
@@ -99,6 +101,7 @@ jobs:
   github-release:
     needs: publish
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:
@@ -130,6 +133,7 @@ permissions:
 jobs:
   preflight:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: read
     steps:
@@ -145,6 +149,7 @@ jobs:
   github-release:
     needs: preflight
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: write
     steps:

package/docs/gates/checks-release-pr.md

@@ -78,8 +78,9 @@ release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d
 
 The `release-pr` workflow below runs it on the default branch when someone starts it with `gh workflow run release-pr`.
 The workflow has no schedule, so a release is cut only when someone asks for one.
+A public package that publishes to npm may add one daily `cron` to it instead, such as `"7 3 * * *"`.
 A package published to npm releases each push to `main` through [checks-release-push](checks-release-push.md) instead, with no pull request.
-[checks-ci-wiring](checks-ci-wiring.md#release-schedule) refuses a schedule on any workflow that releases.
+[checks-ci-wiring](checks-ci-wiring.md#release-schedule) refuses a schedule on any other workflow that releases, and one that runs more than once a day.
 
 ## Running it in CI
 

package/docs/gates/checks-release-push.md

@@ -15,7 +15,7 @@ It refuses when `v<version>` of the next version already tags a commit, since a
 It writes the next version into `package.json` and runs `bun run build`, which writes `CHANGELOG.md`.
 It commits both as `chore: release <version>` on top of `HEAD` through the GitHub API, as `checks-release-pr` does.
 It points the branch `release/<branch>` at that commit and dispatches every check workflow its arguments name there.
-It waits up to 45 minutes in all for those workflows to finish on the release commit.
+It waits up to 22 minutes in all for those workflows to finish on the release commit.
 It reads the newest run of each, so a rerun stands in for the run it repeats.
 A failed read of the runs list does not end the wait.
 The wait retries the read at the same interval.
@@ -26,7 +26,8 @@ When all of them pass, it moves `<branch>` to the release commit without a force
 GitHub refuses that update when `<branch>` moved while the checks ran.
 The run then ends cleanly, since the run of the push that moved it releases the new head.
 When the update fails but `<branch>` already holds the release commit, the update landed and the run goes on.
-It then tags the release commit `v<version>`, pushes the tag and dispatches the release workflow on it, and waits up to 45 minutes for that workflow's run on the release commit to finish.
+It then tags the release commit `v<version>`, pushes the tag and dispatches the release workflow on it.
+It waits up to 22 minutes for that workflow's run on the release commit to finish.
 When that run concludes short of success, or does not finish in time, the bin fails, though `<branch>` already holds the release and the tag exists.
 When `HEAD` is itself a release commit, it tags it as [checks-release-tag](checks-release-tag.md) does, and waits for the release workflow it dispatches the same way.
 So a rerun after a failed tag push finishes the release.
@@ -104,7 +105,7 @@ jobs:
   release:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    timeout-minutes: 120
+    timeout-minutes: 55
     concurrency:
       group: release-push
       cancel-in-progress: false

package/docs/gates/checks-setup.md

@@ -25,6 +25,8 @@ The workflow always runs `bun run lint`, `bun run typecheck` and `bun run test`.
 A `build` script there also brings a `git diff --exit-code` step.
 Other scripts a `package.json` it finds already holds stay, but the workflow never schedules them.
 The workflow always ends with a `bunx checks-commit-title` step for the pull request title.
+It runs on pull requests alone, so a merge to the default branch does not run the suite a second time.
+A newer push to the same pull request cancels the run in progress.
 A `--private` run pins each job to `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
 Setting the `CI_RUNS_ON` variable to a self-hosted runner label then lands the jobs there.
 A public run pins each job to `ubuntu-latest`.

package/docs/gates/checks-test.md

@@ -45,13 +45,14 @@ A skipped test or a todo without `skipReason` fails in every environment.
 ## What it reads
 
 `checks-test` reads test source files and the JUnit report written by its own run.
+A pull request run also reads the event file, the git history between the base and the head, the tracked sources, `package.json` and `bunfig.toml`.
 It reads no skip list from `package.json`, only the smoke list.
 It counts a run as `ci` when `CI` is true and as `local` otherwise.
 A local run covers `./tests/unit` plus the smoke list the repository declares.
 The smoke list lives in `package.json` under `checks.smoke` as an array of test file paths.
 A repository with no smoke list runs the unit tier alone outside CI.
 A local run with no unit test and no smoke list runs nothing and passes.
-A `ci` run covers the full default suite.
+A `ci` run covers the full default suite, unless a pull request narrows it, as [Pull request runs](#pull-request-runs) says.
 A smoke entry that names no test file fails the run.
 A smoke entry under `tests/quarantine/`, `tests/live/` or `tests/pixel/` fails the run, since Bun's ignored paths would drop it.
 
@@ -71,6 +72,32 @@ A unit or e2e run keeps Bun's ignored paths, runs only `./tests/unit` or `./test
 
 Files under `tests/quarantine/` are not run or judged, as [checks-test-layout](checks-test-layout.md) says.
 
+## Pull request runs
+
+A `ci` run on a `pull_request` event runs only the test files the pull request reaches.
+It reads the base and head from the event file `GITHUB_EVENT_PATH` names and the changed paths since their merge base from git.
+A test reaches a changed file when it imports it, names its path, runs its `package.json` bin or imports the package by name.
+A test also reaches a file through a test helper or a source that reaches it, at any depth.
+A source reaches only what it imports, so a registry that lists every bin's path does not make each of its importers reach every bin.
+A test that names a fixture's directory reaches each fixture under it.
+A changed test always reaches itself.
+
+A shared file runs the whole suite instead:
+
+- a lockfile, `package.json`, a `*.config.*` or `tsconfig` file, `bunfig.toml`, or a tool pin such as `.bun-version`
+- a file Bun preloads into every test, or a file a preload imports
+- a test helper, which is a file under `tests/` that is neither a test nor a fixture
+- a stylesheet, a font, or a layout under `layouts/` or named `layout.*`
+
+A dependency bump changes `package.json` or the lockfile, so it runs the whole suite in every repository.
+A workflow under `.github/` is not a shared file, since the suite runs under it rather than reading it.
+A pull request that changes no file a test reaches runs no test and passes.
+The run names how many test files it reached, or which shared file made it run the whole suite.
+A change whose paths cannot be read runs the whole suite.
+A run on any other event, such as `workflow_dispatch` for a release, runs the whole suite.
+`--full` and the live and pixel tiers always run whole.
+A narrowed run judges only the skips the files it ran declare.
+
 ## Test tiers
 
 Tests that need a live machine go in `tests/live/`, and tests that need a screen go in `tests/pixel/`.

package/docs/how-to/set-up-a-repository.md

@@ -83,9 +83,13 @@ To run the gates in CI:
    ```yaml
    on:
      pull_request:
+   concurrency:
+     group: ci-${{ github.event.pull_request.number }}
+     cancel-in-progress: true
    jobs:
      checks:
        runs-on: ubuntu-latest
+       timeout-minutes: 30
        steps:
          - uses: actions/checkout@v5
            with: