@erclx/aitk 0.19.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.19.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.19.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

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+
+# The sandbox tree lives outside the toolkit worktree. `scripts/sandbox/run.sh`
+# sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
+# filesystem root loads into the session. Under the repository the toolkit's own
+# instructions join that chain beside the seeded copy the scenario installed,
+# both carry the rule sending shared session scratch to the main worktree root,
+# and nothing decides which root wins. A session picking the toolkit writes its
+# output where no manifest reads it, so the run reports success while the verdict
+# reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
+# repository for the same reason.
+#
+# Twin of `SANDBOX_DIR` in `src/commands/sandbox.ts`. The exec boundary rules out
+# a shared constant, so a change to the default lands on both sides.
+resolve_sandbox_dir() {
+  if [ -n "${AITK_SANDBOX_DIR:-}" ]; then
+    printf '%s\n' "$AITK_SANDBOX_DIR"
+    return 0
+  fi
+
+  printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
+}
+
+# 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
+
+  printf '%s' "$path"
+}
+
+# Whether `candidate` is `target` or a directory containing it. Removing the
+# former removes the latter, which is what makes an ancestor as dangerous as an
+# exact match.
+is_at_or_above() {
+  local candidate="$1"
+  local target="$2"
+
+  [ "$candidate" = "$target" ] || [ "${target#"$candidate"/}" != "$target" ]
+}
+
+# Prints the reason a location is unusable and returns non-zero, so the caller
+# reports one message naming the path rather than a bare refusal.
+#
+# Provisioning runs `rm -rf` on this path at three sites before staging, so the
+# test is an allowlist rather than a list of paths to refuse. A blocklist has to
+# name every system directory to be right once and stays wrong as soon as one is
+# missed, while requiring a strict descendant of the home directory or of the
+# temp root admits the default and every reasonable override and refuses `/`,
+# `/usr`, `/etc`, and `$HOME` itself without naming any of them.
+#
+# The repository test is separate and runs both ways. A path under the worktree
+# restores the ancestor chain the relocation removed, and a path above it is one
+# `rm -rf` away from deleting the repository. It resolves the main worktree root
+# rather than trusting `$PROJECT_ROOT`, since a linked worktree is itself inside
+# that root.
+assert_sandbox_dir_safe() {
+  local raw="$1"
+  local root="${2:-${PROJECT_ROOT:-$PWD}}"
+
+  if [ -z "$raw" ] || [ "${raw#/}" = "$raw" ]; then
+    printf 'AITK_SANDBOX_DIR must be an absolute path, got: %s\n' "${raw:-<empty>}"
+    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.%s\n' "$raw" "$home" "$temp" "$resolution"
+    return 1
+  fi
+
+  if [ "$dir" = "$home" ] || [ "$dir" = "$temp" ]; then
+    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s rather than be it.\n' "$raw" "$dir"
+    return 1
+  fi
+
+  local main_root
+  main_root="$(git -C "$root" worktree list --porcelain 2>/dev/null |
+    grep -m 1 '^worktree ' | cut -d' ' -f2-)"
+  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.%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.%s Point AITK_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root" "$resolution"
+    return 1
+    ;;
+  esac
+
+  return 0
+}

package/scripts/lib/ui.sh

@@ -6,6 +6,12 @@ if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
   exit 1
 fi
 
+# Resolved from this file's own location rather than `$PROJECT_ROOT`, because
+# `require_project_root` is what several scripts call before anything has
+# established a root.
+# shellcheck source=/dev/null
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/sandbox-path.sh"
+
 GREEN='\033[0;32m'
 RED='\033[0;31m'
 YELLOW='\033[0;33m'
@@ -46,7 +52,9 @@ guard_root() {
 }
 
 require_project_root() {
-  if [[ "$PWD" == *".sandbox"* ]]; then
+  local sandbox
+  sandbox="$(resolve_sandbox_dir)"
+  if [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]]; then
     echo -e "${GREY}┌${NC}" >&2
     log_error "Execution restricted: Command cannot be run from inside the sandbox environment."
   fi

package/scripts/manage-sandbox.sh

@@ -8,6 +8,7 @@ export PROJECT_ROOT
 
 source "$PROJECT_ROOT/scripts/config.sh"
 source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-path.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-git.sh"
 source "$PROJECT_ROOT/scripts/lib/sandbox-fixtures.sh"
 
