ultimate-pi 0.14.0 → 0.15.0

package/.pi/extensions/harness-plan-approval.ts

@@ -2,6 +2,9 @@
  * harness-plan-approval — PlanPacket approval UI and transcript renderer for parent sessions.
  */
 
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -146,6 +149,43 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				`Plan ${planId} — pending your approval`;
 			const runCtx = getLatestRunContext(entries);
 			const projectRoot = process.cwd();
+			const implWarnings: string[] = [];
+			if (runCtx?.run_id) {
+				const implPath = join(
+					projectRoot,
+					".pi",
+					"harness",
+					"runs",
+					runCtx.run_id,
+					"artifacts",
+					"implementation-research.yaml",
+				);
+				let implExists = false;
+				try {
+					await access(implPath, constants.R_OK);
+					implExists = true;
+				} catch {
+					implExists = false;
+				}
+				const risk = String(
+					validated.plan_packet.risk_level ?? "med",
+				).toLowerCase();
+				if (!implExists) {
+					const msg =
+						"approve_plan: missing artifacts/implementation-research.yaml (Phase 3.5 required)";
+					if (risk === "high") {
+						return {
+							content: [{ type: "text", text: msg }],
+							details: {
+								plan_packet: validated.plan_packet,
+								cancelled: true,
+							},
+							isError: true,
+						};
+					}
+					implWarnings.push(msg);
+				}
+			}
 			if (runCtx?.run_id) {
 				const gate = await validatePlanDebateGate(projectRoot, runCtx.run_id);
 				if (!gate.ok) {
@@ -237,13 +277,15 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				);
 			}
 
-			const text = formatApprovePlanResultText(
-				outcome.response,
-				outcome.cancelled,
-			);
+			const text = [
+				formatApprovePlanResultText(outcome.response, outcome.cancelled),
+				...implWarnings,
+			]
+				.filter(Boolean)
+				.join("\n\n");
 			return {
 				content: [{ type: "text", text }],
-				details,
+				details: { ...details, implementation_warnings: implWarnings },
 			};
 		},
 

package/.pi/extensions/lib/debate-bus-core.ts

@@ -19,6 +19,17 @@ import {
 	setDebateState,
 	setLastSeverity,
 } from "./debate-bus-state.js";
+import {
+	type DebateProfile,
+	PLAN_BUDGET_LIGHT,
+	PLAN_BUDGET_STANDARD,
+} from "./plan-debate-eligibility.js";
+import {
+	getPlanFocusCoverage,
+	PLAN_FOCUS_AREAS,
+	type PlanDebateFocus,
+	planDebateOutcomeComplete,
+} from "./plan-debate-focus.js";
 
 export type PolicyDecision =
 	| "pass"
@@ -66,11 +77,7 @@ const THRESHOLDS = {
 };
 const HARD_STOP_DEBATE_CAPS = process.env.HARNESS_DEBATE_HARD_STOP === "true";
 
-const PLAN_BUDGET = {
-	max_rounds: 4,
-	round_token_cap: 2000,
-	debate_global_cap: 12000,
-} as const;
+const PLAN_BUDGET = PLAN_BUDGET_STANDARD;
 
 const AGGRESSIVE_BUDGET = {
 	max_rounds: 6,
@@ -88,16 +95,28 @@ function toSafeFloat(value: unknown): number {
 	return Math.max(0, Math.min(1, n));
 }
 
-export function capsForDebate(debateId: string): {
+export function capsForDebate(
+	debateId: string,
+	profile?: DebateProfile,
+): {
 	name: "plan" | "aggressive";
+	min_focus_rounds: number;
 	max_rounds: number;
+	max_exchanges_per_round: number;
 	round_token_cap: number;
 	debate_global_cap: number;
 } {
 	if (isPlanDebateId(debateId)) {
-		return { name: "plan", ...PLAN_BUDGET };
+		const active = profile ?? getDebateState()?.debate_profile ?? "standard";
+		const budget = active === "light" ? PLAN_BUDGET_LIGHT : PLAN_BUDGET;
+		return { name: "plan", ...budget };
 	}
-	return { name: "aggressive", ...AGGRESSIVE_BUDGET };
+	return {
+		name: "aggressive",
+		min_focus_rounds: 1,
+		max_exchanges_per_round: 1,
+		...AGGRESSIVE_BUDGET,
+	};
 }
 
 function participantAllowed(
@@ -161,23 +180,40 @@ export interface DebateBusHooks {
 	appendEntry: (customType: string, data: unknown) => void;
 }
 
+export interface OpenDebateBusOptions {
+	debate_profile?: DebateProfile;
+	required_focuses?: DebateState["required_focuses"];
+}
+
 export async function openDebateBus(
 	runId: string,
 	debateId: string,
 	hooks: DebateBusHooks,
+	opts?: OpenDebateBusOptions,
 ): Promise<DebateState> {
-	const caps = capsForDebate(debateId);
+	const profile = opts?.debate_profile ?? "standard";
+	const caps = capsForDebate(debateId, profile);
 	const debate_phase = debatePhaseFromId(debateId);
+	const defaultFocuses: PlanDebateFocus[] =
+		profile === "light" ? ["spec", "quality"] : [...PLAN_FOCUS_AREAS];
+	const required_focuses =
+		opts?.required_focuses && opts.required_focuses.length > 0
+			? opts.required_focuses
+			: defaultFocuses;
 	const next: DebateState = {
 		run_id: runId,
 		debate_id: debateId,
 		debate_phase,
 		round_count: 0,
 		budget_used: 0,
+		min_focus_rounds: caps.min_focus_rounds,
 		max_rounds: caps.max_rounds,
+		max_exchanges_per_round: caps.max_exchanges_per_round,
 		round_token_cap: caps.round_token_cap,
 		debate_global_cap: caps.debate_global_cap,
 		last_review_gate_ready: false,
+		debate_profile: profile,
+		required_focuses,
 	};
 	setDebateState(next);
 	setLastSeverity({
@@ -199,6 +235,8 @@ export async function openDebateBus(
 			opened_at: nowIso(),
 			debate_phase,
 			budget_profile: caps.name,
+			debate_profile: profile,
+			required_focuses,
 		},
 	};
 	hooks.appendEntry("harness-debate-envelope", envelope);
@@ -230,7 +268,9 @@ async function emitBudgetExhausted(
 			budget_used: state.budget_used,
 			exhaustion_reason: reason,
 			caps: {
+				min_focus_rounds: state.min_focus_rounds,
 				max_rounds: state.max_rounds,
+				max_exchanges_per_round: state.max_exchanges_per_round,
 				round_token_cap: state.round_token_cap,
 				debate_global_cap: state.debate_global_cap,
 			},
@@ -327,7 +367,9 @@ export async function acceptDebateRound(
 		token_usage: envelope.payload.token_usage,
 		budget_profile: {
 			name: profileName,
+			min_focus_rounds: state.min_focus_rounds,
 			max_rounds: state.max_rounds,
+			max_exchanges_per_round: state.max_exchanges_per_round,
 			round_token_cap: state.round_token_cap,
 			debate_global_cap: state.debate_global_cap,
 		},
@@ -363,12 +405,24 @@ export async function finalizeDebateConsensus(
 	);
 	const decision = decidePolicy(lastSeverity, evidenceScore);
 	const planPhase = state.debate_phase === "plan";
-	const evaluatorPassed = planPhase
-		? Boolean(state.last_review_gate_ready)
-		: true;
-	const debateComplete = planPhase
-		? state.round_count >= state.max_rounds
-		: state.round_count > 0;
+	let evaluatorPassed = true;
+	let debateComplete = state.round_count > 0;
+	if (planPhase) {
+		const runDir = join(process.cwd(), ".pi", "harness", "runs", state.run_id);
+		const requiredFocuses =
+			state.required_focuses && state.required_focuses.length > 0
+				? state.required_focuses
+				: undefined;
+		const coverage = await getPlanFocusCoverage(runDir, {
+			requiredFocuses,
+		});
+		evaluatorPassed =
+			coverage.last_review_gate_ready || Boolean(state.last_review_gate_ready);
+		debateComplete = planDebateOutcomeComplete(coverage, {
+			requiredFocuses,
+			minRoundIndex: state.min_focus_rounds,
+		});
+	}
 
 	const consensus = {
 		schema_version: "1.0.0",

package/.pi/extensions/lib/debate-bus-state.ts

@@ -3,6 +3,8 @@
  */
 
 import type { DebateParticipant } from "../../lib/debate-orchestrator-types.js";
+import type { DebateProfile } from "./plan-debate-eligibility.js";
+import type { PlanDebateFocus } from "./plan-debate-focus.js";
 
 export type DebatePhase = "plan" | "post_execute";
 
@@ -12,10 +14,14 @@ export interface DebateState {
 	debate_phase: DebatePhase;
 	round_count: number;
 	budget_used: number;
+	min_focus_rounds: number;
 	max_rounds: number;
+	max_exchanges_per_round: number;
 	round_token_cap: number;
 	debate_global_cap: number;
 	last_review_gate_ready?: boolean;
+	debate_profile?: DebateProfile;
+	required_focuses?: PlanDebateFocus[];
 }
 
 export interface SeverityScores {

package/.pi/extensions/lib/plan-approval/plan-review.ts

@@ -160,6 +160,62 @@ export function formatResearchBriefMarkdown(
 		}
 	}
 
+	const impl = asRecord(research.implementation);
+	if (impl) {
+		lines.push("## Phase 3.5 — Implementation research");
+		lines.push("");
+		const framing = str(impl.problem_framing);
+		if (framing) {
+			lines.push("**Problem framing:**");
+			lines.push("");
+			lines.push(framing);
+			lines.push("");
+		}
+		const rec = asRecord(impl.recommended_approach);
+		if (rec) {
+			const summary = str(rec.summary);
+			const conf = str(rec.recommended_approach_confidence);
+			if (summary) {
+				lines.push(
+					`**Recommended approach**${conf ? ` (${conf} confidence)` : ""}:`,
+				);
+				lines.push("");
+				lines.push(summary);
+				lines.push("");
+			}
+			const rationale = str(rec.confidence_rationale);
+			if (rationale) {
+				lines.push(`*Rationale:* ${rationale}`);
+				lines.push("");
+			}
+		}
+		const patterns = Array.isArray(impl.solution_patterns)
+			? impl.solution_patterns
+			: [];
+		if (patterns.length) {
+			lines.push("**Solution patterns:**");
+			for (const p of patterns) {
+				const pat = asRecord(p);
+				const name = pat ? str(pat.name) : null;
+				const fit = pat ? str(pat.fit) : null;
+				if (name) lines.push(`- **${name}**${fit ? `: ${fit}` : ""}`);
+			}
+			lines.push("");
+		}
+		const openQs = strList(impl.open_questions);
+		if (openQs.length) {
+			lines.push("**Open questions:**");
+			for (const q of openQs) lines.push(`- ${q}`);
+			lines.push("");
+		}
+		const anti = strList(impl.anti_patterns);
+		if (anti.length) {
+			lines.push("**Anti-patterns:**");
+			for (const a of anti) lines.push(`- ${a}`);
+			lines.push("");
+		}
+	}
+
 	if (evalBrief) {
 		lines.push("## Self-evaluation");
 		lines.push("");

package/.pi/extensions/lib/plan-approval/types.ts

@@ -13,6 +13,7 @@ export interface PlanResearchBrief {
 	hypothesis?: Record<string, unknown> | null;
 	eval?: Record<string, unknown> | null;
 	stack?: Record<string, unknown> | null;
+	implementation?: Record<string, unknown> | null;
 	debate?: {
 		rounds?: Record<string, unknown>[];
 		hypothesis_validations?: Record<string, unknown>[];

package/.pi/extensions/lib/plan-debate-eligibility.ts

@@ -0,0 +1,214 @@
+/**
+ * Pre-debate profile selection (full | standard | light).
+ */
+
+import { PLAN_FOCUS_AREAS, type PlanDebateFocus } from "./plan-debate-focus.js";
+
+export type DebateProfile = "full" | "standard" | "light";
+
+export interface DebateEligibilityInput {
+	risk_level?: string;
+	material_fork?: boolean;
+	dag_pass?: boolean;
+	dag_manually_patched?: boolean;
+	implementation_brief?: Record<string, unknown> | null;
+	stack_brief?: Record<string, unknown> | null;
+	decomposition?: Record<string, unknown> | null;
+}
+
+export interface DebateEligibilityResult {
+	profile: DebateProfile;
+	required_focuses: PlanDebateFocus[];
+	min_focus_rounds: number;
+	max_rounds: number;
+	max_exchanges_per_round: number;
+	round_token_cap: number;
+	debate_global_cap: number;
+	human_required: boolean;
+	rationale: string[];
+}
+
+const LIGHT_FOCUS: PlanDebateFocus[] = ["spec", "quality"];
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function strList(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.map((item) => (typeof item === "string" ? item.trim() : ""))
+		.filter(Boolean);
+}
+
+function implementationOpenQuestions(
+	brief: Record<string, unknown> | null,
+): string[] {
+	if (!brief) return [];
+	return strList(brief.open_questions);
+}
+
+function recommendedApproach(
+	brief: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+	return asRecord(brief?.recommended_approach);
+}
+
+function stackHasClearPrimary(stack: Record<string, unknown> | null): boolean {
+	if (!stack) return false;
+	const primary = stack.recommended_primary;
+	return typeof primary === "string" && primary.trim().length > 0;
+}
+
+function confidenceAllowsLight(brief: Record<string, unknown> | null): boolean {
+	const rec = recommendedApproach(brief);
+	if (!rec) return false;
+	const conf = String(rec.recommended_approach_confidence ?? "").toLowerCase();
+	if (conf !== "high") return false;
+	const rationale =
+		typeof rec.confidence_rationale === "string"
+			? rec.confidence_rationale.trim()
+			: "";
+	const refs = strList(rec.evidence_refs);
+	if (!rationale || refs.length < 2) return false;
+	if (implementationOpenQuestions(brief).length > 0) return false;
+	const patterns = Array.isArray(brief?.solution_patterns)
+		? (brief!.solution_patterns as unknown[])
+		: [];
+	for (const p of patterns) {
+		const pat = asRecord(p);
+		const risks = pat ? strList(pat.risks) : [];
+		if (risks.some((r) => /unmitigated|critical|blocker/i.test(r))) {
+			return false;
+		}
+	}
+	const similar = Array.isArray(brief?.similar_implementations)
+		? (brief!.similar_implementations as unknown[])
+		: [];
+	if (similar.length === 0) return false;
+	return true;
+}
+
+function decompositionTensionCount(
+	decomposition: Record<string, unknown> | null,
+): number {
+	if (!decomposition) return 0;
+	return Array.isArray(decomposition.tensions)
+		? decomposition.tensions.length
+		: 0;
+}
+
+export const PLAN_BUDGET_STANDARD = {
+	min_focus_rounds: 4,
+	max_rounds: 12,
+	max_exchanges_per_round: 3,
+	round_token_cap: 8000,
+	debate_global_cap: 80000,
+} as const;
+
+export const PLAN_BUDGET_LIGHT = {
+	min_focus_rounds: 2,
+	max_rounds: 8,
+	max_exchanges_per_round: 3,
+	round_token_cap: 6000,
+	debate_global_cap: 40000,
+} as const;
+
+function capsForProfile(
+	profile: DebateProfile,
+): Omit<
+	DebateEligibilityResult,
+	"profile" | "required_focuses" | "human_required" | "rationale"
+> {
+	if (profile === "light") {
+		return {
+			...PLAN_BUDGET_LIGHT,
+		};
+	}
+	return {
+		...PLAN_BUDGET_STANDARD,
+	};
+}
+
+/**
+ * Select debate profile from pre-debate signals only (no R1 hypothesis output).
+ */
+export function harnessPlanDebateEligibility(
+	input: DebateEligibilityInput,
+): DebateEligibilityResult {
+	const rationale: string[] = [];
+	const risk = String(input.risk_level ?? "med").toLowerCase();
+	const impl = input.implementation_brief ?? null;
+	const stack = input.stack_brief ?? null;
+	const openQs = implementationOpenQuestions(impl);
+	const materialFork = input.material_fork === true;
+	const dagPatched = input.dag_manually_patched === true;
+	const dagFail = input.dag_pass === false;
+
+	let human_required = false;
+
+	if (dagFail) {
+		rationale.push("DAG validation failed — use standard profile until fixed");
+	}
+
+	if (openQs.length > 0) {
+		rationale.push(
+			`implementation open_questions (${openQs.length}) — not eligible for light`,
+		);
+	}
+
+	const conflictingPatterns =
+		Array.isArray(impl?.solution_patterns) &&
+		(impl!.solution_patterns as unknown[]).length >= 2 &&
+		openQs.length > 0;
+	if (conflictingPatterns) {
+		human_required = true;
+		rationale.push("conflicting external patterns with open questions");
+	}
+
+	let profile: DebateProfile = "standard";
+	rationale.push("default profile: standard (fail-safe)");
+
+	if (
+		risk === "high" ||
+		materialFork ||
+		openQs.length > 0 ||
+		dagPatched ||
+		decompositionTensionCount(input.decomposition ?? null) >= 3
+	) {
+		profile = "full";
+		rationale.push(
+			"full: high risk, material fork, open questions, DAG patch, or tensions",
+		);
+	} else if (
+		risk === "low" &&
+		!materialFork &&
+		!dagPatched &&
+		input.dag_pass !== false &&
+		confidenceAllowsLight(impl) &&
+		stackHasClearPrimary(stack)
+	) {
+		profile = "light";
+		rationale.push(
+			"light: low risk, clear stack, high-confidence implementation approach",
+		);
+	} else if (risk === "med") {
+		profile = "standard";
+		rationale.push("standard: med risk default");
+	}
+
+	const required_focuses: PlanDebateFocus[] =
+		profile === "light" ? [...LIGHT_FOCUS] : [...PLAN_FOCUS_AREAS];
+
+	const caps = capsForProfile(profile);
+
+	return {
+		profile,
+		required_focuses,
+		...caps,
+		human_required,
+		rationale,
+	};
+}

package/.pi/extensions/lib/plan-debate-focus.ts

@@ -0,0 +1,151 @@
+/**
+ * Plan-phase Review Gate focus coverage (spec | wbs | schedule | quality).
+ */
+
+import { constants } from "node:fs";
+import { access, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export const PLAN_FOCUS_AREAS = ["spec", "wbs", "schedule", "quality"] as const;
+export type PlanDebateFocus = (typeof PLAN_FOCUS_AREAS)[number];
+
+export interface PlanFocusCoverage {
+	covered: PlanDebateFocus[];
+	missing: PlanDebateFocus[];
+	rounds_by_focus: Partial<Record<PlanDebateFocus, number>>;
+	focus_by_round: Partial<Record<number, PlanDebateFocus>>;
+	last_review_gate_ready: boolean;
+	last_round_index: number;
+}
+
+export interface PlanFocusCoverageOptions {
+	requiredFocuses?: readonly PlanDebateFocus[];
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function focusFromDraft(
+	draft: Record<string, unknown>,
+): PlanDebateFocus | null {
+	const focus = String(draft.debate_round_focus ?? "").trim();
+	if ((PLAN_FOCUS_AREAS as readonly string[]).includes(focus)) {
+		return focus as PlanDebateFocus;
+	}
+	return null;
+}
+
+/**
+ * Scan submitted review-round artifacts for focus coverage and last gate flag.
+ */
+export async function getPlanFocusCoverage(
+	runDir: string,
+	opts?: PlanFocusCoverageOptions,
+): Promise<PlanFocusCoverage> {
+	const required =
+		opts?.requiredFocuses && opts.requiredFocuses.length > 0
+			? opts.requiredFocuses
+			: PLAN_FOCUS_AREAS;
+	const artifactsDir = join(runDir, "artifacts");
+	const covered = new Set<PlanDebateFocus>();
+	const rounds_by_focus: Partial<Record<PlanDebateFocus, number>> = {};
+	const focus_by_round: Partial<Record<number, PlanDebateFocus>> = {};
+	let last_review_gate_ready = false;
+	let last_round_index = 0;
+
+	let files: string[] = [];
+	try {
+		files = (await readdir(artifactsDir)).filter((f) =>
+			/^review-round-r\d+\.yaml$/i.test(f),
+		);
+	} catch {
+		return {
+			covered: [],
+			missing: [...required],
+			rounds_by_focus: {},
+			focus_by_round: {},
+			last_review_gate_ready: false,
+			last_round_index: 0,
+		};
+	}
+
+	for (const name of files.sort()) {
+		const m = /^review-round-r(\d+)\.yaml$/i.exec(name);
+		if (!m) continue;
+		const roundIndex = Number(m[1]);
+		if (roundIndex > last_round_index) last_round_index = roundIndex;
+		const raw = await readFile(join(artifactsDir, name), "utf-8");
+		let draft: Record<string, unknown>;
+		try {
+			draft = parseYaml(raw) as Record<string, unknown>;
+		} catch {
+			continue;
+		}
+		const focus = focusFromDraft(draft);
+		if (focus) {
+			covered.add(focus);
+			rounds_by_focus[focus] = roundIndex;
+			focus_by_round[roundIndex] = focus;
+		}
+		if (roundIndex === last_round_index) {
+			last_review_gate_ready = draft.review_gate_ready === true;
+		}
+	}
+
+	const coveredList = required.filter((f) => covered.has(f));
+	const missing = required.filter((f) => !covered.has(f));
+
+	return {
+		covered: coveredList,
+		missing,
+		rounds_by_focus,
+		focus_by_round,
+		last_review_gate_ready,
+		last_round_index,
+	};
+}
+
+export interface PlanDebateOutcomeOptions {
+	requiredFocuses?: readonly PlanDebateFocus[];
+	minRoundIndex?: number;
+}
+
+export function planDebateOutcomeComplete(
+	coverage: PlanFocusCoverage,
+	opts?: PlanDebateOutcomeOptions,
+): boolean {
+	const required =
+		opts?.requiredFocuses && opts.requiredFocuses.length > 0
+			? opts.requiredFocuses
+			: PLAN_FOCUS_AREAS;
+	const minRounds = opts?.minRoundIndex ?? required.length;
+	const missing = required.filter((f) => !coverage.covered.includes(f));
+	return (
+		missing.length === 0 &&
+		coverage.last_review_gate_ready === true &&
+		coverage.last_round_index >= minRounds
+	);
+}
+
+/** Read debate_round_focus from an existing review-round artifact. */
+export async function readDebateRoundFocus(
+	runDir: string,
+	roundIndex: number,
+): Promise<PlanDebateFocus | null> {
+	const path = join(runDir, "artifacts", `review-round-r${roundIndex}.yaml`);
+	if (!(await fileExists(path))) return null;
+	try {
+		const raw = await readFile(path, "utf-8");
+		const draft = parseYaml(raw) as Record<string, unknown>;
+		return focusFromDraft(draft);
+	} catch {
+		return null;
+	}
+}