pi-plans 0.7.0 → 0.8.0

package/src/auditor.ts

@@ -1,32 +1,58 @@
 /**
- * Completion auditor (v0.6.1): when every task reaches a terminal state, an
- * independent read-only subagent verifies the plan's verification checks
- * against the worktree. Failed checks roll their covered tasks back to
- * pending (exclusively inside the audit flow); three failed rounds pause the
- * run for the user — or terminate it as stopped under auto-approve/headless
- * so pipelines never hang.
+ * Execution reviewer (v0.8): when every task
+ * reaches a terminal state, an independent read-only subagent verifies the
+ * plan's verification checks against the worktree. Failed checks roll their
+ * covered tasks back to pending (exclusively inside the review flow). The
+ * loop is bounded at REVIEW_MAX_ROUNDS committed rounds; exhaustion pauses
+ * the run for the user in every mode (fail-closed, never a hang and never a
+ * silent stop) — only an explicit /plans-execute confirmation grants a fresh
+ * budget.
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
-import { auditRollbackSet, auditableChecks, skippedPassCheckIds, type TaskView } from "./tasks.ts";
+import * as path from "node:path";
+import { auditableChecks, skippedPassCheckIds, type TaskView } from "./tasks.ts";
 import type { CheckItem } from "./plan.ts";
 import { messaging } from "./messaging.ts";
 
-export const AUDIT_MAX_ROUNDS = 3;
+/** Budget cap: committed rounds per user-granted budget. Discarded (fingerprint-changed) attempts do not count. */
+export const REVIEW_MAX_ROUNDS = 5;
+
+/** Legacy alias for one release: checkpoints and old builds still know this name. */
+export const AUDIT_MAX_ROUNDS = REVIEW_MAX_ROUNDS;
 
 export interface AuditOutcome {
 	round: number;
 	passed: string[];
 	failed: string[];
-	/** Rolled-back task ids (empty when the audit passed). */
-	rolledBack: string[];
+	/** Checks whose report carried no readable verdict, or whose evidence was
+	 * inconclusive. Never treated as `failed`: see src/exec.ts. */
+	undeterminable: string[];
 	report: string;
 }
 
+/** Parse the verdict lines of an audit report against the checks that are
+ * still pending. A pending check with no readable verdict is
+ * `undeterminable`, never `failed` — the caller must be able to tell "the
+ * work is wrong" apart from "I could not read the answer". */
+export interface ParsedAudit {
+	passed: string[];
+	failed: string[];
+	undeterminable: string[];
+}
+
+/** Checks this round must judge: auditable (covering at least one task) and
+ * not already done. The brief and the coverage self-check both use this, so a
+ * well-formed round-2 report that omits an already-done check is not mistaken
+ * for a contract violation. */
+export function auditablePendingChecks(checklist: CheckItem[], tasks: TaskView[]): CheckItem[] {
+	return auditableChecks(checklist, tasks).filter((item) => !item.done);
+}
+
 /** Build the audit brief for the read-only subagent. Exported for tests. */
 export function buildAuditTask(planPath: string, checklist: CheckItem[], tasks: TaskView[], round: number): string {
-	const checks = auditableChecks(checklist, tasks)
+	const checks = auditablePendingChecks(checklist, tasks)
 		.map((check) => `- \`${check.id}\`: ${check.text}`)
 		.join("\n");
 	return `Goal: verify that the implemented worktree satisfies the accepted plan's verification checks.
@@ -37,51 +63,54 @@ Authority boundary: read-only analysis only. Do not edit, write, delete, commit,
 
 Evidence: inspect the repository with read, grep, find, ls, and targeted commands (bash is not granted — rely on the read tools) before judging each check. Tests may be referenced from their recorded evidence; do not re-run them.
 
-Checks to verify (only these; checks covering no task are excluded):
+Checks to verify (only these; checks covering no task and checks already satisfied in an earlier round are excluded):
 
 ${checks}
 
-Output: Markdown with exactly one section per check, in checklist order:
+Output: Markdown with exactly one section per check, in the order above:
 
-- \`VC-###\` — verdict: pass | fail; evidence: <repo path/command proving it>; note: <one line>.
+- \`VC-###\` — verdict: pass | fail | undeterminable; evidence: <repo path/command proving it>; note: <one line>.
 
-Every check needs a verdict backed by evidence you actually inspected. If the evidence is inconclusive, verdict is fail with what is missing.`;
+Emit every listed check exactly once. \`undeterminable\` is a legitimate answer: use it whenever the evidence is missing, unreadable, ambiguous, or beyond your read-only reach. Report \`fail\` only when you can point at the specific thing that breaks the condition — never report \`fail\` for want of evidence.`;
 }
 
 /** Parse the audit subagent's verdict lines. Exported for tests. */
