ultimate-pi 0.20.0 → 0.22.0

package/.pi/lib/harness-slash-completions.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared slash-command argument completions for harness extension commands.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+	harnessRunsRoot,
+	RUN_CONTEXT_BASENAME,
+} from "./harness-run-context.js";
+
+const MAX_RUN_SUGGESTIONS = 20;
+
+export function filterPrefix(
+	items: AutocompleteItem[],
+	prefix: string,
+): AutocompleteItem[] | null {
+	const p = prefix.trim();
+	if (!p) return items.length > 0 ? items : null;
+	const filtered = items.filter(
+		(item) =>
+			item.value.startsWith(p) ||
+			(item.label !== undefined && item.label.startsWith(p)),
+	);
+	return filtered.length > 0 ? filtered : null;
+}
+
+export function completeFlags(
+	prefix: string,
+	flags: string[],
+): AutocompleteItem[] | null {
+	const items = flags.map((flag) => ({ value: flag, label: flag }));
+	return filterPrefix(items, prefix);
+}
+
+export function completeEnum(
+	prefix: string,
+	values: string[],
+): AutocompleteItem[] | null {
+	return completeFlags(prefix, values);
+}
+
+export async function completeRunIds(
+	prefix: string,
+	projectRoot: string,
+): Promise<AutocompleteItem[] | null> {
+	const runsDir = harnessRunsRoot(projectRoot);
+	let names: string[];
+	try {
+		names = await readdir(runsDir);
+	} catch {
+		return null;
+	}
+
+	const entries: { id: string; mtime: number; phase?: string }[] = [];
+	for (const name of names) {
+		if (name.startsWith(".")) continue;
+		const dir = join(runsDir, name);
+		try {
+			const st = await stat(dir);
+			if (!st.isDirectory()) continue;
+			let phase: string | undefined;
+			try {
+				const raw = await readFile(join(dir, RUN_CONTEXT_BASENAME), "utf-8");
+				const match = raw.match(/^phase:\s*(\S+)/m);
+				if (match) phase = match[1];
+			} catch {
+				/* optional */
+			}
+			entries.push({ id: name, mtime: st.mtimeMs, phase });
+		} catch {}
+	}
+
+	entries.sort((a, b) => b.mtime - a.mtime);
+	const items: AutocompleteItem[] = entries
+		.slice(0, MAX_RUN_SUGGESTIONS)
+		.map((entry) => ({
+			value: entry.id,
+			label: entry.id,
+			description: entry.phase ? `phase ${entry.phase}` : undefined,
+		}));
+
+	return filterPrefix(items, prefix);
+}
+
+export async function completeHarnessUseRun(
+	prefix: string,
+	projectRoot: string,
+): Promise<AutocompleteItem[] | null> {
+	const p = prefix.trim();
+	if (p.startsWith("-")) {
+		return completeFlags(p, ["--claim", "--readonly"]);
+	}
+	return completeRunIds(p, projectRoot);
+}
+
+export function completeStrictFlag(prefix: string): AutocompleteItem[] | null {
+	return completeFlags(prefix, ["--strict"]);
+}
+
+export async function completeDebateOpen(
+	prefix: string,
+	projectRoot: string,
+): Promise<AutocompleteItem[] | null> {
+	const runs = await completeRunIds("", projectRoot);
+	if (!runs?.length) {
+		return filterPrefix([{ value: "plan-", label: "plan-<run-id>" }], prefix);
+	}
+	const items = runs.map((run) => ({
+		value: `plan-${run.value}`,
+		label: `plan-${run.value}`,
+		description: run.description,
+	}));
+	return filterPrefix(items, prefix);
+}

package/.pi/lib/harness-spawn-topology.ts

@@ -6,6 +6,7 @@ import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
 import type { HarnessPhase } from "./harness-run-context.js";
+import { isTaskClarificationReady } from "./plan-task-clarification.js";
 
 export interface SpawnTopologyResult {
 	ok: boolean;
@@ -30,6 +31,18 @@ const PARALLEL_RESEARCH_AGENTS = new Set([
 	"harness/planning/stack-researcher",
 ]);
 
+const CLARIFICATION_GATED_AGENTS = new Set([
+	PLANNING_CONTEXT_AGENT,
+	DECOMPOSE_AGENT,
+	HYPOTHESIS_AGENT,
+	...PARALLEL_RESEARCH_AGENTS,
+	...DEBATE_LANE_AGENTS,
+	"harness/planning/plan-synthesizer",
+	"harness/planning/execution-plan-author",
+	"harness/sentrux-steward",
+	"harness/ls-lint-steward",
+]);
+
 function countInSet(names: string[], allowed: Set<string>): number {
 	return names.filter((n) => allowed.has(n)).length;
 }
@@ -58,6 +71,105 @@ async function decompositionReady(
 		return false;
 	}
 }
+function validateParallelBatch(
+	names: string[],
+	taskCount: number,
+): string | null {
+	if (taskCount <= 1) return null;
+	const hasDecompose = names.includes(DECOMPOSE_AGENT);
+	const hasHypothesis = names.includes(HYPOTHESIS_AGENT);
+	if (hasDecompose && hasHypothesis) {
+		return (
+			"Cannot spawn decompose and hypothesis in the same parallel batch. " +
+			"Gate artifacts/decomposition.yaml, then spawn hypothesis sequentially."
+		);
+	}
+
+	const debateCount = countInSet(names, DEBATE_LANE_AGENTS);
+	const debateNames = names.filter((n) => DEBATE_LANE_AGENTS.has(n));
+	const parallelProbePair =
+		debateCount === 2 &&
+		debateNames.includes("harness/planning/plan-evaluator") &&
+		debateNames.includes("harness/planning/plan-adversary");
+	if (debateCount > 1 && !parallelProbePair) {
+		return `Review Gate: spawn one debate lane agent per subagent call (got ${debateCount}: ${debateNames.join(", ")}). Exception: plan-evaluator ∥ plan-adversary for parallel_probes.`;
+	}
+
+	const planningContext = names.filter(
+		(n) => n === PLANNING_CONTEXT_AGENT,
+	).length;
+	const research = countInSet(names, PARALLEL_RESEARCH_AGENTS);
+	const recon = planningContext;
+	if (planningContext > 1) {
+		return "At most one planning-context subagent per parallel batch.";
+	}
+
+	const otherHarness = names.filter(
+		(n) =>
+			n.startsWith("harness/") &&
+			!isReconnaissanceAgent(n) &&
+			!PARALLEL_RESEARCH_AGENTS.has(n) &&
+			!DEBATE_LANE_AGENTS.has(n) &&
+			n !== DECOMPOSE_AGENT &&
+			n !== HYPOTHESIS_AGENT,
+	);
+	if (
+		(recon > 0 && (research > 0 || otherHarness.length > 0)) ||
+		(research > 0 && otherHarness.length > 0)
+	) {
+		return (
+			"Parallel batches may include only one independent group: " +
+			"research (≤2 lanes), optional single planning-context, " +
+			"or a single sequential lane agent."
+		);
+	}
+	if (research > 2) {
+		return "At most 2 research lanes (implementation-researcher, stack-researcher) per parallel batch.";
+	}
+	return null;
+}
+
+async function validateClarificationGate(
+	names: string[],
+	phase: HarnessPhase,
+	opts?: { projectRoot?: string; runId?: string | null },
+): Promise<string | null> {
+	if (!(phase === "plan" && opts?.projectRoot && opts?.runId)) return null;
+	const needsClar = names.some((n) => CLARIFICATION_GATED_AGENTS.has(n));
+	if (!needsClar) return null;
+	const runDir = join(opts.projectRoot, ".pi", "harness", "runs", opts.runId);
+	const clar = await isTaskClarificationReady(runDir);
+	if (clar.ok) return null;
+	return (
+		"Cannot spawn planning subagents before task clarification is ready. " +
+		`Complete Phase 0 and harness_artifact_ready on artifacts/task-clarification.yaml. ${clar.errors.join("; ")}`
+	);
+}
+
+async function validateHypothesisDependency(
+	names: string[],
+	opts?: { projectRoot?: string; runId?: string | null },
+): Promise<string | null> {
+	if (!(names.includes(HYPOTHESIS_AGENT) && opts?.projectRoot && opts?.runId)) {
+		return null;
+	}
+	const ready = await decompositionReady(opts.projectRoot, opts.runId);
+	if (ready) return null;
+	return (
+		"Cannot spawn hypothesis before artifacts/decomposition.yaml exists. " +
+		"Complete decompose and harness_artifact_ready on decomposition first."
+	);
+}
+
+function validatePlanPhaseMutations(
+	names: string[],
+	phase: HarnessPhase,
+): string | null {
+	if (phase !== "plan") return null;
+	const mutating = names.filter((n) => n.startsWith("harness/running/"));
+	if (mutating.length === 0) return null;
+	return `Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}).`;
+}
 
 export async function validateHarnessSpawnTopology(
 	names: string[],
@@ -71,95 +183,17 @@ export async function validateHarnessSpawnTopology(
 	const taskCount =
 		opts?.parallelTaskCount ?? (names.length > 1 ? names.length : 1);
 
-	if (taskCount > 1) {
-		const hasDecompose = names.includes(DECOMPOSE_AGENT);
-		const hasHypothesis = names.includes(HYPOTHESIS_AGENT);
-		if (hasDecompose && hasHypothesis) {
-			return {
-				ok: false,
-				message:
-					"Cannot spawn decompose and hypothesis in the same parallel batch. " +
-					"Gate artifacts/decomposition.yaml, then spawn hypothesis sequentially.",
-			};
-		}
-
-		const debateCount = countInSet(names, DEBATE_LANE_AGENTS);
-		const debateNames = names.filter((n) => DEBATE_LANE_AGENTS.has(n));
-		const parallelProbePair =
-			debateCount === 2 &&
-			debateNames.includes("harness/planning/plan-evaluator") &&
-			debateNames.includes("harness/planning/plan-adversary");
-		if (debateCount > 1 && !parallelProbePair) {
-			return {
-				ok: false,
-				message: `Review Gate: spawn one debate lane agent per subagent call (got ${debateCount}: ${debateNames.join(", ")}). Exception: plan-evaluator ∥ plan-adversary for parallel_probes.`,
-			};
-		}
-
-		const planningContext = names.filter(
-			(n) => n === PLANNING_CONTEXT_AGENT,
-		).length;
-		const research = countInSet(names, PARALLEL_RESEARCH_AGENTS);
-		const recon = planningContext;
-
-		if (planningContext > 1) {
-			return {
-				ok: false,
-				message: "At most one planning-context subagent per parallel batch.",
-			};
-		}
-
-		const otherHarness = names.filter(
-			(n) =>
-				n.startsWith("harness/") &&
-				!isReconnaissanceAgent(n) &&
-				!PARALLEL_RESEARCH_AGENTS.has(n) &&
-				!DEBATE_LANE_AGENTS.has(n) &&
-				n !== DECOMPOSE_AGENT &&
-				n !== HYPOTHESIS_AGENT,
-		);
-		if (
-			(recon > 0 && (research > 0 || otherHarness.length > 0)) ||
-			(research > 0 && otherHarness.length > 0)
-		) {
-			return {
-				ok: false,
-				message:
-					"Parallel batches may include only one independent group: " +
-					"research (≤2 lanes), optional single planning-context, " +
-					"or a single sequential lane agent.",
-			};
-		}
-		if (research > 2) {
-			return {
-				ok: false,
-				message:
-					"At most 2 research lanes (implementation-researcher, stack-researcher) per parallel batch.",
-			};
-		}
-	}
+	const parallelError = validateParallelBatch(names, taskCount);
+	if (parallelError) return { ok: false, message: parallelError };
 
-	if (names.includes(HYPOTHESIS_AGENT) && opts?.projectRoot && opts?.runId) {
-		const ready = await decompositionReady(opts.projectRoot, opts.runId);
-		if (!ready) {
-			return {
-				ok: false,
-				message:
-					"Cannot spawn hypothesis before artifacts/decomposition.yaml exists. " +
-					"Complete decompose and harness_artifact_ready on decomposition first.",
-			};
-		}
-	}
+	const clarError = await validateClarificationGate(names, phase, opts);
+	if (clarError) return { ok: false, message: clarError };
 
-	if (phase === "plan") {
-		const mutating = names.filter((n) => n.startsWith("harness/running/"));
-		if (mutating.length > 0) {
-			return {
-				ok: false,
-				message: `Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}).`,
-			};
-		}
-	}
+	const hypothesisError = await validateHypothesisDependency(names, opts);
+	if (hypothesisError) return { ok: false, message: hypothesisError };
+
+	const mutationError = validatePlanPhaseMutations(names, phase);
+	if (mutationError) return { ok: false, message: mutationError };
 
 	return { ok: true };
 }

package/.pi/lib/harness-subagent-submit-registry.ts

@@ -106,6 +106,16 @@ export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 		schemaFile: "sentrux-manifest-proposal.schema.json",
 		artifactPath: "artifacts/sentrux-manifest-proposal.yaml",
 	},
+	{
+		toolName: "submit_sentrux_repair_plan",
+		schemaFile: "sentrux-repair-plan.schema.json",
+		artifactPath: "artifacts/sentrux-repair-plan.yaml",
+	},
+	{
+		toolName: "submit_ls_lint_manifest_proposal",
+		schemaFile: "ls-lint-manifest-proposal.schema.json",
+		artifactPath: "artifacts/ls-lint-manifest-proposal.yaml",
+	},
 ] as const;
 
 export function specForSubmitTool(

package/.pi/lib/harness-subagents-bridge.ts

@@ -13,7 +13,6 @@ import {
 	type HarnessSubagentsOptions,
 	type SpawnAuthForward,
 } from "../../vendor/pi-subagents/src/subagents.js";
-import { subagentGovernanceExtensionPath } from "../extensions/subagent-governance.js";
 import { getAgentKind, resolveExtensionBundlePaths } from "./agents-policy.mjs";
 import {
 	delegationEnvFromBundle,
@@ -61,6 +60,10 @@ type PendingSpawnTelemetry = {
 };
 let pendingSpawnTelemetry: PendingSpawnTelemetry | null = null;
 
+function subagentGovernanceExtensionPath(packageRoot: string): string {
+	return join(packageRoot, ".pi", "extensions", "subagent-governance.ts");
+}
+
 function collectHarnessAgentIds(params: Record<string, unknown>): string[] {
 	const out = new Set<string>();
 	const maybe = params as {

package/.pi/lib/harness-ui-state.ts

@@ -201,26 +201,33 @@ function deriveFlowSubstate(state: HarnessUiState): HarnessFlowSubstate {
 	return "idle";
 }
 
-export function createStateFromEntries(entries: unknown[]): HarnessUiState {
-	const latest = pickLatestCustomEntries(entries);
-	const state: HarnessUiState = {
-		...DEFAULT_STATE,
-		severity: { ...DEFAULT_STATE.severity },
-	};
-
+function applyPolicyState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const policy = latest.get("harness-policy-state") as
 		| PolicyStateLike
 		| undefined;
 	if (policy?.phase) state.phase = policy.phase;
 	state.planApproved = Boolean(policy?.approvedPlan);
 	state.planId = typeof policy?.planId === "string" ? policy.planId : null;
+}
 
+function applyReviewState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const review = latest.get("harness-review-integrity") as
 		| ReviewIntegrityStateLike
 		| undefined;
 	state.reviewViolationActive = Boolean(review?.violationActive);
 	state.reviewIsolationOk = !state.reviewViolationActive;
+}
 
+function applyBudgetState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const budget = latest.get("harness-budget-exhausted") as
 		| BudgetExhaustedLike
 		| undefined;
@@ -234,30 +241,41 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 		if (budgetUsed != null) state.debateBudgetUsed = budgetUsed;
 		const cap = asNumber(budget.caps?.debate_global_cap);
 		if (cap != null) state.debateBudgetCap = cap;
+		return;
 	}
 	const telemetry = latest.get("harness-budget-telemetry") as
 		| BudgetExhaustedLike
 		| undefined;
-	if (telemetry && !state.budgetExhausted) {
-		const budgetUsed = asNumber(telemetry.budget_used);
-		if (budgetUsed != null) state.debateBudgetUsed = budgetUsed;
-		const cap = asNumber(telemetry.caps?.debate_global_cap);
-		if (cap != null) state.debateBudgetCap = cap;
-	}
+	if (!telemetry) return;
+	const budgetUsed = asNumber(telemetry.budget_used);
+	if (budgetUsed != null) state.debateBudgetUsed = budgetUsed;
+	const cap = asNumber(telemetry.caps?.debate_global_cap);
+	if (cap != null) state.debateBudgetCap = cap;
+}
 
+function applyTestIntegrityState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const testIntegrity = latest.get("harness-test-integrity-flag") as
 		| TestIntegrityLike
 		| undefined;
 	if (
-		testIntegrity?.severity === "high" ||
-		testIntegrity?.severity === "medium"
+		testIntegrity?.severity !== "high" &&
+		testIntegrity?.severity !== "medium"
 	) {
-		state.testIntegritySeverity = testIntegrity.severity;
-		state.testIntegrityReasons = Array.isArray(testIntegrity.reasons)
-			? testIntegrity.reasons.filter((r): r is string => typeof r === "string")
-			: [];
+		return;
 	}
+	state.testIntegritySeverity = testIntegrity.severity;
+	state.testIntegrityReasons = Array.isArray(testIntegrity.reasons)
+		? testIntegrity.reasons.filter((r): r is string => typeof r === "string")
+		: [];
+}
 
+function applyDebateState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const debate = latest.get("harness-debate-state") as
 		| DebateStateLike
 		| undefined;
@@ -269,7 +287,12 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 	if (debateBudgetUsed != null) state.debateBudgetUsed = debateBudgetUsed;
 	const debateBudgetCap = asNumber(debate?.debate_global_cap);
 	if (debateBudgetCap != null) state.debateBudgetCap = debateBudgetCap;
+}
 
+function applyRoundAndConsensusState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const roundResult = latest.get("harness-round-result") as
 		| RoundLike
 		| undefined;
@@ -291,14 +314,19 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 		state.policyDecision = consensus.policy_decision;
 	}
 	const correctness = asNumber(consensus?.severity_scores?.correctness);
-	const security = asNumber(consensus?.severity_scores?.security);
-	const architecture = asNumber(consensus?.severity_scores?.architecture);
-	const test = asNumber(consensus?.severity_scores?.test_integrity);
 	if (correctness != null) state.severity.correctness = correctness;
+	const security = asNumber(consensus?.severity_scores?.security);
 	if (security != null) state.severity.security = security;
+	const architecture = asNumber(consensus?.severity_scores?.architecture);
 	if (architecture != null) state.severity.architecture = architecture;
+	const test = asNumber(consensus?.severity_scores?.test_integrity);
 	if (test != null) state.severity.testIntegrity = test;
+}
 
+function applyTraceState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+): void {
 	const runTrace = latest.get("harness-run-trace") as TraceLike | undefined;
 	const traceState = latest.get("harness-trace-state") as TraceLike | undefined;
 	state.traceRunId =
@@ -307,7 +335,13 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 			: typeof traceState?.run_id === "string"
 				? traceState.run_id
 				: null;
+}
 
+function applyRunContextState(
+	state: HarnessUiState,
+	latest: Map<string, unknown>,
+	entries: unknown[],
+): void {
 	const runCtx = latest.get("harness-run-context") as
 		| {
 				phase?: HarnessPhase;
@@ -320,36 +354,49 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 				status?: string;
 		  }
 		| undefined;
-	if (runCtx?.plan_ready) {
+	if (!runCtx) {
+		state.nextRecommendedCommand = null;
+		return;
+	}
+	if (runCtx.plan_ready) {
 		state.planApproved = true;
 		if (typeof runCtx.plan_id === "string") state.planId = runCtx.plan_id;
 	}
-	if (runCtx?.phase) {
-		state.phase = runCtx.phase;
-	}
-	if (typeof runCtx?.run_id === "string") {
-		state.traceRunId = runCtx.run_id;
-	}
-	if (runCtx) {
-		const persisted = runCtx.next_recommended_command;
-		if (typeof persisted === "string" && persisted.startsWith("/")) {
-			state.nextRecommendedCommand = persisted;
-		} else {
-			const statuses = extractCompletionStatuses(entries);
-			state.nextRecommendedCommand = nextStepAfterOutcome({
-				phase: state.phase,
-				planStatus: runCtx.plan_ready ? "ready" : null,
-				lastCompletedStep: runCtx.last_completed_step,
-				lastOutcome: runCtx.last_outcome,
-				executionStatus: statuses.executionStatus,
-				evalStatus: statuses.evalStatus,
-				aborted: runCtx.status === "aborted",
-			});
-		}
-	} else {
-		state.nextRecommendedCommand = null;
-	}
+	if (runCtx.phase) state.phase = runCtx.phase;
+	if (typeof runCtx.run_id === "string") state.traceRunId = runCtx.run_id;
+
+	const persisted = runCtx.next_recommended_command;
+	if (typeof persisted === "string" && persisted.startsWith("/")) {
+		state.nextRecommendedCommand = persisted;
+		return;
+	}
+	const statuses = extractCompletionStatuses(entries);
+	state.nextRecommendedCommand = nextStepAfterOutcome({
+		phase: state.phase,
+		planStatus: runCtx.plan_ready ? "ready" : null,
+		lastCompletedStep: runCtx.last_completed_step,
+		lastOutcome: runCtx.last_outcome,
+		executionStatus: statuses.executionStatus,
+		evalStatus: statuses.evalStatus,
+		aborted: runCtx.status === "aborted",
+	});
+}
+
+export function createStateFromEntries(entries: unknown[]): HarnessUiState {
+	const latest = pickLatestCustomEntries(entries);
+	const state: HarnessUiState = {
+		...DEFAULT_STATE,
+		severity: { ...DEFAULT_STATE.severity },
+	};
 
+	applyPolicyState(state, latest);
+	applyReviewState(state, latest);
+	applyBudgetState(state, latest);
+	applyTestIntegrityState(state, latest);
+	applyDebateState(state, latest);
+	applyRoundAndConsensusState(state, latest);
+	applyTraceState(state, latest);
+	applyRunContextState(state, latest, entries);
 	state.flowSubstate = deriveFlowSubstate(state);
 	return state;
 }

package/.pi/lib/plan-approval/dialog.ts

@@ -30,9 +30,14 @@ function toAskParams(
 	return {
 		question: "How would you like to proceed with this harness plan?",
 		context: buildPlanApprovalMarkdown(validated),
+		contextFormat: "markdown",
 		options: validated.options,
+		questions: [],
+		mode: "flat",
 		allowMultiple: false,
 		allowFreeform: false,
+		allowComment: false,
+		allowSkip: false,
 		// Inline prompt below the plan — no full-screen overlay.
 		displayMode: "inline",
 	};

package/.pi/lib/plan-approval/validate.ts

@@ -1,5 +1,5 @@
+import { formatResultText } from "../ask-user/format.js";
 import type { AskResponse } from "../ask-user/types.js";
-import { formatResultText } from "../ask-user/validate.js";
 import {
 	type PlanPacketLike,
 	validatePlanPacket,

package/.pi/lib/plan-approval-readiness.ts

@@ -6,6 +6,10 @@ import { constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import {
+	isTaskClarificationReady,
+	TASK_CLARIFICATION_ARTIFACT,
+} from "./plan-task-clarification.js";
 
 export interface PlanApprovalReadiness {
 	ok: boolean;
@@ -140,6 +144,14 @@ export async function validatePlanApprovalReadiness(
 	const risk = String(opts?.risk_level ?? "med").toLowerCase();
 	const quick = opts?.quick === true;
 
+	const clarReady = await isTaskClarificationReady(runDir);
+	if (!clarReady.ok) {
+		const waived = await hasPhaseWaiver(runDir, "missing:task-clarification");
+		if (!waived) {
+			errors.push(...clarReady.errors);
+		}
+	}
+
 	const statusPath = join(runDir, "artifacts", "plan-phase-status.yaml");
 	const statusDoc = await readYamlObject(statusPath);
 	if (statusDoc) {
@@ -160,6 +172,26 @@ export async function validatePlanApprovalReadiness(
 		errors,
 	);
 
+	if (hasPlanningContext) {
+		const ctxDoc = await readYamlObject(
+			join(runDir, PLANNING_CONTEXT_ARTIFACT),
+		);
+		const taskRef = String(ctxDoc?.task_ref ?? "").trim();
+		if (
+			taskRef &&
+			taskRef !== TASK_CLARIFICATION_ARTIFACT &&
+			!taskRef.endsWith("task-clarification.yaml")
+		) {
+			warnings.push(
+				`${PLANNING_CONTEXT_ARTIFACT}: task_ref should point at ${TASK_CLARIFICATION_ARTIFACT}`,
+			);
+		} else if (!taskRef) {
+			warnings.push(
+				`${PLANNING_CONTEXT_ARTIFACT}: set task_ref to ${TASK_CLARIFICATION_ARTIFACT}`,
+			);
+		}
+	}
+
 	if (!hasPlanningContext) {
 		const waived = await hasPhaseWaiver(
 			runDir,