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

package/extensions/phi/providers/acceptance.ts

@@ -0,0 +1,102 @@
+/**
+ * Acceptance criteria and run recipe — the executable contract for /plan and
+ * /build. Criteria are derived from the SPEC (not the code), and each carries an
+ * optional `check` command so "is it satisfied?" is answered by running
+ * something, not by a model's opinion (see docs/design/plan-debug-build.md).
+ */
+
+import { type CommandResult, passed, type RunOptions, runCommand, summarize } from "./execution.js";
+
+/** How to build/run/test the project. Emitted by /plan, consumed by /build. */
+export interface RunRecipe {
+	build?: string;
+	run?: string;
+	test?: string;
+	/** A substring that, once seen in run output, means the app is ready. */
+	readySignal?: string;
+}
+
+export interface AcceptanceCriterion {
+	/** Human statement traced to the spec, e.g. "POST /login returns 200 + a JWT". */
+	description: string;
+	/**
+	 * Optional command that exits 0 iff the criterion holds. When absent the
+	 * criterion is "manual" — it can only be judged by a human/agent, never
+	 * auto-marked satisfied (that is the anti-circularity rule).
+	 */
+	check?: string;
+}
+
+export interface CriterionResult {
+	criterion: AcceptanceCriterion;
+	/** true = ran and passed; false = ran and failed; null = manual (no check). */
+	satisfied: boolean | null;
+	result?: CommandResult;
+}
+
+export interface AcceptanceReport {
+	results: CriterionResult[];
+	/** Criteria with a check that failed — the concrete work for /debug. */
+	failed: CriterionResult[];
+	/** Criteria with no check — cannot be auto-verified, surfaced honestly. */
+	manual: CriterionResult[];
+	/** All checkable criteria passed (manual ones are NOT counted as passing). */
+	allCheckablePassed: boolean;
+}
+
+/**
+ * Run every criterion's check command and classify. A criterion with no check
+ * is reported as `manual` (satisfied: null) — never silently counted as passed.
+ */
+export function checkAcceptance(criteria: AcceptanceCriterion[], options: RunOptions = {}): AcceptanceReport {
+	const results: CriterionResult[] = criteria.map((criterion) => {
+		if (!criterion.check || !criterion.check.trim()) {
+			return { criterion, satisfied: null };
+		}
+		const result = runCommand(criterion.check, options);
+		return { criterion, satisfied: passed(result), result };
+	});
+
+	const failed = results.filter((r) => r.satisfied === false);
+	const manual = results.filter((r) => r.satisfied === null);
+	const checkable = results.filter((r) => r.satisfied !== null);
+	return {
+		results,
+		failed,
+		manual,
+		allCheckablePassed: checkable.length > 0 && failed.length === 0,
+	};
+}
+
+/** Markdown summary of an acceptance run for a report / handoff. */
+export function formatAcceptance(report: AcceptanceReport): string {
+	const line = (r: CriterionResult) => {
+		const mark = r.satisfied === true ? "✅" : r.satisfied === false ? "❌" : "❔";
+		const detail = r.result ? ` — ${summarize(r.result)}` : r.satisfied === null ? " — (no check, manual)" : "";
+		return `- ${mark} ${r.criterion.description}${detail}`;
+	};
+	return report.results.map(line).join("\n");
+}
+
+/**
+ * Validate a parsed RunRecipe/criteria object (e.g. from a phase_result), so a
+ * malformed emission is caught at the boundary.
+ */
+export function validateCriteria(raw: unknown): AcceptanceCriterion[] {
+	if (!Array.isArray(raw)) return [];
+	const out: AcceptanceCriterion[] = [];
+	for (const item of raw) {
+		if (typeof item === "string" && item.trim()) {
+			out.push({ description: item.trim() });
+		} else if (item && typeof item === "object") {
+			const o = item as Record<string, unknown>;
+			if (typeof o.description === "string" && o.description.trim()) {
+				out.push({
+					description: o.description.trim(),
+					check: typeof o.check === "string" && o.check.trim() ? o.check.trim() : undefined,
+				});
+			}
+		}
+	}
+	return out;
+}

