@phi-code-admin/phi-code 0.87.0 → 0.89.0

package/extensions/phi/orchestrator.ts

@@ -23,9 +23,17 @@ import { join } from "node:path";
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "phi-code";
 import { type AgentDef, loadAgentDef } from "./providers/agent-def.js";
+import { buildVerifyInstruction, debugPhaseInstructions } from "./providers/debug-build-commands.js";
+import { type FailingState, parseFailingState } from "./providers/debug-contract.js";
 import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
-import { extractBlockingFindings, extractHandoff, parsePhaseVerdict } from "./providers/orchestrator-helpers.js";
-import { analyzePhaseMessages, buildNextBrief, decidePhaseTransition } from "./providers/phase-machine.js";
+import {
+	analyzePhaseMessages,
+	buildNextBrief,
+	decidePhaseTransition,
+	resolvePhaseOutcome,
+	type StructuredPhaseResult,
+} from "./providers/phase-machine.js";
+import { triage } from "./providers/triage.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -284,6 +292,10 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 
 	let phaseQueue: OrchestratorPhase[] = [];
 	let orchestrationActive = false;
+	// Which pipeline is running. "plan" keeps the existing 5-phase agent_end path
+	// untouched; "debug"/"build" are driven by the separate linear generic driver
+	// so /plan's fragile review-fix + "/5" logic is never engaged for them.
+	let orchestrationMode: "plan" | "debug" | "build" = "plan";
 	let activeAgentPrompt: string | null = null;
 	let _activeAgentTools: string[] | null = null;
 	let savedTools: string[] | null = null;
@@ -309,11 +321,85 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	// Set true right before an INTERNAL ctx.abort() (phase timeout) so the
 	// resulting agent_end is not mistaken for a user Ctrl+C cancellation.
 	let internalAbort = false;
