@erclx/canon 5.38.0 → 5.40.0

package/src/commands/gov.ts

@@ -84,6 +84,7 @@ const CANON_RULES_REL = join('.claude', 'rules', 'canon')
 
 interface InstallOptions {
   readonly add?: string
+  readonly yes?: boolean
 }
 
 interface RegenOptions {
@@ -147,6 +148,7 @@ export function register(program: Command): void {
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--add <rules>', 'Comma-separated rules to layer on the stack')
+    .option('--yes', 'Answer the install confirm without a prompt')
     .addHelpText(
       'after',
       [
@@ -156,6 +158,7 @@ export function register(program: Command): void {
         '  canon gov install node ../my-app',
         '  canon gov install node --add astro,shadcn ../my-app',
         '  canon gov install --add tasks,plan ../my-app',
+        '  canon gov install node --yes ../my-app',
         '',
         'With --add and no stack, the named rules install alone. A first',
         'positional naming a stack is read as the stack, so pass . or a path',
@@ -164,6 +167,10 @@ export function register(program: Command): void {
         'Copies each rule into .claude/rules/canon/, replacing a copy already',
         'there. Rules under .claude/rules/project/ are never read.',
         '',
+        'The install confirm needs a TTY. --yes answers it, so a headless call',
+        'installs without setting CANON_NON_INTERACTIVE=1. It does not pick a',
+        'stack, so a headless call still names one.',
+        '',
         'Exit codes:',
         '  0  installed, the stack held no rules, or the prompt was cancelled',
         '  1  refused: no stack named headlessly, an unknown stack, no --add',
@@ -349,6 +356,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one stated figure disagrees with the tree',
         '',
+        'Reasons:',
+        '  no-git       git could not list the tree',
+        '  no-markdown  the tree holds no markdown file',
+        '',
         'It reports and never gates. The false-positive rate is read off the',
         'first run rather than assumed, and a push failing on a stated figure',
         'that reads correctly to a person would teach a contributor to route',
@@ -415,6 +426,9 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one declaration asserts either',
         '',
+        'Refuses an empty superseded value, a superseded value equal to its',
+        'replacement, and a tree git cannot list. An empty replacement is allowed.',
+        '',
         'Examples:',
         '  canon gov superseded feature-feat- feature-',
         '  canon gov superseded feature-feat- feature- --json',
@@ -496,6 +510,9 @@ export function register(program: Command): void {
         '  2  at least one cited path resolves to nothing, or one glob matches',
         '     nothing in this tree',
         '',
+        'Refuses a tree holding neither rule corpus, and a `git check-ignore`',
+        'read that fails.',
+        '',
         'Examples:',
         '  canon gov citations',
         '  canon gov citations --json',
@@ -543,6 +560,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one instruction is restated outside a declared mirror',
         '',
+        'Reasons:',
+        '  no-instructions  the tree holds no always-loaded file or seed to read',
+        '  no-surfaces      the tree holds no skills tree or rules tree to match against',
+        '',
         'Examples:',
         '  canon gov restated',
         '  canon gov restated --json',
@@ -1268,8 +1289,9 @@ async function runInstall(
   intro('canon gov install')
 
   const add = opts.add ?? ''
+  const yes = opts.yes === true
   if (add !== '' && isAddWithoutStack(stack, target)) {
-    return installExtras(add, stack ?? target)
+    return installExtras(add, stack ?? target, yes)
   }
 
   const resolved = resolveTarget(target, PROJECT_ROOT)
@@ -1314,14 +1336,7 @@ async function runInstall(
   for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
   for (const source of found) logInfo(source.rule)
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')
@@ -1347,6 +1362,28 @@ async function runInstall(
   return 0
 }
 
+/**
+ * The install confirm. `--yes` answers it without a prompt, so the line it
+ * would have printed is skipped rather than duplicated under
+ * `CANON_NON_INTERACTIVE=1`.
+ */
+async function confirmInstall(
+  count: number,
+  target: string,
+  yes: boolean,
+): Promise<boolean> {
+  if (yes) return true
+  return select({
+    message: `Install ${count} rules to ${displayPath(target, CANON_RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+    ttyHint: 'Pass --yes',
+  })
+}
+
 /**
  * Whether `--add` runs with no stack under it. Commander fills the first
  * positional before the second, so `--add a,b ../my-app` arrives with the
@@ -1366,7 +1403,11 @@ function isAddWithoutStack(stack: string | undefined, target: string): boolean {
  * extras are not a stack, and overwriting the chain would cost a target the
  * missing-rule report its stack install recorded.
  */
-async function installExtras(add: string, target: string): Promise<number> {
+async function installExtras(
+  add: string,
+  target: string,
+  yes: boolean,
+): Promise<number> {
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
@@ -1382,14 +1423,7 @@ async function installExtras(add: string, target: string): Promise<number> {
     return 1
   }
 
-  const shouldInstall = await select({
-    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
-    options: [
-      { value: true, label: 'Yes' },
-      { value: false, label: 'No' },
-    ],
-    nonInteractiveDefault: true,
-  })
+  const shouldInstall = await confirmInstall(found.length, target, yes)
 
   if (!shouldInstall) {
     logWarn('Cancelled')

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/intake.ts

@@ -64,6 +64,12 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
         '',
         'Exit codes:',
         '  0  the folders or items were listed',
@@ -105,6 +111,17 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake       the project holds no intake folder',
+        '  no-folder       no folder matches the slug',
+        '  ambiguous-slug  a bare slug matches more than one ordinal-prefixed',
+        '                  folder, all named in `detail`',
+        '  no-cluster      the cluster file named does not exist',
+        '  no-item         the item number named does not exist in the cluster',
+        '  answered        the item already carries an answer',
+        '  bad-input       a malformed command line, such as no selection, an empty',
+        '                  answer, or two answers for one item',
         '',
         'Exit codes:',
         '  0  every named item now carries its answer',

package/src/commands/labels.ts

@@ -111,6 +111,10 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one changed path is reached by no row',
         '',
+        'Reasons:',
+        '  no-map  the project declares no label map, so it labels nothing. An',
+        '          expected absence for `canon audits run`, not a fault',
+        '',
         'Examples:',
         '  canon labels audit',
         '  canon labels audit --json',
@@ -130,7 +134,10 @@ export function register(program: Command): void {
     )
     .argument('<number>', "This branch's open pull request")
     .helpOption('-h, --help', 'Show this help message')
-    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option(
+      '--base <ref>',
+      "Read the git range back to this ref instead of the pull request's files",
+    )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
     .option('--check', 'Report the labels owed and write nothing')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -138,9 +145,10 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Resolves the earned set the way `canon labels audit` does, binds to the',
-        'pull request only when its head is the current branch and it is open,',
-        'and adds each earned label the pull request lacks over REST.',
+        "Resolves the earned set from the pull request's own files listing, or",
+        'from the git range when --base is passed, binds to the pull request only',
+        'when its head is the current branch and it is open, and adds each earned',
+        'label the pull request lacks over REST.',
         '',
         'It adds and never removes, so a label a person applied by hand stays.',
         'A label the remote does not carry is reported under missingOnRemote and',
@@ -155,6 +163,12 @@ export function register(program: Command): void {
         '  2  labels are still owed, being any under --check, or a label the',
         '     remote lacks or a failed add otherwise',
         '',
+        'Reasons:',
+        '  head-mismatch  the pull request is not open on the current branch, under',
+        '                 --check as well',
+        '  gh-failed      the files listing or the labels could not be read, and the',
+        '                 run does not fall back to git',
+        '',
         'Examples:',
         '  canon labels apply 123 --json',
         '  canon labels apply 123 --check',
@@ -396,7 +410,26 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   if (target === null) return refuse('gh-failed')
   if (target.trim() !== `${head} open`) return refuse('head-mismatch')
 
-  const report = await auditLabels(root, { base: opts.base })
+  // An explicit --base is an explicit request for the git route. Otherwise the
+  // pull request's own file listing is the diff the labels describe, and a
+  // failed read refuses rather than falling back, since binding needed gh too.
+  let paths: string[] | undefined
+  if (opts.base === undefined) {
+    const listing = await gh(root, [
+      'api',
+      '--paginate',
+      `repos/{owner}/{repo}/pulls/${number}/files`,
+      '--jq',
+      '.[].filename',
+    ])
+    if (listing === null) return refuse('gh-failed')
+    paths = nonEmptyLines(listing)
+  }
+
+  const report = await auditLabels(root, {
+    base: opts.base,
+    ...(paths !== undefined && { paths }),
+  })
 
   // A project declaring no map earns nothing and is labelled silently, which
   // is an answer and exits clean rather than reading as a break.

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 {