@erclx/aitk 0.36.0 → 0.38.0

package/docs/agents.md

@@ -80,7 +80,7 @@ Full help: `aitk <command> --help`.
 | `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report entry length, depth, bullet weight, cited-path resolution, provenance, and index drift  |
+| `aitk context audit`     | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -377,20 +377,31 @@ aitk context audit
 aitk context audit --json
 aitk context audit --citations-only
 aitk context audit --folder context,diagrams
+aitk context audit --folder docs
 ```
 
-| Option             | Behavior                                                                 |
-| ------------------ | ------------------------------------------------------------------------ |
-| `--json`           | Add a machine-readable record on stdout, keeping the frame               |
-| `--folder <list>`  | Comma-separated folder names under `.claude/` (default: the three below) |
-| `--citations-only` | Run the gating citation check alone, printing nothing when it passes     |
+| Option             | Behavior                                                             |
+| ------------------ | -------------------------------------------------------------------- |
+| `--json`           | Add a machine-readable record on stdout, keeping the frame           |
+| `--folder <list>`  | Comma-separated folder names (default: the three below)              |
+| `--citations-only` | Run the gating citation check alone, printing nothing when it passes |
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
+A name passed to `--folder` resolves under `.claude/` first and at the project root second, which is what puts `docs/` and any later corpus in reach of the same engine. The root base is reached only by a name the caller passes, so the default list still resolves under `.claude/` alone and a project holding a root `wireframes/` is not audited against a standard it never adopted. The scope line prints the resolved path, so a project carrying both spellings reads which one was taken. The JSON record carries the base per folder as `folders[].base`.
+
+A run where no requested name resolves refuses, whichever list it read. Naming the absent ones narrows to `--folder`, since a project carrying one of the three default folders is the ordinary case and a name it never asked for is not a typo. The JSON record carries those names as `unresolvedFolders`.
+
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Required-section, length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
 
 ### What each check reports
 
+The required-section check reports what does not declare `## Overview` and `## Layout`, the two sections `.claude/standards/context.md` marks required. The list is held in code beside the numeric checkpoints rather than parsed out of the standard, so it fails on a defect rather than on a rewrite of the wording around it. A heading at any level counts, because a domain that split into a folder carries its overview in a sibling named `overview.md` where the section is the `#` title and an `##` beneath it would repeat the filename. Matching exactly is what keeps `## Layout catalog` from satisfying `Layout`.
+
+Which unit answers depends on the folder. Entries of the folder named under `.claude/` are one domain each, so each answers for itself and a finding names the entry. Entries of a folder a domain split into describe that one domain between them, so any sibling answers and a finding names the folder. Holding a split folder to the rule per file would report every child beside its `overview.md`, and rolling the named folder up would let one conforming entry stand in for every other domain sitting next to it.
+
+It reports rather than gates, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
+
 Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 rendered lines for an entry, roughly 40 for a run no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent averaging under 130 characters. The weight condition is what separates a scannable catalog of one-liners from a stack of paragraph-bullets, which reach the same count and read nothing alike.
 
 Both checks count rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. Measuring one checkpoint in each unit would put an entry length beside a run length that mean different things. Their exclusions still differ: the file measure counts fenced blocks and frontmatter, while the run measure skips a fence so an example cannot break the run around it. A reference-heavy entry therefore ranks by its examples, which the length legend states on every run. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. Both sections state the width on every run, since a number in rendered lines cannot be reproduced without it.
@@ -401,7 +412,7 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
 
-The provenance and bullet-weight checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
+The provenance, bullet-weight, and required-section checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
 
 Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
 
@@ -413,6 +424,8 @@ Three exclusions keep it from firing on prose about paths. Fenced blocks are ski
 
 What remains is a sentence naming a hypothetical entry to show the shape of a name, which no syntax separates from a real reference. Append `<!-- audit-ignore-citations -->` to that source line. The marker suppresses citation checking for its own line only.
 
+The pattern spells the `.claude/` prefix, so a folder resolved at the project root is measured by every other check and contributes nothing here. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/docs/operating-model.md

