ultimate-pi 0.17.0 → 0.18.1

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/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/{adversary.md → reviewing/adversary.md}

@@ -30,13 +30,6 @@ Pressure-test the candidate with adversarial reasoning and reproducible attacks.
 
 ## Output
 
-```json
-{
-  "block_merge": false,
-  "adversary_report": { },
-  "human_summary": "…",
-  "recommendation": "proceed"
-}
-```
-
-Use `recommendation`: `proceed`, `conditional_pass`, or `block`.
+Call **`submit_adversary_report`** before exit (writes `artifacts/adversary-report.yaml`). Do not emit prose-only JSON for the parent to copy onto disk.
+
+Use `recommendation`: `proceed`, `conditional_pass`, or `block`. Set `block_merge: true` when merge must halt.

package/.pi/agents/harness/{evaluator.md → reviewing/evaluator.md}

@@ -17,7 +17,7 @@ Independently validate execution outcomes and emit structured verdicts. Spawn co
 
 1. Read `HarnessSpawnContext` and artifact paths (`plan_packet_path`, `run_dir`, trace refs).
 2. Reconstruct validation scope from the plan and on-disk run artifacts.
-3. For `benchmark` mode: run or summarize deterministic checks (project tests, harness-verify if instructed in spawn prompt); collect metrics only you measured.
+3. For `benchmark` mode: run or summarize deterministic checks (project tests, harness-verify if instructed in spawn prompt); read `artifacts/sentrux-signal.yaml` and `artifacts/benchmark-log.yaml` when present — cite `check_pass`, `gate_status`, and `quality_signal_summary` as measured structural actuals (do not treat as optimization targets for the executor).
 4. For `verdict` mode: emit `EvalVerdict` matching `.pi/harness/specs/eval-verdict.schema.json`.
 5. Recommend only: `proceed_to_adversary`, `replan`, or `rollback`.
 6. Set `human_required` in structured output when blocked; never call `ask_user`.
@@ -31,15 +31,6 @@ Independently validate execution outcomes and emit structured verdicts. Spawn co
 
 ## Output
 
-End with a fenced `json` block:
+Call **`submit_eval_verdict`** before exit with a document matching `eval-verdict.schema.json` (writes `artifacts/eval-verdict.yaml` under the run dir). Do not ask the parent to parse JSON or write verdict files.
 
-```json
-{
-  "eval_status": "pass",
-  "eval_verdict": { },
-  "human_summary": "…",
-  "recommended_action": "proceed_to_adversary"
-}
-```
-
-Use `eval_status`: `pass`, `conditional_pass`, or `fail`.
+Use `status`: `pass`, `conditional_pass`, or `fail`. `recommended_action`: `proceed_to_adversary`, `replan`, or `rollback`.

package/.pi/agents/harness/running/executor.md

@@ -0,0 +1,45 @@
+---
+description: Harness executor that implements only within approved PlanPacket scope.
+tools: read, write, edit, bash, grep, find, ls, submit_executor_handoff
+extensions: true
+disallowed_tools: ask_user
+thinking: medium
+max_turns: 20
+---
+
+You are the Harness Executor.
+
+## Mission
+
+Implement the approved plan with surgical diffs and strict scope control. The parent orchestrator spawned you with a `HarnessSpawnContext` appendix — use `plan_packet_path`, `run_dir`, and acceptance checks from that JSON.
+
+## Repair mode (`mode: repair`)
+
+When spawn context sets `mode: repair`, read `repair_brief_path` (typically `artifacts/repair-brief.yaml`). Fix only what the brief lists — failed acceptance checks, `fix_directives`, and `priority_lake_ids`. Do **not** widen scope beyond `plan_packet_path`. Set `repair_attempt` in handoff metadata when the schema allows.
+
+## Process
+
+1. Read the approved `PlanPacket` at `plan_packet_path` from spawn context; extract allowed scope before any mutation. Approval is recorded in `run-context.yaml` (`plan_ready: true`) and subprocess policy bootstrap — not as a field inside `plan-packet.yaml`.
+2. When spawn context lists `critical_path_work_item_ids` (from `schedule_metadata`), implement those work items before non-critical items when practical (limiting-step / Grove).
+3. Implement only approved scope with minimal, reversible diffs.
+3. Run focused validations mapped to `acceptance_checks`.
+4. Prepare rollback metadata in `rollback_refs` (revert command, revert branch, patch bundle path under the run directory). **`submit_executor_handoff`** writes `handoff/executor-summary.yaml` and mirrors `rollback_refs` to `artifacts/executor-rollback.yaml` (YAML only — no `artifacts/*.json`).
+5. For plan-level ambiguity (wrong scope, missing acceptance), stop and return structured `scope_drift` — do not widen scope.
+6. Do not self-certify final quality; hand off evidence paths for evaluator/adversary.
+
+## Guardrails
+
+- Only modify files required by the approved `PlanPacket`.
+- Never speculate about code you have not read.
+- If scope drift appears, stop with `execution_status: scope_drift` in your final JSON summary.
+- Never set `inherit_context: true` on harness agents.
+- Do not call `ask_user` — parent handles governance forks.
+
+## Output
+
+Call **`submit_executor_handoff`** with a document matching `harness-executor-handoff.schema.json` before exit:
+
+- `execution_status`: `completed`, `blocked`, or `scope_drift`
+- `files_changed`, `validation_summary`, `rollback_refs`, `handoff_ready`
+
+Do not write `artifacts/executor-rollback.json` — rollback is emitted as YAML by the submit pipeline.

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-harness-project-control.ts

