@fyeeme/pi-review 2.0.0 → 2.1.0

package/src/dispatch.ts

@@ -0,0 +1,301 @@
+/**
+ * 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 { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isFanoutToolAllowed } from "@fyeeme/pi-subagents";
+import * as fs from "node:fs";
+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 { extractLoopFlag, runLoopFixing } from "./loop.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,
+	);
+}
+
+// ---------------------------------------------------------------------------
+// /code-review — effort-level code review (v1 command semantics, relocated)
+// ---------------------------------------------------------------------------
+
+/** Effort levels the /code-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). Shares the config file so users have a single
+ *  pi-review.json; the field is written alongside `maxTurns`, never over it. */
+const STATE_FILE = path.join(getAgentDir(), "pi-review.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.
+ */
+/** True when the effort level uses the xhigh/max finder/verifier fan-out;
+ *  false for the single-pass levels (low/medium/high). Pure — unit-testable. */
+export function usesFanout(level: ReviewLevel): boolean {
+	return level === "xhigh" || level === "max";
+}
+
+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 {
+		// The state field shares a file with user-authored config (maxTurns), so
+		// read-modify-write instead of overwriting, and never clobber a
+		// hand-edited file we cannot parse.
+		let existing: Record<string, unknown> = {};
+		if (fs.existsSync(STATE_FILE)) {
+			let raw: unknown;
+			try {
+				raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+			} catch {
+				return;
+			}
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+			existing = raw as Record<string, unknown>;
+		}
+		existing.codeReviewLastEffort = level;
+		fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+		fs.writeFileSync(STATE_FILE, `${JSON.stringify(existing, null, 2)}\n`);
+	} catch {
+		/* ignore — non-critical */
+	}
+}
+
+// ---------------------------------------------------------------------------
+// /code-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("code-review", {
+		description:
+			"Review the current diff using the code-review skill. low/medium/high review in a single pass in this session; xhigh/max fan out finder/verifier agents. Usage: /code-review [low|medium|high|xhigh|max] [--fix] [--loop] [--comment] [--share] [<pr#>|<branch>|<path>]",
+		getArgumentCompletions(prefix) {
+			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--loop", "--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 budgets = loadTurnBudgets();
+
+			// Effort split: low/medium/high review in ONE pass in the main session
+			// (no subprocess fan-out); xhigh/max keep the finder/verifier pipeline.
+			const fanout = usesFanout(level);
+
+			// --loop is extension-level (drives fix→re-review rounds against the
+			// structured report), so it never reaches the skill text. It needs a
+			// single report turn to loop on — fan-out levels have no such turn.
+			const { wantLoop, rest: flagsRest } = extractLoopFlag(rest);
+			const loopArmed = wantLoop && !fanout;
+			if (wantLoop && fanout) {
+				ctx.ui.notify(
+					`/code-review: --loop applies to single-pass levels (low/medium/high) — ignored for ${level}.`,
+					"warning",
+				);
+			}
+
+			const { body } = loadTemplate(fanout ? "review.parallel.md" : "review.single.md");
+			const shared = {
+				effort: level,
+				"effort-source": source,
+				"extra-args": flagsRest ? `; extra args: ${flagsRest}` : "",
+				skill: bundledSkillPath("code-review/SKILL.md"),
+				// Consumed by the skill's --fix flow (apply → verify → re-report).
+				verify: verifyLine(ctx.cwd),
+			};
+			void pi.sendUserMessage(
+				render(
+					body,
+					fanout
+						? {
+								...shared,
+								"finder-max-turns": String(budgets.subagent),
+								"verifier-max-turns": String(budgets.verifier),
+								"gap-hunt-max-turns": String(budgets.gapHunt),
+							}
+						: {
+								...shared,
+								// Told to the session so every finding carries a P0–P3 priority.
+								"loop-note": loopArmed
+									? `\nLoop fixing is armed: after your report, the extension drives up to ${budgets.loop} fix→re-review rounds until no P0/P1 findings remain — so tag every finding with a priority (P0–P3).\n`
+									: "",
+							},
+				),
+			);
+			if (loopArmed) {
+				await runLoopFixing(pi, ctx, {
+					level,
+					passes: budgets.loop,
+					// Must match where review_report writes (CONFIG_DIR_NAME,
+					// not necessarily ".pi") or the loop never finds a report.
+					reviewDir: path.join(ctx.cwd, CONFIG_DIR_NAME, "review"),
+				});
+			}
+		},
+	});
+
+	pi.registerCommand("code-simplify", {
+		description:
+			"Clean up the changed code (reuse/simplification/efficiency/altitude) using the code-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: /code-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(`/code-simplify: ${ctx.cwd} is not inside a git repo — nothing to clean up.`, "warning");
+					return;
+				}
+				if (outcome.kind === "git-error") {
+					ctx.ui.notify(`/code-simplify: git failed — ${outcome.message}`, "error");
+					return;
+				}
+				if (outcome.kind === "empty") {
+					ctx.ui.notify(
+						`/code-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("code-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(`/code-simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		},
+	});
+}

package/src/loop.ts

@@ -0,0 +1,266 @@
+/**
+ * src/loop.ts — /code-review --loop: extension-driven fix→re-review cycles.
+ *
+ * Ported from the standalone Codex-style review extension's loop fixing
+ * (review → blocking-check → fix → re-review, bounded), with one deliberate
+ * deviation: the blocking decision reads the structured `review_report` JSON
+ * the skill must have written under the project's pi config dir
+ * (<cwd>/.pi/review/ by default — CONFIG_DIR_NAME) instead of scraping the
+ * assistant's markdown. The tool call is the report, so the JSON is the
+ * reliable artifact; markdown scraping was only ever a fallback.
+ *
+ * Loop shape (single-pass levels only — low/medium/high):
+ *   review turn → read newest report → OPEN P0/P1 findings (P0/P1 without a
+ *     decided outcome — a fix turn's re-report marks its findings
+ *     fixed/skipped/no_change_needed)?
+ *     none            → done
+ *     some, rounds left → fix prompt (followUp) → idle → re-review prompt → next round
+ *     some, rounds spent → stop with a safety-limit note
+ * Esc/abort or a missing report stops the loop.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { OUTCOME_VALUES } from "./tools/review_report.ts";
+
+// --- pure helpers (unit-tested) ---------------------------------------------
+
+export const BLOCKING_PRIORITIES = ["P0", "P1"] as const;
+
+/** Strip a --loop flag out of the trailing args; report whether it was there.
+ *  Pure — unit-testable. */
+export function extractLoopFlag(rest: string): { wantLoop: boolean; rest: string } {
+	const tokens = (rest ?? "").split(/\s+/).filter(Boolean);
+	const kept = tokens.filter((t) => t !== "--loop");
+	return { wantLoop: kept.length !== tokens.length, rest: kept.join(" ") };
+}
+
+/** A blocking finding as surfaced back to the fix prompt. */
+export interface BlockingFinding {
+	file: string;
+	line?: number;
+	priority: string;
+	summary: string;
+}
+
+/** Extract P0/P1 findings from a parsed review_report JSON (lenient: any
+ *  shape mismatch → no findings rather than a throw). Pure — unit-testable. */
+export function blockingFindings(report: unknown): BlockingFinding[] {
+	if (!report || typeof report !== "object" || Array.isArray(report)) return [];
+	const raw = (report as { findings?: unknown }).findings;
+	if (!Array.isArray(raw)) return [];
+	const out: BlockingFinding[] = [];
+	for (const f of raw) {
+		if (!f || typeof f !== "object" || Array.isArray(f)) continue;
+		const rec = f as Record<string, unknown>;
+		if (rec.priority !== "P0" && rec.priority !== "P1") continue;
+		if (typeof rec.file !== "string" || rec.file.length === 0) continue;
+		// A decided outcome (a fix turn re-reports its findings with one, per
+		// the skill's fixed-later obligation) un-blocks the finding —
+		// re-prompting a fixed/skipped/declined finding just burns rounds.
+		if (typeof rec.outcome === "string" && (OUTCOME_VALUES as readonly string[]).includes(rec.outcome)) {
+			continue;
+		}
+		out.push({
+			file: rec.file,
+			line: typeof rec.line === "number" ? rec.line : undefined,
+			priority: rec.priority,
+			summary: typeof rec.summary === "string" ? rec.summary : "",
+		});
+	}
+	return out;
+}
+
+/** Newest `*.json` report under `dir` modified after `sinceMs`, or null.
+ *  Missing/unreadable dir → null. Pure — unit-testable. */
+export function latestReportFile(dir: string, sinceMs: number): string | null {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return null;
+	}
+	let newest: { file: string; mtime: number } | null = null;
+	for (const e of entries) {
+		if (!e.isFile() || !e.name.endsWith(".json")) continue;
+		const file = path.join(dir, e.name);
+		try {
+			const mtime = fs.statSync(file).mtimeMs;
+			if (mtime <= sinceMs) continue;
+			if (!newest || mtime > newest.mtime) newest = { file, mtime };
+		} catch {
+			/* stat failed — skip this entry */
+		}
+	}
+	return newest?.file ?? null;
+}
+
+/** Parse a report JSON file; garbage → null (the loop must not crash on a
+ *  half-written or hand-edited file). */
+function readReport(file: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+// --- loop driver -------------------------------------------------------------
+
+/** Minimal session view for the quiescence wait — structural, so
+ *  ExtensionCommandContext satisfies it and tests can drive the logic
+ *  without a live session. */
+export interface QuiescenceView {
+	isIdle(): boolean;
+	hasPendingMessages(): boolean;
+	waitForIdle(): Promise<void>;
+	signal?: { aborted: boolean };
+}
+
+/** Wait until the session is fully quiescent: nothing running AND nothing
+ *  queued. A single `waitForIdle()` is NOT enough — it resolves at the first
+ *  idle point even while follow-ups are still queued (a queued message does
+ *  not flip `isIdle` until its run actually starts), which is exactly the
+ *  window between `sendUserMessage(…, followUp)` and that turn's first
+ *  token. Aborts return false; there is no timeout — Esc is the escape
+ *  hatch, same as for the bare waitForIdle call. */
+export async function waitForQuiescent(session: QuiescenceView): Promise<boolean> {
+	for (;;) {
+		if (session.signal?.aborted) return false;
+		if (!session.isIdle() || session.hasPendingMessages()) {
+			await session.waitForIdle();
+			continue;
+		}
+		return true;
+	}
+}
+
+/** Poll until the review turn has started (idle → busy or a new assistant
+ *  message appears), then wait for it to finish. Returns false on timeout
+ *  or abort. Mirrors the reference extension's waitForLoopTurnToStart. */
+async function waitForTurnSettled(ctx: ExtensionCommandContext, baselineAssistantId: string): Promise<boolean> {
+	const START_TIMEOUT_MS = 15_000;
+	const POLL_MS = 50;
+	const deadline = Date.now() + START_TIMEOUT_MS;
+
+	const lastAssistantId = (): string | undefined => {
+		const branch = ctx.sessionManager.getBranch();
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const entry = branch[i]!;
+			if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+		}
+		return undefined;
+	};
+
+	while (Date.now() < deadline) {
+		if (ctx.signal?.aborted) return false;
+		const current = lastAssistantId();
+		if (!ctx.isIdle() || ctx.hasPendingMessages() || (current && current !== baselineAssistantId)) {
+			// Wait past every queued message, not merely to the next idle
+			// point — waitForIdle() alone returns inside the gap between
+			// queueing a followUp and its run actually starting.
+			return waitForQuiescent(ctx);
+		}
+		await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+	}
+	return false;
+}
+
+function baselineAssistantId(ctx: ExtensionCommandContext): string {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i]!;
+		if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+	}
+	return "";
+}
+
+function fixPrompt(findings: BlockingFinding[]): string {
+	const list = findings
+		.map((f) => `- \`${f.file}${f.line != null ? `:${f.line}` : ""}\` [${f.priority}] ${f.summary}`)
+		.join("\n");
+	return [
+		"Fix the following blocking findings from the code review you just reported",
+		"(full failure scenarios are in the latest report JSON under .pi/review/):",
+		"",
+		list,
+		"",
+		"Apply minimal, surgical fixes — no drive-by refactors. Then re-report these",
+		"findings via the `review_report` tool with `outcome` set per finding",
+		"(fixed / skipped / no_change_needed) and run the verification guidance from",
+		"the review trigger message. Never leave the working tree verified-broken.",
+	].join("\n");
+}
+
+function reReviewPrompt(level: string): string {
+	return [
+		`Fixes applied. Re-run the code-review SINGLE-PASS flow for effort ${level} now`,
+		"— the diff has changed: re-resolve it, re-check the fixed locations and",
+		"sweep for regressions or newly exposed issues, then report via the",
+		"`review_report` tool again (fresh findings list, empty array if clean).",
+	].join("\n");
+}
+
+export interface LoopOptions {
+	/** The effort level the review runs at (echoed in re-review prompts). */
+	level: string;
+	/** Max fix→re-review rounds (config maxTurns.loop). */
+	passes: number;
+	/** Directory the review_report JSON files land in. */
+	reviewDir: string;
+}
+
+/**
+ * Drive the fix→re-review rounds after the FIRST review prompt has already
+ * been sent by the dispatcher. Each iteration reads the newest report (the
+ * first iteration sees the initial review's report, later ones the previous
+ * round's re-review) and sends at most one fix prompt. Runs at most `passes`
+ * fix→re-review rounds; the final iteration only reads the last re-review's
+ * verdict for the safety-limit message. Returns the number of fix rounds run.
+ */
+export async function runLoopFixing(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	options: LoopOptions,
+): Promise<number> {
+	const { level, passes, reviewDir } = options;
+	const baseline = baselineAssistantId(ctx);
+	const loopStart = Date.now();
+
+	let fixes = 0;
+	for (;;) {
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+
+		const reportFile = latestReportFile(reviewDir, loopStart);
+		if (reportFile === null) {
+			ctx.ui.notify("/code-review --loop: no review_report JSON found — stopping the loop.", "warning");
+			return fixes;
+		}
+		const findings = blockingFindings(readReport(reportFile));
+		if (findings.length === 0) {
+			ctx.ui.notify(
+				fixes === 0
+					? "/code-review --loop: no P0/P1 findings — nothing to fix, loop done."
+					: `/code-review --loop: clean after ${fixes} fix round(s) — no open P0/P1 findings remain.`,
+				"info",
+			);
+			return fixes;
+		}
+		if (fixes === passes) {
+			ctx.ui.notify(
+				`/code-review --loop: ${findings.length} P0/P1 finding(s) still open after ${passes} fix round(s) — safety limit reached, stopping.`,
+				"warning",
+			);
+			return fixes;
+		}
+
+		fixes++;
+		ctx.ui.notify(
+			`/code-review --loop: ${findings.length} blocking finding(s) — fixing (round ${fixes}/${passes})…`,
+			"info",
+		);
+		await pi.sendUserMessage(fixPrompt(findings), { deliverAs: "followUp" });
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+		pi.sendUserMessage(reReviewPrompt(level), { deliverAs: "followUp" });
+	}
+}

package/src/strategy.ts

@@ -0,0 +1,76 @@
+/**
+ * src/strategy.ts — declarative parallel-strategy evaluation.
+ *
+ * v1's decideSimplifyMode hardcoded its thresholds in the command handler;
+ * v2 declares them as data in the prompt templates' frontmatter and this
+ * module evaluates the declared guards against runtime variables. Same
+ * semantics, different authority: editing a template's `parallel-when`
+ * block changes the strategy with no code change.
+ *
+ * Fallback-when-unguarded rules (v1 semantics, kept in code because they
+ * are safety invariants, not tuning knobs): unmeasurable context and an
+ * unavailable fan-out tool always select single-pass.
+ */
+
+/** Guards declared in a template's `parallel-when` frontmatter block. */
+export interface ParallelGuards {
+	/** Select single-pass when context usage is at or above this fraction. */
+	readonly contextBelow?: number;
+	/** Select single-pass when the diff reaches this many chars. */
+	readonly diffCharsBelow?: number;
+}
+
+/** Runtime variables gathered by the dispatcher. */
+export interface StrategyRuntime {
+	readonly tokens: number | null;
+	readonly contextWindow: number;
+	readonly diffChars: number;
+	/** Whether fan-out tools are registered in this process (the recursion
+	 *  guard): single-pass is the only option when false. */
+	readonly fanoutAvailable: boolean;
+}
+
+export type ReviewVariant = "parallel" | "single-pass";
+
+/**
+ * Evaluate the declared guards. Returns the variant plus the reasons that
+ * produced it (rendered into the trigger message so the decision stays
+ * observable). Pure — unit-testable.
+ */
+export function selectVariant(
+	guards: ParallelGuards,
+	runtime: StrategyRuntime,
+): { variant: ReviewVariant; reasons: string[] } {
+	const { tokens, contextWindow, diffChars, fanoutAvailable } = runtime;
+	const reasons: string[] = [];
+	// Conservative safety invariant (not a tunable): if we can't measure
+	// context (tokens unknown / window 0), don't risk fan-out.
+	if (tokens == null || contextWindow <= 0) reasons.push("context usage unknown");
+	if (
+		guards.contextBelow != null &&
+		tokens != null &&
+		contextWindow > 0 &&
+		tokens / contextWindow >= guards.contextBelow
+	)
+		reasons.push(`context ${Math.round((tokens / contextWindow) * 100)}% full`);
+	if (guards.diffCharsBelow != null && diffChars >= guards.diffCharsBelow)
+		reasons.push(`diff too large (${Math.round(diffChars / 1024)} KB ≥ fan-out threshold)`);
+	if (!fanoutAvailable) reasons.push("fan-out unavailable in this context (subagent recursion guard)");
+	return { variant: reasons.length > 0 ? "single-pass" : "parallel", reasons };
+}
+
+/** Parse the `parallel-when` block out of a template's frontmatter map.
+ *  Unknown/garbage fields are dropped (silent — garbage becomes absent). */
+export function parseGuards(frontmatter: Record<string, unknown>): ParallelGuards {
+	const raw = frontmatter["parallel-when"];
+	if (!raw || typeof raw !== "object") return {};
+	const r = raw as Record<string, unknown>;
+	const out: { contextBelow?: number; diffCharsBelow?: number } = {};
+	if (typeof r["context-below"] === "number" && r["context-below"] > 0 && r["context-below"] <= 1) {
+		out.contextBelow = r["context-below"];
+	}
+	if (typeof r["diff-chars-below"] === "number" && r["diff-chars-below"] > 0) {
+		out.diffCharsBelow = r["diff-chars-below"];
+	}
+	return out;
+}