ultimate-pi 0.16.0 → 0.18.0

package/.pi/extensions/lib/harness-subprocess-bootstrap.ts

@@ -0,0 +1,73 @@
+/**
+ * Seed harness-run-context + policy-gate session entries in subagent subprocesses.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	getLatestRunContext,
+	type HarnessRunContext,
+	isHarnessSubprocess,
+	loadRunContextForSubprocess,
+	nowIso,
+	policyBootstrapFromRunContext,
+} from "../../lib/harness-run-context.js";
+
+type PolicyState = {
+	phase: "plan" | "execute" | "evaluate" | "adversary" | "merge";
+	approvedPlan: boolean;
+	planId: string | null;
+	budgetBypass: boolean;
+	aborted: boolean;
+	abortReason: string | null;
+	abortedAt: string | null;
+	updatedAt: string;
+};
+
+function defaultPolicyState(): PolicyState {
+	return {
+		phase: "plan",
+		approvedPlan: false,
+		planId: null,
+		budgetBypass: false,
+		aborted: false,
+		abortReason: null,
+		abortedAt: null,
+		updatedAt: nowIso(),
+	};
+}
+
+/** Append disk-backed run + policy entries when subprocess has no session context yet. */
+export async function bootstrapHarnessSubprocessFromEnv(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+): Promise<HarnessRunContext | null> {
+	if (!isHarnessSubprocess()) return null;
+	const entries = ctx.sessionManager.getEntries();
+	if (getLatestRunContext(entries)) return getLatestRunContext(entries);
+
+	const projectRoot = ctx.cwd;
+	const sessionId = ctx.sessionManager.getSessionId();
+	const disk = await loadRunContextForSubprocess(projectRoot);
+	if (!disk?.plan_ready) return null;
+
+	const runCtx: HarnessRunContext = {
+		...disk,
+		pi_session_id: sessionId,
+	};
+	pi.appendEntry("harness-run-context", runCtx);
+
+	const boot = policyBootstrapFromRunContext(runCtx);
+	const policy: PolicyState = {
+		...defaultPolicyState(),
+		phase: boot.phase,
+		approvedPlan: boot.approvedPlan,
+		planId: boot.planId,
+		updatedAt: nowIso(),
+	};
+	pi.appendEntry("harness-policy-state", policy);
+
+	return runCtx;
+}

package/.pi/extensions/lib/plan-approval/create-plan.ts