@@ -135,8 +136,8 @@ validate_environment() {
     log_error "Sandbox directory not found at: $SANDBOX_DIR"
   fi
 
-  if [[ "$PWD" == *".sandbox"* ]]; then
-    log_warn "Detected execution inside .sandbox. Switching to project root..."
+  if [[ "$PWD" == "$SANDBOX" || "$PWD" == "$SANDBOX"/* ]]; then
+    log_warn "Detected execution inside the sandbox. Switching to project root..."
     cd "$PROJECT_ROOT" || log_error "Failed to switch to project root."
   fi
 }
@@ -324,7 +325,7 @@ finalize_sandbox_run() {
 cmd_clean() {
   log_step "Removing sandbox"
   rm -rf "$SANDBOX"
-  log_rem ".sandbox/"
+  log_rem "$SANDBOX"
   trap - EXIT
   close_timeline
   echo "" >&2
@@ -422,9 +423,14 @@ main() {
     log_error "Context error: you must run this command from inside the toolkit repository."
   fi
 
-  SANDBOX="$PROJECT_ROOT/.sandbox"
+  SANDBOX="$(resolve_sandbox_dir)"
   SANDBOX_DIR="$PROJECT_ROOT/scripts/sandbox"
 
+  local unsafe
+  if ! unsafe="$(assert_sandbox_dir_safe "$SANDBOX" "$PROJECT_ROOT")"; then
+    log_error "$unsafe"
+  fi
+
   if [[ "$1" == "reset" ]]; then
     reset_sandbox
     exit 0

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/commands/sandbox.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { PROJECT_ROOT, execScript } from '@/exec'
@@ -28,6 +29,29 @@ import {
 
 const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
 
+/**
+ * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
+ * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
+ * `CLAUDE.md` stays off the ancestor chain of the session `run.sh` spawns with
+ * cwd here.
+ *
+ * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
+ * boundary rules out a shared constant, so a change to the default lands on both
+ * sides.
+ */
+function sandboxTree(): string {
+  const override = process.env.AITK_SANDBOX_DIR
+  if (override !== undefined && override !== '') return override
+
+  const state = process.env.XDG_STATE_HOME
+  const base =
+    state !== undefined && state !== ''
+      ? state
+      : join(homedir(), '.local', 'state')
+
+  return join(base, 'aitk', 'sandbox')
+}
+
 /**
  * Holds fixture content for scenarios rather than scenarios of its own.
  * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.
@@ -224,7 +248,7 @@ function runCheck(
   // A sandbox that was never provisioned fails every path assertion, reading as a
   // skill that did nothing rather than a caller that ran check too early. The
   // whole point of a verdict is that it means what it says.
-  const sandboxDir = join(PROJECT_ROOT, '.sandbox')
+  const sandboxDir = sandboxTree()
   if (!existsSync(sandboxDir)) {
     logError(`No sandbox at ${sandboxDir}. Provision one with aitk sandbox.`)
     outro()

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
+}

package/src/sandbox/expect.ts

@@ -141,9 +141,33 @@ function contentArray(value: unknown): ContentAssertion[] {
     if (typeof entry !== 'object' || entry === null) continue
 
     const record = entry as Record<string, unknown>
+
+    // Dropping a half-written entry rather than throwing is deliberate, and it
+    // reads as the opposite of the stray-key check below. An entry missing its
+    // path or pattern declares no assertion to lose, and `checkExpectation`
+    // fails an arm whose surviving declaration asserts nothing, so the vacuous
+    // pass is already closed one level up. A stray key is the reverse: the entry
+    // is well-formed and the declaration around it silently lost a key it
+    // appears to carry, which nothing downstream can see.
     if (typeof record.path !== 'string' || record.path === '') continue
     if (typeof record.pattern !== 'string' || record.pattern === '') continue
 
+    // A bare key written below a `[[content]]` header belongs to that table in
+    // TOML, not to the document, so a declaration listing `manual` or
+    // `max_turns` after its content blocks parses clean and silently asserts
+    // neither. The `claude/ui-test` arm shipped that way: a turn ceiling that
+    // never ran and five manual entries that never reached the unchecked count,
+    // while `aitk sandbox coverage` counted the arm as armed. Nothing at the
+    // top level can see the difference, so the check belongs here.
+    const stray = Object.keys(record).filter(
+      (key) => key !== 'path' && key !== 'pattern',
+    )
+    if (stray.length > 0) {
+      throw new Error(
+        `content entry for ${record.path} carries ${stray.join(', ')}. Move top-level keys above the first [[content]] block.`,
+      )
+    }
+
     assertions.push({ path: record.path, pattern: record.pattern })
   }
 
@@ -257,6 +281,20 @@ function checkWriteScope(
     }
   }
 
+  // A scope produces one result per write, so a run that wrote nothing produces
+  // none, and without this the declaration vanishes from the verdict entirely:
+  // no result, no skipped entry, and no contribution to the unchecked count that
+  // exists to surface exactly this. The `undefined` branch above cannot stand in,
+  // since `run.sh` always passes `--writes` and `readWrites` returns `[]` for an
+  // empty file. An arm whose output escaped the snapshot reads as a clean run,
+  // which is the vacuous pass the harness exists to remove.
+  if (writes.length === 0) {
+    return {
+      results: [],
+      skipped: ['write scope: the run wrote nothing, so no path was checked'],
+    }
+  }
+
   const globs = expectation.writeScope.map((glob) => new Bun.Glob(glob))
 
   return {