@minionry/minion 0.7.36 → 0.7.39

package/dist/server/services/plan/quality-delta.js

@@ -1,6 +1,6 @@
 // Copyright (c) 2025-present Minionry, Inc.
 // SPDX-License-Identifier: LicenseRef-Minionry-Software
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, relative, resolve } from 'node:path';
 import { getPersistence } from '../websocket/quality-handlers.js';
 import { QualityPersistence } from '../websocket/quality-persistence.js';
@@ -8,6 +8,7 @@ import { indexDismissals, isActiveFinding, runQualityScan } from '../websocket/q
 import { attributeToTrackedDirectories, detectEcosystem } from '../websocket/quality-tools.js';
 import { SOURCE_EXTENSIONS } from '../websocket/quality-types.js';
 import { resolveIsCodeTask } from './issue-classification.js';
+import { allRecordFiles, writeStampedRecord } from './record-file.js';
 export const QUALITY_DELTA_DIRNAME = 'quality';
 export const QUALITY_DELTA_MAX_FINDINGS = 200;
 export const WORKTREE_NOT_CHECKED_REASON = 'worktree boards are not checked yet';
@@ -214,34 +215,15 @@ export function qualityDeltaDir(boardDir) {
 }
 export function persistQualityDelta(boardDir, record, epochMs = Date.now()) {
     const dir = qualityDeltaDir(boardDir);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    const path = join(dir, `${record.issueId}-${epochMs}.json`);
-    writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, 'utf-8');
-    return path;
+    return join(dir, writeStampedRecord(dir, record.issueId, `${JSON.stringify(record, null, 2)}\n`, epochMs));
 }
