@erclx/aitk 0.20.0 → 0.21.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -80,6 +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, cited-path resolution, and index drift in the context folders      |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -98,6 +99,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `slides`    | `render`, `list`                                                       |
 | `tasks`     | `archive`                                                              |
 | `comments`  | `scan`                                                                 |
+| `context`   | `audit`                                                                |
 
 Common patterns:
 
@@ -351,6 +353,43 @@ The degradation sweep reads its vocabulary from whichever rule publishes a `## D
 
 `090-code-comments` is the rule that publishes the list, and it ships on the `base` stack. A project that installs or syncs governance for the first time after that rule landed gets a sweep that previously reported skipped, so hits appear where the command used to stay quiet. Edit the backticked terms in the installed copy to change what that project sweeps for. The sweep matches comment text, so a comment naming a term as an example is a hit, and a hit is a prompt to read the line rather than a verdict on it.
 
+## Context audit
+
+`aitk context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter. It reads and reports. Fixing what it finds is separate work.
+
+```bash
+aitk context audit
+aitk context audit --json
+aitk context audit --citations-only
+aitk context audit --folder context,diagrams
+```
+
+| 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     |
+
+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, table, and index findings print and return `0`, because each is a judgment threshold and failing a push on one would make the check something to route around.
+
+### What each check reports
+
+Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 lines for an entry, roughly 40 for a run of lines 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. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. The report states the convention on every run.
+
+The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
+
+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.
+
+### The citation gate
+
+The citation check resolves every path into an audited folder that appears anywhere in the repository, and it is the half wired into `bun run check`. A stale reference has a silent failure mode: the session opens nothing and carries on.
+
+Three exclusions keep it from firing on prose about paths. Fenced blocks are skipped in markdown, which covers a standard displaying a path as an example. Fixture and harness trees are skipped by location, covering sandbox scenarios that describe their own scratch tree, the eval harness naming its target project, and `*.test.ts`. A path into a folder the project does not carry is skipped, so a skill directing a reader to `.claude/wireframes/index.md` stays valid in a project that has wireframes and silent in one that does not.
+
+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.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/package.json

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

package/scripts/core/verify.sh

@@ -148,6 +148,15 @@ main() {
   run_check "bash $PROJECT_ROOT/scripts/core/check-plugin-boundary.sh" "Plugin ships toolkit-internal content."
   log_info "Plugin boundary clean"
 
+  # Only the citation half of the audit gates. Length, depth, table, and index
+  # findings are judgment thresholds, and failing a push on one would make the
+  # stage something to route around. `bun src/cli.ts` rather than `aitk`, since a
+  # globally installed binary resolves to the main checkout no matter which
+  # worktree is running.
+  log_step "Context citations"
+  run_check "cd $PROJECT_ROOT && bun src/cli.ts context audit --citations-only" "A cited context path does not resolve. Run bun src/cli.ts context audit."
+  log_info "Context citations resolve"
+
   log_step "Plugin manifests"
   if ! command -v claude >/dev/null 2>&1; then
     log_info "Skipped, claude is not installed"

package/scripts/lib/sandbox-path.sh

@@ -21,16 +21,70 @@ resolve_sandbox_dir() {
   printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
 }
 
-# Collapses repeated separators and strips every trailing one, leaving a bare
-# root as `/`. Every comparison below is a string test, so `//` and `$HOME//`
-# would otherwise read as paths no rule names.
+# Collapses repeated separators, folds `.` and `..` segments, and strips every
+# trailing separator, leaving a bare root as `/`. Every comparison below is a
+# string test, so `//`, `$HOME//`, and `$HOME/../../usr` each read as a path no
+# rule names until this runs, and an unresolved `..` defeats the allowlist and
+# both directions of the repository test at once.
+#
+# The fold is lexical because the guard runs before provisioning creates the
+# tree, which rules out `cd` with `pwd -P` and any resolution needing the path
+# to exist. Nothing here follows a symlink, so a `..` below one resolves against
+# the link's own path rather than its target. A `..` climbing past the root
+# clamps to `/`, matching the kernel, which leaves the allowlist to refuse it
+# under the rule that already covers every root path.
 normalize_sandbox_path() {
   local path="$1"
 
+  [ -n "$path" ] || return 0
+
   while [ "$path" != "${path//\/\//\/}" ]; do
     path="${path//\/\//\/}"
   done
 
+  local root=""
+  if [ "${path#/}" != "$path" ]; then
+    root="/"
+    path="${path#/}"
+  fi
+
+  # `resolved` carries each kept segment behind its own separator, so a pop is
+  # one suffix removal and popping an empty stack is the no-op that clamps at
+  # the root. `climbed` holds the leading `..` a relative path has no segment to
+  # pop against, which dropping would change the directory it names.
+  local resolved="" climbed="" segment
+  local remaining=4096
+
+  while [ -n "$path" ] && [ "$remaining" -gt 0 ]; do
+    remaining=$((remaining - 1))
+
+    segment="${path%%/*}"
+    if [ "$segment" = "$path" ]; then
+      path=""
+    else
+      path="${path#*/}"
+    fi
+
+    case "$segment" in
+    "" | .) ;;
+    ..)
+      if [ -n "$resolved" ]; then
+        resolved="${resolved%/*}"
+      elif [ -z "$root" ]; then
+        climbed="$climbed../"
+      fi
+      ;;
+    *) resolved="$resolved/$segment" ;;
+    esac
+  done
+
+  if [ -n "$root" ]; then
+    path="${resolved:-/}"
+  else
+    path="${climbed}${resolved#/}"
+    path="${path:-.}"
+  fi
+
   while [ "${#path}" -gt 1 ] && [ "${path%/}" != "$path" ]; do
     path="${path%/}"
   done
@@ -72,13 +126,28 @@ assert_sandbox_dir_safe() {
     return 1
   fi
 
+  # `normalize_sandbox_path` stops at 4096 segments and drops the remainder,
+  # which would hand the tests below an ancestor of the path provisioning
+  # removes. Refusing past `PATH_MAX` keeps that bound out of reach, since a
+  # segment costs at least two bytes and no syscall accepts the string anyway.
+  if [ "${#raw}" -gt 4096 ]; then
+    printf 'Refusing the sandbox path. It is %s characters, past the longest path any filesystem here accepts.\n' "${#raw}"
+    return 1
+  fi
+
   local dir home temp
   dir="$(normalize_sandbox_path "$raw")"
   home="$(normalize_sandbox_path "${HOME:-/root}")"
   temp="$(normalize_sandbox_path "${TMPDIR:-/tmp}")"
 
+  # Every message below names `$raw`, which is what the operator set. The tests
+  # compare `$dir`, so a path carrying `..` is refused for a location its own
+  # spelling does not show.
+  local resolution=""
+  [ "$dir" = "$raw" ] || resolution=" It resolves to $dir."
+
   if ! is_at_or_above "$home" "$dir" && ! is_at_or_above "$temp" "$dir"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.\n' "$raw" "$home" "$temp"
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.%s\n' "$raw" "$home" "$temp" "$resolution"
     return 1
   fi
 
@@ -93,13 +162,13 @@ assert_sandbox_dir_safe() {
   main_root="$(normalize_sandbox_path "${main_root:-$root}")"
 
   if is_at_or_above "$dir" "$main_root"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.\n' "$raw" "$main_root"
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.%s\n' "$raw" "$main_root" "$resolution"
     return 1
   fi
 
   case "$dir" in
   "$main_root"/*)
-    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain. Point AITK_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root"
+    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain.%s Point AITK_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root" "$resolution"
     return 1
     ;;
   esac

package/src/cli.ts

@@ -19,6 +19,7 @@ import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
 import { register as comments } from '@/commands/comments'
+import { register as context } from '@/commands/context'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -48,6 +49,7 @@ function showHelp(): void {
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
+    `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -79,6 +81,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
     `${GREY}│${NC}    aitk comments scan src --json`,
+    `${GREY}│${NC}    aitk context audit --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -115,5 +118,6 @@ feedback(program)
 transcripts(program)
 tasks(program)
 comments(program)
+context(program)
 
 program.parse()

package/src/commands/context.ts

@@ -0,0 +1,321 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type EntryReport,
+  LENGTH_CHECKPOINT,
+  measureFolders,
+  RUN_CHECKPOINT,
+} from '@/context/audit'
+import { auditCitations, type CitationReport } from '@/context/citations'
+import {
+  type AuditedFolder,
+  DEFAULT_FOLDERS,
+  presentNames,
+  resolveFolders,
+} from '@/context/folders'
+import { auditIndexes, type FolderDrift } from '@/context/index-drift'
+import {
+  frameError,
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
+
+/** Returned when an unresolved citation is found, which is the gating check. */
+const EXIT_UNRESOLVED = 2
+
+/** A name of dots alone is `.` or `..`, both of which escape the audit root. */
+const FOLDER_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+  readonly folder?: string
+  readonly citationsOnly?: boolean
+}
+
+export function register(program: Command): void {
+  const context = program
+    .command('context')
+    .description('Report the structural state of the context folders')
+    .helpOption('-h, --help', 'Show this help message')
+
+  context
+    .command('audit')
+    .description('Report entry length, depth, citations, 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('--citations-only', 'Run the gating citation check alone')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the audit completed with every cited path resolving',
+        '  1  refused, with the reason on stderr',
+        '  2  a cited path did not resolve',
+        '',
+        'Only unresolved citations set a failing exit code. Length, depth,',
+        'table, and index findings are advisory.',
+        '',
+        'Examples:',
+        '  aitk context audit',
+        '  aitk context audit --json',
+        '  aitk context audit --citations-only',
+        '  aitk context audit --folder context,diagrams',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(path, opts)
+    })
+}
+
+function parseFolders(list: string | undefined): string[] | string {
+  if (!list) return [...DEFAULT_FOLDERS]
+
+  const names = list
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+
+  if (names.length === 0) return 'Empty --folder list. Pass at least one name.'
+
+  // `..` would resolve the audit root above `.claude/`, where `presentNames`
+  // has no folder name to slice out and hands the citation pattern undefined.
+  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 names
+}
+
+async function runAudit(
+  path: string | undefined,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const names = parseFolders(opts.folder)
+  const gateOnly = opts.citationsOnly ?? false
+
+  if (typeof names === 'string') return refuse(names, gateOnly)
+
+  const folders = await resolveFolders(root, names)
+  if (folders.length === 0) {
+    return refuse(
+      `No audited folder found under .claude/. Looked for: ${names.join(', ')}.`,
+      gateOnly,
+    )
+  }
+
+  const citations = await auditCitations(root, presentNames(folders))
+  if (citations.kind === 'unavailable') {
+    return refuse(
+      'git could not list the tree, so no citation was checked. Run inside a git repository.',
+      gateOnly,
+    )
+  }
+
+  const entries = gateOnly ? [] : await measureFolders(root, folders)
+  const drift = gateOnly ? [] : await auditIndexes(folders)
+
+  if (gateOnly) {
+    reportGate(citations)
+  } else {
+    intro('aitk context audit')
+    reportScope(folders)
+    reportCitations(citations)
+    reportLength(entries)
+    reportDepth(entries)
+    reportTables(entries)
+    reportDrift(drift)
+    outro()
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        folders: folders.map((folder) => ({
+          path: folder.rel,
+          entries: folder.entries.length,
+        })),
+        citations: {
+          scanned: citations.scanned,
+          total: citations.total,
+          unresolved: citations.unresolved,
+        },
+        entries,
+        indexDrift: drift,
+        checkpoints: {
+          lines: LENGTH_CHECKPOINT,
+          run: RUN_CHECKPOINT,
+          runCountsBlankLines: true,
+        },
+      })}\n`,
+    )
+  }
+
+  return citations.unresolved.length > 0 ? EXIT_UNRESOLVED : 0
+}
+
+function refuse(message: string, gateOnly: boolean): number {
+  if (gateOnly) {
+    frameError(message)
+    return 1
+  }
+
+  intro('aitk context audit')
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  return 1
+}
+
+/**
+ * Prints nothing when every path resolves.
+ *
+ * `--citations-only` is what `verify.sh` runs on every push, and that script
+ * pipes a stage's whole output into its own frame. A passing gate that printed
+ * its frame would nest one inside the other on every contributor's push.
+ */
+function reportGate(report: ScannedCitations): void {
+  const count = report.unresolved.length
+  if (count === 0) return
+
+  intro('aitk context audit')
+  logError(
+    count === 1
+      ? '1 cited path does not resolve'
+      : `${count} cited paths do not resolve`,
+  )
+  pipeOutput(
+    report.unresolved
+      .map((citation) => `${citation.file}:${citation.line}  ${citation.path}`)
+      .join('\n'),
+  )
+  outro()
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
+function reportScope(folders: readonly AuditedFolder[]): void {
+  logStep('Scope')
+
+  for (const folder of folders) {
+    logInfo(`${folder.rel}: ${folder.entries.length} entries`)
+  }
+}
+
+type ScannedCitations = Extract<CitationReport, { kind: 'scanned' }>
+
+function reportCitations(report: ScannedCitations): void {
+  logStep('Citations')
+  logInfo(
+    `${plural(report.total, 'cited path')} across ${plural(report.scanned, 'file')}, fixtures and fenced examples excluded`,
+  )
+
+  if (report.unresolved.length === 0) {
+    logInfo('Every cited path resolves.')
+    return
+  }
+
+  logWarn(`${report.unresolved.length} unresolved`)
+  pipeOutput(
+    report.unresolved
+      .map((citation) => `${citation.file}:${citation.line}  ${citation.path}`)
+      .join('\n'),
+  )
+}
+
+function reportLength(entries: readonly EntryReport[]): void {
+  logStep('Length')
+
+  const over = entries
+    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
+    .sort((a, b) => b.lines - a.lines)
+
+  if (over.length === 0) {
+    logInfo(`No entry past the ${LENGTH_CHECKPOINT}-line checkpoint.`)
+    return
+  }
+
+  logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
+  pipeOutput(
+    over.map((entry) => `${entry.rel}  ${entry.lines} lines`).join('\n'),
+  )
+}
+
+/**
+ * Names the blank-line convention on every run.
+ *
+ * The standard settles heading level and fenced blocks and stops there, so a
+ * hand reader who drops blank lines lands a line or two below this number.
+ * Stating it is what keeps the two measurements reconcilable.
+ */
+function reportDepth(entries: readonly EntryReport[]): void {
+  logStep('Depth')
+  logInfo('Runs count blank lines. Fenced blocks and peer lists are excluded.')
+
+  const over = entries
+    .filter((entry) => entry.longestRun > RUN_CHECKPOINT)
+    .sort((a, b) => b.longestRun - a.longestRun)
+
+  if (over.length === 0) {
+    logInfo(`No run past the ${RUN_CHECKPOINT}-line checkpoint.`)
+    return
+  }
+
+  logWarn(`${over.length} past the ${RUN_CHECKPOINT}-line checkpoint`)
+  pipeOutput(
+    over
+      .map(
+        (entry) =>
+          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} lines unbroken`,
+      )
+      .join('\n'),
+  )
+}
+
+function reportTables(entries: readonly EntryReport[]): void {
+  logStep('Tables')
+
+  const candidates = entries.flatMap((entry) =>
+    entry.catalogTables.map(
+      (table) => `${entry.rel}:${table.line}  ${table.rows} rows`,
+    ),
+  )
+
+  if (candidates.length === 0) {
+    logInfo('No table reads as a catalog that grows a row per shipped thing.')
+    return
+  }
+
+  logWarn(`${plural(candidates.length, 'candidate')} for a bullet list`)
+  pipeOutput(candidates.join('\n'))
+}
+
+function reportDrift(drift: readonly FolderDrift[]): void {
+  logStep('Index drift')
+
+  const lines = drift.flatMap((folder) => [
+    ...folder.unlisted.map((name) => `${folder.rel}  unlisted: ${name}`),
+    ...folder.missing.map((name) => `${folder.rel}  missing: ${name}`),
+  ])
+
+  if (lines.length === 0) {
+    logInfo('Every index agrees with its siblings.')
+    return
+  }
+
+  logWarn(plural(lines.length, 'disagreement'))
+  pipeOutput(lines.join('\n'))
+}

package/src/context/audit.ts

@@ -0,0 +1,227 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+/** Checkpoints quoted from `standards/context.md`. Neither is a cap. */
+export const LENGTH_CHECKPOINT = 150
+export const RUN_CHECKPOINT = 40
+
+/**
+ * A table this size or larger whose first column mostly names artifacts reads
+ * as a catalog that grows a row per shipped thing, which is the shape the
+ * standard routes to a bullet list. Below it, a table is small enough that a
+ * reflow rewrites little.
+ */
+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
+
+const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
+const FENCE = /^\s*(```|~~~)/
+const HEADING = /^#{1,6}\s/
+const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
+const TABLE_ROW = /^\s*\|/
+const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/
+
+export interface TableFinding {
+  readonly line: number
+  readonly rows: number
+}
+
+export interface EntryReport {
+  readonly rel: string
+  readonly lines: number
+  readonly longestRun: number
+  /** First line of the longest run, or 0 when the entry has no run at all. */
+  readonly longestRunLine: number
+  readonly catalogTables: readonly TableFinding[]
+}
+
+interface BodyLine {
+  readonly number: number
+  readonly text: string
+}
+
+/**
+ * Drops the frontmatter while keeping every surviving line's original number,
+ * so a finding points at the line an editor opens rather than at an offset into
+ * the body.
+ */
+function bodyLines(source: string): BodyLine[] {
+  const match = source.match(FRONTMATTER)
+  const offset = match ? match[0].split('\n').length - 1 : 0
+
+  return source
+    .slice(match ? match[0].length : 0)
+    .replace(/\n$/, '')
+    .split('\n')
+    .map((text, index) => ({ number: offset + index + 1, text }))
+}
+
+/**
+ * Reports whether a run is the peer list the standard exempts.
+ *
+ * Every non-blank line has to be a list item at one indent. Prose mixed into
+ * the run or a nested level inside it ends the exemption, because either one
+ * means the block is no longer a flat set a reader can skim.
+ */
+function isPeerList(run: readonly BodyLine[]): boolean {
+  const indents = new Set<number>()
+
+  for (const line of run) {
+    if (line.text.trim() === '') continue
+
+    const match = line.text.match(LIST_ITEM)
+    if (!match) return false
+    indents.add(match[1].length)
+  }
+
+  return indents.size === 1
+}
+
+/**
+ * Measures the longest run of lines no heading breaks.
+ *
+ * Fenced blocks are skipped rather than treated as breaks, per the standard:
+ * they leave the count without ending the run, so prose either side of an
+ * example still measures as the one stretch a reader scrolls through. Blank
+ * lines do count, since the checkpoint is about how far a reader travels
+ * between signposts and a blank line is distance like any other. A hand reader
+ * measuring without them lands one or two lines lower, which the report legend
+ * states.
+ */
+function longestRun(lines: readonly BodyLine[]): {
+  length: number
+  line: number
+} {
+  let longest = 0
+  let longestLine = 0
+  let run: BodyLine[] = []
+  let fenced = false
+
+  const close = (): void => {
+    // The reported line is the run's first non-blank one, since that is what an
+    // editor should open. A run of nothing but blank lines is the gap between
+    // two headings rather than a stretch a reader travels, so it never counts.
+    const first = run.find((line) => line.text.trim() !== '')
+
+    if (first && run.length > longest && !isPeerList(run)) {
+      longest = run.length
+      longestLine = first.number
+    }
+    run = []
+  }
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    if (HEADING.test(line.text)) {
+      close()
+      continue
+    }
+
+    run.push(line)
+  }
+
+  close()
+
+  return { length: longest, line: longestLine }
+}
+
+function firstCell(row: string): string {
+  return row.split('|').slice(1)[0] ?? ''
+}
+
+/**
+ * Finds the tables whose rows name shipped artifacts.
+ *
+ * A bare table count reports mostly fixed comparison tables, where a reflow
+ * costs nothing because no row is ever added. The reflow problem belongs to a
+ * catalog that gains a row per artifact, and a first column carrying a path,
+ * command, or link is what separates the two without reading the prose.
+ */
+function catalogTables(lines: readonly BodyLine[]): TableFinding[] {
+  const findings: TableFinding[] = []
+  let fenced = false
+  let index = 0
+
+  while (index < lines.length) {
+    const line = lines[index]
+
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      index++
+      continue
+    }
+    if (fenced || !TABLE_ROW.test(line.text)) {
+      index++
+      continue
+    }
+
+    const separator = lines[index + 1]
+    if (!separator || !TABLE_SEPARATOR.test(separator.text)) {
+      index++
+      continue
+    }
+
+    const body: BodyLine[] = []
+    let cursor = index + 2
+    while (cursor < lines.length && TABLE_ROW.test(lines[cursor].text)) {
+      body.push(lines[cursor])
+      cursor++
+    }
+
+    const named = body.filter((row) => NAMED_CELL.test(firstCell(row.text)))
+    if (
+      body.length >= CATALOG_ROW_CHECKPOINT &&
+      named.length / body.length >= CATALOG_NAMED_RATIO
+    ) {
+      findings.push({ line: line.number, rows: body.length })
+    }
+
+    index = cursor
+  }
+
+  return findings
+}
+
+export function measureEntry(rel: string, source: string): EntryReport {
+  const lines = bodyLines(source)
+  const run = longestRun(lines)
+
+  return {
+    rel,
+    lines: source.replace(/\n$/, '').split('\n').length,
+    longestRun: run.length,
+    longestRunLine: run.line,
+    catalogTables: catalogTables(lines),
+  }
+}
+
+/**
+ * Measures every entry in the audited folders. A generated `index.md` is not
+ * among them, since its body is rewritten on every regen and no checkpoint
+ * describes a catalog.
+ */
+export async function measureFolders(
+  root: string,
+  folders: readonly AuditedFolder[],
+): Promise<EntryReport[]> {
+  const reports: EntryReport[] = []
+
+  for (const folder of folders) {
+    for (const path of folder.entries) {
+      reports.push(
+        measureEntry(relative(root, path), await readFile(path, 'utf8')),
+      )
+    }
+  }
+
+  return reports
+}

package/src/context/citations.ts

@@ -0,0 +1,167 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Suppresses citation checking for the source line carrying it.
+ *
+ * Prose that teaches a naming pattern displays a path rather than pointing at
+ * one, and no syntax separates the two: an illustration and a reference are
+ * both inline code in a sentence. Location covers the fixture trees and fenced
+ * examples, and this covers what is left, which is a sentence naming a
+ * hypothetical entry to show the shape of the name.
+ */
+export const IGNORE_MARKER = 'audit-ignore-citations'
+
+/**
+ * Trees holding content authored to be parsed rather than followed.
+ *
+ * Sandbox scenarios describe paths inside their own scratch fixtures and the
+ * eval harness names paths in its target project. Neither is a reference into
+ * this repository, so an unresolved path there is correct rather than stale.
+ */
+const FIXTURE_TREES: readonly string[] = ['scripts/sandbox/', 'scripts/eval/']
+
+const FIXTURE_SEGMENTS: readonly string[] = ['fixtures', '__fixtures__']
+
+const FENCE = /^\s*(```|~~~)/
+
+export interface Citation {
+  readonly file: string
+  readonly line: number
+  readonly path: string
+}
+
+export function isFixture(rel: string): boolean {
+  if (rel.endsWith('.test.ts')) return true
+  if (FIXTURE_TREES.some((tree) => rel.startsWith(tree))) return true
+  return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
+}
+
+export function citationPattern(folders: readonly string[]): RegExp {
+  const names = folders.map((name) =>
+    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+  )
+  return new RegExp(
+    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    'g',
+  )
+}
+
+/**
+ * Pulls the cited paths out of one file's text.
+ *
+ * Fenced blocks are skipped for markdown only. A fence is markdown syntax, and
+ * applying it to a shell or TypeScript source would let a heredoc of triple
+ * backticks silently hide the rest of the file.
+ */
+export function collectCitations(
+  rel: string,
+  text: string,
+  pattern: RegExp,
+): Citation[] {
+  const isMarkdown = rel.endsWith('.md')
+  const found: Citation[] = []
+  let fenced = false
+
+  for (const [index, line] of text.split('\n').entries()) {
+    if (isMarkdown && FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced || line.includes(IGNORE_MARKER)) continue
+
+    for (const match of line.matchAll(pattern)) {
+      found.push({ file: rel, line: index + 1, path: match[0] })
+    }
+  }
+
+  return found
+}
+
+/**
+ * Lists the files a citation can live in: tracked, plus untracked files git
+ * does not ignore. The untracked half is what keeps a new entry's references
+ * checked on the branch that adds it rather than one push later.
+ *
+ * Returns undefined when git cannot answer, which the caller reports rather
+ * than smoothing into an empty list. An empty list resolves every one of its
+ * zero citations, so a degraded git would otherwise turn the push gate into an
+ * unconditional pass with output indistinguishable from a clean tree.
+ */
+async function listFiles(root: string): Promise<string[] | undefined> {
+  const run = async (args: string[]): Promise<string[] | undefined> => {
+    const result = await $`git -C ${root} ${args}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+    if (result.exitCode !== 0) return undefined
+    return result.text().split('\n').filter(Boolean)
+  }
+
+  const tracked = await run(['ls-files'])
+  const untracked = await run(['ls-files', '--others', '--exclude-standard'])
+  if (!tracked || !untracked) return undefined
+
+  return [...new Set([...tracked, ...untracked])].sort()
+}
+
+/**
+ * `unavailable` is a distinct state from a clean scan.
+ *
+ * Finding nothing and being unable to look mean opposite things, and only one
+ * of them should let a push through.
+ */
+export type CitationReport =
+  | {
+      readonly kind: 'scanned'
+      readonly scanned: number
+      readonly total: number
+      readonly unresolved: readonly Citation[]
+    }
+  | { readonly kind: 'unavailable' }
+
+/**
+ * Resolves every cited path outside the fixture trees.
+ *
+ * This is the only check that gates the repository check, which makes it the
+ * only one whose false positives cost a contributor anything. It reports a
+ * finding solely for a path that does not resolve on disk, and the exclusions
+ * above are what keep that from firing on prose about paths.
+ */
+export async function auditCitations(
+  root: string,
+  folders: readonly string[],
+): Promise<CitationReport> {
+  const pattern = citationPattern(folders)
+  const listed = await listFiles(root)
+  if (!listed) return { kind: 'unavailable' }
+
+  const candidates = listed.filter((rel) => !isFixture(rel))
+  const citations: Citation[] = []
+
+  for (const rel of candidates) {
+    const path = resolve(root, rel)
+    if (!existsSync(path)) continue
+
+    let text: string
+    try {
+      text = await readFile(path, 'utf8')
+    } catch {
+      continue
+    }
+
+    citations.push(...collectCitations(rel, text, pattern))
+  }
+
+  return {
+    kind: 'scanned',
+    scanned: candidates.length,
+    total: citations.length,
+    unresolved: citations.filter(
+      (citation) => !existsSync(resolve(root, citation.path)),
+    ),
+  }
+}

package/src/context/folders.ts

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+
+/**
+ * Folder names under `.claude/` audited by default.
+ *
+ * The index-plus-entry contract on its own over-collects. `.claude/standards/`
+ * also carries a generated index beside entries with frontmatter, and auditing
+ * it would measure the consumed copy of `standards/` against a rule written for
+ * per-domain narrative. This list names the folders `standards/context.md`
+ * governs, and `--folder` admits another without an edit here.
+ */
+export const DEFAULT_FOLDERS: readonly string[] = [
+  'context',
+  'diagrams',
+  'wireframes',
+]
+
+export interface AuditedFolder {
+  /** Repo-relative folder path, used verbatim in every report line. */
+  readonly rel: string
+  readonly indexPath: string
+  /** Absolute paths of the folder's own entries, excluding its `index.md`. */
+  readonly entries: readonly string[]
+}
+
+/**
+ * Names the requested folders that actually exist, which is the citation
+ * check's scope.
+ *
+ * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
+ * a project that carries the folder and says nothing about one that does not.
+ * Checking a path into an absent folder would fail eight shipped references
+ * here for the sole reason that this repository has no wireframes.
+ */
+export function presentNames(folders: readonly AuditedFolder[]): string[] {
+  return [...new Set(folders.map((folder) => folder.rel.split('/')[1]))]
+}
+
+async function readEntries(dir: string): Promise<string[]> {
+  const paths: string[] = []
+
+  for await (const name of new Bun.Glob('*.md').scan({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    if (name === INDEX_FILE) continue
+    paths.push(resolve(dir, name))
+  }
+
+  return paths.sort()
+}
+
+/**
+ * Resolves the folders to audit under `root`.
+ *
+ * A named folder contributes its own entries plus those of every nested index
+ * folder beneath it, so a domain that outgrew one file and split is audited at
+ * the same grain as one that did not. Discovery of the nested folders runs
+ * through the shared walker, which is what keeps `.gitignore` and the vendored
+ * prune governing this scan as well as index regeneration.
+ *
+ * A requested folder that does not exist is dropped rather than reported. The
+ * default list names three folders and a project carrying one of them is the
+ * ordinary case.
+ */
+export async function resolveFolders(
+  root: string,
+  names: readonly string[] = DEFAULT_FOLDERS,
+): Promise<AuditedFolder[]> {
+  const folders: AuditedFolder[] = []
+
+  for (const name of names) {
+    const dir = resolve(root, '.claude', name)
+    if (!existsSync(`${dir}/${INDEX_FILE}`)) continue
+
+    const dirs = [dir, ...(await listIndexes(dir)).map(dirname)]
+
+    for (const each of [...new Set(dirs)].sort()) {
+      folders.push({
+        rel: relative(root, each),
+        indexPath: `${each}/${INDEX_FILE}`,
+        entries: await readEntries(each),
+      })
+    }
+  }
+
+  return folders
+}

package/src/context/index-drift.ts

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+const ENTRY_LINK = /^-\s+\[[^\]]*\]\(([^)]+)\)/
+
+export interface FolderDrift {
+  readonly rel: string
+  /** Entry files present in the folder that the index does not link. */
+  readonly unlisted: readonly string[]
+  /** Names the index links that resolve to nothing on disk. */
+  readonly missing: readonly string[]
+}
+
+/** Collects the link targets of an index's catalog bullets. */
+export function listedTargets(source: string): string[] {
+  const targets: string[] = []
+
+  for (const line of source.split('\n')) {
+    const match = line.match(ENTRY_LINK)
+    if (match) targets.push(match[1])
+  }
+
+  return targets
+}
+
+/**
+ * Compares one folder's index against its siblings in both directions.
+ *
+ * Both halves are reported because they fail differently. An unlisted entry is
+ * invisible to a session reading the catalog to choose what to open, while a
+ * listed name with no file sends one to a path that opens nothing. Neither
+ * surfaces from reading the index alone.
+ */
+export async function auditFolder(folder: AuditedFolder): Promise<FolderDrift> {
+  const dir = dirname(folder.indexPath)
+  const source = await readFile(folder.indexPath, 'utf8')
+  const targets = listedTargets(source)
+
+  // A sub-catalog is linked as `<name>/index.md` and its entries are audited
+  // as their own folder, so only the leading segment is compared here.
+  const listed = new Set(targets.map((target) => target.split('/')[0]))
+
+  const unlisted = folder.entries
+    .map((path) => basename(path))
+    .filter((name) => !listed.has(name))
+
+  const missing = targets.filter((target) => !existsSync(resolve(dir, target)))
+
+  return { rel: folder.rel, unlisted, missing }
+}
+
+export async function auditIndexes(
+  folders: readonly AuditedFolder[],
+): Promise<FolderDrift[]> {
+  const drift: FolderDrift[] = []
+
+  for (const folder of folders) {
+    drift.push(await auditFolder(folder))
+  }
+
+  return drift
+}