@avi2dg/checks 0.65.2 → 0.66.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.66.0
+
+Released 2026-11-05.
+
+### Features
+
+- **docs:** cap READMEs at 6,000 characters and table cells at 300 [#46](https://github.com/avi2d/checks/pull/46)
+
+## 0.65.3
+
+Released 2026-11-04.
+
+### Fixes
+
+- **ci-wiring:** require the night run step in TypeScript repositories [#45](https://github.com/avi2d/checks/pull/45)
+
 ## 0.65.2
 
 Released 2026-11-04.

package/docs/bins.md

@@ -65,7 +65,7 @@ These bins run on their own:
 - [`checks-commit-title`](gates/checks-commit-title.md) lints the pull request title in one step of the `ci` job.
 - [`checks-pr-text`](gates/checks-pr-text.md) scans the title, body and comments of a pull request in a public repository for a secret or a term of the private pack.
 - [`checks-docs-only`](gates/checks-docs-only.md) tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full run.
-- [`checks-setup`](gates/checks-setup.md) writes the kit config, the CI workflow and the doc templates into a new repository.
+- [`checks-setup`](gates/checks-setup.md) writes the kit config, the CI workflow, the night-run workflow and the doc templates into a new repository.
 
 `checks-lint` has [its own page](gates/checks-lint.md), which says which range it resolves.
 oxlint runs through its own tool, as [Native settings](configs/native-settings.md) says.

package/docs/gates/checks-advisories.md

@@ -116,7 +116,7 @@ on:
   workflow_dispatch:
 jobs:
   advisories:
-    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v5
@@ -127,7 +127,8 @@ 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 public repository keeps `runs-on: ubuntu-latest`.
+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.
 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.
 

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

@@ -32,6 +32,16 @@ A workflow without a `name` answers to its path from the repository root.
 A local reusable `uses` must name a file under `.github/workflows/` that the repository holds.
 Each `needs` entry names a job in the same workflow, so every one must match a job id in that file.
 Each refusal names the file, the line and the missing workflow or job.
+It requires a run step that invokes `checks-lint --night` in a repository that tracks TypeScript, so the four nightly gates run on the night run.
+A call counts directly, through `bunx`, or through `bun` or `bun run` with the bin's path or its source file.
+The call carries only `--night`, since any other argument stops the night run before it runs a gate.
+A call through a `package.json` script counts, as `bun run <script>` where the named script runs the night step with the arguments the step passes.
+A call through a local reusable workflow counts only through a job that uses the file that runs the night step.
+A call through a repository shell script counts, as a path inside the repository whose file runs the night step.
+A shell wrapper forwards its arguments through a standalone `"$@"`, so `exec checks-lint --night "$@"` counts with no arguments passed.
+Shell control flow inside scripts is not evaluated: a night call after `false &&`, in an `if` branch, in a loop body or after `exit 0` counts all the same.
+A call inside a function body counts whether or not the workflow calls the function.
+A step or job with `if: false` or `continue-on-error: true` never counts, nor does a job that waits on one that never runs.
 
 ### Runners
 
@@ -123,6 +133,7 @@ Each refusal names the workflow file, the job and the limit.
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts`, `private` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
+It lists the `*.ts` and `*.tsx` files `git ls-files` tracks to decide whether the night run applies.
 It reads each file a setup-bun step names for its version.
 It reads the fleet pin from the kit's own `.bun-version`.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
@@ -138,7 +149,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, or a job can run for more than 60 minutes. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, a job can run for more than 60 minutes, or a repository that tracks TypeScript never runs `checks-lint --night`. |
 | 2 | A workflow or `package.json` cannot be decoded, or the kit's own `.bun-version` is missing, unreadable or blank. |
 
 ## Sample output
@@ -151,6 +162,14 @@ ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
     no run step invokes it
 ```
 
+A missing night step produces a report like this:
+
+```
+ci-wiring: 1 gate(s) never run on the night run:
+  checks-lint --night
+    no run step invokes it
+```
+
 A mutation job that names `CI_RUNS_ON` in `runs-on` produces a report like this:
 
 ```

package/docs/gates/checks-docs.md

@@ -16,6 +16,7 @@ It fails when such a line copies a version `package.json` or `.bun-version` pins
 It fails when a living doc or an agent file names a path, link or command that does not resolve, and the range added or broke it.
 It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
 It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
+It fails when a range edits a README that is over 6,000 characters or holds a table cell over 300, as [README ceilings](#readme-ceilings) says.
 It fails when a living doc or an agent file names a code span the range removed from every file outside the docs, on any line.
 [Paths, links and commands](#paths-links-and-commands) says how each reference resolves.
 The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
@@ -188,6 +189,23 @@ An entry is any list item a reader sees as CommonMark renders the file, the item
 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.
 
+## README ceilings
+
+The root `README.md` and every `README.md` beside a `package.json` take two ceilings, since npm shows a package's README as its front page:
+
+- The file holds at most 6,000 characters, counted as the agent file ceiling counts them.
+  The failure names the file's size and its largest section, and says to move that section to a page under `docs/`.
+- A table cell holds at most 300 characters.
+  A table follows the GitHub table rules, with a header row above a delimiter row with the same cell count.
+  Every line after the delimiter counts until a blank line.
+  Tables indented by four spaces or a tab, and tables inside blockquotes, are left unchecked.
+  Lines in fenced or indented code never count as table rows.
+  An escaped `\|` never ends a cell.
+
+No line in a complete same-named generated block counts toward either ceiling, from its `<!-- generated <name>: ... -->` line to its `<!-- end generated <name> -->` line, so a generated index sizes itself.
+A README fails only in a range that edits it.
+A README the range leaves alone is listed as advisory, so the first change that edits an oversize README shrinks it.
+
 ## What it reads
 
 It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
@@ -198,6 +216,7 @@ It compares each code span a living doc or an agent file names with the text git
 It reads the repository's own name and its direct dependencies from the root `package.json` at the head commit.
 It reads the versions the root `package.json` and `.bun-version` pin at the head commit.
 It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
+It reads the root `README.md` and each `README.md` beside a tracked `package.json` at the head commit for the README ceilings.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
 
@@ -215,8 +234,8 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, every README the range edits holds to the README ceilings, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, a README the range edits is over a README ceiling, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
@@ -232,6 +251,8 @@ docs: 7 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 README ceiling finding(s) in README(s) the range leaves alone:
+  packages/run/README.md: is 6412 characters, over the 6,000-character ceiling for a README. Its largest section is `## Configure a run` at 2310 characters. Move that section to a page under docs/ and link it from the README in one line
 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:
@@ -243,6 +264,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository adopts the templates as its files change, and the prose rules as its lines change, because an untouched file or line never fails those checks.
 It reshapes its agent files when it adopts the gate, because [Agent files](#agent-files) judges each one whatever the range touches.
+It shrinks an oversize README in the first change that edits it, because [README ceilings](#readme-ceilings) judges only a README the range edits.
 A name the range removes fails wherever a doc still carries it, because the removal is what turned the line stale.
 
 ## Related topics

package/docs/gates/checks-setup.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-setup
 
-`checks-setup` writes the kit config, the CI workflow and the doc templates into a repository that does not hold them yet.
+`checks-setup` writes the kit config, the CI workflow, the night-run workflow and the doc templates into a repository that does not hold them yet.
 
 ## What it checks
 
@@ -30,6 +30,9 @@ A newer push to the same pull request cancels the run in progress.
 A `--private` run pins each job to `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
 Setting the `CI_RUNS_ON` variable to a self-hosted runner label then lands the jobs there.
 A public run pins each job to `ubuntu-latest`.
+It writes `.github/workflows/night-run.yml`, which installs with `bun install --frozen-lockfile` and then runs `bunx checks-lint --night`.
+It runs on manual dispatch alone.
+Its job uses the same runner choice as the CI workflow.
 It copies each kit template under `dist/templates/` into `templates/`, so a new doc file starts from a copy there.
 It names every file it wrote and every file it kept.
 It tells the owner to declare the repository owners in `package.json` `author` or `contributors` before the first commit.

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

@@ -133,6 +133,27 @@ The same job reports the title step's outcome under that name on every run, whic
    ```
 
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](../gates/checks-ci-wiring.md#runners) requires.
+Run the four nightly gates from a night-run workflow once the repository tracks TypeScript:
+
+   ```yaml
+   name: night-run
+   on:
+     workflow_dispatch:
+   jobs:
+     gates:
+       runs-on: ubuntu-latest
+       timeout-minutes: 20
+       steps:
+         - uses: actions/checkout@v5
+           with:
+             fetch-depth: 0
+         - uses: oven-sh/setup-bun@v2
+           with:
+             bun-version-file: .bun-version
+         - run: bun install --frozen-lockfile
+         - run: bunx checks-lint --night
+   ```
+
 `checks-effect-scope` writes the Effect paths of `oxlint.config.ts` and the kit's severities into `tsconfig.json`, as [The Effect rules](../configs/effect-rules.md#language-service) says.
 `bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
 

package/docs/how-to/upgrade-the-kit.md

@@ -31,6 +31,8 @@ To move a repository to a newer release of the kit:
 1. Run `bun run build`, whose `checks-effect-scope` rewrites the Effect override and the kit's severities in `tsconfig.json` when a release changes them.
    A severity key the release drops stays in `tsconfig.json` until the repository removes it.
 1. Copy `node_modules/@avi2dg/checks/bunfig.toml` over `bunfig.toml` again, since `checks-test-layout` compares the copy with the installed preset.
+1. When the repository tracks TypeScript, add a night-run workflow with a run step that invokes `checks-lint --night`, as [Set up a repository](set-up-a-repository.md) shows, or add that step to the workflow that already runs nightly.
+   Only that step runs the four nightly gates.
 1. Run `bun run lint`, `bun run typecheck` and `bun run test`.
 
 The repository's lockfile pins the kit, so a repository moves only when it runs these steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.65.2",
+  "version": "0.66.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -74,6 +74,7 @@
     "src/testing/night-run.ts",
     "src/testing/night-run-findings.ts",
     "src/delivery/ci-wiring.ts",
+    "src/delivery/night-step.ts",
     "src/delivery/shell-command.ts",
     "src/delivery/workflow-references.ts",
     "src/delivery/bun-pin.ts",

package/src/delivery/ci-wiring.ts

@@ -2,7 +2,7 @@
 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 { ENTRY_POINT, KIT_GATES, TYPESCRIPT_SOURCE, type KitGate } from "../core/gates.ts";
 import { findBunPinFaults, formatBunPinReport, readBunPinPolicy } from "./bun-pin.ts";
 import { findLongJobs, formatLongJobReport } from "./job-timeout.ts";
 import { readScheduleFiles, readShellFiles } from "./mutation-job.ts";
@@ -10,7 +10,8 @@ import { findScheduledReleases, formatScheduleReport } from "./release-schedule.
 import { findRunnerFaults, formatRunnerReport, jobRuns, readRunnerConfig } from "./runner-policy.ts";
 import { findScheduledRuns, formatScheduledRunReport } from "./schedule-policy.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
-import { findMissingWorkflows, formatMissingReport, isRecord, names, workflowJobs, type Workflow } from "./workflow-references.ts";
+import { findNightStepFaults, formatNightStepReport } from "./night-step.ts";
+import { findMissingWorkflows, formatMissingReport, isRecord, localUses, names, skippedBy, switchedOff, workflowJobs, type Workflow } from "./workflow-references.ts";
 
 export { BunPinError, findBunPinFaults, formatBunPinReport } from "./bun-pin.ts";
 export { RunnerPolicyError } from "./runner-policy.ts";
@@ -71,26 +72,8 @@ const ScriptsManifest = Schema.Struct({
 });
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
-const CONSTANTS = new Map([
-  ["true", true],
-  ["false", false],
-]);
-const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
 const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
-function constant(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") return value;
-  if (typeof value !== "string") return undefined;
-  const expression = value.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
-  return CONSTANTS.get(expression);
-}
-
-function switchedOff(node: Readonly<Record<string, unknown>>, subject: string): string | undefined {
-  if (constant(node["if"]) === false) return `${subject} sets if: false`;
-  if (constant(node["continue-on-error"]) === true) return `${subject} sets continue-on-error: true`;
-  return undefined;
-}
-
 // Last match wins, as GitHub evaluates a branch filter, so one match anywhere is not enough.
 function selects(patterns: readonly string[], branch: string): boolean {
   let selected = false;
@@ -125,23 +108,6 @@ const pullRequestTrigger = (branch: string): Trigger => (workflow) => {
   return undefined;
 };
 
-// GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
-function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
-  const job = jobs[id];
-  if (!isRecord(job) || seen.includes(id)) return undefined;
-  if (constant(job["if"]) === false) return `job ${id} sets if: false`;
-  if (typeof job["if"] === "string" && STATUS_OVERRIDE.test(job["if"])) return undefined;
-  for (const need of names(job["needs"]) ?? []) {
-    const cause = skippedBy(jobs, need, [...seen, id]);
-    if (cause !== undefined) return cause;
-  }
-  return undefined;
-}
-
-function localCall(uses: unknown): string | undefined {
-  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
-}
-
 function runSteps(workflows: readonly Workflow[], trigger: Trigger): readonly RunStep[] {
   const documents = new Map(workflows.map((workflow) => [workflow.path, workflow.document]));
   const steps: RunStep[] = [];
@@ -162,7 +128,7 @@ function runSteps(workflows: readonly Workflow[], trigger: Trigger): readonly Ru
         blocker ??
         switchedOff(job, `job ${id}`) ??
         (skipped === undefined ? undefined : `job ${id} needs a job that never runs: ${skipped}`);
-      const called = localCall(job["uses"]);
+      const called = localUses(job["uses"]);
       if (called !== undefined && !walked.includes(called)) {
         visit(documents.get(called), `${jobLocation} > ${called}`, jobBlocker, [...walked, called]);
       }
@@ -345,7 +311,11 @@ const wiring = Effect.gen(function* () {
   if (scheduledRuns.length > 0) yield* Console.error(formatScheduledRunReport(scheduledRuns));
   const longJobs = findLongJobs(workflows);
   if (longJobs.length > 0) yield* Console.error(formatLongJobReport(longJobs));
-  return [gaps, faults, missing, bunFaults, scheduled, scheduledRuns, longJobs].every((found) => found.length === 0);
+  const tracksTypeScript =
+    (yield* git(["ls-files", "--", ...TYPESCRIPT_SOURCE.pathspecs], root)).trim() !== "";
+  const nightFaults = findNightStepFaults(tracksTypeScript, workflows, { scripts, files: scheduleFiles });
+  if (nightFaults.length > 0) yield* Console.error(formatNightStepReport(nightFaults));
+  return [gaps, faults, missing, bunFaults, scheduled, scheduledRuns, longJobs, nightFaults].every((found) => found.length === 0);
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/mutation-job.ts

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Path } from "effect";
-import { fromProgram, SHELLS, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+import { fromProgram, SHELLS, shellWords, withoutOptions, type Command, type Word } from "./shell-command.ts";
 
 // An undefined directory is one known only at run time.
 export type Run = {
@@ -9,7 +9,7 @@ export type Run = {
 
 type Invocation =
   | { readonly script: string; readonly body: string }
-  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined };
+  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined; readonly argv: Command };
 
 type Walked = {
   readonly scripts: readonly string[];
@@ -53,7 +53,31 @@ export function runsBin(
   isBin: BinCheck,
   followShellOperands = false,
 ): boolean {
-  return scriptRunsBin(run.script, run.dir, { scripts, files }, { scripts: [], files: [] }, isBin, followShellOperands);
+  return scriptRunsBin(run.script, run.dir, { scripts, files }, { scripts: [], files: [] }, isBin, followShellOperands, []);
+}
+
+
+function isPositionalForward(script: string, word: Word): boolean {
+  if (word.text !== "$@") return false;
+  if (script[word.start] === '"') return script.slice(word.start, word.start + 4) === '"$@"';
+  return script[word.start] === "$" && script[word.start + 1] === "@";
+}
+
+function expandArgv(script: string, words: readonly Word[], argv: Command): Command {
+  return words.flatMap((word) => (isPositionalForward(script, word) ? argv : [word.text]));
+}
+
+function runsExpanded(
+  expanded: Command,
+  cwd: string | undefined,
+  context: Context,
+  walked: Walked,
+  isBin: BinCheck,
+  followShellOperands: boolean,
+): { readonly matched: boolean; readonly cwd: string | undefined } {
+  const [program = "", ...args] = fromProgram(expanded);
+  if (program === "cd") return { matched: false, cwd: changedDirectory(cwd, withoutOptions(args, new Set())) };
+  return { matched: binCommand(expanded, cwd, context, walked, isBin, followShellOperands), cwd };
 }
 
 function scriptRunsBin(
@@ -63,12 +87,14 @@ function scriptRunsBin(
   walked: Walked,
   isBin: BinCheck,
   followShellOperands: boolean,
+  argv: Command,
 ): boolean {
+  const parsed = shellWords(script);
   let cwd = dir;
-  for (const command of shellCommands(script)) {
-    const [program = "", ...args] = fromProgram(command);
-    if (program === "cd") cwd = changedDirectory(cwd, withoutOptions(args, new Set()));
-    else if (binCommand(command, cwd, context, walked, isBin, followShellOperands)) return true;
+  for (const words of parsed) {
+    const next = runsExpanded(expandArgv(script, words, argv), cwd, context, walked, isBin, followShellOperands);
+    if (next.matched) return true;
+    cwd = next.cwd;
   }
   return false;
 }
@@ -92,13 +118,20 @@ function fileAt(dir: string | undefined, path: string): string | undefined {
   return within(dir, path) || undefined;
 }
 
+const PLAIN_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+function quotedWord(word: string): string {
+  if (word !== "" && PLAIN_WORD.test(word)) return word;
+  return `'${word.replace(/'/g, "'\\''")}'`;
+}
+
 function invocation(command: Command, dir: string | undefined, context: Context, walked: Walked, followShellOperands: boolean): Invocation | undefined {
   const [first = "", ...rest] = fromProgram(command);
   if (first !== "bun") {
     if (followShellOperands && rest[0] !== undefined && !rest[0].startsWith("-") && SHELLS.includes(first.slice(first.lastIndexOf("/") + 1))) {
-      return { program: [first, ...rest], file: fileAt(dir, rest[0]), dir };
+      return { program: [first, ...rest], file: fileAt(dir, rest[0]), dir, argv: rest.slice(1) };
     }
-    return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir };
+    return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir, argv: rest };
   }
   const [subcommand = "", ...operands] = withoutOptions(rest, BUN_OPERANDS);
   if (subcommand === "x") return invocation(["bunx", ...operands], dir, context, walked, followShellOperands);
