taskplane 0.28.4 → 0.28.6

package/extensions/taskplane/quality-gate.ts

@@ -1,1033 +1,1033 @@
-/**
- * Quality Gate — structured post-completion review types and verdict evaluation.
- *
- * This module defines the interfaces for quality gate review verdicts and
- * implements the verdict evaluation logic used by the task-runner to decide
- * whether a task passes or needs fixes before `.DONE` creation.
- *
- * Verdict rules (from roadmap Phase 5a):
- * - Any `critical` finding → NEEDS_FIXES
- * - 3+ `important` findings → NEEDS_FIXES
- * - Only `suggestion` findings → PASS
- * - Any `status_mismatch` category → NEEDS_FIXES
- *
- * Fail-open behavior: malformed or missing verdict JSON → PASS
- * (prevents quality gate bugs from blocking task completion)
- *
- * @module quality-gate
- */
-
-import type { PassThreshold } from "./config-schema.ts";
-import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import { spawnSync } from "child_process";
-
-// ── Verdict Interfaces ───────────────────────────────────────────────
-
-/** Severity levels for review findings, ordered by decreasing severity. */
-export type FindingSeverity = "critical" | "important" | "suggestion";
-
-/** Categories of review findings. */
-export type FindingCategory =
-	| "missing_requirement"
-	| "incorrect_implementation"
-	| "incomplete_work"
-	| "status_mismatch";
-
-/** A single finding from the quality gate review. */
-export interface ReviewFinding {
-	/** Severity of the finding */
-	severity: FindingSeverity;
-	/** Category classifying what kind of issue was found */
-	category: FindingCategory;
-	/** Human-readable description of the issue */
-	description: string;
-	/** File path related to the finding (may be empty) */
-	file: string;
-	/** Specific fix instruction for the remediation agent */
-	remediation: string;
-}
-
-/** STATUS.md checkbox reconciliation entry. */
-export interface StatusReconciliation {
-	/** Original checkbox text from STATUS.md */
-	checkbox: string;
-	/** Actual state determined by review */
-	actualState: "done" | "not_done" | "partial";
-	/** Evidence supporting the state determination */
-	evidence: string;
-}
-
-/** Overall quality gate verdict from the review agent. */
-export interface ReviewVerdict {
-	/** Pass/fail verdict */
-	verdict: "PASS" | "NEEDS_FIXES";
-	/** Review agent confidence level */
-	confidence: "high" | "medium" | "low";
-	/** Brief overall assessment */
-	summary: string;
-	/** Individual findings from the review */
-	findings: ReviewFinding[];
-	/** STATUS.md checkbox reconciliation results */
-	statusReconciliation: StatusReconciliation[];
-}
-
-// ── Verdict Evaluation ───────────────────────────────────────────────
-
-/** Reason why a verdict was determined to be NEEDS_FIXES. */
-export interface VerdictFailReason {
-	/** Rule that triggered the failure */
-	rule: "critical_finding" | "important_threshold" | "status_mismatch" | "verdict_says_needs_fixes";
-	/** Human-readable explanation */
-	detail: string;
-}
-
-/** Result of applying verdict rules to a parsed ReviewVerdict. */
-export interface VerdictEvaluation {
-	/** Whether the task passes the quality gate */
-	pass: boolean;
-	/** Reasons for failure (empty array if pass is true) */
-	failReasons: VerdictFailReason[];
-}
-
-/**
- * Apply verdict rules to determine pass/fail based on findings and threshold.
- *
- * Rules applied in order:
- * 1. Any finding with category `status_mismatch` → NEEDS_FIXES
- * 2. Any finding with severity `critical` → NEEDS_FIXES
- * 3. Threshold-dependent important finding count check
- * 4. If verdict itself says NEEDS_FIXES → respect it
- *
- * Threshold behavior:
- * - `no_critical`: PASS if no critical findings and no status mismatches
- * - `no_important`: PASS if no critical, fewer than 3 important, no status mismatches
- * - `all_clear`: PASS only if zero findings of any severity
- *
- * @param verdict - Parsed review verdict
- * @param threshold - Configured pass threshold
- * @returns Evaluation result with pass/fail and reasons
- */
-export function applyVerdictRules(
-	verdict: ReviewVerdict,
-	threshold: PassThreshold,
-): VerdictEvaluation {
-	const failReasons: VerdictFailReason[] = [];
-
-	// Rule 1: Any status_mismatch category → NEEDS_FIXES
-	const statusMismatches = verdict.findings.filter(
-		(f) => f.category === "status_mismatch",
-	);
-	if (statusMismatches.length > 0) {
-		failReasons.push({
-			rule: "status_mismatch",
-			detail: `${statusMismatches.length} status mismatch(es) found — checked boxes don't match actual work`,
-		});
-	}
-
-	// Rule 2: Any critical finding → NEEDS_FIXES
-	const criticals = verdict.findings.filter((f) => f.severity === "critical");
-	if (criticals.length > 0) {
-		failReasons.push({
-			rule: "critical_finding",
-			detail: `${criticals.length} critical finding(s)`,
-		});
-	}
-
-	// Rule 3: Threshold-dependent important check
-	const importants = verdict.findings.filter(
-		(f) => f.severity === "important",
-	);
-
-	if (threshold === "no_important" && importants.length >= 3) {
-		failReasons.push({
-			rule: "important_threshold",
-			detail: `${importants.length} important findings (threshold: fewer than 3 required for pass)`,
-		});
-	}
-
-	if (threshold === "all_clear" && verdict.findings.length > 0) {
-		// For all_clear, any finding of any severity blocks pass
-		if (importants.length > 0 && failReasons.every((r) => r.rule !== "important_threshold")) {
-			failReasons.push({
-				rule: "important_threshold",
-				detail: `${importants.length} important finding(s) (all_clear threshold: zero findings required)`,
-			});
-		}
-		// Suggestions also block under all_clear — but we don't need a separate rule
-		// since we'll catch it via the verdict_says_needs_fixes or the overall pass logic
-	}
-
-	// Rule 4: If the verdict itself says NEEDS_FIXES and we haven't already failed
-	if (verdict.verdict === "NEEDS_FIXES" && failReasons.length === 0) {
-		failReasons.push({
-			rule: "verdict_says_needs_fixes",
-			detail: `Review agent verdict: NEEDS_FIXES — ${verdict.summary}`,
-		});
-	}
-
-	// For all_clear threshold: even suggestions-only should fail
-	if (
-		threshold === "all_clear" &&
-		failReasons.length === 0 &&
-		verdict.findings.length > 0
-	) {
-		const suggestions = verdict.findings.filter(
-			(f) => f.severity === "suggestion",
-		);
-		if (suggestions.length > 0) {
-			failReasons.push({
-				rule: "important_threshold",
-				detail: `${suggestions.length} suggestion(s) found (all_clear threshold: zero findings required)`,
-			});
-		}
-	}
-
-	return {
-		pass: failReasons.length === 0,
-		failReasons,
-	};
-}
-
-// ── Verdict Parsing ──────────────────────────────────────────────────
-
-/** Sentinel verdict returned when parsing fails (fail-open). */
-const FAIL_OPEN_VERDICT: ReviewVerdict = {
-	verdict: "PASS",
-	confidence: "low",
-	summary: "Verdict could not be parsed — fail-open policy applied",
-	findings: [],
-	statusReconciliation: [],
-};
-
-/**
- * Parse a JSON string into a ReviewVerdict, with fail-open behavior.
- *
- * If the input is missing, empty, or malformed JSON, returns a PASS verdict
- * (fail-open) to prevent quality gate bugs from blocking task completion.
- *
- * Performs structural validation:
- * - `verdict` must be "PASS" or "NEEDS_FIXES"
- * - `findings` must be an array (defaults to [] if missing)
- * - `statusReconciliation` must be an array (defaults to [] if missing)
- * - Individual findings are validated and malformed entries are dropped
- *
- * @param jsonString - Raw JSON string from review agent output
- * @returns Parsed and validated ReviewVerdict (never throws)
- */
-export function parseVerdict(jsonString: string | undefined | null): ReviewVerdict {
-	if (!jsonString || jsonString.trim() === "") {
-		return { ...FAIL_OPEN_VERDICT, summary: "No verdict provided — fail-open policy applied" };
-	}
-
-	let raw: unknown;
-	try {
-		raw = JSON.parse(jsonString);
-	} catch {
-		return { ...FAIL_OPEN_VERDICT, summary: "Malformed JSON in verdict — fail-open policy applied" };
-	}
-
-	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-		return { ...FAIL_OPEN_VERDICT, summary: "Verdict is not a JSON object — fail-open policy applied" };
-	}
-
-	const obj = raw as Record<string, unknown>;
-
-	// Validate verdict field
-	const verdict = obj.verdict;
-	if (verdict !== "PASS" && verdict !== "NEEDS_FIXES") {
-		return { ...FAIL_OPEN_VERDICT, summary: `Invalid verdict value "${String(verdict)}" — fail-open policy applied` };
-	}
-
-	// Parse confidence with fallback
-	const validConfidence = ["high", "medium", "low"];
-	const confidence = validConfidence.includes(obj.confidence as string)
-		? (obj.confidence as "high" | "medium" | "low")
-		: "medium";
-
-	// Parse summary with fallback
-	const summary = typeof obj.summary === "string" ? obj.summary : "";
-
-	// Parse and validate findings
-	const findings = validateFindings(obj.findings);
-
-	// Parse and validate statusReconciliation
-	const statusReconciliation = validateReconciliations(obj.statusReconciliation);
-
-	return {
-		verdict,
-		confidence,
-		summary,
-		findings,
-		statusReconciliation,
-	};
-}
-
-// ── Internal Validation Helpers ──────────────────────────────────────
-
-const VALID_SEVERITIES: FindingSeverity[] = ["critical", "important", "suggestion"];
-const VALID_CATEGORIES: FindingCategory[] = [
-	"missing_requirement",
-	"incorrect_implementation",
-	"incomplete_work",
-	"status_mismatch",
-];
-const VALID_STATES = ["done", "not_done", "partial"];
-
-/**
- * Validate and normalize the findings array.
- * Drops individual entries that don't have minimum required fields.
- */
-function validateFindings(raw: unknown): ReviewFinding[] {
-	if (!Array.isArray(raw)) return [];
-
-	const validated: ReviewFinding[] = [];
-	for (const item of raw) {
-		if (typeof item !== "object" || item === null) continue;
-		const f = item as Record<string, unknown>;
-
-		// Severity is required and must be valid
-		if (!VALID_SEVERITIES.includes(f.severity as FindingSeverity)) continue;
-
-		// Category is required and must be valid
-		if (!VALID_CATEGORIES.includes(f.category as FindingCategory)) continue;
-
-		// Description is required
-		if (typeof f.description !== "string" || f.description.trim() === "") continue;
-
-		validated.push({
-			severity: f.severity as FindingSeverity,
-			category: f.category as FindingCategory,
-			description: f.description as string,
-			file: typeof f.file === "string" ? f.file : "",
-			remediation: typeof f.remediation === "string" ? f.remediation : "",
-		});
-	}
-
-	return validated;
-}
-
-/**
- * Validate and normalize the statusReconciliation array.
- * Drops individual entries that don't have minimum required fields.
- */
-function validateReconciliations(raw: unknown): StatusReconciliation[] {
-	if (!Array.isArray(raw)) return [];
-
-	const validated: StatusReconciliation[] = [];
-	for (const item of raw) {
-		if (typeof item !== "object" || item === null) continue;
-		const r = item as Record<string, unknown>;
-
-		if (typeof r.checkbox !== "string" || r.checkbox.trim() === "") continue;
-		if (!VALID_STATES.includes(r.actualState as string)) continue;
-
-		validated.push({
-			checkbox: r.checkbox as string,
-			actualState: r.actualState as "done" | "not_done" | "partial",
-			evidence: typeof r.evidence === "string" ? r.evidence : "",
-		});
-	}
-
-	return validated;
-}
-
-// ── Quality Gate Review Prompt ───────────────────────────────────────
-
-/** Information needed to build the quality gate review evidence package. */
-export interface QualityGateContext {
-	/** Absolute path to task folder */
-	taskFolder: string;
-	/** Absolute path to PROMPT.md */
-	promptPath: string;
-	/** Task ID (e.g., "TP-034") */
-	taskId: string;
-	/** Project name from config */
-	projectName: string;
-	/** Pass threshold from config */
-	passThreshold: PassThreshold;
-}
-
-/** Path where the quality gate verdict JSON file is written by the review agent. */
-export const VERDICT_FILENAME = "REVIEW_VERDICT.json";
-
-/**
- * Compute a robust diff range for the task's git changes.
- *
- * Strategy (in order):
- * 1. `git merge-base HEAD main` — ideal for topic branches
- * 2. `git merge-base HEAD origin/main` — fallback for detached/worktree checkouts
- * 3. `HEAD~N` where N = min(commit count, 50) — bounded fallback for repos
- *    without a main branch or with shallow history
- * 4. Empty string (signals diff unavailable)
- */
-function computeDiffBase(cwd: string): string {
-	const opts = { encoding: "utf-8" as const, cwd, timeout: 15000 };
-
-	// Try merge-base with local main
-	for (const ref of ["main", "origin/main", "master", "origin/master"]) {
-		const result = spawnSync("git", ["merge-base", "HEAD", ref], opts);
-		if (result.status === 0 && result.stdout.trim()) {
-			return result.stdout.trim();
-		}
-	}
-
-	// Fallback: count commits and use HEAD~N (bounded)
-	const countResult = spawnSync("git", ["rev-list", "--count", "HEAD"], opts);
-	if (countResult.status === 0) {
-		const count = parseInt(countResult.stdout.trim(), 10);
-		if (count > 1) {
-			const n = Math.min(count - 1, 50);
-			return `HEAD~${n}`;
-		}
-	}
-
-	return "";
-}
-
-/**
- * Build the git diff for the entire task.
- *
- * Uses `computeDiffBase()` to find a robust baseline, then runs `git diff`
- * between that base and HEAD. Falls back gracefully when git is unavailable
- * or the repository has insufficient history.
- */
-function buildGitDiff(cwd: string): { diff: string; fileList: string } {
-	try {
-		const base = computeDiffBase(cwd);
-		if (!base) {
-			return { diff: "(git diff unavailable — could not determine base)", fileList: "(file list unavailable)" };
-		}
-
-		const range = `${base}..HEAD`;
-
-		// Get file list of changed files
-		const fileListResult = spawnSync("git", ["diff", "--name-only", range], {
-			encoding: "utf-8",
-			cwd,
-			timeout: 30000,
-		});
-		const fileList = fileListResult.status === 0
-			? fileListResult.stdout.trim()
-			: "";
-
-		// Get full diff (truncated to avoid blowing up context)
-		const diffResult = spawnSync("git", ["diff", range], {
-			encoding: "utf-8",
-			cwd,
-			timeout: 30000,
-			maxBuffer: 200 * 1024, // 200KB max
-		});
-		const diff = diffResult.status === 0
-			? diffResult.stdout.trim()
-			: "(git diff unavailable)";
-
-		return { diff, fileList };
-	} catch {
-		return { diff: "(git diff failed)", fileList: "(file list unavailable)" };
-	}
-}
-
-/**
- * Generate the quality gate review prompt that instructs the review agent
- * to produce a structured JSON verdict.
- *
- * The prompt includes:
- * - PROMPT.md content (task requirements)
- * - STATUS.md content (declared progress)
- * - Git diff of all task changes
- * - File change list
- * - JSON schema for the verdict
- * - Instructions for fail criteria
- *
- * @param context - Task context for evidence building
- * @param cwd - Working directory for git commands
- * @returns Review prompt string
- */
-/**
- * Build threshold-specific verdict rule lines for the review prompt.
- *
- * This ensures the reviewer's instructions match the runtime behavior of
- * `applyVerdictRules()` — preventing false failures caused by the reviewer
- * emitting NEEDS_FIXES for findings that the runtime threshold would ignore.
- */
-function buildThresholdRules(threshold: PassThreshold): string[] {
-	const rules: string[] = [];
-
-	// Common rules — always apply
-	rules.push(`- **NEEDS_FIXES** if any finding has category \`status_mismatch\` (checkbox claims work is done but it isn't)`);
-	rules.push(`- **NEEDS_FIXES** if any finding has severity \`critical\``);
-
-	// Threshold-specific rules
-	switch (threshold) {
-		case "no_critical":
-			rules.push(`- **PASS** even if there are \`important\` or \`suggestion\` findings (threshold: \`no_critical\`)`);
-			break;
-		case "no_important":
-			rules.push(`- **NEEDS_FIXES** if 3 or more findings have severity \`important\``);
-			rules.push(`- **PASS** if only \`suggestion\`-level findings remain`);
-			break;
-		case "all_clear":
-			rules.push(`- **NEEDS_FIXES** if ANY findings exist (including \`suggestion\`-level)`);
-			break;
-	}
-
-	rules.push(`- **PASS** if no findings at all`);
-	rules.push(``);
-
-	return rules;
-}
-
-export function generateQualityGatePrompt(context: QualityGateContext, cwd: string): string {
-	const statusPath = join(context.taskFolder, "STATUS.md");
-	const verdictPath = join(context.taskFolder, VERDICT_FILENAME);
-
-	// Read evidence files
-	let promptContent = "(PROMPT.md not found)";
-	try {
-		if (existsSync(context.promptPath)) {
-			promptContent = readFileSync(context.promptPath, "utf-8");
-		}
-	} catch { /* fail-open: proceed without */ }
-
-	let statusContent = "(STATUS.md not found)";
-	try {
-		if (existsSync(statusPath)) {
-			statusContent = readFileSync(statusPath, "utf-8");
-		}
-	} catch { /* fail-open: proceed without */ }
-
-	const { diff, fileList } = buildGitDiff(cwd);
-
-	// Truncate diff if too long (keep first 100KB)
-	const maxDiffLen = 100 * 1024;
-	const truncatedDiff = diff.length > maxDiffLen
-		? diff.slice(0, maxDiffLen) + "\n\n... (diff truncated at 100KB) ..."
-		: diff;
-
-	return [
-		`# Quality Gate Review`,
-		``,
-		`You are performing a structured post-completion quality gate review for task **${context.taskId}** in project **${context.projectName}**.`,
-		``,
-		`Your job is to verify that the task was completed correctly by comparing the PROMPT requirements against the actual code changes and STATUS.md progress claims.`,
-		``,
-		`## Task Requirements (PROMPT.md)`,
-		``,
-		`\`\`\`markdown`,
-		promptContent,
-		`\`\`\``,
-		``,
-		`## Declared Progress (STATUS.md)`,
-		``,
-		`\`\`\`markdown`,
-		statusContent,
-		`\`\`\``,
-		``,
-		`## Changed Files`,
-		``,
-		`\`\`\``,
-		fileList,
-		`\`\`\``,
-		``,
-		`## Git Diff`,
-		``,
-		`\`\`\`diff`,
-		truncatedDiff,
-		`\`\`\``,
-		``,
-		`## Instructions`,
-		``,
-		`1. **Read the PROMPT.md requirements** carefully — identify every deliverable and acceptance criterion.`,
-		`2. **Cross-check STATUS.md checkboxes** — verify each checked item actually has corresponding code/test changes in the diff.`,
-		`3. **Review the git diff** — look for missing implementations, incorrect logic, incomplete work.`,
-		`4. **Use tools** to read actual source files if the diff is unclear.`,
-		`5. **Produce your verdict** as a JSON object written to the file specified below.`,
-		``,
-		`## Verdict Rules`,
-		``,
-		`Report ALL findings you discover with accurate severities. The runtime will`,
-		`apply the configured pass threshold (\`${context.passThreshold}\`) to decide pass/fail.`,
-		``,
-		`Use these rules to determine your verdict:`,
-		...buildThresholdRules(context.passThreshold),
-		``,
-		`## Output Format`,
-		``,
-		`Write a JSON file to: \`${verdictPath}\``,
-		``,
-		`The JSON must conform to this schema:`,
-		``,
-		`\`\`\`json`,
-		`{`,
-		`  "verdict": "PASS" | "NEEDS_FIXES",`,
-		`  "confidence": "high" | "medium" | "low",`,
-		`  "summary": "Brief overall assessment",`,
-		`  "findings": [`,
-		`    {`,
-		`      "severity": "critical" | "important" | "suggestion",`,
-		`      "category": "missing_requirement" | "incorrect_implementation" | "incomplete_work" | "status_mismatch",`,
-		`      "description": "What is wrong",`,
-		`      "file": "path/to/file.ts",`,
-		`      "remediation": "Specific fix instruction"`,
-		`    }`,
-		`  ],`,
-		`  "statusReconciliation": [`,
-		`    {`,
-		`      "checkbox": "Original checkbox text",`,
-		`      "actualState": "done" | "not_done" | "partial",`,
-		`      "evidence": "How you verified"`,
-		`    }`,
-		`  ]`,
-		`}`,
-		`\`\`\``,
-		``,
-		`**IMPORTANT:** Write ONLY valid JSON to the verdict file. No markdown, no explanation — just the JSON object.`,
-		``,
-	].join("\n");
-}
-
-// ── Quality Gate Result ──────────────────────────────────────────────
-
-/** Result of a quality gate review cycle. */
-export interface QualityGateResult {
-	/** Whether the task passed the quality gate */
-	passed: boolean;
-	/** Parsed verdict from the review agent (fail-open sentinel if parsing failed) */
-	verdict: ReviewVerdict;
-	/** Evaluation of verdict rules against threshold */
-	evaluation: VerdictEvaluation;
-	/** Number of review cycles consumed so far */
-	cyclesUsed: number;
-	/** Whether the gate was skipped because it's disabled */
-	skipped: boolean;
-}
-
-/**
- * Read and evaluate the quality gate verdict file from the task folder.
- *
- * Handles all fail-open paths:
- * - Missing verdict file → synthetic PASS
- * - Malformed JSON → synthetic PASS
- * - Invalid verdict structure → synthetic PASS
- *
- * @param taskFolder - Absolute path to task folder
- * @param passThreshold - Configured pass threshold
- * @returns Evaluated quality gate result
- */
-export function readAndEvaluateVerdict(
-	taskFolder: string,
-	passThreshold: PassThreshold,
-): { verdict: ReviewVerdict; evaluation: VerdictEvaluation } {
-	const verdictPath = join(taskFolder, VERDICT_FILENAME);
-
-	let rawJson: string | null = null;
-	try {
-		if (existsSync(verdictPath)) {
-			rawJson = readFileSync(verdictPath, "utf-8");
-		}
-	} catch {
-		// File read error → fail-open
-	}
-
-	const verdict = parseVerdict(rawJson);
-	const evaluation = applyVerdictRules(verdict, passThreshold);
-
-	return { verdict, evaluation };
-}
-
-// ── STATUS.md Reconciliation ─────────────────────────────────────────
-
-/** Result of applying status reconciliation to STATUS.md. */
-export interface ReconciliationResult {
-	/** Number of checkboxes whose state was changed */
-	changed: number;
-	/** Number of reconciliation entries that matched but required no change */
-	alreadyCorrect: number;
-	/** Number of reconciliation entries that could not be matched to a checkbox */
-	unmatched: number;
-	/** Details of each action taken */
-	actions: ReconciliationAction[];
-}
-
-/** A single reconciliation action applied (or skipped). */
-export interface ReconciliationAction {
-	/** The checkbox text from the reconciliation entry */
-	checkbox: string;
-	/** What happened */
-	outcome: "checked" | "unchecked" | "no_change" | "unmatched";
-	/** Human-readable reason */
-	reason: string;
-}
-
-/**
- * Normalize checkbox text for fuzzy matching.
- *
- * Strips markdown formatting, collapses whitespace, lowercases, and removes
- * leading punctuation/bullets. This allows reconciliation entries (which come
- * from the review agent's paraphrasing) to match STATUS.md checkboxes that
- * may differ in whitespace, casing, or minor formatting.
- */
-function normalizeCheckboxText(text: string): string {
-	return text
-		.replace(/\*\*|__|``|`/g, "")       // strip bold/code formatting
-		.replace(/\s+/g, " ")                // collapse whitespace
-		.replace(/^\s*[-*•]\s*/, "")          // strip leading bullets
-		.trim()
-		.toLowerCase();
-}
-
-/**
- * Apply statusReconciliation entries to STATUS.md checkboxes.
- *
- * For each reconciliation entry:
- * - `done` → ensure checkbox is checked (`[x]`)
- * - `not_done` → ensure checkbox is unchecked (`[ ]`)
- * - `partial` → ensure checkbox is unchecked (`[ ]`) with "(partial)" annotation
- *
- * Matching strategy: normalize both the reconciliation `checkbox` text and the
- * STATUS.md checkbox text, then match by substring containment (reconciliation
- * text contained in STATUS line or vice versa). First match wins — duplicates
- * are logged as "unmatched" after the first match is consumed.
- *
- * Idempotency: if a checkbox already has the correct state, no change is made.
- * If no net changes occur, STATUS.md is not rewritten.
- *
- * @param statusPath - Absolute path to STATUS.md
- * @param reconciliations - Array of reconciliation entries from the verdict
- * @returns Summary of changes applied
- */
-export function applyStatusReconciliation(
-	statusPath: string,
-	reconciliations: StatusReconciliation[],
-): ReconciliationResult {
-	const result: ReconciliationResult = {
-		changed: 0,
-		alreadyCorrect: 0,
-		unmatched: 0,
-		actions: [],
-	};
-
-	if (!reconciliations || reconciliations.length === 0) {
-		return result;
-	}
-
-	let content: string;
-	try {
-		if (!existsSync(statusPath)) {
-			// No STATUS.md — mark all as unmatched
-			for (const r of reconciliations) {
-				result.unmatched++;
-				result.actions.push({ checkbox: r.checkbox, outcome: "unmatched", reason: "STATUS.md not found" });
-			}
-			return result;
-		}
-		content = readFileSync(statusPath, "utf-8");
-	} catch {
-		for (const r of reconciliations) {
-			result.unmatched++;
-			result.actions.push({ checkbox: r.checkbox, outcome: "unmatched", reason: "STATUS.md unreadable" });
-		}
-		return result;
-	}
-
-	// Parse lines, identify checkbox lines with their indices
-	const lines = content.split("\n");
-	const checkboxRegex = /^(\s*-\s*\[)([ xX])(\]\s*)(.*)/;
-
-	// Track which line indices have been consumed by a reconciliation match
-	const consumed = new Set<number>();
-
-	for (const recon of reconciliations) {
-		const normalizedRecon = normalizeCheckboxText(recon.checkbox);
-		if (!normalizedRecon) {
-			result.unmatched++;
-			result.actions.push({ checkbox: recon.checkbox, outcome: "unmatched", reason: "Empty checkbox text after normalization" });
-			continue;
-		}
-
-		// Find the best matching checkbox line (first unconsumed match)
-		let matchedIdx = -1;
-		for (let i = 0; i < lines.length; i++) {
-			if (consumed.has(i)) continue;
-			const cbMatch = lines[i].match(checkboxRegex);
-			if (!cbMatch) continue;
-
-			const lineText = normalizeCheckboxText(cbMatch[4]);
-			// Match if either contains the other (handles paraphrasing)
-			if (lineText === normalizedRecon || lineText.includes(normalizedRecon) || normalizedRecon.includes(lineText)) {
-				matchedIdx = i;
-				break;
-			}
-		}
-
-		if (matchedIdx === -1) {
-			result.unmatched++;
-			result.actions.push({ checkbox: recon.checkbox, outcome: "unmatched", reason: "No matching checkbox found in STATUS.md" });
-			continue;
-		}
-
-		consumed.add(matchedIdx);
-		const cbMatch = lines[matchedIdx].match(checkboxRegex)!;
-		const currentlyChecked = cbMatch[2].toLowerCase() === "x";
-		const currentText = cbMatch[4];
-
-		// Determine desired state
-		const shouldBeChecked = recon.actualState === "done";
-		// partial → uncheck (conservative: don't claim done)
-
-		if (shouldBeChecked && currentlyChecked) {
-			// Already correct
-			result.alreadyCorrect++;
-			result.actions.push({ checkbox: recon.checkbox, outcome: "no_change", reason: "Already checked (done)" });
-		} else if (!shouldBeChecked && !currentlyChecked) {
-			// Already correct (unchecked for not_done or partial)
-			// But if partial, might need annotation
-			if (recon.actualState === "partial" && !currentText.includes("(partial)")) {
-				// Add partial annotation
-				lines[matchedIdx] = `${cbMatch[1]} ${cbMatch[3]}${currentText} (partial)`;
-				result.changed++;
-				result.actions.push({ checkbox: recon.checkbox, outcome: "unchecked", reason: "Added (partial) annotation" });
-			} else {
-				result.alreadyCorrect++;
-				result.actions.push({ checkbox: recon.checkbox, outcome: "no_change", reason: `Already unchecked (${recon.actualState})` });
-			}
-		} else if (shouldBeChecked && !currentlyChecked) {
-			// Need to check
-			lines[matchedIdx] = `${cbMatch[1]}x${cbMatch[3]}${currentText}`;
-			result.changed++;
-			result.actions.push({ checkbox: recon.checkbox, outcome: "checked", reason: "Work done but box was unchecked" });
-		} else {
-			// currentlyChecked but should not be (not_done or partial)
-			const annotation = recon.actualState === "partial" ? " (partial)" : "";
-			const cleanText = currentText.replace(/\s*\(partial\)\s*$/, "");
-			lines[matchedIdx] = `${cbMatch[1]} ${cbMatch[3]}${cleanText}${annotation}`;
-			result.changed++;
-			const outcomeReason = recon.actualState === "partial"
-				? "Unchecked — work partially done"
-				: "Unchecked — work not done";
-			result.actions.push({ checkbox: recon.checkbox, outcome: "unchecked", reason: outcomeReason });
-		}
-	}
-
-	// Only rewrite if there were actual changes
-	if (result.changed > 0) {
-		try {
-			writeFileSync(statusPath, lines.join("\n"), "utf-8");
-		} catch {
-			// Write failed — downgrade changes to unmatched for accuracy
-			// (the in-memory result says "changed" but file wasn't updated)
-			for (const action of result.actions) {
-				if (action.outcome === "checked" || action.outcome === "unchecked") {
-					action.outcome = "unmatched";
-					action.reason += " (write failed)";
-					result.changed--;
-					result.unmatched++;
-				}
-			}
-		}
-	}
-
-	return result;
-}
-
-// ── Remediation: Feedback & Fix Agent Prompt ─────────────────────────
-
-/** Path for the review feedback file written for the fix agent. */
-export const FEEDBACK_FILENAME = "REVIEW_FEEDBACK.md";
-
-/**
- * Generate a deterministic REVIEW_FEEDBACK.md from a NEEDS_FIXES verdict.
- *
- * Includes blocking findings based on the configured pass threshold:
- * - `no_critical` / `no_important`: critical + important findings only
- * - `all_clear`: critical + important + suggestion findings (all are blocking)
- *
- * The template is stable across runs so fix-agent prompts are reproducible.
- *
- * This file is intentionally staged as a task artifact (aligns with
- * roadmap 5e: REVIEW_FEEDBACK.md is part of the review audit trail).
- *
- * @param verdict - The NEEDS_FIXES review verdict
- * @param cycleNum - Current remediation cycle number (1-based)
- * @param maxCycles - Maximum review cycles configured
- * @param passThreshold - Configured pass threshold (determines which severities are blocking)
- * @returns Markdown content for REVIEW_FEEDBACK.md
- */
-export function generateFeedbackMd(
-	verdict: ReviewVerdict,
-	cycleNum: number,
-	maxCycles: number,
-	passThreshold: PassThreshold = "no_critical",
-): string {
-	const criticals = verdict.findings.filter(f => f.severity === "critical");
-	const importants = verdict.findings.filter(f => f.severity === "important");
-	const suggestions = verdict.findings.filter(f => f.severity === "suggestion");
-	const mismatches = verdict.statusReconciliation.filter(r => r.actualState !== "done");
-
-	// Under all_clear, suggestions are also blocking
-	const includeSuggestions = passThreshold === "all_clear";
-
-	const blockingLabel = includeSuggestions
-		? "critical, important, and suggestion"
-		: "critical and important";
-
-	const lines: string[] = [
-		`# Review Feedback — Cycle ${cycleNum}/${maxCycles}`,
-		``,
-		`**Verdict:** NEEDS_FIXES`,
-		`**Confidence:** ${verdict.confidence}`,
-		`**Summary:** ${verdict.summary}`,
-		`**Pass Threshold:** \`${passThreshold}\``,
-		``,
-		`> This file was generated by the quality gate. Address all ${blockingLabel}`,
-		`> findings below, then the review will re-run automatically.`,
-		``,
-	];
-
-	if (criticals.length > 0) {
-		lines.push(`## Critical Findings (${criticals.length})`);
-		lines.push(``);
-		for (let i = 0; i < criticals.length; i++) {
-			const f = criticals[i];
-			lines.push(`### C${i + 1}: ${f.description}`);
-			lines.push(``);
-			lines.push(`- **Category:** ${f.category}`);
-			if (f.file) lines.push(`- **File:** \`${f.file}\``);
-			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
-			lines.push(``);
-		}
-	}
-
-	if (importants.length > 0) {
-		lines.push(`## Important Findings (${importants.length})`);
-		lines.push(``);
-		for (let i = 0; i < importants.length; i++) {
-			const f = importants[i];
-			lines.push(`### I${i + 1}: ${f.description}`);
-			lines.push(``);
-			lines.push(`- **Category:** ${f.category}`);
-			if (f.file) lines.push(`- **File:** \`${f.file}\``);
-			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
-			lines.push(``);
-		}
-	}
-
-	if (includeSuggestions && suggestions.length > 0) {
-		lines.push(`## Suggestion Findings (${suggestions.length})`);
-		lines.push(``);
-		lines.push(`> Under \`all_clear\` threshold, suggestions are also blocking.`);
-		lines.push(``);
-		for (let i = 0; i < suggestions.length; i++) {
-			const f = suggestions[i];
-			lines.push(`### S${i + 1}: ${f.description}`);
-			lines.push(``);
-			lines.push(`- **Category:** ${f.category}`);
-			if (f.file) lines.push(`- **File:** \`${f.file}\``);
-			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
-			lines.push(``);
-		}
-	}
-
-	if (mismatches.length > 0) {
-		lines.push(`## STATUS.md Reconciliation Issues (${mismatches.length})`);
-		lines.push(``);
-		for (const r of mismatches) {
-			lines.push(`- **Checkbox:** ${r.checkbox}`);
-			lines.push(`  - **Actual state:** ${r.actualState}`);
-			if (r.evidence) lines.push(`  - **Evidence:** ${r.evidence}`);
-		}
-		lines.push(``);
-	}
-
-	const totalBlocking = criticals.length + importants.length
-		+ (includeSuggestions ? suggestions.length : 0) + mismatches.length;
-
-	if (totalBlocking === 0) {
-		lines.push(`## No blocking findings`);
-		lines.push(``);
-		lines.push(`The review returned NEEDS_FIXES but no blocking findings were extracted for threshold \`${passThreshold}\`.`);
-		lines.push(`This may indicate a threshold or verdict-rule mismatch. Review the REVIEW_VERDICT.json for details.`);
-		lines.push(``);
-	}
-
-	return lines.join("\n");
-}
-
-/**
- * Build the prompt for the fix agent that addresses quality gate findings.
- *
- * The fix agent is spawned in the same worktree as the task and receives
- * the REVIEW_FEEDBACK.md content along with task context. It should make
- * targeted code fixes and commit them.
- *
- * @param context - Quality gate context (task folder, IDs, etc.)
- * @param feedbackContent - Content of REVIEW_FEEDBACK.md
- * @param cycleNum - Current fix cycle number
- * @returns Prompt string for the fix agent
- */
-export function buildFixAgentPrompt(
-	context: QualityGateContext,
-	feedbackContent: string,
-	cycleNum: number,
-): string {
-	const statusPath = join(context.taskFolder, "STATUS.md");
-
-	let statusContent = "(STATUS.md not found)";
-	try {
-		if (existsSync(statusPath)) {
-			statusContent = readFileSync(statusPath, "utf-8");
-		}
-	} catch { /* proceed without */ }
-
-	let promptContent = "(PROMPT.md not found)";
-	try {
-		if (existsSync(context.promptPath)) {
-			promptContent = readFileSync(context.promptPath, "utf-8");
-		}
-	} catch { /* proceed without */ }
-
-	return [
-		`# Quality Gate Remediation — Fix Cycle ${cycleNum}`,
-		``,
-		`You are a fix agent addressing quality gate findings for task **${context.taskId}**.`,
-		``,
-		`The quality gate review found issues that must be fixed before the task can be marked complete.`,
-		`Your job is to make targeted, minimal fixes to address the critical and important findings below.`,
-		``,
-		`## Rules`,
-		``,
-		`1. **Read REVIEW_FEEDBACK.md** below — it lists the blocking findings with specific remediation instructions.`,
-		`2. **Fix each finding** — make the minimal code change needed. Do NOT refactor unrelated code.`,
-		`3. **Commit your fixes** with message: \`fix(${context.taskId}): address quality gate findings (cycle ${cycleNum})\``,
-		`4. **Update STATUS.md** if any checkbox states were flagged as incorrect in the reconciliation section.`,
-		`5. **Do NOT create .DONE** — the quality gate will re-run automatically after you exit.`,
-		``,
-		`## Task Context`,
-		``,
-		`- **Task folder:** ${context.taskFolder}/`,
-		`- **PROMPT:** ${context.promptPath}`,
-		`- **STATUS:** ${statusPath}`,
-		``,
-		`## Review Feedback`,
-		``,
-		`\`\`\`markdown`,
-		feedbackContent,
-		`\`\`\``,
-		``,
-		`## Original Task Requirements (PROMPT.md)`,
-		``,
-		`\`\`\`markdown`,
-		promptContent,
-		`\`\`\``,
-		``,
-		`## Current STATUS.md`,
-		``,
-		`\`\`\`markdown`,
-		statusContent,
-		`\`\`\``,
-		``,
-		`**IMPORTANT:** Focus only on fixing the blocking findings. Do not expand scope or create .DONE.`,
-		``,
-	].join("\n");
-}
+/**
+ * Quality Gate — structured post-completion review types and verdict evaluation.
+ *
+ * This module defines the interfaces for quality gate review verdicts and
+ * implements the verdict evaluation logic used by the task-runner to decide
+ * whether a task passes or needs fixes before `.DONE` creation.
+ *
+ * Verdict rules (from roadmap Phase 5a):
+ * - Any `critical` finding → NEEDS_FIXES
+ * - 3+ `important` findings → NEEDS_FIXES
+ * - Only `suggestion` findings → PASS
+ * - Any `status_mismatch` category → NEEDS_FIXES
+ *
+ * Fail-open behavior: malformed or missing verdict JSON → PASS
+ * (prevents quality gate bugs from blocking task completion)
+ *
+ * @module quality-gate
+ */
+
+import type { PassThreshold } from "./config-schema.ts";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { spawnSync } from "child_process";
+
+// ── Verdict Interfaces ───────────────────────────────────────────────
+
+/** Severity levels for review findings, ordered by decreasing severity. */
+export type FindingSeverity = "critical" | "important" | "suggestion";
+
+/** Categories of review findings. */
+export type FindingCategory =
+	| "missing_requirement"
+	| "incorrect_implementation"
+	| "incomplete_work"
+	| "status_mismatch";
+
+/** A single finding from the quality gate review. */
+export interface ReviewFinding {
+	/** Severity of the finding */
+	severity: FindingSeverity;
+	/** Category classifying what kind of issue was found */
+	category: FindingCategory;
+	/** Human-readable description of the issue */
+	description: string;
+	/** File path related to the finding (may be empty) */
+	file: string;
+	/** Specific fix instruction for the remediation agent */
+	remediation: string;
+}
+
+/** STATUS.md checkbox reconciliation entry. */
+export interface StatusReconciliation {
+	/** Original checkbox text from STATUS.md */
+	checkbox: string;
+	/** Actual state determined by review */
+	actualState: "done" | "not_done" | "partial";
+	/** Evidence supporting the state determination */
+	evidence: string;
+}
+
+/** Overall quality gate verdict from the review agent. */
+export interface ReviewVerdict {
+	/** Pass/fail verdict */
+	verdict: "PASS" | "NEEDS_FIXES";
+	/** Review agent confidence level */
+	confidence: "high" | "medium" | "low";
+	/** Brief overall assessment */
+	summary: string;
+	/** Individual findings from the review */
+	findings: ReviewFinding[];
+	/** STATUS.md checkbox reconciliation results */
+	statusReconciliation: StatusReconciliation[];
+}
+
+// ── Verdict Evaluation ───────────────────────────────────────────────
+
+/** Reason why a verdict was determined to be NEEDS_FIXES. */
+export interface VerdictFailReason {
+	/** Rule that triggered the failure */
+	rule: "critical_finding" | "important_threshold" | "status_mismatch" | "verdict_says_needs_fixes";
+	/** Human-readable explanation */
+	detail: string;
+}
+
+/** Result of applying verdict rules to a parsed ReviewVerdict. */
+export interface VerdictEvaluation {
+	/** Whether the task passes the quality gate */
+	pass: boolean;
+	/** Reasons for failure (empty array if pass is true) */
+	failReasons: VerdictFailReason[];
+}
+
+/**
+ * Apply verdict rules to determine pass/fail based on findings and threshold.
+ *
+ * Rules applied in order:
+ * 1. Any finding with category `status_mismatch` → NEEDS_FIXES
+ * 2. Any finding with severity `critical` → NEEDS_FIXES
+ * 3. Threshold-dependent important finding count check
+ * 4. If verdict itself says NEEDS_FIXES → respect it
+ *
+ * Threshold behavior:
+ * - `no_critical`: PASS if no critical findings and no status mismatches
+ * - `no_important`: PASS if no critical, fewer than 3 important, no status mismatches
+ * - `all_clear`: PASS only if zero findings of any severity
+ *
+ * @param verdict - Parsed review verdict
+ * @param threshold - Configured pass threshold
+ * @returns Evaluation result with pass/fail and reasons
+ */
+export function applyVerdictRules(
+	verdict: ReviewVerdict,
+	threshold: PassThreshold,
+): VerdictEvaluation {
+	const failReasons: VerdictFailReason[] = [];
+
+	// Rule 1: Any status_mismatch category → NEEDS_FIXES
+	const statusMismatches = verdict.findings.filter(
+		(f) => f.category === "status_mismatch",
+	);
+	if (statusMismatches.length > 0) {
+		failReasons.push({
+			rule: "status_mismatch",
+			detail: `${statusMismatches.length} status mismatch(es) found — checked boxes don't match actual work`,
+		});
+	}
+
+	// Rule 2: Any critical finding → NEEDS_FIXES
+	const criticals = verdict.findings.filter((f) => f.severity === "critical");
+	if (criticals.length > 0) {
+		failReasons.push({
+			rule: "critical_finding",
+			detail: `${criticals.length} critical finding(s)`,
+		});
+	}
+
+	// Rule 3: Threshold-dependent important check
+	const importants = verdict.findings.filter(
+		(f) => f.severity === "important",
+	);
+
+	if (threshold === "no_important" && importants.length >= 3) {
+		failReasons.push({
+			rule: "important_threshold",
+			detail: `${importants.length} important findings (threshold: fewer than 3 required for pass)`,
+		});
+	}
+
+	if (threshold === "all_clear" && verdict.findings.length > 0) {
+		// For all_clear, any finding of any severity blocks pass
+		if (importants.length > 0 && failReasons.every((r) => r.rule !== "important_threshold")) {
+			failReasons.push({
+				rule: "important_threshold",
+				detail: `${importants.length} important finding(s) (all_clear threshold: zero findings required)`,
+			});
+		}
+		// Suggestions also block under all_clear — but we don't need a separate rule
+		// since we'll catch it via the verdict_says_needs_fixes or the overall pass logic
+	}
+
+	// Rule 4: If the verdict itself says NEEDS_FIXES and we haven't already failed
+	if (verdict.verdict === "NEEDS_FIXES" && failReasons.length === 0) {
+		failReasons.push({
+			rule: "verdict_says_needs_fixes",
+			detail: `Review agent verdict: NEEDS_FIXES — ${verdict.summary}`,
+		});
+	}
+
+	// For all_clear threshold: even suggestions-only should fail
+	if (
+		threshold === "all_clear" &&
+		failReasons.length === 0 &&
+		verdict.findings.length > 0
+	) {
+		const suggestions = verdict.findings.filter(
+			(f) => f.severity === "suggestion",
+		);
+		if (suggestions.length > 0) {
+			failReasons.push({
+				rule: "important_threshold",
+				detail: `${suggestions.length} suggestion(s) found (all_clear threshold: zero findings required)`,
+			});
+		}
+	}
+
+	return {
+		pass: failReasons.length === 0,
+		failReasons,
+	};
+}
+
+// ── Verdict Parsing ──────────────────────────────────────────────────
+
+/** Sentinel verdict returned when parsing fails (fail-open). */
+const FAIL_OPEN_VERDICT: ReviewVerdict = {
+	verdict: "PASS",
+	confidence: "low",
+	summary: "Verdict could not be parsed — fail-open policy applied",
+	findings: [],
+	statusReconciliation: [],
+};
+
+/**
+ * Parse a JSON string into a ReviewVerdict, with fail-open behavior.
+ *
+ * If the input is missing, empty, or malformed JSON, returns a PASS verdict
+ * (fail-open) to prevent quality gate bugs from blocking task completion.
+ *
+ * Performs structural validation:
+ * - `verdict` must be "PASS" or "NEEDS_FIXES"
+ * - `findings` must be an array (defaults to [] if missing)
+ * - `statusReconciliation` must be an array (defaults to [] if missing)
+ * - Individual findings are validated and malformed entries are dropped
+ *
+ * @param jsonString - Raw JSON string from review agent output
+ * @returns Parsed and validated ReviewVerdict (never throws)
+ */
+export function parseVerdict(jsonString: string | undefined | null): ReviewVerdict {
+	if (!jsonString || jsonString.trim() === "") {
+		return { ...FAIL_OPEN_VERDICT, summary: "No verdict provided — fail-open policy applied" };
+	}
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(jsonString);
+	} catch {
+		return { ...FAIL_OPEN_VERDICT, summary: "Malformed JSON in verdict — fail-open policy applied" };
+	}
+
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return { ...FAIL_OPEN_VERDICT, summary: "Verdict is not a JSON object — fail-open policy applied" };
+	}
+
+	const obj = raw as Record<string, unknown>;
+
+	// Validate verdict field
+	const verdict = obj.verdict;
+	if (verdict !== "PASS" && verdict !== "NEEDS_FIXES") {
+		return { ...FAIL_OPEN_VERDICT, summary: `Invalid verdict value "${String(verdict)}" — fail-open policy applied` };
+	}
+
+	// Parse confidence with fallback
+	const validConfidence = ["high", "medium", "low"];
+	const confidence = validConfidence.includes(obj.confidence as string)
+		? (obj.confidence as "high" | "medium" | "low")
+		: "medium";
+
+	// Parse summary with fallback
+	const summary = typeof obj.summary === "string" ? obj.summary : "";
+
+	// Parse and validate findings
+	const findings = validateFindings(obj.findings);
+
+	// Parse and validate statusReconciliation
+	const statusReconciliation = validateReconciliations(obj.statusReconciliation);
+
+	return {
+		verdict,
+		confidence,
+		summary,
+		findings,
+		statusReconciliation,
+	};
+}
+
+// ── Internal Validation Helpers ──────────────────────────────────────
+
+const VALID_SEVERITIES: FindingSeverity[] = ["critical", "important", "suggestion"];
+const VALID_CATEGORIES: FindingCategory[] = [
+	"missing_requirement",
+	"incorrect_implementation",
+	"incomplete_work",
+	"status_mismatch",
+];
+const VALID_STATES = ["done", "not_done", "partial"];
+
+/**
+ * Validate and normalize the findings array.
+ * Drops individual entries that don't have minimum required fields.
+ */
+function validateFindings(raw: unknown): ReviewFinding[] {
+	if (!Array.isArray(raw)) return [];
+
+	const validated: ReviewFinding[] = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		const f = item as Record<string, unknown>;
+
+		// Severity is required and must be valid
+		if (!VALID_SEVERITIES.includes(f.severity as FindingSeverity)) continue;
+
+		// Category is required and must be valid
+		if (!VALID_CATEGORIES.includes(f.category as FindingCategory)) continue;
+
+		// Description is required
+		if (typeof f.description !== "string" || f.description.trim() === "") continue;
+
+		validated.push({
+			severity: f.severity as FindingSeverity,
+			category: f.category as FindingCategory,
+			description: f.description as string,
+			file: typeof f.file === "string" ? f.file : "",
+			remediation: typeof f.remediation === "string" ? f.remediation : "",
+		});
+	}
+
+	return validated;
+}
+
+/**
+ * Validate and normalize the statusReconciliation array.
+ * Drops individual entries that don't have minimum required fields.
+ */
+function validateReconciliations(raw: unknown): StatusReconciliation[] {
+	if (!Array.isArray(raw)) return [];
+
+	const validated: StatusReconciliation[] = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		const r = item as Record<string, unknown>;
+
+		if (typeof r.checkbox !== "string" || r.checkbox.trim() === "") continue;
+		if (!VALID_STATES.includes(r.actualState as string)) continue;
+
+		validated.push({
+			checkbox: r.checkbox as string,
+			actualState: r.actualState as "done" | "not_done" | "partial",
+			evidence: typeof r.evidence === "string" ? r.evidence : "",
+		});
+	}
+
+	return validated;
+}
+
+// ── Quality Gate Review Prompt ───────────────────────────────────────
+
+/** Information needed to build the quality gate review evidence package. */
+export interface QualityGateContext {
+	/** Absolute path to task folder */
+	taskFolder: string;
+	/** Absolute path to PROMPT.md */
+	promptPath: string;
+	/** Task ID (e.g., "TP-034") */
+	taskId: string;
+	/** Project name from config */
+	projectName: string;
+	/** Pass threshold from config */
+	passThreshold: PassThreshold;
+}
+
+/** Path where the quality gate verdict JSON file is written by the review agent. */
+export const VERDICT_FILENAME = "REVIEW_VERDICT.json";
+
+/**
+ * Compute a robust diff range for the task's git changes.
+ *
+ * Strategy (in order):
+ * 1. `git merge-base HEAD main` — ideal for topic branches
+ * 2. `git merge-base HEAD origin/main` — fallback for detached/worktree checkouts
+ * 3. `HEAD~N` where N = min(commit count, 50) — bounded fallback for repos
+ *    without a main branch or with shallow history
+ * 4. Empty string (signals diff unavailable)
+ */
+function computeDiffBase(cwd: string): string {
+	const opts = { encoding: "utf-8" as const, cwd, timeout: 15000 };
+
+	// Try merge-base with local main
+	for (const ref of ["main", "origin/main", "master", "origin/master"]) {
+		const result = spawnSync("git", ["merge-base", "HEAD", ref], opts);
+		if (result.status === 0 && result.stdout.trim()) {
+			return result.stdout.trim();
+		}
+	}
+
+	// Fallback: count commits and use HEAD~N (bounded)
+	const countResult = spawnSync("git", ["rev-list", "--count", "HEAD"], opts);
+	if (countResult.status === 0) {
+		const count = parseInt(countResult.stdout.trim(), 10);
+		if (count > 1) {
+			const n = Math.min(count - 1, 50);
+			return `HEAD~${n}`;
+		}
+	}
+
+	return "";
+}
+
+/**
+ * Build the git diff for the entire task.
+ *
+ * Uses `computeDiffBase()` to find a robust baseline, then runs `git diff`
+ * between that base and HEAD. Falls back gracefully when git is unavailable
+ * or the repository has insufficient history.
+ */
+function buildGitDiff(cwd: string): { diff: string; fileList: string } {
+	try {
+		const base = computeDiffBase(cwd);
+		if (!base) {
+			return { diff: "(git diff unavailable — could not determine base)", fileList: "(file list unavailable)" };
+		}
+
+		const range = `${base}..HEAD`;
+
+		// Get file list of changed files
+		const fileListResult = spawnSync("git", ["diff", "--name-only", range], {
+			encoding: "utf-8",
+			cwd,
+			timeout: 30000,
+		});
+		const fileList = fileListResult.status === 0
+			? fileListResult.stdout.trim()
+			: "";
+
+		// Get full diff (truncated to avoid blowing up context)
+		const diffResult = spawnSync("git", ["diff", range], {
+			encoding: "utf-8",
+			cwd,
+			timeout: 30000,
+			maxBuffer: 200 * 1024, // 200KB max
+		});
+		const diff = diffResult.status === 0
+			? diffResult.stdout.trim()
+			: "(git diff unavailable)";
+
+		return { diff, fileList };
+	} catch {
+		return { diff: "(git diff failed)", fileList: "(file list unavailable)" };
+	}
+}
+
+/**
+ * Generate the quality gate review prompt that instructs the review agent
+ * to produce a structured JSON verdict.
+ *
+ * The prompt includes:
+ * - PROMPT.md content (task requirements)
+ * - STATUS.md content (declared progress)
+ * - Git diff of all task changes
+ * - File change list
+ * - JSON schema for the verdict
+ * - Instructions for fail criteria
+ *
+ * @param context - Task context for evidence building
+ * @param cwd - Working directory for git commands
+ * @returns Review prompt string
+ */
+/**
+ * Build threshold-specific verdict rule lines for the review prompt.
+ *
+ * This ensures the reviewer's instructions match the runtime behavior of
+ * `applyVerdictRules()` — preventing false failures caused by the reviewer
+ * emitting NEEDS_FIXES for findings that the runtime threshold would ignore.
+ */
+function buildThresholdRules(threshold: PassThreshold): string[] {
+	const rules: string[] = [];
+
+	// Common rules — always apply
+	rules.push(`- **NEEDS_FIXES** if any finding has category \`status_mismatch\` (checkbox claims work is done but it isn't)`);
+	rules.push(`- **NEEDS_FIXES** if any finding has severity \`critical\``);
+
+	// Threshold-specific rules
+	switch (threshold) {
+		case "no_critical":
+			rules.push(`- **PASS** even if there are \`important\` or \`suggestion\` findings (threshold: \`no_critical\`)`);
+			break;
+		case "no_important":
+			rules.push(`- **NEEDS_FIXES** if 3 or more findings have severity \`important\``);
+			rules.push(`- **PASS** if only \`suggestion\`-level findings remain`);
+			break;
+		case "all_clear":
+			rules.push(`- **NEEDS_FIXES** if ANY findings exist (including \`suggestion\`-level)`);
+			break;
+	}
+
+	rules.push(`- **PASS** if no findings at all`);
+	rules.push(``);
+
+	return rules;
+}
+
+export function generateQualityGatePrompt(context: QualityGateContext, cwd: string): string {
+	const statusPath = join(context.taskFolder, "STATUS.md");
+	const verdictPath = join(context.taskFolder, VERDICT_FILENAME);
+
+	// Read evidence files
+	let promptContent = "(PROMPT.md not found)";
+	try {
+		if (existsSync(context.promptPath)) {
+			promptContent = readFileSync(context.promptPath, "utf-8");
+		}
+	} catch { /* fail-open: proceed without */ }
+
+	let statusContent = "(STATUS.md not found)";
+	try {
+		if (existsSync(statusPath)) {
+			statusContent = readFileSync(statusPath, "utf-8");
+		}
+	} catch { /* fail-open: proceed without */ }
+
+	const { diff, fileList } = buildGitDiff(cwd);
+
+	// Truncate diff if too long (keep first 100KB)
+	const maxDiffLen = 100 * 1024;
+	const truncatedDiff = diff.length > maxDiffLen
+		? diff.slice(0, maxDiffLen) + "\n\n... (diff truncated at 100KB) ..."
+		: diff;
+
+	return [
+		`# Quality Gate Review`,
+		``,
+		`You are performing a structured post-completion quality gate review for task **${context.taskId}** in project **${context.projectName}**.`,
+		``,
+		`Your job is to verify that the task was completed correctly by comparing the PROMPT requirements against the actual code changes and STATUS.md progress claims.`,
+		``,
+		`## Task Requirements (PROMPT.md)`,
+		``,
+		`\`\`\`markdown`,
+		promptContent,
+		`\`\`\``,
+		``,
+		`## Declared Progress (STATUS.md)`,
+		``,
+		`\`\`\`markdown`,
+		statusContent,
+		`\`\`\``,
+		``,
+		`## Changed Files`,
+		``,
+		`\`\`\``,
+		fileList,
+		`\`\`\``,
+		``,
+		`## Git Diff`,
+		``,
+		`\`\`\`diff`,
+		truncatedDiff,
+		`\`\`\``,
+		``,
+		`## Instructions`,
+		``,
+		`1. **Read the PROMPT.md requirements** carefully — identify every deliverable and acceptance criterion.`,
+		`2. **Cross-check STATUS.md checkboxes** — verify each checked item actually has corresponding code/test changes in the diff.`,
+		`3. **Review the git diff** — look for missing implementations, incorrect logic, incomplete work.`,
+		`4. **Use tools** to read actual source files if the diff is unclear.`,
+		`5. **Produce your verdict** as a JSON object written to the file specified below.`,
+		``,
+		`## Verdict Rules`,
+		``,
+		`Report ALL findings you discover with accurate severities. The runtime will`,
+		`apply the configured pass threshold (\`${context.passThreshold}\`) to decide pass/fail.`,
+		``,
+		`Use these rules to determine your verdict:`,
+		...buildThresholdRules(context.passThreshold),
+		``,
+		`## Output Format`,
+		``,
+		`Write a JSON file to: \`${verdictPath}\``,
+		``,
+		`The JSON must conform to this schema:`,
+		``,
+		`\`\`\`json`,
+		`{`,
+		`  "verdict": "PASS" | "NEEDS_FIXES",`,
+		`  "confidence": "high" | "medium" | "low",`,
+		`  "summary": "Brief overall assessment",`,
+		`  "findings": [`,
+		`    {`,
+		`      "severity": "critical" | "important" | "suggestion",`,
+		`      "category": "missing_requirement" | "incorrect_implementation" | "incomplete_work" | "status_mismatch",`,
+		`      "description": "What is wrong",`,
+		`      "file": "path/to/file.ts",`,
+		`      "remediation": "Specific fix instruction"`,
+		`    }`,
+		`  ],`,
+		`  "statusReconciliation": [`,
+		`    {`,
+		`      "checkbox": "Original checkbox text",`,
+		`      "actualState": "done" | "not_done" | "partial",`,
+		`      "evidence": "How you verified"`,
+		`    }`,
+		`  ]`,
+		`}`,
+		`\`\`\``,
+		``,
+		`**IMPORTANT:** Write ONLY valid JSON to the verdict file. No markdown, no explanation — just the JSON object.`,
+		``,
+	].join("\n");
+}
+
+// ── Quality Gate Result ──────────────────────────────────────────────
+
+/** Result of a quality gate review cycle. */
+export interface QualityGateResult {
+	/** Whether the task passed the quality gate */
+	passed: boolean;
+	/** Parsed verdict from the review agent (fail-open sentinel if parsing failed) */
+	verdict: ReviewVerdict;
+	/** Evaluation of verdict rules against threshold */
+	evaluation: VerdictEvaluation;
+	/** Number of review cycles consumed so far */
+	cyclesUsed: number;
+	/** Whether the gate was skipped because it's disabled */
+	skipped: boolean;
+}
+
+/**
+ * Read and evaluate the quality gate verdict file from the task folder.
+ *
+ * Handles all fail-open paths:
+ * - Missing verdict file → synthetic PASS
+ * - Malformed JSON → synthetic PASS
+ * - Invalid verdict structure → synthetic PASS
+ *
+ * @param taskFolder - Absolute path to task folder
+ * @param passThreshold - Configured pass threshold
+ * @returns Evaluated quality gate result
+ */
+export function readAndEvaluateVerdict(
+	taskFolder: string,
+	passThreshold: PassThreshold,
+): { verdict: ReviewVerdict; evaluation: VerdictEvaluation } {
+	const verdictPath = join(taskFolder, VERDICT_FILENAME);
+
+	let rawJson: string | null = null;
+	try {
+		if (existsSync(verdictPath)) {
+			rawJson = readFileSync(verdictPath, "utf-8");
+		}
+	} catch {
+		// File read error → fail-open
+	}
+
+	const verdict = parseVerdict(rawJson);
+	const evaluation = applyVerdictRules(verdict, passThreshold);
+
+	return { verdict, evaluation };
+}
+
+// ── STATUS.md Reconciliation ─────────────────────────────────────────
+
+/** Result of applying status reconciliation to STATUS.md. */
+export interface ReconciliationResult {
+	/** Number of checkboxes whose state was changed */
+	changed: number;
+	/** Number of reconciliation entries that matched but required no change */
+	alreadyCorrect: number;
+	/** Number of reconciliation entries that could not be matched to a checkbox */
+	unmatched: number;
+	/** Details of each action taken */
+	actions: ReconciliationAction[];
+}
+
+/** A single reconciliation action applied (or skipped). */
+export interface ReconciliationAction {
+	/** The checkbox text from the reconciliation entry */
+	checkbox: string;
+	/** What happened */
+	outcome: "checked" | "unchecked" | "no_change" | "unmatched";
+	/** Human-readable reason */
+	reason: string;
+}
+
+/**
+ * Normalize checkbox text for fuzzy matching.
+ *
+ * Strips markdown formatting, collapses whitespace, lowercases, and removes
+ * leading punctuation/bullets. This allows reconciliation entries (which come
+ * from the review agent's paraphrasing) to match STATUS.md checkboxes that
+ * may differ in whitespace, casing, or minor formatting.
+ */
+function normalizeCheckboxText(text: string): string {
+	return text
+		.replace(/\*\*|__|``|`/g, "")       // strip bold/code formatting
+		.replace(/\s+/g, " ")                // collapse whitespace
+		.replace(/^\s*[-*•]\s*/, "")          // strip leading bullets
+		.trim()
+		.toLowerCase();
+}
+
+/**
+ * Apply statusReconciliation entries to STATUS.md checkboxes.
+ *
+ * For each reconciliation entry:
+ * - `done` → ensure checkbox is checked (`[x]`)
+ * - `not_done` → ensure checkbox is unchecked (`[ ]`)
+ * - `partial` → ensure checkbox is unchecked (`[ ]`) with "(partial)" annotation
+ *
+ * Matching strategy: normalize both the reconciliation `checkbox` text and the
+ * STATUS.md checkbox text, then match by substring containment (reconciliation
+ * text contained in STATUS line or vice versa). First match wins — duplicates
+ * are logged as "unmatched" after the first match is consumed.
+ *
+ * Idempotency: if a checkbox already has the correct state, no change is made.
+ * If no net changes occur, STATUS.md is not rewritten.
+ *
+ * @param statusPath - Absolute path to STATUS.md
+ * @param reconciliations - Array of reconciliation entries from the verdict
+ * @returns Summary of changes applied
+ */
+export function applyStatusReconciliation(
+	statusPath: string,
+	reconciliations: StatusReconciliation[],
+): ReconciliationResult {
+	const result: ReconciliationResult = {
+		changed: 0,
+		alreadyCorrect: 0,
+		unmatched: 0,
+		actions: [],
+	};
+
+	if (!reconciliations || reconciliations.length === 0) {
+		return result;
+	}
+
+	let content: string;
+	try {
+		if (!existsSync(statusPath)) {
+			// No STATUS.md — mark all as unmatched
+			for (const r of reconciliations) {
+				result.unmatched++;
+				result.actions.push({ checkbox: r.checkbox, outcome: "unmatched", reason: "STATUS.md not found" });
+			}
+			return result;
+		}
+		content = readFileSync(statusPath, "utf-8");
+	} catch {
+		for (const r of reconciliations) {
+			result.unmatched++;
+			result.actions.push({ checkbox: r.checkbox, outcome: "unmatched", reason: "STATUS.md unreadable" });
+		}
+		return result;
+	}
+
+	// Parse lines, identify checkbox lines with their indices
+	const lines = content.split("\n");
+	const checkboxRegex = /^(\s*-\s*\[)([ xX])(\]\s*)(.*)/;
+
+	// Track which line indices have been consumed by a reconciliation match
+	const consumed = new Set<number>();
+
+	for (const recon of reconciliations) {
+		const normalizedRecon = normalizeCheckboxText(recon.checkbox);
+		if (!normalizedRecon) {
+			result.unmatched++;
+			result.actions.push({ checkbox: recon.checkbox, outcome: "unmatched", reason: "Empty checkbox text after normalization" });
+			continue;
+		}
+
+		// Find the best matching checkbox line (first unconsumed match)
+		let matchedIdx = -1;
+		for (let i = 0; i < lines.length; i++) {
+			if (consumed.has(i)) continue;
+			const cbMatch = lines[i].match(checkboxRegex);
+			if (!cbMatch) continue;
+
+			const lineText = normalizeCheckboxText(cbMatch[4]);
+			// Match if either contains the other (handles paraphrasing)
+			if (lineText === normalizedRecon || lineText.includes(normalizedRecon) || normalizedRecon.includes(lineText)) {
+				matchedIdx = i;
+				break;
+			}
+		}
+
+		if (matchedIdx === -1) {
+			result.unmatched++;
+			result.actions.push({ checkbox: recon.checkbox, outcome: "unmatched", reason: "No matching checkbox found in STATUS.md" });
+			continue;
+		}
+
+		consumed.add(matchedIdx);
+		const cbMatch = lines[matchedIdx].match(checkboxRegex)!;
+		const currentlyChecked = cbMatch[2].toLowerCase() === "x";
+		const currentText = cbMatch[4];
+
+		// Determine desired state
+		const shouldBeChecked = recon.actualState === "done";
+		// partial → uncheck (conservative: don't claim done)
+
+		if (shouldBeChecked && currentlyChecked) {
+			// Already correct
+			result.alreadyCorrect++;
+			result.actions.push({ checkbox: recon.checkbox, outcome: "no_change", reason: "Already checked (done)" });
+		} else if (!shouldBeChecked && !currentlyChecked) {
+			// Already correct (unchecked for not_done or partial)
+			// But if partial, might need annotation
+			if (recon.actualState === "partial" && !currentText.includes("(partial)")) {
+				// Add partial annotation
+				lines[matchedIdx] = `${cbMatch[1]} ${cbMatch[3]}${currentText} (partial)`;
+				result.changed++;
+				result.actions.push({ checkbox: recon.checkbox, outcome: "unchecked", reason: "Added (partial) annotation" });
+			} else {
+				result.alreadyCorrect++;
+				result.actions.push({ checkbox: recon.checkbox, outcome: "no_change", reason: `Already unchecked (${recon.actualState})` });
+			}
+		} else if (shouldBeChecked && !currentlyChecked) {
+			// Need to check
+			lines[matchedIdx] = `${cbMatch[1]}x${cbMatch[3]}${currentText}`;
+			result.changed++;
+			result.actions.push({ checkbox: recon.checkbox, outcome: "checked", reason: "Work done but box was unchecked" });
+		} else {
+			// currentlyChecked but should not be (not_done or partial)
+			const annotation = recon.actualState === "partial" ? " (partial)" : "";
+			const cleanText = currentText.replace(/\s*\(partial\)\s*$/, "");
+			lines[matchedIdx] = `${cbMatch[1]} ${cbMatch[3]}${cleanText}${annotation}`;
+			result.changed++;
+			const outcomeReason = recon.actualState === "partial"
+				? "Unchecked — work partially done"
+				: "Unchecked — work not done";
+			result.actions.push({ checkbox: recon.checkbox, outcome: "unchecked", reason: outcomeReason });
+		}
+	}
+
+	// Only rewrite if there were actual changes
+	if (result.changed > 0) {
+		try {
+			writeFileSync(statusPath, lines.join("\n"), "utf-8");
+		} catch {
+			// Write failed — downgrade changes to unmatched for accuracy
+			// (the in-memory result says "changed" but file wasn't updated)
+			for (const action of result.actions) {
+				if (action.outcome === "checked" || action.outcome === "unchecked") {
+					action.outcome = "unmatched";
+					action.reason += " (write failed)";
+					result.changed--;
+					result.unmatched++;
+				}
+			}
+		}
+	}
+
+	return result;
+}
+
+// ── Remediation: Feedback & Fix Agent Prompt ─────────────────────────
+
+/** Path for the review feedback file written for the fix agent. */
+export const FEEDBACK_FILENAME = "REVIEW_FEEDBACK.md";
+
+/**
+ * Generate a deterministic REVIEW_FEEDBACK.md from a NEEDS_FIXES verdict.
+ *
+ * Includes blocking findings based on the configured pass threshold:
+ * - `no_critical` / `no_important`: critical + important findings only
+ * - `all_clear`: critical + important + suggestion findings (all are blocking)
+ *
+ * The template is stable across runs so fix-agent prompts are reproducible.
+ *
+ * This file is intentionally staged as a task artifact (aligns with
+ * roadmap 5e: REVIEW_FEEDBACK.md is part of the review audit trail).
+ *
+ * @param verdict - The NEEDS_FIXES review verdict
+ * @param cycleNum - Current remediation cycle number (1-based)
+ * @param maxCycles - Maximum review cycles configured
+ * @param passThreshold - Configured pass threshold (determines which severities are blocking)
+ * @returns Markdown content for REVIEW_FEEDBACK.md
+ */
+export function generateFeedbackMd(
+	verdict: ReviewVerdict,
+	cycleNum: number,
+	maxCycles: number,
+	passThreshold: PassThreshold = "no_critical",
+): string {
+	const criticals = verdict.findings.filter(f => f.severity === "critical");
+	const importants = verdict.findings.filter(f => f.severity === "important");
+	const suggestions = verdict.findings.filter(f => f.severity === "suggestion");
+	const mismatches = verdict.statusReconciliation.filter(r => r.actualState !== "done");
+
+	// Under all_clear, suggestions are also blocking
+	const includeSuggestions = passThreshold === "all_clear";
+
+	const blockingLabel = includeSuggestions
+		? "critical, important, and suggestion"
+		: "critical and important";
+
+	const lines: string[] = [
+		`# Review Feedback — Cycle ${cycleNum}/${maxCycles}`,
+		``,
+		`**Verdict:** NEEDS_FIXES`,
+		`**Confidence:** ${verdict.confidence}`,
+		`**Summary:** ${verdict.summary}`,
+		`**Pass Threshold:** \`${passThreshold}\``,
+		``,
+		`> This file was generated by the quality gate. Address all ${blockingLabel}`,
+		`> findings below, then the review will re-run automatically.`,
+		``,
+	];
+
+	if (criticals.length > 0) {
+		lines.push(`## Critical Findings (${criticals.length})`);
+		lines.push(``);
+		for (let i = 0; i < criticals.length; i++) {
+			const f = criticals[i];
+			lines.push(`### C${i + 1}: ${f.description}`);
+			lines.push(``);
+			lines.push(`- **Category:** ${f.category}`);
+			if (f.file) lines.push(`- **File:** \`${f.file}\``);
+			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
+			lines.push(``);
+		}
+	}
+
+	if (importants.length > 0) {
+		lines.push(`## Important Findings (${importants.length})`);
+		lines.push(``);
+		for (let i = 0; i < importants.length; i++) {
+			const f = importants[i];
+			lines.push(`### I${i + 1}: ${f.description}`);
+			lines.push(``);
+			lines.push(`- **Category:** ${f.category}`);
+			if (f.file) lines.push(`- **File:** \`${f.file}\``);
+			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
+			lines.push(``);
+		}
+	}
+
+	if (includeSuggestions && suggestions.length > 0) {
+		lines.push(`## Suggestion Findings (${suggestions.length})`);
+		lines.push(``);
+		lines.push(`> Under \`all_clear\` threshold, suggestions are also blocking.`);
+		lines.push(``);
+		for (let i = 0; i < suggestions.length; i++) {
+			const f = suggestions[i];
+			lines.push(`### S${i + 1}: ${f.description}`);
+			lines.push(``);
+			lines.push(`- **Category:** ${f.category}`);
+			if (f.file) lines.push(`- **File:** \`${f.file}\``);
+			if (f.remediation) lines.push(`- **Remediation:** ${f.remediation}`);
+			lines.push(``);
+		}
+	}
+
+	if (mismatches.length > 0) {
+		lines.push(`## STATUS.md Reconciliation Issues (${mismatches.length})`);
+		lines.push(``);
+		for (const r of mismatches) {
+			lines.push(`- **Checkbox:** ${r.checkbox}`);
+			lines.push(`  - **Actual state:** ${r.actualState}`);
+			if (r.evidence) lines.push(`  - **Evidence:** ${r.evidence}`);
+		}
+		lines.push(``);
+	}
+
+	const totalBlocking = criticals.length + importants.length
+		+ (includeSuggestions ? suggestions.length : 0) + mismatches.length;
+
+	if (totalBlocking === 0) {
+		lines.push(`## No blocking findings`);
+		lines.push(``);
+		lines.push(`The review returned NEEDS_FIXES but no blocking findings were extracted for threshold \`${passThreshold}\`.`);
+		lines.push(`This may indicate a threshold or verdict-rule mismatch. Review the REVIEW_VERDICT.json for details.`);
+		lines.push(``);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Build the prompt for the fix agent that addresses quality gate findings.
+ *
+ * The fix agent is spawned in the same worktree as the task and receives
+ * the REVIEW_FEEDBACK.md content along with task context. It should make
+ * targeted code fixes and commit them.
+ *
+ * @param context - Quality gate context (task folder, IDs, etc.)
+ * @param feedbackContent - Content of REVIEW_FEEDBACK.md
+ * @param cycleNum - Current fix cycle number
+ * @returns Prompt string for the fix agent
+ */
+export function buildFixAgentPrompt(
+	context: QualityGateContext,
+	feedbackContent: string,
+	cycleNum: number,
+): string {
+	const statusPath = join(context.taskFolder, "STATUS.md");
+
+	let statusContent = "(STATUS.md not found)";
+	try {
+		if (existsSync(statusPath)) {
+			statusContent = readFileSync(statusPath, "utf-8");
+		}
+	} catch { /* proceed without */ }
+
+	let promptContent = "(PROMPT.md not found)";
+	try {
+		if (existsSync(context.promptPath)) {
+			promptContent = readFileSync(context.promptPath, "utf-8");
+		}
+	} catch { /* proceed without */ }
+
+	return [
+		`# Quality Gate Remediation — Fix Cycle ${cycleNum}`,
+		``,
+		`You are a fix agent addressing quality gate findings for task **${context.taskId}**.`,
+		``,
+		`The quality gate review found issues that must be fixed before the task can be marked complete.`,
+		`Your job is to make targeted, minimal fixes to address the critical and important findings below.`,
+		``,
+		`## Rules`,
+		``,
+		`1. **Read REVIEW_FEEDBACK.md** below — it lists the blocking findings with specific remediation instructions.`,
+		`2. **Fix each finding** — make the minimal code change needed. Do NOT refactor unrelated code.`,
+		`3. **Commit your fixes** with message: \`fix(${context.taskId}): address quality gate findings (cycle ${cycleNum})\``,
+		`4. **Update STATUS.md** if any checkbox states were flagged as incorrect in the reconciliation section.`,
+		`5. **Do NOT create .DONE** — the quality gate will re-run automatically after you exit.`,
+		``,
+		`## Task Context`,
+		``,
+		`- **Task folder:** ${context.taskFolder}/`,
+		`- **PROMPT:** ${context.promptPath}`,
+		`- **STATUS:** ${statusPath}`,
+		``,
+		`## Review Feedback`,
+		``,
+		`\`\`\`markdown`,
+		feedbackContent,
+		`\`\`\``,
+		``,
+		`## Original Task Requirements (PROMPT.md)`,
+		``,
+		`\`\`\`markdown`,
+		promptContent,
+		`\`\`\``,
+		``,
+		`## Current STATUS.md`,
+		``,
+		`\`\`\`markdown`,
+		statusContent,
+		`\`\`\``,
+		``,
+		`**IMPORTANT:** Focus only on fixing the blocking findings. Do not expand scope or create .DONE.`,
+		``,
+	].join("\n");
+}