ultimate-pi 0.22.1 → 0.22.2

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,322 @@
+/**
+ * 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;
+
+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;
+	const humanGate = validateTaskClarificationHumanGate(entries, clarDoc, {
+		quick: opts?.quick,
+		taskSummary: opts?.taskSummary,
+		allowFollowUpMessage: opts?.lastOutcome === "needs_clarification",
+	});
+	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)";
+	}
+
+	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

package/.pi/scripts/generate-agents-policy-yaml.mjs

@@ -13,6 +13,53 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const AGENTS_DIR = join(ROOT, ".pi", "agents");
 const OUT = join(ROOT, ".pi", "harness", "agents.policy.yaml");
 
+/** Per-agent tool denials layered on kind defaults (ADR 0049). */
+const AGENT_TOOLS_DENY = {
+	"harness/planning/hypothesis-validator": [
+		"bash",
+		"grep",
+		"find",
+		"ls",
+		"ctx_batch_execute",
+		"ctx_execute",
+		"ctx_execute_file",
+		"ctx_search",
+		"ctx_fetch_and_index",
+	],
+	"harness/planning/implementation-researcher": [
+		"bash",
+		"find",
+		"ctx_batch_execute",
+		"ctx_execute",
+		"ctx_execute_file",
+	],
+	"harness/planning/stack-researcher": [
+		"bash",
+		"find",
+		"ctx_batch_execute",
+		"ctx_execute",
+		"ctx_execute_file",
+	],
+	"harness/planning/sprint-contract-auditor": [
+		"bash",
+		"find",
+		"ctx_batch_execute",
+		"ctx_execute",
+		"ctx_execute_file",
+		"ctx_fetch_and_index",
+	],
+	"harness/planning/review-integrator": [
+		"bash",
+		"grep",
+		"find",
+		"ctx_batch_execute",
+		"ctx_execute",
+		"ctx_execute_file",
+		"ctx_search",
+		"ctx_fetch_and_index",
+	],
+};
+
 const SUBMIT_BY_AGENT = {
 	"harness/planning/planning-context": ["submit_planning_context"],
 	"harness/planning/decompose": ["submit_decomposition_brief", "submit_human_required"],
@@ -60,14 +107,31 @@ function kindFor(id) {
 	return "other";
 }
 
+const READ_ONLY_BASE_TOOLS = [
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"bash",
+	"ctx_batch_execute",
+	"ctx_execute",
+	"ctx_execute_file",
+	"ctx_search",
+	"ctx_fetch_and_index",
+];
+
 const KIND_BASE = {
-	planner: ["read", "grep", "find", "ls"],
-	executor: ["read", "write", "edit", "bash", "grep", "find", "ls"],
-	evaluator: ["read", "grep", "find", "ls"],
-	adversary: ["read", "grep", "find", "ls"],
-	tie_breaker: ["read", "grep", "find", "ls"],
-	trace: ["read", "grep", "find", "ls"],
-	incident: ["read", "grep", "find", "ls"],
+	planner: [...READ_ONLY_BASE_TOOLS],
+	executor: [
+		...READ_ONLY_BASE_TOOLS,
+		"write",
+		"edit",
+	],
+	evaluator: [...READ_ONLY_BASE_TOOLS],
+	adversary: [...READ_ONLY_BASE_TOOLS],
+	tie_breaker: [...READ_ONLY_BASE_TOOLS],
+	trace: [...READ_ONLY_BASE_TOOLS],
+	incident: [...READ_ONLY_BASE_TOOLS],
 	other: ["read", "grep", "find", "ls"],
 };
 
@@ -117,6 +181,8 @@ async function main() {
 			(t) => !base.has(t),
 		);
 		const entry = { kind };
+		const toolsDeny = AGENT_TOOLS_DENY[id];
+		if (toolsDeny?.length) entry.tools_deny = toolsDeny;
 		if (toolsAdd.length > 0) entry.tools_add = toolsAdd;
 		if (fm.extensions === false) entry.extensions = false;
 		if (fm.extensions === true) entry.extensions = true;

package/.pi/scripts/harness-reconcile-run-context.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Reconcile run-context.yaml with on-disk plan + executor handoff (no Pi session).
+ * Usage: node .pi/scripts/harness-reconcile-run-context.mjs <run-id>
+ */
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const runId = process.argv[2];
+if (!runId) {
+	console.error("usage: node .pi/scripts/harness-reconcile-run-context.mjs <run-id>");
+	process.exit(1);
+}
+
+const dir = mkdtempSync(join(tmpdir(), "harness-reconcile-"));
+const runner = join(dir, "run.mts");
+writeFileSync(
+	runner,
+	`import {
+  reconcileStaleExecuteCompletion,
+  reconcileReviewRouting,
+  loadRunContextFromDisk,
+  saveRunContextToDisk,
+} from ${JSON.stringify(join(root, ".pi/lib/harness-run-context.ts"))};
+
+const root = ${JSON.stringify(root)};
+const runId = ${JSON.stringify(runId)};
+const ctx0 = await loadRunContextFromDisk(runId, root);
+if (!ctx0) {
+  console.error("run not found:", runId);
+  process.exit(1);
+}
+console.log("before", JSON.stringify({
+  phase: ctx0.phase,
+  step: ctx0.last_completed_step,
+  outcome: ctx0.last_outcome,
+  next: ctx0.next_recommended_command,
+}));
+let ctx1 = await reconcileStaleExecuteCompletion(root, ctx0, []);
+ctx1 = await reconcileReviewRouting(root, ctx1);
+await saveRunContextToDisk(ctx1, root);
+console.log("after", JSON.stringify({
+  phase: ctx1.phase,
+  step: ctx1.last_completed_step,
+  outcome: ctx1.last_outcome,
+  next: ctx1.next_recommended_command,
+}));
+`,
+	"utf-8",
+);
+
+const result = spawnSync("npx", ["-y", "tsx", runner], {
+	cwd: root,
+	encoding: "utf-8",
+	stdio: "inherit",
+});
+rmSync(dir, { recursive: true, force: true });
+process.exit(result.status ?? 1);

package/.pi/scripts/harness-schema-compile-verify.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Compile every harness JSON Schema (catches unresolved cross-file $ref).
+ * Invoked from harness-verify.mjs via `npx tsx`.
+ */
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	listHarnessSpecSchemaFiles,
+	verifyHarnessSchemaRefIntegrity,
+	verifyHarnessSchemasCompile,
+} from "../lib/harness-schema-validate.ts";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SPECS = join(ROOT, ".pi", "harness", "specs");
+
+const files = await listHarnessSpecSchemaFiles(SPECS);
+const integrity = await verifyHarnessSchemaRefIntegrity(SPECS);
+if (!integrity.ok) {
+	console.error(integrity.errors.join("\n"));
+	process.exit(1);
+}
+const compiled = await verifyHarnessSchemasCompile(SPECS, files);
+if (!compiled.ok) {
+	console.error(compiled.errors.join("\n"));
+	process.exit(1);
+}
+console.log(`harness-schema-compile-verify: ${files.length} schemas OK`);