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

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/extensions/phi/providers/redteam.ts

@@ -0,0 +1,115 @@
+/**
+ * Executable red-team — the adversary's deliverable is a FAILING RUN, not an
+ * opinion (docs/design/plan-debug-build.md). This is the pure decision core: it
+ * turns the outcome of each adversarial attempt into a loop step, so a "breaking
+ * case" is only ever recorded when a real test went RED. Prose can't lie its way
+ * to a finding here — execution is the oracle.
+ *
+ * Why this exists: in the 3362 measurement an over-clever guard survived a
+ * different model's careful written review because the reviewer shared the
+ * misconception. It would NOT have survived the assertion being *run*. So the
+ * adversary must attack the specific input regime the diff touched, and express
+ * the attack as an executed test.
+ */
+
+import type { FailingState } from "./debug-contract.js";
+import { type CommandResult, passed, tail } from "./execution.js";
+
+/** One adversarial attempt: a runnable test aimed at a specific input regime. */
+export interface RedTeamAttempt {
+	/** Which boundary/regime it targets (e.g. "buffered vs streaming"). */
+	regime: string;
+	/** The runnable breaking test (a command). */
+	test: string;
+	/** The execution of that test (null = it could not be run). */
+	result: CommandResult | null;
+}
+
+/** A confirmed break: an attempt whose test actually ran RED. */
+export interface BreakingCase {
+	regime: string;
+	test: string;
+	symptom: string;
+}
+
+export interface RedTeamState {
+	/** Consecutive rounds that failed to break the code. */
+	dry: number;
+	attemptsUsed: number;
+	breakingCases: BreakingCase[];
+}
+
+export interface RedTeamConfig {
+	/** Stop after this many consecutive rounds that could not break the code. */
+	dryRoundsToStop: number;
+	/** Hard budget on attempts. */
+	maxAttempts: number;
+}
+
+export const DEFAULT_REDTEAM_CONFIG: RedTeamConfig = { dryRoundsToStop: 2, maxAttempts: 8 };
+
+export function initRedTeam(): RedTeamState {
+	return { dry: 0, attemptsUsed: 0, breakingCases: [] };
+}
+
+/** Keep going only while under budget and not yet K dry rounds in a row. */
+export function shouldContinueRedTeam(state: RedTeamState, config: RedTeamConfig): boolean {
+	return state.attemptsUsed < config.maxAttempts && state.dry < config.dryRoundsToStop;
+}
+
+/**
+ * Fold one attempt into the state. A RED run (test failed) is a breaking case
+ * and resets the dry counter; a GREEN run (or one that could not be executed at
+ * all) counts as a dry round — you cannot claim a break you did not run.
+ */
+export function recordAttempt(state: RedTeamState, attempt: RedTeamAttempt, config: RedTeamConfig): RedTeamState {
+	const attemptsUsed = state.attemptsUsed + 1;
+	const ran = attempt.result !== null;
+	const broke = ran && !passed(attempt.result as CommandResult);
+
+	if (broke) {
+		const result = attempt.result as CommandResult;
+		return {
+			dry: 0,
+			attemptsUsed,
+			breakingCases: [
+				...state.breakingCases,
+				{ regime: attempt.regime, test: attempt.test, symptom: tail(result, 20) || `exit ${result.exitCode}` },
+			],
+		};
+	}
+	// Green, or unrunnable: this round produced no finding.
+	void config;
+	return { dry: state.dry + 1, attemptsUsed, breakingCases: state.breakingCases };
+}
+
+/** Turn confirmed breaks into failing states that /debug can consume directly. */
+export function breakingCasesToFailingStates(cases: BreakingCase[], cwd?: string): FailingState[] {
+	return cases.map((c) => ({
+		reproCommand: c.test,
+		trace: c.symptom,
+		expected: `input regime "${c.regime}" must not break the change`,
+		cwd,
+	}));
+}
+
+const STREAMING_HINT = /\b(stream|iter|chunk|read|io|http|response|decode|encode|buffer|socket|pipe)\b/i;
+const PARSE_HINT = /\b(parse|json|yaml|xml|deserialize|decode|token|lexer)\b/i;
+const NUMERIC_HINT = /\b(sum|count|index|offset|length|size|range|price|amount|math|float|int)\b/i;
+const AUTH_HINT = /\b(auth|login|token|session|password|permission|role|jwt)\b/i;
+
+/**
+ * Cheap enumeration of the input regimes worth attacking, given hints from the
+ * change (file names + keywords). Always includes the universal boundaries;
+ * adds domain-specific ones when the hints match. The adversary attacks these,
+ * not the whole app.
+ */
+export function enumerateInputRegimes(hints: { changedFiles?: string[]; keywords?: string } = {}): string[] {
+	const blob = `${(hints.changedFiles ?? []).join(" ")} ${hints.keywords ?? ""}`;
+	const regimes = ["empty input", "null/undefined", "boundary value", "wrong type", "large input"];
+	if (STREAMING_HINT.test(blob)) regimes.push("buffered vs streaming");
+	if (PARSE_HINT.test(blob)) regimes.push("malformed/partial input", "non-ASCII / unicode");
+	if (NUMERIC_HINT.test(blob)) regimes.push("zero / negative", "overflow / very large number");
+	if (AUTH_HINT.test(blob)) regimes.push("missing credentials", "expired / tampered token");
+	return regimes;
+}

