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

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## [0.88.0] - 2026-07-10
+
+### Changed
+
+- **The /plan phase contract is now structured-primary with a text fallback**
+  (see `docs/adr/0001-phase-contract.md`). A phase agent CALLS a new
+  `phase_result` tool to emit its verdict / blocking / handoff as data;
+  `resolvePhaseOutcome` merges that structured emission field-by-field with the
+  regex-scraped markdown report, preferring the structured value. TEST and
+  REVIEW are instructed to call it. When a model does not call the tool,
+  behavior is identical to the previous text-only path — the change cannot make
+  any run worse. This replaces "regex luck" with an exact machine-read path for
+  the control-flow-critical signals (verdict, BLOCKED, the review-fix cycle).
+
+### Added
+
+- **End-to-end integration test of the orchestrator.** The real orchestrator
+  extension is now driven through a full multi-phase run against a simulated Pi
+  runtime (`test/orchestrator-integration.test.ts`): phase progression, handoff
+  propagation, the review-FAIL → fix → re-review cycle, and the BLOCKED pause
+  are all exercised together, not just the pure decision function. (Scripted
+  phase outcomes — deterministic, no live model.)
+- **An eval harness** (`evals/`) — the measurement infrastructure that did not
+  exist. Tasks with deterministic pass/fail verifiers, a runnable baseline
+  strategy (`npx tsx evals/run.ts`), unit-tested scoring/aggregation
+  (`test/evals-lib.test.ts`), and a demonstrated real run (2/2 baseline tasks on
+  a live model). `evals/README.md` documents the methodology and is honest that
+  the /plan-vs-baseline head-to-head is not yet a single number.
+- **Two ADRs** documenting the phase-contract decision and the independent-review
+  release gate (`docs/adr/`).
+
+### Fixed
+
+- Bugs found by an **independent adversarial review** of the phase-contract
+  change (see `docs/adr/0002-independent-review.md`), each now pinned by a
+  regression test:
+  - **State leak between runs**: `currentPhaseResult` was reset only in
+    `sendNextPhase`, but the first phase of each `/plan` run launches directly —
+    a stale structured result (e.g. a BLOCKED verdict) from a previous run could
+    abort a fresh run at phase 1. Reset on every run start + a phase-identity
+    stamp so a stale/late result is never mistaken for the current phase.
+  - **Field erasure on multi-call**: a second `phase_result` call replaced the
+    whole object, wiping a verdict set by the first; it now merges only the
+    fields each call sets.
+  - **Dead text fallback for PLAN/CODE**: `readPhaseReport` looked for
+    `<key>-<ts>.md` but PLAN writes `todo-<ts>.md` and CODE `progress-<ts>.md`,
+    so their handoff blocks were never read. Mapped key → report file.
+  - **`extractSection` over-matching**: a prose line starting with a section
+    word (e.g. "Blocking issues remain: 2") could be read as that section's
+    header. The plain-label form now requires `:` or end-of-line.
+- A TEST/REVIEW phase that finished with tool work but emitted no verdict at all
+  (neither structured nor a VERDICT line) is now surfaced instead of silently
+  passing.
+- **The eval runner** had two Windows bugs its first real run caught: temp-dir
+  cleanup raced `EPERM` (now retries), and `shell:true` with an args array
+  mangled the prompt (now a single quoted command string).
+
+### Tooling
+
+- Biome now also lints `evals/`.
+
 ## [0.87.0] - 2026-07-10
 
 ### Added

package/docs/adr/0001-phase-contract.md

@@ -0,0 +1,57 @@
+# ADR 0001 — Structured-primary phase contract for /plan
+
+Status: accepted (2026-07-10)
+
+## Context
+
+The /plan orchestrator chains five agent phases (explore → plan → code → test
+→ review). Each phase must report two things the orchestrator acts on:
+
+- a **verdict** (TEST/REVIEW): PASS / FAIL / BLOCKED / SKIP, and
+- a **handoff** (+ BLOCKING findings for REVIEW) carried to the next phase.
+
+Originally this was communicated **only** as markdown the model wrote to
+`.phi/plans/<phase>-<ts>.md`, which the orchestrator scraped with regexes
+(`## VERDICT:`, `## HANDOFF`, `## BLOCKING`). That is fragile: models phrase
+headers inconsistently (`**HANDOFF**`, `HANDOFF:`, mid-sentence "verdict"), and
+a mis-scrape silently degrades control flow — a missed REVIEW FAIL skips the fix
+cycle; a missed BLOCKED keeps a doomed run going. The original justification for
+text-only was that the upstream proxy did not guarantee valid structured tool
+output.
+
+## Decision
+
+Keep the markdown report (it is the human-readable artifact) but make the
+**machine-read path structured and primary**:
+
+- The orchestrator registers a `phase_result` tool. TEST and REVIEW phases are
+  instructed to call it with `{verdict, blocking, handoff}`; any phase may call
+  it to hand off.
+- `resolvePhaseOutcome(structured, reportText)` (pure, unit-tested) merges the
+  two sources **field by field**, preferring the structured value and falling
+  back to the regex-scraped report per field. When the model calls the tool the
+  outcome is exact; when it does not, behavior is byte-for-byte the pre-existing
+  text path.
+- The text parser was hardened anyway (`extractSection` accepts heading, bold,
+  and plain-label forms) so the fallback is as robust as possible.
+
+## Why not go structured-only
+
+Two reasons the text path stays as a fallback rather than being removed:
+
+1. **Provider variance.** Not every provider/proxy reliably emits tool calls on
+   every turn; a model that writes a good report but forgets the tool call must
+   still drive the pipeline correctly.
+2. **Zero-regression migration.** Making structured additive means the change
+   cannot make any existing run worse — the worst case equals the old behavior.
+
+## Consequences
+
+- Robustness of control flow (verdict/BLOCKED/fix-cycle) now depends on a
+  structured emission when available, not on regex luck.
+- Two code paths must stay in sync; `resolvePhaseOutcome` centralizes the merge
+  and is covered by unit tests, and `orchestrator-integration.test.ts` drives
+  the whole chain via the structured path.
+- Follow-up (not done here): once telemetry shows the structured path is taken
+  reliably across the providers phi ships, the text fallback can be demoted to a
+  warning-only safety net.

package/docs/adr/0002-independent-review.md

@@ -0,0 +1,47 @@
+# ADR 0002 — Independent adversarial review as a release gate
+
+Status: accepted (2026-07-10)
+
+## Context
+
+phi-code is largely built by a single author, who is also the only reviewer.
+Self-review misses the bugs the author's mental model is blind to — the code
+does what the author *thinks* it does, and they test that. There is no external
+human reviewer on hand for every change.
+
+## Decision
+
+Before shipping a non-trivial change to a load-bearing subsystem (the /plan
+orchestrator, the model/provider layer, compaction, the extension runtime), run
+an **independent adversarial review**: a reviewer with fresh context that did
+not write the code, prompted to *refute* — to find state leaks, races, contract
+mismatches, and edge cases — not to approve.
+
+Findings are triaged (verify each against the code, discard false positives),
+the real ones are fixed, and each fix is pinned with a regression test before
+the change ships.
+
+## Evidence this works
+
+The structured-phase-contract change (ADR 0001) passed the author's own unit
+and integration tests. An independent review of that change then found four
+real defects the author's tests missed:
+
+- a structured result leaking from one `/plan` run into the next (a stale
+  BLOCKED verdict could abort a fresh run at phase 1);
+- a second `phase_result` call erasing fields set by the first;
+- no phase-identity guard against a late tool call landing after a transition;
+- the text HANDOFF fallback being dead for two phases due to a report-file name
+  mismatch.
+
+All four are now fixed and covered by regression tests
+(`orchestrator-integration.test.ts`, `phase-machine.test.ts`).
+
+## Consequences
+
+- "Green tests" is necessary but not sufficient for a load-bearing change; an
+  independent refutation pass is part of the definition of done.
+- The reviewer need not be human to be useful — it needs to be *independent of
+  the authoring context* and prompted adversarially. This is not a substitute
+  for real external users, whose absence remains an honest limitation of the
+  project's validation.

package/extensions/phi/orchestrator.ts

@@ -24,8 +24,13 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "phi-code";
 import { type AgentDef, loadAgentDef } from "./providers/agent-def.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";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -309,11 +314,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 */
