@avi2dg/checks 0.38.1 → 0.40.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.40.0
+
+Released 2026-10-11.
+
+### Features
+
+- **delivery:** fold title lint into the ci job and trim docs-only runs [#146](https://github.com/avi2d/checks/pull/146)
+
+## 0.39.0
+
+Released 2026-10-11.
+
+### Features
+
+- **testing:** prune superseded mutation baselines after main uploads [#144](https://github.com/avi2d/checks/pull/144)
+
 ## 0.38.1
 
 Released 2026-10-11.

package/README.md

@@ -117,7 +117,33 @@ To consume the kit from a repository:
          - run: bun run test
    ```
 
-Add a pull request title lint step in another workflow using `./node_modules/.bin/commitlint`.
+Lint the pull request title in the same job with one step:
+
+   ```yaml
+         - id: title
+           name: lint the title
+           env:
+             PR_TITLE: ${{ github.event.pull_request.title }}
+             GH_TOKEN: ${{ github.token }}
+           run: bunx checks-commit-title
+   ```
+
+A repository whose branch protection requires `commitlint` keeps that required status name while `commitlint.yml` goes away.
+The same job reports the title step's outcome under that name on every run, which needs `statuses: write`:
+
+   ```yaml
+         - name: report the title as commitlint
+           if: always()
+           env:
+             GH_TOKEN: ${{ github.token }}
+             HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+             OUTCOME: ${{ steps.title.outcome }}
+           run: |
+             state=failure
+             if [ "$OUTCOME" = success ]; then state=success; fi
+             gh api "repos/$GITHUB_REPOSITORY/statuses/${HEAD_SHA:-$GITHUB_SHA}" -f state="$state" -f context=commitlint -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --silent
+   ```
+
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](docs/gates/checks-ci-wiring.md#runners) requires.
 `checks-effect-scope` writes the Effect paths of `oxlint.config.ts` and the kit's severities into `tsconfig.json`, as [The Effect rules](docs/configs/effect-rules.md#language-service) says.
 `bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
@@ -157,7 +183,7 @@ These bins run on their own:
 - [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
 - [`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`, through a cache on a self-hosted runner.
+- [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, through a cache on a self-hosted runner, and deletes superseded baselines after a `main` upload.
 - [`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.
@@ -166,9 +192,11 @@ These bins run on their own:
 - [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
 - [`checks-browser`](docs/gates/checks-browser.md) opens a product's built pages in Chrome and fails on the layout, keyboard, motion, accessibility, nesting and asset checks its `browser-checks.json` declares.
+- [`checks-commit-title`](docs/gates/checks-commit-title.md) lints the pull request title in one step of the `ci` job.
+- [`checks-docs-only`](docs/gates/checks-docs-only.md) tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full run.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.
-oxlint and commitlint run through their own tools, as the pages under Related topics say.
+oxlint runs through its own tool, as the pages under Related topics say.
 
 ## Upgrade
 

package/docs/configs/commit-messages.md

@@ -14,20 +14,26 @@ It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-convent
 ## Workflow
 
 The lint runs in CI on pull requests, because `jj` never fires a git hook.
-Each repository owns `.github/workflows/commitlint.yml` and runs the installed `commitlint` binary in a pull request step.
+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 `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.
 
 ## What it lints
 
 It lints the pull request title and nothing else.
 The title is the enforced subject because a squash merge uses it as the main commit subject, and per-commit messages are not linted.
-GitHub appends ` (#N)` to the squashed subject, so the workflow lints the title with that suffix attached, and the header length limit applies to the landed subject, not the bare title.
-The workflow moves git's comment character off `#`, so a title starting with `#` is linted like any other.
-The workflow also triggers on `workflow_dispatch`, since GitHub holds the `pull_request` runs of a release pull request the workflow token opens until a maintainer approves them, as [checks-release-pr](../gates/checks-release-pr.md) says.
-A dispatched run carries no pull request, so the workflow reads the title of the one open pull request its branch heads, and fails when there is none.
+GitHub appends the pull request number to the squashed subject, so the bin lints the title with ` (#0000)` attached.
+The header length limit applies to the landed subject, not the bare title.
+The bin moves the git comment character off `#`, so a title starting with `#` is linted like any other.
+The `ci` job also triggers on `workflow_dispatch`, as [checks-release-pr](../gates/checks-release-pr.md) says.
+GitHub holds the `pull_request` runs of a release pull request the workflow token opens until a maintainer approves them.
+A dispatched run carries no pull request, so the bin reads the title of the one open pull request its branch heads.
+It fails when there is none.
 That lookup needs the workflow's `pull-requests: read` permission.
-It reports a dispatched run's result on the head commit as a `commitlint` status, since GitHub keeps a dispatched run's check off the pull request.
-The kit's own `.github/workflows/commitlint.yml` shows the step.
+The `commitlint` status covers a dispatched run too, since GitHub keeps a dispatched run's check off the pull request.
+The kit's own `.github/workflows/ci.yml` shows the step.
 
 It never sees a commit's author or committer fields, nor the `Co-authored-by` trailer GitHub writes from a foreign author when it squashes, so it cannot enforce who a commit belongs to.
 [checks-commit-identity](../gates/checks-commit-identity.md) is that enforcement.

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

@@ -8,7 +8,8 @@ audience: consumers
 
 ## What it checks
 
-The kit requires `./node_modules/.bin/commitlint` on every pull request.
+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.
 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`.

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

@@ -0,0 +1,57 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-commit-title
+
+`checks-commit-title` lints the pull request title against the shared commitlint config in one step of the `ci` job.
+
+## What it checks
+
+It lints the pull request title and nothing else.
+The title comes from `PR_TITLE` when the event carries one.
+A dispatched run carries no pull request, so the bin reads the title of the one open pull request its branch heads.
+It fails when there is none.
+A run with no title to lint passes and says so.
+The bin lints the title with ` (#0000)` attached, since GitHub appends the pull request number to the squashed subject.
+It moves the git comment character off `#`, so a title starting with `#` is linted like any other.
+
+## What it reads
+
+It reads `PR_TITLE` and `GITHUB_EVENT_NAME` from the environment.
+A dispatched run also reads `GITHUB_REPOSITORY`, `GITHUB_REPOSITORY_OWNER` and `GITHUB_REF_NAME`, and calls `gh api` with `GH_TOKEN` for the open pull request.
+It lints with the installed kit's commitlint config through the installed commitlint cli, as [The commit message lint](../configs/commit-messages.md) says.
+
+## Arguments
+
+The bin takes no arguments.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The title lints clean, or there is no title to lint. |
+| 1 | The title breaks the rules, or no one open pull request heads the branch. |
+| 2 | The kit config or binary cannot be resolved, or a dispatched run misses its environment. |
+
+## Sample output
+
+```
+⧗   --- input ---
+# feat(lint): add x (#0000)
+✖   subject may not be empty [subject-empty]
+✖   type may not be empty [type-empty]
+
+✖   found 2 problems, 0 warnings
+ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
+```
+
+## When it runs
+
+The `ci` job runs it on `pull_request` and `workflow_dispatch`, as [checks-ci-wiring](checks-ci-wiring.md) requires.
+The job then posts its outcome as a `commitlint` status, as [The commit message lint](../configs/commit-messages.md) says.
+
+## Related topics
+
+- [The commit message lint](../configs/commit-messages.md)
+- [checks-ci-wiring](checks-ci-wiring.md)

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

@@ -0,0 +1,50 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-docs-only
+
+`checks-docs-only` tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full `ci` run.
+
+## What it checks
+
+A change is docs-only when every file it touches is a `.md` file at the top level or under `docs/`, and it touches at least one file.
+Markdown anywhere else, such as a test fixture under `tests/` or a template under `dist/`, keeps the full run.
+A rename counts both sides.
+An empty change and a change with no range keep the full run.
+
+## What it reads
+
+It reads the base and head refs from its arguments.
+It compares their merge base with the head through `git merge-base` and `git diff`.
+
+## Arguments
+
+```sh
+checks-docs-only <base-ref> <head-ref>
+```
+
+With no arguments, the bin reports `docs-only=false`.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The bin classified the change, and the verdict is on stdout. |
+| 2 | The range cannot be decoded. |
+
+## Sample output
+
+```
+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`.
+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.
+
+## Related topics
+
+- [checks-ci-wiring](checks-ci-wiring.md)

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

@@ -4,7 +4,8 @@ audience: consumers
 ---
 # checks-mutation-baseline
 
-`checks-mutation-baseline` restores the newest mutation baseline that `main` published, and on a self-hosted runner it keeps each baseline it downloads so the next job copies it instead.
+`checks-mutation-baseline` restores the newest mutation baseline that `main` published, and deletes superseded baselines after a `main` upload.
+On a self-hosted runner it keeps each baseline it downloads, so the next job copies it instead.
 
 ## What it checks
 
@@ -22,12 +23,23 @@ It takes the report from `mutation.json` at the artifact's root, or else from `m
 
 It creates the directories each destination needs.
 
+With `--prune` it deletes the repository's superseded baselines instead of restoring one.
+It keeps the newest unexpired `mutation-baseline` among the runs the restore reads, and the newest unexpired `mutation-baseline-full` the restore takes first.
+It also keeps the unexpired baselines of the run it runs in, which `GITHUB_RUN_ID` names.
+The restore reads only successful runs, so it takes them once that run succeeds.
+A failed artifact lookup while it picks what to keep stops it before it deletes anything.
+Treating that artifact as absent would delete the one the restore takes.
+It deletes only artifacts with exactly those two names in the repository it runs in.
+It deletes only unexpired artifacts, since the restore never reads an expired one.
+With `--dry-run` it prints what it would delete and what it would keep, and deletes nothing.
+It deletes through `gh`, which needs a token that deletes the repository's Actions artifacts, such as `GH_TOKEN: ${{ github.token }}` with `actions: write`.
+
 ## What it reads
 
 It reads the runs and their artifacts through `gh`, which needs a token that reads the repository's Actions, such as `GH_TOKEN: ${{ github.token }}` with `actions: read`.
 The `mutation-baseline` artifact holds `stryker-incremental.json` and `mutation/mutation.json`, which an upload of `reports/stryker-incremental.json` and `reports/mutation/mutation.json` writes.
 The `mutation-baseline-full` artifact holds `mutation.json` at its root, which an upload of `reports/mutation/mutation.json` alone writes.
-It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache.
+It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache, and `--prune` reads `GITHUB_RUN_ID`.
 
 ## The runner cache
 
@@ -51,9 +63,12 @@ When `HOME` is unset it works the same way, and prints to stderr that the runner
 ```sh
 checks-mutation-baseline <incremental-dest> [mutation-json-dest]
 checks-mutation-baseline --full <mutation-json-dest>
+checks-mutation-baseline --prune [--dry-run]
 ```
 
 `--full` restores only the report of a run that started with no state.
+`--prune` deletes superseded baselines after an upload.
+`--dry-run` lists what `--prune` would delete, and deletes nothing.
 
 ## Exit codes
 
@@ -63,6 +78,11 @@ checks-mutation-baseline --full <mutation-json-dest>
 | 2 | the arguments do not parse, `gh` cannot list the runs, the cache cannot be written, or another job removed the entry before it was copied |
 
 A failed artifact lookup or download prints the `gh` error and moves on, as a missing artifact does.
+With `--prune`, `0` means it deleted the superseded artifacts, found none, or could not delete some.
+`2` means the arguments do not parse, or `gh` cannot list the runs, a run's artifacts or the repository's artifacts.
+A failed delete prints a `::warning::` annotation naming the artifact and the `gh` error, moves on, and the summary names the artifacts it could not delete.
+A failed delete still exits `0`, since a failed step fails the `main` run and the restore then skips the baseline that run uploaded.
+The next `main` run's prune deletes what this one missed.
 
 ## Sample output
 
@@ -72,6 +92,12 @@ mutation-baseline: restored it from the runner's cache, mutation-baseline artifa
 
 A miss prints `downloaded it into the runner's cache` instead, and a hosted runner prints `downloaded it`.
 
+```
+mutation-baseline: deleted artifacts 11542133901, 11553708473, 11632727585; kept mutation-baseline artifact 11670749656 from run 38055231501
+```
+
+With `--dry-run` the summary says what it would delete and what it would keep.
+
 ## When it runs
 
 Only a CI step the repository writes runs it.
@@ -84,6 +110,27 @@ A baseline job restores the state the previous `main` run left before an increme
   run: bunx checks-mutation-baseline reports/stryker-incremental.json
 ```
 
+A baseline job uploads the state the incremental run wrote, then on `main` prunes the superseded baselines:
+
+```yaml
+- uses: actions/upload-artifact@v4
+  with:
+    name: mutation-baseline
+    path: |
+      reports/mutation/mutation.json
+      reports/stryker-incremental.json
+    retention-days: 7
+- name: Prune superseded baselines
+  if: github.ref == 'refs/heads/main'
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: bunx checks-mutation-baseline --prune
+```
+
+The incremental upload keeps 7 days of retention, since the restore reads only the newest `main` run.
+The full upload keeps 30 days, since full runs start weekly.
+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`:
 
 ```yaml

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

@@ -47,7 +47,7 @@ The repository needs **Allow GitHub Actions to create and approve pull requests*
 checks-release-pr <workflow>...
 ```
 
-Each argument names a workflow file under `.github/workflows/` whose jobs report the checks the default branch requires, such as `ci.yml` and `commitlint.yml`.
+Each argument names a workflow file under `.github/workflows/` whose jobs report the checks the default branch requires, such as `ci.yml`.
 Each named workflow triggers on `workflow_dispatch`.
 Name no workflow that runs something else on dispatch, such as a mutation baseline.
 
@@ -63,7 +63,7 @@ Name no workflow that runs something else on dispatch, such as a mutation baseli
 A run that opens the pull request prints the build's own output, then one line:
 
 ```
-release-pr: opened https://github.com/acme/widget/pull/12 to release 0.4.0, and dispatched ci.yml, commitlint.yml on release/main
+release-pr: opened https://github.com/acme/widget/pull/12 to release 0.4.0, and dispatched ci.yml on release/main
 ```
 
 A run on the same `HEAD` the next day prints one line:
@@ -115,7 +115,7 @@ jobs:
       - name: open or refresh the release pull request
         env:
           GH_TOKEN: ${{ github.token }}
-        run: ./node_modules/.bin/checks-release-pr ci.yml commitlint.yml
+        run: ./node_modules/.bin/checks-release-pr ci.yml
   tag:
     if: "github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore: release ')"
     runs-on: ubuntu-latest
@@ -150,8 +150,7 @@ Nothing requires them, and approving them runs the same checks again.
 
 The daily release needs the repository's other workflows to accept the dispatch:
 
-- `.github/workflows/ci.yml` and `.github/workflows/commitlint.yml` trigger on `workflow_dispatch`, grant `statuses: write`, and end each required job with the step below.
-  `commitlint.yml` also grants `pull-requests: read`, which the title lookup needs.
+- `.github/workflows/ci.yml` triggers on `workflow_dispatch`, grants `statuses: write` and `pull-requests: read`, and ends each required job with the step below.
 - The title lint reads the title of the one open pull request its branch heads when the event carries none, as [Commit messages](../configs/commit-messages.md) says.
 - `.github/workflows/release.yml` triggers on `workflow_dispatch` and refuses a ref that is not a tag, as [checks-release-notes](checks-release-notes.md) shows.
 - **Allow GitHub Actions to create and approve pull requests** is on, which the call after the step sets.

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

@@ -8,7 +8,7 @@ audience: consumers
 
 ## What it checks
 
-It reads the subject of `HEAD`, and does nothing unless the subject is `chore: release <version>`, with or without the ` (#N)` a squash merge adds.
+It reads the subject of `HEAD`, and does nothing unless the subject is `chore: release <version>`, with or without the pull request number a squash merge appends.
 It refuses a release commit whose `package.json` holds another version.
 It tags `HEAD` as `v<version>` and pushes the tag to `origin`.
 A tag the workflow token pushes starts no `push` workflow, so it then dispatches the workflow its argument names on the tag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,8 @@
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
     "src/delivery/commit-identity.ts",
+    "src/delivery/commit-title.ts",
+    "src/delivery/docs-only.ts",
     "src/testing/mutation.ts",
     "src/testing/mutation-scope.js",
     "src/testing/mutation-guard-plugin.js",
@@ -132,6 +134,8 @@
     "checks-test": "src/testing/test.ts",
     "checks-flake": "src/testing/flake.ts",
     "checks-commit-identity": "src/delivery/commit-identity.ts",
+    "checks-commit-title": "src/delivery/commit-title.ts",
+    "checks-docs-only": "src/delivery/docs-only.ts",
     "checks-mutation": "src/testing/mutation.ts",
     "checks-mutation-compare": "src/testing/mutation-compare.ts",
     "checks-mutation-baseline": "src/testing/mutation-baseline.ts",

package/src/delivery/ci-wiring.ts

@@ -11,6 +11,7 @@ export type { Command };
 export type Gate = {
   readonly command: string;
   readonly words: Command;
+  readonly alternatives: readonly Command[];
 };
 
 export type Declaration = {
@@ -63,7 +64,10 @@ export class WiringError extends Schema.TaggedError<WiringError>()("WiringError"
 const WORKFLOWS = ".github/workflows";
 const SCRIPTED = ["lint", "build", "typecheck", "test"];
 const BUILT_TREE = "git diff --exit-code";
-const TITLE_LINT = "./node_modules/.bin/commitlint";
+const TITLE_LINT = "bunx checks-commit-title";
+// The gate holds until every consumer migrates, so the direct commitlint call still counts.
+// The kit calls its own file through bun, since bunx never resolves the working tree.
+const TITLE_CALLS = ["bun src/delivery/commit-title.ts", "./node_modules/.bin/commitlint"];
 const Manifest = Schema.Struct({ scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)) });
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
@@ -207,6 +211,7 @@ function gapsAmong(gates: readonly Gate[], steps: readonly RunStep[], lintGates:
     const entryPoint = entryPointCommand(gate.words, lintGates);
     const commands = [
       { command: gate.command, words: gate.words },
+      ...gate.alternatives.map((words) => ({ command: gate.command, words })),
       ...(entryPoint === undefined ? [] : [{ command: entryPoint.join(" "), words: entryPoint }]),
     ];
     const invoking = steps.flatMap(({ location, blocker, script }) => {
@@ -258,7 +263,11 @@ export function requiredCommands(scripts: readonly string[]): readonly string[]
 
 export function declarationFor(scripts: readonly string[], branch: string): Declaration {
   return {
-    gates: requiredCommands(scripts).map((command) => ({ command, words: command.split(" ") })),
+    gates: requiredCommands(scripts).map((command) => ({
+      command,
+      words: command.split(" "),
+      alternatives: command === TITLE_LINT ? TITLE_CALLS.map((call) => call.split(" ")) : [],
+    })),
     defaultBranch: branch,
     lintGates: KIT_GATES,
   };

package/src/delivery/commit-title.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
+import { collect } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+
+const NAME = "commit-title";
+
+class TitleSetup extends Schema.TaggedError<TitleSetup>()("TitleSetup", {
+  message: Schema.String,
+}) {}
+
+const setup = (message: string): TitleSetup => new TitleSetup({ message });
+
+// The cli entry stays inside its own package, so this resolves from the install cache as well as node_modules.
+const cliOf = Effect.fn("cliOf")(function* () {
+  const entry = yield* Effect.try({
+    try: () => new URL("./cli.js", import.meta.resolve("@commitlint/cli")),
+    catch: () => setup("cannot resolve @commitlint/cli from the installed kit"),
+  });
+  return yield* (yield* Path.Path).fromFileUrl(entry);
+});
+
+// The config ships with the kit, so it sits two levels above this file wherever the kit is installed.
+const configOf = Effect.fn("configOf")(function* () {
+  const file = yield* Effect.try({
+    try: () => new URL("../../commitlint.config.js", import.meta.url),
+    catch: () => setup("cannot resolve commitlint.config.js from the installed kit"),
+  });
+  return yield* (yield* Path.Path).fromFileUrl(file);
+});
+
+const dispatchedTitle = Effect.fn("dispatchedTitle")(function* () {
+  const repository = yield* Config.String("GITHUB_REPOSITORY").pipe(Config.withDefault(""));
+  const owner = yield* Config.String("GITHUB_REPOSITORY_OWNER").pipe(Config.withDefault(""));
+  const ref = yield* Config.String("GITHUB_REF_NAME").pipe(Config.withDefault(""));
+  if (repository === "" || owner === "" || ref === "") {
+    return yield* setup("a dispatched run lints the open pull request its branch heads, so it needs GITHUB_REPOSITORY, GITHUB_REPOSITORY_OWNER and GITHUB_REF_NAME");
+  }
+  // A dispatched run carries no pull request, so the title comes from the one open pull request the branch heads.
+  const found = yield* collect("gh", [
+    "api",
+    `repos/${repository}/pulls?head=${owner}:${ref}&state=open`,
+    "--jq",
+    `if length == 1 then .[0].title else error("no one open pull request heads the branch") end`,
+  ]);
+  const title = found.stdout.trim();
+  if (found.exitCode !== 0 || title === "" || title === "null") {
+    const report = found.stderr.trim() === "" ? found.stdout.trim() : found.stderr.trim();
+    if (report !== "") yield* Console.error(report);
+    return undefined;
+  }
+  return title;
+});
+
+const lintTitle = Effect.fn("lintTitle")(function* (title: string) {
+  const system = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const file = path.join(yield* system.makeTempDirectoryScoped({ prefix: "checks-commit-title-" }), "pr-title");
+  yield* system.writeFileString(file, `${title} (#0000)`);
+  // A title opening with the git comment character lints as empty without this: commentChar moves off the hash.
+  const linted = yield* collect(process.execPath, [yield* cliOf(), "--config", yield* configOf(), "--edit", file], undefined, {
+    env: { GIT_CONFIG_COUNT: "1", GIT_CONFIG_KEY_0: "core.commentChar", GIT_CONFIG_VALUE_0: "\x01" },
+  });
+  if (linted.stdout.trim() !== "") yield* Console.log(linted.stdout.trim());
+  if (linted.stderr.trim() !== "") yield* Console.error(linted.stderr.trim());
+  return linted.exitCode === 0;
+});
+
+const check = Effect.scoped(Effect.gen(function* () {
+  const direct = yield* Config.String("PR_TITLE").pipe(Config.withDefault(""));
+  if (direct !== "") return yield* lintTitle(direct);
+  const event = yield* Config.String("GITHUB_EVENT_NAME").pipe(Config.withDefault(""));
+  if (event === "workflow_dispatch") {
+    const title = yield* dispatchedTitle();
+    if (title === undefined) return false;
+    return yield* lintTitle(title);
+  }
+  yield* Console.log(`${NAME}: no pull request title is available, so there is nothing to lint`);
+  return true;
+}));
+
+if (import.meta.main) runMain(NAME, check);

package/src/delivery/docs-only.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+import { Console, Effect } from "effect";
+import { changedPaths, git } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+
+const NAME = "docs-only";
+
+export function isDocsPath(path: string): boolean {
+  const lower = path.toLowerCase();
+  return lower.endsWith(".md") && (!lower.includes("/") || lower.startsWith("docs/"));
+}
+
+// The verdict goes to stdout as one line, so a step appends it to GITHUB_OUTPUT; the detail goes to stderr.
+const check = Effect.gen(function* () {
+  const [base, head] = process.argv.slice(2);
+  if (base === undefined || head === undefined) {
+    yield* Console.error(`${NAME}: no range is given, so the full run stays`);
+    yield* Console.log("docs-only=false");
+    return true;
+  }
+  const mergeBase = (yield* git(["merge-base", base, head])).trim();
+  const changes = yield* changedPaths(mergeBase, head, []);
+  const paths = changes.flatMap((change) => (change.kind === "renamed" ? [change.from, change.path] : [change.path]));
+  const full = paths.filter((path) => !isDocsPath(path));
+  if (paths.length === 0) {
+    yield* Console.error(`${NAME}: the range changes no file, so the full run stays`);
+    yield* Console.log("docs-only=false");
+  } else if (full.length === 0) {
+    yield* Console.error(`${NAME}: ${paths.length} changed file(s) are all top-level or docs/ Markdown, so the full run can skip`);
+    yield* Console.log("docs-only=true");
+  } else {
+    yield* Console.error(`${NAME}: ${full.length} changed file(s) need the full run`);
+    yield* Console.log("docs-only=false");
+  }
+  return true;
+});
+
+if (import.meta.main) runMain(NAME, check);

package/src/testing/mutation-baseline.ts

@@ -10,7 +10,7 @@ class BaselineFailure extends Schema.TaggedError<BaselineFailure>()("BaselineFai
 }) {}
 
 const NAME = "checks-mutation-baseline";
-const USAGE = "usage: checks-mutation-baseline <incremental-dest> [mutation-json-dest] | --full <mutation-json-dest>";
+const USAGE = "usage: checks-mutation-baseline <incremental-dest> [mutation-json-dest] | --full <mutation-json-dest> | --prune [--dry-run]";
 const WORKFLOW = "mutation.yml";
 const BRANCH = "main";
 const INCREMENTAL = "stryker-incremental.json";
@@ -21,6 +21,7 @@ const LATEST_ARTIFACT = "mutation-baseline";
 const FULL_ARTIFACT = "mutation-baseline-full";
 const LATEST_LIMIT = 20;
 const FULL_LIMIT = 50;
+const PAGE_SIZE = 100;
 const FULL_EVENTS = ["schedule", "workflow_dispatch"];
 
 // The first of `from` the artifact holds is copied to `to`.
@@ -33,7 +34,7 @@ const Artifact = Schema.Struct({
   id: Schema.Int,
   name: Schema.String,
   expired: Schema.Boolean,
-  workflow_run: Schema.Struct({ repository_id: Schema.Int }),
+  workflow_run: Schema.Struct({ id: Schema.Int, repository_id: Schema.Int }),
 });
 type Artifact = typeof Artifact.Type;
 
@@ -67,12 +68,66 @@ const latestCandidates = Effect.gen(function* () {
   return newest === undefined ? [] : [newest.databaseId];
 });
 
+// All non-pull-request runs newest first: a newer full run holds no baseline, and the newest baseline must survive it.
+const latestRuns = listed(undefined, LATEST_LIMIT).pipe(Effect.map((runs) => newestFirst(runs.filter((run) => run.event !== "pull_request"))));
+
 // Each full event is listed on its own, because one shared window lets push runs crowd out every full run.
 const fullCandidates = Effect.gen(function* () {
   const perEvent = yield* Effect.forEach(FULL_EVENTS, (event) => listed(event, FULL_LIMIT));
   return newestFirst(perEvent.flat());
 });
 
+// A successful run uploaded the files, so the newest unexpired artifact is the one the restore takes.
+// A failed lookup aborts rather than counting as absent, since that would delete the artifact the restore takes.
+const keptArtifact = Effect.fn("keptArtifact")(function* (runs: readonly number[], name: string) {
+  for (const run of runs) {
+    const artifact = yield* artifactOf(run, name);
+    if (Option.isSome(artifact)) return Option.some<Kept>({ run, id: artifact.value.id, name });
+  }
+  return Option.none<Kept>();
+});
+
+const everyArtifact = Effect.fn("everyArtifact")(function* () {
+  const artifacts: Artifact[] = [];
+  let page = 1;
+  while (true) {
+    const batch = yield* gh(["api", `repos/{owner}/{repo}/actions/artifacts?per_page=${PAGE_SIZE}&page=${page}`]).pipe(
+      Effect.flatMap(decodeArtifacts),
+      Effect.mapError((cause) => new BaselineFailure({ message: cause.message })),
+    );
+    artifacts.push(...batch.artifacts);
+    if (batch.artifacts.length < PAGE_SIZE) return artifacts;
+    page += 1;
+  }
+});
+
+const missedDeletion = Effect.fn("missedDeletion")(function* (artifact: Artifact) {
+  return yield* gh(["api", "-X", "DELETE", `repos/{owner}/{repo}/actions/artifacts/${artifact.id}`]).pipe(
+    Effect.as(Option.none<Missed>()),
+    Effect.catch((failure) => Effect.succeedSome<Missed>({ id: artifact.id, name: artifact.name, error: failure.message })),
+  );
+});
+
+const pruneBaselines = Effect.fn("pruneBaselines")(function* (dryRun: boolean) {
+  const running = yield* Config.Int("GITHUB_RUN_ID").pipe(Config.option);
+  const latest = yield* keptArtifact(yield* latestRuns, LATEST_ARTIFACT);
+  const full = yield* keptArtifact(yield* fullCandidates, FULL_ARTIFACT);
+  const artifacts = yield* everyArtifact();
+  const keeping = [...Option.toArray(latest), ...Option.toArray(full), ...uploadedBy(artifacts, running)];
+  const victims = superseded(artifacts, new Set(keeping.map((keep) => keep.id)));
+  const removed: number[] = [];
+  const missed: Missed[] = [];
+  if (!dryRun) {
+    for (const victim of victims) {
+      const failed = yield* missedDeletion(victim);
+      if (Option.isSome(failed)) missed.push(failed.value);
+      else removed.push(victim.id);
+    }
+  }
+  yield* Console.log(pruneReport(dryRun, dryRun ? victims.map((victim) => victim.id) : removed, missed, keeping));
+  return true;
+});
+
 const artifactOf = Effect.fn("artifactOf")(function* (run: number, name: string) {
   const found = yield* gh(["api", `repos/{owner}/{repo}/actions/runs/${run}/artifacts?name=${name}`]).pipe(
     Effect.flatMap(decodeArtifacts),
@@ -98,6 +153,37 @@ const downloaded = Effect.fn("downloaded")(function* (run: number, artifact: Art
   return fetched && (yield* holds(dir, needed));
 });
 
+export type Kept = { readonly run: number; readonly id: number; readonly name: string };
+
+export type Missed = { readonly id: number; readonly name: string; readonly error: string };
+
+const isBaseline = (artifact: Artifact): boolean => (artifact.name === LATEST_ARTIFACT || artifact.name === FULL_ARTIFACT) && !artifact.expired;
+
+// The restore reads only successful runs, so the running run's own uploads join the keepers rather than replace them.
+export function uploadedBy(artifacts: readonly Artifact[], running: Option.Option<number>): readonly Kept[] {
+  if (Option.isNone(running)) return [];
+  return artifacts
+    .filter((artifact) => isBaseline(artifact) && artifact.workflow_run.id === running.value)
+    .sort((one, other) => one.id - other.id)
+    .map((artifact) => ({ run: running.value, id: artifact.id, name: artifact.name }));
+}
+
+export function superseded(artifacts: readonly Artifact[], kept: ReadonlySet<number>): readonly Artifact[] {
+  return artifacts.filter((artifact) => isBaseline(artifact) && !kept.has(artifact.id)).sort((one, other) => one.id - other.id);
+}
+
+// A workflow command ends at a newline, so the error's own newlines and percent signs are escaped.
+const annotated = (text: string): string => text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+
+export function pruneReport(dryRun: boolean, removed: readonly number[], missed: readonly Missed[], keeping: readonly Kept[]): string {
+  const kept = keeping.length === 0 ? "no baseline artifacts" : keeping.map((keep) => `${keep.name} artifact ${keep.id} from run ${keep.run}`).join(", ");
+  const deleted = removed.length === 0 ? "nothing to delete" : `deleted artifacts ${removed.join(", ")}`;
+  if (dryRun) return `mutation-baseline: dry run, ${removed.length === 0 ? "nothing to delete" : `would delete artifacts ${removed.join(", ")}`}; would keep ${kept}`;
+  if (missed.length === 0) return `mutation-baseline: ${deleted}; kept ${kept}`;
+  const warnings = missed.map((miss) => `::warning::mutation-baseline: could not delete ${miss.name} artifact ${miss.id}: ${annotated(miss.error)}`);
+  return [...warnings, `mutation-baseline: ${deleted}; kept ${kept}; could not delete artifacts ${missed.map((miss) => miss.id).join(", ")}`].join("\n");
+}
+
 export function pruned(entries: readonly string[], kept: number, restoring: string): readonly string[] {
   return entries
     .filter((entry) => /^\d+$/.test(entry))
@@ -182,9 +268,16 @@ const runnerCache = Effect.gen(function* () {
 // An artifact that lacks `needed` counts as no baseline, and `optional` copies only what the artifact holds.
 type Request = { readonly full: boolean; readonly needed: Copy; readonly optional: readonly Copy[] };
 
+type PruneRequest = { readonly prune: true; readonly dryRun: boolean };
+
 const isDestination = (arg: string | undefined): arg is string => arg !== undefined && !arg.startsWith("-");
 
-function parsed(args: readonly string[]): Request | undefined {
+function parsed(args: readonly string[]): Request | PruneRequest | undefined {
+  if (args[0] === "--prune") {
+    const [flag, ...extra] = args.slice(1);
+    if ((flag === undefined || flag === "--dry-run") && extra.length === 0) return { prune: true, dryRun: flag !== undefined };
+    return undefined;
+  }
   if (args[0] === "--full") {
     const [report, ...extra] = args.slice(1);
     if (!isDestination(report) || extra.length > 0) return undefined;
@@ -198,6 +291,7 @@ function parsed(args: readonly string[]): Request | undefined {
 const mutationBaseline = Effect.gen(function* () {
   const request = parsed(process.argv.slice(2));
   if (request === undefined) return yield* new Usage({ message: USAGE });
+  if ("prune" in request) return yield* pruneBaselines(request.dryRun);
   const name = request.full ? FULL_ARTIFACT : LATEST_ARTIFACT;
   const root = yield* runnerCache;
   for (const run of yield* request.full ? fullCandidates : latestCandidates) {