@erclx/aitk 3.52.1 → 3.54.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.54.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/agents/sandbox.md

@@ -25,16 +25,20 @@ Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` s
 aitk sandbox check claude:docs drift --json
 ```
 
-| Flag                | Effect                                                     |
-| ------------------- | ---------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
-| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
-| `--json`            | Emit the verdict record on stdout                          |
-| `--strict`          | Exit 1 on `unchecked` instead of 0                         |
+| Flag                | Effect                                                                      |
+| ------------------- | --------------------------------------------------------------------------- |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text                   |
+| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope                  |
+| `--escapes <file>`  | Newline-delimited paths written to a watched toolkit root, for escape scope |
+| `--escapes-watched` | At least one watched root held a target this run                            |
+| `--json`            | Emit the verdict record on stdout                                           |
+| `--strict`          | Exit 1 on `unchecked` instead of 0                                          |
 
 The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
 
-Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
+
+An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `.claude/context/sandbox/overview.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 

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