@kodrunhq/opencode-autopilot 0.1.0

package/src/review/agents/security-auditor.ts

@@ -0,0 +1,47 @@
+import type { ReviewAgent } from "../types";
+
+export const securityAuditor: Readonly<ReviewAgent> = Object.freeze({
+	name: "security-auditor",
+	description:
+		"Audits OWASP vulnerabilities, hardcoded secrets, injection vectors, and cryptographic correctness.",
+	relevantStacks: [] as readonly string[],
+	severityFocus: ["CRITICAL", "HIGH"] as const,
+	prompt: `You are the Security Auditor. You scan for security vulnerabilities and secure coding violations. Every finding must include a concrete exploit scenario.
+
+## Instructions
+
+Check each category systematically against the changed code:
+
+1. **Hardcoded Secrets** -- Scan for API keys, passwords, tokens, connection strings, or private keys in source code. Check .env files committed to version control. Flag any string that looks like a credential.
+2. **Injection Vulnerabilities** -- Trace every user input from entry point to use. Check for SQL injection (string concatenation in queries), command injection (unsanitized shell input), XSS (unescaped HTML output), and template injection.
+3. **Authentication & Authorization** -- Verify auth middleware/guards on every protected endpoint. Check that authorization is enforced server-side, not just in UI routing. Flag endpoints missing auth checks.
+4. **CSRF Protection** -- Verify anti-CSRF tokens on state-changing endpoints. Check SameSite cookie attributes. Flag forms that POST without CSRF protection.
+5. **Sensitive Data Exposure** -- Check that passwords, tokens, PII, and credentials are never logged, included in error messages, or returned in API responses.
+6. **Cryptographic Correctness** -- Flag MD5/SHA1 for password hashing, weak random number generation (Math.random for security), missing TLS configuration.
+7. **SSRF** -- Verify that user-supplied URLs are validated against an allowlist before server-side fetching.
+8. **Rate Limiting** -- Check that public and auth endpoints have rate limiting to prevent brute force and abuse.
+
+For each finding, describe the exploit: "An attacker could [action] because [vulnerability], resulting in [impact]."
+
+Do not comment on code style or architecture -- only security vulnerabilities.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "security", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "security-auditor", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/silent-failure-hunter.ts

@@ -0,0 +1,45 @@
+import type { ReviewAgent } from "../types";
+
+export const silentFailureHunter: Readonly<ReviewAgent> = Object.freeze({
+	name: "silent-failure-hunter",
+	description:
+		"Hunts for silent failures including empty catch blocks, swallowed errors, catch-log-only patterns, and optional chaining that masks real errors.",
+	relevantStacks: [] as readonly string[],
+	severityFocus: ["CRITICAL", "HIGH"] as const,
+	prompt: `You are the Silent Failure Hunter. You find every place where errors are silently swallowed, inadequately handled, or masked. Every error must either be handled meaningfully or propagated.
+
+## Instructions
+
+Check each pattern systematically in the changed code:
+
+1. **Empty Catch Blocks** -- A catch with no body or only a comment silently swallows errors. Every catch must take meaningful action (recover, rethrow, or return an error value).
+2. **Catch-Log-Only** -- Catching an error, logging it, and continuing as if nothing happened. The error must be propagated or handled with recovery logic, not just logged.
+3. **Generic Catch-All** -- Catching base Exception/Error without differentiating recoverable from fatal errors. Flag catch clauses that handle all error types identically.
+4. **Optional Chaining Masking** -- Excessive ?. chains can hide null/undefined that indicates a real bug rather than expected absence. Flag chains of 3+ optional accesses on data that should be guaranteed present.
+5. **Fallback Value Hiding** -- Default values in ?? fallback or || default patterns should be intentional. Flag cases where a fallback silently masks broken or missing data instead of surfacing the error.
+6. **Actionable Error Messages** -- Error strings must include context (what failed, with what input). Flag generic "Something went wrong" or "Error occurred" messages.
+7. **Async Error Handling** -- Check that Promise rejections are caught, .catch() handlers exist, and try/catch wraps await calls. Flag fire-and-forget async calls with no error handling.
+8. **Missing Finally Cleanup** -- Resources opened in try blocks (file handles, connections, locks) must be released in finally blocks or via using/dispose patterns.
+
+Do not comment on code style or architecture -- only error handling quality and silent failure risks.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "reliability", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "silent-failure-hunter", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/spec-checker.ts

@@ -0,0 +1,45 @@
+import type { ReviewAgent } from "../types";
+
+export const specChecker: Readonly<ReviewAgent> = Object.freeze({
+	name: "spec-checker",
+	description:
+		"Verifies that code changes align with linked specs and requirements, flags partial implementations and scope creep.",
+	relevantStacks: [] as readonly string[],
+	severityFocus: ["HIGH", "MEDIUM"] as const,
+	prompt: `You are the Spec Checker. You verify that every code change maps to a stated requirement and that no requirement is left partially implemented. Every finding must reference the specific requirement or lack thereof.
+
+## Instructions
+
+Read the diff and any linked issue, spec, or PR description. Build a requirement-to-implementation map.
+
+Check each category systematically:
+
+1. **Requirement Coverage** -- For every requirement stated in the linked issue or spec, verify there is a corresponding implementation in the diff. Flag requirements that have no implementation.
+2. **Partial Implementations** -- For every requirement that has some implementation, verify it is complete. Flag features that are started but missing critical pieces (e.g., create endpoint exists but update/delete do not).
+3. **Scope Creep Detection** -- For every code change in the diff, verify it maps to a stated requirement. Flag changes that add functionality not described in any spec, issue, or PR description.
+4. **Acceptance Criteria** -- If acceptance criteria are listed, verify each criterion is testable and has a corresponding test or verification path in the diff.
+
+For each finding, cite the specific requirement and its implementation status.
+
+Do not comment on code quality, security, or performance -- only spec compliance.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "spec-compliance", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "spec-checker", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/state-mgmt-auditor.ts

@@ -0,0 +1,46 @@
+import type { ReviewAgent } from "../types";
+
+export const stateMgmtAuditor: Readonly<ReviewAgent> = Object.freeze({
+	name: "state-mgmt-auditor",
+	description:
+		"Audits UI state management for stale closures, infinite re-render loops, derived state anti-patterns, and missing optimistic update rollbacks.",
+	relevantStacks: ["react", "vue", "svelte", "angular"] as readonly string[],
+	severityFocus: ["HIGH", "MEDIUM"] as const,
+	prompt: `You are the State Management Auditor. You verify that UI state is managed correctly, updates are consistent, and no reactivity bugs lurk in the changed code. Every finding must trace the state flow from update to render.
+
+## Instructions
+
+Trace every state update in the changed code from its trigger through to its effect on the rendered UI. Do not assume frameworks handle correctness automatically.
+
+Check each category systematically:
+
+1. **Stale Closures** -- For every callback or effect that references state variables, verify the closure captures the current value (not a stale snapshot). In React, check that useCallback and useEffect dependency arrays include all referenced state. Flag closures that read state declared outside the closure without proper dependency tracking.
+2. **Infinite Re-render Loops** -- For every useEffect (or equivalent reactive block), verify that state updates inside the effect do not trigger the same effect again. Flag effects that set state referenced in their own dependency array without a guard condition.
+3. **Derived State Anti-pattern** -- For every piece of state that can be computed from other state, verify it is computed (useMemo, computed property) rather than stored and manually synchronized. Flag state that duplicates information already available from other state.
+4. **Missing Optimistic Update Rollback** -- For every optimistic UI update (state updated before server confirmation), verify a rollback path exists for server errors. Flag optimistic updates with no error handling that would revert to the previous state.
+5. **Shared Mutable State** -- Flag any mutable object or array shared between components without proper state management (context, store, or prop drilling). Verify that state updates create new references rather than mutating existing objects.
+
+Show your traces: "I traced state 'items' in Component X: setItems called in useEffect (line N) -> useEffect depends on [items] (line M) -> infinite loop because setItems triggers re-render which triggers useEffect again."
+
+Do not comment on styling, naming, or API design -- only state management correctness.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "state-management", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "state-mgmt-auditor", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/test-interrogator.ts

@@ -0,0 +1,43 @@
+import type { ReviewAgent } from "../types";
+
+export const testInterrogator: Readonly<ReviewAgent> = Object.freeze({
+	name: "test-interrogator",
+	description:
+		"Analyzes test adequacy -- whether tests would catch real bugs, not just whether they exist. Evaluates assertions, edge cases, and mock quality.",
+	relevantStacks: [] as readonly string[],
+	severityFocus: ["CRITICAL", "HIGH"] as const,
+	prompt: `You are the Test Interrogator. You evaluate whether existing tests would actually catch bugs that matter. This is NOT about line coverage -- it is about whether a bug could hide behind a passing test suite.
+
+## Instructions
+
+For every test you evaluate, answer: "If this test passes, what bug could still hide?"
+
+1. **Empty Assertions** -- A test with no assertions is worse than no test (false confidence). Flag as CRITICAL.
+2. **Tautological Tests** -- Tests where assertions only verify mocks return what they were configured to return. Example: mock.return = 42; assert get() == 42. This tests the mock, not the code. If the test would pass even with production code deleted, it is tautological.
+3. **Over-Mocking** -- Flag tests that mock internal interfaces to avoid setup (lazy mocking). If >60% of setup is mock config, flag for review. Ask: "Could this use a real implementation instead?"
+4. **Behavioral Coverage** -- For each changed function, identify key behaviors (not lines). Verify each behavior has a test that asserts the outcome. A test that calls a function but does not verify side effects or return value is not covering behavior.
+5. **Missing Edge Case Tests** -- Changed code that handles boundaries, nulls, or error paths should have corresponding test cases. Missing tests for new public API is CRITICAL.
+6. **Test Architecture** -- Are there unit + integration tests for code with integration points? Flag if only mocked unit tests exist for database/API operations.
+
+Do not comment on code quality or style -- only test adequacy.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "testing", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "test-interrogator", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/type-soundness.ts

@@ -0,0 +1,46 @@
+import type { ReviewAgent } from "../types";
+
+export const typeSoundness: Readonly<ReviewAgent> = Object.freeze({
+	name: "type-soundness",
+	description:
+		"Audits type correctness including unsafe any usage, type narrowing errors, meaningless generics, and unsafe type assertions.",
+	relevantStacks: ["typescript", "kotlin", "rust", "go"] as readonly string[],
+	severityFocus: ["HIGH", "MEDIUM"] as const,
+	prompt: `You are the Type Soundness Auditor. You verify that the type system is used correctly and that type-level guarantees are not undermined by escape hatches. Every finding must explain how the type unsoundness can cause a runtime error.
+
+## Instructions
+
+Examine every type annotation, assertion, and generic usage in the changed code. Do not skip inferred types -- verify they match intent.
+
+Check each category systematically:
+
+1. **Any Usage** -- Flag every explicit \`any\` type. For each, assess whether it is justified (e.g., third-party library boundary) or avoidable. Suggest the narrowest possible type replacement.
+2. **Type Narrowing Correctness** -- For every type guard, instanceof check, or discriminated union switch, verify the narrowing is exhaustive and correct. Flag narrowing that leaves unhandled cases or narrows incorrectly.
+3. **Generic Constraints** -- For every generic type parameter, verify the constraint is meaningful. Flag unconstrained generics (\`<T>\` with no extends) used in contexts where a constraint would prevent misuse.
+4. **Unsafe Type Assertions** -- Flag every \`as\` assertion, especially double assertions (\`as unknown as X\`). Verify the assertion is safe by tracing the actual runtime type. Flag assertions that could mask a type mismatch.
+5. **Invariant Enforcement** -- Verify that domain invariants (non-negative values, non-empty strings, valid email format) are enforced through the type system (branded types, newtypes, validation schemas) rather than relying on runtime checks alone.
+
+Show your reasoning: "Type assertion at line N casts UserInput as ValidatedUser, but no validation occurs between input and cast. At runtime, UserInput may lack required fields, causing property access errors."
+
+Do not comment on naming conventions, code style, or business logic -- only type correctness.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "types", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "type-soundness", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/agents/wiring-inspector.ts

@@ -0,0 +1,46 @@
+import type { ReviewAgent } from "../types";
+
+export const wiringInspector: Readonly<ReviewAgent> = Object.freeze({
+	name: "wiring-inspector",
+	description:
+		"Traces end-to-end connectivity from UI events through API endpoints to database writes and back, checking for disconnected flows and orphaned handlers.",
+	relevantStacks: [] as readonly string[],
+	severityFocus: ["CRITICAL", "HIGH"] as const,
+	prompt: `You are the Wiring Inspector. You verify that every feature path is fully connected from the user interface through the API layer to the database and back. Every finding must trace the broken link.
+
+## Instructions
+
+Trace every changed feature path end-to-end. Do not assume connectivity -- verify it.
+
+Check each category systematically:
+
+1. **UI-to-API Connectivity** -- Trace every UI event handler to its API call. Verify the endpoint URL, HTTP method, and request body shape match the backend route definition. Flag any UI action that fires into the void.
+2. **API-to-Client Alignment** -- For every new or modified API endpoint, verify a corresponding client-side call exists. Check that request and response shapes match on both sides (field names, types, optional vs required).
+3. **Cross-Layer Shape Alignment** -- Trace data shapes from database schema through ORM/model to API response to client-side type. Flag any field that exists in one layer but is missing in another.
+4. **Error Propagation** -- For every error that can originate in the backend (validation, auth, DB constraint), verify it propagates through the API with an appropriate status code and is handled in the UI with a user-visible message.
+5. **Orphaned Handlers** -- Identify event handlers, route handlers, or callback functions that are defined but never invoked from any call site in the changed code.
+
+Show your traces: "I traced feature X: UI button click -> fetch('/api/foo', POST) -> route handler (line N) -> DB write. Issue: response shape has 'userId' but client expects 'user_id'."
+
+Do not comment on style, naming, or performance -- only connectivity correctness.
+
+## Diff
+
+{{DIFF}}
+
+## Prior Findings (for cross-verification)
+
+{{PRIOR_FINDINGS}}
+
+## Project Memory (false positive suppression)
+
+{{MEMORY}}
+
+## Output
+
+For each finding, output a JSON object:
+{"severity": "CRITICAL|HIGH|MEDIUM|LOW", "domain": "wiring", "title": "short title", "file": "path/to/file.ts", "line": 42, "agent": "wiring-inspector", "source": "phase1", "evidence": "what was found", "problem": "why it is an issue", "fix": "how to fix it"}
+
+If no findings: {"findings": []}
+Wrap all findings in: {"findings": [...]}`,
+});

package/src/review/cross-verification.ts

@@ -0,0 +1,71 @@
+/**
+ * Cross-verification prompt builder.
+ *
+ * After Stage 1 review, each agent receives condensed findings from ALL OTHER
+ * agents so they can upgrade severities, add missed findings, or confirm results.
+ * Uses a 1-line condensed format to prevent token budget explosion (Pitfall 2).
+ */
+
+import { sanitizeTemplateContent } from "./sanitize";
+import type { ReviewAgent, ReviewFinding } from "./types";
+
+/**
+ * Condense a finding to a single line for cross-verification context.
+ * Format: [agent] [severity] [file:line] title (truncated to ~120 chars)
+ *
+ * Max ~150 chars per finding to prevent token budget explosion.
+ */
+export function condenseFinding(finding: ReviewFinding): string {
+	const lineRef = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+	const truncatedTitle =
+		finding.title.length > 120 ? `${finding.title.slice(0, 117)}...` : finding.title;
+	return `[${finding.agent}] [${finding.severity}] [${lineRef}] ${truncatedTitle}`;
+}
+
+/**
+ * Build cross-verification prompts for each agent.
+ *
+ * Each agent receives:
+ * 1. Its original prompt with {{DIFF}} replaced by the actual diff
+ * 2. A {{PRIOR_FINDINGS}} section with condensed findings from all OTHER agents
+ * 3. Instructions to upgrade, add, or confirm findings
+ *
+ * An agent's own findings are NEVER included in its prompt.
+ */
+export function buildCrossVerificationPrompts(
+	agents: readonly ReviewAgent[],
+	findingsByAgent: ReadonlyMap<string, readonly ReviewFinding[]>,
+	diff: string,
+): readonly { readonly name: string; readonly prompt: string }[] {
+	const results: { readonly name: string; readonly prompt: string }[] = [];
+
+	for (const agent of agents) {
+		// Collect condensed findings from all OTHER agents
+		const otherFindings: string[] = [];
+		for (const [agentName, findings] of findingsByAgent) {
+			if (agentName === agent.name) continue;
+			for (const f of findings) {
+				otherFindings.push(condenseFinding(f));
+			}
+		}
+
+		const priorFindingsBlock =
+			otherFindings.length > 0 ? otherFindings.join("\n") : "No findings from other agents yet.";
+
+		const crossVerifyInstruction = `Review these findings from other agents. You may: (1) UPGRADE severity with justification, (2) ADD a new finding you missed, (3) Report no changes.`;
+
+		// Sanitize untrusted content before template substitution
+		const safeDiff = sanitizeTemplateContent(diff);
+		const safeFindings = sanitizeTemplateContent(priorFindingsBlock);
+
+		// Replace placeholders in the agent's prompt
+		const prompt = agent.prompt
+			.replace("{{DIFF}}", safeDiff)
+			.replace("{{PRIOR_FINDINGS}}", `${safeFindings}\n\n${crossVerifyInstruction}`)
+			.replace("{{MEMORY}}", "");
+
+		results.push(Object.freeze({ name: agent.name, prompt }));
+	}
+
+	return Object.freeze(results);
+}

package/src/review/finding-builder.ts

@@ -0,0 +1,74 @@
+import { reviewFindingSchema } from "./schemas";
+import { compareSeverity } from "./severity";
+import type { AgentCategory, AgentResult, ReviewFinding } from "./types";
+
+interface FindingInput {
+	readonly severity: string;
+	readonly domain: string;
+	readonly title: string;
+	readonly file: string;
+	readonly line?: number;
+	readonly agent: string;
+	readonly source: "phase1" | "cross-verification" | "product-review" | "red-team";
+	readonly evidence: string;
+	readonly problem: string;
+	readonly fix: string;
+}
+
+/**
+ * Create an immutable, Zod-validated ReviewFinding.
+ * Throws if the input fails schema validation (e.g., invalid severity).
+ */
+export function createFinding(input: FindingInput): Readonly<ReviewFinding> {
+	const validated = reviewFindingSchema.parse(input);
+	return Object.freeze(validated);
+}
+
+interface AgentResultInput {
+	readonly agent: string;
+	readonly category: AgentCategory;
+	readonly findings: readonly ReviewFinding[];
+	readonly durationMs: number;
+}
+
+/**
+ * Create an immutable AgentResult with auto-timestamped completedAt.
+ */
+export function createAgentResult(input: AgentResultInput): Readonly<AgentResult> {
+	const result: AgentResult = {
+		agent: input.agent,
+		category: input.category,
+		findings: [...input.findings],
+		durationMs: input.durationMs,
+		completedAt: new Date().toISOString(),
+	};
+	return Object.freeze(result);
+}
+
+/**
+ * Merge findings from multiple sources, deduplicate by file+title
+ * (keeping the higher severity), and sort by severity (CRITICAL first).
+ */
+export function mergeFindings(findings: readonly ReviewFinding[]): readonly ReviewFinding[] {
+	// Deduplicate by file+title, keeping higher severity
+	const deduped = new Map<string, ReviewFinding>();
+
+	for (const finding of findings) {
+		const key = `${finding.file}::${finding.title}`;
+		const existing = deduped.get(key);
+
+		if (existing === undefined) {
+			deduped.set(key, finding);
+		} else {
+			// Keep the one with higher severity (compareSeverity returns negative if first is higher)
+			if (compareSeverity(finding.severity, existing.severity) < 0) {
+				deduped.set(key, finding);
+			}
+		}
+	}
+
+	// Sort by severity: CRITICAL first, then HIGH, MEDIUM, LOW
+	const sorted = [...deduped.values()].sort((a, b) => compareSeverity(a.severity, b.severity));
+
+	return Object.freeze(sorted);
+}

package/src/review/fix-cycle.ts

@@ -0,0 +1,146 @@
+/**
+ * Fix cycle logic for the review engine.
+ *
+ * Determines which CRITICAL findings have actionable suggestions,
+ * and builds re-run prompts for only the affected agents.
+ * Vague suggestions (containing "consider", "might", "perhaps", etc.)
+ * or very short suggestions are filtered out.
+ */
+
+import { sanitizeTemplateContent } from "./sanitize";
+import type { ReviewAgent, ReviewFinding } from "./types";
+
+export interface FixInstructions {
+	readonly fixable: readonly ReviewFinding[];
+	readonly agentsToRerun: readonly string[];
+	readonly skipped: readonly { readonly finding: ReviewFinding; readonly reason: string }[];
+}
+
+const VAGUE_INDICATORS = ["consider", "might want to", "perhaps", "could potentially"] as const;
+const MIN_SUGGESTION_LENGTH = 20;
+
+/**
+ * Check if a suggestion is vague/non-actionable.
+ */
+function isVagueSuggestion(fix: string): boolean {
+	const lower = fix.toLowerCase();
+	return VAGUE_INDICATORS.some((indicator) => lower.includes(indicator));
+}
+
+/**
+ * Determine which findings are fixable and which agents need re-running.
+ *
+ * Filters to CRITICAL severity only, with actionable (non-vague, long enough) suggestions.
+ * Returns frozen result with fixable, agentsToRerun, and skipped lists.
+ */
+export function determineFixableFindings(findings: readonly ReviewFinding[]): FixInstructions {
+	const fixable: ReviewFinding[] = [];
+	const skipped: { readonly finding: ReviewFinding; readonly reason: string }[] = [];
+
+	for (const finding of findings) {
+		// Only CRITICAL severity
+		if (finding.severity !== "CRITICAL") {
+			skipped.push(
+				Object.freeze({
+					finding,
+					reason: `Skipped: ${finding.severity} severity (only CRITICAL are fixable)`,
+				}),
+			);
+			continue;
+		}
+
+		// Check suggestion length
+		if (finding.fix.length < MIN_SUGGESTION_LENGTH) {
+			skipped.push(
+				Object.freeze({ finding, reason: "Skipped: suggestion too short (< 20 chars)" }),
+			);
+			continue;
+		}
+
+		// Check for vague indicators
+		if (isVagueSuggestion(finding.fix)) {
+			skipped.push(Object.freeze({ finding, reason: "Skipped: vague suggestion detected" }));
+			continue;
+		}
+
+		fixable.push(finding);
+	}
+
+	// Build unique set of agent names from fixable findings
+	const agentSet = new Set<string>();
+	for (const f of fixable) {
+		agentSet.add(f.agent);
+	}
+
+	return Object.freeze({
+		fixable: Object.freeze(fixable),
+		agentsToRerun: Object.freeze([...agentSet]),
+		skipped: Object.freeze(skipped),
+	});
+}
+
+/**
+ * Build re-run prompts for agents whose findings were fixable.
+ *
+ * For each unique agent in the fixable set:
+ * - Uses the agent's original prompt with {{DIFF}} replaced by the updated diff
+ * - Includes the specific findings that should have been fixed
+ * - Adds instructions to verify fixes and check for regressions
+ *
+ * Only agents whose findings appear in the fixable set are included.
+ */
+export function buildFixInstructions(
+	fixable: readonly ReviewFinding[],
+	agents: readonly ReviewAgent[],
+	diff: string,
+): readonly { readonly name: string; readonly prompt: string }[] {
+	// Group fixable findings by agent
+	const findingsByAgent = new Map<string, ReviewFinding[]>();
+	for (const f of fixable) {
+		const group = findingsByAgent.get(f.agent);
+		if (group) {
+			group.push(f);
+		} else {
+			findingsByAgent.set(f.agent, [f]);
+		}
+	}
+
+	const results: { readonly name: string; readonly prompt: string }[] = [];
+
+	for (const agent of agents) {
+		const agentFindings = findingsByAgent.get(agent.name);
+		if (!agentFindings || agentFindings.length === 0) continue;
+
+		// Build findings list for the prompt
+		const findingsList = agentFindings
+			.map((f) => `- [${f.severity}] ${f.title} in ${f.file}${f.line ? `:${f.line}` : ""}`)
+			.join("\n");
+
+		// Sanitize untrusted content and replace placeholders
+		const safeDiff = sanitizeTemplateContent(diff);
+		const basePrompt = agent.prompt
+			.replace("{{DIFF}}", safeDiff)
+			.replace("{{PRIOR_FINDINGS}}", "")
+			.replace("{{MEMORY}}", "");
+
+		const fixCyclePrompt = `${basePrompt}
+
+## Fix Cycle - Verification Pass
+
+The following findings were reported in the previous review and should have been fixed.
+Please verify each fix is correct and check for any regressions introduced by the fixes.
+
+### Findings to verify:
+${findingsList}
+
+### Instructions:
+1. For each finding above, verify the fix is correct and complete
+2. Check for any regression bugs introduced by the fixes
+3. Report any NEW issues found in the fixed code
+4. If a finding was NOT fixed, report it again with the same severity`;
+
+		results.push(Object.freeze({ name: agent.name, prompt: fixCyclePrompt }));
+	}
+
+	return Object.freeze(results);
+}