@erclx/canon 5.37.0 → 5.39.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.37.0",
+  "version": "5.39.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -24,9 +24,10 @@
     "access": "public"
   },
   "scripts": {
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
+    "format": "oxfmt . && prettier --write --log-level warn 'web/**/*.astro' && shfmt --write --indent 2 scripts/ tooling/ claude/",
+    "check:format": "oxfmt --check . && prettier --check --log-level warn 'web/**/*.astro' && shfmt --diff --indent 2 scripts/ tooling/ claude/",
     "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
+    "check:lint": "oxlint --disable-nested-config --max-warnings 0",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",
@@ -72,6 +73,8 @@
     "happy-dom": "^20.14.5",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.7.2",

package/scripts/core/install-check.sh

@@ -101,7 +101,7 @@ log_step "Assert scaffold"
 # skills rather than installing into a target. The two
 # rule paths stand for the `claude` and `canon` groups `base` takes whole.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" \
-  ".prettierrc" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.ts" \
+  ".oxfmtrc.json" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.ts" \
   ".claude/rules/canon/claude/output.md" ".claude/rules/canon/canon/scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"

package/src/commands/claude.ts

@@ -70,7 +70,6 @@ import {
   writeSettings,
 } from '@/claude/settings'
 import { copyPreservingMode } from '@/sync/copy'
-import { execScript } from '@/cli/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { recordDir } from '@/roots/record'
 import { SURFACE_ENTRIES, surfaceDir } from '@/roots/surface'
@@ -321,7 +320,7 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Reports rather than gates. Whether a bullet belongs in a rule is the',
-        'judgment canon/context/context-model/overview.md states, and naming a path is evidence for it',
+        'judgment canon/context/context-model.md states, and naming a path is evidence for it',
         'rather than the answer.',
         '',
         'Examples:',

package/src/commands/context.ts

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
   type ContextAuditRefusal,
@@ -12,14 +12,22 @@ import {
   matchesSiblings,
   measureFolders,
   extraSections,
+  GOTCHA_CAP,
+  LAYOUT_BULLET_CAP,
+  LAYOUT_PARAGRAPH_CAP,
   missingSections,
+  OTHER_FOLDERS,
   PROVENANCE_FOLDER,
   ALLOWED_SECTIONS_BY_FOLDER,
   REQUIRED_SECTIONS,
   REQUIRED_SECTIONS_BY_FOLDER,
   requiredSections,
+  RETIRED_SECTIONS_BY_FOLDER,
+  shapeFindings,
   type ExtraSectionFinding,
   type SectionFinding,
+  type ShapeFinding,
+  type ShapeIssue,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
@@ -49,6 +57,8 @@ import {
   resolveFolders,
 } from '@/context/folders'
 import { isGating } from '@/context/gate'
+import { isShapeGated, SHAPE_GATED_FOLDERS } from '@/context/shape-gated'
+import { currentWorktreeRoot } from '@/git/worktree'
 import {
   isOverWordCap,
   measureRequirements,
@@ -103,7 +113,7 @@ export function register(program: Command): void {
     .option('--citations-only', 'Run the gating citation check alone')
     .option(
       '--gate',
-      'Also fail on a missing required section or index drift, the findings that are facts',
+      'Also fail on a missing required section, an H2 outside the set, a shape break in a gated folder, or index drift, the findings that are facts',
     )
     .addHelpText(
       'after',
@@ -118,10 +128,13 @@ export function register(program: Command): void {
         'stating a word cap gates past it, on any run except',
         '--citations-only, which never measures it. A record stating no',
         'cap is reported and never gated. --gate widens the gate to the',
-        'other two findings that are facts rather than judgments: a',
-        'missing required section and index drift. A context entry',
-        'requires Overview and Layout. Entry length, reference form,',
-        'table, and provenance are judgments under both.',
+        'findings that are facts rather than judgments: a missing',
+        'required section, an H2 outside the closed set, and index drift.',
+        'A context entry requires Overview and Layout and allows Gotchas.',
+        'A shape break, such as a Decisions section or a sixth gotcha, is',
+        'reported everywhere and gated only under a shape-gated folder.',
+        'Entry length, reference form, table, and provenance are',
+        'judgments under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `canon markdown audit` measures them.',
@@ -644,6 +657,15 @@ async function runAudit(
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
   const extras = gateOnly ? [] : extraSections(entries)
+  // The gated prefixes name paths from the repository root, while an entry's
+  // path runs from the audit root, which is a seed tree's own root when one is
+  // passed. Resolving here keeps a seed tree listed under its toolkit path.
+  const top = gateOnly ? root : await currentWorktreeRoot(root)
+  const shape = gateOnly
+    ? []
+    : shapeFindings(entries, (rel) =>
+        isShapeGated(relative(top, join(root, rel))),
+      )
   const length = gateOnly ? undefined : lengthFindings(entries)
   // Absent under `--citations-only` and null when the project carries no
   // record. A run that never looked and a project with nothing to look at are
@@ -658,6 +680,7 @@ async function runAudit(
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
     reportSections(sections, extras, folders)
+    reportShape(shape)
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
@@ -696,6 +719,7 @@ async function runAudit(
         length,
         missingSections: sections,
         extraSections: extras,
+        shapeFindings: shape,
         indexDrift: drift,
         // Null says the run opened the project and found no record, which a
         // target that never wrote one is entitled to. Absent says the run
@@ -711,6 +735,11 @@ async function runAudit(
           // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
           allowedSectionsByFolder: ALLOWED_SECTIONS_BY_FOLDER,
+          retiredSectionsByFolder: RETIRED_SECTIONS_BY_FOLDER,
+          gotchaCap: GOTCHA_CAP,
+          layoutBulletCap: LAYOUT_BULLET_CAP,
+          layoutParagraphCap: LAYOUT_PARAGRAPH_CAP,
+          shapeGatedFolders: SHAPE_GATED_FOLDERS,
         },
       })}\n`,
     )
@@ -722,6 +751,7 @@ async function runAudit(
       requirements !== undefined && isOverWordCap(requirements),
     sections,
     extraSections: extras,
+    shape,
     drift,
     widened,
   })
@@ -958,7 +988,7 @@ function reportSections(
   logInfo(
     `The set is closed: ${Object.entries(ALLOWED_SECTIONS_BY_FOLDER)
       .map(([name, set]) => `canon/${name}/ allows ${set.join(', ')}`)
-      .join('. ')} as H2. Any other topic is an H3 under one of them.`,
+      .join('. ')} as H2. A folder is an H3 under Layout.`,
   )
 
   if (extras.length === 0) {
@@ -974,6 +1004,75 @@ function reportSections(
   )
 }
 
+/** Characters of a paragraph the report quotes, enough to find it by. */
+const QUOTE_WIDTH = 60
+
+function clip(text: string): string {
+  return text.length > QUOTE_WIDTH ? `${text.slice(0, QUOTE_WIDTH)}...` : text
+}
+
+/** How each shape break reads in the report. */
+function readIssue(issue: ShapeIssue): string {
+  switch (issue.kind) {
+    case 'retired-section':
+      return `retired section: ${issue.text}`
+    case 'gotcha-count':
+      return `${issue.count ?? 0} gotchas, past ${GOTCHA_CAP}`
+    case 'gotcha-heading':
+      return `heading inside Gotchas: ${issue.text}`
+    case 'gotcha-paragraph':
+      return `paragraph inside Gotchas: ${clip(issue.text)}`
+    case 'layout-heading':
+      return `Layout H3 titled neither a path nor ${OTHER_FOLDERS}: ${issue.text}`
+    case 'layout-bullets':
+      return `${issue.count ?? 0} bullets under ${issue.text}, past ${LAYOUT_BULLET_CAP}`
+    case 'layout-paragraphs':
+      return `${issue.count ?? 0} paragraphs under ${issue.text}, past ${LAYOUT_PARAGRAPH_CAP}`
+    case 'layout-depth':
+      return `heading below H3 under Layout: ${issue.text}`
+  }
+}
+
+/**
+ * Names each entry breaking the section shape, gated ones first, and states
+ * which prefixes gate on every run, since an empty gated list and a corpus that
+ * conforms would otherwise print the same report.
+ */
+function reportShape(shape: readonly ShapeFinding[]): void {
+  logStep('Shape')
+
+  logInfo(
+    SHAPE_GATED_FOLDERS.length === 0
+      ? 'No folder is shape-gated yet, so every shape break reports and none gates.'
+      : `Gated under --gate: ${SHAPE_GATED_FOLDERS.join(', ')}. A break elsewhere reports and never gates.`,
+  )
+
+  if (shape.length === 0) {
+    logInfo('Every entry holds the section shape.')
+    return
+  }
+
+  const gated = shape.filter((finding) => finding.gated)
+  if (gated.length > 0) {
+    logWarn(
+      `${gated.length} gated ${gated.length === 1 ? 'entry' : 'entries'} breaking the shape`,
+    )
+  }
+  logInfo(
+    `${shape.length} ${shape.length === 1 ? 'entry' : 'entries'} breaking the shape in all`,
+  )
+  pipeOutput(
+    [...gated, ...shape.filter((finding) => !finding.gated)]
+      .map(
+        (finding) =>
+          `${finding.rel}${finding.gated ? '  gated' : ''}\n${finding.issues
+            .map((issue) => `  :${issue.line}  ${readIssue(issue)}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 /** How each question reads in the report, in the standard's own order. */
 const QUESTION_LABEL: Record<LengthQuestion, string> = {
   domain: 'one domain',

package/src/commands/hooks.ts

@@ -1,4 +1,6 @@
 import type { Command } from 'commander'
+import { existsSync, readFileSync } from 'node:fs'
+import { findMissingReplyLinks, formatMissing } from '@/hooks/reply-links'
 import {
   readMergedSubjects,
   runCanon,
@@ -11,6 +13,11 @@ interface PostMergeOptions {
   readonly root?: string
 }
 
+interface ReplyLinksOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const hooks = program
     .command('hooks')
@@ -64,4 +71,60 @@ export function register(program: Command): void {
       })
       process.exitCode = 0
     })
+
+  hooks
+    .command('reply-links')
+    .description(
+      'Check that every markdown link in a reply on stdin names a file on disk',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--root <path>',
+      'Root a relative link resolves against, default the main worktree root',
+    )
+    .option('--json', 'Write the findings as a record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads the reply from stdin and resolves each link target on disk.',
+        'Placeholders, globs, URLs, anchors, and links inside code are skipped.',
+        'A :42 or #L42 tail is stripped before the check.',
+        '',
+        'Missing paths go to stderr, and --json adds a record on stdout.',
+        '',
+        'Exit codes:',
+        '  0  every link resolves, or the reply holds none',
+        '  1  at least one link names nothing on disk, or stdin is a terminal',
+        '',
+        'Examples:',
+        '  printf "%s" "$reply" | canon hooks reply-links',
+        '  canon hooks reply-links --json < reply.md',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ReplyLinksOptions) => {
+      if (process.stdin.isTTY) {
+        process.stderr.write('Pipe the reply on stdin.\n')
+        process.exitCode = 1
+        return
+      }
+
+      const found = findMissingReplyLinks(
+        readFileSync(0, 'utf8'),
+        opts.root ?? (await mainWorktreeRoot()),
+        existsSync,
+      )
+      if (opts.json) {
+        process.stdout.write(
+          `${JSON.stringify({
+            message: found.length > 0 ? formatMissing(found) : undefined,
+            missing: found,
+            ok: found.length === 0,
+          })}\n`,
+        )
+      }
+      if (found.length > 0) process.stderr.write(`${formatMissing(found)}\n`)
+      process.exitCode = found.length > 0 ? 1 : 0
+    })
 }

package/src/commands/markdown.ts

@@ -6,19 +6,30 @@ import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { isChangelog, lengthExemption } from '@/markdown/ceiling'
 import { type ColonFinding, findColons } from '@/markdown/colons'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
-import { isGating } from '@/markdown/gate'
+import { densityFindings, type DensityKind } from '@/markdown/density'
+import {
+  type GatedDensityFinding,
+  type GatedReferenceShapeFinding,
+  isGating,
+  referenceShapeGates,
+} from '@/markdown/gate'
 import {
   findHeadingCase,
   type HeadingCaseFinding,
 } from '@/markdown/heading-case'
 import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
+import {
+  REFERENCE_SECTIONS,
+  type ReferenceShapeKind,
+  referenceShapeFindings,
+} from '@/markdown/reference-shape'
 import {
   type BanFinding,
   type BanSets,
   bodyLines,
   scanBans,
 } from '@/markdown/scan'
-import { bulletStacks, CAP, type StackFinding } from '@/markdown/stacks'
+import { densityGates, GATED_PATHS, inDensityScope } from '@/markdown/scope'
 import {
   BASELINE,
   CHECKPOINTS,
@@ -36,6 +47,7 @@ import {
   pipeOutput,
   plural,
 } from '@/cli/ui'
+import { isOwnCheckout } from '@/roots/project'
 
 const EXIT_REFUSED = 1
 const EXIT_GATE = 2
@@ -60,7 +72,10 @@ interface FileReport {
   readonly links: readonly LinkFinding[]
   readonly colons: readonly ColonFinding[]
   readonly headingCase: readonly HeadingCaseFinding[]
-  readonly bulletStacks: readonly StackFinding[]
+  /** Empty on a path outside the density scope, so a plan never carries one. */
+  readonly density: readonly GatedDensityFinding[]
+  /** Empty on a page whose frontmatter does not carry `kind: reference`. */
+  readonly referenceShape: readonly GatedReferenceShapeFinding[]
   readonly structure: StructureReport
   readonly renderedLines: number
   /** The stated reason, or null where the document is not exempt. */
@@ -76,7 +91,7 @@ export function register(program: Command): void {
   markdown
     .command('audit')
     .description(
-      'Fail on a banned character, and report bullet, paragraph, cadence, depth, and length',
+      'Fail on a banned character, a dead link, or a gated density finding, and report weight, cadence, depth, and length',
     )
     .argument(
       '[path...]',
@@ -91,22 +106,33 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
-        '  2  a banned character is present, or a relative link resolves',
-        '     to nothing on disk',
+        '  2  a banned character is present, a relative link resolves to',
+        '     nothing on disk, or a density or reference shape finding sits',
+        '     on a gated path',
         '  3  a shipped ban set is empty, so the run measured nothing',
         '',
         'A ban hit and a dead link are each a fact and gate unconditionally.',
-        'Bullet, paragraph, and depth weight are judgments a reader settles,',
-        'so all three report and none of them fails a run.',
+        'Depth weight is a judgment a reader settles, so it reports and never',
+        'fails a run.',
+        '',
+        'Density holds six limits: a 350-character paragraph, 2 paragraphs in',
+        'a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a',
+        'paragraph or table opening every H3. Only context, docs, skills, tooling',
+        'seeds and references, the wiki, README.md, and CONTRIBUTING.md take a',
+        'finding. One gates under a prefix in GATED_PATHS in src/markdown/scope.ts,',
+        'and a bullet run gates in context, docs, and skills from the start.',
+        'Outside a canon checkout every density finding reports and none gates.',
+        '',
+        'A page whose frontmatter carries kind: reference takes the reference',
+        'shape: no H2 beyond Output, Refusals, and See also, each at most once',
+        'and in that order, no H3, and no table whose first header cell names',
+        'flags or options. It gates under the same prefixes density does, and',
+        'an unmarked page is never measured.',
         '',
         'A mid-sentence colon and a heading with a capital after its first word',
         'report the same way. A proper noun is the one case the second cannot',
         'tell from title case, and the first is sometimes right.',
         '',
-        'Bullet stacks report a run of more than 5 plain bullets under one',
-        'heading and never exit 2. The Bullet stacks gate stage owns that',
-        'verdict, for the reason the length line below states.',
-        '',
         'Length reports a whole document past the ceiling and never exits 2.',
         'The Document ceiling gate stage owns that verdict, since this audit also',
         'runs on a record kept out of version control, where a long plan is not',
@@ -131,7 +157,7 @@ export function register(program: Command): void {
         '  canon markdown audit',
         '  canon markdown audit --json',
         '  canon markdown audit .claude/rules governance',
-        '  canon markdown audit docs/agents/commands.md',
+        '  canon markdown audit docs/agents/install-and-sync.md',
         "  canon markdown audit 'standards/**/*.md'",
         '',
       ].join('\n'),
@@ -171,6 +197,9 @@ async function runAudit(
   const bans = BAN_SETS
   const empty = emptyBanSets(bans)
   const checkpoints = CHECKPOINTS
+  // `GATED_PATHS` describes this repository's rewrite progress, so a target
+  // reads every density finding as a report until its own corpus is gated.
+  const gates = isOwnCheckout(root)
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
@@ -184,7 +213,16 @@ async function runAudit(
         bans: scanBans(lines, bans),
         colons: advisory ? findColons(lines) : [],
         headingCase: advisory ? findHeadingCase(source) : [],
-        bulletStacks: advisory ? bulletStacks(lines) : [],
+        density: inDensityScope(rel)
+          ? densityFindings(lines).map((finding) => ({
+              ...finding,
+              gating: gates && densityGates(rel, finding.kind),
+            }))
+          : [],
+        referenceShape: referenceShapeFindings(source).map((finding) => ({
+          ...finding,
+          gating: gates && referenceShapeGates(rel),
+        })),
         links: findBrokenLinks(lines, (path) =>
           existsSync(resolve(dirname(abs), path)),
         ),
@@ -201,7 +239,8 @@ async function runAudit(
   reportLinks(reports, root)
   reportColons(reports)
   reportHeadingCase(reports)
-  reportStacks(reports)
+  reportDensity(reports, gates)
+  reportReferenceShape(reports, gates)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -237,7 +276,8 @@ async function runAudit(
           links: report.links,
           colons: report.colons,
           headingCase: report.headingCase,
-          bulletStacks: report.bulletStacks,
+          density: report.density,
+          referenceShape: report.referenceShape,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -260,7 +300,8 @@ async function runAudit(
     structure: reports.map((report) => report.structure),
     colons: reports.flatMap((report) => report.colons),
     headingCase: reports.flatMap((report) => report.headingCase),
-    bulletStacks: reports.flatMap((report) => report.bulletStacks),
+    density: reports.flatMap((report) => report.density),
+    referenceShape: reports.flatMap((report) => report.referenceShape),
   })
 
   return gating ? EXIT_GATE : 0
@@ -414,46 +455,142 @@ function reportLinks(reports: readonly FileReport[], root: string): void {
   )
 }
 
-function reportStacks(reports: readonly FileReport[]): void {
-  logStep('Bullet stacks')
+const DENSITY_LABELS: Record<DensityKind, string> = {
+  'paragraph-length': 'paragraph length',
+  'paragraph-run': 'paragraphs in a row',
+  'bullet-length': 'bullet length',
+  'bullet-run': 'bullets in a row',
+  'heading-depth': 'heading depth',
+  'h3-opening': 'H3 opening',
+}
+
+function describeDensity(finding: GatedDensityFinding): string {
+  const measured =
+    finding.kind === 'h3-opening'
+      ? 'opens with neither a paragraph nor a table'
+      : finding.kind === 'heading-depth'
+        ? `H${finding.value} past H${finding.limit}`
+        : `${finding.value} past ${finding.limit}`
+  const gate = finding.gating ? '  gating' : ''
+  return `  :${finding.line}  ${DENSITY_LABELS[finding.kind]}  ${measured}${gate}`
+}
+
+/**
+ * Lists every density finding with whether it gates, since an in-scope path
+ * under no gated prefix reports the same finding a gated one fails on and a
+ * reader has to tell the two apart in one frame.
+ */
+function reportDensity(reports: readonly FileReport[], gates: boolean): void {
+  logStep('Density')
+  logInfo(
+    `Paragraphs past ${CHECKPOINTS.paragraph} characters, more than 2 paragraphs in a row, bullets past ${CHECKPOINTS.bullet} characters, more than 5 plain bullets in a row, a heading past H3, and an H3 opening with neither a paragraph nor a table.`,
+  )
   logInfo(
-    `A run of more than ${CAP} top-level bullets, with no paragraph or heading between them.`,
+    'Measured on context entries, docs, skill bodies and references, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. Every other path takes no density finding.',
   )
   logInfo(
-    'A run whose every item opens with a bold label or a link is exempt. This never fails a run. The Bullet stacks gate stage owns that verdict.',
+    gates
+      ? `A finding gates under a gated prefix (${GATED_PATHS.length === 0 ? 'none yet' : GATED_PATHS.join(', ')}), and a bullet run gates in context, docs, and skills already. Every other finding reports.`
+      : 'This tree is not a canon checkout, so every density finding reports and none gates.',
   )
 
   const carrying = reports
-    .filter((report) => report.bulletStacks.length > 0)
-    .sort((a, b) => longestStack(b) - longestStack(a))
+    .filter((report) => report.density.length > 0)
+    .sort((a, b) => b.density.length - a.density.length)
 
   if (carrying.length === 0) {
-    logInfo(`No run past ${CAP} bullets.`)
+    logInfo('No density finding.')
     return
   }
 
-  const total = carrying.reduce(
-    (sum, report) => sum + report.bulletStacks.length,
+  const total = carrying.reduce((sum, report) => sum + report.density.length, 0)
+  const gating = carrying.reduce(
+    (sum, report) =>
+      sum + report.density.filter((finding) => finding.gating).length,
     0,
   )
-  logWarn(`${plural(total, 'stack')} across ${plural(carrying.length, 'file')}`)
+  logWarn(
+    `${plural(total, 'finding')} across ${plural(carrying.length, 'file')}, ${gating} gating`,
+  )
+  if (gating > 0) logWarn('A gating finding fails the run.')
   logInfo(
-    'Fold the run into prose, give each item an H3, or split the list at its seam.',
+    'Split a long block at its seam, put a heading or a table between paragraphs, give a long list H3s, and open each H3 with a sentence or a table.',
   )
   pipeOutput(
     carrying
       .map(
         (report) =>
-          `${report.rel}  ${plural(report.bulletStacks.length, 'stack')}\n${report.bulletStacks
-            .map((found) => `  :${found.line}  ${found.count} bullets`)
+          `${report.rel}  ${plural(report.density.length, 'finding')}\n${report.density
+            .map(describeDensity)
             .join('\n')}`,
       )
       .join('\n'),
   )
 }
 
-function longestStack(report: FileReport): number {
-  return Math.max(0, ...report.bulletStacks.map((found) => found.count))
+const REFERENCE_SHAPE_LABELS: Record<ReferenceShapeKind, string> = {
+  'extra-section': 'section outside the shape',
+  'section-order': 'section out of order or repeated',
+  subsection: 'H3',
+  'flag-table': 'flag table',
+}
+
+function describeReferenceShape(finding: GatedReferenceShapeFinding): string {
+  const gate = finding.gating ? '  gating' : ''
+  return `  :${finding.line}  ${REFERENCE_SHAPE_LABELS[finding.kind]}  ${finding.text}${gate}`
+}
+
+/**
+ * Lists every reference shape finding with whether it gates, under the same
+ * prefixes the density step names.
+ */
+function reportReferenceShape(
+  reports: readonly FileReport[],
+  gates: boolean,
+): void {
+  logStep('Reference shape')
+  logInfo(
+    `A page whose frontmatter carries kind: reference holds its opening, then ${REFERENCE_SECTIONS.join(', ')}, each at most once and in that order, with no H3 and no table of flags. An unmarked page is never measured.`,
+  )
+  logInfo(
+    gates
+      ? 'A finding gates under the prefixes the density step names. Every other finding reports.'
+      : 'This tree is not a canon checkout, so every reference shape finding reports and none gates.',
+  )
+
+  const carrying = reports.filter((report) => report.referenceShape.length > 0)
+
+  if (carrying.length === 0) {
+    logInfo('No reference shape finding.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, report) => sum + report.referenceShape.length,
+    0,
+  )
+  const gating = carrying.reduce(
+    (sum, report) =>
+      sum + report.referenceShape.filter((finding) => finding.gating).length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'finding')} across ${plural(carrying.length, 'file')}, ${gating} gating`,
+  )
+  if (gating > 0) logWarn('A gating finding fails the run.')
+  logInfo(
+    "Fold an H3 into its section, move a section the shape lacks into the opening or a linked page, and point at the command's own --help for flags.",
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.referenceShape.length, 'finding')}\n${report.referenceShape
+            .map(describeReferenceShape)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
 }
 
 function reportColons(reports: readonly FileReport[]): void {

package/src/commands/pr.ts

@@ -1891,7 +1891,7 @@ async function mapPool<T, R>(
   limit: number,
   task: (input: T) => Promise<R>,
 ): Promise<R[]> {
-  const results: R[] = new Array(inputs.length)
+  const results: R[] = Array.from({ length: inputs.length })
   let next = 0
   const lane = async (): Promise<void> => {
     while (next < inputs.length) {