@@ -104,4 +104,4 @@ port-collision detail.
 
 - [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the isolation and fan-out mechanics
 - [Claude Code subagents](../wiki/claude-subagents.md) for in-session parallelism without worktrees
-- `.claude/context/claude-plugin/skills.md` for how the skills in the loop are categorized
+- `.claude/context/claude-plugin/skill-strategy.md` for how the skills in the loop are categorized

package/docs/visual-design-workflow.md

@@ -130,7 +130,7 @@ Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering
 
 - [Stitch](../wiki/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
 - [Claude Design](../wiki/claude-design.md): first-party hosted design product and handoff bundle
-- `.claude/context/claude-plugin/skills.md`: how to decide between workflow and domain-knowledge skills
+- `.claude/context/claude-plugin/skill-strategy.md`: how to decide between workflow and domain-knowledge skills
 - [Visual wireframes](../wiki/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
 - [Community skills and plugins](../wiki/community-skills.md): catalog of frontend design skills and integrations
 - [Community MCP servers](../wiki/community-mcp-servers.md): catalog of MCPs referenced across all tiers

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/context.ts

@@ -6,10 +6,13 @@ import {
   governsContent,
   LENGTH_CHECKPOINT,
   measureFolders,
+  missingSections,
   PEER_BULLET_CHECKPOINT,
   PROVENANCE_FOLDER,
   RENDER_WIDTH,
+  REQUIRED_SECTIONS,
   RUN_CHECKPOINT,
+  type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
@@ -51,12 +54,15 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report entry length, depth, bullet weight, citations, provenance, and index drift',
+      'Report required sections, entry length, depth, bullet weight, citations, provenance, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option('--folder <list>', `Comma-separated folder names under .claude/`)
+    .option(
+      '--folder <list>',
+      'Comma-separated folder names, resolved under .claude/ then the project root',
+    )
     .option('--citations-only', 'Run the gating citation check alone')
     .addHelpText(
       'after',
@@ -67,14 +73,15 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  a cited path did not resolve',
         '',
-        'Only unresolved citations set a failing exit code. Length, depth,',
-        'bullet, table, provenance, and index findings are advisory.',
+        'Only unresolved citations set a failing exit code. Section, length,',
+        'depth, bullet, table, provenance, and index findings are advisory.',
         '',
         'Examples:',
         '  aitk context audit',
         '  aitk context audit --json',
         '  aitk context audit --citations-only',
         '  aitk context audit --folder context,diagrams',
+        '  aitk context audit --folder docs',
         '',
       ].join('\n'),
     )
@@ -93,11 +100,11 @@ function parseFolders(list: string | undefined): string[] | string {
 
   if (names.length === 0) return 'Empty --folder list. Pass at least one name.'
 
-  // `..` would resolve the audited folder above `.claude/`, taking the scan
-  // and the citation pattern outside the tree the audit describes.
+  // `..` would resolve the audited folder above the project root, taking the
+  // scan and the citation pattern outside the tree the audit describes.
   const invalid = names.filter((name) => !FOLDER_NAME.test(name))
   if (invalid.length > 0) {
-    return `--folder takes folder names under .claude/, not paths: ${invalid.join(', ')}`
+    return `--folder takes folder names, not paths: ${invalid.join(', ')}`
   }
 
   return names
@@ -113,15 +120,38 @@ async function runAudit(
 
   if (typeof names === 'string') return refuse(names, gateOnly)
 
-  const folders = await resolveFolders(root, names)
+  // The root base is opt-in. A target carrying a root `wireframes/` would
+  // otherwise be audited against a standard it never adopted, on a bare run
+  // that named nothing.
+  const named = opts.folder !== undefined
+  const { folders, missing } = await resolveFolders(root, names, {
+    canResolveAtRoot: named,
+  })
   if (folders.length === 0) {
     return refuse(
-      `No audited folder found under .claude/. Looked for: ${names.join(', ')}.`,
+      `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}. Looked for: ${names.join(', ')}.`,
       gateOnly,
     )
   }
 
-  const citations = await auditCitations(root, presentNames(folders))
+  // A default folder a project does not carry is the ordinary case and stays
+  // silent. A name passed by hand that resolves nowhere is a typo, and the run
+  // measuring the names that did resolve reads as a pass against a folder it
+  // never opened.
+  const unresolved = named ? missing : []
+
+  // The gate runs one check. Letting it exit 0 against a scope it could not
+  // build reports a pass on nothing measured, which is the outcome a gate is
+  // there to prevent.
+  const cited = presentNames(folders)
+  if (gateOnly && cited.length === 0) {
+    return refuse(
+      `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
+      gateOnly,
+    )
+  }
+
+  const citations = await auditCitations(root, cited)
   if (citations.kind === 'unavailable') {
     return refuse(
       'git could not list the tree, so no citation was checked. Run inside a git repository.',
@@ -131,13 +161,15 @@ async function runAudit(
 
   const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
+  const sections = gateOnly ? [] : missingSections(root, folders, entries)
 
   if (gateOnly) {
     reportGate(citations)
   } else {
     intro('aitk context audit')
-    reportScope(folders)
-    reportCitations(citations)
+    reportScope(folders, unresolved)
+    reportCitations(citations, cited)
+    reportSections(sections, folders)
     reportLength(entries)
     reportDepth(entries)
     reportBullets(entries, folders)
@@ -153,15 +185,18 @@ async function runAudit(
         root,
         folders: folders.map((folder) => ({
           path: folder.rel,
+          base: folder.base,
           entries: folder.entries.length,
           governsContent: governsContent(folder),
         })),
+        unresolvedFolders: unresolved,
         citations: {
           scanned: citations.scanned,
           total: citations.total,
           unresolved: citations.unresolved,
         },
         entries,
+        missingSections: sections,
         indexDrift: drift,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
@@ -171,6 +206,7 @@ async function runAudit(
           peerBullet: PEER_BULLET_CHECKPOINT,
           bullet: BULLET_CHECKPOINT,
           provenanceFolder: PROVENANCE_FOLDER,
+          requiredSections: REQUIRED_SECTIONS,
         },
       })}\n`,
     )
@@ -221,18 +257,54 @@ function plural(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? '' : 's'}`
 }
 
-function reportScope(folders: readonly AuditedFolder[]): void {
+/**
+ * Names the resolved path of every audited folder, plus the requested names
+ * that resolved nowhere.
+ *
+ * The path is what says which base a name was taken from, which matters once a
+ * name can resolve under `.claude/` or at the project root and a project may
+ * carry both.
+ */
+function reportScope(
+  folders: readonly AuditedFolder[],
+  unresolved: readonly string[],
+): void {
   logStep('Scope')
 
   for (const folder of folders) {
     logInfo(`${folder.rel}: ${folder.entries.length} entries`)
   }
+
+  if (unresolved.length === 0) return
+
+  logWarn(
+    `Under neither .claude/ nor the project root: ${unresolved.join(', ')}`,
+  )
 }
 
 type ScannedCitations = Extract<CitationReport, { kind: 'scanned' }>
 
-function reportCitations(report: ScannedCitations): void {
+/**
+ * States the reach before the count, for the reason the provenance report
+ * states its own.
+ *
+ * A run auditing a folder at the project root builds no pattern, and a count of
+ * zero followed by a line saying every path resolves is indistinguishable from
+ * a corpus that cites nothing.
+ */
+function reportCitations(
+  report: ScannedCitations,
+  cited: readonly string[],
+): void {
   logStep('Citations')
+
+  if (cited.length === 0) {
+    logInfo(
+      'Out of scope. The pattern spells the .claude/ prefix, and no audited folder resolved there.',
+    )
+    return
+  }
+
   logInfo(
     `${plural(report.total, 'cited path')} across ${plural(report.scanned, 'file')}, fixtures and fenced examples excluded`,
   )
@@ -250,6 +322,49 @@ function reportCitations(report: ScannedCitations): void {
   )
 }
 
+/**
+ * Names the path each finding belongs to, which is an entry in the folder named
+ * under `.claude/` and the folder itself in a domain split across one. States
+ * the reach on every run for the reason the provenance report does.
+ *
+ * This prints ahead of the four readability measures because a missing section
+ * asks whether the entry is the right shape at all, which precedes asking
+ * whether it has grown too long.
+ */
+function reportSections(
+  missing: readonly SectionFinding[],
+  folders: readonly AuditedFolder[],
+): void {
+  logStep('Sections')
+
+  const governed = folders.filter(governsContent)
+  if (governed.length === 0) {
+    logInfo(
+      `Out of scope. The list is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+    )
+    return
+  }
+
+  logInfo(
+    `Covers .claude/${PROVENANCE_FOLDER}/ alone, whose standard requires ${REQUIRED_SECTIONS.join(' and ')}.`,
+  )
+  logInfo(
+    'A heading at any level counts. Each entry answers for itself, except in a domain split across a folder, where a sibling answers for the rest.',
+  )
+
+  if (missing.length === 0) {
+    logInfo('Every entry declares each required section.')
+    return
+  }
+
+  logWarn(`${plural(missing.length, 'path')} short a required section`)
+  pipeOutput(
+    missing
+      .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+      .join('\n'),
+  )
+}
+
 function reportLength(entries: readonly EntryReport[]): void {
   logStep('Length')
   logInfo(

package/src/context/audit.ts

@@ -50,9 +50,25 @@ export const CATALOG_ROW_CHECKPOINT = 6
 /** Share of first cells that must name an artifact for a table to qualify. */
 const CATALOG_NAMED_RATIO = 0.6
 
+/**
+ * Sections `standards/context.md` marks required, in the order it states them.
+ *
+ * The list is held here rather than read out of the standard, the way the four
+ * checkpoints above quote their numbers. A parser over the standard's prose
+ * would decide which sections are required from the wording around them, so it
+ * fails on a rewrite of that wording rather than on a defect in an entry.
+ *
+ * These names do not generalize the way a length threshold does, which is why
+ * the measure is scoped to the folder `governsContent` names. A diagram entry
+ * declares a heading per kind and a wireframe entry per screen, and neither
+ * sibling standard states a required section at all.
+ */
+export const REQUIRED_SECTIONS: readonly string[] = ['Overview', 'Layout']
+
 const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
 const FENCE = /^\s*(```|~~~)/
 const HEADING = /^#{1,6}\s/
+const HEADING_TEXT = /^#{1,6}\s+(.+?)\s*$/
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
@@ -144,6 +160,23 @@ export interface EntryReport {
   readonly provenance: readonly ProvenanceFinding[]
   /** Empty for the same reason `provenance` is, and under the same folder. */
   readonly heavyBullets: readonly BulletFinding[]
+  /**
+   * Required sections this entry declares, in the standard's order, and empty
+   * outside the folder whose standard names them. What the folder is short of
+   * is `missingSections`, since one entry answers for its siblings.
+   */
+  readonly sections: readonly string[]
+}
+
+export interface SectionFinding {
+  /**
+   * Repo-relative path of whatever owes the sections: the entry itself in the
+   * folder named under `.claude/`, and the folder in a domain split across
+   * one, since the split folder's entries answer for each other.
+   */
+  readonly rel: string
+  /** Required sections the path above does not declare, never empty. */
+  readonly missing: readonly string[]
 }
 
 interface BodyLine {
@@ -422,6 +455,38 @@ function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
     .map((each) => each.finding)
 }
 
+/**
+ * Finds which required sections the entry declares.
+ *
+ * A heading at any level counts rather than the `##` the standard writes its
+ * examples at. A domain that split into a folder puts its overview in a sibling
+ * named for it, where the section is the `#` title and an `##` beneath it would
+ * repeat the file's own name. All three split folders in this repository are
+ * that shape, so matching `##` alone would report every one of them. Nothing is
+ * titled for a required section without being about it, so the looser match
+ * costs no precision.
+ *
+ * Fenced blocks are skipped for the reason the scans above skip them. A
+ * standard quoted inside an example declares nothing about the entry quoting it.
+ */
+function declaredSections(lines: readonly BodyLine[]): string[] {
+  const found = new Set<string>()
+  let fenced = false
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const match = line.text.match(HEADING_TEXT)
+    if (match && REQUIRED_SECTIONS.includes(match[1])) found.add(match[1])
+  }
+
+  return REQUIRED_SECTIONS.filter((section) => found.has(section))
+}
+
 /**
  * Measures one entry, scanning for provenance only when a standard claims it.
  *
@@ -448,6 +513,7 @@ export function measureEntry(
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
     heavyBullets: governsContent ? heavyBullets(lines) : [],
+    sections: governsContent ? declaredSections(lines) : [],
   }
 }
 
@@ -484,3 +550,56 @@ export async function measureFolders(
 export function governsContent(folder: AuditedFolder): boolean {
   return folder.name === PROVENANCE_FOLDER
 }
+
+/**
+ * Names what does not declare the sections the standard requires.
+ *
+ * Which unit answers depends on what the folder is. A split folder's entries
+ * describe one domain between them and carry the overview and the layout in a
+ * sibling named for them, so any one of them answers and a per-file rule there
+ * would report every other child of all three shipped splits. The entries of
+ * the folder named under `.claude/` are one domain each, so each answers for
+ * itself. Rolling those up too was the first shape of this check, and it let a
+ * single sibling stand in for thirteen domains it says nothing about.
+ *
+ * The judgment sits in the caller because the split case needs the folder's
+ * other entries, which `measureFolders` holds and `measureEntry` does not. A
+ * folder with no entries of its own is a split parent holding an index and
+ * subfolders, and it has nothing to require a section of.
+ *
+ * The standard sanctions omitting `## Layout` from a domain owning no paths,
+ * which no measure can tell from an entry that forgot it. An entry of that
+ * shape therefore reports, which is a reason this is printed and never gated on.
+ */
+export function missingSections(
+  root: string,
+  folders: readonly AuditedFolder[],
+  entries: readonly EntryReport[],
+): SectionFinding[] {
+  const byRel = new Map(entries.map((entry) => [entry.rel, entry]))
+  const findings: SectionFinding[] = []
+
+  const shortOf = (declared: readonly string[]): string[] =>
+    REQUIRED_SECTIONS.filter((name) => !declared.includes(name))
+
+  for (const folder of folders) {
+    if (!governsContent(folder) || folder.entries.length === 0) continue
+
+    const reports = folder.entries
+      .map((path) => byRel.get(relative(root, path)))
+      .filter((entry) => entry !== undefined)
+
+    if (folder.nested) {
+      const missing = shortOf(reports.flatMap((entry) => entry.sections))
+      if (missing.length > 0) findings.push({ rel: folder.rel, missing })
+      continue
+    }
+
+    for (const entry of reports) {
+      const missing = shortOf(entry.sections)
+      if (missing.length > 0) findings.push({ rel: entry.rel, missing })
+    }
+  }
+
+  return findings
+}