@fyeeme/pi-review 2.0.0 → 2.0.1

package/skills/simplify/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: simplify
-description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v3 (from Claude Code CLI v2.1.227, symbol-level verified) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
+description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /review for that. v3 (from Claude Code CLI v2.1.227, symbol-level verified; re-verified against v2.1.261 on 2026-09-05 — bodies unchanged except Altitude) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
 ---
 
 <!--
   Origin: Claude Code built-in skill `/simplify` (CLI v2.1.227), reverse-
-  engineered from bin/claude.exe raw bytes. Pi registers it as /code-simplify.
+  engineered from bin/claude.exe raw bytes. Pi registers it as /simplify.
 
   Lineage:
     v2.1.220 → the first reconstruction         (v1)
@@ -18,6 +18,16 @@ description: "Review the changed code for reuse, simplification, efficiency, and
                VBv/KBv (with interpolated c$e / m7t / u$e / d$e / p$e) are
                unchanged; the mode guard is Dii (see below); fan-out defaults
                nJu=20 / lKs=50 are now mirrored in the subagent tool.
+    v2.1.261 → re-verified 2026-09-05 from raw bytes: the two mode bodies,
+               the 4-angle set, and the Phase 2 apply rules are unchanged;
+               the Altitude angle gained CC's root-cause phrasing + "name
+               that change" (synced here and in the review skill). The command
+               description ("Clean up the changed code without changing
+               behavior"; "Quality only — it does not hunt for bugs; use
+               /code-review for that") and the Agent-tool fan-out ("all in a
+               single message so they run concurrently") are unchanged.
+               The /code-review↔/simplify division of labor is now stated
+               explicitly in both skills upstream — same as here.
 
   CC 2.1.227 empirical evidence (symbol-level, extracted from bin/claude.exe):
     - $u({name: "simplify", ..., getPromptForCommand(args, ctx)}) registers the
@@ -31,14 +41,14 @@ description: "Review the changed code for reuse, simplification, efficiency, and
       default 3, feature flag tengu_hazel_trellis) OR the Agent tool is not in
       the options.tools allowlist (Pa matches by name/aliases).
     - VBv / KBv — the two mode-body templates; interpolated variables shared
-      with /code-review: c$e (Phase 0), m7t/u$e/d$e/p$e (the 4 cleanup angles).
+      with the review skill: c$e (Phase 0), m7t/u$e/d$e/p$e (the 4 cleanup angles).
     - nJu() = CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ?? 20; lKs =
       FORKED_AGENT_DEFAULT_MAX_TURNS = 50 — mirrored as the subagent tool's
       defaults (PI_MAX_CONCURRENT_SUBAGENTS env still overrides the ceiling).
 
   Bundled: ships inside the pi-review extension (skills/simplify/SKILL.md).
 
-  Invocation: /code-simplify [<target>]
+  Invocation: /simplify [<target>]
     target = file path | PR number | branch name
 
   ════════════════════════════════════════════════════════════════════════
@@ -50,50 +60,92 @@ description: "Review the changed code for reuse, simplification, efficiency, and
        agent depth >= CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3); (b) the
        Agent tool must be in the allowlist. On Pi: (a) is N/A — the `subagent`
        tool spawns a fresh subprocess (always depth 0), so depth never accumulates
