mitsupi 1.4.0 → 1.6.0

package/{pi-extensions → extensions}/review.ts

@@ -7,7 +7,7 @@
  * - Review against a base branch (PR style)
  * - Review uncommitted changes
  * - Review a specific commit
- * - Custom review instructions
+ * - Shared custom review instructions (applied to all review modes when configured)
  *
  * Usage:
  * - `/review` - show interactive selector
@@ -17,7 +17,8 @@
  * - `/review branch main` - review against main branch
  * - `/review commit abc123` - review specific commit
  * - `/review folder src docs` - review specific folders/files (snapshot, not diff)
- * - `/review custom "check for security issues"` - custom instructions
+ * - `/review` selector includes Add/Remove custom review instructions (applies to all modes)
+ * - `/review --extra "focus on performance regressions"` - add extra review instruction (works with any mode)
  *
  * Project-specific review guidelines:
  * - If a REVIEW_GUIDELINES.md file exists in the same directory as .pi,
@@ -31,7 +32,6 @@ import { DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
 import {
 	Container,
 	fuzzyFilter,
-	getEditorKeybindings,
 	Input,
 	type SelectItem,
 	SelectList,
@@ -47,6 +47,7 @@ import { promises as fs } from "node:fs";
 let reviewOriginId: string | undefined = undefined;
 let endReviewInProgress = false;
 let reviewLoopFixingEnabled = false;
+let reviewCustomInstructions: string | undefined = undefined;
 let reviewLoopInProgress = false;
 
 const REVIEW_STATE_TYPE = "review-session";
@@ -63,6 +64,7 @@ type ReviewSessionState = {
 
 type ReviewSettingsState = {
 	loopFixingEnabled?: boolean;
+	customInstructions?: string;
 };
 
 function setReviewWidget(ctx: ExtensionContext, active: boolean) {
@@ -124,12 +126,14 @@ function getReviewSettings(ctx: ExtensionContext): ReviewSettingsState {
 
 	return {
 		loopFixingEnabled: state?.loopFixingEnabled === true,
+		customInstructions: state?.customInstructions?.trim() || undefined,
 	};
 }
 
 function applyReviewSettings(ctx: ExtensionContext) {
 	const state = getReviewSettings(ctx);
 	reviewLoopFixingEnabled = state.loopFixingEnabled === true;
+	reviewCustomInstructions = state.customInstructions?.trim() || undefined;
 }
 
 function parseMarkdownHeading(line: string): { level: number; title: string } | null {
@@ -351,7 +355,6 @@ type ReviewTarget =
 	| { type: "uncommitted" }
 	| { type: "baseBranch"; branch: string }
 	| { type: "commit"; sha: string; title?: string }
-	| { type: "custom"; instructions: string }
 	| { type: "pullRequest"; prNumber: number; baseBranch: string; title: string }
 	| { type: "folder"; paths: string[] };
 
@@ -401,6 +404,7 @@ Flag issues that:
 7. Have provable impact on other parts of the code — it is not enough to speculate that a change may disrupt another part, you must identify the parts that are provably affected.
 8. Are clearly not intentional changes by the author.
 9. Be particularly careful with untrusted user input and follow the specific guidelines to review.
+10. Treat silent local error recovery (especially parsing/IO/network fallbacks) as high-signal review candidates unless there is explicit boundary-level justification.
 
 ## Untrusted User Input
 
@@ -423,13 +427,46 @@ Flag issues that:
 
 ## Review priorities
 
-1. Call out newly added dependencies explicitly and explain why they're needed.
+1. Surface critical non-blocking human callouts (migrations, dependency churn, auth/permissions, compatibility, destructive operations) at the end.
 2. Prefer simple, direct solutions over wrappers or abstractions without clear value.
-3. Favor fail-fast behavior; avoid logging-and-continue patterns that hide errors.
-4. Prefer predictable production behavior; crashing is better than silent degradation.
-5. Treat back pressure handling as critical to system stability.
-6. Apply system-level thinking; flag changes that increase operational risk or on-call wakeups.
-7. Ensure that errors are always checked against codes or stable identifiers, never error messages.
+3. Treat back pressure handling as critical to system stability.
+4. Apply system-level thinking; flag changes that increase operational risk or on-call wakeups.
+5. Ensure that errors are always checked against codes or stable identifiers, never error messages.
+
+## Fail-fast error handling (strict)
+
+When reviewing added or modified error handling, default to fail-fast behavior.
+
+1. Evaluate every new or changed \`try/catch\`: identify what can fail and why local handling is correct at that exact layer.
+2. Prefer propagation over local recovery. If the current scope cannot fully recover while preserving correctness, rethrow (optionally with context) instead of returning fallbacks.
+3. Flag catch blocks that hide failure signals (e.g. returning \`null\`/\`[]\`/\`false\`, swallowing JSON parse failures, logging-and-continue, or “best effort” silent recovery).
+4. JSON parsing/decoding should fail loudly by default. Quiet fallback parsing is only acceptable with an explicit compatibility requirement and clear tested behavior.
+5. Boundary handlers (HTTP routes, CLI entrypoints, supervisors) may translate errors, but must not pretend success or silently degrade.
+6. If a catch exists only to satisfy lint/style without real handling, treat it as a bug.
+7. When uncertain, prefer crashing fast over silent degradation.
+
+## Required human callouts (non-blocking, at the very end)
+
+After findings/verdict, you MUST append this final section:
+
+## Human Reviewer Callouts (Non-Blocking)
+
+Include only applicable callouts (no yes/no lines):
+
+- **This change adds a database migration:** <files/details>
+- **This change introduces a new dependency:** <package(s)/details>
+- **This change changes a dependency (or the lockfile):** <files/package(s)/details>
+- **This change modifies auth/permission behavior:** <what changed and where>
+- **This change introduces backwards-incompatible public schema/API/contract changes:** <what changed and where>
+- **This change includes irreversible or destructive operations:** <operation and scope>
+
+Rules for this section:
+1. These are informational callouts for the human reviewer, not fix items.
+2. Do not include them in Findings unless there is an independent defect.
+3. These callouts alone must not change the verdict.
+4. Only include callouts that apply to the reviewed change.
+5. Keep each emitted callout bold exactly as written.
+6. If none apply, write "- (none)".
 
 ## Priority levels
 
@@ -445,11 +482,12 @@ Provide your findings in a clear, structured format:
 1. List each finding with its priority tag, file location, and explanation.
 2. Findings must reference locations that overlap with the actual diff — don't flag pre-existing code.
 3. Keep line references as short as possible (avoid ranges over 5-10 lines; pick the most suitable subrange).
-4. At the end, provide an overall verdict: "correct" (no blocking issues) or "needs attention" (has blocking issues).
+4. Provide an overall verdict: "correct" (no blocking issues) or "needs attention" (has blocking issues).
 5. Ignore trivial style issues unless they obscure meaning or violate documented standards.
 6. Do not generate a full PR fix — only flag issues and optionally provide short suggestion blocks.
+7. End with the required "Human Reviewer Callouts (Non-Blocking)" section and all applicable bold callouts (no yes/no).
 
-Output all findings the author would fix if they knew about them. If there are no qualifying findings, explicitly state the code looks good. Don't stop at the first finding - list every qualifying issue.`;
+Output all findings the author would fix if they knew about them. If there are no qualifying findings, explicitly state the code looks good. Don't stop at the first finding - list every qualifying issue. Then append the required non-blocking callouts section.`;
 
 async function loadProjectReviewGuidelines(cwd: string): Promise<string | null> {
 	let currentDir = path.resolve(cwd);
@@ -683,9 +721,6 @@ async function buildReviewPrompt(
 			}
 			return COMMIT_PROMPT.replace("{sha}", target.sha);
 
-		case "custom":
-			return target.instructions;
-
 		case "pullRequest": {
 			const mergeBase = await getMergeBase(pi, target.baseBranch);
 			const basePrompt = mergeBase
@@ -719,8 +754,6 @@ function getUserFacingHint(target: ReviewTarget): string {
 			const shortSha = target.sha.slice(0, 7);
 			return target.title ? `commit ${shortSha}: ${target.title}` : `commit ${shortSha}`;
 		}
-		case "custom":
-			return target.instructions.length > 40 ? target.instructions.slice(0, 37) + "..." : target.instructions;
 
 		case "pullRequest": {
 			const shortTitle = target.title.length > 30 ? target.title.slice(0, 27) + "..." : target.title;
@@ -802,16 +835,31 @@ const REVIEW_PRESETS = [
 	{ value: "commit", label: "Review a commit", description: "" },
 	{ value: "pullRequest", label: "Review a pull request", description: "(GitHub PR)" },
 	{ value: "folder", label: "Review a folder (or more)", description: "(snapshot, not diff)" },
-	{ value: "custom", label: "Custom review instructions", description: "" },
 ] as const;
 
 const TOGGLE_LOOP_FIXING_VALUE = "toggleLoopFixing" as const;
-type ReviewPresetValue = (typeof REVIEW_PRESETS)[number]["value"] | typeof TOGGLE_LOOP_FIXING_VALUE;
+const TOGGLE_CUSTOM_INSTRUCTIONS_VALUE = "toggleCustomInstructions" as const;
+type ReviewPresetValue =
+	| (typeof REVIEW_PRESETS)[number]["value"]
+	| typeof TOGGLE_LOOP_FIXING_VALUE
+	| typeof TOGGLE_CUSTOM_INSTRUCTIONS_VALUE;
 
 export default function reviewExtension(pi: ExtensionAPI) {
+	function persistReviewSettings() {
+		pi.appendEntry(REVIEW_SETTINGS_TYPE, {
+			loopFixingEnabled: reviewLoopFixingEnabled,
+			customInstructions: reviewCustomInstructions,
+		});
+	}
+
 	function setReviewLoopFixingEnabled(enabled: boolean) {
 		reviewLoopFixingEnabled = enabled;
-		pi.appendEntry(REVIEW_SETTINGS_TYPE, { loopFixingEnabled: enabled });
+		persistReviewSettings();
+	}
+
+	function setReviewCustomInstructions(instructions: string | undefined) {
+		reviewCustomInstructions = instructions?.trim() || undefined;
+		persistReviewSettings();
 	}
 
 	function applyAllReviewState(ctx: ExtensionContext) {
@@ -865,10 +913,21 @@ export default function reviewExtension(pi: ExtensionAPI) {
 		const smartDefaultIndex = presetItems.findIndex((item) => item.value === smartDefault);
 
 		while (true) {
+			const customInstructionsLabel = reviewCustomInstructions
+				? "Remove custom review instructions"
+				: "Add custom review instructions";
+			const customInstructionsDescription = reviewCustomInstructions
+				? "(currently set)"
+				: "(applies to all review modes)";
 			const loopToggleLabel = reviewLoopFixingEnabled ? "Disable Loop Fixing" : "Enable Loop Fixing";
 			const loopToggleDescription = reviewLoopFixingEnabled ? "(currently on)" : "(currently off)";
 			const items: SelectItem[] = [
 				...presetItems,
+				{
+					value: TOGGLE_CUSTOM_INSTRUCTIONS_VALUE,
+					label: customInstructionsLabel,
+					description: customInstructionsDescription,
+				},
 				{ value: TOGGLE_LOOP_FIXING_VALUE, label: loopToggleLabel, description: loopToggleDescription },
 			];
 
@@ -920,6 +979,28 @@ export default function reviewExtension(pi: ExtensionAPI) {
 				continue;
 			}
 
+			if (result === TOGGLE_CUSTOM_INSTRUCTIONS_VALUE) {
+				if (reviewCustomInstructions) {
+					setReviewCustomInstructions(undefined);
+					ctx.ui.notify("Custom review instructions removed", "info");
+					continue;
+				}
+
+				const customInstructions = await ctx.ui.editor(
+					"Enter custom review instructions (applies to all review modes):",
+					"",
+				);
+
+				if (!customInstructions?.trim()) {
+					ctx.ui.notify("Custom review instructions not changed", "info");
+					continue;
+				}
+
+				setReviewCustomInstructions(customInstructions);
+				ctx.ui.notify("Custom review instructions saved", "info");
+				continue;
+			}
+
 			// Handle each preset type
 			switch (result) {
 				case "uncommitted":
@@ -941,12 +1022,6 @@ export default function reviewExtension(pi: ExtensionAPI) {
 					break;
 				}
 
-				case "custom": {
-					const target = await showCustomInput(ctx);
-					if (target) return target;
-					break;
-				}
-
 				case "folder": {
 					const target = await showFolderInput(ctx);
 					if (target) return target;
@@ -997,7 +1072,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 			description: branch === defaultBranch ? "(default)" : "",
 		}));
 
-		const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+		const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) => {
 			const container = new Container();
 			container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
 			container.addChild(new Text(theme.fg("accent", theme.bold("Select base branch"))));
@@ -1053,16 +1128,15 @@ export default function reviewExtension(pi: ExtensionAPI) {
 					container.invalidate();
 				},
 				handleInput(data: string) {
-					const kb = getEditorKeybindings();
 					if (
-						kb.matches(data, "selectUp") ||
-						kb.matches(data, "selectDown") ||
-						kb.matches(data, "selectConfirm") ||
-						kb.matches(data, "selectCancel")
+						keybindings.matches(data, "tui.select.up") ||
+						keybindings.matches(data, "tui.select.down") ||
+						keybindings.matches(data, "tui.select.confirm") ||
+						keybindings.matches(data, "tui.select.cancel")
 					) {
 						if (selectList) {
 							selectList.handleInput(data);
-						} else if (kb.matches(data, "selectCancel")) {
+						} else if (keybindings.matches(data, "tui.select.cancel")) {
 							done(null);
 						}
 						tui.requestRender();
@@ -1097,7 +1171,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 			description: "",
 		}));
 
-		const result = await ctx.ui.custom<{ sha: string; title: string } | null>((tui, theme, _kb, done) => {
+		const result = await ctx.ui.custom<{ sha: string; title: string } | null>((tui, theme, keybindings, done) => {
 			const container = new Container();
 			container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
 			container.addChild(new Text(theme.fg("accent", theme.bold("Select commit to review"))));
@@ -1160,16 +1234,15 @@ export default function reviewExtension(pi: ExtensionAPI) {
 					container.invalidate();
 				},
 				handleInput(data: string) {
-					const kb = getEditorKeybindings();
 					if (
-						kb.matches(data, "selectUp") ||
-						kb.matches(data, "selectDown") ||
-						kb.matches(data, "selectConfirm") ||
-						kb.matches(data, "selectCancel")
+						keybindings.matches(data, "tui.select.up") ||
+						keybindings.matches(data, "tui.select.down") ||
+						keybindings.matches(data, "tui.select.confirm") ||
+						keybindings.matches(data, "tui.select.cancel")
 					) {
 						if (selectList) {
 							selectList.handleInput(data);
-						} else if (kb.matches(data, "selectCancel")) {
+						} else if (keybindings.matches(data, "tui.select.cancel")) {
 							done(null);
 						}
 						tui.requestRender();
@@ -1187,18 +1260,6 @@ export default function reviewExtension(pi: ExtensionAPI) {
 		return { type: "commit", sha: result.sha, title: result.title };
 	}
 
-	/**
-	 * Show custom instructions input
-	 */
-	async function showCustomInput(ctx: ExtensionContext): Promise<ReviewTarget | null> {
-		const result = await ctx.ui.editor(
-			"Enter review instructions:",
-			"Review the code for security vulnerabilities and potential bugs...",
-		);
-
-		if (!result?.trim()) return null;
-		return { type: "custom", instructions: result.trim() };
-	}
 
 	function parseReviewPaths(value: string): string[] {
 		return value
@@ -1288,7 +1349,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 		ctx: ExtensionCommandContext,
 		target: ReviewTarget,
 		useFreshSession: boolean,
-		options?: { includeLocalChanges?: boolean },
+		options?: { includeLocalChanges?: boolean; extraInstruction?: string },
 	): Promise<boolean> {
 		// Check if we're already in a review
 		if (reviewOriginId) {
@@ -1360,6 +1421,14 @@ export default function reviewExtension(pi: ExtensionAPI) {
 		// Combine the review rubric with the specific prompt
 		let fullPrompt = `${REVIEW_RUBRIC}\n\n---\n\nPlease perform a code review with the following focus:\n\n${prompt}`;
 
+		if (reviewCustomInstructions) {
+			fullPrompt += `\n\nShared custom review instructions (applies to all reviews):\n\n${reviewCustomInstructions}`;
+		}
+
+		if (options?.extraInstruction?.trim()) {
+			fullPrompt += `\n\nAdditional user-provided review instruction:\n\n${options.extraInstruction.trim()}`;
+		}
+
 		if (projectGuidelines) {
 			fullPrompt += `\n\nThis project has additional instructions for code reviews:\n\n${projectGuidelines}`;
 		}
@@ -1376,49 +1445,122 @@ export default function reviewExtension(pi: ExtensionAPI) {
 	 * Parse command arguments for direct invocation
 	 * Returns the target or a special marker for PR that needs async handling
 	 */
-	function parseArgs(args: string | undefined): ReviewTarget | { type: "pr"; ref: string } | null {
-		if (!args?.trim()) return null;
+	type ParsedReviewArgs = {
+		target: ReviewTarget | { type: "pr"; ref: string } | null;
+		extraInstruction?: string;
+		error?: string;
+	};
+
+	function tokenizeArgs(value: string): string[] {
+		const tokens: string[] = [];
+		let current = "";
+		let quote: '"' | "'" | null = null;
+
+		for (let i = 0; i < value.length; i++) {
+			const char = value[i];
+
+			if (quote) {
+				if (char === "\\" && i + 1 < value.length) {
+					current += value[i + 1];
+					i += 1;
+					continue;
+				}
+				if (char === quote) {
+					quote = null;
+					continue;
+				}
+				current += char;
+				continue;
+			}
+
+			if (char === '"' || char === "'") {
+				quote = char;
+				continue;
+			}
+
+			if (/\s/.test(char)) {
+				if (current.length > 0) {
+					tokens.push(current);
+					current = "";
+				}
+				continue;
+			}
+
+			current += char;
+		}
+
+		if (current.length > 0) {
+			tokens.push(current);
+		}
+
+		return tokens;
+	}
+
+	function parseArgs(args: string | undefined): ParsedReviewArgs {
+		if (!args?.trim()) return { target: null };
+
+		const rawParts = tokenizeArgs(args.trim());
+		const parts: string[] = [];
+		let extraInstruction: string | undefined;
+
+		for (let i = 0; i < rawParts.length; i++) {
+			const part = rawParts[i];
+			if (part === "--extra") {
+				const next = rawParts[i + 1];
+				if (!next) {
+					return { target: null, error: "Missing value for --extra" };
+				}
+				extraInstruction = next;
+				i += 1;
+				continue;
+			}
+
+			if (part.startsWith("--extra=")) {
+				extraInstruction = part.slice("--extra=".length);
+				continue;
+			}
+
+			parts.push(part);
+		}
+
+		if (parts.length === 0) {
+			return { target: null, extraInstruction };
+		}
 
-		const parts = args.trim().split(/\s+/);
 		const subcommand = parts[0]?.toLowerCase();
 
 		switch (subcommand) {
 			case "uncommitted":
-				return { type: "uncommitted" };
+				return { target: { type: "uncommitted" }, extraInstruction };
 
 			case "branch": {
 				const branch = parts[1];
-				if (!branch) return null;
-				return { type: "baseBranch", branch };
+				if (!branch) return { target: null, extraInstruction };
+				return { target: { type: "baseBranch", branch }, extraInstruction };
 			}
 
 			case "commit": {
 				const sha = parts[1];
-				if (!sha) return null;
+				if (!sha) return { target: null, extraInstruction };
 				const title = parts.slice(2).join(" ") || undefined;
-				return { type: "commit", sha, title };
+				return { target: { type: "commit", sha, title }, extraInstruction };
 			}
 
-			case "custom": {
-				const instructions = parts.slice(1).join(" ");
-				if (!instructions) return null;
-				return { type: "custom", instructions };
-			}
 
 			case "folder": {
 				const paths = parseReviewPaths(parts.slice(1).join(" "));
-				if (paths.length === 0) return null;
-				return { type: "folder", paths };
+				if (paths.length === 0) return { target: null, extraInstruction };
+				return { target: { type: "folder", paths }, extraInstruction };
 			}
 
 			case "pr": {
 				const ref = parts[1];
-				if (!ref) return null;
-				return { type: "pr", ref };
+				if (!ref) return { target: null, extraInstruction };
+				return { target: { type: "pr", ref }, extraInstruction };
 			}
 
 			default:
-				return null;
+				return { target: null, extraInstruction };
 		}
 	}
 
@@ -1474,7 +1616,11 @@ export default function reviewExtension(pi: ExtensionAPI) {
 		return false;
 	}
 
-	async function runLoopFixingReview(ctx: ExtensionCommandContext, target: ReviewTarget): Promise<void> {
+	async function runLoopFixingReview(
+		ctx: ExtensionCommandContext,
+		target: ReviewTarget,
+		extraInstruction?: string,
+	): Promise<void> {
 		if (reviewLoopInProgress) {
 			ctx.ui.notify("Loop fixing review is already running.", "warning");
 			return;
@@ -1490,7 +1636,10 @@ export default function reviewExtension(pi: ExtensionAPI) {
 
 			for (let pass = 1; pass <= REVIEW_LOOP_MAX_ITERATIONS; pass++) {
 				const reviewBaselineAssistantId = getLastAssistantSnapshot(ctx)?.id;
-				const started = await executeReview(ctx, target, true, { includeLocalChanges: true });
+				const started = await executeReview(ctx, target, true, {
+					includeLocalChanges: true,
+					extraInstruction,
+				});
 				if (!started) {
 					ctx.ui.notify("Loop fixing stopped before starting the review pass.", "warning");
 					return;
@@ -1588,7 +1737,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 
 	// Register the /review command
 	pi.registerCommand("review", {
-		description: "Review code changes (PR, uncommitted, branch, commit, folder, or custom)",
+		description: "Review code changes (PR, uncommitted, branch, commit, or folder)",
 		handler: async (args, ctx) => {
 			if (!ctx.hasUI) {
 				ctx.ui.notify("Review requires interactive mode", "error");
@@ -1616,17 +1765,23 @@ export default function reviewExtension(pi: ExtensionAPI) {
 			// Try to parse direct arguments
 			let target: ReviewTarget | null = null;
 			let fromSelector = false;
+			let extraInstruction: string | undefined;
 			const parsed = parseArgs(args);
+			if (parsed.error) {
+				ctx.ui.notify(parsed.error, "error");
+				return;
+			}
+			extraInstruction = parsed.extraInstruction?.trim() || undefined;
 
-			if (parsed) {
-				if (parsed.type === "pr") {
+			if (parsed.target) {
+				if (parsed.target.type === "pr") {
 					// Handle PR checkout (async operation)
-					target = await handlePrCheckout(ctx, parsed.ref);
+					target = await handlePrCheckout(ctx, parsed.target.ref);
 					if (!target) {
 						ctx.ui.notify("PR review failed. Returning to review menu.", "warning");
 					}
 				} else {
-					target = parsed;
+					target = parsed.target;
 				}
 			}
 
@@ -1655,7 +1810,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 				}
 
 				if (reviewLoopFixingEnabled) {
-					await runLoopFixingReview(ctx, target);
+					await runLoopFixingReview(ctx, target, extraInstruction);
 					return;
 				}
 
@@ -1683,7 +1838,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
 					useFreshSession = choice === "Empty branch";
 				}
 
-				await executeReview(ctx, target, useFreshSession);
+				await executeReview(ctx, target, useFreshSession, { extraInstruction });
 				return;
 			}
 		},
@@ -1718,6 +1873,19 @@ For EACH finding, include:
 - Any constraints or preferences mentioned during review
 - Or "(none)"
 
+## Human Reviewer Callouts (Non-Blocking)
+Include only applicable callouts (no yes/no lines):
+- **This change adds a database migration:** <files/details>
+- **This change introduces a new dependency:** <package(s)/details>
+- **This change changes a dependency (or the lockfile):** <files/package(s)/details>
+- **This change modifies auth/permission behavior:** <what changed and where>
+- **This change introduces backwards-incompatible public schema/API/contract changes:** <what changed and where>
+- **This change includes irreversible or destructive operations:** <operation and scope>
+
+If none apply, write "- (none)".
+
+These are informational callouts for humans and are not fix items by themselves.
+
 Preserve exact file paths, function names, and error messages where available.`;
 
 	const REVIEW_FIX_FINDINGS_PROMPT = `Use the latest review summary in this session and implement the review findings now.
@@ -1726,8 +1894,12 @@ Instructions:
 1. Treat the summary's Findings/Fix Queue as a checklist.
 2. Fix in priority order: P0, P1, then P2 (include P3 if quick and safe).
 3. If a finding is invalid/already fixed/not possible right now, briefly explain why and continue.
-4. Run relevant tests/checks for touched code where practical.
-5. End with: fixed items, deferred/skipped items (with reasons), and verification results.`;
+4. Treat "Human Reviewer Callouts (Non-Blocking)" as informational only; do not convert them into fix tasks unless there is a separate explicit finding.
+5. Follow fail-fast error handling: do not add local catch/fallback recovery unless this scope is an explicit boundary that can safely translate the failure.
+6. If you add or keep a \`try/catch\`, explain the expected failure mode and either rethrow with context or return a boundary-safe error response.
+7. JSON parsing/decoding should fail loudly by default; avoid silent fallback parsing.
+8. Run relevant tests/checks for touched code where practical.
+9. End with: fixed items, deferred/skipped items (with reasons), and verification results.`;
 
 	type EndReviewAction = "returnOnly" | "returnAndFix" | "returnAndSummarize";
 	type EndReviewActionResult = "ok" | "cancelled" | "error";