@fyeeme/pi-review 2.0.1 → 2.1.1

package/skills/{simplify → code-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 /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."
+name: code-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; 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 /simplify.
+  engineered from bin/claude.exe raw bytes. Pi registers it as /code-simplify.
 
   Lineage:
     v2.1.220 → the first reconstruction         (v1)
@@ -26,7 +26,7 @@ description: "Review the changed code for reuse, simplification, efficiency, and
                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
+               The /code-review↔/code-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):
@@ -46,9 +46,9 @@ description: "Review the changed code for reuse, simplification, efficiency, and
       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).
+  Bundled: ships inside the pi-review extension (skills/code-simplify/SKILL.md).
 
-  Invocation: /simplify [<target>]
+  Invocation: /code-simplify [<target>]
     target = file path | PR number | branch name
 
   ════════════════════════════════════════════════════════════════════════
@@ -69,10 +69,10 @@ description: "Review the changed code for reuse, simplification, efficiency, and
        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
+       DETERMINISTICALLY by the /code-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: /simplify.
+    3. Command     — CC: /simplify; Pi: /code-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
@@ -94,9 +94,9 @@ description: "Review the changed code for reuse, simplification, efficiency, and
 
 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 `/review` is for.
+find. Do not look for correctness bugs — that is what `/code-review` is for.
 
-The `/simplify` handler has already chosen the mode (PARALLEL or
+The `/code-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
@@ -106,7 +106,7 @@ VISIBLE, model-run step before anything launches.
 ## Phase 0 — Gather the diff
 
 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
+/code-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
@@ -125,7 +125,7 @@ review that target instead. Treat this diff as the review scope.)
 
 # PARALLEL MODE  (context not near-full AND diff under the fan-out threshold AND fan-out available)
 
-`/simplify → visible Phase 0 (read the diff, summarize) → subagent tool (parallel, 4 cleaner agents) → apply the fixes`
+`/code-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)
 
