@erclx/aitk 3.48.1 → 3.49.0

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

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

package/docs/agents/commands.md

@@ -55,6 +55,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                               |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
 | `aitk gov restated`        | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)  |
+| `aitk gov citations`       | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`)                                                       |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
 | `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
 | `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
@@ -96,7 +97,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                                |
 | `snippets`  | `list`, `create`                                                                                                                      |
 | `standards` | `list`, `audit`, `<name>`                                                                                                             |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`, `citations`                                                  |
 | `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
 | `demo`      | `compile`, `run`                                                                                                                      |
 | `inventory` | `run`                                                                                                                                 |

package/docs/agents/index.md

@@ -28,6 +28,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
+- [Rule citations](rule-citations.md): Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the three forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see

package/docs/agents/rule-citations.md

@@ -0,0 +1,98 @@
+---
+title: Rule citations
+description: Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the three forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
+---
+
+# Rule citations
+
+`aitk gov citations` resolves every path a rule cites and every frontmatter glob the internal corpus declares, naming the ones reaching nothing. It answers a failure no other stage sees: a rule points a reader at a file, the file moves, and nothing reports it until a session opens the path and finds an absence.
+
+A glob fails the same way and more quietly. A rule scoped at a directory that moved stops matching, so it never loads again, and a rule that never fires looks exactly like a rule nobody violated.
+
+```bash
+aitk gov citations
+aitk gov citations --json
+aitk gov citations --root ../my-app
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | Tree to read, defaulting to the current directory          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## What the drift check cannot see
+
+`bun run check` asserts that an authored rule and its consumed copy agree, and a dead citation passes that assertion because both copies carry it. `governance/rules/claude/561-teach.md` told its reader to open a `references/glossary.md` inside the teach skill that had never existed at that path. The rule shipped, survived a release, and fired during a real teach run before anyone noticed.
+
+Two files agreeing is what a drift check measures. Whether either one is right about the tree is a different question, and this is the stage that asks it.
+
+## The three forms
+
+A citation reaches a reader in one of three shapes, and each resolves against a different root.
+
+| Form       | Shape                    | Resolves against                   |
+| ---------- | ------------------------ | ---------------------------------- |
+| `standard` | `aitk standards <name>`  | `standards/<name>.md`              |
+| `path`     | a backticked path        | the root                           |
+| `sibling`  | a bare `<nnn>-<slug>.md` | the folder the citing rule sits in |
+
+`standard` is the live form and carries most of the corpus, which is what makes scoping this check to the two path shapes a check over almost nothing.
+
+A standard name resolves against the authoring root and nowhere else, matching `standardRoots` in `src/standards/read.ts`, which reads `standards/` at the working root and then the package corpus. The stage refuses a tree holding no rule corpus, so it runs only where those two roots are one directory. `internal/standards/` is deliberately not tried: `aitk standards <name>` never reaches it, so admitting it would pass a citation that refuses for the session opening it, which is a gate failing open.
+
+A `path` is anchored on the whole backticked span rather than on a trailing pattern inside it. Cutting `standards/tooling-reference.md` out of `internal/standards/tooling-reference.md` and resolving that against the standards root reports a file that exists as missing, which is a mistake made by hand while measuring this corpus before the stage was written.
+
+## What is not a citation
+
+A rule body is full of backticked spans carrying a slash, and almost none of them names a file in this tree. The stage declines four shapes outright.
+
+- A placeholder or glob segment describes a shape rather than naming a file: `.claude/context/<domain>.md`, `standards/<name>.md`, `app/**/route.ts`, `${CLAUDE_SKILL_DIR}/../../standards/<name>.md`.
+- A bare filename names a convention: `route.ts`, `manifest.toml`, `components.json`, `playwright.config.ts`. A bare name is read as a citation only when it matches a rule filename, which is how `562-session.md` points at `555-tasks.md`.
+- A span carrying no file extension is a folder or a module specifier: `src/pages/`, `next/font`, `try/except`, `react-hooks/set-state-in-effect`, `oven-sh/setup-bun@v2`, `@/lib/utils`.
+- A fenced block displays a path rather than pointing at one.
+
+The extension test is what carries most of the separation, and it costs one real path: `claude/standards` is a symlink this stage declines to check because nothing in the span says it is a file. Declining is the right direction for a gate, where a guess that goes wrong fails a push over prose.
+
+## Where an absent path is correct
+
+Two classes resolve to nothing and are right to. Both are reported by name rather than dropped, so a reader can see what the verdict declined to judge.
+
+**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here. `governance/rules/claude/560-diagrams.md` declares `.claude/DIAGRAMS.md` and then tells its reader to convert one an older install left behind, so the file is correctly absent from this tree and correctly named in the rule.
+
+Only an exact declaration exempts, never a glob match against one. A glob declares a shape, so a body path sitting inside it is still a citation and a stale one is still a defect. A rule scoped at `docs/**` citing a `docs/agents/renamed.md` that moved is exactly the class this stage exists to catch, and matching the glob would excuse it.
+
+**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/claude/555-tasks.md` cites `.claude/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
+
+## Why the glob half reads one corpus
+
+Bodies are read across both corpora and frontmatter globs across `internal/rules/` alone.
+
+A rule under `governance/rules/` installs into a target, and its `paths:` entries name the shape that project holds rather than anything here. Measured over that corpus, 32 of its 72 globs match nothing in this tree and every one of them is correct. `src/pages/**` in the Astro rule cannot be told by pattern from a path this repository might hold, so a check cannot separate the two, and gating them would ship an exemption list the length of the corpus. Nothing reads the shipped globs, and the measurement is the reason rather than a gap left for someone to close.
+
+`internal/rules/` ships nowhere. The tree it governs is the tree present, which makes the question answerable, and all 14 of its globs across 7 rules match at the commit this shipped on.
+
+What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/305-e2e-reliability.md` scopes itself at `e2e/*.ts` and `e2e/**/*.ts`, and no probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
+
+## The exemption marker
+
+Everything the classifier can separate mechanically is separated there. For the residue, a line carries `aitk-allow-citation: <reason>` on itself or the one directly above, which moves it into the report's `Exempt` section. Only a marker naming a reason counts, since a bare token is a line that meant to say something and did not. This is the `aitk-allow-superseded` shape, and both read the same placement rule through one helper.
+
+## The blind spots
+
+A citation that resolves and points at the wrong file passes. Resolution is mechanical and correctness is a reading, and only the first is a gate's business.
+
+A path written into running prose without backticks is not read at all. Matching one would report every sentence that happens to name a file, and the backticks are what separate a reference a reader follows from a name in a sentence.
+
+A folder or a path carrying no extension is declined rather than guessed at, which is stated above as the cost of the test that carries the separation.
+
+A glob under `governance/rules/` is not read, and a glob that resolves while reaching none of the work it was scoped at is a reading rather than a resolution. Both are stated above.
+
+## Exit codes
+
+Exit codes are `0` when every citation resolves or is excused and every glob read matches, `1` for a refusal, and `2` for at least one cited path reaching nothing or one glob matching nothing. It refuses a tree holding neither rule corpus, since a tree with no rules passes each of its zero rules, and a `git check-ignore` read that fails.
+
+This gates, and `bun run check` runs it as the `Rule citations` stage. The sibling sweeps report rather than gate because a value appears for reasons unrelated to the convention, so their output is a reading. A path resolving to nothing carries no judgment: either the file is there or the citation is stale, and the two classes where absence is correct are separated before the verdict rather than left for a reader to settle. The corpus is clean at the commit this shipped on, so the gate starts green and stays that way until something breaks.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the JSON record's `citations` array and filter on `status` rather than the exit when a skill consumes this.

package/package.json

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

package/scripts/core/verify.sh

@@ -387,6 +387,22 @@ main() {
   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"
 
+  # A rule citing a file that moved fails silently. The consumed-copy drift
+  # stage passes an authored rule and its copy that are wrong together, and
+  # nothing else resolves the path until a session opens it, which is how
+  # `561-teach.md` shipped a `references/glossary.md` that had never existed. A
+  # rule whose frontmatter glob names a directory that moved fails the same way,
+  # by never firing again.
+  #
+  # This gates for the reason the stage above gates: a path resolving to
+  # nothing carries no judgment. The classes where absence is correct, a path
+  # the rule declares in its own frontmatter and one git ignores, are separated
+  # inside the verb rather than left as a threshold here. Globs are read under
+  # `internal/rules/` alone, since a shipped rule's glob names a target's shape.
+  log_step "Rule citations"
+  run_check "cd $PROJECT_ROOT && bun src/cli.ts gov citations" "A path a rule cites, or an internal frontmatter glob, does not resolve. Run bun src/cli.ts gov citations."
+  log_info "Rule citations resolve"
+
   # A banned character, word, or spelling is a fact rather than a threshold, so
   # it fails the push while bullet, paragraph, and depth weight stay advisory
   # for the reason the stage above leaves its own thresholds so.

package/src/commands/gov.ts

@@ -30,6 +30,14 @@ import {
   SEED_REL,
   SHIPPED_SKILLS_REL,
 } from '@/gov/restated'
+import {
+  CITATION_MARKER,
+  type CitationReport,
+  GLOB_CORPUS,
+  readCitations,
+  RULE_DIRS,
+  type RuleCitation,
+} from '@/gov/citations'
 import {
   readSuperseded,
   SUPERSEDED_MARKER,
@@ -85,6 +93,11 @@ interface SupersededOptions {
   readonly json?: boolean
 }
 
+interface CitationsOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 interface RestatedOptions {
   readonly root?: string
   readonly json?: boolean
@@ -348,6 +361,86 @@ export function register(program: Command): void {
       },
     )
 
+  gov
+    .command('citations')
+    .description(
+      'Resolve every path a rule cites and every internal frontmatter glob, naming the ones reaching nothing',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads bodies across ${RULE_DIRS.join(' and ')}, and frontmatter globs`,
+        `under ${GLOB_CORPUS} alone. A rule citing a file that moved fails`,
+        'silently: nothing resolves the path until a session opens it, and the',
+        'drift check beside this one passes an authored rule and its consumed',
+        'copy that are wrong together. A rule whose glob names a directory that',
+        'moved fails the same way, by never firing again.',
+        '',
+        'This gates, unlike the superseded sweep beside it. A path resolving to',
+        'nothing carries no judgment, and the classes where absence is correct',
+        'are separated before the verdict rather than left for a reader.',
+        '',
+        `Frontmatter globs read under ${GLOB_CORPUS} and nowhere else. A rule`,
+        `under ${RULE_DIRS[0]} installs into a target and its paths: entries`,
+        "name that project's shape, so src/pages/** in the Astro rule cannot be",
+        'told by pattern from a path here. Measured over that corpus, 32 of 72',
+        'globs match nothing in this tree and every one of them is correct, so',
+        'gating them would ship an exemption list the length of the corpus. The',
+        'internal corpus ships nowhere, which makes the tree it governs the tree',
+        'present and the question answerable.',
+        '',
+        'Forms read, with where each resolves:',
+        '  standard  aitk standards <name> , against standards/ alone, which',
+        '            is where the verb itself looks. internal/standards/ is not',
+        '            tried, since a name resolving only there refuses for the',
+        '            session that opens the citation.',
+        '  path      a backticked path carrying a directory segment and a file',
+        '            extension, against the root',
+        "  sibling   a bare <nnn>-<slug>.md , against the citing rule's folder",
+        '',
+        'Not read, each a shape the corpus writes and none of them a citation:',
+        '  a placeholder or glob segment, which describes a shape rather than',
+        '  naming a file, such as .claude/context/<domain>.md or app/**/route.ts',
+        '  a bare filename naming a convention, such as route.ts or manifest.toml',
+        '  a span carrying no file extension, which is a folder or a module',
+        '  specifier, such as src/pages/ , next/font , or claude/standards',
+        '  a fenced block, which displays a path rather than pointing at one',
+        '',
+        'Exempt, reported by name rather than dropped:',
+        '  governed  the citing rule spells the path in its own frontmatter, so',
+        '            it names a target artifact rather than a file here. A glob',
+        '            never exempts, since a typo inside one is the defect.',
+        '  ignored   git ignores the path, which is session scratch a clone is',
+        '            not expected to hold',
+        `  exempt    the line carries a \`${CITATION_MARKER}: <reason>\` marker`,
+        '            on itself or the one above',
+        '',
+        'Blind spots: a citation that resolves and points at the wrong file, a',
+        'path written without backticks, a folder or a path carrying no extension,',
+        'which this declines rather than guesses at, and a glob that matches real',
+        'files while reaching none of the work it was scoped at, which is a',
+        'reading rather than a resolution.',
+        '',
+        'Exit codes:',
+        '  0  every citation resolves or is exempt, and every glob read matches',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one cited path resolves to nothing, or one glob matches',
+        '     nothing in this tree',
+        '',
+        'Examples:',
+        '  aitk gov citations',
+        '  aitk gov citations --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: CitationsOptions) => {
+      process.exitCode = await runCitations(opts)
+    })
+
   gov
     .command('restated')
     .description(
@@ -529,6 +622,160 @@ async function runSuperseded(
   return report.findings.length > 0 ? 2 : 0
 }
 
+/**
+ * Gates, unlike `superseded` and `test-order` above. The classes where a path
+ * reaching nothing is correct are separated inside the sweep, which is what
+ * leaves the remainder a defect with no judgment in it, so a finding fails the
+ * push rather than asking a reader to weigh it.
+ */
+async function runCitations(opts: CitationsOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = await readCitations(root)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('aitk gov citations')
+    logStep('Refused')
+    logError(report.reason)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  const dead = report.citations.filter((citation) => citation.status === 'dead')
+  const unmatched = report.globs.filter((glob) => !glob.matched)
+  reportCitations(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ok: true, root, ...report })}\n`)
+  }
+
+  return dead.length + unmatched.length > 0 ? 2 : 0
+}
+
+function describeCitation(citation: RuleCitation): string {
+  const tried = citation.candidates.join(', ')
+  return `[${citation.form}] ${citation.file}:${citation.line}: ${citation.cited} reaches nothing at ${tried}`
+}
+
+/**
+ * Named rather than counted, matching the exempt section of the sweep beside
+ * this one. An exemption is a judgment the tree recorded, and a reader weighing
+ * this report has to be able to reach the line that carries it.
+ */
+function reportExcused(
+  citations: readonly RuleCitation[],
+  status: RuleCitation['status'],
+  label: string,
+  empty: string,
+): void {
+  const excused = citations.filter((citation) => citation.status === status)
+
+  logStep(label)
+  if (excused.length === 0) {
+    logInfo(empty)
+    return
+  }
+
+  for (const citation of excused) {
+    logInfo(`${citation.file}:${citation.line}: ${citation.cited}`)
+  }
+}
+
+/**
+ * Names the corpus on every run, clean or not.
+ *
+ * A section reporting that every glob resolves, over a corpus the reader
+ * assumes is both of them, says the shipped rules were checked and they were
+ * not. The scope is the finding here as much as the count is.
+ */
+function reportGlobs(
+  report: Extract<CitationReport, { kind: 'measured' }>,
+): void {
+  const unmatched = report.globs.filter((glob) => !glob.matched)
+
+  logStep('Frontmatter globs')
+  logInfo(`${report.globs.length} globs read, under ${GLOB_CORPUS} alone`)
+
+  if (unmatched.length === 0) {
+    logInfo('every glob matches a file in this tree')
+  } else {
+    for (const glob of unmatched) {
+      logError(
+        `${glob.file}:${glob.line}: ${glob.glob} matches nothing, so the rule never fires`,
+      )
+    }
+  }
+
+  logInfo(
+    `not read: a glob under ${RULE_DIRS[0]}, which names the shape a target holds rather than this tree, and a glob matching real files while reaching none of the work it was scoped at`,
+  )
+}
+
+function reportCitations(
+  report: Extract<CitationReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov citations')
+
+  logStep('Sweep')
+  logInfo(`${report.rules} rules under ${RULE_DIRS.join(' and ')} in ${root}`)
+
+  const counted = new Map<RuleCitation['form'], number>()
+  for (const citation of report.citations) {
+    counted.set(citation.form, (counted.get(citation.form) ?? 0) + 1)
+  }
+  logInfo(
+    report.citations.length === 0
+      ? 'no citation in either corpus'
+      : `${report.citations.length} citations: ${[...counted]
+          .map(([form, count]) => `${count} ${form}`)
+          .join(', ')}`,
+  )
+
+  const dead = report.citations.filter((citation) => citation.status === 'dead')
+
+  logStep('Unresolved')
+  if (dead.length === 0) {
+    logInfo('every cited path resolves')
+  } else {
+    for (const citation of dead) logError(describeCitation(citation))
+  }
+
+  reportGlobs(report)
+
+  reportExcused(
+    report.citations,
+    'governed',
+    'Governed',
+    'no rule cites a path it declares in its own frontmatter',
+  )
+  reportExcused(
+    report.citations,
+    'ignored',
+    'Ignored',
+    'no rule cites a path git ignores',
+  )
+  reportExcused(
+    report.citations,
+    'exempt',
+    'Exempt',
+    `no line carries a ${CITATION_MARKER} marker`,
+  )
+
+  logInfo(
+    'not read: a citation that resolves and points at the wrong file, a path written without backticks, and a folder or a path carrying no extension',
+  )
+
+  outro()
+}
+
 function describeHit(hit: SupersededHit): string {
   const note = hit.carriesReplacement
     ? ' (the replacement is on this line)'

package/src/gov/citations.ts

@@ -0,0 +1,514 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { $ } from 'bun'
+import { isMarked } from '@/exempt-marker'
+import { gitEnv } from '@/git-env'
+import { listRuleFiles } from '@/gov/payload'
+import { parseFrontmatter } from '@/indexes/frontmatter'
+
+/**
+ * The inline token exempting one line from this sweep, shaped on the
+ * `aitk-allow-superseded` precedent and read by the same two-line rule.
+ *
+ * Everything the classifier below can separate mechanically is separated
+ * there. This is for the residue: a line whose path is written as a reference
+ * and is correct in naming something absent, for a reason a later reader has
+ * to be able to weigh. A bare token names no reason, so it mutes nothing.
+ */
+export const CITATION_MARKER = 'aitk-allow-citation'
+
+/** The two rule corpora, authored here and read from the repository root. */
+export const RULE_DIRS: readonly string[] = [
+  join('governance', 'rules'),
+  join('internal', 'rules'),
+]
+
+/**
+ * The corpus whose frontmatter globs resolve against this tree.
+ *
+ * Bodies are read across both corpora and globs across this one alone. A rule
+ * under `governance/rules/` installs into a target and its `paths:` entries
+ * name that project's shape, which is why 32 of the 72 globs there match
+ * nothing here and every one of them is correct: `src/pages/**` in the Astro
+ * rule is indistinguishable by pattern from a path this repository might hold.
+ * Gating on them would ship a permanent exemption list the length of the
+ * corpus. The internal corpus ships nowhere, so the tree it governs is the
+ * tree present and a glob matching nothing there is a rule that stopped
+ * firing.
+ */
+export const GLOB_CORPUS = join('internal', 'rules')
+
+/**
+ * How the citation was written, kept on the finding because the three resolve
+ * against different roots and a reader repairing one needs to know which.
+ *
+ * `standard` is the live form, carried by 20 rules. `path` is a backticked
+ * repository path. `sibling` is a rule naming another rule by filename alone,
+ * which resolves inside the folder the citing rule sits in.
+ */
+export type CitationForm = 'path' | 'standard' | 'sibling'
+
+/**
+ * What the sweep decided about one citation.
+ *
+ * `governed` and `ignored` are the two classes where a path reaching nothing is
+ * correct rather than stale, and they are named rather than dropped so the
+ * report states what it declined to judge. `exempt` is the marker.
+ */
+export type CitationStatus =
+  | 'resolved'
+  | 'governed'
+  | 'ignored'
+  | 'exempt'
+  | 'dead'
+
+export interface RuleCitation {
+  /** The citing rule, relative to the root that was swept. */
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly form: CitationForm
+  /** The citation exactly as the rule wrote it. */
+  readonly cited: string
+  /** Repository-relative paths tried, in order, so a finding names its net. */
+  readonly candidates: readonly string[]
+  /** Which candidate answered, absent when none did. */
+  readonly resolved: string | undefined
+  readonly status: CitationStatus
+  readonly preview: string
+}
+
+/**
+ * One `paths:` entry from a rule's frontmatter, resolved against the tree.
+ *
+ * Only the internal corpus is read. A rule shipping to a target declares the
+ * shape that target holds, so its globs answer about a tree that is not this
+ * one, which `GLOB_CORPUS` states and the report repeats on every run.
+ */
+export interface RuleGlob {
+  readonly file: string
+  readonly line: number
+  readonly glob: string
+  readonly matched: boolean
+}
+
+export type CitationReport =
+  | {
+      readonly kind: 'measured'
+      /** Rule files opened, which is what the verdict covers. */
+      readonly rules: number
+      readonly citations: readonly RuleCitation[]
+      /** Frontmatter globs read, from `GLOB_CORPUS` alone. */
+      readonly globs: readonly RuleGlob[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+/**
+ * The longest preview a finding carries, matching the superseded sweep beside
+ * it. A rule bullet runs long and the report prints one line per citation.
+ */
+const PREVIEW_LIMIT = 200
+
+const FENCE = /^\s*(?:```|~~~)/
+
+const FRONTMATTER_DELIMITER = /^---\s*$/
+
+/**
+ * A backticked span, which is the only carrier a rule writes a citation in. No
+ * rule in either corpus uses a markdown link, and matching running prose would
+ * report every sentence that happens to name a file.
+ */
+const BACKTICKED = /`([^`\n]+)`/g
+
+/**
+ * The verb form, with the name captured. A leading letter or digit is required,
+ * which is what leaves `aitk standards <name>` unmatched: that line teaches the
+ * form rather than citing a standard, and it is the only one in either corpus.
+ */
+const STANDARD_CALL = /aitk standards ([A-Za-z0-9][A-Za-z0-9._-]*)/g
+
+/** A rule filename, which is how a rule names a sibling with no folder around it. */
+const SIBLING_RULE = /^\d{3}-[a-z0-9-]+\.md$/
+
+/**
+ * A character that puts the span outside this repository, or outside paths
+ * altogether.
+ *
+ * `<` and `$` are the placeholder forms, `*` is a glob, and both describe a
+ * shape rather than name a file. The rest are anchors nothing here resolves
+ * against: an absolute path, a home path, a module alias, a URL scheme.
+ */
+function isNotRepositoryPath(span: string): boolean {
+  if (/[\s<>$*|]/.test(span)) return true
+  if (span.includes('://')) return true
+  return /^[/~@#!]/.test(span)
+}
+
+/**
+ * Whether the span's last segment carries a file extension.
+ *
+ * This is what separates a citation from the folder and module conventions the
+ * corpus is full of. `next/font`, `try/except`, `react-hooks/set-state-in-effect`,
+ * and `oven-sh/setup-bun@v2` all carry a slash and name no file, and a trailing
+ * slash is a folder rather than a document. The cost is that `claude/standards`
+ * is a real path this declines to check, which is the bound the report states.
+ */
+function namesAFile(span: string): boolean {
+  if (span.endsWith('/')) return false
+  const segment = span.slice(span.lastIndexOf('/') + 1)
+  return /\.[A-Za-z0-9]+$/.test(segment)
+}
+
+/**
+ * Which form the span is written in, or nothing when it names no file this
+ * sweep can resolve.
+ *
+ * The whole span is classified rather than a trailing pattern inside it.
+ * Extracting `standards/tooling-reference.md` out of
+ * `internal/standards/tooling-reference.md` and resolving that against the
+ * standards root manufactures a dead citation out of a file that exists, which
+ * a session measuring this corpus did before the check was written.
+ */
+export function classifySpan(span: string): CitationForm | undefined {
+  if (isNotRepositoryPath(span)) return undefined
+  if (!namesAFile(span)) return undefined
+  if (span.includes('/')) return 'path'
+  return SIBLING_RULE.test(span) ? 'sibling' : undefined
+}
+
+/**
+ * Where a citation could answer, which is wherever the reader's own tools look
+ * and nowhere else.
+ *
+ * A standard name takes the authoring root alone, matching `standardRoots` in
+ * `@/standards/read`, which reads `standards/` at the working root and then the
+ * package corpus. This verb refuses a tree holding no rule corpus, so it runs
+ * only where those two roots are one directory. `internal/standards/` is
+ * deliberately absent: `aitk standards <name>` never reaches it, so admitting it
+ * here would pass a citation that refuses for the session opening it, which is a
+ * gate failing open.
+ *
+ * A sibling resolves inside the folder the citing rule sits in, since that is
+ * the only place a bare rule filename means anything.
+ */
+function candidatesFor(
+  form: CitationForm,
+  cited: string,
+  ruleFile: string,
+): string[] {
+  if (form === 'standard') return [join('standards', `${cited}.md`)]
+  if (form === 'sibling') return [join(dirname(ruleFile), cited)]
+  return [cited]
+}
+
+interface RawCitation {
+  readonly line: number
+  readonly form: CitationForm
+  readonly cited: string
+  readonly preview: string
+  readonly marked: boolean
+}
+
+/**
+ * Every citation one rule body carries.
+ *
+ * The frontmatter block is skipped, since a `paths:` glob declares what the
+ * rule governs rather than what it points a reader at, and the two questions
+ * resolve against different trees. Fenced blocks are skipped for the reason the
+ * marker exists: a fenced example displays a path rather than citing one. No
+ * rule in either corpus opens a fence today, so this is a floor rather than a
+ * filter over anything present.
+ */
+export function collectCitations(text: string): RawCitation[] {
+  const lines = text.split('\n')
+  const found: RawCitation[] = []
+  let fenced = false
+  let inFrontmatter = FRONTMATTER_DELIMITER.test(lines[0] ?? '')
+
+  for (const [index, line] of lines.entries()) {
+    if (inFrontmatter) {
+      if (index > 0 && FRONTMATTER_DELIMITER.test(line)) inFrontmatter = false
+      continue
+    }
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const trimmed = line.trim()
+    const preview =
+      trimmed.length > PREVIEW_LIMIT
+        ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
+        : trimmed
+    const marked = isMarked(lines, index, CITATION_MARKER)
+
+    for (const match of line.matchAll(STANDARD_CALL)) {
+      found.push({
+        line: index + 1,
+        form: 'standard',
+        cited: match[1] ?? '',
+        preview,
+        marked,
+      })
+    }
+
+    for (const match of line.matchAll(BACKTICKED)) {
+      const span = match[1] ?? ''
+      const form = classifySpan(span)
+      if (form === undefined) continue
+      found.push({ line: index + 1, form, cited: span, preview, marked })
+    }
+  }
+
+  return found
+}
+
+/**
+ * The paths one rule declares in its own frontmatter.
+ *
+ * A rule spelling a whole path there is declaring that exact artifact, and a
+ * body line naming it again is naming what the rule governs rather than
+ * pointing a reader somewhere. `governance/rules/claude/560-diagrams.md` tells
+ * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
+ * is correctly absent from this tree and correctly named in the rule.
+ */
+function governedPaths(text: string): string[] {
+  const parsed = parseFrontmatter(text)
+  const paths = parsed?.fields.paths
+  if (!Array.isArray(paths)) return []
+  return paths.filter((entry): entry is string => typeof entry === 'string')
+}
+
+/**
+ * Exact declarations only, never a glob match against one.
+ *
+ * A glob declares a shape rather than an artifact, so a body path sitting
+ * inside one is still a citation and a stale one is still a defect. Matching
+ * the glob would exempt a rule scoped at `docs/**` citing a
+ * `docs/agents/renamed.md` that moved, which is the class this check exists
+ * to catch.
+ */
+function isGoverned(cited: string, declared: readonly string[]): boolean {
+  return declared.includes(cited)
+}
+
+/**
+ * A `paths:` list entry, with the glob captured and its quoting dropped.
+ *
+ * Anchored on the entry shape rather than searched for as a substring. A bare
+ * scan for the glob text finds it in the `description:` line first wherever a
+ * rule names what it governs in prose, which is how `596-claude-md.md` reported
+ * its `CLAUDE.md` glob against line 2 instead of line 4.
+ */
+const LIST_ENTRY = /^\s*-\s*(?:'([^']*)'|"([^"]*)"|(\S.*?))\s*$/
+
+/**
+ * Where each declared glob sits, so a finding names a line a reader can click.
+ *
+ * The values come from the YAML parse and the line numbers from a scan of the
+ * frontmatter block alone, rather than from a second parse of the list syntax.
+ * A quoted entry, a bare one, and a flow sequence all reach the parse
+ * identically, and only the first two are what this corpus writes, so a flow
+ * sequence resolves its value and reports no line.
+ */
+function locateGlobs(text: string): { line: number; glob: string }[] {
+  const declared = governedPaths(text)
+  if (declared.length === 0) return []
+
+  const lines = text.split('\n')
+  const close = lines.findIndex(
+    (line, index) => index > 0 && FRONTMATTER_DELIMITER.test(line),
+  )
+  const block = close === -1 ? lines : lines.slice(0, close)
+  const taken = new Set<number>()
+
+  return declared.map((glob) => {
+    const at = block.findIndex((line, index) => {
+      if (taken.has(index)) return false
+      const entry = line.match(LIST_ENTRY)
+      return entry !== null && (entry[1] ?? entry[2] ?? entry[3]) === glob
+    })
+    if (at !== -1) taken.add(at)
+    return { line: at + 1, glob }
+  })
+}
+
+/**
+ * Whether the glob matches a file present in this tree.
+ *
+ * Read only for `internal/rules/`. A shipped rule's glob names the shape a
+ * target holds, so `src/pages/**` in the Astro rule is indistinguishable by
+ * pattern from a path here and resolving it would report 32 of 72 correct
+ * globs as defects. The internal corpus ships nowhere, which makes the tree it
+ * governs the tree present and the question answerable.
+ */
+function globMatches(root: string, glob: string): boolean {
+  const scan = new Bun.Glob(glob).scanSync({
+    cwd: root,
+    onlyFiles: true,
+    dot: true,
+  })
+  for (const _ of scan) return true
+  return false
+}
+
+/**
+ * Which of `paths` git ignores, or nothing when git could not answer.
+ *
+ * Session scratch is the class this reaches. `.claude/tasks/index.md` is real
+ * in a live project, absent from a fresh clone and from every linked worktree,
+ * and a rule naming it is right either way. Resolving against the filesystem
+ * alone would make the verdict depend on which tree the check ran in.
+ *
+ * `git check-ignore` exits 1 when nothing matches, which is a clean answer
+ * rather than a failure, so only a higher code is read as one.
+ */
+async function readIgnored(
+  root: string,
+  paths: readonly string[],
+): Promise<Set<string> | undefined> {
+  if (paths.length === 0) return new Set()
+
+  const input = Buffer.from(`${paths.join('\n')}\n`)
+  const result = await $`git -C ${root} check-ignore --stdin < ${input}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+
+  if (result.exitCode > 1) return undefined
+  return new Set(result.text().split('\n').filter(Boolean))
+}
+
+/**
+ * Resolves every path the two rule corpora cite and names the ones reaching
+ * nothing, plus every frontmatter glob under `GLOB_CORPUS`.
+ *
+ * Two questions rather than one, because they fail the same way. A citation
+ * broken by a move sends a reader to an absence, and a glob broken by a move
+ * stops the rule firing at all, and neither says anything when it happens. One
+ * stage reads both rather than two reading one file each.
+ *
+ * This gates rather than reports, unlike the superseded sweep it sits beside. A
+ * path resolving to nothing carries no judgment: either the file is there or the
+ * citation is stale, and the classes where absence is correct are separated
+ * before the verdict rather than left for a reader to settle.
+ *
+ * What it cannot see is a citation that resolves and points somewhere wrong,
+ * a path written without backticks, a folder or module specifier carrying no
+ * extension, which `namesAFile` declines rather than guessing at, and a glob
+ * that matches real files while reaching none of the work it was scoped at.
+ */
+export async function readCitations(root: string): Promise<CitationReport> {
+  const dirs = RULE_DIRS.map((rel) => ({
+    rel,
+    abs: resolve(root, rel),
+  })).filter((dir) => existsSync(dir.abs))
+
+  if (dirs.length === 0) {
+    return {
+      kind: 'unreadable',
+      reason: `No rule corpus under ${root}. A tree holding neither ${RULE_DIRS.join(' nor ')} passes each of its zero rules, so it refuses rather than reporting clean.`,
+    }
+  }
+
+  const citations: RuleCitation[] = []
+  const globs: RuleGlob[] = []
+  let rules = 0
+
+  for (const dir of dirs) {
+    for (const abs of listRuleFiles(dir.abs)) {
+      const file = join(dir.rel, abs.slice(dir.abs.length + 1))
+
+      let text: string
+      try {
+        text = await readFile(abs, 'utf8')
+      } catch {
+        // A rule git listed and the filesystem will not open is a file removed
+        // since the glob answered. Skipping it under-reports rather than
+        // failing a push on a race.
+        continue
+      }
+
+      rules += 1
+      const declared = governedPaths(text)
+
+      if (dir.rel === GLOB_CORPUS) {
+        for (const { line, glob } of locateGlobs(text)) {
+          globs.push({ file, line, glob, matched: globMatches(root, glob) })
+        }
+      }
+
+      for (const raw of collectCitations(text)) {
+        const candidates = candidatesFor(raw.form, raw.cited, file)
+        const resolved = candidates.find((path) =>
+          existsSync(resolve(root, path)),
+        )
+
+        citations.push({
+          file,
+          line: raw.line,
+          form: raw.form,
+          cited: raw.cited,
+          candidates,
+          resolved,
+          status: classifyStatus(raw, resolved, declared),
+          preview: raw.preview,
+        })
+      }
+    }
+  }
+
+  return applyIgnored(root, { kind: 'measured', rules, citations, globs })
+}
+
+function classifyStatus(
+  raw: RawCitation,
+  resolved: string | undefined,
+  declared: readonly string[],
+): CitationStatus {
+  if (resolved !== undefined) return 'resolved'
+  if (raw.marked) return 'exempt'
+  if (raw.form === 'path' && isGoverned(raw.cited, declared)) return 'governed'
+  return 'dead'
+}
+
+/**
+ * Moves the unresolved paths git ignores out of the dead set.
+ *
+ * Batched into one call over the whole sweep rather than one per citation, and
+ * skipped outright when nothing is unresolved, so a clean corpus spawns no git
+ * at all. A read git cannot answer refuses, since treating it as "nothing is
+ * ignored" would fail a push over session scratch that was never in the tree.
+ */
+async function applyIgnored(
+  root: string,
+  measured: Extract<CitationReport, { kind: 'measured' }>,
+): Promise<CitationReport> {
+  const pending = measured.citations.filter(
+    (citation) => citation.status === 'dead' && citation.form === 'path',
+  )
+  if (pending.length === 0) return measured
+
+  const ignored = await readIgnored(
+    root,
+    pending.map((citation) => citation.cited),
+  )
+
+  if (ignored === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Git could not say which of ${pending.length} unresolved paths it ignores under ${root}. Session scratch is absent from a fresh clone and correctly cited anyway, so an unreadable answer refuses rather than reporting those paths dead.`,
+    }
+  }
+
+  return {
+    ...measured,
+    citations: measured.citations.map((citation) =>
+      citation.status === 'dead' && ignored.has(citation.cited)
+        ? { ...citation, status: 'ignored' as const }
+        : citation,
+    ),
+  }
+}