@@ -0,0 +1,133 @@
+/**
+ * harness-project-control — always-on enable/disable for harness governance.
+ *
+ * Writes `.pi/harness/project.json`, blocks workflow slash commands while disabled,
+ * and emits `harness-project-enabled:changed` so live TUI surfaces update immediately.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	isHarnessProjectEnabled,
+	isHarnessWorkflowCommand,
+	readHarnessProjectConfig,
+	writeHarnessProjectEnabled,
+} from "../lib/harness-project-config.js";
+import { parseHarnessSlashInput } from "../lib/harness-run-context.js";
+
+function showCommandMessage(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	text: string,
+): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(text, "info");
+		return;
+	}
+	pi.sendMessage({
+		customType: "harness-project-control",
+		content: text,
+		display: true,
+	});
+}
+
+function formatStatus(projectRoot: string): string {
+	const config = readHarnessProjectConfig(projectRoot);
+	const env = process.env.HARNESS_ENABLED?.trim();
+	const lines = [
+		`Harness governance: ${config.enabled ? "enabled" : "disabled"}`,
+		`Config: .pi/harness/project.json`,
+	];
+	if (env) {
+		lines.push(`Env override: HARNESS_ENABLED=${env}`);
+	}
+	if (config.updated_at) {
+		lines.push(`Updated: ${config.updated_at}`);
+	}
+	if (!config.enabled) {
+		lines.push(
+			"Workflow commands (/harness-plan, /harness-run, …) are blocked until you run /harness-enable.",
+		);
+	} else {
+		lines.push("Run /harness-disable to turn governance off.");
+	}
+	return lines.join("\n");
+}
+
+export default function harnessProjectControl(pi: ExtensionAPI) {
+	pi.on("input", async (event) => {
+		if (event.source === "extension") {
+			return { action: "continue" as const };
+		}
+		const parsed = parseHarnessSlashInput(event.text);
+		if (!parsed || !isHarnessWorkflowCommand(parsed.command)) {
+			return { action: "continue" as const };
+		}
+		if (isHarnessProjectEnabled()) {
+			return { action: "continue" as const };
+		}
+		return {
+			action: "handled" as const,
+			message: [
+				`Harness governance is disabled — /${parsed.command} was not started.`,
+				"Run /harness-enable to restore the workflow command surface.",
+			].join("\n"),
+		};
+	});
+
+	pi.registerCommand("harness-enable", {
+		description: "Enable harness governance for this project",
+		handler: async (_args, ctx) => {
+			const projectRoot = process.cwd();
+			const config = writeHarnessProjectEnabled(projectRoot, true);
+			const effectiveConfig = readHarnessProjectConfig(projectRoot);
+			pi.events.emit("harness-project-enabled:changed", {
+				enabled: effectiveConfig.enabled,
+				projectRoot,
+				updated_at: config.updated_at,
+			});
+			showCommandMessage(
+				pi,
+				ctx,
+				[
+					"Harness governance enabled.",
+					`Wrote .pi/harness/project.json (enabled=true, updated ${config.updated_at}).`,
+					"Live TUI surfaces were refreshed.",
+				].join("\n"),
+			);
+		},
+	});
+
+	pi.registerCommand("harness-disable", {
+		description: "Disable harness governance for this project",
+		handler: async (_args, ctx) => {
+			const projectRoot = process.cwd();
+			const config = writeHarnessProjectEnabled(projectRoot, false);
+			const effectiveConfig = readHarnessProjectConfig(projectRoot);
+			pi.events.emit("harness-project-enabled:changed", {
+				enabled: effectiveConfig.enabled,
+				projectRoot,
+				updated_at: config.updated_at,
+			});
+			showCommandMessage(
+				pi,
+				ctx,
+				[
+					"Harness governance disabled.",
+					`Wrote .pi/harness/project.json (enabled=false, updated ${config.updated_at}).`,
+					"Workflow slash commands are blocked immediately.",
+					"Live TUI surfaces were refreshed.",
+				].join("\n"),
+			);
+		},
+	});
+
+	pi.registerCommand("harness-enabled-status", {
+		description: "Show whether harness governance is enabled for this project",
+		handler: async (_args, ctx) => {
+			showCommandMessage(pi, ctx, formatStatus(process.cwd()));
+		},
+	});
+}

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/budget-guard.ts

@@ -12,6 +12,7 @@ import {
 	isHarnessBudgetEnforceOn,
 	shouldEmitBlockingBudgetExhausted,
 } from "../lib/harness-budget-enforce.js";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 
 type HarnessPhase = "plan" | "execute" | "evaluate" | "adversary" | "merge";
@@ -203,6 +204,7 @@ async function emitBudgetEvent(
 const debouncedSoftLimit = new Map<string, boolean>();
 
 export default function budgetGuard(pi: ExtensionAPI) {
+	if (!isHarnessProjectEnabled()) return;
 	pi.on("tool_call", async (_event, ctx) => {
 		const policy = getPolicyContext(ctx);
 		if (policy.phase === null || policy.budgetBypass) return undefined;

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

@@ -6,6 +6,7 @@
 
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 import {
 	acceptDebateRound,
@@ -32,6 +33,7 @@ function getRunId(ctx: {
 }
 
 export default function debateOrchestrator(pi: ExtensionAPI) {
+	if (!isHarnessProjectEnabled()) return;
 	const hooks = {
 		appendEntry: (customType: string, data: unknown) =>
 			pi.appendEntry(customType, data),

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

@@ -18,13 +18,13 @@ import {
 	toToolDetails,
 	validateAskParams,
 } from "./lib/ask-user/validate.js";
-import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { claimHarnessGovernanceLoad } 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;
+	if (!claimHarnessGovernanceLoad("harness-ask-user", MODULE_URL)) return;
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",

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

@@ -24,7 +24,7 @@ import {
 	openDebateBus,
 } from "./lib/debate-bus-core.js";
 import { getDebateState } from "./lib/debate-bus-state.js";
-import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { claimHarnessGovernanceLoad } from "./lib/extension-load-guard.js";
 import { captureHarnessEvent } from "./lib/harness-posthog.js";
 import { DEBATE_AGENT_SUBMIT_TOOL } from "./lib/harness-subagent-submit-registry.js";
 import {
@@ -115,7 +115,7 @@ function subagentResults(
 const USE_SUBMIT_TOOLS = process.env.HARNESS_SUBMIT_TOOLS !== "0";
 
 export default function harnessDebateTools(pi: ExtensionAPI) {
-	if (!claimExtensionLoad("harness-debate-tools", MODULE_URL)) return;
+	if (!claimHarnessGovernanceLoad("harness-debate-tools", MODULE_URL)) return;
 
 	pi.on("tool_result", async (event, ctx) => {
 		if (event.isError || event.toolName !== "subagent") return;

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

@@ -2,6 +2,8 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { isHarnessProjectEnabled } from "../lib/harness-project-config.js";
+import { evaluateCrossSessionResume } from "../lib/harness-run-context.js";
 import {
 	deriveHarnessStatusHint,
 	formatHarnessPhaseLabel,
@@ -244,7 +246,7 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 	let mountCtx: ExtensionContext | null = null;
 
 	function mountHarnessWidget(ctx: ExtensionContext): void {
-		if (!ctx.hasUI) return;
+		if (!ctx.hasUI || !isHarnessProjectEnabled()) return;
 		const state = stateStore.refresh(ctx);
 		lastRenderHash = computeRenderHash(state);
 
@@ -269,9 +271,21 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		updateStatusFallback(ctx, state);
 	}
 
+	function clearHarnessWidget(ctx: ExtensionContext): void {
+		if (!ctx.hasUI) return;
+		const tui = tuiHandle;
+		ctx.ui.setWidget("harness-live", undefined);
+		ctx.ui.setStatus("harness-mode", undefined);
+		widgetMounted = false;
+		tuiHandle = null;
+		component = null;
+		lastRenderHash = "";
+		tui?.requestRender();
+	}
+
 	function remountHarnessLiveWidget(ctx: ExtensionContext): void {
 		if (!ctx.hasUI || !widgetMounted) return;
-		ctx.ui.setWidget("harness-live", undefined);
+		clearHarnessWidget(ctx);
 		mountHarnessWidget(ctx);
 	}
 
@@ -283,6 +297,36 @@ 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);
+	});
+
+	pi.events.on("harness-project-enabled:changed", (payload: unknown) => {
+		const data =
+			payload && typeof payload === "object"
+				? (payload as { enabled?: boolean })
+				: null;
+		if (!mountCtx || typeof data?.enabled !== "boolean") return;
+		if (data.enabled) {
+			mountHarnessWidget(mountCtx);
+			tuiHandle?.requestRender();
+			return;
+		}
+		clearHarnessWidget(mountCtx);
+	});
+
 	function updateStatusFallback(
 		ctx: ExtensionContext,
 		state: HarnessUiState,
@@ -304,6 +348,7 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 			policyDecision: state.policyDecision,
 			flowSubstate: state.flowSubstate,
 			nextRecommendedCommand: state.nextRecommendedCommand,
+			crossSessionResumeCommand: state.crossSessionResumeCommand,
 		});
 	}
 
@@ -312,6 +357,10 @@ export default function harnessLiveWidget(pi: ExtensionAPI) {
 		refreshQueued = true;
 		queueMicrotask(() => {
 			refreshQueued = false;
+			if (!isHarnessProjectEnabled()) {
+				clearHarnessWidget(ctx);
+				return;
+			}
 			const state = stateStore.refresh(ctx);
 			const hash = computeRenderHash(state);
 			updateStatusFallback(ctx, state);
@@ -322,9 +371,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) => {