-       — so decideSimplifyMode substitutes a context-fraction heuristic
-       (tokens/contextWindow >= 0.8 → single-pass), a Pi addition NOT a mirror of
-       Dii; (b) is mirrored as "the `subagent` tool must be registered". The
-       decision is made DETERMINISTICALLY by the /code-simplify handler — it can
+       — so decideSimplifyMode substitutes three Pi-added guards: a context-fraction
+       heuristic (tokens/contextWindow >= 0.8 → single-pass), a diff-size
+       guard (diff >= 400K chars → single-pass; the 4-copy fan-out would burn
+       ~400K input tokens on prompt text alone), and fan-out availability
+       (the fan-out tools must be registered for this process — the Pi
+       counterpart of Dii's allowlist clause) — Pi additions NOT mirrors of
+       Dii. The cleanup agents' tool whitelist (read/grep/find/ls/bash) never
+       includes a fan-out tool, so recursion stays physically bounded
+       regardless of tool registration. The decision is made
+       DETERMINISTICALLY by the /simplify handler — it can
        read ctx.getContextUsage(), which a pure-prompt skill cannot — and announced
        in the trigger message; this skill just provides the two mode bodies.
-    3. Command     — CC: /simplify; Pi: /code-simplify.
-
-  Prerequisite: the `subagent` tool (provided by the pi-review extension) for
-                PARALLEL MODE, and the `review_report` tool (same extension) for
-                the Phase 2 structured outcome report. SINGLE-PASS MODE runs
-                standalone apart from `review_report`.
+    3. Command     — CC: /simplify; Pi: /simplify.
+    4. Dispatch    — CC's lead model writes the 4 Agent prompts itself after its
+       visible Phase 0. Pi keeps the same TIMELINE but moves the packaging into
+       code: the trigger message carries the handler-resolved scope, the
+       changed-file index, and the exact `git -C … diff …` command; the model
+       runs it, reads the diff, writes a change-intent summary, and THEN calls
+       the `subagent` tool in parallel mode (the counterpart of CC's Agent
+       call) with the 4 bundled cleaner agents; the tool result carries the
+       findings back into the same turn for Phase 2.
+
+  Prerequisite: the `review_report` tool (provided by the pi-review extension)
+                for the Phase 2 structured outcome report. PARALLEL MODE
+                additionally needs the `subagent` tool (@fyeeme/pi-subagents;
+                registered whenever fan-out is allowed for this process — the
+                recursion guard; the dispatcher only picks PARALLEL when it
+                is) plus the bundled agents cleaner-reuse /
+                cleaner-simplification / cleaner-efficiency / cleaner-altitude.
+                SINGLE-PASS MODE runs standalone apart from `review_report`.
 -->
 
 You are improving the quality of the changed code, not hunting for bugs. Review
 it for reuse, simplification, efficiency, and altitude issues, then fix what you
-find. Do not look for correctness bugs — that is what `/code-review` is for.
+find. Do not look for correctness bugs — that is what `/review` is for.
 
-The `/code-simplify` handler has already chosen the mode (PARALLEL or
+The `/simplify` handler has already chosen the mode (PARALLEL or
 SINGLE-PASS) from real context usage and announced it in the trigger message.
 Follow the body that matches; do not fake the mode you weren't asked to run.
+Both modes open the same way: the trigger message carries the handler-resolved
+scope, a changed-file index, and the exact git command — Phase 0 below is a
+VISIBLE, model-run step before anything launches.
 
 ## Phase 0 — Gather the diff
 
-Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+When the trigger message carries a handler-resolved scope (it always does for
+/simplify), use THAT: run the exact `git -C … diff …` command the trigger
+provides — the handler already ran the cascade (merge-base → HEAD → staged →
+unstaged) to pick it — read the full diff, and write a 2–4 line change-intent
+summary before anything else. Do not re-derive a different range. That summary
+and your first-hand reading are what you will use to merge, dedup, and judge
+findings in Phase 2.
+
+(No trigger scope — e.g. the skill invoked standalone? Then: run
+`git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
 if there's no upstream) to get the unified diff under review. If there are
 uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
 include the working-tree changes in scope — the review often runs before the
 commit. If a PR number, branch name, or file path was passed as an argument,
-review that target instead. Treat this diff as the review scope.
+review that target instead. Treat this diff as the review scope.)
 
 ---
 
-# PARALLEL MODE  (subagent tool available AND context not near-full)
+# PARALLEL MODE  (context not near-full AND diff under the fan-out threshold AND fan-out available)
 
-`/code-simplify → 4 cleanup agents in parallel → apply the fixes`
+`/simplify → visible Phase 0 (read the diff, summarize) → subagent tool (parallel, 4 cleaner agents) → apply the fixes`
 
 ## Phase 1 — Review (4 cleanup agents in parallel)
 
-Launch **4 independent review agents** via the subagent tool, all in a
-single message so they run concurrently. Pass each agent the diff and one of
-the four angles below. Each returns its findings with `file`, `line`, a
-one-line `summary`, and the concrete cost (what is duplicated, wasted, or
-harder to maintain).
+After your Phase 0 summary, call the `subagent` tool exactly as the trigger
+message instructs: parallel mode, 4 tasks, one per bundled agent —
+cleaner-reuse, cleaner-simplification, cleaner-efficiency, cleaner-altitude —
+each with `maxTurns: 15` (set it on the call; 15 is the built-in default — a
+different budget stated in the trigger message wins). The agents' angle guidance
+rides their own definitions (read-only tool whitelist read/grep/find/ls/bash);
+each returns its findings with `file`, `line`, a one-line `summary`, and the
+concrete cost (what is duplicated, wasted, or harder to maintain). The agent
+rows appear live in the agent widget / FleetView and respect the
+`maxConcurrency` setting.
+
+Do NOT write the four agent prompts yourself or inline the diff into any
+prompt. If the fan-out conditions no longer hold (context grew while you read
+the diff), fall back to the SINGLE-PASS body below and report `fanned_out:
+false`. When the tool result arrives, merge and deduplicate the findings
+against your first-hand Phase 0 reading. The four angles below are what the
+agents were asked to find.
 
 ### Reuse
 
@@ -119,23 +171,27 @@ alternative.
 
 ### Altitude
 
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix
-isn't deep enough — prefer generalizing the underlying mechanism over adding
-special cases.
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler,
+more general change to the underlying mechanism over adding special cases,
+and name that change.
 ## Phase 2 — Apply, verify, and report
 
-Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). The parallel fan-out only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: true` in the report since the 4-agent fan-out actually ran.
+Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). The parallel fan-out only changes how findings are gathered (Phase 1 — done by the handler); applying, verifying, and reporting are identical across modes. Set `fanned_out: true` in the report since the 4-agent fan-out actually ran.
 
 ---
 
-# SINGLE-PASS MODE  (subagent tool unavailable OR context near-full)
+# SINGLE-PASS MODE  (context near-full OR diff too large OR fan-out unavailable)
 
-`/code-simplify → subagent tool unavailable → single-pass inline cleanup → apply the fixes`
+`/simplify → handler decided single-pass (reasons in the trigger message) → inline cleanup → apply the fixes`
 
-The subagent tool isn't available in this context, so the usual
-4-agent fan-out can't run. Work through all four angles below yourself, in
-this same context, in one pass — do not skip an angle for lack of fan-out.
+The handler decided against the 4-agent fan-out (context near-full, diff too
+large, fan-out unavailable, or usage unmeasurable — the exact reasons are in
+the trigger message), so work through all four angles below yourself, in this
+same context, in one pass — do not skip an angle for lack of fan-out. Phase 0
+is the same visible opening: run the exact git command from the trigger
+message, read the diff, write the change-intent summary.
 
 ## Phase 1 — Review (4 cleanup angles, single pass)
 
@@ -167,10 +223,11 @@ alternative.
 
 ### Altitude
 
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix
-isn't deep enough — prefer generalizing the underlying mechanism over adding
-special cases.
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler,
+more general change to the underlying mechanism over adding special cases,
+and name that change.
 ## Phase 2 — Apply, verify, and report
 
 Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). Single-pass vs parallel only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: false` in the report so a reader is not misled into thinking the 4-agent fan-out ran.
@@ -180,7 +237,7 @@ Follow the shared **Phase 2** procedure at the end of this skill (snapshot → a
 # Phase 2 — Apply, verify, and report (shared by both modes)
 
 Dedup findings that point at the same line or mechanism first. Then apply,
-verify, and report. This safety net is what distinguishes `/code-simplify` from
+verify, and report. This safety net is what distinguishes `/simplify` from
 a blind cleanup: a finding is only "done" once it is applied AND the project
 still verifies — otherwise it is reverted.
 
@@ -201,7 +258,7 @@ for any file in a subdirectory. If a fix CREATES a new file, record its path so
 Step 3a can remove it on rollback (it has no baseline entry).
 
 This baseline captures the working-tree state **including** the user's
-uncommitted changes — reverting to it undoes only `/code-simplify`'s fixes,
+uncommitted changes — reverting to it undoes only `/simplify`'s fixes,
 never the user's diff. Do **not** use `git checkout` / `git restore` to revert:
 that would discard the user's intended changes too.
 

package/src/config.ts

@@ -0,0 +1,103 @@
+/**
+ * src/config.ts — file-based turn-budget configuration, mirroring the
+ * pi-subagents `pi-subagent.json` pattern (read-only, lenient, two layers
+ * with project overriding global):
+ *
+ *   - Global:  <agentDir>/pi-review.json   (user-wide defaults)
+ *   - Project: <cwd>/.pi/pi-review.json    (overrides global on load)
+ *
+ * Schema (all keys optional):
+ *
+ *   {
+ *     "maxTurns": {
+ *       "subagent": 20,   // per-call budget for each /review finder batch
+ *       "gapHunt":  15,   // budget for the /review Phase 3 gap-hunter
+ *       "simplify": 15    // budget for each /simplify PARALLEL cleaner agent
+ *     }
+ *   }
+ *
+ * The defaults here are the numbers the bundled prompts and skills were
+ * written with (finder 20 / gap-hunt 15 / simplify 15). With no config file
+ * — or with any key absent or invalid — the rendered instructions carry
+ * exactly those numbers, so absence of configuration changes nothing.
+ *
+ * Read at command time (like pi-subagents' maxConcurrency): an edited file
+ * takes effect on the next /review or /simplify without a restart. Malformed
+ * files are ignored with a stderr warning (never fatal); unknown/garbage
+ * fields are dropped on read.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Settings file name (both layers). */
+const CONFIG_FILE = "pi-review.json";
+
+/** The four dispatchable turn budgets, keyed by what they throttle. */
+export interface TurnBudgets {
+	/** `maxTurns` set on each /review finder-batch `subagent` call. */
+	subagent: number;
+	/** `maxTurns` set on each /review Phase 2 verifier `subagent` call. */
+	verifier: number;
+	/** `maxTurns` set on the /review Phase 3 gap-hunt `subagent` call. */
+	gapHunt: number;
+	/** `maxTurns` set on each /simplify PARALLEL cleaner `subagent` call. */
+	simplify: number;
+}
+
+/** Built-in budgets — identical to the literals in prompts/ and skills/. */
+export const DEFAULT_TURN_BUDGETS: TurnBudgets = {
+	subagent: 20,
+	verifier: 15,
+	gapHunt: 15,
+	simplify: 15,
+};
+
+function globalPath(): string {
+	return join(getAgentDir(), CONFIG_FILE);
+}
+
+function projectPath(cwd: string): string {
+	return join(cwd, ".pi", CONFIG_FILE);
+}
+
+/** Positive integers only; anything else (floats, 0, negatives, strings) is
+ *  dropped so the built-in default applies. */
+function sanitizeBudget(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+
+/** Read one config file; missing file → {} (the normal case, silent).
+ *  Unparseable file → warn + {}. Unknown fields are dropped. */
+function readBudgetsFile(path: string): Partial<TurnBudgets> {
+	if (!existsSync(path)) return {};
+	try {
+		const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!raw || typeof raw !== "object") return {};
+		const maxTurns = (raw as Record<string, unknown>).maxTurns;
+		const mt = maxTurns && typeof maxTurns === "object" ? (maxTurns as Record<string, unknown>) : {};
+		const out: Partial<TurnBudgets> = {};
+		const subagent = sanitizeBudget(mt.subagent);
+		if (subagent !== undefined) out.subagent = subagent;
+		const verifier = sanitizeBudget(mt.verifier);
+		if (verifier !== undefined) out.verifier = verifier;
+		const gapHunt = sanitizeBudget(mt.gapHunt);
+		if (gapHunt !== undefined) out.gapHunt = gapHunt;
+		const simplify = sanitizeBudget(mt.simplify);
+		if (simplify !== undefined) out.simplify = simplify;
+		return out;
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		console.warn(`[pi-review] Ignoring malformed config at ${path}: ${reason}`);
+		return {};
+	}
+}
+
+/** Load the effective turn budgets: built-in defaults ← global ← project. */
+export function loadTurnBudgets(cwd: string = process.cwd()): TurnBudgets {
+	return {
+		...DEFAULT_TURN_BUDGETS,
+		...readBudgetsFile(globalPath()),
+		...readBudgetsFile(projectPath(cwd)),
+	};
+}

package/src/diff.ts

@@ -0,0 +1,306 @@
+/**
+ * src/diff.ts — deterministic diff resolution for the review prompts (v1
+ * semantics, relocated verbatim from src/commands/code-simplify.ts).
+ *
+ * The candidate ladder widens "changed code" as far as it resolves:
+ * upstream merge-base → HEAD worktree → staged-fresh → unstaged-fresh, and
+ * covers git submodules (a target inside a submodule resolves to the
+ * submodule's own root, so the real changes are reviewed instead of a dirty
+ * pointer). Pure functions — unit-testable, injected GitRunner.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Soft cap on the changed-file list in the context package (see buildContextPackage). */
+export const CONTEXT_PACKAGE_MAX_FILES = 200;
+
+/**
+ * Walk up from `from` to the nearest directory containing `.git` (a directory
+ * or a submodule pointer file). Returns that root or null.
+ */
+export function findGitRoot(from: string): string | null {
+	let dir = path.resolve(from);
+	for (;;) {
+		if (fs.existsSync(path.join(dir, ".git"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Normalize a /simplify target argument: trimmed, with an optional
+ *  path-prefix `@` PRESERVED — a real directory may itself start with `@`
+ *  (e.g. node_modules/@scope/pkg), so the resolver tries the literal path
+ *  first and only falls back to the @-stripped form when it does not exist. */
+function normalizeTarget(target: string | undefined): string {
+	return (target ?? "").trim();
+}
+
+/** Resolve the diff scope for a review/simplify target. Pure — unit-testable.
+ *
+ *  - target absent/unresolvable → the nearest git root of `cwd`, full diff.
+ *  - target is a path → its nearest git root; the relative path inside that
+ *    root is the diff scope. Crucially this covers git SUBMODULES: a target
+ *    like `@packages/extensions/pi-review/` resolves to the submodule's own
+ *    git root, so the real changes inside it (invisible to the parent repo's
+ *    `git diff`) are reviewed instead of a dirty-submodule pointer.
+ *  - target at the git root itself (e.g. the whole submodule) → full diff.
+ * Returns null when no git root exists.
+ */
+export function resolveDiffScope(
+	cwd: string,
+	target: string | undefined,
+): { gitRoot: string; relPath: string | null } | null {
+	const raw = normalizeTarget(target);
+	// The `@`-prefix path convention (`@packages/extensions/pi-review/`): try
+	// the literal path FIRST (a real directory may itself start with `@`, e.g.
+	// node_modules/@scope/pkg) and only fall back to the @-stripped form.
+	let abs: string | null = null;
+	if (raw) {
+		for (const candidate of raw.startsWith("@") ? [raw, raw.slice(1)] : [raw]) {
+			const resolved = path.resolve(cwd, candidate);
+			if (fs.existsSync(resolved)) {
+				abs = resolved;
+				break;
+			}
+		}
+	}
+	// Unresolvable target — absent, or a non-path (branch / PR number) that
+	// doesn't exist on disk — keeps the whole-diff scope of cwd's git root.
+	if (abs == null) {
+		const gitRoot = findGitRoot(cwd);
+		return gitRoot ? { gitRoot, relPath: null } : null;
+	}
+	const gitRoot = findGitRoot(abs);
+	if (!gitRoot) return null;
+	const relPath = path.relative(gitRoot, abs);
+	return { gitRoot, relPath: relPath === "" || relPath === "." ? null : relPath };
+}
+
+/** Injectably run `git` (defaults to promisified execFile — array argv, no
+ *  shell, and non-blocking: the caller is async, so git runs on the event
+ *  loop instead of freezing the TUI for the whole diff duration). `signal`
+ *  (optional) lets the caller abort an in-flight diff via ctx.signal. */
+export type GitRunner = (args: string[], opts: { cwd: string; signal?: AbortSignal }) => Promise<string>;
+
+const execFileAsync = promisify(execFile);
+
+const defaultGitRunner: GitRunner = async (args, opts) =>
+	(await execFileAsync("git", args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		maxBuffer: 10 * 1024 * 1024,
+		signal: opts.signal,
+	})).stdout;
+
+/** Which diff range produced the diff (drives scope reporting in prompts/messages). */
+export type DiffScopeKind = "upstream" | "worktree" | "staged-fresh" | "unstaged-fresh";
+
+/** Human label per scope kind — the single place the wording lives. */
+export const DIFF_SCOPES: Record<DiffScopeKind, string> = {
+	upstream: "unpushed commits + uncommitted changes (merge-base of @{upstream} → working tree)",
+	worktree: "uncommitted changes (HEAD → working tree)",
+	"staged-fresh": "staged changes (repo has no commits yet)",
+	"unstaged-fresh": "unstaged changes (repo has no commits yet)",
+};
+
+/**
+ * Result of resolving the diff. `ok` carries the diff plus the scope kind
+ * that produced it and `gitCommand` — a shell-ready command that reproduces
+ * the exact diff invocation (range + path limiter + git root), so the
+ * rendered prompt can have the model re-read the SAME diff visibly instead
+ * of re-deriving a different range; the failure kinds are distinguishable so
+ * the caller can report WHY nothing was reviewed instead of a blanket "no
+ * changes".
+ */
+export type DiffOutcome =
+	| { kind: "ok"; diff: string; gitRoot: string; scopeKind: DiffScopeKind; gitCommand: string }
+	| { kind: "no-repo" }
+	| { kind: "empty" }
+	| { kind: "git-error"; message: string };
+
+/**
+ * Resolve the diff for the resolved scope (see resolveDiffScope), widening
+ * the view to the full "changed code":
+ *
+ *  1. upstream — `git diff <merge-base @{upstream} HEAD>`: everything since
+ *     divergence from the tracked upstream (unpushed commits + staged +
+ *     unstaged) in one range. Skipped when no upstream is configured.
+ *  2. worktree — `git diff HEAD`: all uncommitted (staged + unstaged).
+ *  3. staged-fresh / unstaged-fresh — repos with no commits yet (HEAD doesn't
+ *     resolve): index vs empty tree, then worktree vs index.
+ *
+ * The first candidate that yields a non-empty diff wins. All empty → `empty`;
+ * every candidate erroring (broken repo, diff exceeding maxBuffer) →
+ * `git-error` carrying the last error message; no git root → `no-repo`.
+ */
+export async function getRepoDiff(
+	cwd: string,
+	target: string | undefined,
+	run: GitRunner = defaultGitRunner,
+	signal?: AbortSignal,
+): Promise<DiffOutcome> {
+	const scope = resolveDiffScope(cwd, target);
+	if (!scope) return { kind: "no-repo" };
+	const { gitRoot, relPath } = scope;
+	const pathArgs: string[] = relPath ? ["--", relPath] : [];
+	/** argv of one diff invocation — the single construction shared by the
+	 *  executed call (diffAttempt) and the reproduction command (commandFor),
+	 *  so the command shown to the model cannot drift from what ran. */
+	const diffArgs = (range: string[]): string[] => ["diff", "--no-color", ...range, ...pathArgs];
+	/** Shell-ready reproduction of a diff invocation (JSON.stringify quotes each
+	 *  path — valid POSIX quoting that also escapes embedded quotes). The
+	 *  relPath is re-quoted here for the DISPLAY only; the executed call uses
+	 *  the raw argv (diffArgs). A shell interpreting the displayed command
+	 *  produces the same argv, so the two cannot drift. */
+	const commandFor = (range: string[]): string => {
+		// Only shell-unsafe relPaths get quoted — a plain path stays clean in
+		// the displayed command, a path with spaces/glob metachars is quoted
+		// (JSON.stringify = valid POSIX quoting) so the visible re-run
+		// reproduces it exactly.
+		const safeRelPath = (p: string): string => (/^[A-Za-z0-9_./-]+$/.test(p) ? p : JSON.stringify(p));
+		return [
+			"git",
+			"-C",
+			JSON.stringify(gitRoot),
+			"diff",
+			"--no-color",
+			...range,
+			...(relPath ? ["--", safeRelPath(relPath)] : []),
+		].join(" ");
+	};
+
+	let lastError: string | undefined;
+	/** `recordError` false = a failure that is a legitimate fallback signal
+	 *  (git diff HEAD on a repo with no commits yet) — it must not be mistaken
+	 *  for a broken repo, or an empty fresh repo would report git-error
+	 *  instead of empty. */
+	const diffAttempt = async (range: string[], recordError = true): Promise<string | null> => {
+		try {
+			const out = (await run(diffArgs(range), { cwd: gitRoot, signal })).trim();
+			return out || null;
+		} catch (err) {
+			if (recordError) lastError = err instanceof Error ? err.message : String(err);
+			return null;
+		}
+	};
+	const mergeBaseWithUpstream = async (): Promise<string | null> => {
+		try {
+			return (await run(["merge-base", "@{upstream}", "HEAD"], { cwd: gitRoot, signal })).trim() || null;
+		} catch {
+			return null;
+		}
+	};
+
+	// Candidate ladder in priority order — the first non-empty diff wins.
+	// `git diff HEAD` failing (recordError false) is the EXPECTED fresh-repo
+	// signal, not a broken repo; the later staged/unstaged candidates carry
+	// the real errors so a genuinely broken repo still surfaces git-error.
+	const candidates: { scopeKind: DiffScopeKind; range: string[]; recordError: boolean }[] = [];
+	const mb = await mergeBaseWithUpstream();
+	if (mb) candidates.push({ scopeKind: "upstream", range: [mb], recordError: true });
+	candidates.push(
+		{ scopeKind: "worktree", range: ["HEAD"], recordError: false },
+		{ scopeKind: "staged-fresh", range: ["--staged"], recordError: true },
+		{ scopeKind: "unstaged-fresh", range: [], recordError: true },
+	);
+	for (const c of candidates) {
+		const out = await diffAttempt(c.range, c.recordError);
+		if (out) return { kind: "ok", diff: out, gitRoot, scopeKind: c.scopeKind, gitCommand: commandFor(c.range) };
+	}
+	return lastError ? { kind: "git-error", message: lastError } : { kind: "empty" };
+}
+
+/**
+ * Build the zero-token context package injected into every rendered prompt:
+ * repo root, the resolved diff scope, and a changed-file index with
+ * add/remove line counts, parsed straight out of the diff — no extra git
+ * calls, no drift from the diff embedded below. Gathered dispatcher-side
+ * where it costs no parent-context tokens, so each agent skips its own 1–3
+ * exploration rounds of `git diff --stat`. Pure — unit-testable.
+ */
+export function buildContextPackage(diff: string, gitRoot: string, scopeLabel: string): string {
+	const churn = new Map<string, { added: number; removed: number; binary: boolean }>();
+	let current: string | null = null;
+	/** git quotes path headers with non-ASCII/special chars (core.quotepath
+	 *  default true) — accept both the plain and the quoted "a/…" "b/…" forms. */
+	const FILE_HEADER = /^diff --git (?:a\/(.*) b\/(.*)|"a\/(.*)" "b\/(.*)")$/;
+	/** `--- a/…` / `+++ b/…` (or /dev/null, or quoted variants) are file
+	 *  headers, not content lines — but a CONTENT line may itself start with
+	 *  `+`/`-` (rendered `+++x`), so only the exact header prefixes skip. */
+	const HEADER_PREFIXES = [
+		"--- a/",
+		"--- /dev/null",
+		"+++ b/",
+		"+++ /dev/null",
+		'--- "a/',
+		'+++ "b/',
+	];
+	for (const line of diff.split("\n")) {
+		const m = FILE_HEADER.exec(line);
+		if (m) {
+			current = m[2] ?? m[4]!;
+			if (!churn.has(current)) churn.set(current, { added: 0, removed: 0, binary: false });
+			continue;
+		}
+		if (current == null) continue;
+		const c = churn.get(current)!;
+		if (line.startsWith("Binary files")) c.binary = true;
+		else if (HEADER_PREFIXES.some((p) => line.startsWith(p))) continue;
+		else if (line.startsWith("+")) c.added++;
+		else if (line.startsWith("-")) c.removed++;
+	}
+
+	// Map iterates in insertion order — the keys ARE the first-seen file order.
+	const files = [...churn.keys()];
+	const lines: string[] = [`Repo root: ${gitRoot}`, `Diff scope: ${scopeLabel}`];
+	if (files.length > 0) {
+		lines.push("Changed files (added/removed lines):");
+		for (const f of files.slice(0, CONTEXT_PACKAGE_MAX_FILES)) {
+			const c = churn.get(f)!;
+			lines.push(`  ${f}${c.binary ? " (binary)" : ` +${c.added} -${c.removed}`}`);
+		}
+		if (files.length > CONTEXT_PACKAGE_MAX_FILES)
+			lines.push(`  … and ${files.length - CONTEXT_PACKAGE_MAX_FILES} more (see the diff below)`);
+	}
+	return lines.join("\n");
+}
+
+/** Priority order for picking a verification command from package.json scripts. */
+const VERIFY_SCRIPT_PRIORITY = ["check", "test", "lint", "typecheck"] as const;
+
+/**
+ * Pick the project verification command from a package.json `scripts` map, in
+ * priority order (check → test → lint → typecheck). Pure — unit-testable.
+ * Returns the runnable command (e.g. `npm run check`) or null when none exists.
+ */
+export function detectVerifyCommand(scripts: Record<string, string> | null): string | null {
+	if (!scripts) return null;
+	for (const key of VERIFY_SCRIPT_PRIORITY) {
+		const v = scripts[key];
+		if (typeof v === "string" && v.trim() !== "") return `npm run ${key}`;
+	}
+	return null;
+}
+
+/** Read package.json scripts from `cwd`; returns null when absent/unparseable. */
+export function readScriptsAt(cwd: string): Record<string, string> | null {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		return pkg.scripts ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** Build the "verify/apply" guidance line rendered into the prompts. */
+export function verifyLine(cwd: string): string {
+	const verifyCmd = detectVerifyCommand(readScriptsAt(cwd));
+	return verifyCmd
+		? `Verification command: \`${verifyCmd}\` (detected from package.json scripts). After applying fixes, run it; on failure, follow the skill's auto-revert procedure — never leave the working tree verified-broken.`
+		: `No verification command detected in package.json (looked for check/test/lint/typecheck). Apply fixes and report outcomes, but state in the report that no verification was run (verification is opportunistic, never blocking).`;
+}