@@ -184,7 +184,7 @@ Follow the shared **Phase 2** procedure at the end of this skill (snapshot → a
 
 # SINGLE-PASS MODE  (context near-full OR diff too large OR fan-out unavailable)
 
-`/simplify → handler decided single-pass (reasons in the trigger message) → inline cleanup → apply the fixes`
+`/code-simplify → handler decided single-pass (reasons in the trigger message) → inline cleanup → apply the fixes`
 
 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
@@ -237,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 `/simplify` from
+verify, and report. This safety net is what distinguishes `/code-simplify` from
 a blind cleanup: a finding is only "done" once it is applied AND the project
 still verifies — otherwise it is reverted.
 
@@ -258,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 `/simplify`'s fixes,
+uncommitted changes — reverting to it undoes only `/code-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

@@ -10,19 +10,20 @@
  *
  *   {
  *     "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
+ *       "subagent": 20,   // per-call budget for each /code-review finder batch (xhigh/max)
+ *       "gapHunt":  15,   // budget for the /code-review Phase 3 gap-hunter (xhigh/max)
+ *       "simplify": 15,   // budget for each /code-simplify PARALLEL cleaner agent
+ *       "loop": 3         // --loop fix→re-review round cap (single-pass levels)
  *     }
  *   }
  *
  * 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
+ * written with (finder 20 / gap-hunt 15 / simplify 15 / loop 3). 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
+ * takes effect on the next /code-review or /code-simplify without a restart. Malformed
  * files are ignored with a stderr warning (never fatal); unknown/garbage
  * fields are dropped on read.
  */
@@ -33,16 +34,18 @@ 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. */
+/** The dispatchable turn budgets, keyed by what they throttle. */
 export interface TurnBudgets {
-	/** `maxTurns` set on each /review finder-batch `subagent` call. */
+	/** `maxTurns` set on each /code-review finder-batch `subagent` call. */
 	subagent: number;
-	/** `maxTurns` set on each /review Phase 2 verifier `subagent` call. */
+	/** `maxTurns` set on each /code-review Phase 2 verifier `subagent` call. */
 	verifier: number;
-	/** `maxTurns` set on the /review Phase 3 gap-hunt `subagent` call. */
+	/** `maxTurns` set on the /code-review Phase 3 gap-hunt `subagent` call. */
 	gapHunt: number;
-	/** `maxTurns` set on each /simplify PARALLEL cleaner `subagent` call. */
+	/** `maxTurns` set on each /code-simplify PARALLEL cleaner `subagent` call. */
 	simplify: number;
+	/** Max fix→re-review rounds when /code-review runs with --loop. */
+	loop: number;
 }
 
 /** Built-in budgets — identical to the literals in prompts/ and skills/. */
@@ -51,6 +54,7 @@ export const DEFAULT_TURN_BUDGETS: TurnBudgets = {
 	verifier: 15,
 	gapHunt: 15,
 	simplify: 15,
+	loop: 3,
 };
 
 function globalPath(): string {
@@ -85,6 +89,8 @@ function readBudgetsFile(path: string): Partial<TurnBudgets> {
 		if (gapHunt !== undefined) out.gapHunt = gapHunt;
 		const simplify = sanitizeBudget(mt.simplify);
 		if (simplify !== undefined) out.simplify = simplify;
+		const loop = sanitizeBudget(mt.loop);
+		if (loop !== undefined) out.loop = loop;
 		return out;
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);

package/src/diff.ts

@@ -30,7 +30,7 @@ export function findGitRoot(from: string): string | null {
 	}
 }
 
-/** Normalize a /simplify target argument: trimmed, with an optional
+/** Normalize a /code-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. */
@@ -38,7 +38,7 @@ function normalizeTarget(target: string | undefined): string {
 	return (target ?? "").trim();
 }
 
-/** Resolve the diff scope for a review/simplify target. Pure — unit-testable.
+/** Resolve the diff scope for a code-review/code-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

package/src/dispatch.ts

@@ -13,14 +13,14 @@
  * 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 { 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 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 { extractLoopFlag, runLoopFixing } from "./loop.ts";
 import { bundledSkillPath } from "./skills.ts";
 import { parseGuards, selectVariant } from "./strategy.ts";
 
@@ -51,17 +51,19 @@ export function render(body: string, vars: Record<string, string>): string {
 }
 
 // ---------------------------------------------------------------------------
-// /review — effort-level code review (v1 command semantics, relocated)
+// /code-review — effort-level code review (v1 command semantics, relocated)
 // ---------------------------------------------------------------------------
 
-/** Effort levels the /review command accepts (mirrors CC's effort enum). */
+/** 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). */
-const STATE_FILE = path.join(os.homedir(), ".pi", ".pi-review-state.json");
+/** 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";
 
@@ -69,6 +71,12 @@ 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: "" };
@@ -108,15 +116,30 @@ function readLastEffort(): ReviewLevel | 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({ codeReviewLastEffort: level }));
+		fs.writeFileSync(STATE_FILE, `${JSON.stringify(existing, null, 2)}\n`);
 	} catch {
 		/* ignore — non-critical */
 	}
 }
 
 // ---------------------------------------------------------------------------
-// /simplify — cleanup fan-out with the declared parallel strategy
+// /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
@@ -128,11 +151,11 @@ const DIFF_TOO_LARGE_CHARS = 400_000;
 // ---------------------------------------------------------------------------
 
 export function registerDispatcher(pi: ExtensionAPI): void {
-	pi.registerCommand("review", {
+	pi.registerCommand("code-review", {
 		description:
-			"Review the current diff using the review skill. Usage: /review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]",
+			"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", "--comment", "--share"];
+			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) {
@@ -141,42 +164,82 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 			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),
-				}),
+
+			// 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("simplify", {
+	pi.registerCommand("code-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>]",
+			"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(`/simplify: ${ctx.cwd} is not inside a git repo — nothing to clean up.`, "warning");
+					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(`/simplify: git failed — ${outcome.message}`, "error");
+					ctx.ui.notify(`/code-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.`,
+						`/code-simplify: no changes found (checked unpushed+uncommitted vs @{upstream}, uncommitted vs HEAD, staged, unstaged) — nothing to clean up.`,
 						"warning",
 					);
 					return;
@@ -193,7 +256,7 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 				});
 				const pct = usage && usage.percent != null ? `${Math.round(usage.percent)}%` : "?";
 				const target = args || "(whole diff)";
-				const skill = bundledSkillPath("simplify/SKILL.md");
+				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);
@@ -231,7 +294,7 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 					}),
 				);
 			} catch (err) {
-				ctx.ui.notify(`/simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+				ctx.ui.notify(`/code-simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
 			}
 		},
 	});