@avi2dg/checks 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.34.0
+
+Released 2026-10-03.
+
+### Features
+
+- **delivery:** pin mutation jobs to winbox and default other jobs to hosted runners [#123](https://github.com/avi2d/checks/pull/123)
+
+## 0.33.0
+
+Released 2026-10-03.
+
+### Features
+
+- **docs:** report sentences over trial length caps as advisory [#120](https://github.com/avi2d/checks/pull/120)
+
+### Fixes
+
+- move effect to stable 4.0.0 [#122](https://github.com/avi2d/checks/pull/122)
+- **complexity:** accept signed numbers and earlier props names in thin-astro defaults [#115](https://github.com/avi2d/checks/pull/115)
+- **docs:** judge agent file entries and headings from a CommonMark parse [#116](https://github.com/avi2d/checks/pull/116)
+- **docs:** fail link anchors the checks-docs reference rule could not check [#114](https://github.com/avi2d/checks/pull/114)
+
 ## 0.32.0
 
 Released 2026-09-29.

package/README.md

@@ -9,12 +9,12 @@ Each repository owns its workflows and native tool configs, as [Native settings]
 <!-- generated prerequisites: bun run build writes it from package.json, .bun-version and scripts/doc-blocks.ts -->
 
 - A git repository, whose history the range gates read.
-- Bun 1.3.13, which runs every bin.
+- Bun 1.4.2, which runs every bin.
 - The peer dependencies, at the exact versions the kit pins:
   - `@effect/tsgo` 0.45.0
   - `@swc/core` 1.16.2
   - `dependency-cruiser` 18.4.0
-  - `effect` 4.0.0-rc.115
+  - `effect` 4.0.0
   - `jscpd` 5.3.2
   - `oxlint` 1.83.0
   - `oxlint-tsgolint` 7.0.2002
@@ -31,7 +31,7 @@ To consume the kit from a repository:
    <!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
 
    ```sh
-   bun add -d @avi2dg/checks @effect/tsgo@0.45.0 @swc/core@1.16.2 dependency-cruiser@18.4.0 effect@4.0.0-rc.115 jscpd@5.3.2 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
+   bun add -d @avi2dg/checks @effect/tsgo@0.45.0 @swc/core@1.16.2 dependency-cruiser@18.4.0 effect@4.0.0 jscpd@5.3.2 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
    ```
 
    <!-- end generated install -->
@@ -104,6 +104,7 @@ To consume the kit from a repository:
    ```
 
 Add a pull request title lint step in another workflow using `./node_modules/.bin/commitlint`.
+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.
 `bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
 
 ## What runs

package/dist/readability/index.js

@@ -400,11 +400,11 @@ var rule = {
   create(context) {
     const max = maxOf(context.options);
     const check = (node) => {
-      const score2 = node.type === "StaticBlock" ? cognitiveComplexity(node, NO_NAMES) : cognitiveComplexity(node, selfNames(node));
-      if (score2 <= max)
+      const score = node.type === "StaticBlock" ? cognitiveComplexity(node, NO_NAMES) : cognitiveComplexity(node, selfNames(node));
+      if (score <= max)
         return;
       const name = node.type === "StaticBlock" ? "static block" : `function \`${displayName(node)}\``;
-      context.report({ node, message: `${name} has a cognitive complexity of ${score2}. Maximum allowed is ${max}.` });
+      context.report({ node, message: `${name} has a cognitive complexity of ${score}. Maximum allowed is ${max}.` });
     };
     return {
       FunctionDeclaration: check,
@@ -430,6 +430,9 @@ function isAstroProps(value) {
   const { object, property } = value;
   return object.type === "Identifier" && object.name === "Astro" && property.type === "Identifier" && property.name === "props";
 }
+function isSignedNumber(value) {
+  return value.type === "UnaryExpression" && (value.operator === "-" || value.operator === "+") && value.argument.type === "Literal" && typeof value.argument.value === "number";
+}
 function isPlainValue(value, bound) {
   return value.type === "Literal" || value.type === "Identifier" && bound.has(value.name);
 }
@@ -442,17 +445,23 @@ function readsProps(expression, bound) {
   return isAstroProps(value) || readsProps(value.object, bound);
 }
 function isPlainPattern(pattern, bound) {
+  return isPlainInOrder(pattern, bound, new Set(bound));
+}
+function isPlainInOrder(pattern, bound, seen) {
   if (pattern === null)
     return true;
   if (pattern.type === "RestElement")
-    return isPlainPattern(pattern.argument, bound);
-  if (pattern.type === "AssignmentPattern")
-    return isPlainValue(pattern.right, bound) && isPlainPattern(pattern.left, bound);
+    return isPlainInOrder(pattern.argument, bound, seen);
+  if (pattern.type === "AssignmentPattern") {
+    return (isPlainValue(pattern.right, seen) || isSignedNumber(pattern.right)) && isPlainInOrder(pattern.left, bound, seen);
+  }
   if (pattern.type === "ArrayPattern")
-    return pattern.elements.every((element) => isPlainPattern(element, bound));
-  if (pattern.type === "Identifier")
+    return pattern.elements.every((element) => isPlainInOrder(element, bound, seen));
+  if (pattern.type === "Identifier") {
+    seen.add(pattern.name);
     return true;
-  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainPattern(property.argument, bound) : (!property.computed || isPlainValue(property.key, bound)) && isPlainPattern(property.value, bound));
+  }
+  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainInOrder(property.argument, bound, seen) : (!property.computed || isPlainValue(property.key, bound)) && isPlainInOrder(property.value, bound, seen));
 }
 function isPropsRead(declarator, bound) {
   return declarator.init !== null && readsProps(declarator.init, bound) && isPlainPattern(declarator.id, bound);

package/docs/configs/typescript-rules.md

@@ -48,7 +48,7 @@ The base loads the kit's `data-shape` plugin from `dist/` with one rule for ever
 An override in `oxlintrc.json` turns on one rule of the kit's `readability` plugin in each `.astro` file:
 
 - `readability/thin-astro` refuses a statement in the frontmatter or a script block that is neither an import, a re-export from another module, a type or interface declaration, nor a variable read from `Astro.props`.
-- A default inside an `Astro.props` destructuring passes only when it is a literal or a name read from `Astro.props` earlier, so `const { title = "Home" } = Astro.props;` passes and a call or `await` in a default is refused.
+- A default inside an `Astro.props` destructuring passes only when it is a literal, a `-` or `+` on a numeric literal, or a name read from `Astro.props` earlier, in the same pattern or a statement before it, so `const { title = "Home", heading = title } = Astro.props;` passes and a call or `await` in a default is refused.
 - Move a refused statement into a `.ts` file and import it, so the `.astro` file holds only imports, props and markup.
 - A script block loads client code with a side-effect import, as in `<script>import "../client.ts";</script>`, and the override turns off `import/no-unassigned-import` so that import passes.
 - A dynamic route re-exports `getStaticPaths` from a `.ts` file, as in `export { getStaticPaths } from "../lib/paths.ts";`.

package/docs/design.md

@@ -67,7 +67,7 @@ So the fragment lists the rules in `files`, and in `include` beside every file u
 
 The source sits under `src/<vector>/`, one directory for each thing the kit judges a repository on: complexity, quality, testing, docs, delivery and dependencies.
 `src/core/` holds what every vector runs on.
-`scripts/` holds only the kit's own build, and nothing in it ships.
+`scripts/` holds only the kit's own build and CI tooling, and nothing in it ships.
 Sorting files by what loads them would put both oxlint plugins at the root and every bin in one flat directory.
 Nothing would then say which gate a helper serves.
 A mutation runner's default scope covers `src/`, so the kit's own Stryker run mutates its source with no `mutate` list.
@@ -100,7 +100,7 @@ The `.ts` bins keep a `bun` shebang and need no build step, unlike the oxlint pl
 The bins are written in Effect.
 So `effect` is a peer dependency, and `@effect/platform-bun`, which only the bins use, is a dependency.
 `@effect/platform-node-shared` is a direct dependency only to pin its version.
-`@effect/platform-bun` asks for it with a `^` range, and a newer release candidate of it peers on a newer `effect` than consumers install.
+`@effect/platform-bun` asks for it with a `^` range, so a newer minor of it could resolve and peer on a newer `effect` than the exact version consumers install.
 So the three packages move together at one exact version.
 
 ## checks-lint runs each gate as its own bin
@@ -211,6 +211,10 @@ A score cannot fail a change without failing correct prose, and a suggestion tha
 `src/docs/prose-matchers.ts` imports nothing, so the gate and a write-time hook run one matcher and refuse in the same words.
 A hook bundle ships without `node_modules`, so a matcher that needed Vale or another package could not refuse at write time.
 
+The entry rule and the rule against a `## Maintaining this file` section take their list items and headings from `commonmark`, the CommonMark reference parser.
+A reader sees the blocks a renderer builds, and a line rule that guesses at blockquotes, HTML blocks and indented code misjudges each corner its guess misses.
+Only the gate runs these rules, so the parser costs no hook anything, and the line scan reads each entry's code spans and links from that entry's line alone.
+
 A path, link or command on a line the range leaves alone still fails when the range broke it, for example by deleting the file it names.
 A reference goes stale far more often because the code it names moves than because its own line is edited.
 So a gate on edited lines alone would miss the usual break.

package/docs/gates/checks-advisories.md

@@ -110,7 +110,7 @@ on:
   workflow_dispatch:
 jobs:
   advisories:
-    runs-on: self-hosted
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v5
@@ -119,8 +119,9 @@ jobs:
       - run: ./node_modules/.bin/checks-advisories --all
 ```
 
+The job runs on a hosted runner unless `CI_RUNS_ON` names another, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
+A hosted runner starts each run with an empty cache, so each run downloads both the scanner and the database.
 A self-hosted runner keeps `~/.cache/avi2dg-checks/` between runs, so it downloads the scanner once per pinned version and the database about once a day.
-A hosted runner starts each run with an empty cache, so each run downloads both.
 
 ## Related topics
 

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

@@ -21,10 +21,22 @@ It refuses a step or job with `if: false` or `continue-on-error: true`.
 It also refuses a workflow that does not trigger on both `opened` and `synchronize` pull requests to the target branch.
 A path filter cannot cover every pull request and therefore cannot satisfy the check.
 
+### Runners
+
+It also judges the runner of every job in every workflow.
+A mutation job is one with a run step that calls `stryker run`, `checks-mutation`, `checks-mutation-compare` or a `package.json` script that does, directly or through `bun`, `bun run` or `bunx`.
+The call counts as a command of its own or inside a command substitution, never as an argument to another command.
+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.
+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.
+The check knows a repository is private only from GitHub's event, so a run outside CI judges only the rules that hold in either.
+
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml` and the `scripts` in `package.json` from the working tree.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
+It reads whether the repository is private from `repository.private` in that event file.
 It parses the workflows with `Bun.YAML` without executing them.
 
 ## Arguments
@@ -36,7 +48,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked. |
+| 1 | A required command is missing or blocked, or a job runs on the wrong runner. |
 | 2 | A workflow or `package.json` cannot be decoded. |
 
 ## Sample output
@@ -49,6 +61,13 @@ ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
     no run step invokes it
 ```
 
+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]
+```
+
 ## When it runs
 
 `checks-lint` runs it in every repository.

package/docs/gates/checks-docs.md

@@ -110,6 +110,8 @@ A line holds one sentence, so a changed line is a changed sentence.
 A bold label that opens a line, as in `**Status.**`, heads the sentence after it and is not a sentence of its own.
 No rule reads fenced code, inline code, link destinations, URLs, HTML comments or front matter.
 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.
 
 `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`.
@@ -121,7 +123,8 @@ Each reference a living doc or an agent file names has to resolve at the head co
 
 - A path in inline code that ends in a file extension, such as `src/core/lint.ts`, names a file from the root or from the doc's directory.
 - A relative Markdown link names a file or a directory.
-  Its anchor names a heading in that file, as GitHub derives the anchor, or an explicit `id`.
+  Its anchor names a heading in that Markdown or MDX file, as GitHub derives the anchor, or an explicit `id`.
+  An anchor into a directory or any other file fails, because it names no heading the gate can check.
 - A `bun run` command in code names a script in the nearest `package.json`, a bin in `node_modules/.bin`, or a file that exists.
 - A code span fails when some tracked file outside the docs held that exact text at the base, and none holds it at the head.
   A span the path check already fails on is not reported again.
@@ -150,7 +153,8 @@ audience: consumers
 An agent file holds the router its template sketches, and the rules below hold its shape whatever the range touches.
 A file over 3,000 characters fails.
 Move each part's notes into the people doc that covers that part, and delete what a check or the code already holds.
-A file that holds a `## Maintaining this file` section fails, because this gate holds the shape the section asked for.
+A file that holds a `## Maintaining this file` section a reader sees fails, because this gate holds the shape the section asked for.
+A heading inside an HTML comment, an HTML block or a code block is not such a section.
 Each entry names at least one of these, or it fails:
 
 - A path in inline code that git tracks at the head commit, a file or a directory, such as `package.json`, `LICENSE` or `.gitignore`.
@@ -159,7 +163,7 @@ Each entry names at least one of these, or it fails:
 - A `bun run` command.
 
 Whether the link or the command resolves is the reference rule's call, as [Paths, links and commands](#paths-links-and-commands) says, and it fails when the range adds or breaks one.
-An entry is any list item a reader sees, the items above the first section included.
+An entry is any list item a reader sees as CommonMark renders the file, the items above the first section included.
 A list item inside an HTML comment, an HTML block or an indented code block is not an entry.
 A fresh file passes the ceiling, and its entries pass once each names the file that holds its detail.
 
@@ -205,6 +209,8 @@ docs: 6 violation(s):
   docs/parts.md:9: names `gates.lint`, which the range removed from every file outside the docs. Say what holds now, or drop the line
 docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
   docs/adr/0001-quality-gates.md: 5 violation(s)
+docs: advisory, 1 sentence(s) over the trial length caps:
+  README.md:16: carries a 27-word descriptive sentence, over the 25-word cap (procedural means an ordered list item, capped at 20 words)
 docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files name were broken before the range:
   docs/parts.md:9: links to `suppliers.md#prices`, and `docs/suppliers.md` has no heading with that anchor
 ```

package/docs/gates/checks-flake.md

@@ -76,6 +76,8 @@ jobs:
           path: flake-report.json
 ```
 
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the job, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
+
 ## Related topics
 
 - [checks-test](checks-test.md)

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

@@ -107,8 +107,9 @@ jobs:
 Both Stryker runs are full sweeps, and GitHub sets `CI=true` on every runner, so the preset lets them through.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
 A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
-A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` instead.
-With `CI_RUNS_ON` unset, the job then runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
+A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its full sweeps.
+The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
+[checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 
 ## Related topics
 

package/docs/gates/checks-mutation.md

@@ -59,8 +59,9 @@ An `--incremental` run with no report stops before instrumenting with the missin
 ## When it runs
 
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
+A repository that picks a pull request scope from a baseline also runs that workflow on a nightly schedule.
 Run scoped checks locally during development.
-A scheduled run never starts one, because a baseline costs a full Stryker run.
+A scheduled run costs a full Stryker run.
 
 ## Running it in CI
 
@@ -72,7 +73,7 @@ on:
   workflow_dispatch:
 jobs:
   mutation:
-    runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}
+    runs-on: [self-hosted, Linux, X64, winbox]
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
@@ -87,8 +88,9 @@ jobs:
           path: reports/mutation/mutation.json
 ```
 
-With `CI_RUNS_ON` unset, the job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a private repository sends its full sweeps.
-A repository sets `CI_RUNS_ON` only to name a different runner.
+The job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a repository sends its full sweeps.
+It never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the sweep waiting for `winbox`.
+[checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
 The `name: mutation` line is what `gh workflow run mutation` looks up.
 GitHub sets `CI=true` on every runner, so the preset lets the full run through there.
 

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

@@ -133,6 +133,7 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
 A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
 When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
 A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.

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

@@ -138,11 +138,11 @@ jobs:
 ```
 
 A public repository keeps `runs-on: ubuntu-latest`.
-A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` on both jobs, as its other workflows do.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on both jobs, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires of every job but a mutation job.
 A repository whose build needs more than Bun adds the steps its `.github/workflows/ci.yml` runs before `bun run build` to both jobs, and nothing after it.
 Neither job runs a test suite or a mutation run.
 On a hosted runner the `pull-request` job takes about 25 seconds, which GitHub bills as one minute, whether it opens, refreshes or leaves the pull request alone.
-A private repository runs it on its self-hosted runner, which bills no minutes.
+A private repository runs it there too unless `CI_RUNS_ON` names its self-hosted runner, which bills no minutes.
 The `tag` job runs only when a release lands, and a job its `if` skips bills nothing.
 The checks it dispatches are the release pull request's own required checks, and they run again only when `main` moves under it.
 The pull request also lists its own `pull_request` runs as waiting for approval.

package/docs/gates/checks-vendor.md

@@ -60,19 +60,19 @@ With no arguments it pins nothing.
 ## Sample output
 
 ```
-checks-vendor: cloned effect@4.0.0-rc.115 from https://github.com/Effect-TS/effect.git and linked repos/effect
+checks-vendor: cloned effect@4.0.0 from https://github.com/Effect-TS/effect.git and linked repos/effect
 ```
 
 A fresh fetch reports the tag it cloned and the link it made.
 
 ```
-checks-vendor: repos/effect still holds effect@4.0.0-rc.115, verified against its recorded commit
+checks-vendor: repos/effect still holds effect@4.0.0, verified against its recorded commit
 ```
 
 A later run reports the link it kept.
 
 ```
-checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@4.0.0-rc.115, and froze the tree again, so repos/effect still holds effect@4.0.0-rc.115, verified against its recorded commit
+checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@4.0.0, and froze the tree again, so repos/effect still holds effect@4.0.0, verified against its recorded commit
 ```
 
 A run that found an owner write bit reports how many paths carried one and the first of them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -60,6 +60,7 @@
     "src/complexity/exports.ts",
     "src/complexity/knip.ts",
     "src/testing/quarantine-clock.ts",
+    "src/docs/sentence-length.ts",
     "src/docs/docs.ts",
     "src/dependencies/vendor.ts",
     "src/dependencies/vendor-args.ts",
@@ -136,7 +137,7 @@
     "@swc/core": "1.16.2",
     "dependency-cruiser": "18.4.0",
     "@effect/tsgo": "0.45.0",
-    "effect": "4.0.0-rc.115",
+    "effect": "4.0.0",
     "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002",
@@ -149,8 +150,9 @@
     "@stryker-mutator/core": "10.0.0",
     "@swc/core": "1.16.2",
     "@types/bun": "^1.3.0",
+    "@types/commonmark": "0.27.10",
     "dependency-cruiser": "18.4.0",
-    "effect": "4.0.0-rc.115",
+    "effect": "4.0.0",
     "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002",
@@ -159,13 +161,17 @@
   "dependencies": {
     "@commitlint/cli": "21.2.3",
     "@commitlint/config-conventional": "21.2.3",
-    "@effect/platform-bun": "4.0.0-rc.115",
-    "@effect/platform-node-shared": "4.0.0-rc.115",
+    "@effect/platform-bun": "4.0.0",
+    "@effect/platform-node-shared": "4.0.0",
     "@total-typescript/ts-reset": "0.6.1",
+    "commonmark": "0.31.2",
     "knip": "6.38.0"
   },
   "overrides": {
     "qs": "6.16.0",
     "smol-toml": "1.9.0"
+  },
+  "patchedDependencies": {
+    "@hughescr/stryker-bun-runner@1.4.0": "patches/@hughescr%2Fstryker-bun-runner@1.4.0.patch"
   }
 }

package/src/core/git.ts

@@ -1,5 +1,5 @@
 import { Config, Effect, FileSystem, Path, Schema, Stream } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { DEFAULT_BRANCH } from "./gates.ts";
 import { Usage } from "./main.ts";
 

package/src/core/lint.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { EVERY_REPOSITORY, KIT_GATES, type KitGate } from "./gates.ts";
 import { defaultBranch, git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";

package/src/delivery/ci-wiring.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
-import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
+import { fromProgram, invokes, mentions, plainCommand, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
 
 export type { Command };
 
@@ -34,6 +34,18 @@ export type Gap = {
   readonly blocked: readonly BlockedInvocation[];
 };
 
+export type Visibility = "private" | "public" | "unknown";
+
+export type RunnerPolicy = {
+  readonly visibility: Visibility;
+  readonly scripts: ReadonlyMap<string, string>;
+};
+
+export type RunnerFault = {
+  readonly location: string;
+  readonly fault: string;
+};
+
 type RunStep = {
   readonly location: string;
   readonly blocker: string | undefined;
@@ -58,6 +70,17 @@ const CONSTANTS = new Map([
   ["false", false],
 ]);
 const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+// GitHub expressions match context and property names without regard to case.
+const OVERRIDE_ACCESS = String.raw`vars\s*(?:\.\s*CI_RUNS_ON\b|\[\s*'CI_RUNS_ON'\s*\])`;
+const RUNNER_OVERRIDE = new RegExp(String.raw`\b${OVERRIDE_ACCESS}`, "i");
+const HOSTED_OVERRIDE = new RegExp(String.raw`^\$\{\{\s*${OVERRIDE_ACCESS}\s*\|\|\s*'ubuntu-latest'\s*\}\}$`, "i");
+const MUTATION_RUNNER = ["self-hosted", "Linux", "X64", "winbox"];
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+const MUTATION_BINS = ["checks-mutation", "checks-mutation-compare"];
+const BUN_OPERANDS = new Set(["--cwd", "-c", "--config", "--env-file", "-F", "--filter", "-r", "--preload", "--require", "--import", "-e", "--eval", "-p", "--print", "--elide-lines", "--tsconfig-override"]);
+// bun's own commands take precedence over a package.json script of the same name unless bun run names it.
+const BUN_COMMANDS = new Set(["test", "repl", "exec", "install", "i", "add", "a", "remove", "rm", "update", "outdated", "link", "unlink", "pm", "build", "init", "create", "c", "upgrade", "publish", "patch", "patch-commit", "audit", "info", "why"]);
+const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -243,13 +266,75 @@ export function declarationFor(scripts: readonly string[], branch: string): Decl
   };
 }
 
+function runsMutation(script: string, scripts: ReadonlyMap<string, string>, walked: readonly string[] = []): boolean {
+  return shellCommands(script).some((command) => mutationCommand(command, scripts, walked));
+}
+
+function mutationCommand(command: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [first = "", ...rest] = fromProgram(command);
+  return first === "bun" ? bunRunsMutation(rest, scripts, walked) : mutationBin([first, ...rest]);
+}
+
+function bunRunsMutation(args: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [command = "", ...rest] = withoutOptions(args, BUN_OPERANDS);
+  if (command === "x") return mutationCommand(["bunx", ...rest], scripts, walked);
+  if (BUN_COMMANDS.has(command)) return false;
+  const [target = "", ...targetArgs] = command === "run" ? withoutOptions(rest, BUN_OPERANDS) : [command, ...rest];
+  const body = walked.includes(target) ? undefined : scripts.get(target);
+  return body === undefined ? mutationBin([target, ...targetArgs]) : runsMutation(body, scripts, [...walked, target]);
+}
+
+function mutationBin([program = "", subcommand]: Command): boolean {
+  const bin = program.slice(program.lastIndexOf("/") + 1);
+  return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
+}
+
+function sameLabels(runsOn: unknown, labels: readonly string[]): boolean {
+  const named = Array.isArray(runsOn) ? names(runsOn) : undefined;
+  return named?.length === labels.length && labels.every((label) => named.includes(label));
+}
+
+function readsOverride(runsOn: unknown): boolean {
+  if (typeof runsOn === "string") return RUNNER_OVERRIDE.test(runsOn);
+  const values = isRecord(runsOn) ? Object.values(runsOn) : Array.isArray(runsOn) ? runsOn : [];
+  return values.some(readsOverride);
+}
+
+function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility): string | undefined {
+  const overridden = readsOverride(runsOn);
+  const pin = `set runs-on: [${MUTATION_RUNNER.join(", ")}]`;
+  if (mutation && overridden) return `a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; ${pin}`;
+  if (mutation) return visibility === "private" && !sameLabels(runsOn, MUTATION_RUNNER) ? `a mutation job in a private repository runs off winbox; ${pin}` : undefined;
+  const hosted = typeof runsOn === "string" && HOSTED_OVERRIDE.test(runsOn.trim());
+  if (hosted || (visibility !== "private" && !overridden)) return undefined;
+  return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
+}
+
+export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
+  return workflows.flatMap((workflow) => {
+    const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+    if (!isRecord(jobs)) return [];
+    return Object.entries(jobs).flatMap(([id, job]) => {
+      if (!isRecord(job) || job["runs-on"] === undefined) return [];
+      const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+      const mutation = steps.some((step: unknown) => isRecord(step) && typeof step["run"] === "string" && runsMutation(step["run"], policy.scripts));
+      const fault = runnerFault(job["runs-on"], mutation, policy.visibility);
+      return fault === undefined ? [] : [{ location: `${workflow.path} job ${id}`, fault }];
+    });
+  });
+}
+
+export function formatRunnerReport(faults: readonly RunnerFault[]): string {
+  return [`ci-wiring: ${faults.length} job(s) run on the wrong runner:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}
+
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
     try: () => ({ path, document: Bun.YAML.parse(text) }),
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
-export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+const readScripts = Effect.fn("readScripts")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const file = (yield* Path.Path).join(root, "package.json");
   const { scripts = {} } = (yield* fs.exists(file))
@@ -258,7 +343,22 @@ export const readDeclaration = Effect.fn("readDeclaration")(function* (root: str
         Effect.mapError((cause) => new WiringError({ message: `cannot read ${file}: ${cause.message}` })),
       )
     : Manifest.make({});
-  return declarationFor(Object.keys(scripts), yield* defaultBranch(root));
+  return new Map(Object.entries(scripts));
+});
+
+export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  return declarationFor([...(yield* readScripts(root)).keys()], yield* defaultBranch(root));
+});
+
+// Only GitHub's event says whether the repository is private, so a run outside CI judges what holds in either.
+const readVisibility = Effect.gen(function* () {
+  const eventPath = yield* Config.String("GITHUB_EVENT_PATH").pipe(Config.withDefault(""));
+  if (eventPath === "") return "unknown" satisfies Visibility;
+  return yield* (yield* FileSystem.FileSystem).readFileString(eventPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(EventRepository)),
+    Effect.map(({ repository }): Visibility => (repository.private ? "private" : "public")),
+    Effect.orElseSucceed((): Visibility => "unknown"),
+  );
 });
 
 export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string) {
@@ -283,7 +383,9 @@ const wiring = Effect.gen(function* () {
   const gaps = findGaps(declaration, workflows);
   const gapReport = formatReport(declaration, gaps);
   yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
-  return gaps.length === 0;
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts: yield* readScripts(root) }, workflows);
+  if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
+  return gaps.length === 0 && faults.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/github.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect";
-import { ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/process";
 import { collect } from "../core/git.ts";
 
 export class GitHubFailure extends Schema.TaggedError<GitHubFailure>()("GitHubFailure", {

package/src/delivery/release-pr.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
-import { Console, Effect, Encoding, FileSystem, Path, Schema } from "effect";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import * as Base64 from "effect/encoding/Base64";
 import { dispatch, gitHubJson, REPOSITORY } from "./github.ts";
 import { nextVersion, type Pending, readPending, releaseTitle, runBuild, withVersion } from "./release.ts";
 import { git } from "../core/git.ts";
@@ -105,7 +106,7 @@ const readStaged = Effect.fn("readStaged")(function* (root: string, staged: Stag
   if (staged.kind === "deleted") return staged;
   if (!REGULAR_FILE_MODES.has(staged.mode)) return yield* refused(`the build wrote ${staged.path} with mode ${staged.mode}, which is no regular file`);
   const bytes = yield* (yield* FileSystem.FileSystem).readFile((yield* Path.Path).join(root, staged.path));
-  return { ...staged, content: Encoding.encodeBase64(bytes) };
+  return { ...staged, content: Base64.encode(bytes) };
 });
 
 // The build writes into the working tree, so the tree it starts from has to hold nothing a release would sweep in.

package/src/delivery/release.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { groupOf } from "./changelog.ts";
 import { git } from "../core/git.ts";
 

package/src/delivery/shell-command.ts

@@ -64,6 +64,149 @@ export function plainCommand(script: string): Command | undefined {
   return words.length === 0 ? undefined : words;
 }
 
+type ShellPart = Span & { readonly substitutions: readonly string[] };
+
+const COMMAND_BREAKS = new Set(["\n", ";", "&", "|", "(", ")", "`"]);
+const WORD_BREAKS = new Set([" ", "\t"]);
+const REDIRECTS = new Set(["<", ">"]);
+const REDIRECT_OPERATOR = /^[<>][<>&|]*/;
+const FILE_DESCRIPTOR = /^\d+$/;
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const RESERVED_WORDS = new Set(["!", "{", "if", "then", "elif", "else", "while", "until", "do"]);
+const LAUNCHER_OPERANDS = new Map<string, ReadonlySet<string>>([
+  ["time", new Set(["-o", "-f"])],
+  ["env", new Set(["-u", "-C", "--unset", "--chdir"])],
+  ["exec", new Set(["-a"])],
+  ["nohup", new Set()],
+  ["sudo", new Set(["-u", "-g", "-C", "-D", "-h", "-p", "-r", "-t", "-U", "--user", "--group", "--chdir", "--host", "--prompt"])],
+  ["bunx", new Set(["-p", "--package"])],
+  ["npx", new Set(["-p", "--package", "-c", "--call", "-w", "--workspace"])],
+]);
+
+function substitutionEnd(script: string, start: number): number {
+  if (script.charAt(start) === "`") {
+    const close = script.indexOf("`", start + 1);
+    return close === -1 ? script.length : close;
+  }
+  let depth = 0;
+  for (let index = start + 1; index < script.length; index += 1) {
+    if (script.charAt(index) === "(") depth += 1;
+    if (script.charAt(index) === ")") depth -= 1;
+    if (depth === 0) return index;
+  }
+  return script.length;
+}
+
+function doubleQuotedPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  const next = script.charAt(index + 1);
+  if (char === "\\" && next === "\n") return { text: "", end: index + 2, substitutions: [] };
+  if (char === "\\" && DOUBLE_QUOTE_ESCAPES.has(next)) return { text: next, end: index + 2, substitutions: [] };
+  if (char !== "`" && !(char === "$" && next === "(")) return { text: char, end: index + 1, substitutions: [] };
+  const end = substitutionEnd(script, index);
+  return { text: "", end: end + 1, substitutions: [script.slice(index + (char === "`" ? 1 : 2), end)] };
+}
+
+function shellDoubleQuoted(script: string, open: number): ShellPart {
+  let text = "";
+  const substitutions: string[] = [];
+  let index = open + 1;
+  while (index < script.length && script.charAt(index) !== '"') {
+    const part = doubleQuotedPart(script, index);
+    text += part.text;
+    substitutions.push(...part.substitutions);
+    index = part.end;
+  }
+  return { text, end: index + 1, substitutions };
+}
+
+function shellPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  if (char === "'") {
+    const close = script.indexOf("'", index + 1);
+    const end = close === -1 ? script.length : close;
+    return { text: script.slice(index + 1, end), end: end + 1, substitutions: [] };
+  }
+  if (char === '"') return shellDoubleQuoted(script, index);
+  if (char === "\\") return { text: script.charAt(index + 1), end: index + 2, substitutions: [] };
+  return { text: char, end: index + 1, substitutions: [] };
+}
+
+function commentEnd(script: string, from: number): number {
+  const newline = script.indexOf("\n", from);
+  return newline === -1 ? script.length : newline;
+}
+
+type ShellParse = {
+  readonly commands: string[][];
+  readonly substitutions: string[];
+  words: string[];
+  word: string | undefined;
+  redirecting: boolean;
+};
+
+function endWord(parse: ShellParse): void {
+  if (parse.word === undefined) return;
+  if (!parse.redirecting) parse.words.push(parse.word);
+  parse.redirecting = false;
+  parse.word = undefined;
+}
+
+function endCommand(parse: ShellParse): void {
+  endWord(parse);
+  parse.commands.push(parse.words);
+  parse.words = [];
+  parse.redirecting = false;
+}
+
+function startRedirect(parse: ShellParse, script: string, index: number): number {
+  if (parse.word !== undefined && FILE_DESCRIPTOR.test(parse.word)) parse.word = undefined;
+  endWord(parse);
+  parse.redirecting = true;
+  return index + (REDIRECT_OPERATOR.exec(script.slice(index))?.[0].length ?? 1);
+}
+
+export function shellCommands(script: string): readonly Command[] {
+  const parse: ShellParse = { commands: [], substitutions: [], words: [], word: undefined, redirecting: false };
+  let index = 0;
+  while (index < script.length) {
+    const char = script.charAt(index);
+    if (char === "\\" && script.charAt(index + 1) === "\n") {
+      index += 2;
+    } else if (char === "#" && parse.word === undefined) {
+      index = commentEnd(script, index);
+    } else if (REDIRECTS.has(char)) {
+      index = startRedirect(parse, script, index);
+    } else if (COMMAND_BREAKS.has(char) || WORD_BREAKS.has(char)) {
+      if (COMMAND_BREAKS.has(char)) endCommand(parse);
+      else endWord(parse);
+      index += 1;
+    } else {
+      const part = shellPart(script, index);
+      parse.word = (parse.word ?? "") + part.text;
+      parse.substitutions.push(...part.substitutions);
+      index = part.end;
+    }
+  }
+  endCommand(parse);
+  return [...parse.commands, ...parse.substitutions.flatMap(shellCommands)].filter((command) => command.length > 0);
+}
+
+export function withoutOptions(words: Command, operands: ReadonlySet<string>): Command {
+  const [first = "", ...rest] = words;
+  if (first === "--") return rest;
+  if (!first.startsWith("-")) return words;
+  return withoutOptions(operands.has(first) ? rest.slice(1) : rest, operands);
+}
+
+export function fromProgram(words: Command): Command {
+  const [first = "", ...rest] = words;
+  if (ASSIGNMENT.test(first) || RESERVED_WORDS.has(first)) return fromProgram(rest);
+  const operands = LAUNCHER_OPERANDS.get(first);
+  return operands === undefined ? words : fromProgram(withoutOptions(rest, operands));
+}
+
 // bun run resolves any other word, even one holding a slash, to a package.json script of that name first.
 const FILE_PATH = /^\.{0,2}\//;
 

package/src/dependencies/pinned-binary.ts

@@ -1,6 +1,7 @@
-import { Crypto, Effect, Encoding, FileSystem, Path, Schema } from "effect";
-import { HttpClient, HttpClientResponse } from "effect/unstable/http";
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { Crypto, Effect, FileSystem, Path, Schema } from "effect";
+import * as Hex from "effect/encoding/Hex";
+import { HttpClient, HttpClientResponse } from "effect/http";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
 import { collect } from "../core/git.ts";
 
 const EXECUTABLE_MODE = 0o755;
@@ -19,7 +20,7 @@ function installedSha256(asset: Asset): string {
 
 const sha256Of = Effect.fn("sha256Of")(function* (bytes: Uint8Array) {
   const crypto = yield* Crypto.Crypto;
-  return Encoding.encodeHex(yield* crypto.digest("SHA-256", bytes));
+  return Hex.encode(yield* crypto.digest("SHA-256", bytes));
 });
 
 const verified = Effect.fn("verified")(function* (binary: string, sha256: string) {

package/src/docs/doc-agents.ts

@@ -1,11 +1,9 @@
+import { Parser, type NodeType } from "commonmark";
 import { commandNames, type Snapshot } from "./doc-references.ts";
 import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
 
 export const AGENT_CEILING = 3000;
 
-const LIST_ITEM = /^(?:\s*>)*\s*(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
-const INDENT = /^[ \t]*/;
-const CODE_INDENT = 4;
 const INLINE_LINK =
   /(?<![!\\])\[(?:[^[\]\\]|\\.|\[[^\]]*\])*\]\(\s*(?:<[^<>\n]+>|[^\s()<>]+(?:\([^\s()]*\)[^\s()<>]*)*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
 const MAINTAINING = /^\s{0,3}#{1,6}\s+Maintaining this file(?:\s+#+)?\s*$/;
@@ -27,8 +25,24 @@ export function ceilingFinding(text: string): AgentFinding | undefined {
   };
 }
 
+function blockStarts(lines: readonly MarkdownLine[], type: NodeType): ReadonlySet<number> {
+  const read = lines.map(({ kind, raw }) => (kind === "front-matter" ? "" : raw)).join("\n");
+  const walker = new Parser().parse(read).walker();
+  const starts = new Set<number>();
+  for (let step = walker.next(); step !== null; step = walker.next()) {
+    if (step.entering && step.node.type === type) starts.add(step.node.sourcepos[0][0]);
+  }
+  return starts;
+}
+
+function linesOpening(text: string, type: NodeType): readonly MarkdownLine[] {
+  const lines = scanMarkdown(text);
+  const starts = blockStarts(lines, type);
+  return lines.filter(({ line }) => starts.has(line)).flatMap(({ line, raw }) => scanMarkdown(raw).map((alone) => ({ ...alone, line })));
+}
+
 export function maintainingFinding(text: string): AgentFinding | undefined {
-  const heading = scanMarkdown(text).find(({ kind, raw }) => kind === "heading" && MAINTAINING.test(raw));
+  const heading = linesOpening(text, "heading").find(({ raw }) => MAINTAINING.test(raw));
   if (heading === undefined) return undefined;
   return {
     line: heading.line,
@@ -36,27 +50,14 @@ export function maintainingFinding(text: string): AgentFinding | undefined {
   };
 }
 
-function indentOf(raw: string): number {
-  return (INDENT.exec(raw)?.[0] ?? "").replaceAll("\t", "    ").length;
-}
-
 export function entries(text: string): readonly MarkdownLine[] {
-  let inList = false;
-  let afterBlank = true;
-  return scanMarkdown(text).filter((line) => {
-    const blank = line.raw.trim() === "";
-    const indented = !blank && indentOf(line.raw) >= CODE_INDENT && !line.raw.trimStart().startsWith(">");
-    const listItem = line.kind === "prose" && LIST_ITEM.test(line.prose) && (inList || !indented);
-    if (listItem) inList = true;
-    else if (!blank && !indented && (afterBlank || line.kind !== "prose")) inList = false;
-    afterBlank = blank;
-    return listItem;
-  });
+  return linesOpening(text, "item");
 }
 
 type Tracked = Pick<Snapshot, "files" | "directories">;
 
 const STAYS = new Set(["", "."]);
+const NAMES_A_SEGMENT = /[^/]/;
 
 function joined(directory: string, segment: string): string {
   return directory === "" ? segment : `${directory}/${segment}`;
@@ -76,10 +77,11 @@ function resolvesFrom(directory: string, span: string, tracked: Tracked): boolea
   if (walked === undefined) return false;
   if (!STAYS.has(last) && last !== ".." && tracked.files.has(joined(walked, last))) return true;
   const end = enter(walked, last, tracked);
-  return end !== undefined && end !== "" && end !== directory;
+  return end !== undefined && end !== "";
 }
 
 function namesTrackedPath(agentFile: string, span: string, tracked: Tracked): boolean {
+  if (!NAMES_A_SEGMENT.test(span)) return false;
   const directory = agentFile.includes("/") ? agentFile.slice(0, agentFile.lastIndexOf("/")) : "";
   const fromFile = resolvesFrom(directory, span, tracked);
   return fromFile || (!span.startsWith("./") && !span.startsWith("../") && resolvesFrom("", span, tracked));

package/src/docs/doc-names.ts

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
-import { ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/process";
 import { collect, git, pathsAt } from "../core/git.ts";
 import type { Unresolved } from "./doc-references.ts";
 import { scanMarkdown } from "./prose-matchers.ts";

package/src/docs/doc-references.ts

@@ -78,20 +78,28 @@ function unresolvedPath(doc: string, line: number, span: string, snapshot: Snaps
 const SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
 const ASCII_ESCAPE = /%([0-7][0-9a-f])/gi;
 
+function linkPath(doc: string, target: string, hash: number): string | undefined {
+  const written = (hash < 0 ? target : target.slice(0, hash)).split("?", 1)[0] ?? "";
+  const decoded = written.replace(ASCII_ESCAPE, (_, code: string) => String.fromCharCode(Number.parseInt(code, 16)));
+  return decoded === "" ? doc : decoded.startsWith("/") ? normalize(decoded) : within(directoryOf(doc), decoded);
+}
+
 function unresolvedLink(doc: string, line: number, target: string, snapshot: Snapshot): Unresolved | undefined {
   if (target === "" || SCHEME.test(target)) return undefined;
   const hash = target.indexOf("#");
-  const written = (hash < 0 ? target : target.slice(0, hash)).split("?", 1)[0] ?? "";
-  const decoded = written.replace(ASCII_ESCAPE, (_, code: string) => String.fromCharCode(Number.parseInt(code, 16)));
-  const path = decoded === "" ? doc : decoded.startsWith("/") ? normalize(decoded) : within(directoryOf(doc), decoded);
+  const path = linkPath(doc, target, hash);
   if (path === undefined) return undefined;
   const named = target;
   if (!exists(snapshot, path)) {
     return { kind: "link", line, named, message: `links to \`${named}\`, which is not in the repository`, missing: { type: "file", path } };
   }
   const anchor = hash < 0 ? "" : target.slice(hash + 1);
+  if (anchor === "") return undefined;
   const anchors = snapshot.anchors.get(path);
-  if (anchor === "" || anchors === undefined || anchors.has(anchor) || anchors.has(anchor.toLowerCase())) return undefined;
+  if (anchors === undefined) {
+    return { kind: "link", line, named, message: `links to \`${named}\`, and \`${path}\` has no headings to check`, missing: { type: "anchor" } };
+  }
+  if (anchors.has(anchor) || anchors.has(anchor.toLowerCase())) return undefined;
   return { kind: "link", line, named, message: `links to \`${named}\`, and \`${path}\` has no heading with that anchor`, missing: { type: "anchor" } };
 }
 
@@ -152,9 +160,8 @@ export function anchoredTargets(doc: string, text: string): readonly string[] {
     links.flatMap((target) => {
       const hash = target.indexOf("#");
       if (hash < 0 || SCHEME.test(target)) return [];
-      const written = target.slice(0, hash);
-      const path = written === "" ? doc : written.startsWith("/") ? normalize(written) : within(directoryOf(doc), written);
-      return path?.endsWith(".md") === true ? [path] : [];
+      const path = linkPath(doc, target, hash);
+      return path !== undefined && (path.endsWith(".md") || path.endsWith(".mdx")) ? [path] : [];
     }),
   );
 }

package/src/docs/docs.ts

@@ -8,6 +8,7 @@ import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
 import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { proseFindings, readerOf } from "./prose-matchers.ts";
+import { longSentences } from "./sentence-length.ts";
 
 type Finding = {
   readonly path: string;
@@ -22,6 +23,7 @@ type Judged = {
   readonly agents: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
+  readonly sentenceAdvisory: readonly Finding[];
   readonly brokenBefore: readonly Finding[];
 };
 
@@ -105,6 +107,9 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const prose = edited.flatMap(({ path, reader }) =>
     proseFindings(text(path), reader, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
   );
+  const sentenceAdvisory = edited
+    .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
+    .toSorted(inPathOrder);
   const judging = (path: string): Judging => ({ commands: !speaksToConsumers(text(path)) });
   // A directory the range deletes still belongs to this repository, so a path under it is stale rather than another repository's.
   const roots = rootsOf(yield* pathsAt(base, [], root));
@@ -133,6 +138,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
       ...entries,
     ].toSorted(inPathOrder),
     advisory,
+    sentenceAdvisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
 });
@@ -141,7 +147,7 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, agents, findings, advisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, agents, findings, advisory, sentenceAdvisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
@@ -158,6 +164,13 @@ export function report({ held, edited, named, agents, findings, advisory, broken
           `${NAME}: advisory, ${advisory.size} doc file(s) the range leaves alone do not hold to their templates yet:`,
           ...[...advisory].map(([path, count]) => `  ${path}: ${count} violation(s)`),
         ];
+  const sentences =
+    sentenceAdvisory.length === 0
+      ? []
+      : [
+          `${NAME}: advisory, ${sentenceAdvisory.length} sentence(s) over the trial length caps:`,
+          ...sentenceAdvisory.map(describe),
+        ];
   const broken =
     brokenBefore.length === 0
       ? []
@@ -165,7 +178,7 @@ export function report({ held, edited, named, agents, findings, advisory, broken
           `${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs or agent files name were broken before the range:`,
           ...brokenBefore.map(describe),
         ];
-  return [...verdict, ...unconformed, ...broken].join("\n");
+  return [...verdict, ...unconformed, ...sentences, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {

package/src/docs/prose-matchers.ts

@@ -243,7 +243,7 @@ export function scanMarkdown(text: string): readonly MarkdownLine[] {
 
 const LEADING_MARKERS = /^(?:\s*>)*\s*(?:#{1,6}\s+|(?:[-*+]|\d{1,9}[.)])\s+(?:\[[ xX]\]\s+)?)?/;
 
-function bodyOf({ prose }: MarkdownLine): string {
+export function bodyOf({ prose }: MarkdownLine): string {
   const markers = LEADING_MARKERS.exec(prose)?.[0] ?? "";
   return BLANK.repeat(markers.length) + prose.slice(markers.length);
 }

package/src/docs/sentence-length.ts

@@ -0,0 +1,106 @@
+import { bodyOf, scanMarkdown } from "./prose-matchers.ts";
+
+export const PROCEDURAL_WORD_CAP = 20;
+export const DESCRIPTIVE_WORD_CAP = 25;
+
+export type SentenceKind = "procedural" | "descriptive";
+
+export type SentenceLength = {
+  readonly line: number;
+  readonly words: number;
+  readonly kind: SentenceKind;
+};
+
+export type LongSentence = SentenceLength & {
+  readonly message: string;
+};
+
+function graphemesOf(body: string): readonly string[] {
+  return [...new Intl.Segmenter().segment(body)].map(({ segment }) => segment);
+}
+
+function dropPrefix(raw: string): string {
+  const chars = graphemesOf(raw);
+  for (const [at, char] of chars.entries()) {
+    if (char !== " " && char !== "\t" && char !== ">") return chars.slice(at).join("");
+  }
+  return "";
+}
+
+function orderedAt(raw: string): boolean {
+  const rest = dropPrefix(raw);
+  const digits = /^\d+/.exec(rest)?.[0] ?? "";
+  if (digits === "") return false;
+  const marker = rest.charAt(digits.length);
+  if (marker !== "." && marker !== ")") return false;
+  const after = rest.charAt(digits.length + 1);
+  return after === " " || after === "\t" || after === "";
+}
+
+function isWordChar(char: string): boolean {
+  return (char >= "0" && char <= "9") || (char >= "A" && char <= "Z") || (char >= "a" && char <= "z");
+}
+
+function wordsIn(sentence: string): number {
+  let words = 0;
+  let inToken = false;
+  let holdsWordChar = false;
+  for (const char of sentence) {
+    if (char === " " || char === "\t") {
+      if (inToken && holdsWordChar) words += 1;
+      inToken = false;
+      holdsWordChar = false;
+    } else {
+      inToken = true;
+      if (isWordChar(char)) holdsWordChar = true;
+    }
+  }
+  return inToken && holdsWordChar ? words + 1 : words;
+}
+
+function isCloser(char: string): boolean {
+  return char === '"' || char === "'" || char === ")" || char === "]" || char === "*" || char === "_" || char === "”" || char === "’";
+}
+
+function sentencesIn(body: string): readonly string[] {
+  const chars = graphemesOf(body);
+  const sentences: string[] = [];
+  let start = 0;
+  let cut = -1;
+  for (const [at, char] of chars.entries()) {
+    if (char === "." || char === "!" || char === "?") cut = at + 1;
+    else if (cut === at && isCloser(char)) cut = at + 1;
+    else if (cut > start && (char === " " || char === "\t")) {
+      sentences.push(chars.slice(start, cut).join(""));
+      start = cut;
+      cut = -1;
+    } else if (cut > start) cut = -1;
+  }
+  if (cut === chars.length && cut > start) {
+    sentences.push(chars.slice(start, cut).join(""));
+    start = cut;
+  }
+  const tail = chars.slice(start).join("");
+  if (tail.trim() !== "") sentences.push(tail);
+  return sentences;
+}
+
+export function sentenceLengths(text: string, within?: ReadonlySet<number>): readonly SentenceLength[] {
+  return scanMarkdown(text).flatMap((line) => {
+    if (line.kind !== "prose" || (within !== undefined && !within.has(line.line))) return [];
+    const kind: SentenceKind = orderedAt(line.raw) ? "procedural" : "descriptive";
+    return sentencesIn(bodyOf(line)).map((sentence) => ({ line: line.line, words: wordsIn(sentence), kind }));
+  });
+}
+
+export function longSentences(text: string, within?: ReadonlySet<number>): readonly LongSentence[] {
+  return sentenceLengths(text, within).flatMap(({ line, words, kind }) => {
+    const cap = kind === "procedural" ? PROCEDURAL_WORD_CAP : DESCRIPTIVE_WORD_CAP;
+    if (words <= cap) return [];
+    const rule =
+      kind === "procedural"
+        ? `procedural means an ordered list item; descriptive caps at ${DESCRIPTIVE_WORD_CAP} words`
+        : `procedural means an ordered list item, capped at ${PROCEDURAL_WORD_CAP} words`;
+    return [{ line, words, kind, message: `carries a ${words}-word ${kind} sentence, over the ${cap}-word cap (${rule})` }];
+  });
+}

package/src/testing/flake.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
 

package/src/testing/mutation.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Config, Effect, Schema } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain } from "../core/main.ts";
 import { fullRunRefusal } from "./mutation-scope.js";
 

package/src/testing/test.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { TEST_ENTRY_POINT } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
 import { readSkipDeclarations, type Environment, type SkipDeclaration, type TestTier } from "./test-skips.ts";