@fyeeme/pi-review 1.1.1 → 2.0.1

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).`;
+}

package/src/dispatch.ts

@@ -0,0 +1,238 @@
+/**
+ * src/dispatch.ts — the generic prompt dispatcher (v2's only command layer).
+ *
+ * Per invocation: parse leading arguments, gather deterministic runtime
+ * variables (resolved diff via the candidate ladder, context usage,
+ * changed-file context package, sticky last-effort state), evaluate the
+ * guards declared in the selected template's frontmatter, pick the template
+ * variant, substitute {{var}} placeholders, and hand the rendered message to
+ * the session via sendUserMessage.
+ *
+ * The parallel-strategy decisions live in prompts/*.md frontmatter (data);
+ * this module only executes them. Adding a new prompt/skill requires no
+ * change here — the templates and skills are the registration surface.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isFanoutToolAllowed } from "@fyeeme/pi-subagents";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadTurnBudgets } from "./config.ts";
+import { DIFF_SCOPES, buildContextPackage, getRepoDiff, verifyLine } from "./diff.ts";
+import { bundledSkillPath } from "./skills.ts";
+import { parseGuards, selectVariant } from "./strategy.ts";
+
+// This file lives at <pkg>/src/ → ".." is the package root.
+const PKG_ROOT = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+
+/** Absolute path to a prompt template bundled in this package's prompts/ dir. */
+function bundledPromptPath(rel: string): string {
+	return path.join(PKG_ROOT, "prompts", rel);
+}
+
+/** Load a bundled template: frontmatter map + body. */
+function loadTemplate(rel: string): { frontmatter: Record<string, unknown>; body: string } {
+	const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(
+		fs.readFileSync(bundledPromptPath(rel), "utf8"),
+	);
+	return { frontmatter, body };
+}
+
+/** Substitute {{var}} placeholders. An unknown placeholder is an error at
+ *  load time in dev, but rendering must never crash a command — unfilled
+ *  placeholders are left visible (they self-report in the rendered message).
+ *  Pure — unit-testable. */
+export function render(body: string, vars: Record<string, string>): string {
+	return body.replace(/\{\{([a-z-]+)\}\}/g, (whole, name: string) =>
+		name in vars ? vars[name]! : whole,
+	);
+}
+
+// ---------------------------------------------------------------------------
+// /review — effort-level code review (v1 command semantics, relocated)
+// ---------------------------------------------------------------------------
+
+/** Effort levels the /review command accepts (mirrors CC's effort enum). */
+export const REVIEW_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type ReviewLevel = (typeof REVIEW_LEVELS)[number];
+
+const DEFAULT_LEVEL: ReviewLevel = "low";
+
+/** Where the last explicitly-typed effort is persisted (CC 2.1.223 codeReviewLastEffort). */
+const STATE_FILE = path.join(os.homedir(), ".pi", ".pi-review-state.json");
+
+export type EffortSource = "explicit" | "last-used" | "default";
+
+/**
+ * Parse a leading effort level out of raw args; the remainder (flags + target)
+ * is returned verbatim. Pure — unit-testable.
+ */
+export function parseReviewArgs(args: string): { level: ReviewLevel | undefined; rest: string } {
+	const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	if (tokens.length === 0) return { level: undefined, rest: "" };
+	const first = tokens[0]!.toLowerCase();
+	const isLevel = (REVIEW_LEVELS as readonly string[]).includes(first);
+	return {
+		level: isLevel ? (first as ReviewLevel) : undefined,
+		rest: isLevel ? tokens.slice(1).join(" ") : tokens.join(" "),
+	};
+}
+
+/**
+ * Resolve the effective effort + where it came from. Pure — unit-testable.
+ * Explicit wins; otherwise the last-typed level; otherwise low.
+ */
+export function resolveEffort(
+	explicit: ReviewLevel | undefined,
+	lastUsed: ReviewLevel | undefined,
+): { level: ReviewLevel; source: EffortSource } {
+	if (explicit) return { level: explicit, source: "explicit" };
+	if (lastUsed) return { level: lastUsed, source: "last-used" };
+	return { level: DEFAULT_LEVEL, source: "default" };
+}
+
+// Best-effort persistence — sticky-effort is a convenience, not a correctness
+// invariant; a read/write failure must not break the review.
+function readLastEffort(): ReviewLevel | undefined {
+	try {
+		const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8")) as { codeReviewLastEffort?: unknown };
+		const v = raw.codeReviewLastEffort;
+		return typeof v === "string" && (REVIEW_LEVELS as readonly string[]).includes(v)
+			? (v as ReviewLevel)
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+function writeLastEffort(level: ReviewLevel): void {
+	try {
+		fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+		fs.writeFileSync(STATE_FILE, JSON.stringify({ codeReviewLastEffort: level }));
+	} catch {
+		/* ignore — non-critical */
+	}
+}
+
+// ---------------------------------------------------------------------------
+// /simplify — cleanup fan-out with the declared parallel strategy
+// ---------------------------------------------------------------------------
+
+/** v1 DIFF_TOO_LARGE_CHARS — kept for the single-pass "too large to read at
+ *  once" note (the strategy threshold itself lives in the template). */
+const DIFF_TOO_LARGE_CHARS = 400_000;
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerDispatcher(pi: ExtensionAPI): void {
+	pi.registerCommand("review", {
+		description:
+			"Review the current diff using the review skill. Usage: /review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]",
+		getArgumentCompletions(prefix) {
+			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--comment", "--share"];
+			return tokens.filter((t) => t.startsWith(prefix)).map((t) => ({ label: t, value: t }));
+		},
+		async handler(args, ctx) {
+			const { level: explicit, rest } = parseReviewArgs(args ?? "");
+			// Skip the read when we just wrote it — resolveEffort returns `explicit` unchanged.
+			const lastUsed = explicit ? undefined : readLastEffort();
+			if (explicit) writeLastEffort(explicit); // remember the explicit level
+			const { level, source } = resolveEffort(explicit, lastUsed);
+			const { body } = loadTemplate("review.md");
+			const budgets = loadTurnBudgets();
+			pi.sendUserMessage(
+				render(body, {
+					effort: level,
+					"effort-source": source,
+					"extra-args": rest ? `; extra args: ${rest}` : "",
+					skill: bundledSkillPath("review/SKILL.md"),
+					"finder-max-turns": String(budgets.subagent),
+					"verifier-max-turns": String(budgets.verifier),
+					"gap-hunt-max-turns": String(budgets.gapHunt),
+					// Consumed by the skill's --fix flow (apply → verify → re-report).
+					verify: verifyLine(ctx.cwd),
+				}),
+			);
+		},
+	});
+
+	pi.registerCommand("simplify", {
+		description:
+			"Clean up the changed code (reuse/simplification/efficiency/altitude) using the simplify skill. Mode (parallel 4-agent vs single-pass) is decided from the strategy declared in prompts/simplify.*.md (context usage, diff size, fan-out availability); PARALLEL opens with a visible Phase 0 before the subagent tool launches the agents. Usage: /simplify [<target>]",
+		async handler(args, ctx) {
+			try {
+				// ctx.signal (undefined while idle) lets Esc abort an in-flight diff.
+			const outcome = await getRepoDiff(ctx.cwd, args?.trim() || undefined, undefined, ctx.signal);
+				if (outcome.kind === "no-repo") {
+					ctx.ui.notify(`/simplify: ${ctx.cwd} is not inside a git repo — nothing to clean up.`, "warning");
+					return;
+				}
+				if (outcome.kind === "git-error") {
+					ctx.ui.notify(`/simplify: git failed — ${outcome.message}`, "error");
+					return;
+				}
+				if (outcome.kind === "empty") {
+					ctx.ui.notify(
+						`/simplify: no changes found (checked unpushed+uncommitted vs @{upstream}, uncommitted vs HEAD, staged, unstaged) — nothing to clean up.`,
+						"warning",
+					);
+					return;
+				}
+
+				const usage = ctx.getContextUsage();
+				const budgets = loadTurnBudgets(ctx.cwd);
+				const parallelTemplate = loadTemplate("simplify.parallel.md");
+				const { variant, reasons } = selectVariant(parseGuards(parallelTemplate.frontmatter), {
+					tokens: usage?.tokens ?? null,
+					contextWindow: usage?.contextWindow ?? 0,
+					diffChars: outcome.diff.length,
+					fanoutAvailable: isFanoutToolAllowed(),
+				});
+				const pct = usage && usage.percent != null ? `${Math.round(usage.percent)}%` : "?";
+				const target = args || "(whole diff)";
+				const skill = bundledSkillPath("simplify/SKILL.md");
+				const scopeLabel = DIFF_SCOPES[outcome.scopeKind];
+				const contextPackage = buildContextPackage(outcome.diff, outcome.gitRoot, scopeLabel);
+				const verify = verifyLine(outcome.gitRoot);
+
+				if (variant === "single-pass") {
+					const { body } = loadTemplate("simplify.single.md");
+					pi.sendUserMessage(
+						render(body, {
+							target,
+							reasons: reasons.join("; "),
+							"scope-label": scopeLabel,
+							"too-large":
+								outcome.diff.length >= DIFF_TOO_LARGE_CHARS
+									? `\nThe diff is too large to read at once — work through it file-by-file from the changed-file list above.\n`
+									: "",
+							"git-command": outcome.gitCommand,
+							"context-package": contextPackage,
+							skill,
+							verify,
+						}),
+					);
+					return;
+				}
+
+				pi.sendUserMessage(
+					render(parallelTemplate.body, {
+						target,
+						pct,
+						"scope-label": scopeLabel,
+						"git-command": outcome.gitCommand,
+						"context-package": contextPackage,
+						skill,
+						verify,
+						"simplify-max-turns": String(budgets.simplify),
+					}),
+				);
+			} catch (err) {
+				ctx.ui.notify(`/simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		},
+	});
+}