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

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/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.88.0",
+	"version": "0.89.0",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {