ultimate-pi 0.13.1 → 0.15.0

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

@@ -0,0 +1,220 @@
+/**
+ * Persist plan debate lane YAML + pi-messenger side effects from subagent output.
+ */
+
+import { constants } from "node:fs";
+import { access, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+	parseStructuredDocument,
+	writeYamlFile,
+} from "../../lib/harness-yaml.js";
+import { postMessengerMessage } from "./plan-messenger.js";
+
+export type DebateLaneKind =
+	| "hypothesis-validation"
+	| "validation-turn"
+	| "adversary-brief"
+	| "sprint-audit";
+
+const AGENT_LANE: Record<string, DebateLaneKind> = {
+	"harness/planning/hypothesis-validator": "hypothesis-validation",
+	"harness/planning/plan-evaluator": "validation-turn",
+	"harness/planning/plan-adversary": "adversary-brief",
+	"harness/planning/sprint-contract-auditor": "sprint-audit",
+};
+
+export function debateLaneForAgent(agent: string): DebateLaneKind | null {
+	const normalized = agent.replace(/^\.pi\/agents\//, "").trim();
+	return AGENT_LANE[normalized] ?? null;
+}
+
+export function laneArtifactPath(
+	lane: DebateLaneKind,
+	roundIndex: number,
+): string {
+	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`;
+	}
+}
+
+export function extractClaimIds(doc: Record<string, unknown>): string[] {
+	const explicit = doc.messenger_claim_ids;
+	if (Array.isArray(explicit)) {
+		return explicit.filter(
+			(x): x is string => typeof x === "string" && x.length > 0,
+		);
+	}
+	const checks = doc.checks;
+	if (!Array.isArray(checks)) return [];
+	return checks
+		.map((c) => (c as { id?: string }).id)
+		.filter((id): id is string => typeof id === "string" && id.length > 0);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export interface ApplyDebateLaneResult {
+	ok: boolean;
+	lane: DebateLaneKind;
+	round_index: number;
+	artifact_path: string;
+	messenger_posted: boolean;
+	errors: string[];
+	next_step?: string;
+}
+
+export async function applyDebateLane(opts: {
+	runDir: string;
+	lane: DebateLaneKind;
+	content: string;
+	roundIndex?: number;
+}): Promise<ApplyDebateLaneResult> {
+	const errors: string[] = [];
+	let doc: Record<string, unknown>;
+	try {
+		doc = parseStructuredDocument(opts.content, opts.lane) as Record<
+			string,
+			unknown
+		>;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			lane: opts.lane,
+			round_index: opts.roundIndex ?? 0,
+			artifact_path: "",
+			messenger_posted: false,
+			errors: [msg],
+		};
+	}
+
+	const roundIndex =
+		typeof doc.round_index === "number"
+			? doc.round_index
+			: (opts.roundIndex ?? 1);
+	const relPath = laneArtifactPath(opts.lane, roundIndex);
+	const absPath = join(opts.runDir, relPath);
+	await mkdir(dirname(absPath), { recursive: true });
+	await writeYamlFile(absPath, doc);
+
+	let messengerPosted = false;
+	let nextStep: string | undefined;
+
+	if (opts.lane === "validation-turn") {
+		const claimIds = extractClaimIds(doc);
+		const body =
+			(typeof doc.human_summary === "string" && doc.human_summary.trim()) ||
+			claimIds.map((id) => `Check ${id}`).join("; ") ||
+			"Plan evaluator claims for this round.";
+		if (claimIds.length === 0) {
+			errors.push(
+				"validation-turn has no claim ids (checks[].id or messenger_claim_ids)",
+			);
+		} else {
+			await postMessengerMessage(opts.runDir, {
+				from: "PlanEvaluatorAgent",
+				kind: "claim",
+				round_index: roundIndex,
+				to: ["broadcast"],
+				body,
+				claim_ids: claimIds,
+				in_reply_to: [],
+				evidence_refs: [relPath],
+				artifact_path: relPath,
+			});
+			messengerPosted = true;
+			nextStep = `Spawn plan-adversary with harness_messenger_read_round({ round_index: ${roundIndex} }) transcript, then harness_debate_apply_lane for adversary output.`;
+		}
+	}
+
+	if (opts.lane === "adversary-brief") {
+		const turnPath = join(
+			opts.runDir,
+			laneArtifactPath("validation-turn", roundIndex),
+		);
+		let inReplyTo: string[] = [];
+		if (await fileExists(turnPath)) {
+			const { readFile } = await import("node:fs/promises");
+			const { parse: parseYaml } = await import("yaml");
+			const turn = parseYaml(await readFile(turnPath, "utf-8")) as Record<
+				string,
+				unknown
+			>;
+			inReplyTo = extractClaimIds(turn);
+		}
+		if (inReplyTo.length === 0) {
+			errors.push(
+				"no claim ids to rebut — validation-turn-rN must exist before adversary",
+			);
+		} else {
+			const body =
+				(typeof doc.human_summary === "string" && doc.human_summary.trim()) ||
+				(Array.isArray(doc.failure_modes) && doc.failure_modes[0]) ||
+				"Adversary rebuttal for evaluator claims.";
+			await postMessengerMessage(opts.runDir, {
+				from: "PlanAdversaryAgent",
+				kind: "rebuttal",
+				round_index: roundIndex,
+				to: ["broadcast"],
+				body: String(body),
+				claim_ids: [],
+				in_reply_to: inReplyTo,
+				evidence_refs: [relPath],
+				artifact_path: relPath,
+			});
+			messengerPosted = true;
+			nextStep = `Spawn review-integrator with harness_messenger_read_round({ round_index: ${roundIndex} }) + lane artifacts, then harness_debate_submit_round.`;
+		}
+	}
+
+	return {
+		ok: errors.length === 0,
+		lane: opts.lane,
+		round_index: roundIndex,
+		artifact_path: relPath,
+		messenger_posted: messengerPosted,
+		errors,
+		next_step: nextStep,
+	};
+}
+
+export function formatApplyLaneMessage(result: ApplyDebateLaneResult): string {
+	if (!result.ok) {
+		return `Lane ${result.lane} failed:\n- ${result.errors.join("\n- ")}`;
+	}
+	const parts = [
+		`Wrote ${result.artifact_path}`,
+		result.messenger_posted
+			? "messenger updated"
+			: "no messenger post for this lane",
+	];
+	if (result.next_step) parts.push(`Next: ${result.next_step}`);
+	return parts.join("\n");
+}
+
+export const DEBATE_LANE_AGENT_ORDER: Array<{
+	lane: DebateLaneKind;
+	agent: string;
+}> = [
+	{
+		lane: "hypothesis-validation",
+		agent: "harness/planning/hypothesis-validator",
+	},
+	{ lane: "validation-turn", agent: "harness/planning/plan-evaluator" },
+	{ lane: "adversary-brief", agent: "harness/planning/plan-adversary" },
+];

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

package/.pi/extensions/lib/plan-debate-round-status.ts

@@ -0,0 +1,137 @@
+/**
+ * Round-level debate readiness for parent orchestration.
+ */
+
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { capsForDebate } from "./debate-bus-core.js";
+import {
+	type PlanDebateFocus,
+	readDebateRoundFocus,
+} from "./plan-debate-focus.js";
+import { planDebateIdForRun } from "./plan-debate-id.js";
+import { laneArtifactPath } from "./plan-debate-lane.js";
+import { lanesForRound } from "./plan-debate-lanes.js";
+import {
+	getMessengerRoundState,
+	loadMessengerState,
+	messengerRoundDialogueReady,
+} from "./plan-messenger.js";
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export interface RoundStatusResult {
+	round_index: number;
+	/** Lane YAML + messenger dialogue complete; spawn integrator next. */
+	ready_for_integrator: boolean;
+	/** review-round-rN.yaml on disk (call harness_debate_submit_round if bus not updated). */
+	review_round_on_disk: boolean;
+	missing: string[];
+	next_tool?: string;
+	messenger: { ok: boolean; errors: string[] };
+	dialogue: { ok: boolean; errors: string[] };
+	unresolved_claim_ids: string[];
+	exchange_count: number;
+	debate_round_focus?: PlanDebateFocus | null;
+}
+
+export async function getPlanDebateRoundStatus(
+	runDir: string,
+	roundIndex: number,
+	runId?: string,
+	opts?: { debate_round_focus?: PlanDebateFocus },
+): Promise<RoundStatusResult> {
+	const focus =
+		opts?.debate_round_focus ??
+		(await readDebateRoundFocus(runDir, roundIndex));
+	const missing: string[] = [];
+	for (const lane of lanesForRound(roundIndex, focus)) {
+		const rel = laneArtifactPath(lane, roundIndex);
+		if (!(await exists(join(runDir, rel)))) {
+			missing.push(rel);
+		}
+	}
+	const messengerState = await loadMessengerState(runDir);
+	const profile = messengerState?.debate_profile;
+	const caps = capsForDebate(
+		runId ? planDebateIdForRun(runId) : `plan-${runId ?? "unknown"}`,
+		profile,
+	);
+	const roundState = await getMessengerRoundState(runDir, roundIndex);
+	const dialogueOpts = {
+		max_exchanges_per_round: caps.max_exchanges_per_round,
+	};
+	const dialogue = messengerRoundDialogueReady(roundState, dialogueOpts);
+	if (!dialogue.ok) {
+		missing.push(...dialogue.errors.map((e) => `messenger: ${e}`));
+	}
+	const reviewRound = `artifacts/review-round-r${roundIndex}.yaml`;
+	const reviewRoundOnDisk = await exists(join(runDir, reviewRound));
+
+	let next_tool: string | undefined;
+	if (missing.some((m) => m.includes("hypothesis-validation"))) {
+		next_tool = "subagent harness/planning/hypothesis-validator";
+	} else if (missing.some((m) => m.includes("validation-turn"))) {
+		next_tool = "subagent harness/planning/plan-evaluator";
+	} else if (
+		missing.some((m) => m.includes("adversary-brief")) &&
+		!roundState?.evaluator_posted
+	) {
+		next_tool = "subagent harness/planning/plan-evaluator";
+	} else if (missing.some((m) => m.includes("adversary-brief"))) {
+		next_tool =
+			"harness_messenger_read_round then subagent harness/planning/plan-adversary";
+	} else if (missing.some((m) => m.includes("sprint-audit"))) {
+		next_tool = "subagent harness/planning/sprint-contract-auditor";
+	} else if (
+		roundState &&
+		roundState.evaluator_posted &&
+		!roundState.adversary_posted
+	) {
+		next_tool =
+			"harness_messenger_read_round then subagent harness/planning/plan-adversary";
+	} else if (
+		roundState &&
+		roundState.unresolved_claim_ids.length > 0 &&
+		roundState.exchange_count < caps.max_exchanges_per_round
+	) {
+		const spawnEvaluator = roundState.exchange_count % 2 === 1;
+		next_tool = spawnEvaluator
+			? "harness_debate_advance_thread → harness_messenger_read_round → subagent harness/planning/plan-evaluator (clarification; address unresolved claim_ids)"
+			: "harness_debate_advance_thread → harness_messenger_read_round → subagent harness/planning/plan-adversary (counter or concede)";
+	} else if (!dialogue.ok) {
+		next_tool =
+			"harness_debate_advance_thread or harness_debate_apply_lane (evaluator/adversary)";
+	} else if (!reviewRoundOnDisk) {
+		next_tool =
+			"subagent harness/planning/review-integrator then harness_debate_submit_round";
+	} else {
+		next_tool =
+			"harness_debate_submit_round with integrator draft from review-round file";
+	}
+
+	const laneMissing = missing.filter((m) => !m.startsWith("messenger"));
+	const readyForIntegrator =
+		dialogue.ok && laneMissing.length === 0 && !reviewRoundOnDisk;
+
+	return {
+		round_index: roundIndex,
+		ready_for_integrator: readyForIntegrator,
+		review_round_on_disk: reviewRoundOnDisk,
+		missing,
+		next_tool,
+		messenger: dialogue,
+		dialogue,
+		unresolved_claim_ids: roundState?.unresolved_claim_ids ?? [],
+		exchange_count: roundState?.exchange_count ?? 0,
+		debate_round_focus: focus,
+	};
+}

package/.pi/extensions/lib/plan-debate-write-guard.ts

@@ -0,0 +1,20 @@
+/**
+ * P0 — only harness_debate_submit_round may write review-round-r*.yaml via write_harness_yaml.
+ */
+
+let reviewRoundWriteDepth = 0;
+
+export function isReviewRoundYamlWriteAllowed(): boolean {
+	return reviewRoundWriteDepth > 0;
+}
+
+export async function withReviewRoundYamlWrite<T>(
+	fn: () => Promise<T>,
+): Promise<T> {
+	reviewRoundWriteDepth += 1;
+	try {
+		return await fn();
+	} finally {
+		reviewRoundWriteDepth -= 1;
+	}
+}