package/extensions/phi/providers/build-loop.ts

@@ -0,0 +1,89 @@
+/**
+ * /build outer loop — the pure decision core that composes the two oracles
+ * (docs/design/plan-debug-build.md): an acceptance RUN and an executable
+ * red-team. It never runs anything itself; given this round's reports it decides
+ * SUCCESS, CONTINUE (hand these real failures to /debug), or PARTIAL (budget
+ * spent — report what still fails honestly, never a confident-wrong PASS).
+ */
+
+import type { AcceptanceReport, CriterionResult } from "./acceptance.js";
+import type { FailingState } from "./debug-contract.js";
+import { type BreakingCase, breakingCasesToFailingStates } from "./redteam.js";
+
+export type BuildStatus = "success" | "continue" | "partial";
+
+export interface BuildDecision {
+	status: BuildStatus;
+	/** Real failures to route to /debug (continue) or to report (partial). */
+	failures: FailingState[];
+	/** Manual criteria that could not be executed — surfaced, never counted green. */
+	unverified: string[];
+	reason: string;
+}
+
+export interface BuildRoundInput {
+	round: number;
+	maxRounds: number;
+	acceptance: AcceptanceReport;
+	breakingCases: BreakingCase[];
+	cwd?: string;
+}
+
+/** A failed acceptance criterion becomes a failing state /debug can reproduce. */
+export function criterionToFailingState(r: CriterionResult, cwd?: string): FailingState {
+	return {
+		reproCommand: r.criterion.check,
+		expected: r.criterion.description,
+		trace: r.result ? `${r.result.command} exited ${r.result.exitCode}` : undefined,
+		cwd,
+	};
+}
+
+/**
+ * Decide one round of the build loop. SUCCESS requires: at least one criterion
+ * was actually checked, none failed, and the red-team found no break. Manual
+ * criteria never count toward success — they are reported as `unverified`.
+ */
+export function decideBuildRound(input: BuildRoundInput): BuildDecision {
+	const failedStates = input.acceptance.failed.map((r) => criterionToFailingState(r, input.cwd));
+	const breakStates = breakingCasesToFailingStates(input.breakingCases, input.cwd);
+	const failures = [...failedStates, ...breakStates];
+	const unverified = input.acceptance.manual.map((r) => r.criterion.description);
+
+	if (failures.length === 0) {
+		if (!input.acceptance.allCheckablePassed) {
+			// Nothing failed, but nothing was executably verified either.
+			return {
+				status: "partial",
+				failures: [],
+				unverified,
+				reason: "no criterion could be executed — nothing verified; add checkable acceptance criteria",
+			};
+		}
+		const note = unverified.length ? ` (${unverified.length} manual criteria still unverified)` : "";
+		return {
+			status: "success",
+			failures: [],
+			unverified,
+			reason: `all checkable acceptance criteria passed and the red-team found no break${note}`,
+		};
+	}
+
+	if (input.round >= input.maxRounds) {
+		return {
+			status: "partial",
+			failures,
+			unverified,
+			reason: `budget exhausted after ${input.maxRounds} round(s); ${failures.length} failure(s) still open`,
+		};
+	}
+
+	return {
+		status: "continue",
+		failures,
+		unverified,
+		reason: `${failures.length} real failure(s) this round → route to /debug (round ${input.round}/${input.maxRounds})`,
+	};
+}
+
+export const DEFAULT_MAX_ROUNDS = 4;

