ultimate-pi 0.10.1 → 0.12.0

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

@@ -1,71 +1,140 @@
 ---
-description: Build a strict read-only PlanPacket before any mutating work.
+description: PM-grade harness plan — scouts, ExecutionPlan, DAG validation, Review Gate debate, approval.
 argument-hint: "\"<task>\" [--risk low|med|high] [--budget <amount>] [--quick]"
 ---
 
 # harness-plan
 
-Orchestrator only — spawn `harness/planner` once. The planner runs clarification (`ask_user`), approval (`approve_plan`), and persists the plan (`create_plan`). Do **not** write `plan-packet.json` in this parent session.
+You are the **planning PM** for this harness run. Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`), not strategy theater. Parent owns `ask_user`, `approve_plan`, `create_plan`, debate bus commands, and YAML writes under `.pi/harness/runs/<run_id>/`.
 
-## Step 0 — Parse arguments
+Never `write`/`edit` the final canonical packet except via **`write_harness_yaml`** for run artifacts and **`create_plan`** after approval. Do not paste JSON into `.yaml` files — subagents emit JSON; you convert via `write_harness_yaml`.
 
-Read `$ARGUMENTS`:
+## Allowed subagents
 
-- task statement (required)
-- optional: `--risk low|med|high`, `--budget <amount>`, `--quick`
+- `harness/planning/scout-graphify`
+- `harness/planning/scout-structure`
+- `harness/planning/scout-semantic` (skip when `--quick`)
+- `harness/planning/decompose`
+- `harness/planning/hypothesis`
+- `harness/planning/stack-researcher`
+- `harness/planning/execution-plan-author`
+- `harness/planning/hypothesis-validator` (debate R1 only)
+- `harness/planning/plan-evaluator`
+- `harness/planning/plan-adversary`
+- `harness/planning/sprint-contract-auditor`
+- `harness/planning/review-integrator`
 
-If task is missing:
+Read **harness-debate-plan** skill before Review Gate rounds.
 
-`Usage: /harness-plan "<task>" [--risk low|med|high] [--budget <amount>] [--quick]`
+## Performance rules
 
-`--quick` narrows planning breadth only — it does **not** skip user approval.
+1. Use `subagent` with `agentScope: "both"` and parallel `tasks` where lanes are independent.
+2. Each `subagent` call blocks until subprocesses finish — batch parallel scouts in one `tasks` array.
+3. Cap: **12** harness subagent invocations per parent session (extension-enforced).
+4. Compact task text: embed `HarnessSpawnContext` JSON + lane-specific instructions only.
+
+## Step 0 — Parse `$ARGUMENTS`
+
+- task (required)
+- `--risk low|med|high`, `--budget`, `--quick`
+
+`--quick` skips **scout-semantic** and post-run adversary only — **never** skip graphify, structure, decompose, hypothesis, stack research, execution plan, DAG validation, or **4-round plan debate**.
 
 ## Active plan context
 
-Use injected context only — **do not** read `.pi/harness/specs/*.schema.json` or explore specs with bash.
+Use `[HarnessActivePlan]` / `[HarnessRunContext]` only. On revise: preserve `plan_id` / `task_id`. Canonical paths: `plan-packet.yaml`, `research-brief.yaml`, `artifacts/*.yaml`.
+
+## Phase 1 — Parallel scouts
+
+```json
+{
+  "agentScope": "both",
+  "tasks": [
+    { "agent": "harness/planning/scout-graphify", "task": "<HarnessSpawnContext + graphify lane>", "timeoutMs": 90000 },
+    { "agent": "harness/planning/scout-structure", "task": "<HarnessSpawnContext + structure lane>", "timeoutMs": 90000 }
+  ]
+}
+```
+
+Add `harness/planning/scout-semantic` to `tasks` unless `--quick`. Require graphify + structure success.
+
+## Phase 2 & 3 — Decompose + hypothesis (parallel)
+
+One `subagent` call with `tasks` for `harness/planning/decompose` and `harness/planning/hypothesis`. Parse `PlanDecompositionBrief` and `PlanHypothesisBrief` from outputs. Persist with `write_harness_yaml` → `artifacts/decomposition.yaml` and `artifacts/hypothesis.yaml`.
+
+## Phase 4 — Draft shell + fork
+
+Build draft `PlanPacket` (`contract_version: "1.1.0"`):
+
+- `scope`, `assumptions`, `acceptance_checks`, `risk_level`, `rollback_plan`
+- `execution_plan` placeholder until Phase 4b
+
+`ask_user` when `dialectical_fork` is material.
 
-If `[HarnessActivePlan]` is present:
+Initialize `research-brief.yaml` with decomposition + hypothesis (`write_harness_yaml`).
 
-- Treat task as **revise/amend** unless `/harness-new-run` was used.
-- Pass `mode: revise` using the `HarnessSpawnContext` JSON in `[HarnessRunContext]`.
+## Phase 4a — Stack research
 
-Otherwise use `HarnessSpawnContext` from `[HarnessRunContext]` for greenfield `mode: create`.
+```
+subagent({ agentScope: "both", agent: "harness/planning/stack-researcher", task: "<HarnessSpawnContext + stack research brief>" })
+```
 
-## Orchestration (required)
+`write_harness_yaml` → `artifacts/stack.yaml`; merge into `research-brief.yaml` → `stack`.
 
-1. Copy the `HarnessSpawnContext=…` JSON from `[HarnessRunContext]` into the spawn prompt (adjust `risk_level`, `quick`, `mode` from `$ARGUMENTS` if needed). Do **not** add “call ask_user for approval” in the `Agent` prompt — the planner agent instructions already define `approve_plan` / `create_plan`.
-2. Spawn **once** with **`inherit_context: false`**:
+## Phase 4b — Execution plan author
 
 ```
-Agent({ subagent_type: "harness/planner", prompt: "<task + HarnessSpawnContext JSON + output schema>" })
+subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author", task: "<HarnessSpawnContext + execution plan brief>" })
 ```
 
-3. `get_subagent_result` — parse final JSON (`status`, `plan_packet`, `human_summary`, `clarification`) via fenced `json` block. Treat `plan_packet` in that JSON as **read-only summary context** — not input for another approval tool call.
-4. If `status === "ready"` and `[HarnessRunContext]` shows `plan_ready: true` (planner called `create_plan`), confirm `plan_packet_path` exists — do **not** write the file yourself.
-5. If `needs_clarification`, tell the user the planner is waiting — do **not** re-spawn; user should answer in the subagent or re-run `/harness-plan`.
-6. Do **not** call `ask_user`, `approve_plan`, or `create_plan` in this parent session.
+Merge `execution_plan` into draft `plan-packet.yaml` (`write_harness_yaml`). Save `artifacts/execution-plan-draft.yaml` the same way.
+
+## Phase 4c — DAG validation (hard gate)
+
+```bash
+node .pi/scripts/validate-plan-dag.mjs --packet .pi/harness/runs/<run_id>/plan-packet.yaml --write
+```
+
+Must **pass** before debate. On fail: fix via author or parent patches, re-run.
+
+## Phase 5 — Review Gate debate (4 rounds, even with `--quick`)
+
+1. `/harness-debate-open plan-<run_id>`
+2. For rounds 1–4 (`debate_round_focus`: spec, wbs, schedule, quality):
+
+| Round | Extra spawns (before integrator) |
+|-------|----------------------------------|
+| 1 | `hypothesis-validator` (blind: task + hypothesis only) → `plan-evaluator` → `plan-adversary` |
+| 2 | `plan-evaluator` → `plan-adversary` (optional `sprint-contract-auditor` if done_criteria thin) |
+| 3 | `plan-evaluator` → `plan-adversary` |
+| 4 | `plan-evaluator` → `plan-adversary` → **`sprint-contract-auditor` (required)** |
+
+Then `review-integrator` → `write_harness_yaml` → `artifacts/review-round-r{N}.yaml` → build bus envelope → `/harness-debate-round '<json>'`.
+
+3. `/harness-debate-consensus` after round 4.
+
+**R1 blind rule:** hypothesis-validator prompt must exclude decomposition, scouts, PlanPacket, prior debate.
+
+If R1 `revision_recommended` or `relevance.passes === false`: one `hypothesis` re-spawn, update brief, continue.
 
-## After subagent returns (no second approval)
+**Blockers:** `policy_decision: block` → do not `approve_plan`. `human_required` → `ask_user` before approval.
 
-User approval happens **once**, inside the planner subagent: `approve_plan` uses the parent TUI bridge. You are the orchestrator, **not** an approver.
+## Phase 5b — Revise packet
 
-After `get_subagent_result`:
+Apply `recommended_packet_patches` from last integrator round. Re-run `validate-plan-dag.mjs`. If >30% work items changed, one partial re-round on affected focus.
 
-- If `[HarnessRunContext]` shows `plan_ready: true`, or the transcript already has `harness-plan-approval` / bridged `approve_plan` with **Approve** → planning is complete. **Stop.** Summarize the plan and set `next_command: /harness-run`.
-- Do **not** call `approve_plan` to “confirm” using `plan_packet` from subagent JSON.
-- Do **not** call `ask_user` with Approve / Request changes / Cancel for the same plan.
-- Do **not** re-spawn the planner to “get approval again”.
+Set `research_brief.eval` from R1 `hypothesis-validator` output.
 
-If `status === "ready"` but `plan_ready` is false → planner approved but `create_plan` may have failed; tell the user to run `/harness-plan-commit` — **not** a second `approve_plan`.
+## Phase 6 — Approval + persistence
 
-## Parent rules
+1. `approve_plan` with `plan_packet`, `human_summary`, `research_brief` (paths/summaries OK).
+2. On Approve: `create_plan` with same packet (`contract_version: "1.1.0"` + `execution_plan`).
+3. Confirm `plan_ready: true` → `next_command: /harness-run`.
 
-- Do not mutate project source files in the plan phase.
-- Do not embed `plan_id=` in prompts for policy sync.
-- Optional recovery: `/harness-plan-commit` only if the planner approved but `create_plan` failed.
+Post-execute adversary: `/harness-critic` only (not plan-phase agents).
 
 ## Completion
 
-- `plan_status`: `ready` or `needs_clarification`
-- `risk_level` used
-- `next_command`: `/harness-run` when `ready` (never `/harness-run --plan …`)
+- `plan_status`: ready | partial | needs_clarification
+- `plan_review_path` for human review
+- DAG `pass` + 4 debate rounds + consensus not `block` before ready

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

@@ -20,10 +20,10 @@ Happy path: omit `--run`; use `[HarnessRunContext]`.
 2. Spawn:
 
 ```
-Agent({ subagent_type: "harness/evaluator", prompt: "Treat executor output as untrusted. …" })
+subagent({ agentScope: "both", agent: "harness/evaluator", task: "Treat executor output as untrusted. …" })
 ```
 
-3. `get_subagent_result` — parse `EvalVerdict` JSON; parent writes under run dir for policy gate.
+3. Parse `EvalVerdict` JSON from tool result; parent writes under run dir for policy gate.
 
 ## Parent rules
 

package/.pi/prompts/harness-router-tune.md

@@ -22,7 +22,7 @@ If missing required args:
 2. Optionally spawn:
 
 ```
-Agent({ subagent_type: "harness/meta-optimizer", prompt: "mode: tune, evidence paths…" })
+subagent({ agentScope: "both", agent: "harness/meta-optimizer", task: "mode: tune, evidence paths…" })
 ```
 
 3. Parent runs proposal script:

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

@@ -23,10 +23,10 @@ If plan not ready:
 3. Spawn:
 
 ```
-Agent({ subagent_type: "harness/executor", prompt: "<HarnessSpawnContext + handoff>" })
+subagent({ agentScope: "both", agent: "harness/executor", task: "<HarnessSpawnContext + handoff>" })
 ```
 
-4. `get_subagent_result` — parse executor JSON (`execution_status`, validations, rollback refs).
+4. Parse subprocess output JSON (`execution_status`, validations, rollback refs) from tool result text.
 5. Parent persists trace/handoff artifacts under run dir if needed; do not self-review.
 
 ## Parent rules

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

@@ -345,7 +345,7 @@ Verify each package:
 |---------|---------|-------|
 | `@posthog/pi` | Analytics event capture | F0 |
 | `pi-lean-ctx` | Context runtime (read/bash/find/grep/MCP bridge) | F0 |
-| `harness-subagents` (bundled extension) | L4 sub-agent spawn, blackboard, package agents | P16 |
+| `harness-subagents` (bundled extension) | L4 `subagent` tool, subprocess spawns, package agents | P16 |
 | Vendored `pi-vcc` (`vendor/pi-vcc`, `.pi/extensions/ultimate-pi-vcc.ts`) | VCC compaction / `vcc_recall` — env-only: `HARNESS_VCC_COMPACTION` (default on), `HARNESS_VCC_DEBUG` | Shipped |
 | `pi-model-router` | Vendored (`vendor/`); activates after `.pi/model-router.json` exists | F0 |
 
@@ -383,11 +383,11 @@ Manual override: **`/router profile auto`** anytime after reload if they changed
 
 ## Step 3.6 — Harness agents (package-resolved)
 
-`harness-subagents` loads agents from the installed **`ultimate-pi`** package (`$UP_PKG/.pi/agents/**`) with namespaced ids (`harness/planner`, `pi-pi/agent-expert`). **Do not copy** agents into the project unless you want a deliberate override.
+`harness-subagents` loads agents from the installed **`ultimate-pi`** package (`$UP_PKG/.pi/agents/**`) with namespaced ids (`harness/executor`, `harness/planning/scout-graphify`, `pi-pi/agent-expert`). **Do not copy** agents into the project unless you want a deliberate override.
 
 **Slash commands are orchestrators:** `/harness-plan`, `/harness-run`, etc. spawn `harness/*` agents via the `Agent` tool — bootstrap stays **script-first**; only optionally spawn `harness/sentrux-bootstrap` for Sentrux (see Step 4.2).
 
-Optional per-repo overrides: place `.md` files at the **same relative path** (e.g. `.pi/agents/harness/planner.md` overrides the package planner).
+Optional per-repo overrides: place `.md` files at the **same relative path** (e.g. `.pi/agents/harness/planning/scout-graphify.md` overrides the package scout).
 
 Verify manifest drift after `pi update ultimate-pi`:
 
@@ -478,16 +478,25 @@ Template keys (placeholders — user fills secrets): `HARNESS_TELEMETRY_ENABLED`
 
 ### 4.1 — .gitignore Entries
 
-Ensure `.gitignore` contains:
+Ensure `.gitignore` contains harness runtime entries (see repo root `.gitignore` — **do not** ignore `.pi/harness/specs/`; JSON schemas are shared contracts):
+
 ```
 .env
 .web/
 .searxng/
 .raw/
 .vault-meta/
-.pi/harness/critics/
+.pi/harness/active-run.json
+.pi/harness/release-readiness-report.md
 .pi/harness/plans/
-.pi/harness/specs/
+.pi/harness/critics/
+.pi/harness/runs/**
+!.pi/harness/runs/README.md
+.pi/harness/incidents/*
+!.pi/harness/incidents/README.md
+.pi/harness/debates/*
+!.pi/harness/debates/README.md
+.pi/harness/router/proposals/*
 
 # Model router config (user-specific — generated from env)
 .pi/model-router.json

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

@@ -20,10 +20,10 @@ Happy path: omit `--run`.
 2. Spawn:
 
 ```
-Agent({ subagent_type: "harness/trace-librarian", prompt: "…" })
+subagent({ agentScope: "both", agent: "harness/trace-librarian", task: "…" })
 ```
 
-3. `get_subagent_result` — present timeline and artifact index to user.
+3. Present timeline and artifact index from tool result to user.
 
 ## Completion
 

package/.pi/scripts/harness-agents-manifest.mjs

@@ -14,7 +14,7 @@ import {
 	isSafeAgentId,
 	sha256Content,
 	walkAgentsDir,
-} from "../../test/harness-subagents-loader.core.mjs";
+} from "../lib/harness-agent-discovery.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const MANIFEST_PATH = join(ROOT, ".pi", "harness", "agents.manifest.json");

package/.pi/scripts/harness-resolve-up-pkg.mjs

@@ -30,7 +30,20 @@ function hasHarnessScripts(root) {
 	return existsSync(join(root, ".pi", "scripts", "harness-cli-verify.sh"));
 }
 
+function isSourceCheckout(root) {
+	try {
+		const pkg = requireFromCwd.resolve("./package.json");
+		return dirname(pkg) === root;
+	} catch {
+		return false;
+	}
+}
+
 function tryResolveUltimatePi() {
+	if (hasHarnessScripts(process.cwd()) && isSourceCheckout(process.cwd())) {
+		return process.cwd();
+	}
+
 	if (process.env.ULTIMATE_PI_PKG) {
 		const envRoot = process.env.ULTIMATE_PI_PKG;
 		if (hasHarnessScripts(envRoot)) return envRoot;

package/.pi/scripts/harness-verify.mjs

@@ -202,32 +202,41 @@ async function main() {
 	if (!(await fileExists(runCtxLib))) fail("missing lib/harness-run-context.ts");
 	ok("lib/harness-run-context.ts");
 
-	const vendoredIndex = join(
+	const subagentsVendor = join(
+		ROOT,
+		"vendor",
+		"pi-subagents",
+		"src",
+		"subagents.ts",
+	);
+	if (!(await fileExists(subagentsVendor))) {
+		fail("missing vendor/pi-subagents/src/subagents.ts");
+	}
+	const bridgePath = join(
 		ROOT,
 		".pi",
 		"extensions",
 		"lib",
-		"harness-subagents",
-		"vendored",
-		"index.ts",
+		"harness-subagents-bridge.ts",
 	);
-	const vendoredSrc = await readFile(vendoredIndex, "utf-8");
-	const runCtxImport = vendoredSrc.match(
-		/from ["']([^"']*harness-run-context\.js)["']/,
-	);
-	if (!runCtxImport) {
-		fail("vendored/index.ts must import harness-run-context.js");
+	if (!(await fileExists(bridgePath))) {
+		fail("missing harness-subagents-bridge.ts");
 	}
-	const runCtxImportPath = resolve(
-		dirname(vendoredIndex),
-		runCtxImport[1].replace(/\.js$/, ".ts"),
-	);
-	if (runCtxImportPath !== runCtxLib) {
-		fail(
-			`vendored/index.ts harness-run-context import resolves to ${runCtxImportPath}, expected ${runCtxLib}`,
-		);
+	const bridgeSrc = await readFile(bridgePath, "utf-8");
+	if (!bridgeSrc.includes("precheckHarnessSubagentSpawn")) {
+		fail("harness-subagents-bridge must run precheckHarnessSubagentSpawn");
+	}
+	if (!bridgeSrc.includes("packageRoot")) {
+		fail("harness-subagents-bridge must pass packageRoot for agent discovery");
+	}
+	const subagentsSrc = await readFile(subagentsVendor, "utf-8");
+	if (!subagentsSrc.includes("discoverAgents")) {
+		fail("vendor subagents.ts must implement discoverAgents");
+	}
+	if (!subagentsSrc.includes("packageRoot")) {
+		fail("vendor subagents.ts must pass packageRoot into discovery");
 	}
-	ok("vendored/index.ts harness-run-context import path");
+	ok("vendor pi-subagents + harness bridge");
 
 	const policyGateSrc = await readFile(
 		join(ROOT, ".pi", "extensions", "policy-gate.ts"),

package/.pi/scripts/validate-plan-dag.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * validate-plan-dag — deterministic ExecutionPlan DAG checks (YAML packet in).
+ */
+
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readYamlFile, writeYamlFile } from "../lib/harness-yaml.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const MINIMUMS = {
+	low: { phases: 2, work_items: 5, acceptance_checks: 3, risks: 0 },
+	med: { phases: 3, work_items: 8, acceptance_checks: 5, risks: 3 },
+	high: { phases: 4, work_items: 12, acceptance_checks: 8, risks: 3 },
+};
+
+function fail(msg) {
+	console.error(`validate-plan-dag: FAIL: ${msg}`);
+	process.exit(1);
+}
+
+function ok(msg) {
+	console.log(`  ✓ ${msg}`);
+}
+
+function topoSort(workItems) {
+	const ids = new Set(workItems.map((w) => w.work_item_id));
+	const adj = new Map();
+	for (const w of workItems) {
+		adj.set(w.work_item_id, (w.depends_on ?? []).filter((d) => ids.has(d)));
+	}
+	const visited = new Set();
+	const stack = new Set();
+	const order = [];
+	const cycles = [];
+
+	function dfs(n, path) {
+		if (stack.has(n)) {
+			cycles.push([...path, n]);
+			return;
+		}
+		if (visited.has(n)) return;
+		visited.add(n);
+		stack.add(n);
+		for (const d of adj.get(n) ?? []) dfs(d, [...path, n]);
+		stack.delete(n);
+		order.push(n);
+	}
+
+	for (const id of ids) dfs(id, []);
+	order.reverse();
+	return { order, cycles };
+}
+
+function computeCriticalPath(workItems) {
+	const ids = new Set(workItems.map((w) => w.work_item_id));
+	const len = new Map();
+	for (const w of workItems) len.set(w.work_item_id, 0);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const w of workItems) {
+			const deps = (w.depends_on ?? []).filter((d) => ids.has(d));
+			const base = deps.length === 0 ? 0 : Math.max(...deps.map((d) => len.get(d) ?? 0)) + 1;
+			if (base > (len.get(w.work_item_id) ?? 0)) {
+				len.set(w.work_item_id, base);
+				changed = true;
+			}
+		}
+	}
+	const maxLen = Math.max(0, ...len.values());
+	const end = workItems.filter((w) => len.get(w.work_item_id) === maxLen).map((w) => w.work_item_id);
+	// Backtrack one longest path
+	const path = [];
+	let cur = end[0];
+	if (!cur) return [];
+	const byId = new Map(workItems.map((w) => [w.work_item_id, w]));
+	while (cur) {
+		path.unshift(cur);
+		const w = byId.get(cur);
+		const deps = (w?.depends_on ?? []).filter((d) => ids.has(d));
+		if (deps.length === 0) break;
+		cur = deps.reduce((a, b) => ((len.get(a) ?? 0) >= (len.get(b) ?? 0) ? a : b));
+	}
+	return path;
+}
+
+export function validateExecutionPlan(packet, projectRoot = ROOT) {
+	const errors = [];
+	const ep = packet.execution_plan;
+	if (!ep) {
+		errors.push("execution_plan required");
+		return { status: "fail", errors, report: null };
+	}
+
+	const risk = packet.risk_level ?? "med";
+	const min = MINIMUMS[risk] ?? MINIMUMS.med;
+	const phases = ep.phases ?? [];
+	const workItems = ep.work_items ?? [];
+	const conflicts = [];
+
+	if (phases.length < min.phases) {
+		errors.push(`need >= ${min.phases} phases for risk ${risk}`);
+	}
+	if (workItems.length < min.work_items) {
+		errors.push(`need >= ${min.work_items} work_items for risk ${risk}`);
+	}
+	const ac = packet.acceptance_checks ?? [];
+	if (ac.length < min.acceptance_checks) {
+		errors.push(`need >= ${min.acceptance_checks} acceptance_checks`);
+	}
+	if ((ep.risk_register ?? []).length < min.risks) {
+		errors.push(`need >= ${min.risks} risks for risk ${risk}`);
+	}
+
+	const phaseIds = new Set(phases.map((p) => p.phase_id));
+	const phaseIndex = new Map(phases.map((p, i) => [p.phase_id, i]));
+	const wiIds = new Set(workItems.map((w) => w.work_item_id));
+
+	for (const p of phases) {
+		if (!p.exit_criteria?.length) errors.push(`phase ${p.phase_id} missing exit_criteria`);
+		if (!p.work_item_ids?.length) errors.push(`phase ${p.phase_id} has no work items`);
+	}
+
+	const wiInPhase = new Set();
+	for (const w of workItems) {
+		if (!phaseIds.has(w.phase_id)) {
+			errors.push(`work_item ${w.work_item_id} unknown phase_id`);
+		}
+		wiInPhase.add(w.work_item_id);
+		for (const d of w.depends_on ?? []) {
+			if (!wiIds.has(d)) errors.push(`work_item ${w.work_item_id} depends_on missing ${d}`);
+		}
+		if (!w.non_code && (!w.files || w.files.length === 0)) {
+			errors.push(`work_item ${w.work_item_id} needs files[] or non_code: true`);
+		}
+	}
+
+	for (const p of phases) {
+		for (const wid of p.work_item_ids ?? []) {
+			if (!wiIds.has(wid)) errors.push(`phase ${p.phase_id} references missing ${wid}`);
+		}
+	}
+
+	const { order, cycles } = topoSort(workItems);
+	if (cycles.length) errors.push(`cycle detected: ${JSON.stringify(cycles[0])}`);
+
+	// File conflicts
+	for (let i = 0; i < workItems.length; i++) {
+		for (let j = i + 1; j < workItems.length; j++) {
+			const a = workItems[i];
+			const b = workItems[j];
+			const filesA = new Set(a.files ?? []);
+			const overlap = (b.files ?? []).filter((f) => filesA.has(f));
+			if (overlap.length === 0) continue;
+			const reachable = (from, to, seen = new Set()) => {
+				if (from === to) return true;
+				if (seen.has(from)) return false;
+				seen.add(from);
+				const w = workItems.find((x) => x.work_item_id === from);
+				for (const d of w?.depends_on ?? []) {
+					if (reachable(d, to, seen)) return true;
+				}
+				return false;
+			};
+			if (!reachable(a.work_item_id, b.work_item_id) && !reachable(b.work_item_id, a.work_item_id)) {
+				if ((phaseIndex.get(a.phase_id) ?? 0) === (phaseIndex.get(b.phase_id) ?? 0)) {
+					conflicts.push(
+						`file overlap ${overlap.join(",")} between ${a.work_item_id} and ${b.work_item_id} without dependency`,
+					);
+				}
+			}
+		}
+	}
+
+	const computedCp = computeCriticalPath(workItems);
+	const authorCp = ep.schedule_metadata?.critical_path_work_item_ids ?? [];
+	if (computedCp.length >= 3 && authorCp.length) {
+		const same =
+			authorCp.length === computedCp.length &&
+			authorCp.every((id, i) => id === computedCp[i]);
+		if (!same) {
+			errors.push(
+				`critical_path mismatch author=${authorCp.join("→")} computed=${computedCp.join("→")}`,
+			);
+		}
+	}
+
+	const acIds = new Set(
+		ac.map((c) => (typeof c === "string" ? c : c.id)).filter(Boolean),
+	);
+	for (const w of workItems) {
+		for (const acid of w.acceptance_check_ids ?? []) {
+			if (!acIds.has(acid)) errors.push(`${w.work_item_id} references orphan ${acid}`);
+		}
+	}
+	for (const acid of acIds) {
+		const used = workItems.some((w) => (w.acceptance_check_ids ?? []).includes(acid));
+		if (!used) errors.push(`orphan acceptance check ${acid}`);
+	}
+
+	const status = errors.length === 0 && conflicts.length === 0 ? "pass" : "fail";
+	const report = {
+		status,
+		topological_order: order,
+		cycles,
+		conflicts: [...conflicts, ...errors],
+	};
+	return { status, errors: [...errors, ...conflicts], report };
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+	let packetPath = null;
+	let writeBack = false;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--packet" && args[i + 1]) packetPath = args[++i];
+		else if (args[i] === "--write") writeBack = true;
+	}
+
+	if (!packetPath) {
+		console.error("Usage: validate-plan-dag.mjs --packet <plan-packet.yaml> [--write]");
+		process.exit(2);
+	}
+
+	const abs = resolve(packetPath);
+	try {
+		await access(abs, constants.R_OK);
+	} catch {
+		fail(`cannot read ${abs}`);
+	}
+
+	const packet = await readYamlFile(abs);
+	const { status, errors, report } = validateExecutionPlan(packet, dirname(abs));
+
+	if (writeBack && report && packet.execution_plan) {
+		packet.execution_plan.dag_validation = {
+			status: report.status,
+			topological_order: report.topological_order,
+			cycles: report.cycles,
+			conflicts: report.conflicts,
+		};
+		await writeYamlFile(abs, packet);
+	}
+
+	if (status !== "pass") {
+		for (const e of errors) console.error(`  - ${e}`);
+		fail("validation failed");
+	}
+	ok(`DAG validation pass (${report.topological_order.length} work items)`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+	main();
+}

package/.pi/scripts/vendor-sync-pi-subagents.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Re-fetch upstream pi-subagents from narumiruna/pi-extensions.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+VEND="$ROOT/vendor/pi-subagents"
+BASE="https://raw.githubusercontent.com/narumiruna/pi-extensions/main/extensions/pi-subagents"
+
+mkdir -p "$VEND/src"
+curl -fsSL "$BASE/LICENSE" -o "$VEND/LICENSE"
+curl -fsSL "$BASE/src/subagents.ts" -o "$VEND/src/subagents.upstream.ts"
+
+# Preserve ultimate-pi harness extensions (agents.ts, harness patches applied to subagents.ts manually or via merge).
+if [[ ! -f "$VEND/src/agents.ts" ]]; then
+	curl -fsSL "$BASE/src/agents.ts" -o "$VEND/src/agents.ts"
+fi
+
+sed -i 's/from "typebox"/from "@sinclair\/typebox"/g' "$VEND/src/subagents.upstream.ts" 2>/dev/null || true
+
+echo "Fetched upstream into $VEND/src/subagents.upstream.ts — merge harness changes into subagents.ts before commit."