@@ -658,6 +737,7 @@ After implementation, use \`memory_write\` to save a summary of what was built,
    - 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 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
@@ -731,6 +811,7 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
    - **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 +925,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 +1047,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);
@@ -1063,13 +1155,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 +1220,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 +1245,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 +1313,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 +1379,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;
 

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);

package/extensions/phi/providers/phase-machine.ts

@@ -13,7 +13,13 @@
  *   > continue (with diagnostics).
  */
 
-import { isTransientError, type PhaseVerdict } from "./orchestrator-helpers.js";
+import {
+	extractBlockingFindings,
+	extractHandoff,
+	isTransientError,
+	type PhaseVerdict,
+	parsePhaseVerdict,
+} from "./orchestrator-helpers.js";
 
 export interface PhaseEndAnalysis {
 	userAborted: boolean;
@@ -177,16 +183,65 @@ export interface PhaseDecisionInput {
 	analysis: PhaseEndAnalysis;
 	/** Currently executing phase, or null when the queue raced. */
 	phase: { key: string; retried?: boolean } | null;
-	/** Verdict parsed from the phase's report file (null = absent/unparseable). */
+	/** Resolved verdict (structured phase_result or parsed report; null = none). */
 	verdict: PhaseVerdict | null;
-	/** Whether a report file existed at all for this phase. */
-	hasReport: boolean;
 	/** Completed review-fix cycles so far (bounded to one). */
 	reviewFixRounds: number;
 	maxToolCallsPerPhase: number;
 }
 
-/** Phases whose contract REQUIRES a leading "VERDICT:" line in their report. */
+/**
+ * Structured phase result: what a phase agent emits by CALLING the
+ * `phase_result` tool (robust primary path), instead of only writing markdown
+ * that has to be regex-scraped (fragile fallback). All fields optional — a
+ * partial structured emission is merged field-by-field with the parsed report.
+ */
+export interface StructuredPhaseResult {
+	verdict?: PhaseVerdict;
+	blocking?: string;
+	handoff?: string;
+}
+
+export interface EffectivePhaseOutcome {
+	verdict: PhaseVerdict | null;
+	blocking: string;
+	handoff: string;
+	/** Where each resolved field came from — for diagnostics and tests. */
+	source: "structured" | "text" | "mixed" | "none";
+}
+
+/**
+ * Resolve a phase's effective outcome, preferring the structured tool emission
+ * and falling back to the regex-scraped markdown report per field. This is the
+ * heart of the "structured primary, text fallback" contract: when the model
+ * calls phase_result the outcome is exact; when it doesn't, behavior is
+ * identical to the pure-text path that shipped before.
+ */
+export function resolvePhaseOutcome(
+	structured: StructuredPhaseResult | null,
+	reportText: string | null,
+): EffectivePhaseOutcome {
+	const textVerdict = reportText ? parsePhaseVerdict(reportText) : null;
+	const textBlocking = reportText ? extractBlockingFindings(reportText) : "";
+	const textHandoff = reportText ? extractHandoff(reportText) : "";
+
+	const verdict = structured?.verdict ?? textVerdict;
+	const blocking = structured?.blocking?.trim() || textBlocking;
+	const handoff = structured?.handoff?.trim() || textHandoff;
+
+	const usedStructured = Boolean(
+		structured && (structured.verdict || structured.blocking?.trim() || structured.handoff?.trim()),
+	);
+	const usedText = Boolean(textVerdict || textBlocking || textHandoff);
+	let source: EffectivePhaseOutcome["source"] = "none";
+	if (usedStructured && usedText) source = "mixed";
+	else if (usedStructured) source = "structured";
+	else if (usedText) source = "text";
+
+	return { verdict, blocking, handoff, source };
+}
+
+/** Phases whose contract REQUIRES a verdict (structured or a leading VERDICT: line). */
 const VERDICT_PHASES = new Set(["test", "review"]);
 
 /**
@@ -194,7 +249,7 @@ const VERDICT_PHASES = new Set(["test", "review"]);
  * caller interprets the decision (notifications, queue edits, checkpoints).
  */
 export function decidePhaseTransition(input: PhaseDecisionInput): PhaseDecision {
-	const { analysis, phase, verdict, hasReport, reviewFixRounds, maxToolCallsPerPhase } = input;
+	const { analysis, phase, verdict, reviewFixRounds, maxToolCallsPerPhase } = input;
 
 	if (analysis.userAborted) return { action: "stop", reason: "user-abort" };
 	if (analysis.hasAuthError) return { action: "stop", reason: "auth-error" };
@@ -212,9 +267,17 @@ export function decidePhaseTransition(input: PhaseDecisionInput): PhaseDecision
 		return { action: "review-fix-cycle" };
 	}
 
+	// A TEST/REVIEW phase must produce a verdict (structured phase_result is
+	// mandatory for them, with the report's VERDICT line as fallback). If it
+	// completed with tool work but no verdict either way, that is a contract
+	// deviation worth surfacing — not silently passing. The zero-tool-call case
+	// has its own warning, so exclude it here to avoid a double warning.
+	const missingVerdict =
+		phase !== null && VERDICT_PHASES.has(phase.key) && verdict === null && analysis.toolCallCount > 0;
+
 	return {
 		action: "continue",
 		zeroToolCalls: analysis.toolCallCount === 0,
-		missingVerdict: phase !== null && VERDICT_PHASES.has(phase.key) && hasReport && verdict === null,
+		missingVerdict,
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.87.0",
+	"version": "0.88.0",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {