ultimate-pi 0.22.1 → 0.23.0

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

@@ -19,6 +19,7 @@ import {
 	laneArtifactPathsForParallelProbesRound,
 	laneArtifactPathsForRound,
 } from "./plan-debate-lanes.js";
+import { getPlanDebateRoundStatus } from "./plan-debate-round-status.js";
 import {
 	getMessengerRoundState,
 	loadMessengerState,
@@ -331,3 +332,89 @@ export function isReviewRoundArtifactPath(relPath: string): boolean {
 		norm === CONSOLIDATED_REVIEW_ARTIFACT
 	);
 }
+
+function roundIndexForFocus(
+	focus: PlanDebateFocus,
+	required: readonly PlanDebateFocus[],
+): number {
+	const idx = required.indexOf(focus);
+	return idx >= 0 ? idx + 1 : 1;
+}
+
+/** Actionable recovery steps when approve_plan is blocked by the debate gate. */
+export async function buildPlanDebateGateRecovery(
+	projectRoot: string,
+	runId: string,
+	gate: PlanDebateGateResult,
+): Promise<string> {
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const messenger = await loadMessengerState(runDir);
+	const required: readonly PlanDebateFocus[] =
+		messenger?.required_focuses && messenger.required_focuses.length > 0
+			? messenger.required_focuses
+			: (["spec", "wbs", "schedule", "quality"] as const);
+	const profile =
+		messenger?.debate_profile ?? gate.debate_profile ?? "standard";
+	const mode = messenger?.review_gate_mode ?? "threaded";
+	const coverage = gate.focus_coverage;
+
+	const lines: string[] = [
+		"Review Gate must finish before approve_plan.",
+		"",
+		"Blocking checks:",
+		...gate.errors.map((e) => `- ${e}`),
+		"",
+		`Debate profile: ${profile}, mode: ${mode}, required focuses: ${required.join(", ")}`,
+		"",
+	];
+
+	const needsConsensus = gate.errors.some(
+		(e) => e.includes("consensus") || e.includes(".consensus.json"),
+	);
+	const needsRounds = gate.errors.some(
+		(e) =>
+			e.includes("review_gate_ready") ||
+			e.includes("focus not covered") ||
+			e.includes("missing artifacts/") ||
+			e.includes("round events"),
+	);
+
+	if (needsRounds) {
+		const nextFocus: PlanDebateFocus =
+			(coverage?.missing[0] as PlanDebateFocus | undefined) ??
+			required[0] ??
+			"spec";
+		const roundIndex =
+			mode === "consolidated" ? 1 : roundIndexForFocus(nextFocus, required);
+		const status = await getPlanDebateRoundStatus(runDir, roundIndex, runId, {
+			debate_round_focus: mode === "consolidated" ? "all" : nextFocus,
+		});
+		lines.push(
+			`Next round: ${roundIndex} (focus: ${mode === "consolidated" ? "all" : nextFocus})`,
+		);
+		if (status.missing.length > 0) {
+			lines.push("Missing lane artifacts:");
+			for (const m of status.missing) {
+				lines.push(`- ${m}`);
+			}
+		}
+		if (status.next_tool) {
+			lines.push(`Next tool: ${status.next_tool}`);
+		}
+		lines.push(
+			"Workflow: complete lane subagents (one per batch) → review-integrator → harness_debate_submit_round → harness_debate_focus_coverage.",
+		);
+	}
+
+	if (needsConsensus) {
+		lines.push(
+			"When all required focuses are covered and the last round has review_gate_ready: true, call harness_debate_consensus, then approve_plan again.",
+		);
+	}
+
+	if (gate.warnings.length > 0) {
+		lines.push("", "Warnings:", ...gate.warnings.map((w) => `- ${w}`));
+	}
+
+	return lines.join("\n");
+}

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

