@avi2dg/checks 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 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 -->

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-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-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
 

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.33.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/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/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";