@avi2dg/checks 0.65.3 → 0.67.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.67.0
+
+Released 2026-11-06.
+
+### Features
+
+- **ci-wiring:** accept shared runner pick and setup action [#48](https://github.com/avi2d/checks/pull/48)
+
+## 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.

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

@@ -68,6 +68,10 @@ Any other expression refuses as unresolvable.
 A job on `push` or another trigger no fork reaches may still name self-hosted labels.
 In a private repository each mutation job carries exactly the labels the consumer declares in `package.json` under `checks.mutationRunner`.
 Every other job there carries exactly the hosted-default expression, or exactly one of the label sets the consumer declares under `checks.selfHostedRunners`.
+A job there also carries `runs-on: ${{ needs.<job>.outputs.runs-on }}` when the same workflow needs that job and that job calls the runner pick.
+The pick is the repository file `runner.yml` under `.github/workflows/` or `avi2d/workflows/.github/workflows/runner.yml` at a pinned full SHA.
+A public repository still refuses that expression on a job a fork can reach.
+The resolved label cannot be shown to be a hosted runner before the run.
 A repository without those declarations fails each job they would pin until it declares them.
 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.
 
@@ -90,7 +94,9 @@ The fleet version is the version the kit ships in its own `.bun-version`.
 The step fails the check when the version is missing or differs from the fleet bun version.
 A range fails because it differs from the fleet version.
 A version built from an expression fails because it cannot be shown equal before the run.
-This rule skips a repository with no setup-bun step.
+A step that uses `avi2d/workflows/actions/setup` reads `.bun-version`.
+The step fails the check when `.bun-version` is missing or differs from the fleet bun version.
+This rule skips a repository with no setup-bun step and no shared setup step.
 A kit release that moves the fleet version turns each consumer red until its pin follows.
 Each refusal names the workflow file and line, the version found and where it was read, and the fleet version.
 
@@ -133,8 +139,10 @@ 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 reads each shell script that a shell script it reads runs, until none is left.
 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 `.bun-version` for each step that uses the shared setup action.
 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.
 It reads whether the repository is private from `repository.private` in that event file.
@@ -149,7 +157,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, a job can run for more than 60 minutes, or a repository that tracks TypeScript never runs `checks-lint --night`. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a bun setup 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.65.3",
+  "version": "0.67.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -81,6 +81,7 @@
     "src/delivery/mutation-job.ts",
     "src/delivery/job-timeout.ts",
     "src/delivery/runner-policy.ts",
+    "src/delivery/runner-pick.ts",
     "src/delivery/secrets.ts",
     "src/delivery/secrets-pack.ts",
     "src/delivery/pr-text.ts",

package/src/delivery/bun-pin.ts

@@ -17,12 +17,19 @@ export type BunPinFault = {
 
 const SETUP_BUN = /^oven-sh\/setup-bun(?:@(?<ref>.*))?$/i;
 const V2_REF = /^v2(?:\.\d+){0,2}$/;
+const SHARED_SETUP = /^avi2d\/workflows\/actions\/setup(?:@(?<ref>.*))?$/i;
+const SETUP_VERSION_FILE = ".bun-version";
 
 function setupBunRef(uses: unknown): string | undefined {
   const match = typeof uses === "string" ? SETUP_BUN.exec(uses.trim()) : null;
   return match === null ? undefined : (match.groups?.["ref"] ?? "");
 }
 
+function sharedSetupRef(uses: unknown): string | undefined {
+  const match = typeof uses === "string" ? SHARED_SETUP.exec(uses.trim()) : null;
+  return match === null ? undefined : (match.groups?.["ref"] ?? "");
+}
+
 function isExpression(value: string): boolean {
   return value.includes("${{");
 }
@@ -106,6 +113,15 @@ function unknownRefFault(ref: string): string {
   return `uses oven-sh/setup-bun at ${ref === "" ? "no ref" : ref}, but the check knows only setup-bun v2's version resolution, so the step must use oven-sh/setup-bun@v2`;
 }
 
+function sharedSetupFault(policy: BunPinPolicy, ref: string): string | undefined {
+  const version = nonEmpty(policy.files.get(SETUP_VERSION_FILE));
+  const uses = ref === "" ? "avi2d/workflows/actions/setup" : `avi2d/workflows/actions/setup@${ref}`;
+  if (version === undefined) {
+    return `uses ${uses}, which reads ${SETUP_VERSION_FILE}, but the repository holds no ${SETUP_VERSION_FILE} file, want ${policy.fleet}`;
+  }
+  return version === policy.fleet ? undefined : `requests bun ${version} from ${SETUP_VERSION_FILE}, want ${policy.fleet}`;
+}
+
 export function findBunPinFaults(policy: BunPinPolicy, workflows: readonly Workflow[]): readonly BunPinFault[] {
   return workflows.flatMap((workflow) => {
     const at = locate(workflow.path, workflow.text.split("\n"));
@@ -113,17 +129,25 @@ export function findBunPinFaults(policy: BunPinPolicy, workflows: readonly Workf
       const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
       return steps.flatMap((step: unknown, index: number) => {
         if (!isRecord(step)) return [];
+        const atStep = (fault: string) => [
+          { location: at(["jobs", id, "steps", index, "uses"], String(step["uses"]), `job ${id} step ${index + 1}`), fault },
+        ];
         const ref = setupBunRef(step["uses"]);
-        if (ref === undefined) return [];
-        const fault = V2_REF.test(ref) ? bunPinFault(policy, step) : unknownRefFault(ref);
-        return fault === undefined ? [] : [{ location: at(["jobs", id, "steps", index, "uses"], String(step["uses"]), `job ${id} step ${index + 1}`), fault }];
+        if (ref !== undefined) {
+          const fault = V2_REF.test(ref) ? bunPinFault(policy, step) : unknownRefFault(ref);
+          return fault === undefined ? [] : atStep(fault);
+        }
+        const sharedRef = sharedSetupRef(step["uses"]);
+        if (sharedRef === undefined) return [];
+        const fault = sharedSetupFault(policy, sharedRef);
+        return fault === undefined ? [] : atStep(fault);
       });
     });
   });
 }
 
 export function formatBunPinReport(faults: readonly BunPinFault[]): string {
-  return [`ci-wiring: ${faults.length} setup-bun step(s) drift from the fleet bun version:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+  return [`ci-wiring: ${faults.length} bun setup step(s) drift from the fleet bun version:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
 }
 
 function versionFileKeys(job: Readonly<Record<string, unknown>>): readonly string[] {
@@ -139,11 +163,17 @@ function versionFileKeys(job: Readonly<Record<string, unknown>>): readonly strin
   return keys;
 }
 
+function usesSharedSetup(job: Readonly<Record<string, unknown>>): boolean {
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  return steps.some((step) => isRecord(step) && sharedSetupRef(step["uses"]) !== undefined);
+}
+
 function wantedBunPinFiles(workflows: readonly Workflow[]): ReadonlySet<string> {
   const wanted = new Set<string>([ROOT_MANIFEST]);
   for (const workflow of workflows) {
     for (const [, job] of workflowJobs(workflow)) {
       for (const key of versionFileKeys(job)) wanted.add(key);
+      if (usesSharedSetup(job)) wanted.add(SETUP_VERSION_FILE);
     }
   }
   return wanted;

package/src/delivery/runner-pick.ts

@@ -0,0 +1,29 @@
+import { names, type Workflow } from "./workflow-references.ts";
+
+const NEEDS_RUNS_ON = /^\$\{\{\s*needs\.([\w-]+)\.outputs\.runs-on\s*\}\}$/i;
+const SHARED_RUNNER = /^avi2d\/workflows\/\.github\/workflows\/runner\.yml@[0-9a-f]{40}$/i;
+const LOCAL_RUNNER = ".github/workflows/runner.yml";
+
+function callsRunnerPick(uses: unknown, workflows: readonly Workflow[]): boolean {
+  if (typeof uses !== "string") return false;
+  const target = uses.trim();
+  if (target.startsWith("./")) {
+    const path = target.slice(2);
+    return path === LOCAL_RUNNER && workflows.some((workflow) => workflow.path === path);
+  }
+  return SHARED_RUNNER.test(target);
+}
+
+// GitHub fills needs.<job> only for jobs the current job needs.
+export function readsRunnerPick(
+  job: Readonly<Record<string, unknown>>,
+  runsOn: unknown,
+  jobs: ReadonlyMap<string, Readonly<Record<string, unknown>>>,
+  workflows: readonly Workflow[],
+): boolean {
+  if (typeof runsOn !== "string") return false;
+  const need = NEEDS_RUNS_ON.exec(runsOn.trim())?.[1];
+  if (need === undefined) return false;
+  if (!(names(job["needs"]) ?? []).includes(need)) return false;
+  return callsRunnerPick(jobs.get(need)?.["uses"], workflows);
+}

package/src/delivery/runner-policy.ts

@@ -1,5 +1,6 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
 import { runsMutation, within, type Run } from "./mutation-job.ts";
+import { readsRunnerPick } from "./runner-pick.ts";
 import { isRecord, names, workflowJobs, workflowTitle, type Workflow } from "./workflow-references.ts";
 
 export type RunnerConfig = {
@@ -314,11 +315,20 @@ function watchedWorkflows(workflow: Workflow): readonly string[] {
   return isRecord(watched) ? (names(watched["workflows"]) ?? []) : [];
 }
 
-function runnerFault(job: Readonly<Record<string, unknown>>, runsOn: unknown, mutation: boolean, policy: RunnerPolicy, reachable: boolean): string | undefined {
+function runnerFault(
+  job: Readonly<Record<string, unknown>>,
+  runsOn: unknown,
+  mutation: boolean,
+  policy: RunnerPolicy,
+  reachable: boolean,
+  jobs: ReadonlyMap<string, Readonly<Record<string, unknown>>>,
+  workflows: readonly Workflow[],
+): string | undefined {
   if (policy.visibility === "public" && reachable) {
     const fault = publicFault(job, runsOn, policy.runners);
     if (fault !== undefined) return fault;
   }
+  if (readsRunnerPick(job, runsOn, jobs, workflows)) return undefined;
   return mutation ? mutationFault(runsOn, policy.runners.mutation, policy.visibility, reachable) : otherFault(runsOn, policy.runners, policy.visibility);
 }
 
@@ -359,14 +369,16 @@ export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workf
       }
     }
   }
-  return workflows.flatMap((workflow) =>
-    workflowJobs(workflow).flatMap(([id, job]) => {
+  return workflows.flatMap((workflow) => {
+    const entries = workflowJobs(workflow);
+    const jobs = new Map(entries);
+    return entries.flatMap(([id, job]) => {
       if (job["runs-on"] === undefined) return [];
       const mutation = jobRuns(workflow, job).some((run) => runsMutation(run, policy.scripts, (file) => policy.files?.get(file)));
-      const fault = runnerFault(job, job["runs-on"], mutation, policy, reachable.get(workflow.path) ?? forkReachable(workflow));
+      const fault = runnerFault(job, job["runs-on"], mutation, policy, reachable.get(workflow.path) ?? forkReachable(workflow), jobs, workflows);
       return fault === undefined ? [] : [{ location: workflow.path + " job " + id, fault }];
-    }),
-  );
+    });
+  });
 }
 
 export function formatRunnerReport(faults: readonly RunnerFault[]): string {

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* () {