@erclx/aitk 3.52.1 → 3.53.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.52.1",
+  "version": "3.53.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-pr-review/SKILL.md

@@ -117,6 +117,14 @@ Test every unchecked box against the testing discipline in `${CLAUDE_SKILL_DIR}/
 
 Test every ticked box too, bounded to one naming a file or a command. Confirm what it names still exists at `<headRefOid>`, `git show <headRefOid>:<path>` for a file or `git grep <command> <headRefOid>` for a command, rather than re-running what it claims. A box naming neither stays untested, since nothing here can confirm a claim carrying no artifact. A box ticked before a later commit removed or replaced what it names is a `should-fix` finding on the body itself, filed under a `**PR body**` block ahead of the file blocks, since what it corrupts is the merge record rather than a file in the diff.
 
+Test what `## Key Changes` claims against the diff it describes, with `aitk pr key-changes <number> --json`. This repository squash-merges, so that section becomes the commit message and the record on the trunk once the branch is gone, which is the same thing a stale ticked box corrupts. Branch on the record rather than on the exit code, which a shell function wrapping `aitk` can flatten to zero.
+
+Read `unmet` as a `should-fix` finding under the same `**PR body**` block the stale box takes, one entry per path, quoting the bullet the record carries on `preview` and naming the `head` the comparison ran at. Read the bullet before filing it, since one class survives the reader: a bullet citing where something is defined while claiming an edit elsewhere, which puts a real path in the claim region and points the change at a locative the path does not name. Report that as the class rather than as a stale claim. A body is edited between pushes, so the reading is true at that commit and can be false a minute later. Read `unnamed` as a question rather than a finding, since the class covers a real omission and equally a lockfile, a generated asset, or a regenerated index that earns no bullet, and raise it only where a reader would want the bullet. Report `unresolved` nowhere: a path written partially was judged in neither direction and says nothing about the body.
+
+A `reason` of `no-claims` means the reader resolved no path out of a section that exists, which is the extractor failing over prose rather than the body being wrong. Say so and raise nothing. `no-section` is the body carrying no such heading, which is a finding only where the pull request template asks for one.
+
+Compose this on the body read Step 4 already performs rather than opening a second one. That step scans the title and body for a leaked phase label, and both reads answer from the same text at the same head.
+
 Ask rather than grade. Whether a human is genuinely required is a reading the branch author may hold a reason this session cannot see, so the question carries no severity and enters no count. What it does carry is the heading and the dispatch, on the rule Step 4 states, because a question the author never receives corrects nothing and the author is the only party who can answer it. Answering it closes it, and the answer may be that the requirement holds.
 
 Read `## For the reviewer` the same way, bounded to the bullets under that heading rather than the Summary or the Technical Context around it. Those two carry the author's argument for the change, and reading them while judging it is most of what an independent pass exists to avoid, so the read stops at the section itself.

package/docs/agents/commands.md

@@ -61,6 +61,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
 | `aitk labels scan`         | Fail a pull request whose title or body carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--json`)          |
 | `aitk autoship classify`   | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
+| `aitk pr key-changes`      | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
 | `aitk census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                                |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |

package/docs/agents/index.md

@@ -22,6 +22,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
+- [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and why they are graded apart, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 - [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain

package/docs/agents/key-changes.md

@@ -0,0 +1,103 @@
+---
+title: Key Changes bijection
+description: Comparing the files a pull request body's Key Changes names against its own diff, the two directions and why they are graded apart, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+---
+
+# Key Changes bijection
+
+`aitk pr key-changes` reads the `## Key Changes` section of a pull request body, lifts the paths its bullets claim, and compares that set against the files the pull request actually changed. This repository squash-merges, so the body becomes the commit message and the record on the trunk once the branch is gone.
+
+```bash
+aitk pr key-changes
+aitk pr key-changes 1265 --json
+aitk pr key-changes --body .claude/.tmp/pr/body.md --base origin/main
+```
+
+The positional is the pull request to read, defaulting to the one open on this branch.
+
+| Option          | Behavior                                                           |
+| --------------- | ------------------------------------------------------------------ |
+| `--body <path>` | Read the body from a file, taking the changed set from git instead |
+| `--base <ref>`  | Far side of the range when `--body` supplies the body              |
+| `--root <path>` | Repository to read, defaulting to the cwd                          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame         |
+
+`--body` decides where both halves come from, so a number passed beside it is never read. The body comes off disk and the changed set from the local range, which is the shape a fixture and a body still being drafted both need.
+
+Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
+
+That view caps its file list at 100 rows and says nothing about having done so, which was measured against `#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+
+## The two directions
+
+They are reported apart because they want different tolerances.
+
+- **`unmet`** is a whole path the body claims and the diff does not carry. This is the graded direction and it sets the exit code. A bullet naming an untouched file is wrong more often than not, and it corrupts the record that reaches the trunk.
+- **`unnamed`** is a changed file no bullet reached. Reported with no grade, since the class covers a real omission and equally a lockfile, a generated asset, or a regenerated index that earns no bullet. Grading it would fire on nearly every branch.
+- **`unresolved`** is a path written partially, such as `claude-worker/SKILL.md` for a file under `claude/skills/`. It is judged in neither direction.
+
+A partial path can credit a changed file and can never accuse one. Nothing separates a path written short from a path written wrong, so the asymmetry keeps the accusing direction to spans the tree can anchor.
+
+## What counts as a claim
+
+Only `## Key Changes` is read. `## Technical Context` legitimately names files a branch never touched, such as an install stamp inside a target, so widening the read manufactures a finding out of every argument an author made for the change.
+
+Inside the section, the claim region of a bullet ends at its first comma outside a backticked span. That one lever was chosen by measurement. Over the 23 merged pull requests in this repository carrying the section, reading whole bullets reported 16 paths as claimed-but-untouched and every one was a file the body named for context. Cutting at the comma left 110 claims of the original 149 and took the false reports to 2. A list of sixteen clause-opening words tried beside it removed nothing the comma had not already removed, because this corpus punctuates every one of them.
+
+A span inside the claim region has to survive all of these:
+
+| Rule                                              | What it keeps out                                      |
+| ------------------------------------------------- | ------------------------------------------------------ |
+| No whitespace, `<`, `>`, `$`, `*`, `\|`, `?`, `^` | A backticked command, a placeholder, a glob, a pattern |
+| No `://` and no leading `/`, `~`, `@`, `#`, `!`   | A URL, an absolute path, a module alias                |
+| Contains `/`                                      | A bare filename with no folder around it               |
+| Extension starts with a letter, or ends with `/`  | A dotted number such as an address                     |
+| Not a single top-level folder                     | `src/`, which nobody claims to have rewritten whole    |
+| A `file:line` span leads its bullet               | A citation into a file the bullet is describing        |
+| The region carries no no-change marker            | A bullet recording a file it deliberately left alone   |
+
+The last three rows earn their place from the corpus rather than from a rule. Every body that spelled a lone top-level folder was naming where something lives, and a line citation that follows another claim in the same bullet points into the file being described rather than naming a second one. A line citation leading its bullet stays a claim, which is how a body names the exact line it rewrote.
+
+The no-change marker is the one rule the region cut cannot substitute for. A body writes "Leave `x` untouched, since the decision keeps it" to record a change it declined, and the path sits ahead of the first comma, so a stricter cut would not reach it and a looser one would find more. Since `keep` and `leave` each open a real claim often enough, the marker decides it rather than the leading verb. Three words carry the set: `untouched`, `unchanged`, and `as written`. `in place` was measured and dropped, because rewriting a file in place is an ordinary claim, and `no other line` was dropped because a correct bullet writes "as one insertion that touches no other line" about a change it did make. `alone` shipped in the set too, until review found every corpus occurrence sitting past the first comma, where the cut already excludes it, so the word voided no true claim there. Restrictive use is the more common one in this repository's own prose, and a comma-free bullet exposed it: "Move the threshold read into `src/gate/stages.ts` alone" asserts an edit, and the marker voided it while the word was still in the set. Over the 40-pull-request corpus the rule still voids no true claim.
+
+A folder claim covers every changed file beneath it. A bare filename drops outright: resolved as a sibling of a path earlier in its bullet it produced seven wrong paths across this corpus against two right ones, because a compound bullet names a sibling folder as often as a sibling file.
+
+## Anchoring
+
+A claim is anchored when its first segment names a folder the tree holds. The roots come from the tracked file list joined with the first segment of every changed path, and the second half is what admits a folder the branch created. Reading the tree alone would mark every claim under a new top-level directory unanchored, and an unanchored claim never accuses, so the first branch to open one would lose the graded direction with nothing reporting it.
+
+## Exit codes and refusals
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| `0`  | every claimed path is in the diff                 |
+| `1`  | refused, with `reason` naming the cause           |
+| `2`  | at least one claimed path is absent from the diff |
+
+Branch on the record rather than on the exit code. A shell function wrapping `aitk` takes its status from whatever it runs last, so every non-zero exit can reach a caller as zero.
+
+Three refusals separate a clean pass from a read that produced nothing:
+
+- `no-section`. The body carries no such heading, so it claims nothing.
+- `no-claims`. The heading is there and no span resolved, which is the extractor failing over prose rather than the body being wrong. Nothing is raised.
+- `no-changes`. The pull request changed no files, so no claim has anything to answer.
+
+An empty extraction read as a clean pass is the failure shape this repository has recorded twice, which is why the middle one is its own reason rather than a zero count.
+
+`gh-missing`, `gh-failed`, `gh-truncated`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
+
+## What it was measured against
+
+Driven over the 40 most recent merged pull requests in this repository, 23 of which carry the section, the shipped verb reported zero unmet paths and one `no-claims` refusal. The naive extractor it replaced reported 16.
+
+The first body written after that corpus closed produced two, which is what the no-change marker and the open class above come from. One was the disclaiming bullet and the rule now covers it at no cost to the corpus. The other is the definition-site class, left open with the report naming it.
+
+The bound is that the corpus is one repository writing to one house style. A project that punctuates differently loses claims to the comma cut rather than gaining false ones, since every rule above drops rather than invents, so the check degrades toward silence rather than toward noise.
+
+What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, a path written without backticks, and a claim in a second coordinated clause after the comma. The last of those falls to the ungraded direction rather than out of the reading.
+
+One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
+
+## Where it runs
+
+`claude-pr-review` Step 3 calls it and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at.

package/docs/operating-model.md

@@ -73,6 +73,14 @@ They collide only if the worker also runs a deep pass. Keep the worker's review
 light and let the orchestrator own the deep, independent one. The human read at
 merge is the final gate. No layer repeats another.
 
+The orchestrator's pass also reads the pull request body against itself, which is
+a vantage the worker never has. This repository squash-merges, so the body
+becomes the commit message and the record on the trunk once the branch is gone.
+`aitk pr key-changes` compares the paths the body's Key Changes claims against
+its own changed-file list, and a claim the diff does not carry is a finding on
+the body rather than on a file. See
+[Key Changes bijection](agents/key-changes.md).
+
 ## The review channel
 
 Findings travel on the PR. `claude-pr-review` posts them there.

package/package.json

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

package/src/cli.ts

@@ -35,6 +35,7 @@ import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
 import { register as autoship } from '@/commands/autoship'
+import { register as pr } from '@/commands/pr'
 import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
@@ -83,6 +84,7 @@ function showHelp(): void {
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
+    `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
@@ -187,6 +189,7 @@ secrets(program)
 deps(program)
 labels(program)
 autoship(program)
+pr(program)
 census(program)
 audits(program)
 gate(program)

package/src/commands/pr.ts

@@ -0,0 +1,411 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  listChangedFiles,
+  listRepositoryFiles,
+  resolveBaseRef,
+} from '@/git-files'
+import {
+  type Bijection,
+  type BijectionRefusal,
+  compareKeyChanges,
+  treeRoots,
+} from '@/pr/bijection'
+import { KEY_CHANGES } from '@/pr/paths'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+const GH_TIMEOUT_MS = 30_000
+
+/** How many unnamed files the frame prints before it names a count instead. */
+const UNNAMED_PRINT_LIMIT = 10
+
+/**
+ * Where `gh pr view --json files` stops.
+ *
+ * It pages the underlying query once and returns at most this many rows with
+ * nothing on the record saying so, which was measured against `#1250`: the
+ * pull request carries 101 files and the view reports 100. A set silently one
+ * short is the worst input this comparison can take, since the missing file is
+ * exactly what a claim would then be accused of inventing.
+ */
+const GH_VIEW_FILE_CAP = 100
+
+interface KeyChangesOptions {
+  readonly body?: string
+  readonly base?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** Why the read produced no comparison, ahead of the ones the compare owns. */
+type SourceRefusal =
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'gh-truncated'
+  | 'unreadable-body'
+  | 'unreadable-tree'
+  | 'no-base'
+  | 'bad-base'
+  | 'unreadable-changes'
+
+type Refusal = SourceRefusal | BijectionRefusal
+
+/** What a reader does about each way this produced no reading. */
+const REFUSALS: Record<Refusal, string> = {
+  'gh-missing':
+    'gh is not on the path, so no pull request body could be read. Pass --body <path> to read one off disk instead.',
+  'gh-failed':
+    'gh could not answer for this branch. Name the pull request number, or pass --body <path>.',
+  'gh-truncated': `gh returned the first ${GH_VIEW_FILE_CAP} changed files and the paginated read that would complete the set failed, so a claim could be accused of naming a file this read never saw.`,
+  'unreadable-body': 'The file named by --body could not be read.',
+  'unreadable-tree':
+    'git could not list this repository, so no path could be judged whole rather than partial.',
+  'no-base': 'No base resolves against the trunk. Fetch origin or pass --base.',
+  'bad-base':
+    'The ref passed to --base resolves to no commit here. Pass one this tree carries.',
+  'unreadable-changes':
+    'git could not list what this branch changed, so the set is unknown.',
+  'no-section': `This body carries no ## ${KEY_CHANGES} section, so it claims nothing to compare.`,
+  'no-claims': `The ## ${KEY_CHANGES} section carried no path this reader could resolve. That is the extractor failing over prose rather than the body being wrong, so nothing is raised.`,
+  'no-changes':
+    'The pull request changed no files, so there is nothing for a claim to answer.',
+}
+
+export function register(program: Command): void {
+  const pr = program
+    .command('pr')
+    .description('Read a pull request body against the change it describes')
+    .helpOption('-h, --help', 'Show this help message')
+
+  pr.command('key-changes')
+    .description(
+      `Compare the files a body's ## ${KEY_CHANGES} names against its own diff`,
+    )
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--body <path>',
+      'Read the body from a file rather than the API, ignoring any number',
+    )
+    .option(
+      '--base <ref>',
+      'Far side of the range when --body supplies the body',
+    )
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'This repository squash-merges, so a pull request body becomes the commit',
+        'message and the record on the trunk once the branch is gone. A bullet',
+        'claiming a change nobody made corrupts that record, and a changed file no',
+        'bullet names leaves it incomplete.',
+        '',
+        'The two directions carry different weight:',
+        '  unmet      a whole path the body claims and the diff does not carry,',
+        '             which is the graded direction',
+        '  unnamed    a changed file no bullet reached, reported without a grade,',
+        '             since a lockfile or a generated asset earns no bullet',
+        '  unresolved a path written partially, which can credit a changed file',
+        '             and never accuse one',
+        '',
+        `Only ## ${KEY_CHANGES} is read. ## Technical Context legitimately names`,
+        'files a branch never touched, so widening the read manufactures findings.',
+        '',
+        'One class survives the reader: a bullet citing where something is defined',
+        'while claiming an edit elsewhere puts a real path in the claim region and',
+        'points the change at a locative the path does not name. Read the bullet on',
+        "the record's preview before filing an unmet path as a stale claim.",
+        '',
+        'Exit codes:',
+        '  0  every claimed path is in the diff',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one claimed path is absent from the diff',
+        '',
+        'Examples:',
+        '  aitk pr key-changes',
+        '  aitk pr key-changes 1265 --json',
+        '  aitk pr key-changes --body .claude/.tmp/body.md --base origin/main',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: KeyChangesOptions) => {
+      process.exitCode = await runKeyChanges(number, opts)
+    })
+}
+
+interface PullRequestRead {
+  readonly body: string
+  readonly changed: readonly string[]
+  readonly head: string | undefined
+  readonly number: number | undefined
+}
+
+type SourceRead =
+  | { readonly kind: 'read'; readonly source: PullRequestRead }
+  | { readonly kind: 'refused'; readonly reason: SourceRefusal }
+
+/**
+ * Reads the body and the changed set from the pull request the caller named,
+ * or from the one open on this branch.
+ *
+ * One call wherever the file list fits inside it. The body and the file list
+ * have to describe the same head, and reading them separately leaves a window
+ * where a push between them compares a body against another commit's files. A
+ * pull request at the view's cap takes the second read anyway, because a set
+ * short by an unknown number is worse than a set read a moment later.
+ */
+async function readFromApi(
+  cwd: string,
+  number: string | undefined,
+): Promise<SourceRead> {
+  if (Bun.which('gh') === null) {
+    return { kind: 'refused', reason: 'gh-missing' }
+  }
+
+  const args = ['pr', 'view']
+  if (number !== undefined) args.push(number)
+  args.push('--json', 'body,files,headRefOid,number')
+
+  try {
+    // See src/worktrees/reclaim.ts for why gh needs the stripped environment:
+    // it resolves its repository through the same variables git does and they
+    // beat `cwd`, so a run from inside a hook would answer for another
+    // repository and compare this branch's claims against its files.
+    const result = await execa('gh', args, {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+
+    const row = JSON.parse(result.stdout) as {
+      body?: string
+      files?: readonly { path: string }[]
+      headRefOid?: string
+      number?: number
+    }
+
+    const viewed = (row.files ?? []).map((file) => file.path)
+    const changed =
+      viewed.length < GH_VIEW_FILE_CAP || row.number === undefined
+        ? viewed
+        : await listFilesByPage(cwd, row.number)
+
+    if (changed === undefined) {
+      return { kind: 'refused', reason: 'gh-truncated' }
+    }
+
+    return {
+      kind: 'read',
+      source: {
+        body: row.body ?? '',
+        changed: [...changed].sort(),
+        head: row.headRefOid,
+        number: row.number,
+      },
+    }
+  } catch {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+}
+
+/**
+ * Every file a pull request changed, read through the paginated endpoint.
+ *
+ * Only reached when the view came back at the cap, since it costs a request per
+ * page and nearly every pull request here fits in one view. Returns undefined
+ * when the follow-up fails, which refuses rather than falling back to the
+ * capped set: a comparison run against a set known to be short would accuse a
+ * correct bullet of naming a file nobody changed.
+ */
+async function listFilesByPage(
+  cwd: string,
+  number: number,
+): Promise<string[] | undefined> {
+  try {
+    // See src/worktrees/reclaim.ts for why gh needs the stripped environment.
+    const result = await execa(
+      'gh',
+      [
+        'api',
+        '--paginate',
+        `repos/{owner}/{repo}/pulls/${number}/files`,
+        '--jq',
+        '.[].filename',
+      ],
+      { cwd, timeout: GH_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+    )
+    return result.stdout.split('\n').filter(Boolean)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads the body off disk and the changed set from git, which is the shape a
+ * fixture and a body still being drafted both need.
+ */
+async function readFromFile(
+  root: string,
+  path: string,
+  base: string | undefined,
+): Promise<SourceRead> {
+  let body: string
+  try {
+    body = await readFile(resolve(root, path), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-body' }
+  }
+
+  const resolved = await resolveBaseRef(root, base)
+  if (resolved === undefined) {
+    return {
+      kind: 'refused',
+      reason: base === undefined ? 'no-base' : 'bad-base',
+    }
+  }
+
+  const changed = await listChangedFiles(root, resolved)
+  if (changed === undefined) {
+    return { kind: 'refused', reason: 'unreadable-changes' }
+  }
+
+  const head = await $`git -C ${root} rev-parse HEAD`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+
+  return {
+    kind: 'read',
+    source: {
+      body,
+      changed,
+      head: head.exitCode === 0 ? head.text().trim() : undefined,
+      number: undefined,
+    },
+  }
+}
+
+async function runKeyChanges(
+  number: string | undefined,
+  opts: KeyChangesOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk pr key-changes')
+
+  const source =
+    opts.body === undefined
+      ? await readFromApi(root, number)
+      : await readFromFile(root, opts.body, opts.base)
+
+  if (source.kind === 'refused') return refuse(source.reason, emitJson, root)
+
+  const tracked = await listRepositoryFiles(root)
+  if (tracked === undefined) return refuse('unreadable-tree', emitJson, root)
+
+  const report: Bijection = compareKeyChanges({
+    body: source.source.body,
+    changed: source.source.changed,
+    roots: treeRoots(tracked, source.source.changed),
+    ...(source.source.head !== undefined && { head: source.source.head }),
+  })
+
+  if (report.kind === 'refused') return refuse(report.reason, emitJson, root)
+
+  logStep('Scope')
+  logInfo(
+    `${plural(report.claims.length, 'claim')} against ${plural(report.changed.length, 'changed file')}${
+      report.head === undefined ? '' : ` at ${report.head.slice(0, 8)}`
+    }`,
+  )
+
+  logStep(report.unmet.length === 0 ? 'Claimed' : 'Unmet')
+  if (report.unmet.length === 0) {
+    logInfo('every claimed path is in the diff')
+  } else {
+    logWarn(
+      `${plural(report.unmet.length, 'claimed path')} the diff does not carry. Correct the bullet, or make the change it describes.`,
+    )
+    for (const claim of report.unmet) {
+      logWarn(`${claim.path} — ${claim.preview}`)
+    }
+  }
+
+  // Named rather than counted into the verdict. A generated asset, a lockfile,
+  // and a regenerated index all change without earning a bullet, so grading
+  // this direction would fire on nearly every branch.
+  logStep('Unnamed')
+  if (report.unnamed.length === 0) {
+    logInfo('every changed file is reached by a bullet')
+  } else {
+    logInfo(
+      `${plural(report.unnamed.length, 'changed file')} no bullet reached. Add one where the change is worth a reader knowing about.`,
+    )
+    // Capped in the frame and whole in the record. A rename branch measured
+    // here left 71 of its 100 files unnamed, correctly, and printing all of
+    // them buries the graded direction above under a list nobody reads.
+    for (const path of report.unnamed.slice(0, UNNAMED_PRINT_LIMIT)) {
+      logInfo(path)
+    }
+    if (report.unnamed.length > UNNAMED_PRINT_LIMIT) {
+      logInfo(
+        `…and ${report.unnamed.length - UNNAMED_PRINT_LIMIT} more, whole in the --json record.`,
+      )
+    }
+  }
+
+  if (report.unresolved.length > 0) {
+    logStep('Unresolved')
+    logInfo(
+      `${plural(report.unresolved.length, 'path')} written partially, so neither direction judged it.`,
+    )
+    for (const claim of report.unresolved) logInfo(claim.path)
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(source.source.number !== undefined && {
+          number: source.source.number,
+        }),
+        ...(report.head !== undefined && { head: report.head }),
+        changed: report.changed,
+        claims: report.claims,
+        unmet: report.unmet,
+        unnamed: report.unnamed,
+        unresolved: report.unresolved,
+      })}\n`,
+    )
+  }
+
+  return report.unmet.length === 0 ? 0 : 2
+}
+
+/**
+ * Frames a refusal on stderr in both modes and puts the record on stdout alone,
+ * so an operator reading the terminal sees the reason rather than a command
+ * that appeared to do nothing.
+ */
+function refuse(reason: Refusal, emitJson: boolean, root: string): number {
+  logStep('Refused')
+  logWarn(REFUSALS[reason])
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason, message: REFUSALS[reason] })}\n`,
+    )
+  }
+  return 1
+}

package/src/pr/bijection.ts

@@ -0,0 +1,145 @@
+import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
+
+/**
+ * Why the comparison produced no reading.
+ *
+ * The three are apart because each names a different repair. `no-section` is a
+ * body missing the heading, `no-claims` is the extractor failing over a section
+ * full of prose, and `no-changes` is a pull request with no files. Folding any
+ * of them into a clean pass is the failure this check exists to prevent, since
+ * a reader cannot tell a check that found nothing from one that read nothing.
+ */
+export type BijectionRefusal = 'no-section' | 'no-claims' | 'no-changes'
+
+export interface BijectionReport {
+  readonly kind: 'measured'
+  /** The commit the changed set was read at, which a finding has to name. */
+  readonly head: string | undefined
+  readonly changed: readonly string[]
+  readonly claims: readonly PathClaim[]
+  /**
+   * Anchored claims no changed file answers, which is the graded direction. A
+   * bullet naming an untouched file is wrong more often than not, and this
+   * corpus reported zero of them across 23 correct bodies.
+   */
+  readonly unmet: readonly PathClaim[]
+  /**
+   * Claims whose first segment names no entry in the tree, so the comparison
+   * could not judge them either way. Reported so a run says what it declined
+   * rather than counting a partial spelling as met.
+   */
+  readonly unresolved: readonly PathClaim[]
+  /**
+   * Changed files no claim reaches. Reported without a severity, since the
+   * class covers a real omission and equally a lockfile, a generated asset, or
+   * a regenerated index that legitimately earns no bullet.
+   */
+  readonly unnamed: readonly string[]
+}
+
+export type Bijection =
+  | BijectionReport
+  | { readonly kind: 'refused'; readonly reason: BijectionRefusal }
+
+export interface BijectionInput {
+  readonly body: string
+  readonly changed: readonly string[]
+  /** Top-level entries the tree holds, which decides what counts as anchored. */
+  readonly roots: ReadonlySet<string>
+  readonly head?: string
+  readonly title?: string
+}
+
+/**
+ * Whether one changed path is the file, or a file under the folder, a claim
+ * names.
+ *
+ * An unanchored claim matches on a segment-anchored suffix, which is what lets
+ * `claude-worker/SKILL.md` credit `claude/skills/claude-worker/SKILL.md`. That
+ * asymmetry is deliberate: a partial spelling can confirm a changed file was
+ * named and never accuse one of being absent, because nothing here separates a
+ * path written short from a path written wrong.
+ */
+function covers(claim: PathClaim, path: string): boolean {
+  if (claim.directory) {
+    return claim.anchored
+      ? path.startsWith(claim.path)
+      : path.includes(`/${claim.path}`)
+  }
+  if (path === claim.path) return true
+  return !claim.anchored && path.endsWith(`/${claim.path}`)
+}
+
+/**
+ * Compares what a pull request body claims to have changed against what it
+ * actually changed, in both directions.
+ *
+ * The two directions are reported apart because they want different
+ * tolerances. A claim nobody made good on is a defect in the record that
+ * squash-merges onto the trunk, and a changed file nobody recorded is often
+ * correct. Merging them into one count would either grade the second or excuse
+ * the first.
+ *
+ * Pure, so the whole judgment is testable against a fixture. The caller reads
+ * the body, the changed set, and the tree roots and hands all three in.
+ */
+export function compareKeyChanges(input: BijectionInput): Bijection {
+  if (input.changed.length === 0)
+    return { kind: 'refused', reason: 'no-changes' }
+
+  const read = extractKeyChangePaths(
+    input.body,
+    input.roots,
+    input.title ?? KEY_CHANGES,
+  )
+  if (read.kind === 'no-section')
+    return { kind: 'refused', reason: 'no-section' }
+  if (read.claims.length === 0) return { kind: 'refused', reason: 'no-claims' }
+
+  const unmet: PathClaim[] = []
+  const unresolved: PathClaim[] = []
+  const named = new Set<string>()
+
+  for (const claim of read.claims) {
+    const hits = input.changed.filter((path) => covers(claim, path))
+    for (const path of hits) named.add(path)
+    if (hits.length > 0) continue
+    if (claim.anchored) unmet.push(claim)
+    else unresolved.push(claim)
+  }
+
+  return {
+    kind: 'measured',
+    head: input.head,
+    changed: [...input.changed],
+    claims: read.claims,
+    unmet,
+    unresolved,
+    unnamed: input.changed.filter((path) => !named.has(path)),
+  }
+}
+
+/**
+ * The top-level folders a claim may be anchored on: the first segment of every
+ * path the tree holds, plus the first segment of every changed path.
+ *
+ * The changed half is what admits a folder this branch created. Reading the
+ * tree alone would mark every claim under a new top-level directory unanchored,
+ * and an unanchored claim never accuses, so the first branch to open one would
+ * silently lose the graded direction.
+ *
+ * A path with no folder above it contributes nothing, since a claim carrying no
+ * slash never reaches the extractor's output and no root would ever be read
+ * against it.
+ */
+export function treeRoots(
+  tracked: readonly string[],
+  changed: readonly string[],
+): Set<string> {
+  const roots = new Set<string>()
+  for (const path of [...tracked, ...changed]) {
+    const at = path.indexOf('/')
+    if (at > 0) roots.add(path.slice(0, at))
+  }
+  return roots
+}

package/src/pr/paths.ts

@@ -0,0 +1,335 @@
+/**
+ * The heading whose bullets state what a branch changed.
+ *
+ * Read alone, and never widened to a sibling section. `## Technical Context`
+ * legitimately names files a branch never touched, such as an install stamp
+ * inside a target, so a reader that took the whole body would manufacture a
+ * finding out of every argument the author made for the change.
+ */
+export const KEY_CHANGES = 'Key Changes'
+
+/** What one bullet claimed, kept with its bullet so a finding can quote it. */
+export interface PathClaim {
+  /** Repository-relative, with a trailing slash kept on a directory claim. */
+  readonly path: string
+  /** True when the span named a folder, which covers every file beneath it. */
+  readonly directory: boolean
+  /**
+   * True when the first segment names an entry the tree actually holds.
+   *
+   * An unanchored claim is a path written partially, such as
+   * `claude-worker/SKILL.md` for a file under `claude/skills/`. It can confirm
+   * that a changed file was named and can never accuse one of being absent,
+   * because the comparison has no way to tell a partial spelling from a
+   * genuinely wrong one.
+   */
+  readonly anchored: boolean
+  /** The span exactly as the body wrote it, before the line suffix came off. */
+  readonly span: string
+  /** One-based index of the bullet inside the section. */
+  readonly bullet: number
+  /** The bullet, trimmed, so a finding names the sentence it came from. */
+  readonly preview: string
+}
+
+export type KeyChangeRead =
+  | {
+      readonly kind: 'read'
+      readonly claims: readonly PathClaim[]
+      /** Bullets the section carried, so an empty claim set is separable. */
+      readonly bullets: number
+    }
+  | { readonly kind: 'no-section' }
+
+/** The longest bullet a claim carries forward, matching the citation sweep. */
+const PREVIEW_LIMIT = 200
+
+/** A backticked span, the only carrier this corpus writes a path in. */
+const BACKTICKED = /`([^`\n]+)`/g
+
+/** A list item at any indent, in either bullet spelling or as an ordinal. */
+const BULLET = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/
+
+const FENCE = /^\s*(?:```|~~~)/
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/
+
+/**
+ * A `file.ts:42` or `file.ts:42-58` suffix, which is a reader's click target
+ * rather than part of the name.
+ */
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/
+
+/**
+ * A character that puts the span outside a path this comparison resolves.
+ *
+ * Whitespace separates a backticked command from a backticked path, and it is
+ * the whole answer to one of the four observed false-positive classes:
+ * `aitk markdown audit .claude/rules --json` carries a slash and names no file.
+ * Angle brackets answer a second, since `.claude/plans/feature-<slug>.md`
+ * describes a shape rather than naming a file. A glob and a caret describe a
+ * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * a leading anchor names something outside this repository.
+ *
+ * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
+ * a different question. That sweep resolves what a rule points a reader at,
+ * against the filesystem, with a sibling resolving inside the citing rule's own
+ * folder. This one resolves what a bullet claims to have changed, against a
+ * changed-file list, and it admits a folder where that sweep declines one.
+ */
+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.
+ *
+ * The extension has to start with a letter, which is what keeps `127.0.0.1`
+ * out. A bare dotted number reaching the comparison is the shape that put
+ * `src/serve/127.0.0.1` in a report over a body that was correct.
+ */
+function hasExtension(span: string): boolean {
+  const segment = span.slice(span.lastIndexOf('/') + 1)
+  return /\.[A-Za-z][A-Za-z0-9]*$/.test(segment)
+}
+
+/** Blanks every backticked span so a cue search never fires inside one. */
+function maskSpans(text: string): string {
+  return text.replace(/`[^`\n]*`/g, (span) => ' '.repeat(span.length))
+}
+
+/**
+ * The part of a bullet that asserts a change, which ends at its first comma.
+ *
+ * This is the one lever that separates a claim from a mention, and it was
+ * chosen by measurement rather than by grammar. Over the 23 merged pull
+ * requests in this repository that carry the section, reading whole bullets
+ * reported 16 paths as claimed-but-untouched and every one of them was a file
+ * the body named for context. Cutting at the comma left 110 claims of the
+ * original 149 and took the false reports to 2. A list of clause-opening words
+ * tried beside it (`which`, `since`, `because`, `rather than`, and eleven more)
+ * removed nothing the comma had not already removed, because this corpus
+ * punctuates every one of them.
+ *
+ * What it costs is a claim in a second coordinated clause, as in "Add `x` to
+ * `a.ts`, and delete the old inline `y` from `b.ts`", where `b.ts` stops being
+ * claimed and falls to the unnamed direction instead. That direction reports
+ * without grading, so the cost lands where it does no damage.
+ */
+function claimRegion(bullet: string): string {
+  const at = maskSpans(bullet).indexOf(',')
+  return at === -1 ? bullet : bullet.slice(0, at)
+}
+
+/**
+ * A claim region that asserts nothing changed.
+ *
+ * A body writes such a bullet to record a decision it declined, and the path it
+ * names is the file it deliberately did not touch, which is the exact inverse
+ * of a claim. `#1274` opens one with "Leave `...expect.toml` untouched" and the
+ * path sits ahead of the first comma, so the region cut cannot reach it: a
+ * stricter cut would not catch this and a looser one would find more.
+ *
+ * The marker rather than the leading verb decides it, because `keep` and
+ * `leave` both open a real claim often enough and neither is safe alone. The
+ * set is deliberately three words. `in place` was measured and dropped, since
+ * rewriting a file in place is an ordinary claim, and `no other line` was
+ * dropped because `#1269` writes "as one insertion that touches no other line"
+ * about a change it did make. `alone` was in the set and came out on review:
+ * every occurrence across the 40-pull-request corpus sits past the first
+ * comma, where the region cut already excludes it, so the word caught nothing
+ * real there. Kept, it turns restrictive on a comma-free bullet, which is this
+ * repository's more common use of the word: "Move the threshold read into
+ * `src/gate/stages.ts` alone." asserts an edit and voided to an empty claim
+ * set while the word was in the set, unlike the other three, which disclaim
+ * wherever they land.
+ */
+const NO_CHANGE =
+  /\b(?:untouched|unchanged)\b|\bas written\b|^\s*(?:do not|don't|never)\b/i
+
+function disclaimsChange(region: string): boolean {
+  return NO_CHANGE.test(maskSpans(region))
+}
+
+/**
+ * The lines under a heading, ending at the next heading of the same level or
+ * higher. Undefined when the body carries no such heading, which the caller
+ * reports rather than reading as an empty section.
+ */
+export function readSection(body: string, title: string): string | undefined {
+  const lines = body.replace(/\r\n/g, '\n').split('\n')
+  const wanted = title.toLowerCase()
+
+  let start = -1
+  let level = 0
+  let fenced = false
+
+  for (const [index, line] of lines.entries()) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    const heading = line.match(HEADING)
+    if (heading === null) continue
+    if ((heading[2] ?? '').toLowerCase() !== wanted) continue
+    start = index + 1
+    level = (heading[1] ?? '').length
+    break
+  }
+
+  if (start === -1) return undefined
+
+  const out: string[] = []
+  fenced = false
+  for (const line of lines.slice(start)) {
+    if (FENCE.test(line)) fenced = !fenced
+    const heading = fenced ? null : line.match(HEADING)
+    if (heading !== null && (heading[1] ?? '').length <= level) break
+    out.push(line)
+  }
+
+  return out.join('\n')
+}
+
+/**
+ * Splits a section into bullets, folding a wrapped continuation line into the
+ * bullet above it and starting a new one at every list marker.
+ *
+ * A nested bullet is its own bullet rather than part of its parent, which keeps
+ * one claim region per claim a reader sees.
+ */
+function splitBullets(section: string): string[] {
+  const bullets: string[] = []
+  let current: string[] | undefined
+  let fenced = false
+
+  for (const line of section.split('\n')) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      current?.push(line)
+      continue
+    }
+
+    const marker = fenced ? null : line.match(BULLET)
+    if (marker !== null) {
+      if (current !== undefined) bullets.push(current.join(' '))
+      current = [marker[1] ?? '']
+      continue
+    }
+
+    if (current === undefined) continue
+    if (!fenced && line.trim() === '') {
+      bullets.push(current.join(' '))
+      current = undefined
+      continue
+    }
+    current.push(line.trim())
+  }
+
+  if (current !== undefined) bullets.push(current.join(' '))
+  return bullets
+}
+
+/** What one span resolved to, or nothing when it names no comparable path. */
+interface ResolvedSpan {
+  readonly path: string
+  readonly directory: boolean
+}
+
+function resolveSpan(span: string): ResolvedSpan | undefined {
+  if (span === '' || isNotRepositoryPath(span)) return undefined
+
+  // A bare name is the fourth observed false-positive class and it drops
+  // outright. Resolved as a sibling of a path earlier in the bullet it produced
+  // seven wrong paths across this corpus against two right ones, because a
+  // compound bullet names a sibling folder as often as a sibling file. Dropping
+  // it under-reports in the unnamed direction and never fires in the other.
+  if (!span.includes('/')) return undefined
+
+  if (span.endsWith('/')) {
+    // A single top-level folder is never a claim. Nobody reports having changed
+    // the whole of `src/`, and every body that spelled one was naming where
+    // something lives.
+    return span.indexOf('/') === span.length - 1
+      ? undefined
+      : { path: span, directory: true }
+  }
+
+  return hasExtension(span) ? { path: span, directory: false } : undefined
+}
+
+/**
+ * Every path the `## Key Changes` section claims a change to.
+ *
+ * `roots` names the entries the tree holds at its top level, which is what
+ * separates a whole path from one written partially. It is passed in rather
+ * than read here so the extractor stays a pure function of the body, and there
+ * is no default: an absent set would silently mark every claim anchored, which
+ * is the direction that accuses.
+ *
+ * Reports `no-section` rather than an empty read when the heading is absent,
+ * and an empty claim set with a bullet count when the heading is there and
+ * nothing resolved. The caller needs those apart. A body with no section states
+ * nothing, a section that produced no claim is this extractor failing over
+ * prose, and only a section that produced claims supports a comparison. An
+ * empty extraction read as a clean pass is the failure shape this repository
+ * has already recorded twice.
+ */
+export function extractKeyChangePaths(
+  body: string,
+  roots: ReadonlySet<string>,
+  title: string = KEY_CHANGES,
+): KeyChangeRead {
+  const section = readSection(body, title)
+  if (section === undefined) return { kind: 'no-section' }
+
+  const bullets = splitBullets(section)
+  const claims: PathClaim[] = []
+  const seen = new Set<string>()
+
+  for (const [index, bullet] of bullets.entries()) {
+    const trimmed = bullet.trim()
+    const preview =
+      trimmed.length > PREVIEW_LIMIT
+        ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
+        : trimmed
+    const region = claimRegion(trimmed)
+    if (disclaimsChange(region)) continue
+
+    let claimed = false
+
+    for (const match of region.matchAll(BACKTICKED)) {
+      const span = match[1] ?? ''
+      const bare = span.replace(LINE_SUFFIX, '')
+
+      // A `file:line` span following another claim in the same bullet is a
+      // citation into a file being described rather than a second claim, which
+      // is what "the stages at `verify.sh:634` and `:642`" is doing inside a
+      // bullet whose claim is the context entry that describes them. Leading
+      // its bullet it is an ordinary claim, which is how a body names the exact
+      // line it rewrote.
+      const cited = bare !== span
+      if (cited && claimed) continue
+
+      const resolved = resolveSpan(bare)
+      if (resolved === undefined) continue
+      claimed = true
+      if (seen.has(resolved.path)) continue
+      seen.add(resolved.path)
+
+      claims.push({
+        path: resolved.path,
+        directory: resolved.directory,
+        anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
+        span,
+        bullet: index + 1,
+        preview,
+      })
+    }
+  }
+
+  return { kind: 'read', claims, bullets: bullets.length }
+}