@@ -48,12 +48,14 @@ export async function applyDebateLaneFromDoc(opts: {
 	lane: DebateLaneKind;
 	doc: Record<string, unknown>;
 	roundIndex?: number;
+	skipArtifactWrite?: boolean;
 }): Promise<ApplyDebateLaneResult> {
 	return applyDebateLane({
 		runDir: opts.runDir,
 		lane: opts.lane,
 		content: JSON.stringify(opts.doc),
 		roundIndex: opts.roundIndex,
+		skipArtifactWrite: opts.skipArtifactWrite,
 	});
 }
 
@@ -95,6 +97,8 @@ export async function applyDebateLane(opts: {
 	lane: DebateLaneKind;
 	content: string;
 	roundIndex?: number;
+	/** When true, artifact YAML was already written (e.g. submit pipeline); only messenger side effects run. */
+	skipArtifactWrite?: boolean;
 }): Promise<ApplyDebateLaneResult> {
 	const errors: string[] = [];
 	let doc: Record<string, unknown>;
@@ -121,8 +125,10 @@ export async function applyDebateLane(opts: {
 			: (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);
+	if (!opts.skipArtifactWrite) {
+		await mkdir(dirname(absPath), { recursive: true });
+		await writeYamlFile(absPath, doc);
+	}
 
 	let messengerPosted = false;
 	let nextStep: string | undefined;

package/.pi/lib/plan-human-gates.ts

@@ -0,0 +1,404 @@
+/**
+ * Human-in-the-loop gates for /harness-plan — Phase 0 ask_user and Phase 6 approve_plan.
+ */
+
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import {
+	isHarnessNonInteractive,
+	isPlanApprovalAskUser,
+} from "./ask-user/policy.js";
+import {
+	hasPlanUserApproval,
+	indexOfLastPlanCommand,
+} from "./harness-run-context.js";
+import { validatePlanApprovalReadiness } from "./plan-approval-readiness.js";
+import {
+	buildPlanDebateGateRecovery,
+	validatePlanDebateGate,
+} from "./plan-debate-gate.js";
+import {
+	isTaskClarificationReady,
+	readTaskClarificationDoc,
+	type TaskClarificationReadiness,
+	validateTaskClarificationDoc,
+} from "./plan-task-clarification.js";
+
+const EXPLICIT_ACCEPTANCE_RE =
+	/\b(acceptance|success criteria|definition of done|done when|must (pass|satisfy)|out of scope|in scope)\b/i;
+
+function logPlanHumanGate(payload: {
+	runId: string;
+	hypothesisId: string;
+	location: string;
+	message: string;
+	data: Record<string, unknown>;
+}): void {
+	// #region agent log
+	fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-Debug-Session-Id": "f7763e",
+		},
+		body: JSON.stringify({
+			sessionId: "f7763e",
+			runId: payload.runId,
+			hypothesisId: payload.hypothesisId,
+			location: payload.location,
+			message: payload.message,
+			data: payload.data,
+			timestamp: Date.now(),
+		}),
+	}).catch(() => {});
+	// #endregion
+}
+
+type SessionEntryLike = {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+		content?: string | unknown[];
+	};
+};
+
+function isNonInteractivePlan(): boolean {
+	return (
+		process.env.HARNESS_PLAN_NONINTERACTIVE === "1" || isHarnessNonInteractive()
+	);
+}
+
+function askUserCallWasTaskClarification(details: unknown): boolean {
+	if (!details || typeof details !== "object") return false;
+	const d = details as { cancelled?: boolean; input?: unknown };
+	if (d.cancelled) return false;
+	const input = d.input as
+		| { question?: string; options?: unknown[]; questions?: unknown[] }
+		| undefined;
+	if (!input) return true;
+	return !isPlanApprovalAskUser(input);
+}
+
+export function hasTaskClarificationAskUserSincePlanCommand(
+	entries: unknown[],
+): boolean {
+	if (isNonInteractivePlan()) return true;
+	const since = Math.max(0, indexOfLastPlanCommand(entries));
+	for (let i = since; i < entries.length; i++) {
+		const entry = entries[i] as SessionEntryLike;
+		if (
+			entry.type === "custom" &&
+			entry.customType === "harness-task-clarification-engagement"
+		) {
+			return true;
+		}
+		if (entry.type !== "message" || entry.message?.role !== "toolResult") {
+			continue;
+		}
+		if (entry.message.toolName !== "ask_user") continue;
+		if (askUserCallWasTaskClarification(entry.message.details)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+export function hasClarificationFollowUpUserMessage(
+	entries: unknown[],
+): boolean {
+	const since = Math.max(0, indexOfLastPlanCommand(entries));
+	for (let i = since; i < entries.length; i++) {
+		const entry = entries[i] as SessionEntryLike;
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const content = entry.message.content;
+		const text =
+			typeof content === "string"
+				? content.trim()
+				: Array.isArray(content)
+					? content
+							.filter(
+								(c): c is { type: string; text?: string } =>
+									typeof c === "object" && c !== null && "type" in c,
+							)
+							.map((c) => c.text ?? "")
+							.join("")
+							.trim()
+					: "";
+		if (!text || text.startsWith("/")) continue;
+		return true;
+	}
+	return false;
+}
+
+export function isExplicitTaskAcceptance(taskSummary: string): boolean {
+	const t = taskSummary.trim();
+	if (t.length < 24) return false;
+	return EXPLICIT_ACCEPTANCE_RE.test(t);
+}
+
+export interface TaskClarificationHumanGateResult {
+	ok: boolean;
+	errors: string[];
+}
+
+export function validateTaskClarificationHumanGate(
+	entries: unknown[],
+	doc: Record<string, unknown> | null,
+	opts?: {
+		quick?: boolean;
+		taskSummary?: string;
+		allowFollowUpMessage?: boolean;
+	},
+): TaskClarificationHumanGateResult {
+	const errors: string[] = [];
+	const status = String(doc?.status ?? "").toLowerCase();
+	if (status !== "ready") {
+		return { ok: true, errors };
+	}
+
+	const engagement = doc?.user_engagement as { source?: string } | undefined;
+	if (engagement?.source === "ask_user") {
+		return { ok: true, errors };
+	}
+
+	if (hasTaskClarificationAskUserSincePlanCommand(entries)) {
+		return { ok: true, errors };
+	}
+
+	if (
+		opts?.allowFollowUpMessage &&
+		hasClarificationFollowUpUserMessage(entries)
+	) {
+		return { ok: true, errors };
+	}
+
+	if (opts?.quick && isExplicitTaskAcceptance(opts.taskSummary ?? "")) {
+		return { ok: true, errors };
+	}
+
+	errors.push(
+		"Phase 0 requires ask_user before task-clarification status: ready. Call ask_user (harness-decisions skill), merge answers, then harness_artifact_ready.",
+	);
+	return { ok: false, errors };
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export interface PlanHumanGateStatus {
+	phase0Ready: boolean;
+	phase0NeedsAskUser: boolean;
+	debateComplete: boolean;
+	debateRequired: boolean;
+	approvalRequired: boolean;
+	approvalRecorded: boolean;
+	nextRequiredAction: string | null;
+	/** Actionable Review Gate recovery when debateRequired. */
+	debateRecoveryHint: string | null;
+}
+
+export async function resolvePlanHumanGateStatus(
+	projectRoot: string,
+	runId: string,
+	entries: unknown[],
+	opts?: { quick?: boolean; taskSummary?: string; lastOutcome?: string | null },
+): Promise<PlanHumanGateStatus> {
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const clar = await isTaskClarificationReady(runDir);
+	const clarDoc = clar.ok ? await readTaskClarificationDoc(runDir) : null;
+	logPlanHumanGate({
+		runId,
+		hypothesisId: "H3",
+		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:clar",
+		message: "Task clarification readiness evaluated",
+		data: {
+			runDir,
+			clarOk: clar.ok,
+			clarErrors: clar.errors,
+			docStatus: String(clarDoc?.status ?? ""),
+			docEngagementSource:
+				typeof clarDoc?.user_engagement === "object" &&
+				clarDoc?.user_engagement !== null
+					? String(
+							(
+								clarDoc.user_engagement as {
+									source?: string;
+								}
+							).source ?? "",
+						)
+					: "",
+		},
+	});
+	const humanGate = validateTaskClarificationHumanGate(entries, clarDoc, {
+		quick: opts?.quick,
+		taskSummary: opts?.taskSummary,
+		allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
+	});
+	logPlanHumanGate({
+		runId,
+		hypothesisId: "H1-H2",
+		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:humanGate",
+		message: "Human gate evaluated for phase0 ask_user requirement",
+		data: {
+			humanGateOk: humanGate.ok,
+			humanGateErrors: humanGate.errors,
+			allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
+			hasTaskClarificationAskUserSincePlanCommand:
+				hasTaskClarificationAskUserSincePlanCommand(entries),
+			hasClarificationFollowUpUserMessage:
+				hasClarificationFollowUpUserMessage(entries),
+			indexOfLastPlanCommand: indexOfLastPlanCommand(entries),
+			entriesLen: entries.length,
+		},
+	});
+	const phase0Ready = clar.ok && humanGate.ok;
+	const phase0NeedsAskUser = clar.ok && !humanGate.ok;
+	const approvalRecorded = hasPlanUserApproval(entries, {
+		sincePlanCommand: true,
+	});
+	const dagPath = join(runDir, "plan-packet.yaml");
+	const hasPacket = await fileExists(dagPath);
+	const messengerPath = join(runDir, "debate-messenger", "state.json");
+	const debateOpened = await fileExists(messengerPath);
+
+	let debateComplete = true;
+	let debateGate = null;
+	let readinessOk = false;
+	let approvalRequired = false;
+
+	if (phase0Ready && !approvalRecorded) {
+		const readiness = await validatePlanApprovalReadiness(projectRoot, runId, {
+			risk_level: String(clarDoc?.risk_level ?? "med"),
+			quick: opts?.quick,
+		});
+		readinessOk = readiness.ok;
+		debateGate = await validatePlanDebateGate(projectRoot, runId);
+		debateComplete = debateGate.ok;
+		approvalRequired = readiness.ok && debateComplete && hasPacket;
+	}
+
+	const debateRequired =
+		phase0Ready &&
+		!debateComplete &&
+		!approvalRecorded &&
+		(debateOpened || hasPacket);
+
+	let debateRecoveryHint: string | null = null;
+	let nextRequiredAction: string | null = null;
+	if (!phase0Ready) {
+		nextRequiredAction = phase0NeedsAskUser
+			? "ask_user (Phase 0 task contract)"
+			: "complete artifacts/task-clarification.yaml (Phase 0)";
+	} else if (debateRequired && debateGate) {
+		debateRecoveryHint = await buildPlanDebateGateRecovery(
+			projectRoot,
+			runId,
+			debateGate,
+		);
+		nextRequiredAction =
+			"Complete Review Gate (debate rounds + harness_debate_consensus) before approve_plan";
+	} else if (approvalRequired && !approvalRecorded) {
+		nextRequiredAction = "approve_plan then create_plan (Phase 6)";
+	}
+	logPlanHumanGate({
+		runId,
+		hypothesisId: "H4",
+		location: "plan-human-gates.ts:resolvePlanHumanGateStatus:result",
+		message: "Resolved plan human gate status",
+		data: {
+			phase0Ready,
+			phase0NeedsAskUser,
+			debateComplete,
+			debateRequired,
+			approvalRequired,
+			approvalRecorded,
+			nextRequiredAction,
+		},
+	});
+
+	return {
+		phase0Ready,
+		phase0NeedsAskUser,
+		debateComplete,
+		debateRequired,
+		approvalRequired,
+		approvalRecorded,
+		nextRequiredAction,
+		debateRecoveryHint,
+	};
+}
+
+export function formatPlanHumanGateBlock(status: PlanHumanGateStatus): string {
+	if (!status.nextRequiredAction) return "";
+	const lines = [
+		"[HarnessPlanGate]",
+		`next_required_action=${status.nextRequiredAction}`,
+		`phase0_ready=${status.phase0Ready}`,
+		`review_gate_complete=${status.debateComplete}`,
+		`review_gate_required=${status.debateRequired}`,
+		`plan_approval_required=${status.approvalRequired}`,
+		`plan_approval_recorded=${status.approvalRecorded}`,
+	];
+	if (status.debateRequired) {
+		lines.push(
+			"Do not end this turn with prose only — call harness_debate_round_status / harness_debate_focus_coverage and spawn the next debate lane subagent (one per batch).",
+		);
+	} else {
+		lines.push(
+			"Do not spawn planning subagents or end this turn until the required human step completes.",
+		);
+	}
+	if (status.debateRecoveryHint) {
+		lines.push("", status.debateRecoveryHint);
+	}
+	return lines.join("\n");
+}
+
+export async function shouldBlockSubagentForMissingPlanApproval(
+	projectRoot: string,
+	runId: string,
+	entries: unknown[],
+	phase: string,
+): Promise<{ block: boolean; reason?: string }> {
+	if (phase !== "plan" || isNonInteractivePlan()) return { block: false };
+	if (hasPlanUserApproval(entries, { sincePlanCommand: true })) {
+		return { block: false };
+	}
+	const status = await resolvePlanHumanGateStatus(projectRoot, runId, entries);
+	if (!status.approvalRequired) return { block: false };
+	return {
+		block: true,
+		reason:
+			"Plan Review Gate is complete but user approval is missing. Call approve_plan (then create_plan) before further subagent work.",
+	};
+}
+
+export async function validateTaskClarificationReadyWithHumanGate(
+	runDir: string,
+	entries: unknown[],
+	opts?: { quick?: boolean; taskSummary?: string; lastOutcome?: string | null },
+): Promise<TaskClarificationReadiness & { humanErrors: string[] }> {
+	const doc = await readTaskClarificationDoc(runDir);
+	const base = validateTaskClarificationDoc(doc, { requireReady: true });
+	const human = validateTaskClarificationHumanGate(entries, doc, {
+		quick: opts?.quick,
+		taskSummary: opts?.taskSummary,
+		allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
+	});
+	return {
+		ok: base.ok && human.ok,
+		errors: [...base.errors, ...human.errors],
+		humanErrors: human.errors,
+	};
+}

package/.pi/prompts/harness-clear.md

@@ -0,0 +1,25 @@
+---
+description: Safely delete historical harness run directories while preserving the active run.
+---
+
+# harness-clear
+
+Delete only historical run directories under `.pi/harness/runs/`.
+
+## What this does
+
+- enumerates delete candidates strictly from `.pi/harness/runs/<run_id>/`
+- always preserves active run ids discovered from session context and active-run pointer
+- asks for one confirmation before any filesystem mutation
+- fails closed: cancel/decline/timeout/error/unavailable confirmation paths delete nothing
+- reports deleted vs protected/skipped counts
+
+## Usage
+
+`/harness-clear`
+
+## Safety boundaries
+
+- in scope: historical run directories only
+- out of scope: full `.pi/harness/` reset, non-run harness assets, active-run deletion overrides
+- confirmation is mandatory; non-affirmative outcomes are no-op

package/.pi/prompts/harness-plan.md

@@ -11,6 +11,10 @@ Use the phase order and spawn topology defined in this prompt directly.
 
 Subagents persist artifacts via scoped **`submit_*`** tools (deterministic YAML under the run dir). Parent uses **`harness_artifact_ready`** to gate phases (no JSON parsing). Parent merges still use **`write_harness_yaml`** for `research-brief.yaml`, `plan-packet.yaml`, `planning-context.yaml`, and integrator patches.
 
+### Subagent submit → gate (required)
+
+After a subprocess **`submit_*`** succeeds (or the artifact path is on disk and schema-valid), call **`harness_artifact_ready({ paths: ["<that-artifact>"] })` once** before the next phase or spawn. If spawn topology returns **Duplicate spawn blocked**, do **not** re-spawn that agent — call `harness_artifact_ready` on the existing artifact and advance. Never call the same `submit_*` twice with identical content (idempotent noop — end the subprocess turn instead).
+
 **Phase 0 is mandatory** before reconnaissance or any planning subagent. `write_harness_yaml` and spawn topology enforce `artifacts/task-clarification.yaml` with `status: ready`.
 
 ## Allowed subagents
@@ -184,6 +188,8 @@ subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author",
 
 Merge `execution_plan` into draft `plan-packet.yaml` (`write_harness_yaml`). Save `artifacts/execution-plan-draft.yaml` the same way.
 
+The `execution_plan` must make testing expectations explicit: decide whether unit, integration, and e2e/end-to-end tests are applicable for each changed surface based on risk and implementation scope; add work items/done criteria to create or update applicable tests; list relevant verification commands; and record a short rationale when a test level is not applicable. Do not hard-require all three test levels for every change — make the applicability decision visible.
+
 ## Phase 4c — Deterministic quality gate (hard stop)
 
 **Practice:** Harness engineering — never trust the model for graph validity.

package/.pi/prompts/harness-review.md

@@ -75,6 +75,8 @@ Ensure `artifacts/ls-lint-signal.yaml` exists (from `/harness-run` or write from
 
 Run project tests if the approved `PlanPacket` or spawn context lists a test command. Capture stdout paths only — do not paste full logs into the next spawn.
 
+Verify the testing obligation itself: the approved `PlanPacket` or spawn context must show planned applicability decisions for unit, integration, and e2e/end-to-end tests, and executor evidence must show applicable tests were implemented or updated and run. If a test level was not applicable, require a clear rationale tied to risk and changed surface; missing planned or executed applicable testing is a benchmark failure.
+
 Write `artifacts/benchmark-log.yaml` via `write_harness_yaml` when any shell step ran:
 
 ```yaml

package/.pi/prompts/harness-run.md

@@ -52,14 +52,15 @@ Note `violation_count` in run notes (do not block execute on pre-existing violat
 1. Confirm `[HarnessActivePlan]` / extension reports plan ready.
 2. Build `HarnessSpawnContext` with `mode: execute`, `plan_packet_path`, `run_dir`, `acceptance_checks` from plan file.
 3. Include **`critical_path_work_item_ids`** from `execution_plan.schedule_metadata` in spawn task when present — executor should tackle limiting-step items first (Grove).
-4. Spawn (max **1** agent per call):
+4. Include the plan's testing expectations in the spawn task: the executor must implement or update applicable unit, integration, and e2e/end-to-end tests, run the relevant verification commands, and report command evidence or a rationale for any non-applicable test level in `validation_summary`.
+5. Spawn (max **1** agent per call):
 
 ```
 subagent({ agentScope: "both", agent: "harness/running/executor", task: "<HarnessSpawnContext + handoff + critical path hint>" })
 ```
 
-5. Parse subprocess output JSON (`execution_status`, validations, rollback refs) from tool result text.
-6. Parent persists trace/handoff artifacts under run dir if needed; do not self-review.
+6. Parse subprocess output JSON (`execution_status`, validations, rollback refs) from tool result text.
+7. Parent persists trace/handoff artifacts under run dir if needed; do not self-review.
 
 ## Post-work — Structural observation (parent)