package/extensions/phi/providers/candidate-select.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimality guard — pick the best of several candidate fixes.
+ *
+ * Lesson from the SWE-bench-lite head-to-head: /plan's extra deliberation made
+ * it produce a MORE elaborate (and wrong) fix than a single shot on the missed
+ * instance, while its diff was better-formed (it applied; the baseline's did
+ * not). The winning move is to generate more than one candidate and keep the
+ * SIMPLEST one that actually passes an executable acceptance repro — combining
+ * /plan's well-formed diffs with single-shot's tendency to stay minimal.
+ *
+ * This module is the pure decision core (no I/O): the caller runs each
+ * candidate against the same acceptance repro and reports `passedRepro`; this
+ * picks the winner. "Simplest" = fewest changed source lines in the unified
+ * diff (a robust, language-agnostic proxy for over-engineering).
+ */
+
+export interface FixCandidate {
+	/** Where it came from, for diagnostics: "single-shot", "plan", "plan-fix", ... */
+	source: string;
+	/** Unified diff. */
+	patch: string;
+	/**
+	 * Did this candidate pass the model's own falsify-first acceptance repro
+	 * (the repro that FAILS on the pre-fix code and must PASS after)? Undefined
+	 * when no repro was available to gate on.
+	 */
+	passedRepro?: boolean;
+}
+
+export interface CandidateSelection {
+	chosen: FixCandidate | null;
+	/** Human-readable rationale (surfaced to the user and asserted in tests). */
+	reason: string;
+	/** Changed-source-line count of the chosen patch (0 when none). */
+	chosenSize: number;
+}
+
+/**
+ * Count changed source lines in a unified diff: added/removed lines, excluding
+ * diff/hunk headers (---, +++, @@, diff --git, index) so the number reflects
+ * real edits, not file boilerplate.
+ */
+export function diffChangedLines(patch: string): number {
+	if (!patch) return 0;
+	let n = 0;
+	for (const line of patch.split("\n")) {
+		if (line.startsWith("+++") || line.startsWith("---")) continue;
+		if ((line.startsWith("+") || line.startsWith("-")) && line.length > 0) n++;
+	}
+	return n;
+}
+
+const hasPatch = (c: FixCandidate) => c.patch.trim().length > 0;
+
+/**
+ * Select the best candidate:
+ *  1. Among candidates that PASSED the acceptance repro, pick the smallest diff
+ *     (ties → the earliest in the list, so callers can order by preference).
+ *  2. If none is known to pass but some were never gated (passedRepro undefined),
+ *     pick the smallest non-empty patch among those (best effort).
+ *  3. If a repro existed and every candidate FAILED it, choose nothing — the
+ *     honest outcome is "no candidate is verified", not "ship the least-bad".
+ *  4. No non-empty patches → nothing.
+ */
+export function selectMinimalPassingCandidate(candidates: FixCandidate[]): CandidateSelection {
+	const nonEmpty = candidates.filter(hasPatch);
+	if (nonEmpty.length === 0) {
+		return { chosen: null, reason: "no candidate produced a non-empty patch", chosenSize: 0 };
+	}
+
+	const passed = nonEmpty.filter((c) => c.passedRepro === true);
+	if (passed.length > 0) {
+		const chosen = smallest(passed);
+		const others = passed.filter((c) => c !== chosen);
+		const note = others.length
+			? ` (over ${others.map((c) => `${c.source}:${diffChangedLines(c.patch)}`).join(", ")})`
+			: "";
+		return {
+			chosen,
+			reason: `smallest patch that passes the acceptance repro: ${chosen.source} (${diffChangedLines(chosen.patch)} changed lines)${note}`,
+			chosenSize: diffChangedLines(chosen.patch),
+		};
+	}
+
+	const anyGated = nonEmpty.some((c) => c.passedRepro === true || c.passedRepro === false);
+	if (anyGated) {
+		// A repro existed and nothing passed it — do not pretend a candidate is verified.
+		return { chosen: null, reason: "an acceptance repro existed but no candidate passed it", chosenSize: 0 };
+	}
+
+	// No repro to gate on: fall back to the smallest non-empty patch (best effort).
+	const chosen = smallest(nonEmpty);
+	return {
+		chosen,
+		reason: `no acceptance repro to gate on; smallest non-empty patch: ${chosen.source} (${diffChangedLines(chosen.patch)} changed lines)`,
+		chosenSize: diffChangedLines(chosen.patch),
+	};
+}
+
+/** Smallest by changed-line count; ties keep list order (stable). */
+function smallest(cs: FixCandidate[]): FixCandidate {
+	let best = cs[0];
+	let bestSize = diffChangedLines(best.patch);
+	for (let i = 1; i < cs.length; i++) {
+		const s = diffChangedLines(cs[i].patch);
+		if (s < bestSize) {
+			best = cs[i];
+			bestSize = s;
+		}
+	}
+	return best;
+}

package/extensions/phi/providers/debug-build-commands.ts

@@ -0,0 +1,129 @@
+/**
+ * Instruction builders for the /debug and /build phase pipelines.
+ *
+ * These are PURE text builders (no fs, no Pi) so the exact protocol each phase
+ * agent receives is unit-testable. They encode the contracts from
+ * docs/design/plan-debug-build.md: /debug turns a REAL failure green through
+ * REPRODUCE → LOCALIZE → FIX → VERIFY with execution as the only oracle; /build
+ * adds an execution-grounded verify (run recipe + acceptance + executable
+ * red-team) that routes real failures back to the /debug protocol.
+ */
+
+import type { FailingState } from "./debug-contract.js";
+
+/** Render a failing state as a compact, unambiguous block for an instruction. */
+export function formatFailingState(state: FailingState): string {
+	const lines: string[] = [];
+	if (state.failingTest?.trim()) lines.push(`- Failing test: \`${state.failingTest.trim()}\``);
+	if (state.reproCommand?.trim()) lines.push(`- Repro command: \`${state.reproCommand.trim()}\``);
+	if (state.expected?.trim()) lines.push(`- Expected behaviour: ${state.expected.trim()}`);
+	if (state.trace?.trim()) lines.push(`- Trace / error:\n\`\`\`\n${state.trace.trim()}\n\`\`\``);
+	if (state.cwd?.trim()) lines.push(`- Working directory: \`${state.cwd.trim()}\``);
+	return lines.length ? lines.join("\n") : "- (no structured failing state supplied)";
+}
+
+export interface DebugInstructions {
+	reproduce: string;
+	localize: string;
+	fix: string;
+	verify: string;
+}
+
+const DEBUG_RULES = `
+---
+## /debug operating rules (non-negotiable)
+- **Execution is the only oracle.** No verdict without a real run whose output you paste. Never write FIXED because the code "looks right".
+- **No fabricated PASS.** If you cannot run the reproduction (missing env/deps), emit \`BLOCKED: no executable environment\` — do NOT reconstruct a mock and grade your own reconstruction.
+- **Minimal fix wins.** Prefer the smallest change; every added guard/condition is a liability that can hide the bug (an over-clever guard is exactly how these fixes go wrong).
+- **Root cause, not workaround.** No skipped tests, no \`--no-verify\`, no mock that hides the failure.
+- The user does NOT answer during these phases. Act autonomously; do not end with a question.`;
+
+/** The four /debug phase instructions, specialised to the concrete failing state. */
+export function debugPhaseInstructions(state: FailingState): DebugInstructions {
+	const failing = formatFailingState(state);
+	const repro = state.failingTest?.trim() || state.reproCommand?.trim() || "(the reproduction command)";
+
+	return {
+		reproduce:
+			`You are the REPRODUCE agent (phase 1 of /debug). Your only job is to CONFIRM the failure is real.
+
+**The reported failing state:**
+${failing}
+
+**Do exactly this:**
+1. Run the reproduction on the CURRENT, unmodified code: \`${repro}\`.
+2. Paste the exact command and its full output.
+3. Decide:
+   - If it FAILS as reported → capture the precise symptom (assertion, exception, exit code) and hand off to LOCALIZE.
+   - If it PASSES → STOP. Write \`BLOCKED: cannot reproduce — passes on current code\` with the run pasted. Do not invent a bug.
+   - If it cannot be run at all (missing deps/env) → STOP. Write \`BLOCKED: no executable environment\` with what failed.
+4. Do NOT edit any source yet. This phase only observes.
+5. **Last action:** call \`phase_result\` — \`verdict: PASS\` if it reproduced (proceed to LOCALIZE), or \`verdict: BLOCKED\` with the reason if you stopped.` +
+			DEBUG_RULES,
+
+		localize: `You are the LOCALIZE agent (phase 2 of /debug). Drive from the REAL symptom the previous phase captured.
+
+**The failing state:**
+${failing}
+
+**Do exactly this:**
+1. Read the traceback / error from the reproduction. Follow it to the exact frame.
+2. Read the implicated source and the symbols it touches (grep the nearby/changed identifiers).
+3. Name the fault site precisely — file:line and the wrong assumption. Localization, not more review, is the lever here.
+4. Hand off a crisp fault description; do NOT fix yet.${DEBUG_RULES}`,
+
+		fix:
+			`You are the FIX agent (phase 3 of /debug). Produce the MINIMAL change that addresses the located root cause.
+
+**The failing state:**
+${failing}
+
+**Do exactly this:**
+1. Write the smallest patch that fixes the root cause at the fault site LOCALIZE named.
+2. If two approaches are plausible, prefer the one that adds the least surface (fewest new branches/guards).
+3. Do NOT run the suite to "confirm" here by eye — VERIFY re-runs everything. Just make the change and state precisely what you changed and why it addresses the cause.` +
+			DEBUG_RULES,
+
+		verify: `You are the VERIFY agent (phase 4 of /debug) — the oracle. A green verdict requires TWO real runs.
+
+**The failing state:**
+${failing}
+
+**Do exactly this, pasting every command's output:**
+1. Re-run the reproduction: \`${repro}\`. It MUST now pass.
+2. Run the existing test suite (the project's test command). It MUST NOT regress.
+3. Verdict:
+   - Both green → \`FIXED\`, and paste the before(fail)/after(pass) reproduction runs and the green suite as evidence.
+   - Reproduction still fails, or the suite regresses → \`BLOCKED\` with the closest diagnostic. Do NOT ship the least-bad patch; a wrong fix is worse than an honest BLOCKED.
+4. Write the final verdict block, then call \`phase_result\` with \`verdict: PASS\` (FIXED) or \`verdict: BLOCKED\`, plus a one-line handoff:
+\`\`\`
+VERDICT: FIXED | BLOCKED
+Evidence: reproBefore=fail reproAfter=pass suite=green|skipped
+Reason: <only when BLOCKED>
+\`\`\`${DEBUG_RULES}`,
+	};
+}
+
+/**
+ * The /build execution-grounded verify phase: run the recipe, check acceptance,
+ * red-team the boundary the change touched, and route real failures to /debug.
+ */
+export function buildVerifyInstruction(spec: string): string {
+	return `You are the BUILD-VERIFY agent — the execution oracle for /build. The code has been written; now PROVE it runs and meets the spec, or report honestly what still fails.
+
+**Original spec:** ${spec}
+
+**Do exactly this, pasting every command's output:**
+1. **Run recipe.** From the brief's \`## Run Recipe\` (or package.json / Makefile / Dockerfile), build and start the app. Distinguish a real failure from a stale launch recipe.
+2. **Acceptance.** For each acceptance criterion derived from the SPEC (not the code), run a concrete check that exits 0 iff it holds. Mark each ✅ (ran+passed), ❌ (ran+failed), or ❔ (could not be executed — NEVER count ❔ as passing).
+3. **Executable red-team.** Attack the specific input regimes the change touched (empty, null, boundary, wrong-type, and buffered-vs-streaming / malformed / auth as relevant). Each attack must be a RUNNABLE test that goes RED if it breaks the code — an opinion is not a finding.
+4. **Route real failures.** For every ❌ criterion and every red-team break, treat it as a concrete failing state (failing test / repro command / expected) and fix it with the /debug protocol: REPRODUCE → LOCALIZE → minimal FIX → VERIFY (re-run the reproduction AND the suite).
+5. **Honest verdict.** When all checkable criteria pass and the red-team finds no break, write \`BUILD: SUCCESS\`. If rounds/budget run out with failures open, write \`BUILD: PARTIAL\` and LIST exactly which criteria still fail — never a confident-wrong SUCCESS. Then call \`phase_result\` with \`verdict: PASS\` (SUCCESS) or \`verdict: FAIL\`/\`BLOCKED\` and the handoff.
+\`\`\`
+VERDICT: PASS | FAIL | BLOCKED
+Handoff:
+State: <what runs and is proven by a real run>
+Open Risks: <criteria still ❔ unverified or ❌ failing>
+Next: <the single most important remaining action>
+\`\`\`${DEBUG_RULES}`;
+}

package/extensions/phi/providers/debug-contract.ts

@@ -0,0 +1,131 @@
+/**
+ * /debug contract — turn a REAL failing state green, or honestly say BLOCKED.
+ *
+ * The whole point (docs/design/plan-debug-build.md): /debug never guesses what
+ * is wrong. It is given a reproducible failure, confirms it fails on the current
+ * code, fixes it, and VERIFIES by re-running — repro passes AND the existing
+ * suite does not regress — selecting the minimal passing candidate. There is no
+ * path to FIXED without execution.
+ */
+
+import { type FixCandidate, selectMinimalPassingCandidate } from "./candidate-select.js";
+import { type CommandResult, passed } from "./execution.js";
+
+/** A concrete, reproducible failing state — /debug's input. */
+export interface FailingState {
+	/** A test command, e.g. "pytest tests/x.py::test_y". */
+	failingTest?: string;
+	/** A stack trace / error output pasted from a real run. */
+	trace?: string;
+	/** A command that exhibits the bug. */
+	reproCommand?: string;
+	/** What should happen instead (from the user/spec). */
+	expected?: string;
+	cwd?: string;
+}
+
+/** How to run the existing suite, to catch regressions. */
+export interface SuiteRecipe {
+	test?: string;
+}
+
+export type DebugVerdict = "FIXED" | "BLOCKED";
+
+export interface DebugOutcome {
+	verdict: DebugVerdict;
+	patch?: string;
+	evidence?: { reproBefore: "fail"; reproAfter: "pass"; suite: "green" | "skipped" };
+	reason?: string;
+}
+
+/** True when the input actually gives something runnable to reproduce. */
+export function hasReproducibleFailure(state: FailingState): boolean {
+	return Boolean(state.failingTest?.trim() || state.reproCommand?.trim());
+}
+
+/** The command that reproduces the failure (test preferred over generic repro). */
+export function reproCommand(state: FailingState): string | undefined {
+	return state.failingTest?.trim() || state.reproCommand?.trim() || undefined;
+}
+
+export type ReproduceDecision = { action: "proceed"; symptom: string } | { action: "blocked"; reason: string };
+
+/**
+ * REPRODUCE gate: the failing state must FAIL on the current code. If there is
+ * nothing runnable, or it already passes, /debug stops — it will not fabricate a
+ * bug or a repro from imagination.
+ */
+export function decideReproduce(state: FailingState, runOnCurrentCode: CommandResult | null): ReproduceDecision {
+	if (!hasReproducibleFailure(state)) {
+		return { action: "blocked", reason: "no reproducible failing state (need a failing test or a repro command)" };
+	}
+	if (runOnCurrentCode === null) {
+		return { action: "blocked", reason: "could not run the reproduction (no executable environment)" };
+	}
+	if (passed(runOnCurrentCode)) {
+		return { action: "blocked", reason: "the reported failure does not reproduce — it passes on the current code" };
+	}
+	return { action: "proceed", symptom: `${runOnCurrentCode.command} exited ${runOnCurrentCode.exitCode}` };
+}
+
+/** A fix candidate paired with its verification runs. */
+export interface VerifiedCandidate {
+	source: string;
+	patch: string;
+	/** The reproduction re-run WITH this candidate applied. */
+	reproAfter: CommandResult | null;
+	/** The existing suite re-run WITH this candidate applied (null = no suite). */
+	suite: CommandResult | null;
+}
+
+/**
+ * VERIFY: a candidate is accepted only if the repro now PASSES and the suite (if
+ * any) is green. Among accepted candidates, pick the minimal diff. If none is
+ * accepted, BLOCKED — never ship the least-bad.
+ */
+export function decideVerify(candidates: VerifiedCandidate[], hasSuite: boolean): DebugOutcome {
+	const fixCandidates: FixCandidate[] = candidates.map((c) => {
+		const reproOk = c.reproAfter !== null && passed(c.reproAfter);
+		const suiteOk = !hasSuite || (c.suite !== null && passed(c.suite));
+		return { source: c.source, patch: c.patch, passedRepro: reproOk && suiteOk };
+	});
+	const selection = selectMinimalPassingCandidate(fixCandidates);
+	if (!selection.chosen) {
+		return {
+			verdict: "BLOCKED",
+			reason: fixCandidates.some((c) => c.patch.trim())
+				? "no candidate makes the reproduction pass without regressing the suite"
+				: "no candidate produced a patch",
+		};
+	}
+	return {
+		verdict: "FIXED",
+		patch: selection.chosen.patch,
+		evidence: { reproBefore: "fail", reproAfter: "pass", suite: hasSuite ? "green" : "skipped" },
+		reason: selection.reason,
+	};
+}
+
+/** Parse a /debug argument string / structured input into a FailingState. */
+export function parseFailingState(arg: string, structured?: Partial<FailingState>): FailingState {
+	const a = arg.trim();
+	const state: FailingState = { ...structured };
+	// Heuristic: a bare test-runner invocation is a failing test; anything else
+	// with a command shape is a repro command; free prose is `expected`.
+	if (!state.failingTest && !state.reproCommand && a) {
+		// Test-runner invocations → a failing test. Bare `node x.js` / `python x.py`
+		// / `./x` are script runs → a repro command. Free prose → expected.
+		if (
+			/^(pytest|jest|vitest|mocha|go test|cargo test|npm (run )?test|npx (vitest|jest|mocha|playwright)|python -m pytest)\b/.test(
+				a,
+			)
+		) {
+			state.failingTest = a;
+		} else if (/^(node|python|python3|\.\/|bash|sh|deno|bun|ruby|php)\b|[|&;><]/.test(a)) {
+			state.reproCommand = a;
+		} else {
+			state.expected = state.expected || a;
+		}
+	}
+	return state;
+}

