ultimate-pi 0.10.1 → 0.12.0

package/.pi/agents/harness/planning/scout-semantic.md

@@ -0,0 +1,47 @@
+---
+description: Plan-phase scout — ck semantic code search (read-only).
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
+extensions: false
+thinking: low
+max_turns: 6
+---
+
+You are the **Harness planning scout (semantic lane)**.
+
+## Mission
+
+Find conceptually related code via ck semantic search for the task in `HarnessSpawnContext`. You do **not** build the PlanPacket or mutate files.
+
+## Spawn context
+
+Read `HarnessSpawnContext` in the spawn prompt. For `mode: revise`, bias searches toward delta areas from the existing plan at `plan_packet_path`.
+
+## Process
+
+1. Use `ck search` or `ck query` (or project-documented ck CLI) with task-focused queries.
+2. If ck is unavailable, set `status: partial` and document in `findings`.
+3. **Stop early** — top **5** most relevant paths only.
+
+## Bash guardrails
+
+Read-only only: no installs, index rebuilds that mutate disk, or redirects.
+
+## Output limits
+
+- `findings`: at most **6** bullets
+- `key_paths`: at most **8** absolute paths
+- `open_questions`: at most **4** items
+
+## Output (required JSON block)
+
+```json
+{
+  "schema_version": "1.0.0",
+  "lane": "semantic",
+  "status": "ok",
+  "findings": ["…"],
+  "key_paths": ["/absolute/path"],
+  "open_questions": ["…"]
+}
+```

package/.pi/agents/harness/planning/scout-structure.md

@@ -0,0 +1,50 @@
+---
+description: Plan-phase scout — ast-grep structural code search (read-only).
+tools: read, bash, ls
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
+extensions: false
+thinking: low
+max_turns: 6
+---
+
+You are the **Harness planning scout (structure lane)**.
+
+## Mission
+
+Find relevant code structure for the task using ast-grep (`sg`). You do **not** build the PlanPacket or mutate files.
+
+Findings should name **implementation surfaces** (handlers, types, exports, call sites) for hypothesis mechanism and experiment design.
+
+## Spawn context
+
+Read `HarnessSpawnContext` in the spawn prompt. For `mode: revise`, read the existing plan at `plan_packet_path` and focus on files and patterns affected by the revision.
+
+## Process
+
+1. Run `sg -p '…'` with patterns tied to the task (handlers, types, exports, call sites). **Do not use `find` or `grep`.**
+2. Prefer absolute paths in `key_paths`.
+3. If `sg` is not on PATH, set `status: partial` and note the tooling gap in `findings`.
+4. **Stop early** — target ≤6 tool calls when possible.
+
+## Bash guardrails
+
+Read-only only: no installs, redirects, or mutating git/npm commands.
+
+## Output limits
+
+- `findings`: at most **8** bullets
+- `key_paths`: at most **10** absolute paths
+- `open_questions`: at most **5** items
+
+## Output (required JSON block)
+
+```json
+{
+  "schema_version": "1.0.0",
+  "lane": "structure",
+  "status": "ok",
+  "findings": ["…"],
+  "key_paths": ["/absolute/path"],
+  "open_questions": ["…"]
+}
+```

package/.pi/agents/harness/planning/sprint-contract-auditor.md

@@ -0,0 +1,18 @@
+---
+description: Plan-phase ADR-020 sprint contract auditor.
+tools: read, grep, find, ls
+disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 10
+---
+
+You are **sprint-contract-auditor** — ADR-020 Sprint Contract, Done Criteria Types, checkpoints, Keep Quality Left.
+
+Required on debate **round 4**; optional spot-check round 2 if done_criteria sparse.
+
+## Output
+
+Valid **YAML only** — `PlanSprintAuditTurn` (`.pi/harness/specs/plan-sprint-audit-turn.schema.json`).
+
+Bus label: `SprintContractAuditorsubagent`.

package/.pi/agents/harness/planning/stack-researcher.md

@@ -0,0 +1,24 @@
+---
+description: Plan-phase stack research (ctx7 + web, read-only file writes via parent).
+tools: read, grep, find, ls, bash, web_search, web_fetch
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: medium
+max_turns: 14
+---
+
+You are **stack-researcher** — evidence-backed stack recommendations for harness planning.
+
+## Mission
+
+Produce `PlanStackBrief` with ranked options. For brownfield tasks, always include **extend current stack** as one ranked option.
+
+## Protocol
+
+1. **Libraries / APIs:** `ctx7 library` → `ctx7 docs` (read context7-cli skill). Cite library IDs in `evidence_refs`.
+2. **Comparisons / landscape:** `web_search` + `web_fetch` (`.web/` artifacts).
+3. **Greenfield:** ≥3 distinct options with pros/cons/risks.
+
+## Output
+
+Return valid **YAML only** (no fences) matching `PlanStackBrief` (`.pi/harness/specs/plan-stack-brief.schema.json`). Parent writes `artifacts/stack.yaml`.

package/.pi/agents/harness/tie-breaker.md

@@ -5,7 +5,6 @@ extensions: false
 disallowed_tools: ask_user
 thinking: high
 max_turns: 15
-inherit_context: false
 ---
 
 You are the Harness Tie-Breaker.

package/.pi/agents/harness/trace-librarian.md

@@ -4,7 +4,6 @@ tools: read, grep, find, ls
 extensions: false
 thinking: medium
 max_turns: 20
-inherit_context: false
 ---
 
 You are the Harness Trace Librarian.

package/.pi/extensions/debate-orchestrator.ts

@@ -14,16 +14,20 @@
  * }
  */
 
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type DebateParticipant,
+	debatePhaseFromId,
+	isPlanDebateId,
+	PLAN_DEBATE_PARTICIPANTS,
+	POST_EXECUTE_DEBATE_PARTICIPANTS,
+} from "../lib/debate-orchestrator-types.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 
-type DebateParticipant =
-	| "EvaluatorAgent"
-	| "AdversaryAgent"
-	| "TieBreakerAgent";
 type PolicyDecision = "pass" | "conditional_pass" | "block" | "human_required";
+type DebatePhase = "plan" | "post_execute";
 
 interface RoundPayload {
 	participants: DebateParticipant[];
@@ -46,11 +50,13 @@ interface RoundPayload {
 interface DebateState {
 	run_id: string;
 	debate_id: string;
+	debate_phase: DebatePhase;
 	round_count: number;
 	budget_used: number;
 	max_rounds: number;
 	round_token_cap: number;
 	debate_global_cap: number;
+	last_review_gate_ready?: boolean;
 }
 
 interface BusEnvelope<T = unknown> {
@@ -104,46 +110,39 @@ function getRunId(ctx: {
 	);
 }
 
-async function readRoundCapsFromSchema(): Promise<{
+const PLAN_BUDGET = {
+	max_rounds: 4,
+	round_token_cap: 2000,
+	debate_global_cap: 12000,
+} as const;
+
+const AGGRESSIVE_BUDGET = {
+	max_rounds: 6,
+	round_token_cap: 2500,
+	debate_global_cap: 35000,
+} as const;
+
+function capsForDebate(debateId: string): {
+	name: "plan" | "aggressive";
 	max_rounds: number;
 	round_token_cap: number;
 	debate_global_cap: number;
-}> {
-	try {
-		const roundSchemaPath = join(
-			process.cwd(),
-			".pi",
-			"harness",
-			"specs",
-			"round-result.schema.json",
+} {
+	if (isPlanDebateId(debateId)) {
+		return { name: "plan", ...PLAN_BUDGET };
+	}
+	return { name: "aggressive", ...AGGRESSIVE_BUDGET };
+}
+
+function participantAllowed(participant: string, phase: DebatePhase): boolean {
+	if (phase === "plan") {
+		return (PLAN_DEBATE_PARTICIPANTS as readonly string[]).includes(
+			participant,
 		);
-		const parsed = JSON.parse(await readFile(roundSchemaPath, "utf-8")) as {
-			properties?: {
-				budget_profile?: {
-					properties?: {
-						max_rounds?: { const?: number };
-						round_token_cap?: { const?: number };
-						debate_global_cap?: { const?: number };
-					};
-				};
-			};
-		};
-		return {
-			max_rounds: Number(
-				parsed?.properties?.budget_profile?.properties?.max_rounds?.const ?? 6,
-			),
-			round_token_cap: Number(
-				parsed?.properties?.budget_profile?.properties?.round_token_cap
-					?.const ?? 2500,
-			),
-			debate_global_cap: Number(
-				parsed?.properties?.budget_profile?.properties?.debate_global_cap
-					?.const ?? 35000,
-			),
-		};
-	} catch {
-		return { max_rounds: 6, round_token_cap: 2500, debate_global_cap: 35000 };
 	}
+	return (POST_EXECUTE_DEBATE_PARTICIPANTS as readonly string[]).includes(
+		participant,
+	);
 }
 
 async function writeDebateEvent(
@@ -197,13 +196,18 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 	let lastSeverity = defaultSeverity();
 
 	async function openDebate(runId: string, debateId: string): Promise<void> {
-		const caps = await readRoundCapsFromSchema();
+		const caps = capsForDebate(debateId);
+		const debate_phase = debatePhaseFromId(debateId);
 		state = {
 			run_id: runId,
 			debate_id: debateId,
+			debate_phase,
 			round_count: 0,
 			budget_used: 0,
-			...caps,
+			max_rounds: caps.max_rounds,
+			round_token_cap: caps.round_token_cap,
+			debate_global_cap: caps.debate_global_cap,
+			last_review_gate_ready: false,
 		};
 		pi.appendEntry("harness-debate-state", state);
 		const envelope: BusEnvelope = {
@@ -216,7 +220,8 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			},
 			payload: {
 				opened_at: nowIso(),
-				budget_profile: "aggressive",
+				debate_phase,
+				budget_profile: caps.name,
 			},
 		};
 		pi.appendEntry("harness-debate-envelope", envelope);
@@ -267,6 +272,15 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			return { ok: false, reason: "debate id mismatch" };
 		}
 
+		for (const p of envelope.payload.participants ?? []) {
+			if (!participantAllowed(p, state.debate_phase)) {
+				return {
+					ok: false,
+					reason: `participant ${p} invalid for debate_phase=${state.debate_phase}`,
+				};
+			}
+		}
+
 		const nextRound = state.round_count + 1;
 		if (nextRound > state.max_rounds) {
 			await emitBudgetExhausted("max_rounds_reached");
@@ -310,6 +324,11 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			};
 		}
 
+		const profileName =
+			state.debate_phase === "plan"
+				? ("plan" as const)
+				: ("aggressive" as const);
+
 		const roundRecord = {
 			schema_version: "1.0.0",
 			contract_version: "1.0.0",
@@ -322,7 +341,7 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			evidence_refs: envelope.payload.evidence_refs,
 			token_usage: envelope.payload.token_usage,
 			budget_profile: {
-				name: "aggressive",
+				name: profileName,
 				max_rounds: state.max_rounds,
 				round_token_cap: state.round_token_cap,
 				debate_global_cap: state.debate_global_cap,
@@ -354,12 +373,20 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			),
 		);
 		const decision = decidePolicy(lastSeverity, evidenceScore);
+		const planPhase = state.debate_phase === "plan";
+		const evaluatorPassed = planPhase
+			? Boolean(state.last_review_gate_ready)
+			: true;
+		const debateComplete = planPhase
+			? state.round_count >= state.max_rounds
+			: state.round_count > 0;
 
 		const consensus = {
 			schema_version: "1.0.0",
 			contract_version: "1.0.0",
 			run_id: state.run_id,
 			debate_id: state.debate_id,
+			debate_phase: state.debate_phase,
 			round_count: state.round_count,
 			budget_used: state.budget_used,
 			severity_scores: lastSeverity,
@@ -371,15 +398,25 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			},
 			confidence_weights: WEIGHTS,
 			evidence_refs: [],
-			strict_gate_prerequisites: {
-				plan_gate_passed: true,
-				execution_completed: true,
-				evaluator_passed: true,
-				adversarial_debate_completed: state.round_count > 0,
-				severity_policy_ok: decision !== "block",
-				benchmark_delta_checks_passed: false,
-				rollback_artifacts_generated: false,
-			},
+			strict_gate_prerequisites: planPhase
+				? {
+						plan_gate_passed: false,
+						execution_completed: false,
+						evaluator_passed: evaluatorPassed,
+						adversarial_debate_completed: debateComplete,
+						severity_policy_ok: decision !== "block",
+						benchmark_delta_checks_passed: false,
+						rollback_artifacts_generated: false,
+					}
+				: {
+						plan_gate_passed: true,
+						execution_completed: true,
+						evaluator_passed: true,
+						adversarial_debate_completed: debateComplete,
+						severity_policy_ok: decision !== "block",
+						benchmark_delta_checks_passed: false,
+						rollback_artifacts_generated: false,
+					},
 			policy_decision: decision,
 			rationale,
 		};

package/.pi/extensions/harness-ask-user.ts

@@ -18,8 +18,13 @@ import {
 	toToolDetails,
 	validateAskParams,
 } from "./lib/ask-user/validate.js";
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
 
 export default function harnessAskUser(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("harness-ask-user", MODULE_URL)) return;
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",

package/.pi/extensions/harness-plan-approval.ts

@@ -4,14 +4,25 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import type { PlanPacketLike } from "../lib/harness-run-context.js";
 import {
 	appendPlanApprovalIfNew,
 	getLatestRunContext,
 	hasPlanUserApproval,
 	parsePlanApprovalFromMessage,
+	planPacketSummary,
 } from "../lib/harness-run-context.js";
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import {
+	CREATE_PLAN_GUIDELINES,
+	CREATE_PLAN_SNIPPET,
+	executeCreatePlan,
+	formatCreatePlanResultText,
+} from "./lib/plan-approval/create-plan.js";
 import { runPlanApprovalDialog } from "./lib/plan-approval/dialog.js";
 import { runPlanApprovalFallback } from "./lib/plan-approval/fallback.js";
+import { writePlanReviewMarkdown } from "./lib/plan-approval/plan-review.js";
 import {
 	renderApprovePlanCall,
 	renderApprovePlanResult,
@@ -32,7 +43,21 @@ import {
 	validateApprovePlanParams,
 } from "./lib/plan-approval/validate.js";
 
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+const CreatePlanParamsSchema = Type.Object({
+	plan_packet: Type.Object(
+		{},
+		{
+			description:
+				"Approved PlanPacket to persist (same object as approve_plan).",
+		},
+	),
+});
+
 export default function harnessPlanApproval(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("harness-plan-approval", MODULE_URL)) return;
 	pi.registerMessageRenderer(
 		"harness-plan-draft",
 		(message, _options, theme) => {
@@ -61,7 +86,7 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 		name: "approve_plan",
 		label: "Approve Plan",
 		description:
-			"Present a PlanPacket for user approval with a scrollable plan view. Planners should prefer the subagent bridge; this registers the tool on parent sessions for non-interactive fallback.",
+			"Present a PlanPacket for user approval with a scrollable plan view. Parent /harness-plan orchestrator calls this after decomposition, hypothesis, and parallel reviews.",
 		promptSnippet: PROMPT_SNIPPET,
 		promptGuidelines: PROMPT_GUIDELINES,
 		parameters: ApprovePlanParamsSchema,
@@ -92,7 +117,7 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text",
-							text: `Plan ${planId} already approved in this harness run (planner subagent). Proceed with /harness-run.`,
+							text: `Plan ${planId} already approved in this harness run. Proceed with /harness-run.`,
 						},
 					],
 					details: {
@@ -111,14 +136,32 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 			const summary =
 				validated.human_summary?.trim() ||
 				`Plan ${planId} — pending your approval`;
+			const runCtx = getLatestRunContext(entries);
+			const projectRoot = process.cwd();
+			const reviewPath = await writePlanReviewMarkdown(
+				projectRoot,
+				runCtx,
+				validated.plan_packet,
+				{
+					human_summary: validated.human_summary,
+					research_brief: validated.research_brief,
+					status: "draft",
+				},
+			);
+			const draftContent =
+				reviewPath != null
+					? `${summary}\nEditor review: ${reviewPath}`
+					: summary;
 			pi.sendMessage({
 				customType: "harness-plan-draft",
-				content: summary,
+				content: draftContent,
 				display: true,
 				details: {
 					schema_version: "1.0.0",
 					plan_packet: validated.plan_packet,
 					human_summary: validated.human_summary ?? null,
+					research_brief: validated.research_brief ?? null,
+					plan_review_path: reviewPath,
 					shown_at: new Date().toISOString(),
 				},
 			});
@@ -153,6 +196,23 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				);
 			}
 
+			const approved =
+				!outcome.cancelled &&
+				outcome.response?.kind === "selection" &&
+				/^approve/i.test(outcome.response.selections[0] ?? "");
+			if (approved && runCtx) {
+				await writePlanReviewMarkdown(
+					projectRoot,
+					runCtx,
+					validated.plan_packet,
+					{
+						human_summary: validated.human_summary,
+						research_brief: validated.research_brief,
+						status: "approved",
+					},
+				);
+			}
+
 			const text = formatApprovePlanResultText(
 				outcome.response,
 				outcome.cancelled,
@@ -171,4 +231,78 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 			return renderApprovePlanResult(result, options, theme);
 		},
 	});
+
+	pi.registerTool({
+		name: "create_plan",
+		label: "Create Plan",
+		description:
+			"Write the approved PlanPacket to plan-packet.yaml for this harness run. Call only after approve_plan (Approve). Do not use write/edit.",
+		promptSnippet: CREATE_PLAN_SNIPPET,
+		promptGuidelines: CREATE_PLAN_GUIDELINES,
+		parameters: CreatePlanParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const validated = validateApprovePlanParams(params as ApprovePlanParams);
+			if (typeof validated === "string") {
+				return {
+					content: [{ type: "text", text: validated }],
+					details: { error: validated },
+					isError: true,
+				};
+			}
+
+			const entries = ctx.sessionManager.getEntries();
+			const runCtx = getLatestRunContext(entries);
+			const projectRoot = process.cwd();
+			const result = await executeCreatePlan(validated.plan_packet, {
+				projectRoot,
+				getParentEntries: () => entries,
+				getSubagentEntries: () => entries,
+				getParentRunContext: () => runCtx,
+				onCommitted: (updated, packet, planPath) => {
+					pi.appendEntry("harness-run-context", updated);
+					pi.appendEntry(
+						"harness-plan-packet",
+						planPacketSummary(packet, planPath, "ready"),
+					);
+				},
+			});
+
+			const text = formatCreatePlanResultText(result);
+			return {
+				content: [{ type: "text", text }],
+				details: result.ok
+					? { plan_path: result.planPath, plan_id: result.planId }
+					: { error: result.error },
+				isError: !result.ok,
+			};
+		},
+
+		renderCall(args, theme) {
+			const packet = (args as { plan_packet?: PlanPacketLike }).plan_packet;
+			const id = packet?.plan_id ?? "?";
+			return new Text(theme.fg("accent", `create_plan: ${id}`), 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as
+				| { plan_path?: string; error?: string }
+				| undefined;
+			if (details?.error) {
+				return new Text(
+					theme.fg("error", details.error ?? "create_plan failed"),
+					0,
+					0,
+				);
+			}
+			return new Text(
+				theme.fg(
+					"success",
+					`Wrote ${details?.plan_path ?? "plan-packet.yaml"}`,
+				),
+				0,
+				0,
+			);
+		},
+	});
 }