package/extensions/phi/providers/triage.ts

@@ -0,0 +1,96 @@
+/**
+ * Triage / adaptive depth — pick the CHEAPEST mode consistent with the signals.
+ *
+ * The measured lesson (docs/design/plan-debug-build.md): the 6–14× overhead of
+ * the full pipeline is only worth paying when a single shot fails the real
+ * oracle. So this classifier defaults to the least machinery and escalates only
+ * on concrete signals — a supplied failing state routes to /debug, a large or
+ * under-specified build routes to /build, everything else is a single shot.
+ */
+
+export type Route = "debug" | "single-shot" | "build" | "plan";
+
+export interface TriageSignals {
+	/** A concrete failing test / trace / repro command was supplied. */
+	hasFailingState?: boolean;
+	/** Rough number of files the task will touch (undefined = estimate from text). */
+	estimatedFiles?: number;
+	/** The task text, for cheap keyword signals. */
+	text?: string;
+	/** Caller forces a specific mode (an explicit /debug, /build, /plan). */
+	forced?: Route;
+	/** Caller wants only a plan artifact, not the execution loop. */
+	planOnly?: boolean;
+}
+
+export interface TriageDecision {
+	route: Route;
+	/** "minimal" = do the least; "full" = the multi-phase pipeline is justified. */
+	depth: "minimal" | "full";
+	reason: string;
+}
+
+const BUILD_KEYWORDS =
+	/\b(build|scaffold|application|app|feature|end[- ]?to[- ]?end|full[- ]?stack|from scratch|new (project|service|module|api|endpoint|component|page)|several files|multiple files)\b/i;
+
+/** At/above this many touched files, a single shot is unlikely to stay coherent. */
+export const MULTI_FILE_THRESHOLD = 3;
+
+/**
+ * Cheap file-count estimate from a request: count distinct path-like tokens.
+ * Deliberately conservative — defaults to 1 when nothing looks like a path.
+ */
+export function estimateFiles(text: string): number {
+	if (!text.trim()) return 1;
+	const paths = new Set<string>();
+	for (const m of text.matchAll(/\b[\w./-]+\.[a-z]{1,6}\b/gi)) {
+		paths.add(m[0].toLowerCase());
+	}
+	return Math.max(1, paths.size);
+}
+
+/**
+ * Map signals to a route + depth. Pure and deterministic: same signals in, same
+ * decision out. Order matters — a forced mode wins, then a real failing state
+ * (cheapest useful oracle), then build-scale, else single shot.
+ */
+export function triage(signals: TriageSignals): TriageDecision {
+	if (signals.forced) {
+		return {
+			route: signals.forced,
+			depth: signals.forced === "single-shot" ? "minimal" : "full",
+			reason: `explicit /${signals.forced}`,
+		};
+	}
+
+	if (signals.hasFailingState) {
+		return {
+			route: "debug",
+			depth: "minimal",
+			reason: "a reproducible failing state was supplied — fix it directly, skip planning",
+		};
+	}
+
+	const text = signals.text ?? "";
+	const files = signals.estimatedFiles ?? estimateFiles(text);
+	const buildy = BUILD_KEYWORDS.test(text);
+	const large = files >= MULTI_FILE_THRESHOLD;
+
+	if (buildy || large) {
+		const why = large ? `~${files} files touched (≥ ${MULTI_FILE_THRESHOLD})` : "build-scale request";
+		if (signals.planOnly) {
+			return {
+				route: "plan",
+				depth: "full",
+				reason: `${why}; plan-only requested — decompose without the run loop`,
+			};
+		}
+		return { route: "build", depth: "full", reason: `${why} — decompose and run the build→verify→debug loop` };
+	}
+
+	return {
+		route: "single-shot",
+		depth: "minimal",
+		reason: "small, self-contained — try one shot and verify before escalating",
+	};
+}

package/package.json

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