ultimate-pi 0.13.1 → 0.15.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-envelope.ts

@@ -51,6 +51,7 @@ export function buildPlanReviewRoundEnvelope(
 		token_usage: { per_agent: Record<string, number>; round_total: number };
 		consensus_delta: number;
 		severity_scores?: PlanReviewRoundDraft["severity_scores"];
+		review_gate_ready?: boolean;
 	};
 } {
 	const participants = (draft.participants ?? [
@@ -79,6 +80,7 @@ export function buildPlanReviewRoundEnvelope(
 			},
 			consensus_delta: draft.consensus_delta ?? 0,
 			severity_scores: draft.severity_scores,
+			review_gate_ready: draft.review_gate_ready,
 		},
 	};
 }

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

@@ -0,0 +1,198 @@
+/**
+ * P0 — plan debate artifact + bus gates before approve_plan.
+ */
+
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+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";
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function countJsonlKinds(
+	debateJsonlPath: string,
+): Promise<{ rounds: number; hasConsensus: boolean }> {
+	try {
+		const raw = await readFile(debateJsonlPath, "utf-8");
+		let rounds = 0;
+		let hasConsensus = false;
+		for (const line of raw.split("\n")) {
+			if (!line.trim()) continue;
+			const ev = JSON.parse(line) as { kind?: string };
+			if (ev.kind === "round") rounds += 1;
+			if (ev.kind === "consensus") hasConsensus = true;
+		}
+		return { rounds, hasConsensus };
+	} catch {
+		return { rounds: 0, hasConsensus: false };
+	}
+}
+
+export interface PlanDebateGateResult {
+	ok: boolean;
+	errors: string[];
+	warnings: string[];
+	debateId: string;
+	focus_coverage?: {
+		covered: string[];
+		missing: string[];
+		last_review_gate_ready: boolean;
+	};
+	debate_profile?: string;
+}
+
+export async function validatePlanDebateGate(
+	projectRoot: string,
+	runId: string,
+): Promise<PlanDebateGateResult> {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	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 (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 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}`);
+			}
+		}
+	}
+
+	if (coverage.last_round_index > caps.max_rounds) {
+		errors.push(
+			`round_count ${coverage.last_round_index} exceeds max_rounds ${caps.max_rounds}`,
+		);
+	}
+
+	if (!messenger) {
+		errors.push(
+			"debate-messenger/state.json missing — call harness_debate_open",
+		);
+	} else if (messenger.debate_id !== debateId) {
+		errors.push(`messenger debate_id ${messenger.debate_id} !== ${debateId}`);
+	}
+
+	const jsonlPath = join(debatesDir, `${debateId}.jsonl`);
+	const { rounds, hasConsensus } = await countJsonlKinds(jsonlPath);
+	const minRounds = caps.min_focus_rounds;
+	if (rounds < minRounds) {
+		errors.push(
+			`${debateId}.jsonl has ${rounds}/${minRounds} minimum round events — use harness_debate_submit_round per focus`,
+		);
+	}
+	if (!hasConsensus) {
+		errors.push(
+			`missing consensus on ${debateId} — call harness_debate_consensus`,
+		);
+	}
+
+	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`);
+	} else {
+		try {
+			const raw = await readFile(consensusPath, "utf-8");
+			const packet = JSON.parse(raw) as { policy_decision?: string };
+			if (packet.policy_decision === "block") {
+				errors.push("consensus policy_decision is block — cannot approve");
+			}
+		} catch {
+			errors.push("invalid consensus json");
+		}
+	}
+
+	if (rounds > caps.max_rounds) {
+		warnings.push(
+			`bus round count ${rounds} exceeds soft max_rounds ${caps.max_rounds}`,
+		);
+	}
+
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings,
+		debateId,
+		focus_coverage: {
+			covered: coverage.covered,
+			missing: coverage.missing,
+			last_review_gate_ready: coverage.last_review_gate_ready,
+		},
+		debate_profile: debateProfile,
+	};
+}
+
+export function isReviewRoundArtifactPath(relPath: string): boolean {
+	return /^artifacts\/review-round-r\d+\.yaml$/i.test(
+		relPath.replace(/\\/g, "/"),
+	);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Canonical plan-phase debate identifiers (ADR-0035).
+ */
+
+export function planDebateIdForRun(runId: string): string {
+	const trimmed = runId.trim();
+	if (!trimmed) throw new Error("run_id is required for plan debate");
+	return `plan-${trimmed}`;
+}
+
+/** Accept plan-<run_id> only; rewrite plan-<plan_id> when run_id is known. */
+export function normalizePlanDebateId(
+	rawDebateId: string,
+	runId: string,
+): { debateId: string; corrected: boolean; warning?: string } {
+	const trimmed = rawDebateId.trim();
+	const canonical = planDebateIdForRun(runId);
+	if (!trimmed) {
+		return { debateId: canonical, corrected: true, warning: "empty debate id" };
+	}
+	if (trimmed === canonical) {
+		return { debateId: canonical, corrected: false };
+	}
+	if (trimmed.startsWith("plan-") && trimmed !== canonical) {
+		return {
+			debateId: canonical,
+			corrected: true,
+			warning: `debate id must be plan-<run_id>; got ${trimmed}, using ${canonical}`,
+		};
+	}
+	if (!trimmed.startsWith("plan-")) {
+		return {
+			debateId: trimmed,
+			corrected: false,
+			warning: "non-plan debate id (post-execute profile)",
+		};
+	}
+	return { debateId: trimmed, corrected: false };
+}