+	// Structured result emitted by the current phase via the `phase_result` tool
+	// (robust primary path). Reset at each phase start; read in agent_end and
+	// merged with the parsed markdown report (fallback) by resolvePhaseOutcome.
+	// currentPhaseResultKey stamps which phase produced it, so a stale result
+	// from a previous run/phase (or a tool call that lands after the phase
+	// transition) is never mistaken for the current phase's output.
+	let currentPhaseResult: StructuredPhaseResult | null = null;
+	let currentPhaseResultKey: string | null = null;
+
+	// ─── phase_result Tool — structured phase outcome (robust primary path) ───
+	// A phase agent CALLS this to emit its verdict/handoff/blocking as data
+	// instead of relying on the orchestrator regex-scraping its markdown report.
+	// It is only meaningful during /plan; outside orchestration it is a no-op so
+	// a stray call never errors. The markdown report is still written (it is the
+	// human-readable artifact); this just makes the machine-read path exact.
+	pi.registerTool({
+		name: "phase_result",
+		label: "Phase Result",
+		description:
+			"Report THIS /plan phase's structured outcome so the orchestrator reads it exactly instead of parsing your markdown. Call it once, at the end, IN ADDITION to writing your report file. TEST and REVIEW phases MUST call it with a verdict.",
+		promptGuidelines: [
+			"During a /plan phase, after writing your report file, call phase_result once with your verdict (TEST/REVIEW) and a concise handoff for the next phase.",
+			"verdict: PASS only if you OBSERVED success; FAIL if any blocking issue; BLOCKED if you could not run; SKIP if not applicable.",
+			"blocking: the must-fix findings (REVIEW), one per line. handoff: what is done, open risks, and the single most important next action.",
+		],
+		parameters: Type.Object({
+			verdict: Type.Optional(
+				Type.Union([Type.Literal("PASS"), Type.Literal("FAIL"), Type.Literal("BLOCKED"), Type.Literal("SKIP")], {
+					description: "Phase verdict (required for TEST and REVIEW phases)",
+				}),
+			),
+			blocking: Type.Optional(
+				Type.String({ description: "Must-fix findings, one per line (REVIEW). Empty when none." }),
+			),
+			handoff: Type.Optional(
+				Type.String({ description: "Concise handoff for the next phase: state, open risks, next action." }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!orchestrationActive) {
+				return {
+					content: [{ type: "text", text: "phase_result is only used during /plan orchestration; ignored here." }],
+					details: undefined,
+				};
+			}
+			const raw = params as { verdict?: StructuredPhaseResult["verdict"]; blocking?: string; handoff?: string };
+			// Merge only the fields this call actually set, so a phase that emits
+			// its result across several calls (verdict first, handoff later — a
+			// common LLM pattern) does not erase earlier fields. Start fresh when
+			// the previous result belonged to a different phase.
+			const defined: StructuredPhaseResult = {};
+			if (raw.verdict !== undefined) defined.verdict = raw.verdict;
+			if (typeof raw.blocking === "string") defined.blocking = raw.blocking;
+			if (typeof raw.handoff === "string") defined.handoff = raw.handoff;
+			const samePhase = currentPhaseResultKey === (currentPhase?.key ?? null);
+			currentPhaseResult = { ...(samePhase && currentPhaseResult ? currentPhaseResult : {}), ...defined };
+			currentPhaseResultKey = currentPhase?.key ?? null;
+			const parts = [
+				raw.verdict ? `verdict ${raw.verdict}` : null,
+				raw.blocking?.trim() ? "blocking findings" : null,
+				raw.handoff?.trim() ? "handoff" : null,
+			].filter(Boolean);
+			return {
+				content: [{ type: "text", text: `Phase result recorded${parts.length ? ` (${parts.join(", ")})` : ""}.` }],
+				details: undefined,
+			};
+		},
+	});
+
+	// A phase's report file is not always named <key>-<ts>.md: PLAN writes its
+	// handoff into todo-<ts>.md and CODE into progress-<ts>.md. Map key -> file
+	// stem so the text fallback for HANDOFF/BLOCKING actually finds them.
+	const REPORT_FILE_STEM: Record<string, string> = { plan: "todo", code: "progress" };
 
-	/** Read a phase's report file (.phi/plans/<key>-<ts>.md). Null-safe. */
+	/** Read a phase's report file (.phi/plans/<stem>-<ts>.md). Null-safe. */
 	function readPhaseReport(key: string, ts: string): string | null {
 		try {
-			const f = join(process.cwd(), ".phi", "plans", `${key}-${ts}.md`);
+			const stem = REPORT_FILE_STEM[key] ?? key;
+			const f = join(process.cwd(), ".phi", "plans", `${stem}-${ts}.md`);
 			if (existsSync(f)) return readFileSync(f, "utf-8");
 		} catch {
 			/* ignore */
@@ -626,6 +712,7 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 **Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "implementation" type "Phase" with properties {status: "complete", files: "N"}) and add a relation to the project entity.
 
 **CRITICAL RULES:**
+- **Minimal diff, root cause.** Prefer the SMALLEST change that fixes the underlying cause. Every extra condition, guard, or early-return you add is a liability — it can silently make the fix a no-op in the real scenario (a guard that skips the fix on the exact input the bug is about). When in doubt, do LESS and match the existing code's pattern rather than adding cleverness. A fix more elaborate than the problem is a red flag, not thoroughness.
 - Write ONE file per tool call — NEVER combine multiple files in a single response
 - Keep each file under 500 lines. If longer, split into modules
 - After writing ALL files, verify they exist with a single \`find . -name '*.ts' -o -name '*.js' -o -name '*.html' | sort\`` +
@@ -650,14 +737,13 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 
 **Step 1:** Read \`.phi/plans/todo-*.md\` to know what was planned
 **Step 2:** Read \`.phi/plans/progress-*.md\` to see what was done
-**Step 3:** ACTUALLY RUN the code and observe it (proof, not a declarative checkbox). Verification = runtime evidence, by surface type:
-   - **CLI:** run the real command, capture stdout AND the exit code, paste them.
-   - **HTTP/API:** start the server in the background with a readiness wait, then \`curl\` the route that changed; paste the response + status.
-   - **Library/package:** import the public entry and call it; paste the output.
-   - At least one adversarial probe per feature (empty input, wrong type, missing arg).
-   - Running \`npm test\` alone is NOT sufficient proof for a feature.
-**Step 4:** Fix any real errors you find (root cause, not a workaround).
+**Step 3 (GROUND TRUTH — the single most important step):** Derive the expected behaviour from the **Project Request above**, NEVER from the code that was written. Write a reproduction of the EXACT scenario the request describes — same conditions, same inputs. If the request is about a streaming response with no charset, stream a chunked response with no charset; if it is about an empty list, pass an empty list. Assert the behaviour the **request** says is correct, and make each assertion trace to a specific phrase in the request.
+   - **CRITICAL ANTI-PATTERN:** do NOT write a test that merely re-states what the CODE now does — that only confirms the code's own assumptions, which is exactly how a wrong fix passes its own tests. The test must be written as if you had NOT seen the fix.
+   - **FALSIFY FIRST:** your reproduction MUST FAIL against the ORIGINAL (pre-fix) code — \`git stash\` the fix, run it, confirm it fails, then \`git stash pop\` and confirm it now passes. If it passes on the original code, it does not reproduce the bug: rewrite it. Paste both runs.
+**Step 3b:** ACTUALLY RUN it and paste runtime evidence (stdout + exit code). Add at least one adversarial probe per feature (empty input, wrong type, missing arg). Running \`npm test\`/the existing suite alone is NOT sufficient — it does not cover the new scenario.
+**Step 4:** Fix any real errors you find (root cause, not a workaround). If the fix is a no-op in the request's own scenario, that is a FAIL, not a pass.
 **Step 5:** Write test results to \`.phi/plans/test-${ts}.md\`, starting the file with a VERDICT line.
+**Step 6 (MANDATORY):** Call the \`phase_result\` tool with your \`verdict\` (PASS/FAIL/BLOCKED) and a concise \`handoff\`. This is how the orchestrator reads your outcome exactly; the report file above is the human-readable copy.
 
 **Test report format (the FIRST line MUST be the verdict):**
 \`\`\`markdown
@@ -725,12 +811,14 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
    - **Angle 1 - Correctness:** read the diff line by line. What behaviour did it change or remove? Off-by-one, null/undefined, wrong condition, broken invariant.
    - **Angle 2 - Cross-file:** grep the callers and callees of changed symbols. Did a signature/return/contract change break a caller elsewhere?
    - **Angle 3 - Security & language pitfalls:** input validation, injection, secrets, auth, error handling; plus language traps (async not awaited, shadowed scope, mutation of shared state).
+   - **Angle 4 - Over-engineering & dead guards (the failure mode that ships confident-wrong fixes — check this FIRST):** for EVERY new condition, guard, or early-return the diff added, name the concrete input where it takes the SKIP / else branch, and check the behaviour is still correct THERE — *especially against the exact scenario in the Project Request*. A guard that makes the fix a no-op in the request's own scenario (e.g. an \`if buffered\` guard on a bug that is about the streaming path) is a **CONFIRMED** blocking bug. Then compare the diff's size to the problem: if the fix is more elaborate than the request requires, or does not match the surrounding code's existing pattern, that itself is a finding — the minimal change is usually the correct one.
 **Step 3 - VERIFY (3-state, cite the line):** for EACH candidate, quote the exact line and classify:
    - **CONFIRMED** - you can name the input/state that triggers it and the wrong output. Quote the line.
    - **PLAUSIBLE** - the mechanism is real but the trigger is uncertain. Say what would confirm it.
    - **REFUTED** - drop it. Only refute if you can quote the line that proves it cannot happen (a type, guard, or constant). When unsure, keep it PLAUSIBLE.
    Keep only CONFIRMED + PLAUSIBLE. A finding with no concrete failure scenario is noise: drop it.
 **Step 4:** Write \`.phi/plans/review-${ts}.md\`, starting with the VERDICT line.
+**Step 5 (MANDATORY):** Call the \`phase_result\` tool with your \`verdict\` (PASS/FAIL), the \`blocking\` findings (one per line, empty when none), and a short \`handoff\`. A FAIL here drives the one bounded fix→re-review cycle, so the orchestrator must read it exactly — do not rely on markdown parsing alone.
 
 **Final report format (the FIRST line MUST be the verdict):**
 \`\`\`markdown
@@ -844,9 +932,16 @@ Tag the note with relevant keywords for vector search.
 			activeAgentPrompt = agentDef.systemPrompt;
 			// Restrict tools to agent's allowed tools
 			if (agentDef.tools.length > 0) {
-				// Always include memory tools in orchestration phases
-				const memoryTools = ["memory_search", "memory_write", "memory_read", "ontology_add", "ontology_query"];
-				const agentTools = [...agentDef.tools, ...memoryTools.filter((t) => !agentDef.tools.includes(t))];
+				// Always include the memory tools and phase_result in orchestration phases.
+				const forcedTools = [
+					"memory_search",
+					"memory_write",
+					"memory_read",
+					"ontology_add",
+					"ontology_query",
+					"phase_result",
+				];
+				const agentTools = [...agentDef.tools, ...forcedTools.filter((t) => !agentDef.tools.includes(t))];
 				_activeAgentTools = agentTools;
 				pi.setActiveTools(agentTools);
 			} else if (savedTools) {
@@ -959,6 +1054,10 @@ Tag the note with relevant keywords for vector search.
 		const phase = phaseQueue.shift()!;
 		phasePending = true;
 		currentPhase = phase;
+		// New phase starts with no structured result; it is set only if this
+		// phase's agent calls phase_result.
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
 
 		switchModelForPhase(phase, ctx).then(({ modelId, warning }) => {
 			activateAgent(phase, ctx);
@@ -1004,6 +1103,242 @@ Tag the note with relevant keywords for vector search.
 		});
 	}
 
+	// ─── Generic linear driver (/debug, /build) ─────────────────────
+	// A deliberately simpler engine than /plan's: phases run in order, a BLOCKED
+	// verdict halts, and there is no review-fix cycle or "/5" bookkeeping. It
+	// reuses the tested primitives (switchModelForPhase, activateAgent,
+	// resolvePhaseOutcome) but never the /plan-specific agent_end path.
+
+	function routeFor(routeKey: string): { preferred: string; fallback: string } {
+		const routingPath = join(homedir(), ".phi", "agent", "routing.json");
+		try {
+			const routing = JSON.parse(readFileSync(routingPath, "utf-8"));
+			const route = routing.routes?.[routeKey];
+			return {
+				preferred: route?.preferredModel || routing.default?.model || "default",
+				fallback: route?.fallback || routing.default?.model || "default",
+			};
+		} catch {
+			return { preferred: "default", fallback: "default" };
+		}
+	}
+
+	function genericPhase(
+		key: string,
+		label: string,
+		routeKey: string,
+		agentKey: string,
+		instruction: string,
+	): OrchestratorPhase {
+		const route = routeFor(routeKey);
+		return {
+			key,
+			label,
+			model: route.preferred,
+			fallback: route.fallback,
+			agent: loadAgentDef(agentKey),
+			instruction: instruction + COMMON_PHASE_RULES,
+		};
+	}
+
+	// /debug: REPRODUCE → LOCALIZE → FIX → VERIFY. Each phase routes to a model
+	// that does NOT share the coder's blind spot (verify on the test family).
+	function buildDebugPhases(state: FailingState): OrchestratorPhase[] {
+		const ins = debugPhaseInstructions(state);
+		return [
+			genericPhase("reproduce", "🔴 Phase 1 — REPRODUCE", "test", "test", ins.reproduce),
+			genericPhase("localize", "🔎 Phase 2 — LOCALIZE", "explore", "explore", ins.localize),
+			genericPhase("fix", "🔧 Phase 3 — FIX", "code", "code", ins.fix),
+			genericPhase("verify", "✅ Phase 4 — VERIFY", "test", "test", ins.verify),
+		];
+	}
+
+	// /build: reuse /plan's EXPLORE→PLAN→CODE, then an execution-grounded
+	// BUILD-VERIFY that runs the recipe, checks acceptance, red-teams the
+	// boundary, and routes real failures to the /debug protocol.
+	function buildBuildPhases(spec: string, ts: string): OrchestratorPhase[] {
+		const planLike = buildPhases(spec, ts).slice(0, 3); // explore, plan, code
+		const verify = genericPhase(
+			"verify",
+			"🧪 Phase 4 — BUILD-VERIFY",
+			"review",
+			"review",
+			buildVerifyInstruction(spec),
+		);
+		return [...planLike, verify];
+	}
+
+	function finishGenericOrchestration(ctx: any, headline: string) {
+		const elapsed = phaseStartTime ? Math.round((Date.now() - phaseStartTime) / 1000) : 0;
+		const minutes = Math.floor(elapsed / 60);
+		const seconds = elapsed % 60;
+		const mode = orchestrationMode;
+		setOrchestrationActive(false);
+		phasePending = false;
+		orchestrationMode = "plan";
+		deactivateAgent();
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
+		}
+		if (originalModel) {
+			const toRestore = originalModel;
+			originalModel = null;
+			Promise.resolve(pi.setModel(toRestore)).catch(() => {
+				/* best effort */
+			});
+		}
+		ctx.ui.notify(
+			`\n📊 **/${mode} summary** — ${completedPhases} phase(s) in ${minutes}m ${seconds}s${
+				skippedPhases ? ` (${skippedPhases} skipped on timeout)` : ""
+			}\n${headline}`,
+			"info",
+		);
+	}
+
+	function sendNextGenericPhase(ctx: any) {
+		if (phaseQueue.length === 0) {
+			finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+			return;
+		}
+		const phase = phaseQueue.shift()!;
+		phasePending = true;
+		currentPhase = phase;
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
+
+		switchModelForPhase(phase, ctx).then(({ modelId, warning }) => {
+			activateAgent(phase, ctx);
+			const agentName = phase.agent?.name || phase.key;
+			ctx.ui.notify(`\n${phase.label} → \`${modelId}\` (agent: ${agentName})`, "info");
+			if (warning) ctx.ui.notify(`\n⚠️ ${warning}`, "warning");
+			setTimeout(() => pi.sendUserMessage(phase.instruction, { deliverAs: "followUp" }), 500);
+			if (phaseTimeoutId) clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = setTimeout(() => {
+				if (orchestrationActive && phasePending) {
+					phasePending = false;
+					internalAbort = true;
+					try {
+						ctx.abort();
+					} catch {
+						/* best effort */
+					}
+					if (!phase.retried) {
+						phase.retried = true;
+						phase.useFallback = true;
+						phaseQueue.unshift(phase);
+						ctx.ui.notify(
+							`\n⏰ **Phase timed out** (${MAX_PHASE_DURATION_MS / 60000} min) — retrying once on the fallback model.`,
+							"warning",
+						);
+					} else {
+						skippedPhases++;
+						ctx.ui.notify(`\n⏰ **Phase timed out again** — skipping to next phase.`, "warning");
+					}
+					sendNextGenericPhase(ctx);
+				}
+			}, MAX_PHASE_DURATION_MS);
+		});
+	}
+
+	async function handleGenericPhaseEnd(event: any, ctx: any) {
+		const messages = event.messages || [];
+		const analysis = analyzePhaseMessages(messages);
+
+		if (analysis.userAborted) {
+			ctx.ui.notify(`\n🛑 **/${orchestrationMode} cancelled** by user. Remaining phases skipped.`, "warning");
+			finishGenericOrchestration(ctx, "🛑 Cancelled.");
+			return;
+		}
+
+		if (!phasePending) {
+			if (phaseQueue.length === 0) finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+			return;
+		}
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
+		}
+
+		// A BLOCKED verdict (REPRODUCE cannot reproduce / VERIFY could not confirm)
+		// halts the pipeline honestly — no fabricated success.
+		const structuredForThisPhase = currentPhaseResultKey === (currentPhase?.key ?? null) ? currentPhaseResult : null;
+		const outcome = resolvePhaseOutcome(structuredForThisPhase, null);
+		if (outcome.verdict === "BLOCKED" && currentPhase) {
+			ctx.ui.notify(
+				`\n⏸️ **${currentPhase.label} reported BLOCKED.** ${outcome.handoff || "No reproducible/verifiable result."}`,
+				"warning",
+			);
+			finishGenericOrchestration(ctx, `⏸️ **/${orchestrationMode} stopped: BLOCKED at ${currentPhase.label}.**`);
+			return;
+		}
+
+		// Propagate a concise handoff to the next phase, like /plan does.
+		const nextBrief = buildNextBrief(
+			analysis,
+			outcome.handoff,
+			currentPhase?.label || "previous phase",
+			MAX_TOOL_CALLS_PER_PHASE,
+		);
+		if (nextBrief && phaseQueue.length > 0) {
+			phaseQueue[0].instruction += `\n\n**Previous phase summary:**\n${nextBrief}`;
+		}
+
+		completedPhases++;
+		phasePending = false;
+		sendNextGenericPhase(ctx);
+	}
+
+	function startGenericOrchestration(
+		mode: "debug" | "build",
+		phases: OrchestratorPhase[],
+		ctx: any,
+		headline: string,
+	) {
+		phaseQueue = phases.slice(1);
+		orchestrationMode = mode;
+		setOrchestrationActive(true);
+		phasePending = true;
+		originalModel = ctx.model || null;
+		savedTools = pi.getActiveTools();
+		completedPhases = 0;
+		skippedPhases = 0;
+		internalAbort = false;
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
+		phaseStartTime = Date.now();
+		const first = phases[0];
+		currentPhase = first;
+
+		ctx.ui.notify(headline, "info");
+		for (const p of phases) {
+			const agentName = p.agent?.name || p.key;
+			ctx.ui.notify(`  ${p.label} → \`${p.model}\` (agent: ${agentName})`, "info");
+		}
+
+		switchModelForPhase(first, ctx).then(({ modelId, warning }) => {
+			activateAgent(first, ctx);
+			ctx.ui.notify(`\n${first.label} → \`${modelId}\``, "info");
+			if (warning) ctx.ui.notify(`\n⚠️ ${warning}`, "warning");
+			if (phaseTimeoutId) clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = setTimeout(() => {
+				if (orchestrationActive && phasePending) {
+					phasePending = false;
+					internalAbort = true;
+					try {
+						ctx.abort();
+					} catch {
+						/* best effort */
+					}
+					skippedPhases++;
+					ctx.ui.notify(`\n⏰ **First phase timed out** — skipping.`, "warning");
+					sendNextGenericPhase(ctx);
+				}
+			}, MAX_PHASE_DURATION_MS);
+			setTimeout(() => pi.sendUserMessage(first.instruction, { deliverAs: "followUp" }), 200);
+		});
+	}
+
 	// ─── System Prompt Injection — Agent personas ────────────────────
 
 	pi.on("before_agent_start", async (_event, _ctx) => {
@@ -1033,6 +1368,13 @@ Tag the note with relevant keywords for vector search.
 			return;
 		}
 
+		// /debug and /build run on the separate linear driver — never through the
+		// /plan-specific review-fix + "/5" transition logic below.
+		if (orchestrationMode !== "plan") {
+			await handleGenericPhaseEnd(event, ctx);
+			return;
+		}
+
 		const messages = event.messages || [];
 		// Analyze what happened, read the phase's report, and let the pure state
 		// machine (providers/phase-machine.ts, unit tested) decide the transition.
@@ -1063,13 +1405,18 @@ Tag the note with relevant keywords for vector search.
 			phaseTimeoutId = null;
 		}
 
+		// Resolve the phase outcome: prefer the structured phase_result emission
+		// (exact) and fall back per-field to the regex-scraped markdown report.
+		// Only trust a structured result stamped with THIS phase's key — a stale
+		// result from a previous run or a late tool call is ignored.
 		const reportContent = currentPhase ? readPhaseReport(currentPhase.key, currentRunTs) : null;
-		const verdict = reportContent ? parsePhaseVerdict(reportContent) : null;
+		const structuredForThisPhase = currentPhaseResultKey === (currentPhase?.key ?? null) ? currentPhaseResult : null;
+		const outcome = resolvePhaseOutcome(structuredForThisPhase, reportContent);
+		const verdict = outcome.verdict;
 		const decision = decidePhaseTransition({
 			analysis,
 			phase: currentPhase ? { key: currentPhase.key, retried: currentPhase.retried } : null,
 			verdict,
-			hasReport: reportContent !== null,
 			reviewFixRounds,
 			maxToolCallsPerPhase: MAX_TOOL_CALLS_PER_PHASE,
 		});
@@ -1123,22 +1470,21 @@ Tag the note with relevant keywords for vector search.
 		}
 
 		if (decision.action === "continue" && decision.missingVerdict && currentPhase) {
-			// The model deviated from the text contract: this phase must start its
-			// report with "VERDICT: ..." and nothing parseable was found. Surface it
-			// instead of silently treating the phase as passed.
+			// The model deviated from BOTH contract paths: it neither called
+			// phase_result with a verdict nor wrote a parseable "VERDICT:" line.
+			// Surface it instead of silently treating the phase as passed.
 			ctx.ui.notify(
-				`\n⚠️ **${currentPhase.label} wrote no parseable VERDICT line** in \`.phi/plans/${currentPhase.key}-${currentRunTs}.md\` — treating it as passed. Check the report manually.`,
+				`\n⚠️ **${currentPhase.label} reported no verdict** (no phase_result call and no VERDICT line in \`.phi/plans/${currentPhase.key}-${currentRunTs}.md\`) — treating it as passed. Check the report manually.`,
 				"warning",
 			);
 		}
 