-const DELTA_FILE_RE = /^(.+)-(\d+)\.json$/;
 export function readLatestQualityDeltas(boardDir) {
     const dir = qualityDeltaDir(boardDir);
     const newest = new Map();
-    let names;
-    try {
-        names = readdirSync(dir);
-    }
-    catch {
-        return new Map();
-    }
-    for (const name of names) {
-        const match = name.match(DELTA_FILE_RE);
-        if (!match)
-            continue;
-        const epochMs = Number(match[2]);
-        const current = newest.get(match[1]);
-        if (!current || epochMs > current.epochMs)
-            newest.set(match[1], { epochMs, name });
-    }
+    for (const { id, fileName } of allRecordFiles(dir))
+        newest.set(id, fileName);
     const records = new Map();
-    for (const [issueId, { name }] of newest) {
+    for (const [issueId, name] of newest) {
         try {
             const record = JSON.parse(readFileSync(join(dir, name), 'utf-8'));
             if (record && typeof record === 'object' && record.issueId === issueId)

package/dist/server/services/plan/readiness-planner.js

@@ -1,19 +1,27 @@
 // Copyright (c) 2025-present Minionry, Inc.
 // SPDX-License-Identifier: LicenseRef-Minionry-Software
 const TERMINAL_STATUSES = new Set(['done', 'cancelled']);
+const WAITING_STATUSES = new Set(['awaiting_approval']);
 export function buildCompletionReason(issues, epicScope) {
     const nonEpic = issues.filter(i => i.type !== 'epic');
     const done = nonEpic.filter(i => TERMINAL_STATUSES.has(i.status)).length;
+    const awaitingApproval = nonEpic.filter(i => WAITING_STATUSES.has(i.status)).length;
     const blocked = nonEpic.filter(i => i.status === 'todo').length;
     if (done === nonEpic.length)
         return epicScope ? 'All epic issues are done' : 'All issues are done';
-    if (blocked > 0)
-        return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
+    if (awaitingApproval > 0 || blocked > 0) {
+        const parts = [`${done}/${nonEpic.length} issues done`];
+        if (awaitingApproval > 0)
+            parts.push(`${awaitingApproval} awaiting approval`);
+        if (blocked > 0)
+            parts.push(`${blocked} blocked by incomplete dependencies`);
+        return parts.join(', ');
+    }
     return epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
 }
 export function detectDeadState(issues) {
     const nonEpic = issues.filter(i => i.type !== 'epic');
-    const stuck = nonEpic.filter(i => !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+    const stuck = nonEpic.filter(i => !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo' && !WAITING_STATUSES.has(i.status));
     if (stuck.length === 0)
         return null;
     const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
@@ -30,5 +38,5 @@ export function detectDeadState(issues) {
     return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
 }
 export function hasBlockedIssues(issues) {
-    return issues.some(i => i.type !== 'epic' && !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+    return issues.some(i => i.type !== 'epic' && !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo' && !WAITING_STATUSES.has(i.status));
 }

package/dist/server/services/plan/record-file.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const RECORD_FILE_RE = /^(.+)-(\d+)\.json$/;
+export function matchRecordFile(fileName) {
+    const match = fileName.match(RECORD_FILE_RE);
+    return match ? { fileName, id: match[1], epochMs: Number(match[2]) } : null;
+}
+export function allRecordFiles(dir, keep) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const name of names) {
+        const match = matchRecordFile(name);
+        if (match && (!keep || keep(match)))
+            files.push(match);
+    }
+    return files.sort((a, b) => a.epochMs - b.epochMs);
+}
+export function recordFilesFor(dir, id) {
+    return allRecordFiles(dir, (file) => file.id === id);
+}
+export function newestRecordFile(dir, id) {
+    const files = recordFilesFor(dir, id);
+    return files[files.length - 1] ?? null;
+}
+const MAX_STAMP_ATTEMPTS = 1000;
+export function writeStampedRecord(dir, id, contents, preferredEpochMs) {
+    if (/[/\\\0]/.test(id))
+        throw new Error(`Unsafe issue id for a record file: ${id}`);
+    mkdirSync(dir, { recursive: true });
+    let epochMs = Math.max(preferredEpochMs ?? Date.now(), (newestRecordFile(dir, id)?.epochMs ?? 0) + 1);
+    for (let attempt = 0; attempt < MAX_STAMP_ATTEMPTS; attempt++) {
+        const fileName = `${id}-${epochMs}.json`;
+        try {
+            writeFileSync(join(dir, fileName), contents, { encoding: 'utf-8', flag: 'wx' });
+            return fileName;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            epochMs += 1;
+        }
+    }
+    throw new Error(`No free record name for ${id} in ${dir} after ${MAX_STAMP_ATTEMPTS} attempts`);
+}

package/dist/server/services/plan/review-approval.js

@@ -0,0 +1,64 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { newestRecordFile, recordFilesFor, writeStampedRecord } from './record-file.js';
+const SAFE_RECORD_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function approvalsDir(boardOrSandboxDir) {
+    return join(boardOrSandboxDir, 'approvals');
+}
+export function latestReviewVerdict(boardOrSandboxDir, issueId) {
+    return boardOrSandboxDir ? newestRecordFile(join(boardOrSandboxDir, 'reviews'), issueId) : null;
+}
+export function writeReviewApproval(boardOrSandboxDir, record, epochMs = Date.now()) {
+    if (!SAFE_RECORD_ID_RE.test(record.issueId)) {
+        throw new Error(`Unsafe issue id for a decision record: ${record.issueId}`);
+    }
+    return writeStampedRecord(approvalsDir(boardOrSandboxDir), record.issueId, JSON.stringify(record, null, 2), epochMs);
+}
+export function readReviewApprovals(boardOrSandboxDir, issueId) {
+    if (!boardOrSandboxDir)
+        return [];
+    const dir = approvalsDir(boardOrSandboxDir);
+    return recordFilesFor(dir, issueId)
+        .map((file) => readApprovalFile(dir, file.fileName, file.epochMs, issueId))
+        .filter((stored) => stored !== null);
+}
+export function readLatestReviewApproval(boardOrSandboxDir, issueId) {
+    if (!boardOrSandboxDir)
+        return null;
+    const dir = approvalsDir(boardOrSandboxDir);
+    const newest = newestRecordFile(dir, issueId);
+    return newest ? readApprovalFile(dir, newest.fileName, newest.epochMs, issueId) : null;
+}
+function readApprovalFile(dir, fileName, epochMs, issueId) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, fileName), 'utf-8'));
+        return isReviewApprovalRecord(parsed, issueId) ? { record: parsed, fileName, epochMs } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isReviewApprovalRecord(value, issueId) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return record.issueId === issueId && (record.decision === 'approve' || record.decision === 'reject');
+}
+export const REVIEW_REJECTION_CHECK = 'changes_requested';
+export function rejectionFeedbackFor(boardOrSandboxDir, issueId) {
+    const latest = readLatestReviewApproval(boardOrSandboxDir, issueId);
+    if (!latest || latest.record.decision !== 'reject')
+        return [];
+    const comment = latest.record.comment?.trim();
+    if (!comment)
+        return [];
+    const verdict = latestReviewVerdict(boardOrSandboxDir, issueId);
+    if (verdict && verdict.epochMs > latest.epochMs)
+        return [];
+    return [{
+            name: REVIEW_REJECTION_CHECK,
+            details: `A person reviewed this issue on ${latest.record.decidedAt.slice(0, 10)} and requested changes: ${comment}`,
+        }];
+}

package/dist/server/services/plan/review-gate.js

@@ -1,6 +1,6 @@
 // Copyright (c) 2025-present Minionry, Inc.
 // SPDX-License-Identifier: LicenseRef-Minionry-Software
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { persistTranscriptSession } from '../websocket/session-history.js';
 import { loadAgentPrompt } from './agent-loader.js';
@@ -9,45 +9,29 @@ import { appendCancellationNote, appendOutputHistoryEntry } from './issue-writer
 import { resolveOutputPath } from './output-manager.js';
 import { createPlanRunner } from './plan-runner-factory.js';
 import { QUALITY_DELTA_MAX_FINDINGS, qualityDeltaDir } from './quality-delta.js';
+import { newestRecordFile, recordFilesFor, writeStampedRecord } from './record-file.js';
+import { decideReviewRecovery, parseReviewBlocker, parseReviewConfidence, reviewConfidence, reviewDisposition, shouldEscalate, } from './review-outcome.js';
 import { REVIEW_INCOMPLETE_CHECK } from './review-report.js';
+import { describeReviewTarget, escalatedReviewTarget, REVIEW_ESCALATION_EFFORT_LEVEL, REVIEW_GATE_EFFORT_LEVEL, REVIEW_GATE_ENGINE, REVIEW_GATE_MODEL, resolveReviewTarget, toReviewRunner, } from './review-target.js';
 import { balancedObjectEnd, createVerdictStream, parseVerdictObject } from './review-verdict-stream.js';
 import { MAX_REVIEW_ATTEMPTS } from './types.js';
-export { MAX_REVIEW_ATTEMPTS };
-export const REVIEW_GATE_ENGINE = 'claude-code';
-export const REVIEW_GATE_MODEL = 'fable';
-export const REVIEW_GATE_EFFORT_LEVEL = 'max';
+export { MAX_REVIEW_ATTEMPTS, REVIEW_ESCALATION_EFFORT_LEVEL, REVIEW_GATE_EFFORT_LEVEL, REVIEW_GATE_ENGINE, REVIEW_GATE_MODEL };
 export async function reviewIssue(options) {
-    const { workingDir, issue, pmDir, outputPath, onOutput, onPrompt, onComplete, logDir, boardDir, qualityDelta } = options;
+    const { workingDir, issue, pmDir, outputPath, onOutput, onPrompt, onComplete, boardDir, qualityDelta } = options;
     const isCodeTask = resolveIsCodeTask(issue);
     const issueType = isCodeTask ? 'code' : 'non-code';
     try {
         const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask, boardDir, workingDir, qualityDelta);
         onPrompt?.(prompt);
-        if (issue.reviewModel && issue.reviewModel !== REVIEW_GATE_MODEL) {
-            onOutput?.(`Review model '${issue.reviewModel}' overridden — the review gate is pinned to ${REVIEW_GATE_MODEL} at ${REVIEW_GATE_EFFORT_LEVEL} effort.\n`);
-        }
-        const stream = createVerdictStream(onOutput);
-        const runner = createPlanRunner('review', {
-            workingDir,
-            prompt,
-            engineId: REVIEW_GATE_ENGINE,
-            model: REVIEW_GATE_MODEL,
-            effortLevel: REVIEW_GATE_EFFORT_LEVEL,
-            verbose: true,
-            outputCallback: (text) => stream.write(text),
-            extraEnv: options.extraEnv,
-            abortSignal: options.abortSignal,
-            logLabel: 'pm-review',
-            logDir,
-        });
-        const result = await runner.run().finally(() => stream.flush());
-        await onComplete?.(result, prompt);
+        const target = options.reviewTarget ?? resolveReviewTarget(issue);
+        onOutput?.(`Reviewing on ${describeReviewTarget(target)}${target.source === 'issue' ? " (the issue's `review_model`)" : ''}.\n`);
+        const result = await runReviewer(options, target, prompt, 'pm-review', onComplete);
         if (result.completed && result.assistantResponse) {
-            const verdict = applyQualityGate(await resolveVerdict(options, issueType, result.assistantResponse), qualityDelta);
-            const blocked = verdict.checks.find((c) => c.name === QUALITY_DELTA_CHECK && !c.passed);
+            const primary = stampRunner(applyQualityGate(await resolveVerdict(options, issueType, result.assistantResponse, target), qualityDelta), target);
+            const blocked = primary.checks.find((c) => c.name === QUALITY_DELTA_CHECK && !c.passed);
             if (blocked)
                 onOutput?.(`\nQuality gate (block): ${blocked.details}\n`);
-            return verdict;
+            return await maybeEscalate(options, issueType, primary, target, qualityDelta);
         }
         return incompleteReviewResult(issue.id, issueType, options.abortSignal?.aborted ? 'Review aborted by user stop' : 'Review runner did not complete');
     }
@@ -57,37 +41,109 @@ export async function reviewIssue(options) {
             : `Review threw an error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-async function resolveVerdict(options, issueType, reviewerOutput) {
+async function runReviewer(options, target, prompt, logLabel, onComplete) {
+    const stream = createVerdictStream(options.onOutput);
+    const runner = createPlanRunner('review', {
+        workingDir: options.workingDir,
+        prompt,
+        engineId: target.engine,
+        model: target.model,
+        effortLevel: target.effortLevel,
+        verbose: true,
+        outputCallback: (text) => stream.write(text),
+        extraEnv: options.extraEnv,
+        abortSignal: options.abortSignal,
+        logLabel,
+        logDir: options.logDir,
+    });
+    const result = await runner.run().finally(() => stream.flush());
+    await onComplete?.(result, prompt);
+    return result;
+}
+async function maybeEscalate(options, issueType, primary, primaryTarget, qualityDelta) {
+    if (!shouldEscalate(primary, isIncompleteReview(primary)))
+        return primary;
+    const next = escalatedReviewTarget(primaryTarget);
+    const why = reviewDisposition(primary) === 'blocked'
+        ? `claims the issue cannot pass review (${primary.blocker?.kind})`
+        : `is ${reviewConfidence(primary)}-confidence`;
+    if (!next) {
+        options.onOutput?.(`\nVerdict ${why}, but ${primaryTarget.model} is already the top review tier — the verdict stands.\n`);
+        return primary;
+    }
+    options.onOutput?.(`\nVerdict ${why} — escalating to ${describeReviewTarget(next)} for a second opinion.\n`);
+    const prompt = buildReviewPrompt(options.issue, options.pmDir, options.outputPath, issueType === 'code', options.boardDir, options.workingDir, qualityDelta);
+    const run = await runReviewer(options, next, prompt, 'pm-review-escalation');
+    if (!run.completed || !run.assistantResponse) {
+        options.onOutput?.('\nEscalated review did not complete — keeping the first verdict.\n');
+        return demoteUnconfirmedBlocker(primary);
+    }
+    const escalated = stampRunner(applyQualityGate(await resolveVerdict(options, issueType, run.assistantResponse, next), qualityDelta), next);
+    if (isIncompleteReview(escalated)) {
+        options.onOutput?.('\nEscalated review reached no verdict — keeping the first verdict.\n');
+        return demoteUnconfirmedBlocker(primary);
+    }
+    return { ...escalated, escalatedFrom: toReviewRunner(primaryTarget) };
+}
+function demoteUnconfirmedBlocker(result) {
+    if (reviewDisposition(result) !== 'blocked')
+        return result;
+    const { blocker, ...rest } = result;
+    return {
+        ...rest,
+        disposition: 'revise',
+        checks: [
+            ...result.checks,
+            {
+                name: 'blocked_claim_unverified',
+                passed: false,
+                details: `The reviewer reported this issue as blocked (${blocker?.kind}: ${blocker?.detail}) but the escalated second opinion could not confirm it, so the issue is being retried rather than cancelled.`,
+                remediation: blocker?.humanAction ?? 'Attempt the work; if it is genuinely impossible here, say so explicitly in the output file.',
+            },
+        ],
+    };
+}
+function stampRunner(result, target) {
+    return { ...result, reviewedBy: toReviewRunner(target) };
+}
+async function resolveVerdict(options, issueType, reviewerOutput, target) {
     const parsed = parseReviewOutput(options.issue.id, issueType, reviewerOutput);
     if (!hasFailedChecksWithoutDetails(parsed))
         return parsed;
     options.onOutput?.('\nReview verdict listed failed checks without details — asking the reviewer for reasons.\n');
-    const followUp = await runDetailsFollowUp(options, issueType, parsed, reviewerOutput);
+    const followUp = await runDetailsFollowUp(options, issueType, parsed, reviewerOutput, target);
     if (followUp && !hasFailedChecksWithoutDetails(followUp))
         return followUp;
     return incompleteReviewResult(options.issue.id, issueType, 'Reviewer reported failed checks without details');
 }
+function reviewsDirOf(boardOrSandboxDir) {
+    return join(boardOrSandboxDir, 'reviews');
+}
 export function getReviewAttemptCount(boardOrSandboxDir, issue) {
+    return boardOrSandboxDir ? recordFilesFor(reviewsDirOf(boardOrSandboxDir), issue.id).length : 0;
+}
+export function readLatestReviewResult(boardOrSandboxDir, issue) {
     if (!boardOrSandboxDir)
-        return 0;
-    const reviewsDir = join(boardOrSandboxDir, 'reviews');
-    if (!existsSync(reviewsDir))
-        return 0;
+        return null;
+    const dir = reviewsDirOf(boardOrSandboxDir);
+    const newest = newestRecordFile(dir, issue.id);
+    if (!newest)
+        return null;
     try {
-        return readdirSync(reviewsDir).filter(f => f.startsWith(issue.id) && f.endsWith('.json')).length;
+        const record = JSON.parse(readFileSync(join(dir, newest.fileName), 'utf-8'));
+        return record && typeof record === 'object' && record.issueId === issue.id ? record : null;
     }
     catch {
-        return 0;
+        return null;
     }
 }
 export function persistReviewResult(boardOrSandboxDir, issue, result) {
     if (!boardOrSandboxDir)
         return;
-    const reviewsDir = join(boardOrSandboxDir, 'reviews');
-    if (!existsSync(reviewsDir))
-        mkdirSync(reviewsDir, { recursive: true });
+    const dir = reviewsDirOf(boardOrSandboxDir);
+    mkdirSync(dir, { recursive: true });
     try {
-        writeFileSync(join(reviewsDir, `${issue.id}-${Date.now()}.json`), JSON.stringify(result, null, 2), 'utf-8');
+        writeStampedRecord(dir, issue.id, JSON.stringify(result, null, 2));
     }
     catch {   }
 }
@@ -96,8 +152,10 @@ export function appendReviewFeedback(pmDir, issue, result) {
     try {
         let content = readFileSync(fullPath, 'utf-8');
         const failedChecks = result.checks.filter(c => !c.passed);
-        const feedback = failedChecks.map(c => `  - ${c.name}: ${c.details}`).join('\n');
-        const entry = `- Review failed (${new Date().toISOString().split('T')[0]}): ${failedChecks.length} check(s) failed\n${feedback}`;
+        const entry = [
+            `- Review failed (${new Date().toISOString().split('T')[0]}): ${failedChecks.length} check(s) failed`,
+            ...failedChecks.flatMap(renderFeedbackCheck),
+        ].join('\n');
         if (content.includes('## Activity')) {
             content = content.replace(/## Activity/, `## Activity\n${entry}`);
         }
@@ -108,6 +166,14 @@ export function appendReviewFeedback(pmDir, issue, result) {
     }
     catch {   }
 }
+function renderFeedbackCheck(check) {
+    const lines = [`  - ${check.name}: ${check.details}`];
+    if (check.evidence?.trim())
+        lines.push(`    - evidence: ${check.evidence.trim()}`);
+    if (check.remediation?.trim())
+        lines.push(`    - fix: ${check.remediation.trim()}`);
+    return lines;
+}
 function balancedObjectAt(text, start) {
     const end = balancedObjectEnd(text, start);
     return end === -1 ? null : text.slice(start, end);
@@ -148,27 +214,38 @@ function lastTopLevelVerdict(output) {
 }
 export function parseReviewOutput(issueId, issueType, output) {
     const parsed = extractReviewVerdict(output);
-    if (parsed) {
-        return {
-            issueId,
-            issueType,
-            passed: !!parsed.passed,
-            checks: Array.isArray(parsed.checks) ? parsed.checks.map((c) => ({
-                name: String(c.name ?? 'unknown'),
-                passed: !!c.passed,
-                details: String(c.details ?? ''),
-            })) : [],
-            reviewedAt: new Date().toISOString(),
-        };
-    }
-    return incompleteReviewResult(issueId, issueType, 'Could not parse review output');
+    if (!parsed)
+        return incompleteReviewResult(issueId, issueType, 'Could not parse review output');
+    const passed = !!parsed.passed;
+    const blocker = passed ? null : parseReviewBlocker(parsed.blocker);
+    return {
+        issueId,
+        issueType,
+        passed,
+        checks: Array.isArray(parsed.checks) ? parsed.checks.map(parseReviewCheck) : [],
+        reviewedAt: new Date().toISOString(),
+        confidence: parseReviewConfidence(parsed.confidence),
+        disposition: passed ? 'pass' : blocker ? 'blocked' : 'revise',
+        ...(blocker ? { blocker } : {}),
+    };
+}
+function parseReviewCheck(raw) {
+    const evidence = String(raw.evidence ?? '').trim();
+    const remediation = String(raw.remediation ?? '').trim();
+    return {
+        name: String(raw.name ?? 'unknown'),
+        passed: !!raw.passed,
+        details: String(raw.details ?? ''),
+        ...(evidence ? { evidence } : {}),
+        ...(remediation ? { remediation } : {}),
+    };
 }
 export function hasFailedChecksWithoutDetails(result) {
     if (result.passed || isIncompleteReview(result))
         return false;
     return result.checks.some((c) => !c.passed && c.details.trim().length === 0);
 }
-async function runDetailsFollowUp(options, issueType, verdict, previousOutput) {
+async function runDetailsFollowUp(options, issueType, verdict, previousOutput, target) {
     const failedNames = verdict.checks.filter((c) => !c.passed).map((c) => c.name);
     const prompt = [
         `You reviewed issue ${options.issue.id} (${options.issue.title}) and returned this verdict:`,
@@ -177,18 +254,18 @@ async function runDetailsFollowUp(options, issueType, verdict, previousOutput) {
         '```',
         '',
         `The failed checks ${failedNames.join(', ')} carry no details. The implementing agent cannot act on a bare label.`,
-        'Restate the SAME verdict as one JSON object with, for every failed check, a specific `details` string naming what is wrong and what would satisfy the check (file, criterion, behaviour). Do not change which checks passed or failed.',
+        'Restate the SAME verdict as one JSON object with, for every failed check, a specific `details` string naming what is wrong, an `evidence` string citing what you read that shows it (file:line, a quoted criterion, a command and its output), and a `remediation` string naming the concrete change that would satisfy the check. Do not change which checks passed or failed.',
         'Output EXACTLY one JSON object on its own line (no markdown fencing):',
-        '{"passed": false, "checks": [{"name": "criteria_met", "passed": false, "details": "..."}]}',
+        '{"passed": false, "confidence": "high", "checks": [{"name": "criteria_met", "passed": false, "details": "...", "evidence": "...", "remediation": "..."}]}',
     ].join('\n');
     try {
         const stream = createVerdictStream(options.onOutput);
         const runner = createPlanRunner('review', {
             workingDir: options.workingDir,
             prompt,
-            engineId: REVIEW_GATE_ENGINE,
-            model: REVIEW_GATE_MODEL,
-            effortLevel: REVIEW_GATE_EFFORT_LEVEL,
+            engineId: target.engine,
+            model: target.model,
+            effortLevel: target.effortLevel,
             verbose: true,
             inferenceOnly: true,
             policy: 'NONE',
@@ -342,17 +419,19 @@ export async function runReviewPipeline(options, callbacks) {
     const { issue, pmDir, workingDir, executionDir, boardDir, extraEnv, abortSignal, qualityDelta } = options;
     const reviewDir = boardDir ?? pmDir;
     const attempts = getReviewAttemptCount(reviewDir, issue);
+    const previous = readLatestReviewResult(reviewDir, issue);
     if (attempts >= MAX_REVIEW_ATTEMPTS) {
-        await callbacks.setStatus(issue.path, 'cancelled');
-        await appendCancellationNote(pmDir, issue, `Cancelled after ${MAX_REVIEW_ATTEMPTS} failed reviews — issue may need restructuring`, callbacks.warn);
-        callbacks.onReviewProgress(issue.id, 'max_attempts');
-        callbacks.onIssueAbandoned(issue.id, `Review failed ${MAX_REVIEW_ATTEMPTS} times — cancelled to unblock dependents`, attempts);
-        callbacks.onOutput(issue.id, 'Review: max attempts reached, cancelling issue to unblock dependents');
+        await abandonIssue(options, callbacks, {
+            action: 'abandon',
+            reason: `Review failed ${attempts} times — cancelled to unblock dependents; the issue likely needs restructuring`,
+            attempts,
+        });
         return false;
     }
     await callbacks.setStatus(issue.path, 'in_review');
     callbacks.onReviewProgress(issue.id, 'reviewing');
     const outputPath = resolveOutputPath(issue, workingDir, boardDir);
+    const reviewTarget = resolveReviewTarget(issue);
     const reviewStart = Date.now();
     const reviewSessionId = `improv-${reviewStart}-pm-${issue.id}-review`;
     const result = await reviewIssue({
@@ -361,15 +440,16 @@ export async function runReviewPipeline(options, callbacks) {
         pmDir,
         outputPath,
         onOutput: (text) => callbacks.onOutput(issue.id, text),
-        onPrompt: (prompt) => callbacks.onReviewPrompt(issue.id, prompt),
+        onPrompt: (prompt) => callbacks.onReviewPrompt(issue.id, prompt, reviewTarget),
+        reviewTarget,
         onComplete: async (sessionResult, prompt) => {
             persistTranscriptSession(workingDir, {
                 sessionId: reviewSessionId,
                 userPrompt: prompt,
                 result: sessionResult,
                 execStart: reviewStart,
-                engine: REVIEW_GATE_ENGINE,
-                model: REVIEW_GATE_MODEL,
+                engine: reviewTarget.engine,
+                model: reviewTarget.model,
             });
             await appendOutputHistoryEntry(pmDir, issue.path, {
                 sessionId: reviewSessionId,
@@ -390,20 +470,49 @@ export async function runReviewPipeline(options, callbacks) {
         persistReviewResult(reviewDir, issue, stamped);
         callbacks.onReviewResult?.(issue.id, stamped);
     }
-    if (result.passed) {
-        await callbacks.setStatus(issue.path, 'done');
-        callbacks.onReviewProgress(issue.id, 'passed');
-        callbacks.onIssueCompleted(issue);
-        return true;
-    }
     if (isIncompleteReview(result)) {
         callbacks.onOutput(issue.id, `Review: ${result.checks[0]?.details ?? 'incomplete'} — leaving for retry.`);
         callbacks.onIssueError(issue.id, `Review incomplete: ${result.checks[0]?.details ?? 'no verdict'}`);
         return false;
     }
+    const recovery = decideReviewRecovery(result, previous, attempts);
+    if (recovery.action === 'complete') {
+        switch (issue.reviewGate) {
+            case 'none':
+            case 'auto':
+                await callbacks.setStatus(issue.path, 'done');
+                callbacks.onReviewProgress(issue.id, 'passed');
+                callbacks.onIssueCompleted(issue);
+                return true;
+            case 'required':
+                await callbacks.setStatus(issue.path, 'awaiting_approval');
+                callbacks.onReviewProgress(issue.id, 'awaiting_approval');
+                return false;
+            default: {
+                const exhaustive = issue.reviewGate;
+                throw new Error(`Unknown review gate: ${exhaustive}`);
+            }
+        }
+    }
+    if (recovery.action === 'abandon') {
+        appendReviewFeedback(pmDir, issue, result);
+        await abandonIssue(options, callbacks, recovery);
+        return false;
+    }
     await callbacks.setStatus(issue.path, 'todo');
     appendReviewFeedback(pmDir, issue, result);
     callbacks.onReviewProgress(issue.id, 'failed');
-    callbacks.onIssueError(issue.id, `Review failed: ${result.checks.filter(c => !c.passed).map(c => c.name).join(', ')}`);
+    callbacks.onIssueError(issue.id, recovery.reason);
     return false;
 }
+async function abandonIssue(options, callbacks, recovery) {
+    const { issue, pmDir } = options;
+    const note = recovery.blocker?.humanAction
+        ? `${recovery.reason} To unblock: ${recovery.blocker.humanAction}`
+        : recovery.reason;
+    await callbacks.setStatus(issue.path, 'cancelled');
+    await appendCancellationNote(pmDir, issue, note, callbacks.warn);
+    callbacks.onReviewProgress(issue.id, 'max_attempts');
+    callbacks.onIssueAbandoned(issue.id, note, recovery.attempts);
+    callbacks.onOutput(issue.id, `Review: ${note}\n`);
+}