ultimate-pi 0.22.0 → 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

@@ -5,13 +5,17 @@ argument-hint: "\"<task>\" [--risk low|med|high] [--quick]"
 
 # harness-plan
 
-You are the **planning orchestrator** (agent-native; ADR 0042). Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`) with **lake-sized** outcomes and path-first tools. Parent owns gates: `ask_user`, `approve_plan({ human_summary? })`, `create_plan()`, plan-verify, and scoped writes under `.pi/harness/runs/<run_id>/`.
+You are the **planning orchestrator**. Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`) with **lake-sized** outcomes and path-first tools. Parent owns gates: `ask_user`, `approve_plan({ human_summary? })`, `create_plan()`, plan-verify, and scoped writes under `.pi/harness/runs/<run_id>/`.
 
-**Practice map:** `.pi/harness/docs/practice-map.md` — phase → proven practice → agent → spawn topology.
+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.
 
-**Phase 0 is mandatory** before reconnaissance or any planning subagent. `write_harness_yaml` and spawn topology enforce `artifacts/task-clarification.yaml` with `status: ready` (ADR 0053).
+### 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
 
@@ -34,7 +38,7 @@ Read **harness-debate-plan** skill before Review Gate rounds.
 
 1. Parallel `tasks` only for **independent** merges (implementation ∥ stack research; plan-evaluator ∥ plan-adversary for `parallel_probes`). **Never** parallelize decompose ∥ hypothesis.
 2. Max **2** research lanes, **1** debate agent, **1** optional `planning-context` subagent per `subagent` call.
-3. Downstream agents **read** upstream artifacts — do not re-derive (see practice-map anti-patterns).
+3. Downstream agents **read** upstream artifacts — do not re-derive upstream work.
 
 ## Performance rules
 
@@ -57,7 +61,7 @@ Use `[HarnessActivePlan]` / `[HarnessRunContext]` only. On revise: preserve `pla
 
 ## Phase 0 — Task clarification (mandatory; parent-led)
 
-**Practice:** Collect requirements / pool of shared meaning before WBS (PMBOK; Crucial Conversations). **ADR 0053.**
+**Practice:** Collect requirements and shared meaning before WBS (PMBOK; Crucial Conversations).
 
 **Goal:** `artifacts/task-clarification.yaml` with `status: ready`, `unresolved_questions: []`, and a canonical `clarified_task`. No full planning until gated.
 
@@ -121,7 +125,7 @@ Decompose treats **`task-clarification.yaml` as authoritative** for scope; §1.1
 
 ## Phase 2b — Hypothesis-driven approach (sequential)
 
-**Practice:** Lean exploration — falsifiable claim before plan detail (DARWIN / ADR 0034).
+**Practice:** Lean exploration — require a falsifiable claim before plan detail.
 
 **Requires** `artifacts/decomposition.yaml`. Do **not** spawn in parallel with decompose.
 
@@ -262,7 +266,7 @@ Med/low non-fork plans with clear stack and no implementation `open_questions` d
 
 ## Phase 5 — Structured inspection / Review Gate (Fagan-style)
 
-**Practice:** Code Complete collaborative construction; Fagan inspection with rubrics in `.pi/harness/docs/planning-rubrics.md`. Parent is **chair**; one debate agent per `subagent` batch.
+**Practice:** Code Complete collaborative construction with Fagan-style inspection criteria. Parent is **chair**; one debate agent per `subagent` batch.
 
 **Forbidden:** parallel `subagent` calls for any debate lane agent in one batch.
 

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

@@ -7,7 +7,7 @@ argument-hint: "[--run <run-id>] [--quick] [--readonly] [--trace <trace-ref>]"
 
 You are the **post-run verification PM** (PMBOK Monitoring and Controlling). Run measure → judge → red team in one command. Parent owns `ask_user`, deterministic scripts, `harness_artifact_ready`, and run ownership (`--claim` on resume). Subagents persist via **`submit_*`** only (no parent `write` to verdict artifacts).
 
-**Practice map:** `.pi/harness/docs/practice-map.md`
+Follow the review sequence in this prompt directly: deterministic checks → benchmark evaluator → verdict evaluator → adversary → optional tie-breaker.
 
 Read **harness-orchestration** and **harness-review** skills before spawning.
 
@@ -91,7 +91,7 @@ notes: "…"
 
 ## Phase 1b — Sentrux repair advisor (subagent)
 
-**Practice:** Close the loop from fitness-function observation → bounded repair directives (ADR 0052). Skip when `artifacts/sentrux-repair-plan.yaml` already exists and `HARNESS_SENTRUX_RESCAN` is unset.
+**Practice:** Close the loop from fitness-function observation to bounded repair directives. Skip when `artifacts/sentrux-repair-plan.yaml` already exists and `HARNESS_SENTRUX_RESCAN` is unset.
 
 Spawn when **any**:
 
@@ -131,7 +131,7 @@ Gate:
 harness_artifact_ready({ paths: ["artifacts/eval-verdict.yaml"] })
 ```
 
-**Do not stop** after benchmark fail — continue to verdict (and adversary per tier) so `review-outcome.yaml` can route steer vs replan (ADR 0044).
+**Do not stop** after benchmark fail — continue to verdict (and adversary per tier) so `review-outcome.yaml` can route steer vs replan.
 
 ## Phase 3 — Policy / quality audit (verdict evaluator)
 
@@ -153,7 +153,7 @@ Gate again with `harness_artifact_ready`.
 
 ## Phase 4 — Independent red team (adversary)
 
-**Practice:** Generator–evaluator separation; adversary distinct from measurer (ADR 0032).
+**Practice:** Generator–evaluator separation; adversary stays distinct from the measurer.
 
 Skip when `--quick`. **Tiered steer:** full adversary on initial run + steer attempt 1; lite review (no adversary) on steer attempts 2+ unless prior `block_merge`.
 
@@ -185,7 +185,7 @@ subagent({ agentScope: "both", agent: "harness/reviewing/tie-breaker", task: "
 
 - **Never** parse subprocess JSON to write `eval-verdict.yaml` or `adversary-report.yaml` — use `submit_*` + `harness_artifact_ready` only.
 - Do not edit `plan-packet.yaml`.
-- Do not run inline review checks in this session (subagent isolation per ADR 0032).
+- Do not run inline review checks in this session (keep review work isolated to subagents).
 - Same Pi session as `/harness-run` is preferred; `--claim` makes cross-session resume work.
 
 ## Phase 6 — Review outcome + repair brief (parent)

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

@@ -4,7 +4,7 @@ description: Execute only against an approved PlanPacket with strict phase gates
 
 # harness-run
 
-**Practice map:** `.pi/harness/docs/practice-map.md`
+Follow this prompt's execution flow directly: baseline gate → executor spawn → structural observation → review handoff.
 
 You orchestrate the **Executing Process Group** — spawn `harness/running/executor` only. Do **not** implement inline.
 
@@ -106,7 +106,7 @@ phase: execute
 
 ## Parent rules
 
-- On `scope_drift`, finish handoff and recommend **`/harness-review`** (review classifies `plan_gap` vs `implementation_gap` — ADR 0044).
+- On `scope_drift`, finish handoff and recommend **`/harness-review`** (review classifies whether the gap is planning or implementation).
 - Do not call `ask_user` for plan-level ambiguity — return to plan command.
 
 ## Completion

package/.pi/prompts/harness-sentrux-steward.md

@@ -39,14 +39,14 @@ Gate: `harness_artifact_ready({ paths: ["artifacts/sentrux-manifest-proposal.yam
 Read `artifacts/sentrux-manifest-proposal.yaml`.
 
 - `change_class: none` → report no manifest change; stop.
-- Otherwise → `ask_user` with summary, evidence bullets, and `adr_draft` if `adr_required`.
+- Otherwise → `ask_user` with summary, evidence bullets, and any draft decision text when a formal decision record is required.
 
 On approval:
 
 1. Apply `manifest_patch` to `.pi/harness/sentrux/architecture.manifest.json` (parent `write` or manual edit).
 2. `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force`
 3. Append session custom entry `harness-architecture-changed` (triggers rules sync extension).
-4. If `adr_required`, file harness ADR snippet or `docs/adr/` entry per team convention.
+4. If a formal decision record is required, file it in the target project's standard decision-log location.
 
 On reject: keep manifest unchanged; document decision in run notes.
 

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

@@ -289,7 +289,7 @@ Quick smoke test:
 sg -p 'function $NAME($$$ARGS) { $$$BODY }' --json 2>/dev/null | head -5 && echo "✓ ast-grep pattern matching works" || echo "! ast-grep smoke test — may need language-specific config"
 ```
 
-### 2.7 — gh CLI (GitHub Issues Spec Storage — ADR-025)
+### 2.7 — gh CLI (GitHub Issues Spec Storage)
 
 ```bash
 if ! command -v gh &>/dev/null || [ "$FORCE" = "true" ]; then
@@ -335,7 +335,7 @@ Installed and smoke-tested by `harness-cli-verify.sh` (`npm install -g @ls-lint/
 
 ## Step 3 — Pi Extension Packages
 
-Bundled extensions load from the installed `ultimate-pi` package. The harness lens wrapper at `.pi/extensions/harness-lens.ts` loads `.pi/extensions/lib/harness-lens/` for edit autopatch, secrets blocking, deferred format, and LSP tools. Structural search uses shell `sg` (installed globally by setup); architecture gates use Sentrux. See [ADR 0045](.pi/harness/docs/adrs/0045-harness-lens-minimal-contract.md).
+Bundled extensions load from the installed `ultimate-pi` package. The harness lens wrapper at `.pi/extensions/harness-lens.ts` loads `.pi/extensions/lib/harness-lens/` for edit autopatch, secrets blocking, deferred format, and LSP tools. Structural search uses shell `sg` (installed globally by setup); architecture gates use Sentrux.
 
 Harness lens findings are **complementary** to Sentrux:
 
@@ -471,7 +471,7 @@ Harness `ask_user` supports terminal (TUI), headless (CI), and Glimpse WebView (
 | **Desktop Linux / macOS / WSLg** | `auto` or `glimpse` for richer questionnaires |
 | **CI / `--non-interactive`** | Prompts skipped; do not expect WebView |
 
-Append `HARNESS_ASK_USER_UI=tui` to `.env` when WebView is unavailable. The first real `ask_user` reports `ui_backend` and `ui_degraded` in tool details. See ADR 0054.
+Append `HARNESS_ASK_USER_UI=tui` to `.env` when WebView is unavailable. The first real `ask_user` reports `ui_backend` and `ui_degraded` in tool details.
 
 Template keys (placeholders — user fills secrets): `HARNESS_TELEMETRY_ENABLED`, `HARNESS_WEB_*`, `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`, plus commented optional PostHog / Graphify vars.
 

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

@@ -5,7 +5,7 @@ argument-hint: "[--attempt N]"
 
 # harness-steer
 
-Thin orchestrator for the **steer loop** (ADR 0044). Run only after `/harness-review` produced `artifacts/review-outcome.yaml` and `artifacts/repair-brief.yaml` with `remediation_class: implementation_gap`.
+Thin orchestrator for the **steer loop**. Run only after `/harness-review` produced `artifacts/review-outcome.yaml` and `artifacts/repair-brief.yaml` with `remediation_class: implementation_gap`.
 
 ## Preconditions
 
@@ -19,10 +19,10 @@ Thin orchestrator for the **steer loop** (ADR 0044). Run only after `/harness-re
 2. Update `artifacts/steer-state.yaml` (`attempt`, `max_attempts`, `active: true`).
 3. Set policy phase to **execute** before spawning executor (required for mutating tools).
 4. One `ask_user` steer gate unless `run-context.steer_approved` is already true.
-5. Spawn **`harness/running/executor`** with `HarnessSpawnContext.mode: repair` and `repair_brief_path: artifacts/repair-brief.yaml`. Repair uses the same hash-anchored `read`/`edit`, batching, and pre-handoff verification rules as `/harness-run` (ADR 0051).
-6. Optional: `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save` after repair to refresh baseline (ADR 0044).
-7. Optional: `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` after repair to confirm filename conventions (ADR 0052).
-7. `next_command`: **`/harness-review`** (always re-verify; tiered adversary on attempts 2+ per practice-map).
+5. Spawn **`harness/running/executor`** with `HarnessSpawnContext.mode: repair` and `repair_brief_path: artifacts/repair-brief.yaml`. Repair uses the same hash-anchored `read`/`edit`, batching, and pre-handoff verification rules as `/harness-run`.
+6. Optional: `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save` after repair to refresh the structural baseline.
+7. Optional: `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` after repair to confirm filename conventions.
+7. `next_command`: **`/harness-review`** (always re-verify; use tiered adversary on attempts 2+).
 
 ## Forbidden