@@ -106,7 +139,8 @@ function invocation(command: Command, dir: string | undefined, context: Context,
   const [target = "", ...targetArgs] = subcommand === "run" ? withoutOptions(operands, BUN_OPERANDS) : [subcommand, ...operands];
   const cwd = bunDirectory([...bunOptions(rest), ...(subcommand === "run" ? bunOptions(operands) : [])], dir);
   const body = walked.scripts.includes(target) ? undefined : context.scripts.get(target);
-  return body === undefined ? { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd } : { script: target, body };
+  if (body === undefined) return { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd, argv: targetArgs };
+  return { script: target, body: targetArgs.length === 0 ? body : `${body} ${targetArgs.map(quotedWord).join(" ")}` };
 }
 
 function binCommand(
@@ -120,14 +154,16 @@ function binCommand(
   const call = invocation(command, dir, context, walked, followShellOperands);
   if (call === undefined) return false;
   // bun runs a script from the directory of the package.json that names it.
-  if ("body" in call) return scriptRunsBin(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] }, isBin, followShellOperands);
-  return isBin(call.program) || fileRunsBin(call.file, call.dir, context, walked, isBin, followShellOperands);
+  if ("body" in call)
+    return scriptRunsBin(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] }, isBin, followShellOperands, []);
+  return isBin(call.program) || fileRunsBin(call.file, call.dir, call.argv, context, walked, isBin, followShellOperands);
 }
 
 // A script file runs in its caller's directory, not its own.
 function fileRunsBin(
   file: string | undefined,
   dir: string | undefined,
+  argv: Command,
   context: Context,
   walked: Walked,
   isBin: BinCheck,
@@ -135,7 +171,10 @@ function fileRunsBin(
 ): boolean {
   if (file === undefined || walked.files.includes(file)) return false;
   const body = context.files(file);
-  return body !== undefined && scriptRunsBin(body, dir, context, { ...walked, files: [...walked.files, file] }, isBin, followShellOperands);
+  return (
+    body !== undefined &&
+    scriptRunsBin(body, dir, context, { ...walked, files: [...walked.files, file] }, isBin, followShellOperands, argv)
+  );
 }
 
 function mutationBin([program = "", subcommand]: Command): boolean {

package/src/delivery/night-step.ts

@@ -0,0 +1,79 @@
+import { ENTRY_POINT } from "../core/gates.ts";
+import { runsBin } from "./mutation-job.ts";
+import type { ScheduleContext } from "./release-schedule.ts";
+import { jobRuns } from "./runner-policy.ts";
+import type { Command } from "./shell-command.ts";
+import { isRecord, localUses, names, skippedBy, switchedOff, type Workflow } from "./workflow-references.ts";
+
+const NIGHT_STEP = `${ENTRY_POINT.bin} --night`;
+
+export type NightStepFault = {
+  readonly gate: string;
+};
+
+const NIGHT_BINS = [ENTRY_POINT.bin, ENTRY_POINT.script];
+
+function isNightLint([head = "", ...rest]: Command): boolean {
+  return NIGHT_BINS.some((name) => head === name || head.endsWith("/" + name)) && rest.length === 1 && rest[0] === "--night";
+}
+
+function rootBlocker(workflow: Workflow): string | undefined {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const events = isRecord(on) ? Object.keys(on) : (names(on) ?? []);
+  if (events.length > 0 && events.every((event) => event.toLowerCase() === "workflow_call")) {
+    return `${workflow.path} runs only when called`;
+  }
+  return undefined;
+}
+
+function workflowRunsNightStep(
+  workflow: Workflow,
+  context: ScheduleContext,
+  byPath: ReadonlyMap<string, Workflow>,
+  walkedWorkflows: readonly string[],
+  inherited: string | undefined,
+): boolean {
+  const files = (file: string) => context.files.get(file);
+  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+  if (!isRecord(jobs)) return false;
+  return Object.entries(jobs).some(([id, job]) => {
+    if (!isRecord(job)) return false;
+    const skipped = skippedBy(jobs, id, []);
+    const jobBlocker =
+      inherited ?? switchedOff(job, `job ${id}`) ?? (skipped === undefined ? undefined : `job ${id} needs a job that never runs: ${skipped}`);
+    const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+    const runRecords: readonly Readonly<Record<string, unknown>>[] = steps.flatMap((step: unknown) =>
+      isRecord(step) && typeof step["run"] === "string" ? [step] : [],
+    );
+    const unblocked = jobRuns(workflow, job).some(
+      (run, index) =>
+        (jobBlocker ?? switchedOff(runRecords[index] ?? {}, "the step")) === undefined &&
+        runsBin(run, context.scripts, files, isNightLint, true),
+    );
+    if (unblocked) return true;
+    const called = localUses(job["uses"]);
+    if (called === undefined || walkedWorkflows.includes(called)) return false;
+    const next = byPath.get(called);
+    return next !== undefined && workflowRunsNightStep(next, context, byPath, [...walkedWorkflows, called], jobBlocker);
+  });
+}
+
+function runsNightStep(workflows: readonly Workflow[], context: ScheduleContext): boolean {
+  const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
+  return workflows.some((workflow) => workflowRunsNightStep(workflow, context, byPath, [workflow.path], rootBlocker(workflow)));
+}
+
+export function findNightStepFaults(
+  tracksTypeScript: boolean,
+  workflows: readonly Workflow[],
+  context: ScheduleContext,
+): readonly NightStepFault[] {
+  return tracksTypeScript && !runsNightStep(workflows, context) ? [{ gate: NIGHT_STEP }] : [];
+}
+
+export function formatNightStepReport(faults: readonly NightStepFault[]): string {
+  return [
+    "ci-wiring: " + faults.length + " gate(s) never run on the night run:",
+    ...faults.flatMap(({ gate }) => ["  " + gate, "    no run step invokes it"]),
+  ].join("\n");
+}

package/src/delivery/release-schedule.ts

@@ -1,7 +1,7 @@
 import { runsBin } from "./mutation-job.ts";
 import { jobRuns } from "./runner-policy.ts";
 import type { Command } from "./shell-command.ts";
-import { isRecord, locate, names, workflowJobs, type Workflow } from "./workflow-references.ts";
+import { isRecord, localUses, locate, names, workflowJobs, type Workflow } from "./workflow-references.ts";
 
 export type ScheduledRelease = {
   readonly location: string;
@@ -35,11 +35,6 @@ function isReleaseCommand(program: Command): boolean {
   return isPublishCommand(program) || isBinIn(RELEASE_BINS, program[0] ?? "");
 }
 
-function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
-  const uses = job["uses"];
-  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
-}
-
 function workflowRuns(
   workflow: Workflow,
   context: ScheduleContext,
@@ -55,7 +50,7 @@ function workflowRuns(
   )
     return true;
   return workflowJobs(workflow).some(([, job]) => {
-    const called = localUses(job);
+    const called = localUses(job["uses"]);
     if (called === undefined || walkedWorkflows.includes(called)) return false;
     const next = byPath.get(called);
     return next !== undefined && workflowRuns(next, context, isBin, byPath, [...walkedWorkflows, called]);

package/src/delivery/setup-workflow.ts

@@ -1,6 +1,31 @@
 const HOSTED_FALLBACK = "ubuntu-latest";
 const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 
+export function nightWorkflow(isPrivate: boolean): string {
+  const lines = [
+    "name: night-run",
+    "",
+    "on:",
+    "  workflow_dispatch:",
+    "",
+    "jobs:",
+    "  gates:",
+    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
+    "    timeout-minutes: 20",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: oven-sh/setup-bun@v2",
+    "        with:",
+    "          bun-version-file: .bun-version",
+    "      - run: bun install --frozen-lockfile",
+    "      - run: bunx checks-lint --night",
+    "",
+  ];
+  return lines.join("\n");
+}
+
 export function ciWorkflow(isPrivate: boolean, hasBuild: boolean): string {
   const lines = [
     "name: ci",

package/src/delivery/setup.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
-import { ciWorkflow } from "./setup-workflow.ts";
+import { ciWorkflow, nightWorkflow } from "./setup-workflow.ts";
 import { TEMPLATES } from "../docs/doc-templates.ts";
 import { scriptOptions } from "../testing/test.ts";
 import { withServiceOverrides, type ServiceOverride } from "../quality/effect-scope.ts";
@@ -349,6 +349,7 @@ const check = Effect.gen(function* () {
   yield* setupTsconfig(root, oxlintText);
   yield* setupFile(root, "knip.config.ts", KNIP_CONFIG);
   yield* setupFile(root, ".github/workflows/ci.yml", ciWorkflow(isPrivate, outcome.hasBuild));
+  yield* setupFile(root, ".github/workflows/night-run.yml", nightWorkflow(isPrivate));
   for (const kind of Object.keys(TEMPLATES)) {
     yield* setupFile(root, "templates/" + kind + ".md", yield* kitText("dist/templates/" + kind + ".md"));
   }

package/src/delivery/workflow-references.ts

@@ -26,6 +26,42 @@ export function names(value: unknown): readonly string[] | undefined {
   return value.filter((entry): entry is string => typeof entry === "string");
 }
 
+const CONSTANTS = new Map([
+  ["true", true],
+  ["false", false],
+]);
+const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+
+function constant(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return undefined;
+  const expression = value.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+  return CONSTANTS.get(expression);
+}
+
+export function switchedOff(node: Readonly<Record<string, unknown>>, subject: string): string | undefined {
+  if (constant(node["if"]) === false) return `${subject} sets if: false`;
+  if (constant(node["continue-on-error"]) === true) return `${subject} sets continue-on-error: true`;
+  return undefined;
+}
+
+// GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
+export function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
+  const job = jobs[id];
+  if (!isRecord(job) || seen.includes(id)) return undefined;
+  if (constant(job["if"]) === false) return `job ${id} sets if: false`;
+  if (typeof job["if"] === "string" && STATUS_OVERRIDE.test(job["if"])) return undefined;
+  for (const need of names(job["needs"]) ?? []) {
+    const cause = skippedBy(jobs, need, [...seen, id]);
+    if (cause !== undefined) return cause;
+  }
+  return undefined;
+}
+
+export function localUses(uses: unknown): string | undefined {
+  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
+}
+
 type Key = string | number;
 
 type Target = { readonly name: string; readonly invocation: number };

package/src/docs/doc-agents.ts

@@ -1,8 +1,18 @@
 import { Parser, type NodeType } from "commonmark";
 import { commandNames, type Snapshot } from "./doc-references.ts";
+import { handWritten } from "./doc-versions.ts";
 import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
 
 export const AGENT_CEILING = 3000;
+export const README_CEILING = 6000;
+export const CELL_CEILING = 300;
+
+const README = "README.md";
+const MANIFEST = "package.json";
+const SECOND_LEVEL = /^\s{0,3}##(?:\s+|$)(.*?)(?:\s+#+)?\s*$/;
+const SETEXT_SECOND = /^\s{0,3}-+\s*$/;
+const CELL_SEPARATOR = /(?<!\\)\|/;
+const ROW_EDGES = /^\||(?<!\\)\|$/g;
 
 const INLINE_LINK =
   /(?<![!\\])\[(?:[^[\]\\]|\\.|\[[^\]]*\])*\]\(\s*(?:<[^<>\n]+>|[^\s()<>]+(?:\([^\s()]*\)[^\s()<>]*)*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
@@ -25,6 +35,167 @@ export function ceilingFinding(text: string): AgentFinding | undefined {
   };
 }
 
+export function isCeiledReadme(repositoryPath: string, files: ReadonlySet<string>): boolean {
+  if (repositoryPath === README) return true;
+  return repositoryPath.endsWith(`/${README}`) && files.has(`${repositoryPath.slice(0, -README.length)}${MANIFEST}`);
+}
+
+type Part = { readonly title: string; readonly lines: readonly MarkdownLine[] };
+
+function endingLengths(text: string): readonly number[] {
+  const pieces = text.split("\n");
+  return pieces.map((piece, index) => (index < pieces.length - 1 ? (piece.endsWith("\r") ? 2 : 1) : 0));
+}
+
+function sizeOf(lines: readonly MarkdownLine[], endings: readonly number[]): number {
+  return lines.reduce((sum, { line, raw }) => sum + raw.length + (endings[line - 1] ?? 0), 0);
+}
+
+function sectionTitle(line: MarkdownLine, next: MarkdownLine | undefined): string | undefined {
+  if (line.kind !== "heading") return undefined;
+  const atx = SECOND_LEVEL.exec(line.raw);
+  if (atx !== null) return atx[1] ?? "";
+  return next !== undefined && SETEXT_SECOND.test(next.raw) ? line.raw.trim() : undefined;
+}
+
+function partsOf(lines: readonly MarkdownLine[]): readonly Part[] {
+  const starts = lines.flatMap((line, index) => {
+    const title = sectionTitle(line, lines[index + 1]);
+    return title === undefined ? [] : [{ index, title: `\`## ${title}\`` }];
+  });
+  const bounds = [{ index: 0, title: "the text before the first section" }, ...starts];
+  return bounds.map(({ index, title }, at) => ({ title, lines: lines.slice(index, bounds[at + 1]?.index ?? lines.length) }));
+}
+
+function largestPart(lines: readonly MarkdownLine[], endings: readonly number[]): { readonly title: string; readonly size: number } {
+  return partsOf(lines)
+    .map(({ title, lines: held }) => ({ title, size: sizeOf(held, endings) }))
+    .reduce((largest, part) => (part.size > largest.size ? part : largest));
+}
+
+function cellsOf(raw: string): readonly string[] {
+  return raw.trim().replaceAll(ROW_EDGES, "").split(CELL_SEPARATOR).map((cell) => cell.trim());
+}
+
+const DELIMITER_CELL = /^\s*:?-+:?\s*$/;
+
+function isDelimiterRow(raw: string): boolean {
+  if (/^\s*>/.test(raw)) return false;
+  if (/^(?: {4}|\t)/.test(raw)) return false;
+  const trimmed = raw.trim();
+  if (!trimmed.includes("|") || !trimmed.includes("-")) return false;
+  const inner = trimmed.replace(/^\|/, "").replace(/\|$/, "");
+  return inner.split("|").every((cell) => DELIMITER_CELL.test(cell));
+}
+
+function codeLinesIn(scanned: readonly MarkdownLine[]): ReadonlySet<number> {
+  const read = scanned.map(({ kind, raw }) => (kind === "front-matter" ? "" : raw)).join("\n");
+  const walker = new Parser().parse(read).walker();
+  const excluded = new Set<number>();
+  for (let step = walker.next(); step !== null; step = walker.next()) {
+    if (step.entering && step.node.type === "code_block") {
+      const start = step.node.sourcepos[0][0];
+      const end = step.node.sourcepos[1][0];
+      for (let line = start; line <= end; line += 1) excluded.add(line);
+    }
+  }
+  return excluded;
+}
+
+function isTableCandidate(line: MarkdownLine, code: ReadonlySet<number>): boolean {
+  if (line.kind !== "prose" && line.kind !== "table") return false;
+  if (code.has(line.line)) return false;
+  if (/^\s*>/.test(line.raw)) return false;
+  if (/^(?: {4}|\t)/.test(line.raw)) return false;
+  return true;
+}
+
+type TableRow = { readonly line: number; readonly raw: string; readonly width: number };
+
+function isBodyLine(line: MarkdownLine, code: ReadonlySet<number>): boolean {
+  if (line.raw.trim() === "") return false;
+  if (code.has(line.line)) return false;
+  if (/^\s*>/.test(line.raw)) return false;
+  if (/^(?: {4}|\t)/.test(line.raw)) return false;
+  return true;
+}
+
+type HeaderMatch = { readonly header: MarkdownLine; readonly delimiterLine: number; readonly width: number };
+
+function matchHeader(lines: readonly MarkdownLine[], at: number, code: ReadonlySet<number>): HeaderMatch | undefined {
+  const delimiter = lines[at];
+  if (delimiter === undefined || !isTableCandidate(delimiter, code)) return undefined;
+  if (!isDelimiterRow(delimiter.raw) || !CELL_SEPARATOR.test(delimiter.raw)) return undefined;
+  const header = lines[at - 1];
+  if (header === undefined || header.line + 1 !== delimiter.line) return undefined;
+  if (!isTableCandidate(header, code) || !CELL_SEPARATOR.test(header.raw)) return undefined;
+  const width = cellsOf(header.raw).length;
+  if (width !== cellsOf(delimiter.raw).length) return undefined;
+  return { header, delimiterLine: delimiter.line, width };
+}
+
+function collectBody(
+  lines: readonly MarkdownLine[],
+  from: number,
+  delimiterLine: number,
+  width: number,
+  code: ReadonlySet<number>,
+): { readonly rows: readonly TableRow[]; readonly last: number } {
+  const rows: TableRow[] = [];
+  let expected = delimiterLine + 1;
+  let last = from - 1;
+  for (let next = from; next < lines.length; next += 1) {
+    const body = lines[next];
+    if (body === undefined || body.line !== expected) break;
+    if (!isBodyLine(body, code)) break;
+    rows.push({ line: body.line, raw: body.raw, width });
+    expected += 1;
+    last = next;
+  }
+  return { rows, last };
+}
+
+function tableRows(lines: readonly MarkdownLine[], code: ReadonlySet<number>): readonly TableRow[] {
+  const rows: TableRow[] = [];
+  for (let at = 0; at < lines.length; at += 1) {
+    const matched = matchHeader(lines, at, code);
+    if (matched === undefined) continue;
+    rows.push({ line: matched.header.line, raw: matched.header.raw, width: matched.width });
+    const body = collectBody(lines, at + 1, matched.delimiterLine, matched.width, code);
+    rows.push(...body.rows);
+    at = body.last;
+  }
+  return rows;
+}
+
+export function readmeFindings(text: string): readonly AgentFinding[] {
+  const scanned = scanMarkdown(text);
+  const endings = endingLengths(text);
+  const lines = handWritten(scanned);
+  const size = sizeOf(lines, endings);
+  const largest = largestPart(lines, endings);
+  const ceiling: readonly AgentFinding[] =
+    size <= README_CEILING
+      ? []
+      : [
+          {
+            line: undefined,
+            message: `is ${size} characters, over the 6,000-character ceiling for a README. Its largest section is ${largest.title} at ${largest.size} characters. Move that section to a page under docs/ and link it from the README in one line`,
+          },
+        ];
+  const rows = tableRows(lines, codeLinesIn(scanned));
+  const cells = rows.flatMap(({ line, raw, width }) =>
+      cellsOf(raw)
+        .slice(0, width)
+        .filter((cell) => cell.length > CELL_CEILING)
+        .map((cell) => ({
+          line,
+          message: `holds a ${cell.length}-character table cell, over the 300-character ceiling for a README table cell. Move the detail to a page under docs/ and keep the cell to what a reader scans`,
+        })),
+    );
+  return [...ceiling, ...cells];
+}
+
 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();

package/src/docs/doc-versions.ts

@@ -64,7 +64,7 @@ function patternOf({ name, version }: Pin): RegExp {
 const GENERATED_OPEN = /^\s*<!-- generated ([\w-]+):/;
 const GENERATED_CLOSE = /^\s*<!-- end generated ([\w-]+) -->/;
 
-function handWritten(lines: readonly MarkdownLine[]): readonly MarkdownLine[] {
+export function handWritten(lines: readonly MarkdownLine[]): readonly MarkdownLine[] {
   const exempt = new Set<number>();
   let at = 0;
   while (at < lines.length) {

package/src/docs/docs.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "./doc-agents.ts";
+import { ceilingFinding, entryFindings, isAgentFile, isCeiledReadme, maintainingFinding, readmeFindings } from "./doc-agents.ts";
 import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
@@ -22,8 +22,10 @@ type Judged = {
   readonly edited: { readonly docs: number; readonly lines: number };
   readonly named: number;
   readonly agents: number;
+  readonly readmes: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
+  readonly readmeAdvisory: readonly Finding[];
   readonly sentenceAdvisory: readonly Finding[];
   readonly brokenBefore: readonly Finding[];
 };
@@ -127,6 +129,8 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
   );
   const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
+  const readmes = proseDocs.filter(({ path }) => isCeiledReadme(path, tracked.files));
+  const oversize = readmes.flatMap(({ path }) => readmeFindings(text(path)).map((finding) => ({ path, ...finding })));
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
@@ -134,6 +138,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
     named: referenced.size,
     agents: agents.length,
+    readmes: readmes.filter(({ path }) => touched.has(path)).length,
     findings: [
       ...templated.filter((finding) => touched.has(finding.path)),
       ...prose,
@@ -142,8 +147,10 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
       ...vanished,
       ...shapes,
       ...entries,
+      ...oversize.filter((finding) => touched.has(finding.path)),
     ].toSorted(inPathOrder),
     advisory,
+    readmeAdvisory: oversize.filter((finding) => !touched.has(finding.path)).toSorted(inPathOrder),
     sentenceAdvisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
@@ -153,7 +160,7 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, agents, findings, advisory, sentenceAdvisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, agents, readmes, findings, advisory, readmeAdvisory, sentenceAdvisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
@@ -162,6 +169,7 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${NAME}: no line the range adds or edits copies a version package.json or .bun-version pins`,
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
           `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
+          `${NAME}: the ${readmes} README(s) the range edits hold to the 6,000-character ceiling and the 300-character table cell ceiling`,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =
@@ -171,6 +179,10 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${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 oversize =
+    readmeAdvisory.length === 0
+      ? []
+      : [`${NAME}: advisory, ${readmeAdvisory.length} README ceiling finding(s) in README(s) the range leaves alone:`, ...readmeAdvisory.map(describe)];
   const sentences =
     sentenceAdvisory.length === 0
       ? []
@@ -185,7 +197,7 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${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, ...sentences, ...broken].join("\n");
+  return [...verdict, ...unconformed, ...oversize, ...sentences, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {