ultimate-pi 0.13.1 → 0.14.0

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

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-round-status.ts

@@ -0,0 +1,94 @@
+/**
+ * Round-level debate readiness for parent orchestration.
+ */
+
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { type DebateLaneKind, laneArtifactPath } from "./plan-debate-lane.js";
+import {
+	getMessengerRoundState,
+	messengerRoundDebateReady,
+} from "./plan-messenger.js";
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function lanesForRound(roundIndex: number): DebateLaneKind[] {
+	const lanes: DebateLaneKind[] = ["validation-turn", "adversary-brief"];
+	if (roundIndex === 1) lanes.unshift("hypothesis-validation");
+	if (roundIndex === 4) lanes.push("sprint-audit");
+	return lanes;
+}
+
+export interface RoundStatusResult {
+	round_index: number;
+	/** Lane YAML + messenger thread 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[] };
+}
+
+export async function getPlanDebateRoundStatus(
+	runDir: string,
+	roundIndex: number,
+): Promise<RoundStatusResult> {
+	const missing: string[] = [];
+	for (const lane of lanesForRound(roundIndex)) {
+		const rel = laneArtifactPath(lane, roundIndex);
+		if (!(await exists(join(runDir, rel)))) {
+			missing.push(rel);
+		}
+	}
+	const roundState = await getMessengerRoundState(runDir, roundIndex);
+	const messenger = messengerRoundDebateReady(roundState, roundIndex === 4);
+	if (!messenger.ok) {
+		missing.push(...messenger.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"))) {
+		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 (!messenger.ok) {
+		next_tool =
+			"harness_debate_apply_lane (evaluator/adversary) or re-spawn lane agent";
+	} 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 readyForIntegrator =
+		messenger.ok &&
+		missing.filter((m) => !m.startsWith("messenger")).length === 0 &&
+		!reviewRoundOnDisk;
+
+	return {
+		round_index: roundIndex,
+		ready_for_integrator: readyForIntegrator,
+		review_round_on_disk: reviewRoundOnDisk,
+		missing,
+		next_tool,
+		messenger,
+	};
+}

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

package/.pi/extensions/lib/plan-messenger.ts

@@ -0,0 +1,276 @@
+/**
+ * pi-messenger-style plan debate transport — per-agent inboxes + round threads.
+ *
+ * Layout under `.pi/harness/runs/<run_id>/debate-messenger/`:
+ *   inbox/<AgentLabel>/<seq>-<kind>.json
+ *   threads/round-<N>/transcript.jsonl
+ *   state.json
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+	appendFile,
+	mkdir,
+	readdir,
+	readFile,
+	writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import type { DebateParticipant } from "../../lib/debate-orchestrator-types.js";
+
+export type MessengerMessageKind =
+	| "system"
+	| "claim"
+	| "rebuttal"
+	| "integrate"
+	| "audit";
+
+export interface MessengerMessage {
+	schema_version: "1.0.0";
+	id: string;
+	ts: string;
+	from: DebateParticipant | "system";
+	to: Array<DebateParticipant | "broadcast">;
+	kind: MessengerMessageKind;
+	round_index: number;
+	in_reply_to: string[];
+	body: string;
+	claim_ids: string[];
+	evidence_refs: string[];
+	artifact_path?: string;
+}
+
+export interface MessengerRoundState {
+	round_index: number;
+	evaluator_posted: boolean;
+	adversary_posted: boolean;
+	integrator_posted: boolean;
+	claim_count: number;
+	rebuttal_count: number;
+}
+
+export interface MessengerState {
+	schema_version: "1.0.0";
+	run_id: string;
+	debate_id: string;
+	opened_at: string;
+	rounds: Record<string, MessengerRoundState>;
+}
+
+function messengerRoot(runDir: string): string {
+	return join(runDir, "debate-messenger");
+}
+
+function nowIso(): string {
+	return new Date().toISOString();
+}
+
+function roundKey(roundIndex: number): string {
+	return String(roundIndex);
+}
+
+export async function initPlanMessenger(
+	runDir: string,
+	opts: { runId: string; debateId: string },
+): Promise<string> {
+	const root = messengerRoot(runDir);
+	await mkdir(join(root, "inbox"), { recursive: true });
+	await mkdir(join(root, "threads"), { recursive: true });
+	const state: MessengerState = {
+		schema_version: "1.0.0",
+		run_id: opts.runId,
+		debate_id: opts.debateId,
+		opened_at: nowIso(),
+		rounds: {},
+	};
+	await writeFile(
+		join(root, "state.json"),
+		`${JSON.stringify(state, null, 2)}\n`,
+		"utf-8",
+	);
+	return root;
+}
+
+export async function loadMessengerState(
+	runDir: string,
+): Promise<MessengerState | null> {
+	const path = join(messengerRoot(runDir), "state.json");
+	try {
+		const raw = await readFile(path, "utf-8");
+		return JSON.parse(raw) as MessengerState;
+	} catch {
+		return null;
+	}
+}
+
+async function saveMessengerState(
+	runDir: string,
+	state: MessengerState,
+): Promise<void> {
+	await writeFile(
+		join(messengerRoot(runDir), "state.json"),
+		`${JSON.stringify(state, null, 2)}\n`,
+		"utf-8",
+	);
+}
+
+function defaultRoundState(roundIndex: number): MessengerRoundState {
+	return {
+		round_index: roundIndex,
+		evaluator_posted: false,
+		adversary_posted: false,
+		integrator_posted: false,
+		claim_count: 0,
+		rebuttal_count: 0,
+	};
+}
+
+export async function postMessengerMessage(
+	runDir: string,
+	msg: Omit<MessengerMessage, "schema_version" | "id" | "ts"> & {
+		id?: string;
+		ts?: string;
+	},
+): Promise<MessengerMessage> {
+	const root = messengerRoot(runDir);
+	const full: MessengerMessage = {
+		schema_version: "1.0.0",
+		id: msg.id ?? randomUUID(),
+		ts: msg.ts ?? nowIso(),
+		from: msg.from,
+		to: msg.to,
+		kind: msg.kind,
+		round_index: msg.round_index,
+		in_reply_to: msg.in_reply_to ?? [],
+		body: msg.body,
+		claim_ids: msg.claim_ids ?? [],
+		evidence_refs: msg.evidence_refs ?? [],
+		artifact_path: msg.artifact_path,
+	};
+
+	const inboxDir = join(root, "inbox", full.from);
+	await mkdir(inboxDir, { recursive: true });
+	const inboxName = `${full.round_index.toString().padStart(2, "0")}-${full.kind}-${full.id.slice(0, 8)}.json`;
+	await writeFile(
+		join(inboxDir, inboxName),
+		`${JSON.stringify(full, null, 2)}\n`,
+	);
+
+	const threadDir = join(root, "threads", `round-${full.round_index}`);
+	await mkdir(threadDir, { recursive: true });
+	await appendFile(
+		join(threadDir, "transcript.jsonl"),
+		`${JSON.stringify(full)}\n`,
+		"utf-8",
+	);
+
+	const state = (await loadMessengerState(runDir)) ?? {
+		schema_version: "1.0.0",
+		run_id: "",
+		debate_id: "",
+		opened_at: nowIso(),
+		rounds: {},
+	};
+	const key = roundKey(full.round_index);
+	const round = state.rounds[key] ?? defaultRoundState(full.round_index);
+	if (full.from === "PlanEvaluatorAgent" && full.kind === "claim") {
+		round.evaluator_posted = true;
+		round.claim_count += full.claim_ids.length || 1;
+	}
+	if (full.from === "PlanAdversaryAgent" && full.kind === "rebuttal") {
+		round.adversary_posted = true;
+		round.rebuttal_count += full.in_reply_to.length || 1;
+	}
+	if (full.from === "ReviewIntegratorAgent" && full.kind === "integrate") {
+		round.integrator_posted = true;
+	}
+	state.rounds[key] = round;
+	await saveMessengerState(runDir, state);
+	return full;
+}
+
+export async function readRoundTranscript(
+	runDir: string,
+	roundIndex: number,
+): Promise<MessengerMessage[]> {
+	const path = join(
+		messengerRoot(runDir),
+		"threads",
+		`round-${roundIndex}`,
+		"transcript.jsonl",
+	);
+	try {
+		const raw = await readFile(path, "utf-8");
+		return raw
+			.split("\n")
+			.filter((line) => line.trim())
+			.map((line) => JSON.parse(line) as MessengerMessage);
+	} catch {
+		return [];
+	}
+}
+
+export function formatTranscriptForSpawn(
+	messages: MessengerMessage[],
+	maxChars = 12000,
+): string {
+	const lines = messages.map((m) => {
+		const reply =
+			m.in_reply_to.length > 0 ? ` (re: ${m.in_reply_to.join(", ")})` : "";
+		const claims = m.claim_ids.length > 0 ? ` [${m.claim_ids.join(", ")}]` : "";
+		return `[${m.from}/${m.kind}${claims}${reply}] ${m.body}`;
+	});
+	let text = lines.join("\n\n");
+	if (text.length > maxChars) {
+		text = `${text.slice(0, maxChars)}\n\n…(transcript truncated)`;
+	}
+	return text || "(empty thread — post evaluator claims before adversary)";
+}
+
+export async function getMessengerRoundState(
+	runDir: string,
+	roundIndex: number,
+): Promise<MessengerRoundState | null> {
+	const state = await loadMessengerState(runDir);
+	if (!state) return null;
+	return state.rounds[roundKey(roundIndex)] ?? null;
+}
+
+export function messengerRoundDebateReady(
+	round: MessengerRoundState | null,
+	_requireSprintAudit: boolean,
+): { ok: boolean; errors: string[] } {
+	const errors: string[] = [];
+	if (!round) {
+		errors.push("no messenger activity for this round");
+		return { ok: false, errors };
+	}
+	if (!round.evaluator_posted) {
+		errors.push("PlanEvaluatorAgent has not posted claims to the thread");
+	}
+	if (!round.adversary_posted) {
+		errors.push("PlanAdversaryAgent has not posted rebuttals to the thread");
+	}
+	if (round.claim_count < 1) {
+		errors.push("round thread has no claim_ids");
+	}
+	if (round.rebuttal_count < 1) {
+		errors.push("adversary must rebut at least one claim (in_reply_to)");
+	}
+	if (!round.integrator_posted) {
+		errors.push(
+			"ReviewIntegratorAgent must post integrate message before bus submit",
+		);
+	}
+	return { ok: errors.length === 0, errors };
+}
+
+export async function listInboxAgents(runDir: string): Promise<string[]> {
+	const inbox = join(messengerRoot(runDir), "inbox");
+	try {
+		const entries = await readdir(inbox, { withFileTypes: true });
+		return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+	} catch {
+		return [];
+	}
+}