@@ -12,12 +12,11 @@ import {
 import { writeYamlFile } from "../../../lib/harness-yaml.js";
 import { writePlanReviewMarkdown } from "./plan-review.js";
 
-export const CREATE_PLAN_SNIPPET =
-	"create_plan({ plan_packet: { ...approved PlanPacket } })";
+export const CREATE_PLAN_SNIPPET = "create_plan()";
 
 export const CREATE_PLAN_GUIDELINES = [
 	"Call create_plan only after the user approves via approve_plan (Approve selection).",
-	"Pass the same plan_packet you showed in approve_plan — path is resolved automatically.",
+	"Uses plan-packet.yaml on disk at plan_packet_path (path-first; no inline packet).",
 	"Never use write or edit for plan-packet.yaml; create_plan is the only allowed plan write.",
 ];
 

package/.pi/extensions/lib/plan-approval/resolve-disk.ts

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import {
+	canonicalPlanPath,
+	getLatestRunContext,
+	harnessRunsRoot,
+	type PlanPacketLike,
+	RESEARCH_BRIEF_BASENAME,
+	readPlanPacketFromPath,
+	validatePlanPacket,
+} from "../../../lib/harness-run-context.js";
+import { readYamlFile } from "../../../lib/harness-yaml.js";
+import type { ApprovePlanParams, PlanResearchBrief } from "./types.js";
+
+function isNonEmptyPacket(
+	packet: PlanPacketLike | null | undefined,
+): packet is PlanPacketLike {
+	return Boolean(
+		packet &&
+			typeof packet === "object" &&
+			Object.keys(packet).length > 0 &&
+			packet.plan_id,
+	);
+}
+
+export async function loadResearchBriefFromRun(
+	runId: string,
+	projectRoot: string,
+): Promise<PlanResearchBrief | undefined> {
+	try {
+		const path = join(
+			harnessRunsRoot(projectRoot),
+			runId,
+			RESEARCH_BRIEF_BASENAME,
+		);
+		return (await readYamlFile(
+			path,
+			RESEARCH_BRIEF_BASENAME,
+		)) as PlanResearchBrief;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Path-first approve_plan: load packet + research brief from active run dir. */
+export async function resolveApprovePlanParamsFromDisk(
+	params: ApprovePlanParams,
+	entries: unknown[],
+	projectRoot: string,
+): Promise<
+	| {
+			ok: true;
+			plan_packet: PlanPacketLike;
+			research_brief?: PlanResearchBrief;
+	  }
+	| { ok: false; error: string }
+> {
+	const inline = params.plan_packet;
+	if (isNonEmptyPacket(inline)) {
+		const validation = validatePlanPacket(inline);
+		if (!validation.valid) {
+			return {
+				ok: false,
+				error: `approve_plan: invalid plan_packet — ${validation.errors.join("; ")}`,
+			};
+		}
+		return {
+			ok: true,
+			plan_packet: inline,
+			research_brief: params.research_brief ?? undefined,
+		};
+	}
+
+	const runCtx = getLatestRunContext(entries);
+	if (!runCtx?.run_id) {
+		return {
+			ok: false,
+			error:
+				'approve_plan: no active harness run. Run /harness-plan "<task>" first.',
+		};
+	}
+	const planPath =
+		runCtx.plan_packet_path ?? canonicalPlanPath(runCtx.run_id, projectRoot);
+	const packet = await readPlanPacketFromPath(planPath);
+	if (!isNonEmptyPacket(packet)) {
+		return {
+			ok: false,
+			error:
+				"approve_plan: plan_packet missing on disk. Write plan-packet.yaml draft before approve_plan.",
+		};
+	}
+	const validation = validatePlanPacket(packet);
+	if (!validation.valid) {
+		return {
+			ok: false,
+			error: `approve_plan: invalid plan_packet on disk — ${validation.errors.join("; ")}`,
+		};
+	}
+	const research_brief =
+		params.research_brief ??
+		(await loadResearchBriefFromRun(runCtx.run_id, projectRoot));
+	return { ok: true, plan_packet: packet, research_brief };
+}

package/.pi/extensions/lib/plan-approval/schema.ts

@@ -1,12 +1,14 @@
 import { Type } from "@sinclair/typebox";
 
 export const ApprovePlanParamsSchema = Type.Object({
-	plan_packet: Type.Object(
-		{},
-		{
-			description:
-				"Full PlanPacket object (schema_version, plan_id, task_id, scope, assumptions, risk_level, acceptance_checks, rollback_plan).",
-		},
+	plan_packet: Type.Optional(
+		Type.Object(
+			{},
+			{
+				description:
+					"Optional inline PlanPacket (deprecated). Default: read plan-packet.yaml from active run (ADR 0043).",
+			},
+		),
 	),
 	human_summary: Type.Optional(
 		Type.String({
@@ -45,10 +47,22 @@ export const ApprovePlanParamsSchema = Type.Object({
 });
 
 export const PROMPT_SNIPPET =
-	"approve_plan({ plan_packet: { ...PlanPacket fields... }, human_summary?: string, research_brief?: { decomposition, hypothesis, eval } })";
+	"approve_plan({ human_summary?: string }) — loads plan-packet.yaml from active run";
 
 export const PROMPT_GUIDELINES = [
-	"Call approve_plan once with the complete plan_packet when ready for user approval.",
+	"Call approve_plan once when plan-packet.yaml is on disk (path-first; do not embed full packet in tool args).",
 	"Use ask_user only for clarification — not for final plan approval.",
 	"On Request changes, revise the plan and call approve_plan again.",
 ];
+
+export const CreatePlanParamsSchema = Type.Object({
+	plan_packet: Type.Optional(
+		Type.Object(
+			{},
+			{
+				description:
+					"Optional inline packet (deprecated). Default: read approved plan from plan_packet_path.",
+			},
+		),
+	),
+});

package/.pi/extensions/lib/plan-approval/types.ts

@@ -22,7 +22,7 @@ export interface PlanResearchBrief {
 }
 
 export interface ApprovePlanParams {
-	plan_packet: PlanPacketLike;
+	plan_packet?: PlanPacketLike;
 	human_summary?: string;
 	research_brief?: PlanResearchBrief | null;
 	options?: Array<string | { title: string; description?: string }>;

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

@@ -15,8 +15,8 @@ export function validateApprovePlanParams(
 	params: ApprovePlanParams,
 ): ValidatedApprovePlanParams | string {
 	const packet = params.plan_packet;
-	if (!packet || typeof packet !== "object") {
-		return "approve_plan: plan_packet object is required.";
+	if (!packet || typeof packet !== "object" || !packet.plan_id) {
+		return "approve_plan: plan_packet must be resolved from disk before validate (use resolveApprovePlanParamsFromDisk).";
 	}
 	const validation = validatePlanPacket(packet as PlanPacketLike);
 	if (!validation.valid) {

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

@@ -0,0 +1,241 @@
+/**
+ * Pre-approve_plan readiness checks (artifacts, scouts, phase status).
+ */
+
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export interface PlanApprovalReadiness {
+	ok: boolean;
+	errors: string[];
+	warnings: string[];
+}
+
+const LEGACY_SCOUT_ARTIFACTS = [
+	"artifacts/scout-graphify.yaml",
+	"artifacts/scout-structure.yaml",
+	"artifacts/scout-semantic.yaml",
+] as const;
+
+const PLANNING_CONTEXT_ARTIFACT = "artifacts/planning-context.yaml";
+
+const PHASE35_ARTIFACTS = [
+	"artifacts/implementation-research.yaml",
+	"artifacts/stack.yaml",
+] as const;
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function readYamlObject(
+	path: string,
+): Promise<Record<string, unknown> | null> {
+	try {
+		const raw = await readFile(path, "utf-8");
+		const doc = parseYaml(raw) as unknown;
+		return doc && typeof doc === "object" && !Array.isArray(doc)
+			? (doc as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+async function hasPhaseWaiver(
+	runDir: string,
+	reason: string,
+): Promise<boolean> {
+	const path = join(runDir, "artifacts", "plan-phase-waiver.yaml");
+	const doc = await readYamlObject(path);
+	if (!doc) return false;
+	const waived = doc.waived as unknown;
+	if (!Array.isArray(waived)) return false;
+	return waived.some((w) => {
+		if (!w || typeof w !== "object") return false;
+		const entry = w as Record<string, unknown>;
+		return String(entry.reason ?? "") === reason;
+	});
+}
+
+function artifactStatusBad(
+	doc: Record<string, unknown> | null,
+	label: string,
+): string | null {
+	const status = String(doc?.status ?? "ok").toLowerCase();
+	if (status === "partial" || status === "failed" || status === "error") {
+		return `${label}: status "${status}" without waiver`;
+	}
+	return null;
+}
+
+function coverageLaneStatus(
+	doc: Record<string, unknown> | null,
+	lane: string,
+): string {
+	const coverage = doc?.coverage as Record<string, unknown> | undefined;
+	if (!coverage || typeof coverage !== "object") return "";
+	const laneDoc = coverage[lane] as Record<string, unknown> | undefined;
+	return String(laneDoc?.status ?? "").toLowerCase();
+}
+
+async function validateLegacyScouts(
+	runDir: string,
+	quick: boolean,
+	errors: string[],
+	warnings: string[],
+): Promise<boolean> {
+	let anyPresent = false;
+	for (const rel of LEGACY_SCOUT_ARTIFACTS) {
+		if (rel === "artifacts/scout-semantic.yaml" && quick) continue;
+		const abs = join(runDir, rel);
+		if (!(await fileExists(abs))) {
+			const waived = await hasPhaseWaiver(runDir, `missing:${rel}`);
+			if (!waived) {
+				errors.push(`missing ${rel}`);
+			}
+			continue;
+		}
+		anyPresent = true;
+		const doc = await readYamlObject(abs);
+		const bad = artifactStatusBad(doc, rel);
+		if (bad) {
+			const waived = await hasPhaseWaiver(
+				runDir,
+				`scout:${rel}:${String(doc?.status ?? "")}`,
+			);
+			if (!waived) {
+				errors.push(bad);
+			}
+		}
+	}
+	if (anyPresent) {
+		warnings.push(
+			"legacy scout YAML artifacts detected — prefer artifacts/planning-context.yaml (see ADR 0041)",
+		);
+	}
+	return anyPresent;
+}
+
+async function validatePlanningContext(
+	runDir: string,
+	quick: boolean,
+	errors: string[],
+): Promise<boolean> {
+	const rel = PLANNING_CONTEXT_ARTIFACT;
+	const abs = join(runDir, rel);
+	if (!(await fileExists(abs))) {
+		return false;
+	}
+	const doc = await readYamlObject(abs);
+	const bad = artifactStatusBad(doc, rel);
+	if (bad) {
+		const waived = await hasPhaseWaiver(
+			runDir,
+			`planning-context:${String(doc?.status ?? "")}`,
+		);
+		if (!waived) {
+			errors.push(bad);
+		}
+	}
+	const arch = coverageLaneStatus(doc, "architecture");
+	const structure = coverageLaneStatus(doc, "structure");
+	if (arch !== "ok" && arch !== "partial") {
+		errors.push(
+			`${rel}: coverage.architecture.status must be ok or partial (got "${arch || "missing"}")`,
+		);
+	}
+	if (structure !== "ok" && structure !== "partial") {
+		errors.push(
+			`${rel}: coverage.structure.status must be ok or partial (got "${structure || "missing"}")`,
+		);
+	}
+	if (!quick) {
+		const semantic = coverageLaneStatus(doc, "semantic");
+		if (
+			semantic &&
+			semantic !== "ok" &&
+			semantic !== "partial" &&
+			semantic !== "skipped"
+		) {
+			errors.push(
+				`${rel}: coverage.semantic.status must be ok, partial, or skipped (got "${semantic}")`,
+			);
+		}
+	}
+	return true;
+}
+
+export async function validatePlanApprovalReadiness(
+	projectRoot: string,
+	runId: string,
+	opts?: { risk_level?: string; quick?: boolean },
+): Promise<PlanApprovalReadiness> {
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const risk = String(opts?.risk_level ?? "med").toLowerCase();
+	const quick = opts?.quick === true;
+
+	const statusPath = join(runDir, "artifacts", "plan-phase-status.yaml");
+	const statusDoc = await readYamlObject(statusPath);
+	if (statusDoc) {
+		const planStatus = String(statusDoc.plan_status ?? "").toLowerCase();
+		if (planStatus === "partial" || planStatus === "needs_clarification") {
+			const waived = await hasPhaseWaiver(runDir, `plan_status:${planStatus}`);
+			if (!waived) {
+				errors.push(
+					`plan phase status is "${planStatus}" — resolve gaps, set plan_status ready, or write artifacts/plan-phase-waiver.yaml`,
+				);
+			}
+		}
+	}
+
+	const hasPlanningContext = await validatePlanningContext(
+		runDir,
+		quick,
+		errors,
+	);
+	const hasLegacyScouts = hasPlanningContext
+		? false
+		: await validateLegacyScouts(runDir, quick, errors, warnings);
+
+	if (!hasPlanningContext && !hasLegacyScouts) {
+		const waived = await hasPhaseWaiver(
+			runDir,
+			"missing:planning-reconnaissance",
+		);
+		if (!waived) {
+			errors.push(
+				`missing ${PLANNING_CONTEXT_ARTIFACT} (or legacy scout-graphify/structure/semantic trio)`,
+			);
+		}
+	}
+
+	for (const rel of PHASE35_ARTIFACTS) {
+		const abs = join(runDir, rel);
+		if (!(await fileExists(abs))) {
+			if (risk === "high" || risk === "med") {
+				errors.push(`missing ${rel} (Phase 3.5 required for risk ${risk})`);
+			} else {
+				warnings.push(`missing ${rel} (recommended for risk ${risk})`);
+			}
+		}
+	}
+
+	if (!(await fileExists(join(runDir, "artifacts/decomposition.yaml")))) {
+		errors.push("missing artifacts/decomposition.yaml");
+	}
+	if (!(await fileExists(join(runDir, "artifacts/hypothesis.yaml")))) {
+		errors.push("missing artifacts/hypothesis.yaml");
+	}
+
+	return { ok: errors.length === 0, errors, warnings };
+}

package/.pi/extensions/lib/plan-debate-eligibility.ts

@@ -4,7 +4,7 @@
 
 import { PLAN_FOCUS_AREAS, type PlanDebateFocus } from "./plan-debate-focus.js";
 
-export type DebateProfile = "full" | "standard" | "light";
+export type DebateProfile = "full" | "standard" | "light" | "fast";
 
 export interface DebateEligibilityInput {
 	risk_level?: string;
@@ -26,6 +26,7 @@ export interface DebateEligibilityResult {
 	debate_global_cap: number;
 	human_required: boolean;
 	rationale: string[];
+	review_gate_strategy: PlanReviewGateStrategy;
 }
 
 const LIGHT_FOCUS: PlanDebateFocus[] = ["spec", "quality"];
@@ -75,7 +76,7 @@ function confidenceAllowsLight(brief: Record<string, unknown> | null): boolean {
 	if (!rationale || refs.length < 2) return false;
 	if (implementationOpenQuestions(brief).length > 0) return false;
 	const patterns = Array.isArray(brief?.solution_patterns)
-		? (brief!.solution_patterns as unknown[])
+		? (brief?.solution_patterns as unknown[])
 		: [];
 	for (const p of patterns) {
 		const pat = asRecord(p);
@@ -85,7 +86,7 @@ function confidenceAllowsLight(brief: Record<string, unknown> | null): boolean {
 		}
 	}
 	const similar = Array.isArray(brief?.similar_implementations)
-		? (brief!.similar_implementations as unknown[])
+		? (brief?.similar_implementations as unknown[])
 		: [];
 	if (similar.length === 0) return false;
 	return true;
@@ -116,17 +117,46 @@ export const PLAN_BUDGET_LIGHT = {
 	debate_global_cap: 40000,
 } as const;
 
+export const PLAN_BUDGET_FAST = {
+	min_focus_rounds: 1,
+	max_rounds: 2,
+	max_exchanges_per_round: 1,
+	round_token_cap: 3500,
+	debate_global_cap: 20000,
+} as const;
+
+export interface PlanReviewGateStrategy {
+	mode: "consolidated" | "threaded" | "parallel_probes";
+	profile: DebateProfile;
+	required_focuses: PlanDebateFocus[];
+	min_focus_rounds: number;
+	max_rounds: number;
+	max_exchanges_per_round: number;
+	round_token_cap: number;
+	debate_global_cap: number;
+	rationale: string[];
+}
+
 function capsForProfile(
 	profile: DebateProfile,
 ): Omit<
 	DebateEligibilityResult,
-	"profile" | "required_focuses" | "human_required" | "rationale"
+	| "profile"
+	| "required_focuses"
+	| "human_required"
+	| "rationale"
+	| "review_gate_strategy"
 > {
 	if (profile === "light") {
 		return {
 			...PLAN_BUDGET_LIGHT,
 		};
 	}
+	if (profile === "fast") {
+		return {
+			...PLAN_BUDGET_FAST,
+		};
+	}
 	return {
 		...PLAN_BUDGET_STANDARD,
 	};
@@ -161,7 +191,7 @@ export function harnessPlanDebateEligibility(
 
 	const conflictingPatterns =
 		Array.isArray(impl?.solution_patterns) &&
-		(impl!.solution_patterns as unknown[]).length >= 2 &&
+		(impl?.solution_patterns as unknown[]).length >= 2 &&
 		openQs.length > 0;
 	if (conflictingPatterns) {
 		human_required = true;
@@ -182,6 +212,18 @@ export function harnessPlanDebateEligibility(
 		rationale.push(
 			"full: high risk, material fork, open questions, DAG patch, or tensions",
 		);
+	} else if (
+		risk === "med" &&
+		!materialFork &&
+		!dagPatched &&
+		input.dag_pass !== false &&
+		openQs.length === 0 &&
+		stackHasClearPrimary(stack)
+	) {
+		profile = "fast";
+		rationale.push(
+			"fast: medium risk with clear stack and no open questions; use consolidated review with escalation on blockers",
+		);
 	} else if (
 		risk === "low" &&
 		!materialFork &&
@@ -192,7 +234,7 @@ export function harnessPlanDebateEligibility(
 	) {
 		profile = "light";
 		rationale.push(
-			"light: low risk, clear stack, high-confidence implementation approach",
+			"light: low risk, clear stack, high-confidence implementation (threaded spec+quality)",
 		);
 	} else if (risk === "med") {
 		profile = "standard";
@@ -200,7 +242,9 @@ export function harnessPlanDebateEligibility(
 	}
 
 	const required_focuses: PlanDebateFocus[] =
-		profile === "light" ? [...LIGHT_FOCUS] : [...PLAN_FOCUS_AREAS];
+		profile === "fast" || profile === "light"
+			? [...LIGHT_FOCUS]
+			: [...PLAN_FOCUS_AREAS];
 
 	const caps = capsForProfile(profile);
 
@@ -210,5 +254,21 @@ export function harnessPlanDebateEligibility(
 		...caps,
 		human_required,
 		rationale,
+		review_gate_strategy: {
+			mode:
+				profile === "fast"
+					? "consolidated"
+					: profile === "standard"
+						? "parallel_probes"
+						: "threaded",
+			profile,
+			required_focuses: [...required_focuses],
+			min_focus_rounds: caps.min_focus_rounds,
+			max_rounds: caps.max_rounds,
+			max_exchanges_per_round: caps.max_exchanges_per_round,
+			round_token_cap: caps.round_token_cap,
+			debate_global_cap: caps.debate_global_cap,
+			rationale: [...rationale],
+		},
 	};
 }