ultimate-pi 0.14.0 → 0.16.0

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;
+	}
+}

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

@@ -5,32 +5,21 @@
 import { constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { isHarnessBudgetEnforceOn } from "../../lib/harness-budget-enforce.js";
+import { capsForDebate } from "./debate-bus-core.js";
+import {
+	getPlanFocusCoverage,
+	type PlanDebateFocus,
+	planDebateOutcomeComplete,
+} from "./plan-debate-focus.js";
 import { planDebateIdForRun } from "./plan-debate-id.js";
+import { laneArtifactPathsForRound } from "./plan-debate-lanes.js";
 import {
 	getMessengerRoundState,
 	loadMessengerState,
 	messengerRoundDebateReady,
 } from "./plan-messenger.js";
 
-const PLAN_ROUNDS = 4;
-const FOCUS_BY_ROUND = ["spec", "wbs", "schedule", "quality"] as const;
-
-function laneFilesForRound(roundIndex: number): string[] {
-	const n = roundIndex;
-	const lanes = [
-		`artifacts/validation-turn-r${n}.yaml`,
-		`artifacts/adversary-brief-r${n}.yaml`,
-	];
-	if (n === 1) {
-		lanes.unshift(`artifacts/hypothesis-validation-r${n}.yaml`);
-	}
-	if (n === 4) {
-		lanes.push(`artifacts/sprint-audit-r${n}.yaml`);
-	}
-	lanes.push(`artifacts/review-round-r${n}.yaml`);
-	return lanes;
-}
-
 async function fileExists(path: string): Promise<boolean> {
 	try {
 		await access(path, constants.R_OK);
@@ -64,6 +53,12 @@ export interface PlanDebateGateResult {
 	errors: string[];
 	warnings: string[];
 	debateId: string;
+	focus_coverage?: {
+		covered: string[];
+		missing: string[];
+		last_review_gate_ready: boolean;
+	};
+	debate_profile?: string;
 }
 
 export async function validatePlanDebateGate(
@@ -75,16 +70,47 @@ export async function validatePlanDebateGate(
 	const debateId = planDebateIdForRun(runId);
 	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
 	const debatesDir = join(projectRoot, ".pi", "harness", "debates");
+	const messenger = await loadMessengerState(runDir);
+	const debateProfile = messenger?.debate_profile ?? "standard";
+	const requiredFocuses: readonly PlanDebateFocus[] =
+		messenger?.required_focuses && messenger.required_focuses.length > 0
+			? messenger.required_focuses
+			: (["spec", "wbs", "schedule", "quality"] as const);
+	const caps = capsForDebate(debateId, debateProfile);
+	const coverage = await getPlanFocusCoverage(runDir, { requiredFocuses });
+	const dialogueOpts = {
+		max_exchanges_per_round: caps.max_exchanges_per_round,
+	};
 
-	for (let r = 1; r <= PLAN_ROUNDS; r++) {
-		for (const rel of laneFilesForRound(r)) {
+	for (const focus of coverage.missing) {
+		errors.push(`focus not covered in submitted rounds: ${focus}`);
+	}
+	if (!coverage.last_review_gate_ready) {
+		errors.push("last submitted review round has review_gate_ready !== true");
+	}
+
+	const roundIndices = [
+		...new Set(
+			Object.values(coverage.rounds_by_focus).filter(
+				(v): v is number => typeof v === "number",
+			),
+		),
+	];
+	for (const r of roundIndices) {
+		const focus = coverage.focus_by_round[r] ?? null;
+		for (const rel of laneArtifactPathsForRound(r, focus)) {
 			const abs = join(runDir, rel);
 			if (!(await fileExists(abs))) {
 				errors.push(`missing ${rel}`);
 			}
 		}
 		const roundState = await getMessengerRoundState(runDir, r);
-		const messengerCheck = messengerRoundDebateReady(roundState, r === 4);
+		const requireSprint = focus === "quality" || r >= 4;
+		const messengerCheck = messengerRoundDebateReady(
+			roundState,
+			requireSprint,
+			dialogueOpts,
+		);
 		if (!messengerCheck.ok) {
 			for (const e of messengerCheck.errors) {
 				errors.push(`round ${r} messenger: ${e}`);
@@ -92,7 +118,22 @@ export async function validatePlanDebateGate(
 		}
 	}
 
-	const messenger = await loadMessengerState(runDir);
+	if (
+		isHarnessBudgetEnforceOn() &&
+		coverage.last_round_index > caps.max_rounds
+	) {
+		errors.push(
+			`round_count ${coverage.last_round_index} exceeds max_rounds ${caps.max_rounds}`,
+		);
+	} else if (
+		!isHarnessBudgetEnforceOn() &&
+		coverage.last_round_index > caps.max_rounds
+	) {
+		warnings.push(
+			`round_count ${coverage.last_round_index} exceeds advisory max_rounds ${caps.max_rounds} (budget enforce off)`,
+		);
+	}
+
 	if (!messenger) {
 		errors.push(
 			"debate-messenger/state.json missing — call harness_debate_open",
@@ -103,9 +144,10 @@ export async function validatePlanDebateGate(
 
 	const jsonlPath = join(debatesDir, `${debateId}.jsonl`);
 	const { rounds, hasConsensus } = await countJsonlKinds(jsonlPath);
-	if (rounds < PLAN_ROUNDS) {
+	const minRounds = caps.min_focus_rounds;
+	if (rounds < minRounds) {
 		errors.push(
-			`${debateId}.jsonl has ${rounds}/${PLAN_ROUNDS} round events — use harness_debate_submit_round each round`,
+			`${debateId}.jsonl has ${rounds}/${minRounds} minimum round events — use harness_debate_submit_round per focus`,
 		);
 	}
 	if (!hasConsensus) {
@@ -114,6 +156,17 @@ export async function validatePlanDebateGate(
 		);
 	}
 
+	if (
+		!planDebateOutcomeComplete(coverage, {
+			requiredFocuses,
+			minRoundIndex: caps.min_focus_rounds,
+		})
+	) {
+		errors.push(
+			`debate outcome incomplete: required focuses [${requiredFocuses.join(", ")}] with last review_gate_ready true (profile=${debateProfile})`,
+		);
+	}
+
 	const consensusPath = join(debatesDir, `${debateId}.consensus.json`);
 	if (!(await fileExists(consensusPath))) {
 		errors.push(`missing ${debateId}.consensus.json`);
@@ -129,15 +182,10 @@ export async function validatePlanDebateGate(
 		}
 	}
 
-	for (let r = 0; r < FOCUS_BY_ROUND.length; r++) {
-		const focus = FOCUS_BY_ROUND[r];
-		const reviewPath = join(runDir, `artifacts/review-round-r${r + 1}.yaml`);
-		if (await fileExists(reviewPath)) {
-			const raw = await readFile(reviewPath, "utf-8");
-			if (!raw.includes(focus)) {
-				warnings.push(`review-round-r${r + 1} may not match focus ${focus}`);
-			}
-		}
+	if (rounds > caps.max_rounds) {
+		warnings.push(
+			`bus round count ${rounds} exceeds soft max_rounds ${caps.max_rounds}`,
+		);
 	}
 
 	return {
@@ -145,6 +193,12 @@ export async function validatePlanDebateGate(
 		errors,
 		warnings,
 		debateId,
+		focus_coverage: {
+			covered: coverage.covered,
+			missing: coverage.missing,
+			last_review_gate_ready: coverage.last_review_gate_ready,
+		},
+		debate_profile: debateProfile,
 	};
 }
 

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

@@ -45,6 +45,21 @@ export function laneArtifactPath(
 	}
 }
 
+/** Apply messenger side effects when artifact YAML was already written via submit tool. */
+export async function applyDebateLaneFromDoc(opts: {
+	runDir: string;
+	lane: DebateLaneKind;
+	doc: Record<string, unknown>;
+	roundIndex?: number;
+}): Promise<ApplyDebateLaneResult> {
+	return applyDebateLane({
+		runDir: opts.runDir,
+		lane: opts.lane,
+		content: JSON.stringify(opts.doc),
+		roundIndex: opts.roundIndex,
+	});
+}
+
 export function extractClaimIds(doc: Record<string, unknown>): string[] {
 	const explicit = doc.messenger_claim_ids;
 	if (Array.isArray(explicit)) {

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

@@ -0,0 +1,44 @@
+/**
+ * Shared Review Gate lane list for a round (gate + round-status).
+ */
+
+import type { PlanDebateFocus } from "./plan-debate-focus.js";
+import type { DebateLaneKind } from "./plan-debate-lane.js";
+
+/** Lanes required before review-integrator for this round. */
+export function lanesForRound(
+	roundIndex: number,
+	debateRoundFocus?: PlanDebateFocus | null,
+): DebateLaneKind[] {
+	const lanes: DebateLaneKind[] = ["validation-turn", "adversary-brief"];
+	if (roundIndex === 1) {
+		lanes.unshift("hypothesis-validation");
+	}
+	if (roundIndex >= 4 || debateRoundFocus === "quality") {
+		lanes.push("sprint-audit");
+	}
+	return lanes;
+}
+
+/** Relative artifact paths for lane YAML + review-round. */
+export function laneArtifactPathsForRound(
+	roundIndex: number,
+	debateRoundFocus?: PlanDebateFocus | null,
+): string[] {
+	const paths = lanesForRound(roundIndex, debateRoundFocus).map((lane) => {
+		switch (lane) {
+			case "hypothesis-validation":
+				return `artifacts/hypothesis-validation-r${roundIndex}.yaml`;
+			case "validation-turn":
+				return `artifacts/validation-turn-r${roundIndex}.yaml`;
+			case "adversary-brief":
+				return `artifacts/adversary-brief-r${roundIndex}.yaml`;
+			case "sprint-audit":
+				return `artifacts/sprint-audit-r${roundIndex}.yaml`;
+			default:
+				return `artifacts/${lane}-r${roundIndex}.yaml`;
+		}
+	});
+	paths.push(`artifacts/review-round-r${roundIndex}.yaml`);
+	return paths;
+}