ultimate-pi 0.16.0 → 0.18.0

package/.pi/agents/harness/planning/plan-synthesizer.md

@@ -0,0 +1,25 @@
+---
+name: harness/planning/plan-synthesizer
+description: Lake-first plan synthesis for low/med risk — problem framing, hypothesis, and execution_plan draft in one pass.
+---
+
+# Plan synthesizer
+
+You produce **lake-sized** outcomes (ADR 0042), not ticket-granularity WBS. Read `artifacts/planning-context.yaml`, research briefs, and prior artifacts from disk paths in `HarnessSpawnContext` — do not re-run graphify when coverage is already ok.
+
+## Outputs (all required on disk)
+
+1. **`submit_decomposition_brief`** → `artifacts/decomposition.yaml` — `core_tension`, `lakes[]` (outcome, scope boundary, verification intent), not a deep task tree.
+2. **`submit_hypothesis_brief`** → `artifacts/hypothesis.yaml` — falsifiable claim grounded in decomposition.
+3. **`submit_execution_plan_brief`** → `artifacts/execution-plan-draft.yaml` — lake-first `execution_plan` with `work_items` (each with `lake_id`, rich `description`, optional `context_bundle_path`), `executor_strategy` (`single_pass` for low, `per_lake` for med unless user dictates otherwise).
+
+## Rules
+
+- Use **`submit_*({ source_path })`** when drafts exist on disk (ADR 0043); otherwise `document`.
+- Do not spawn subprocesses; you are the subprocess.
+- Match schemas under `.pi/harness/specs/`.
+- Parent runs `validate-plan-dag.mjs` after merge into `plan-packet.yaml`.
+
+## High risk
+
+If `--risk high` or material fork, stop and tell parent to use sequential `decompose` → `hypothesis` → `execution-plan-author` instead.

package/.pi/agents/harness/planning/planning-context.md

@@ -0,0 +1,48 @@
+---
+description: Plan-phase optional reconnaissance subagent — graphify, sg, ccc (read-only). Prefer parent tool use.
+tools: read, bash, ls, submit_planning_context
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
+extensions: false
+thinking: low
+max_turns: 12
+---
+
+You are the **Harness planning-context gatherer** (optional Phase 1 subprocess).
+
+## When to use
+
+The **parent orchestrator** normally compiles `artifacts/planning-context.yaml` using tools directly. Spawn this agent only when reconnaissance is large enough to need a clean subprocess or context isolation.
+
+## Mission
+
+Compile merged reconnaissance for the task in `HarnessSpawnContext`. You do **not** build the PlanPacket, approve plans, or mutate anything.
+
+Use the repo tool hierarchy intelligently — pick tools that answer the task, not every tool by rote:
+
+1. **Architecture / relationships:** `graphify-out/GRAPH_REPORT.md`, then `graphify query`, `graphify explain`, `graphify path` (read-only).
+2. **Structure / symbols:** `sg -p '…'` — do not use `find` or `grep` for code search.
+3. **Semantic implementation:** `ccc search` (2–3 focused queries). The harness runs incremental `ccc index` before spawns — do **not** run `ccc index` or `ccc search --refresh`.
+
+Skip lanes that add no value for this task. Record skipped lanes in `coverage.<lane>.status: skipped`.
+
+## Spawn context
+
+Read `HarnessSpawnContext` (`task_summary`, `mode`, `plan_packet_path`, `risk_level`, `quick`). For `mode: revise`, read the existing plan first and focus on delta/risk areas.
+
+When `quick: true`, you may set `coverage.semantic.status: skipped`.
+
+## Bash guardrails
+
+Read-only only: no `graphify update`, installs, redirects (`>`, `>>`), or file creation.
+
+## Output
+
+Before ending, call `submit_planning_context` exactly once with a full `PlanPlanningContext` document:
+
+- `schema_version: "1.0.0"`
+- `status`: `ok` | `partial` | `failed`
+- `summary`: one paragraph
+- `coverage`: `architecture`, `structure`, and `semantic` (each with `status`, `tools_used`, `summary`, `key_paths` as applicable)
+- `findings`, `evidence_refs`, `open_questions`
+
+Do not paste the artifact as prose — the tool write is the deliverable.

package/.pi/agents/harness/planning/review-integrator.md

@@ -7,6 +7,8 @@ thinking: medium
 max_turns: 12
 ---
 
+**Inspection role:** Recorder / integration PM (round synthesis). Parent is chair. See `.pi/harness/docs/practice-map.md`.
+
 ## Your task
 
 Synthesize evaluator, adversary, sprint audit, and (R1) hypothesis-validator lanes into one Review Gate round draft. Decide `review_gate_ready` from evidence, not optimism.

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

@@ -1,5 +1,5 @@
 ---
-description: Plan-phase scout — graphify graph and wiki navigation (read-only).
+description: "[DEPRECATED — ADR 0041] Legacy graphify-only scout. Prefer parent tools + planning-context.yaml."
 tools: read, bash, ls, submit_scout_findings
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
@@ -7,6 +7,8 @@ thinking: low
 max_turns: 8
 ---
 
+> **Deprecated (ADR 0041):** The parent orchestrator should compile `artifacts/planning-context.yaml` using tools directly, or spawn `harness/planning/planning-context` once. This agent remains for backward compatibility only.
+
 You are the **Harness planning scout (graphify lane)**.
 
 ## Mission

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

@@ -1,5 +1,5 @@
 ---
-description: Plan-phase scout — CocoIndex semantic code search (read-only).
+description: "[DEPRECATED — ADR 0041] Legacy semantic-only scout. Prefer parent tools + planning-context.yaml."
 tools: read, bash, ls, submit_scout_findings
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
@@ -7,6 +7,8 @@ thinking: low
 max_turns: 6
 ---
 
+> **Deprecated (ADR 0041):** Prefer parent tool use or `harness/planning/planning-context`.
+
 You are the **Harness planning scout (semantic lane)**.
 
 ## Mission

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

@@ -1,5 +1,5 @@
 ---
-description: Plan-phase scout — ast-grep structural code search (read-only).
+description: "[DEPRECATED — ADR 0041] Legacy structure-only scout. Prefer parent tools + planning-context.yaml."
 tools: read, bash, ls, submit_scout_findings
 disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
@@ -7,6 +7,8 @@ thinking: low
 max_turns: 6
 ---
 
+> **Deprecated (ADR 0041):** Prefer parent tool use or `harness/planning/planning-context`.
+
 You are the **Harness planning scout (structure lane)**.
 
 ## Mission

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

@@ -7,6 +7,8 @@ thinking: medium
 max_turns: 12
 ---
 
+**Inspection role:** Definition of Done auditor (sprint contract). See `.pi/harness/docs/practice-map.md`.
+
 ## Your task
 
 Audit `execution_plan.sprint_contract` and work_item `done_criteria` against ADR-020 (Sprint Contract, Done Criteria Types, Keep Quality Left).

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

@@ -0,0 +1,51 @@
+---
+description: Propose architecture.manifest.json changes from graphify evidence (read-only governance steward).
+tools: read, grep, find, ls, bash, submit_sentrux_manifest_proposal
+disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
+extensions: false
+thinking: high
+max_turns: 16
+---
+
+You are the **Harness Sentrux Steward** — architectural **intent** governance, not setup or execution.
+
+**Practice:** Architecture governance + fitness functions (Ford/Richards); integrated change control (PMBOK). See `.pi/harness/docs/practice-map.md` phase 4e.
+
+## Mission
+
+Propose updates to `.pi/harness/sentrux/architecture.manifest.json` when the codebase or plan introduces a **new bounded context**, **new forbidden dependency class**, or **evidence-backed constraint tuning**. You never write the manifest, `rules.toml`, or merge patches yourself.
+
+## Spawn context
+
+Read `HarnessSpawnContext` (`run_id`, `run_dir`, `plan_packet_path`, `task_summary`, scope hints). Read `artifacts/planning-context.yaml` and `artifacts/execution-plan-draft.yaml` when paths are provided.
+
+## Protocol (graphify-first)
+
+1. Read `graphify-out/GRAPH_REPORT.md` — god nodes, communities, surprising edges for paths in scope.
+2. Run **targeted** read-only graphify (no `graphify update`):
+   - `graphify query "<module> coupling boundaries layers"`
+   - `graphify path "<concept A>" "<concept B>"` when proposing a new boundary
+   - `graphify explain "Modularity"` or `"Architecture governance"` for corpus-backed rationale
+3. Compare manifest layers/boundaries to plan scope and repo structure (`sg -p` for import edges when proposing boundaries).
+4. Optional: `sentrux check .` — cite violation messages only; do not fix code.
+5. Classify proposal:
+   - `none` — existing layer globs cover changes; no new coupling class
+   - `tune_constraint` — e.g. `max_cc` with sentrux/graphify evidence
+   - `add_boundary` — new forbidden import direction
+   - `add_layer` / `split_layer` — new bounded context or split overloaded layer
+
+## Output
+
+Call **`submit_sentrux_manifest_proposal`** before exit with document matching `sentrux-manifest-proposal.schema.json` → `artifacts/sentrux-manifest-proposal.yaml`.
+
+- `manifest_patch`: JSON Merge Patch against current manifest (minimal diff).
+- `evidence[]`: at least one entry per non-`none` change; prefer `source: graphify`.
+- `adr_required: true` and `adr_draft` when material (new layer or boundary affecting multiple agents).
+- `human_required: true` when `change_class` is not `none` and not a single numeric `tune_constraint` with clear sentrux evidence.
+
+## Guardrails
+
+- Read-only — no file mutations, no `harness-sentrux-bootstrap`, no `/harness-sentrux-sync`.
+- Do not duplicate full WBS decomposition — read planning artifacts instead.
+- Do not auto-sync rules from directory trees.
+- Never set `inherit_context: true`.

package/.pi/extensions/00-posthog-network-bootstrap.ts

@@ -0,0 +1,11 @@
+/**
+ * Load before other extensions: IPv4-first fetch for *.posthog.com (@posthog/pi uses global fetch).
+ */
+
+import { installPostHogFetchPatch } from "./lib/posthog-client.js";
+
+installPostHogFetchPatch();
+
+export default function posthogNetworkBootstrap() {
+	// Side effects run at module load; no hooks required.
+}

package/.pi/extensions/harness-debate-tools.ts

@@ -192,7 +192,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 		name: "harness_plan_debate_eligibility",
 		label: "Plan Debate Eligibility",
 		description:
-			"Pre-debate profile selection (full|standard|light). Call after DAG pass, before harness_debate_open. Uses risk, fork, implementation/stack briefs — not R1 hypothesis output.",
+			"Pre-debate profile selection (full|standard|light|fast). Call after DAG pass, before harness_debate_open. Uses risk, fork, implementation/stack briefs — not R1 hypothesis output.",
 		parameters: Type.Object({
 			risk_level: Type.Optional(
 				Type.String({ description: "low | med | high" }),
@@ -250,6 +250,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const result = harnessPlanDebateEligibility(input);
 			const lines = [
 				`profile: ${result.profile}`,
+				`review_gate_mode: ${result.review_gate_strategy.mode}`,
 				`required_focuses: ${result.required_focuses.join(", ")}`,
 				`min_focus_rounds: ${result.min_focus_rounds}`,
 				`debate_global_cap: ${result.debate_global_cap}`,
@@ -273,7 +274,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 				Type.String({ description: "Optional; normalized to plan-<run_id>" }),
 			),
 			debate_profile: Type.Optional(
-				Type.String({ description: "full | standard | light" }),
+				Type.String({ description: "full | standard | light | fast" }),
 			),
 			required_focuses: Type.Optional(
 				Type.Array(
@@ -297,7 +298,8 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const profile =
 				p.debate_profile === "full" ||
 				p.debate_profile === "standard" ||
-				p.debate_profile === "light"
+				p.debate_profile === "light" ||
+				p.debate_profile === "fast"
 					? p.debate_profile
 					: "standard";
 			const required_focuses = (p.required_focuses ?? []).filter((f) =>
@@ -308,11 +310,14 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 				required_focuses:
 					required_focuses.length > 0 ? required_focuses : undefined,
 			});
+			const review_gate_mode =
+				profile === "fast" ? ("consolidated" as const) : ("threaded" as const);
 			await initPlanMessenger(runDir(projectRoot, runId), {
 				runId,
 				debateId,
 				debate_profile: profile,
 				required_focuses: opened.required_focuses,
+				review_gate_mode,
 			});
 			const sessionId = ctx.sessionManager.getSessionId();
 			captureHarnessEvent(sessionId, "harness_debate_round", {
@@ -325,11 +330,15 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const lines = [
 				`Plan debate opened: ${debateId}`,
 				`Profile: ${profile}`,
+				`Review gate mode: ${review_gate_mode}`,
 				required_focuses.length
 					? `Required focuses: ${required_focuses.join(", ")}`
 					: opened.required_focuses?.length
 						? `Required focuses: ${opened.required_focuses.join(", ")}`
 						: "Required focuses: (default all four)",
+				review_gate_mode === "consolidated"
+					? "Consolidated path: one review round (artifacts/review-round-consolidated.yaml); escalate to threaded rounds only on blockers."
+					: "Threaded path: one review round per focus (spec → wbs → schedule → quality).",
 				`Messenger: debate-messenger/ (inbox + threads/round-N/transcript.jsonl)`,
 			];
 			if (warning) lines.push(`Note: ${warning}`);

package/.pi/extensions/harness-live-widget.ts

@@ -2,6 +2,7 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { evaluateCrossSessionResume } from "../lib/harness-run-context.js";
 import {
 	deriveHarnessStatusHint,
 	formatHarnessPhaseLabel,
@@ -283,6 +284,22 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		if (mountCtx) remountHarnessLiveWidget(mountCtx);
 	});
 
+	pi.events.on("harness-run-context:updated", () => {
+		stateStore.setCrossSessionResumeCommand(null);
+		if (mountCtx) scheduleRefresh(mountCtx);
+	});
+
+	pi.events.on("harness-cross-session-resume", (payload: unknown) => {
+		const data =
+			payload && typeof payload === "object"
+				? (payload as { resume_command?: string })
+				: null;
+		const cmd =
+			typeof data?.resume_command === "string" ? data.resume_command : null;
+		stateStore.setCrossSessionResumeCommand(cmd);
+		if (mountCtx) scheduleRefresh(mountCtx);
+	});
+
 	function updateStatusFallback(
 		ctx: ExtensionContext,
 		state: HarnessUiState,
@@ -304,6 +321,7 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 			policyDecision: state.policyDecision,
 			flowSubstate: state.flowSubstate,
 			nextRecommendedCommand: state.nextRecommendedCommand,
+			crossSessionResumeCommand: state.crossSessionResumeCommand,
 		});
 	}
 
@@ -322,9 +340,17 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		});
 	}
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
 		mountCtx = ctx;
 		mountHarnessWidget(ctx);
+		const info = await evaluateCrossSessionResume(
+			process.cwd(),
+			ctx.sessionManager.getEntries(),
+		);
+		if (info) {
+			stateStore.setCrossSessionResumeCommand(info.resumeCommand);
+			scheduleRefresh(ctx);
+		}
 	});
 
 	pi.on("context", (_event, ctx) => {

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

@@ -2,12 +2,8 @@
  * harness-plan-approval — PlanPacket approval UI and transcript renderer for parent sessions.
  */
 
-import { constants } from "node:fs";
-import { access } from "node:fs/promises";
-import { join } from "node:path";
 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,
@@ -33,8 +29,10 @@ import {
 	renderApprovePlanResult,
 	renderHarnessPlanDraft,
 } from "./lib/plan-approval/render.js";
+import { resolveApprovePlanParamsFromDisk } from "./lib/plan-approval/resolve-disk.js";
 import {
 	ApprovePlanParamsSchema,
+	CreatePlanParamsSchema,
 	PROMPT_GUIDELINES,
 	PROMPT_SNIPPET,
 } from "./lib/plan-approval/schema.js";
@@ -47,21 +45,12 @@ import {
 	toApprovePlanToolDetails,
 	validateApprovePlanParams,
 } from "./lib/plan-approval/validate.js";
+import { validatePlanApprovalReadiness } from "./lib/plan-approval-readiness.js";
 import { validatePlanDebateGate } from "./lib/plan-debate-gate.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(
@@ -103,12 +92,37 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 		parameters: ApprovePlanParamsSchema,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const validated = validateApprovePlanParams(params as ApprovePlanParams);
+			const entries = ctx.sessionManager.getEntries();
+			const projectRoot = process.cwd();
+			const resolved = await resolveApprovePlanParamsFromDisk(
+				params as ApprovePlanParams,
+				entries,
+				projectRoot,
+			);
+			if (!resolved.ok) {
+				return {
+					content: [{ type: "text", text: resolved.error }],
+					details: {
+						plan_packet: (params as ApprovePlanParams).plan_packet ?? {},
+						options: [],
+						response: null,
+						cancelled: true,
+					},
+					isError: true,
+				};
+			}
+			const validated = validateApprovePlanParams({
+				...(params as ApprovePlanParams),
+				plan_packet: resolved.plan_packet,
+				research_brief:
+					resolved.research_brief ??
+					(params as ApprovePlanParams).research_brief,
+			});
 			if (typeof validated === "string") {
 				return {
 					content: [{ type: "text", text: validated }],
 					details: {
-						plan_packet: (params as ApprovePlanParams).plan_packet ?? {},
+						plan_packet: resolved.plan_packet,
 						options: [],
 						response: null,
 						cancelled: true,
@@ -116,7 +130,6 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				};
 			}
 
-			const entries = ctx.sessionManager.getEntries();
 			if (
 				hasPlanUserApproval(entries, {
 					sincePlanCommand: true,
@@ -148,43 +161,33 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 				validated.human_summary?.trim() ||
 				`Plan ${planId} — pending your approval`;
 			const runCtx = getLatestRunContext(entries);
-			const projectRoot = process.cwd();
 			const implWarnings: string[] = [];
+			const risk = String(
+				validated.plan_packet.risk_level ?? "med",
+			).toLowerCase();
 			if (runCtx?.run_id) {
-				const implPath = join(
+				const readiness = await validatePlanApprovalReadiness(
 					projectRoot,
-					".pi",
-					"harness",
-					"runs",
 					runCtx.run_id,
-					"artifacts",
-					"implementation-research.yaml",
+					{ risk_level: risk },
 				);
-				let implExists = false;
-				try {
-					await access(implPath, constants.R_OK);
-					implExists = true;
-				} catch {
-					implExists = false;
-				}
-				const risk = String(
-					validated.plan_packet.risk_level ?? "med",
-				).toLowerCase();
-				if (!implExists) {
-					const msg =
-						"approve_plan: missing artifacts/implementation-research.yaml (Phase 3.5 required)";
-					if (risk === "high") {
-						return {
-							content: [{ type: "text", text: msg }],
-							details: {
-								plan_packet: validated.plan_packet,
-								cancelled: true,
+				if (!readiness.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `approve_plan blocked — plan phase not ready:\n- ${readiness.errors.join("\n- ")}`,
 							},
-							isError: true,
-						};
-					}
-					implWarnings.push(msg);
+						],
+						details: {
+							plan_packet: validated.plan_packet,
+							readiness,
+							cancelled: true,
+						},
+						isError: true,
+					};
 				}
+				implWarnings.push(...readiness.warnings);
 			}
 			if (runCtx?.run_id) {
 				const gate = await validatePlanDebateGate(projectRoot, runCtx.run_id);
@@ -308,19 +311,22 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 		parameters: CreatePlanParamsSchema,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const validated = validateApprovePlanParams(params as ApprovePlanParams);
-			if (typeof validated === "string") {
+			const entries = ctx.sessionManager.getEntries();
+			const runCtx = getLatestRunContext(entries);
+			const projectRoot = process.cwd();
+			const resolved = await resolveApprovePlanParamsFromDisk(
+				params as ApprovePlanParams,
+				entries,
+				projectRoot,
+			);
+			if (!resolved.ok) {
 				return {
-					content: [{ type: "text", text: validated }],
-					details: { error: validated },
+					content: [{ type: "text", text: resolved.error }],
+					details: { error: resolved.error },
 					isError: true,
 				};
 			}
-
-			const entries = ctx.sessionManager.getEntries();
-			const runCtx = getLatestRunContext(entries);
-			const projectRoot = process.cwd();
-			const result = await executeCreatePlan(validated.plan_packet, {
+			const result = await executeCreatePlan(resolved.plan_packet, {
 				projectRoot,
 				getParentEntries: () => entries,
 				getSubagentEntries: () => entries,