package/extensions/phi/providers/execution.ts

@@ -0,0 +1,75 @@
+/**
+ * Execution oracle — run real commands and report objective results.
+ *
+ * This is the ground truth the /plan → /debug → /build design turns on: an
+ * accept/reject decision must come from RUNNING code, not from a model reviewing
+ * its own output (see docs/design/plan-debug-build.md). Everything here is thin
+ * and deterministic so the result interpretation can be unit-tested; the spawn
+ * itself is exercised with trivial real commands.
+ */
+
+import { spawnSync } from "node:child_process";
+
+export interface CommandResult {
+	command: string;
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	durationMs: number;
+	timedOut: boolean;
+}
+
+/** A command passed iff it exited 0 and did not time out. */
+export function passed(result: CommandResult): boolean {
+	return result.exitCode === 0 && !result.timedOut;
+}
+
+/** One-line summary for a phase report / handoff. */
+export function summarize(result: CommandResult): string {
+	if (result.timedOut) return `\`${result.command}\` → TIMED OUT after ${Math.round(result.durationMs / 1000)}s`;
+	return `\`${result.command}\` → exit ${result.exitCode ?? "?"} (${Math.round(result.durationMs / 1000)}s)`;
+}
+
+/** Last N lines of the combined output — what a model needs to see to react. */
+export function tail(result: CommandResult, lines = 40): string {
+	const combined = `${result.stdout}\n${result.stderr}`.trimEnd();
+	const all = combined.split("\n");
+	return all.slice(Math.max(0, all.length - lines)).join("\n");
+}
+
+export interface RunOptions {
+	cwd?: string;
+	timeoutMs?: number;
+	env?: NodeJS.ProcessEnv;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run a shell command and capture its result. Never throws — a non-zero exit,
+ * a spawn error, or a timeout all come back as a CommandResult so callers make
+ * decisions from data, not exceptions.
+ */
+export function runCommand(command: string, options: RunOptions = {}): CommandResult {
+	const start = Date.now();
+	const res = spawnSync(command, {
+		cwd: options.cwd,
+		timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		env: options.env ?? process.env,
+		shell: true,
+		encoding: "utf-8",
+		maxBuffer: 32 * 1024 * 1024,
+	});
+	const durationMs = Date.now() - start;
+	// spawnSync sets error with code "ETIMEDOUT" on timeout, and signal SIGTERM.
+	const timedOut = res.error !== undefined && (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+	const spawnFailed = res.error !== undefined && !timedOut;
+	return {
+		command,
+		exitCode: spawnFailed ? null : (res.status ?? (timedOut ? null : null)),
+		stdout: res.stdout ?? "",
+		stderr: spawnFailed ? `${(res.error as Error).message}\n${res.stderr ?? ""}` : (res.stderr ?? ""),
+		durationMs,
+		timedOut,
+	};
+}

package/extensions/phi/providers/orchestrator-helpers.ts

@@ -33,8 +33,20 @@ export function parsePhaseVerdict(content: string): PhaseVerdict | null {
  */
 export function extractSection(content: string, heading: string): string {
 	if (!content) return "";
-	// Header line: optional leading heading hashes and/or bold stars, then the name.
-	const start = new RegExp(`(?:^|\\n)[ \\t]{0,3}(?:#{1,6}[ \\t]*)?\\*{0,2}[ \\t]*${heading}\\b[^\\n]*\\n`, "i");
+	// Header line, in one of three shapes, anchored to line start:
+	//   `## HANDOFF ...`  (markdown heading — trailing text allowed)
+	//   `**HANDOFF**`     (bold label — closing stars, then only trailing space)
+	//   `HANDOFF:` / `HANDOFF` (plain label — must be the whole line or end in ":")
+	// The plain form requires ":" or end-of-line after the name so a prose line
+	// like "Blocking issues remain: 2" is not mistaken for a "BLOCKING" header.
+	const start = new RegExp(
+		`(?:^|\\n)[ \\t]{0,3}(?:` +
+			`#{1,6}[ \\t]*\\*{0,2}[ \\t]*${heading}\\b[^\\n]*` + // heading
+			`|\\*{2}[ \\t]*${heading}[ \\t]*\\*{2}[ \\t]*` + // bold label
+			`|${heading}[ \\t]*:?[ \\t]*` + // plain label (bare or "name:")
+			`)\\n`,
+		"i",
+	);
 	const m = start.exec(content);
 	if (!m) return "";
 	const rest = content.slice(m.index + m[0].length);