-		// Prefer the phase's canonical "## HANDOFF" block (a deterministic text
-		// contract written to its report file) over the heuristic summary; fall back
-		// to the heuristic when the model did not write one.
-		const handoff = reportContent ? extractHandoff(reportContent) : "";
+		// Prefer the resolved HANDOFF (structured phase_result, else the report's
+		// "## HANDOFF" block) over the heuristic summary; fall back to the
+		// heuristic when neither was provided.
 		const nextBrief = buildNextBrief(
 			analysis,
-			handoff,
+			outcome.handoff,
 			currentPhase?.label || "previous phase",
 			MAX_TOOL_CALLS_PER_PHASE,
 		);
@@ -1149,7 +1495,7 @@ Tag the note with relevant keywords for vector search.
 		if (decision.action === "review-fix-cycle" && currentPhase) {
 			// REVIEW FAIL: open ONE bounded fix -> re-review cycle.
 			reviewFixRounds++;
-			const blocking = (reportContent ? extractBlockingFindings(reportContent) : "").slice(0, 4000);
+			const blocking = outcome.blocking.slice(0, 4000);
 			const fixPhase: OrchestratorPhase = {
 				key: "code",
 				label: "🔧 Fix — CODE (review remediation)",
@@ -1217,6 +1563,10 @@ Tag the note with relevant keywords for vector search.
 				skippedPhases = 0;
 				reviewFixRounds = 0;
 				internalAbort = false;
+				// Clear any structured result left over from a prior run so this
+				// resumed phase's outcome is read fresh (see phase-result leak guard).
+				currentPhaseResult = null;
+				currentPhaseResultKey = null;
 				phaseStartTime = Date.now();
 				const firstResume = remaining[0];
 				currentPhase = firstResume;
@@ -1279,6 +1629,11 @@ Tag the note with relevant keywords for vector search.
 			skippedPhases = 0;
 			reviewFixRounds = 0;
 			internalAbort = false;
+			// Clear any structured result left over from a previous /plan run in
+			// this session; the first phase is launched directly (not via
+			// sendNextPhase), so without this a stale verdict/handoff would leak.
+			currentPhaseResult = null;
+			currentPhaseResultKey = null;
 			const firstPhase = phases[0];
 			currentPhase = firstPhase;
 
@@ -1411,4 +1766,105 @@ Tag the note with relevant keywords for vector search.
 			ctx.ui.notify(output, "info");
 		},
 	});
+
+	// ─── /debug Command — turn a real failure green (execution-grounded) ──
+
+	pi.registerCommand("debug", {
+		description: "Fix a REAL failing state — REPRODUCE → LOCALIZE → FIX → VERIFY, verdict backed by a real run",
+		handler: async (args, ctx) => {
+			if (orchestrationActive) {
+				ctx.ui.notify("An orchestration is already running. Let it finish, or restart the session.", "warning");
+				return;
+			}
+			const raw = args.trim();
+			if (!raw) {
+				ctx.ui.notify(
+					`**Usage:** \`/debug <failing test | repro command | description>\`
+
+/debug never guesses — it needs something reproducible.
+**Examples:**
+  /debug pytest tests/test_auth.py::test_login_returns_jwt
+  /debug node repro.js  (segfaults on empty input, should return [])
+  /debug the /login route 500s when the body is missing
+
+It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a real before/after run — otherwise BLOCKED.`,
+					"info",
+				);
+				return;
+			}
+
+			const state: FailingState = parseFailingState(raw, { cwd: ctx.cwd || process.cwd() });
+			// Honest gate at the boundary: /debug needs a reproducible failure. A bare
+			// prose description with no test/command still runs (REPRODUCE will try to
+			// derive one), but we tell the user the oracle depends on a real run.
+			if (!state.failingTest && !state.reproCommand) {
+				ctx.ui.notify(
+					`⚠️ No failing test or repro command detected — /debug works best with one (e.g. \`pytest …\` or \`node repro.js\`). Proceeding: REPRODUCE will try to construct a reproduction from your description, and will emit **BLOCKED** if it cannot run one (no fabricated PASS).`,
+					"warning",
+				);
+			}
+
+			await ensurePlansDir();
+			const phases = buildDebugPhases(state);
+			startGenericOrchestration(
+				"debug",
+				phases,
+				ctx,
+				`🐛 **/debug started** — 4 execution-grounded phases (verdict requires a real run)\n`,
+			);
+		},
+	});
+
+	// ─── /build Command — build until it runs (plan + execution loop) ────
+
+	pi.registerCommand("build", {
+		description:
+			"Build from a spec AND prove it runs — EXPLORE → PLAN → CODE → BUILD-VERIFY (run + red-team + debug)",
+		handler: async (args, ctx) => {
+			if (orchestrationActive) {
+				ctx.ui.notify("An orchestration is already running. Let it finish, or restart the session.", "warning");
+				return;
+			}
+			const spec = args.trim();
+			if (!spec) {
+				ctx.ui.notify(
+					`**Usage:** \`/build <what to build>\`
+
+/build = /plan then an execution-grounded verify loop (run the recipe, check acceptance, executable red-team, fix real failures via /debug).
+**Examples:**
+  /build a REST API for user auth with JWT and refresh tokens
+  /build a CLI that converts CSV to JSON with a --pretty flag
+
+It reports SUCCESS only when a real run meets the acceptance criteria — otherwise an honest PARTIAL listing what still fails. For a pure decomposition use \`/plan\`; to fix a known failure use \`/debug\`.`,
+					"info",
+				);
+				return;
+			}
+
+			// Cheap triage note (transparency): confirm /build is the right depth.
+			const decision = triage({ text: spec });
+			if (decision.route === "single-shot") {
+				ctx.ui.notify(
+					`ℹ️ This looks small and self-contained (${decision.reason}). /build will still run, but a single request may be cheaper.`,
+					"info",
+				);
+			}
+
+			await ensurePlansDir();
+			const ts = timestamp();
+			await writeFile(
+				join(plansDir, `spec-${ts}.md`),
+				`# ${spec}\n\n**Created:** ${new Date().toLocaleString()}\n`,
+				"utf-8",
+			);
+			currentDescription = spec;
+			const phases = buildBuildPhases(spec, ts);
+			startGenericOrchestration(
+				"build",
+				phases,
+				ctx,
+				`🏗️ **/build started** — plan + execution loop (SUCCESS requires a real run, else honest PARTIAL)\n`,
+			);
+		},
+	});
 }