-export function parseAuditReport(report: string, checklist: CheckItem[]): { passed: string[]; failed: string[] } {
+export function parseAuditReport(report: string, pendingVcIds: string[]): ParsedAudit {
 	const passed: string[] = [];
 	const failed: string[] = [];
-	const known = new Set(checklist.map((item) => item.id));
-	for (const match of report.matchAll(/`?(VC-\d+)`?[^\n]*?verdict:\s*(pass|fail)/gi)) {
+	const known = new Set(pendingVcIds.map((id) => id.toUpperCase()));
+	// The auditor writes Markdown, so a verdict may carry emphasis
+	// (`**pass**`, `*pass*`, `_pass_`, `` `pass` ``). Requiring a bare token
+	// silently discarded such verdicts, and the caller's fail-closed rule then
+	// marked every check failed and rolled the whole run back -- reporting
+	// correct work as failure. Tolerate the markers; \b keeps `passed` and
+	// `passing` from matching.
+	for (const match of report.matchAll(/`?(VC-\d+)`?[^\n]*?verdict:\s*[*_`~]*\s*(pass|fail|undeterminable)\b/gi)) {
 		const id = match[1].toUpperCase();
 		if (!known.has(id)) continue;
-		(match[2].toLowerCase() === "pass" ? passed : failed).push(id);
+		const verdict = match[2].toLowerCase();
+		if (verdict === "pass") passed.push(id);
+		else if (verdict === "fail") failed.push(id);
 	}
-	// Dedupe, keep first occurrence order; a check with conflicting verdicts fails.
-	for (const id of [...passed]) if (failed.includes(id)) passed.splice(passed.indexOf(id), 1);
-	return { passed: [...new Set(passed)], failed: [...new Set(failed)] };
+	// A check with conflicting verdicts resolves to fail: the reader saw both.
+	for (const id of [...new Set(passed)]) if (failed.includes(id)) passed.splice(passed.indexOf(id), 1);
+	const undecided = new Set(known);
+	for (const id of [...passed, ...failed]) undecided.delete(id);
+	return { passed: [...new Set(passed)], failed: [...new Set(failed)], undeterminable: [...undecided] };
 }
 
-/** Pure decision core: given a parsed report, mutate the task tree with the
- * rollback set. Returns the outcome (rolled-back ids). Exported for tests. */
-export function applyAuditOutcome(
-	checklist: CheckItem[],
-	tasks: TaskView[],
-	round: number,
-	passed: string[],
-	failed: string[],
-	report: string,
-): AuditOutcome {
-	for (const id of passed) {
-		const item = checklist.find((candidate) => candidate.id === id);
-		if (item) item.done = true;
-	}
-	const rolledBack: string[] = [];
-	for (const id of failed) {
-		rolledBack.push(...auditRollbackSet(tasks, checklist, id));
-	}
-	return { round, passed, failed, rolledBack, report };
+/** Pure decision core: classify a parsed report into the audit outcome. It
+ * touches neither the checklist nor the task tree — the caller owns writing
+ * `done` and computing the rollback set, so there is exactly one authority for
+ * both. Exported for tests. */
+export function applyAuditOutcome(round: number, parsed: ParsedAudit, report: string): AuditOutcome {
+	return {
+		round,
+		passed: parsed.passed,
+		failed: parsed.failed,
+		undeterminable: parsed.undeterminable,
+		report,
+	};
 }
 
 /** Skipped-pass checks (all covered tasks skipped) pass without audit. */
@@ -89,9 +118,13 @@ export function presolvedCheckIds(checklist: CheckItem[], tasks: TaskView[]): st
 	return skippedPassCheckIds(checklist, tasks);
 }
 
-/** Spawn the audit subagent and apply its outcome. Returns null when the
- * audit subagent itself failed to run (treated as a failed round with an
- * empty rollback; the caller counts it against the round cap). */
+/** Spawn the audit subagent and classify its report. Returns `{ cancelled: true }`
+ * when the child was aborted (session shutdown, stop, restore, tree switch) —
+ * such a round burns no budget and sends no wake; `null` when the subagent
+ * itself failed to run (treated as an all-undeterminable committed round; the
+ * caller counts it against the round cap). */
+export type AuditRoundResult = AuditOutcome | { cancelled: true } | null;
+
 export async function runCompletionAudit(
 	ctx: ExtensionContext,
 	opts: {
@@ -100,27 +133,95 @@ export async function runCompletionAudit(
 		tasks: TaskView[];
 		round: number;
 		model?: string;
+		thinkingLevel?: string;
+		timeoutMs?: number;
 		signal?: AbortSignal;
+		onProgress?: (event: import("./subagent.ts").SubagentProgressEvent) => void;
 	},
-): Promise<AuditOutcome | null> {
+): Promise<AuditRoundResult> {
 	const { runPiSubagent } = await import("./subagent.ts");
+	const pending = auditablePendingChecks(opts.checklist, opts.tasks);
 	const task = buildAuditTask(opts.planPath, opts.checklist, opts.tasks, opts.round);
-	let agentPrompt = "You are a read-only completion auditor for pi-plans.";
-	try {
-		agentPrompt = fs.readFileSync(new URL("../agents/reviewer.md", import.meta.url), "utf8");
-	} catch {
-		/* fall back to the inline prompt */
-	}
+	// agents/auditor.md, not agents/reviewer.md: the reviewer prompt mandates a
+	// plan-review shape (`## Findings` / `## Questions`, F-###) and never says
+	// "verdict", so auditing under it produced reports this parser could not
+	// read at all -- every check then fell through to fail-closed.
+	// v0.8: a missing agent definition is a hard error — the silent inline
+	// fallback once swapped in a minimal prompt that produced unparsable
+	// reports and burned whole audit budgets as undeterminable.
+	const agentPrompt = fs.readFileSync(new URL("../agents/execution-reviewer.md", import.meta.url), "utf8");
 	const result = await runPiSubagent({
-		systemPrompt: `${agentPrompt}\n\nYou are acting as the completion auditor; the task brief below defines the output contract.`,
+		systemPrompt: agentPrompt,
 		task,
 		cwd: ctx.cwd,
 		model: opts.model,
+		thinkingLevel: opts.thinkingLevel,
+		timeoutMs: opts.timeoutMs,
 		tools: ["read", "grep", "find", "ls"],
 		signal: opts.signal,
+		onProgress: opts.onProgress,
 	});
-	if (!result.ok) return null;
-	const { passed, failed } = parseAuditReport(result.output, opts.checklist);
-	messaging().appendEntry("pi-plans-audit", { planPath: opts.planPath, round: opts.round, passed, failed });
-	return applyAuditOutcome(opts.checklist, opts.tasks, opts.round, passed, failed, result.output);
+	if (!result.ok) {
+		if (result.cancelled === true) return { cancelled: true };
+		return null;
+	}
+	const parsed = parseAuditReport(result.output, pending.map((item) => item.id));
+	messaging().appendEntry("pi-plans-audit", {
+		planPath: opts.planPath,
+		round: opts.round,
+		passed: parsed.passed,
+		failed: parsed.failed,
+		undeterminable: parsed.undeterminable,
+	});
+	return applyAuditOutcome(opts.round, parsed, result.output);
+}
+
+/** Persist one review-round attempt under `<run-dir>/execution-review/`.
+ * The attempt index (not the budget round) names the file, so a discarded
+ * attempt's evidence survives its re-run: round-<budgetRound>-attempt-<k>.md.
+ * These files are the only cross-session record of what a round saw — the
+ * in-flight marker itself is memory-only. Best-effort: an unwritable run dir
+ * must never fail the loop itself. */
+export function writeReviewRoundReport(
+	runDir: string,
+	entry: {
+		budgetRound: number;
+		attempt: number;
+		outcome: "passed" | "failed" | "undeterminable" | "discarded" | "spawn-failed" | "cancelled";
+		passed: string[];
+		failed: string[];
+		undeterminable: string[];
+		discardedReason?: string;
+		fingerprintCaptured?: string;
+		fingerprintFound?: string;
+		coveredTaskIds: string[];
+		report: string;
+	},
+): string | null {
+	try {
+		const dir = path.join(runDir, "execution-review");
+		fs.mkdirSync(dir, { recursive: true });
+		const file = path.join(dir, `round-${entry.budgetRound}-attempt-${entry.attempt}.md`);
+		const lines = [
+			`# Execution review round ${entry.budgetRound} (attempt ${entry.attempt})`,
+			"",
+			`- outcome: ${entry.outcome}`,
+			`- passed: ${entry.passed.join(", ") || "(none)"}`,
+			`- failed: ${entry.failed.join(", ") || "(none)"}`,
+			`- undeterminable: ${entry.undeterminable.join(", ") || "(none)"}`,
+			...(entry.discardedReason ? [`- discarded: ${entry.discardedReason}`] : []),
+			`- fingerprint (captured): ${entry.fingerprintCaptured ?? "(n/a)"}`,
+			`- fingerprint (at resolve): ${entry.fingerprintFound ?? "(n/a)"}`,
+			`- covered tasks: ${entry.coveredTaskIds.join(", ") || "(none)"}`,
+			"",
+			"## Report",
+			"",
+			entry.report,
+			"",
+		];
+		fs.writeFileSync(file, lines.join("\n"), "utf8");
+		return file;
+	} catch {
+		return null;
+	}
 }

package/src/code-graph/commands.ts

@@ -284,7 +284,12 @@ export async function applyGraphCommand(args: string, ctx: CommandContext): Prom
 		errors > 0 ? "error" : "info",
 	);
 	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
-	if (active) setRunStatus(ctx.cwd, active.run_id, "executing");
+	if (active) {
+		// Never demote a verifying run back to executing: the execution-review
+		// loop owns the status until it converges (or pauses at the round cap).
+		const current = getRun(ctx.cwd, active.run_id)?.status;
+		if (current !== "verifying") setRunStatus(ctx.cwd, active.run_id, "executing");
+	}
 }
 
 export async function graphStatusCommand(_args: string, ctx: CommandContext): Promise<void> {

package/src/dashboard.ts

@@ -16,6 +16,7 @@
  */
 
 import type { CheckItem } from "./plan.ts";
+import { REVIEW_MAX_ROUNDS } from "./auditor.ts";
 import { truncateToWidth, visibleWidth } from "./refine-ui-helpers.ts";
 import {
 	allTasksTerminal,
@@ -38,15 +39,24 @@ export interface DashboardModel {
 	/** Audit round counter; null = audit not yet started. */
 	auditRounds: number | null;
 	auditFailed: string[];
+	/** Checks whose verdict the auditor could not be read for. Neither passed
+	 * nor failed: shown so the run does not read as finished. */
+	auditUndeterminable: string[];
+	/** v0.8: true while an execution-review round is in flight. The panel must
+	 * never render `audit complete ✓` while this is set — the round-1 mis-cue
+	 * showed the tick for the whole duration of a running audit. */
+	reviewRunning: boolean;
 	startedAt: string;
 	usage: { inToks: number; outToks: number };
 }
 
-/** Tree marker for one task row. */
+/** Tree marker for one task row. A rolled-back task is `pending` but still
+ * carries the evidence of its previous attempt, so it gets its own marker
+ * rather than reading as untouched work. */
 export function taskMarker(task: TaskView, currentId: string | null): string {
 	if (taskIsTerminal(task)) return task.status === "skipped" ? "~" : "✓";
 	if (task.id === currentId) return "▸";
-	return "·";
+	return task.evidence === undefined ? "·" : "↺";
 }
 
 /** Truncate to at most `max` display columns, ellipsis when clipped. */
@@ -157,16 +167,39 @@ export function renderDashboardLines(model: DashboardModel, width: number, theme
 			lines.push(boxRow("│", `   ${clip(cur.files.join(", "), inner - 4)}`, " ", width));
 		}
 	} else if (allTasksTerminal(model.tasks)) {
-		const auditLine = model.auditFailed.length > 0
-			? `audit: ${model.auditFailed.length} check(s) failed — rollback pending`
-			: model.auditRounds !== null
-				? "audit complete ✓"
-				: "all tasks terminal — audit pending";
+		// v0.8 mis-cue guard: `audit complete ✓` ONLY when nothing is running
+		// and nothing is owed. A running or owed review shows its round number
+		// instead — the panel must look alive, never finished-then-silent.
+		const owed = model.checklist.some((item) => !item.done);
+		const nextRound = (model.auditRounds ?? 0) + 1;
+		const auditLine = model.reviewRunning
+			? `review: round ${nextRound}/${REVIEW_MAX_ROUNDS} running — read-only reviewer verifying`
+			: model.auditFailed.length > 0
+				? `audit: ${model.auditFailed.length} check(s) failed — rollback pending`
+				: model.auditUndeterminable.length > 0
+					? `audit: ${model.auditUndeterminable.length} check(s) undeterminable — verdict unreadable`
+					: owed
+						? `review: round ${nextRound}/${REVIEW_MAX_ROUNDS} — verdict pending`
+						: model.auditRounds !== null
+							? "audit complete ✓"
+							: "all tasks terminal — audit pending";
 		lines.push(boxRow("│", ` ${clip(auditLine, inner - 2)}`, " ", width));
 	}
 	if (!narrow && model.auditFailed.length > 0) {
 		lines.push(boxRow("│", ` ✗ ${clip(model.auditFailed.join(", "), inner - 3)}`, " ", width));
 	}
+	if (!narrow && model.auditUndeterminable.length > 0) {
+		lines.push(boxRow("│", ` ? ${clip(model.auditUndeterminable.join(", "), inner - 3)}`, " ", width));
+	}
+	// Rolled-back work keeps the evidence of the attempt that was rolled back.
+	// The tree view shows it per row; the compact panel has room for a summary
+	// and must show it too, otherwise the retention is invisible outside the
+	// expanded view. Capped at two rows to protect the fixed panel height.
+	for (const rolled of flattenTaskViews(model.tasks)
+		.filter((task) => task.status === "pending" && task.evidence !== undefined)
+		.slice(0, 2)) {
+		lines.push(boxRow("│", ` ↺ ${rolled.id} ${clip(rolled.evidence!, inner - 6)}`, " ", width));
+	}
 	lines.push(boxRow("└", "─ Ctrl+Shift+T tree", "─", width, "┘"));
 	// The title row carries its own colours; every other row is muted.
 	const painted = theme ? lines.map((line, i) => (i === 0 ? line : theme.fg("muted", line))) : lines;
@@ -183,7 +216,7 @@ export function deriveDashboardModel(
 	topic: string,
 	tasks: TaskView[],
 	checklist: CheckItem[],
-	extra?: { paused?: boolean; pausedReason?: string; auditRounds?: number | null; auditFailed?: string[]; startedAt?: string; usage?: { inToks: number; outToks: number } },
+	extra?: { paused?: boolean; pausedReason?: string; auditRounds?: number | null; auditFailed?: string[]; auditUndeterminable?: string[]; reviewRunning?: boolean; startedAt?: string; usage?: { inToks: number; outToks: number } },
 ): DashboardModel {
 	return {
 		topic,
@@ -193,6 +226,8 @@ export function deriveDashboardModel(
 		pausedReason: extra?.pausedReason,
 		auditRounds: extra?.auditRounds ?? null,
 		auditFailed: extra?.auditFailed ?? [],
+		auditUndeterminable: extra?.auditUndeterminable ?? [],
+		reviewRunning: extra?.reviewRunning ?? false,
 		startedAt: extra?.startedAt ?? new Date().toISOString(),
 		usage: extra?.usage ?? { inToks: 0, outToks: 0 },
 	};
@@ -226,6 +261,9 @@ export function renderDashboardTreeLines(model: DashboardModel, width: number, t
 		if (wide && task.deps.length > 0) line += `  (deps: ${task.deps.join(", ")})`;
 		if (task.status === "skipped" && task.skipReason) line += `  ~${task.skipReason}`;
 		if (task.status === "complete" && task.evidence) line += `  ✓${clip(task.evidence, 40)}`;
+		// Rolled-back work keeps its evidence, and that evidence is the only
+		// record of what the previous attempt did.
+		if (task.status === "pending" && task.evidence) line += `  ↺${clip(task.evidence, 40)}`;
 		lines.push(line);
 		for (const child of task.children) row(child, depth + 1);
 	};	for (const task of model.tasks) row(task, 0);
@@ -235,9 +273,17 @@ export function renderDashboardTreeLines(model: DashboardModel, width: number, t
 		const mark = model.auditFailed.includes(item.id) ? "✗" : item.done ? "☑" : "☐";
 		lines.push(`  ${mark} ${item.id}${wide ? ` ${clip(item.text.split(";")[1] ?? item.text, Math.min(80, width))}` : ""}`);
 	}
-	if (model.auditRounds !== null) {
+	if (model.reviewRunning) {
+		lines.push("");
+		lines.push(`Execution review: round ${(model.auditRounds ?? 0) + 1}/${REVIEW_MAX_ROUNDS} running`);
+	} else if (model.auditRounds !== null) {
 		lines.push("");
-		lines.push(`Completion audit: round ${model.auditRounds}${model.auditFailed.length > 0 ? ` — failed: ${model.auditFailed.join(", ")}` : " — passed ✓"}`);
+		const verdict = model.auditFailed.length > 0
+			? ` — failed: ${model.auditFailed.join(", ")}`
+			: model.auditUndeterminable.length > 0
+				? ` — undeterminable: ${model.auditUndeterminable.join(", ")}`
+				: " — passed ✓";
+		lines.push(`Execution review: round ${model.auditRounds}${verdict}`);
 	}
 	const painted = theme ? lines.map((line) => theme.fg("muted", line)) : lines;
 	return clampLines(painted, width);