ultimate-pi 0.14.0 → 0.16.0

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

@@ -1,13 +1,13 @@
 ---
-description: PM-grade harness plan — scouts, ExecutionPlan, DAG validation, Review Gate debate, approval.
-argument-hint: "\"<task>\" [--risk low|med|high] [--budget <amount>] [--quick]"
+description: PM-grade harness plan — scouts, implementation research, ExecutionPlan, DAG validation, selective Review Gate debate, approval.
+argument-hint: "\"<task>\" [--risk low|med|high] [--quick]"
 ---
 
 # harness-plan
 
 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>/`.
 
-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`.
+Subagents persist artifacts via scoped **`submit_*`** tools (deterministic YAML under the run dir). Parent uses **`harness_artifact_ready`** to gate phases (no JSON parsing). Parent merges still use **`write_harness_yaml`** for `research-brief.yaml`, `plan-packet.yaml` shell, and integrator patches only.
 
 ## Allowed subagents
 
@@ -16,6 +16,7 @@ Never `write`/`edit` the final canonical packet except via **`write_harness_yaml
 - `harness/planning/scout-semantic` (skip when `--quick`)
 - `harness/planning/decompose`
 - `harness/planning/hypothesis`
+- `harness/planning/implementation-researcher`
 - `harness/planning/stack-researcher`
 - `harness/planning/execution-plan-author`
 - `harness/planning/hypothesis-validator` (debate R1 only)
@@ -31,15 +32,15 @@ Read **harness-debate-plan** skill before Review Gate rounds.
 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. Do **not** set `timeoutMs` unless the user explicitly requests a cap — subagents run until natural completion (optional backstop: `PI_SUBAGENT_TIMEOUT_MS`).
-4. No harness subagent spawn cap — run the full scout + debate pipeline without skipping lanes for budget.
-5. Compact task text: embed `HarnessSpawnContext` JSON + lane-specific instructions only.
+4. No harness subagent spawn cap — run the full scout + research + debate pipeline without skipping lanes for budget.
+5. Compact task text: embed spawn context + lane instructions. Prefer `HarnessSpawnContext={"run_id":"…","plan_packet_path":"…",…}` or a JSON object with `"HarnessSpawnContext":{…}` — both parse; `run_id` is required so subprocess submit tools get `HARNESS_RUN_ID`.
 
 ## Step 0 — Parse `$ARGUMENTS`
 
 - task (required)
-- `--risk low|med|high`, `--budget`, `--quick`
+- `--risk low|med|high`, `--quick` (`--budget` is reserved/no-op; token budgets are telemetry-only unless `HARNESS_BUDGET_ENFORCE=1`)
 
-`--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**.
+`--quick` skips **scout-semantic** and post-run adversary only — **never** skip graphify, structure, decompose, hypothesis, **Phase 3.5 implementation research**, stack research, execution plan, DAG validation, or **Review Gate debate**.
 
 ## Active plan context
 
@@ -63,33 +64,50 @@ Do **not** run `ccc index` or `ccc search --refresh`. The harness runs increment
 
 Add `harness/planning/scout-semantic` to `tasks` unless `--quick`. Require graphify + structure success. Semantic lane uses `ccc search` only (see `scout-semantic` agent).
 
+After scouts: `harness_artifact_ready({ paths: ["artifacts/scout-graphify.yaml", "artifacts/scout-structure.yaml", ...] })`.
+
 ## 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`.
+One `subagent` call with `tasks` for `harness/planning/decompose` and `harness/planning/hypothesis` (include scout YAML paths in task text). Gate with `harness_artifact_ready` on `artifacts/decomposition.yaml` and `artifacts/hypothesis.yaml`.
 
-## Phase 4 — Draft shell + fork
+Decompose **prior_art** is **internal only** (from scouts). External prior art arrives in Phase 3.5.
 
-Build draft `PlanPacket` (`contract_version: "1.1.0"`):
+## Phase 3.5 — External solution research (required)
 
-- `scope`, `assumptions`, `acceptance_checks`, `risk_level`, `rollback_plan`
-- `execution_plan` placeholder until Phase 4b
+**MUST** run unless you document a `human_required` waiver in the run trace. Parallel batch:
+
+```json
+{
+  "agentScope": "both",
+  "tasks": [
+    { "agent": "harness/planning/implementation-researcher", "task": "<HarnessSpawnContext + paths to decomposition/hypothesis/scout summaries — patterns/repos/workflows only; no stack version SERPs>" },
+    { "agent": "harness/planning/stack-researcher", "task": "<HarnessSpawnContext + stack research brief — libraries/APIs only>" }
+  ]
+}
+```
 
-`ask_user` when `dialectical_fork` is material.
+- Subagents write via `submit_implementation_research` / `submit_stack_brief`; gate with `harness_artifact_ready` on both paths.
+- Merge both into `research-brief.yaml` (`implementation:` + `stack:`) via parent `write_harness_yaml`.
+- **Partial failure:** if one lane fails, re-spawn that lane once; if still failing set `plan_status: partial` and `human_required` via `ask_user`. Do not proceed to Phase 4b without both artifacts or explicit human waiver.
+- **Web dedup:** implementation owns patterns/repos; stack owns libraries/versions — no overlapping queries.
 
-Initialize `research-brief.yaml` with decomposition + hypothesis (`write_harness_yaml`).
+On `mode: revise`: re-run implementation-researcher when task scope, acceptance_checks, or >30% work_items change; skip when delta is schedule-only and prior artifact is fresh.
 
-## Phase 4a — Stack research
+## Phase 4 — Draft shell
 
-```
-subagent({ agentScope: "both", agent: "harness/planning/stack-researcher", task: "<HarnessSpawnContext + stack research brief>" })
-```
+Build draft `PlanPacket` (`contract_version: "1.1.0"`):
+
+- `scope`, `assumptions`, `acceptance_checks`, `risk_level`, `rollback_plan`
+- `execution_plan` placeholder until Phase 4b
 
-`write_harness_yaml` → `artifacts/stack.yaml`; merge into `research-brief.yaml` → `stack`.
+Initialize `research-brief.yaml` with decomposition + hypothesis + Phase 3.5 merges (`write_harness_yaml`).
+
+**`ask_user` on material `dialectical_fork`** after Phase 3.5 merge (evidence-backed — conflicting external patterns may trigger `human_required` from eligibility).
 
 ## Phase 4b — Execution plan author
 
 ```
-subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author", task: "<HarnessSpawnContext + execution plan brief>" })
+subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author", task: "<HarnessSpawnContext + PlanImplementationResearchBrief + PlanStackBrief + decomposition/hypothesis>" })
 ```
 
 Merge `execution_plan` into draft `plan-packet.yaml` (`write_harness_yaml`). Save `artifacts/execution-plan-draft.yaml` the same way.
@@ -102,37 +120,71 @@ node .pi/scripts/validate-plan-dag.mjs --packet .pi/harness/runs/<run_id>/plan-p
 
 Must **pass** before debate. On fail: fix via author or parent patches, re-run.
 
-## Phase 5 — Review Gate debate (4 rounds, pi-messenger, even with `--quick`)
+## Phase 4d — Debate eligibility (before Review Gate)
+
+```
+harness_plan_debate_eligibility({ risk_level, material_fork, dag_pass: true, ... })
+```
+
+Pre-debate signals only (no R1 hypothesis output). Default profile **standard** when ambiguous.
 
-1. `harness_debate_open` (debate id normalized to `plan-<run_id>`; creates `debate-messenger/` inboxes + threads).
-2. Optional: `harness_plan_scope_check` after decomposition — if `material_drift`, `ask_user` before continuing.
-3. For rounds 1–4 (`debate_round_focus`: spec, wbs, schedule, quality):
+If `human_required: true` → `ask_user` before `harness_debate_open`.
+
+Then:
+
+```
+harness_debate_open({ debate_profile, required_focuses })
+```
 
-| Round | Lane spawns (sequential) | Messenger |
-|-------|--------------------------|-----------|
-| 1 | `hypothesis-validator` (blind) → `plan-evaluator` → `plan-adversary` | evaluator `claim` → adversary `rebuttal` (`in_reply_to` claim ids) |
-| 2 | `plan-evaluator` → `plan-adversary` | same |
-| 3 | `plan-evaluator` → `plan-adversary` | same |
-| 4 | `plan-evaluator` → `plan-adversary` → **`sprint-contract-auditor`** | same + audit message optional |
+Profiles:
 
-Lane YAML + messenger claims/rebuttals are **auto-applied** when each debate subagent completes (`harness-debate-lane-applied` entry). You may also call `harness_debate_apply_lane` if fenced YAML was truncated.
+| Profile | Focuses required | min_focus_rounds |
+|---------|------------------|------------------|
+| full | spec, wbs, schedule, quality | 4 |
+| standard | all four | 4 |
+| light | spec, quality only | 2 |
 
-Per round (no prose-only turns — **always call a tool**):
+## Phase 5 — Review Gate debate (profile-aware, pi-messenger, even with `--quick`)
 
-1. Spawn lane agents (evaluator → adversary → integrator; R1/R4 extras per table).
-2. After each subagent: verify `harness-debate-next-step` message or run `harness_debate_round_status({ round_index: N })`.
-3. Before adversary: `harness_messenger_read_round` → include transcript in adversary task.
-4. After integrator: `harness_debate_submit_round({ round_index, integrator_draft })` (writes review-round + bus round + integrate message — **do not** `write_harness_yaml` review-round paths).
+**Forbidden:** parallel `subagent` calls for any debate lane agent in one batch. One lane agent per tool batch, in order.
+
+1. Optional: `harness_plan_scope_check` — if `material_drift`, `ask_user` before debate.
+2. Drive debate with **`harness_debate_focus_coverage`** and **`harness_debate_round_status({ round_index, debate_round_focus })`** — cover **required_focuses** from eligibility, not always all four.
+
+### Focus coverage (required before consensus)
+
+Each required focus must appear in a submitted `review-round-rN.yaml` (`debate_round_focus`). Monotonic `round_index` (cap from profile). Consensus only when:
+
+- all **required** focuses covered, **and**
+- last round `review_gate_ready: true`, **and**
+- `validate-plan-dag.mjs` still passes (re-run after patches).
+
+### Per-round state machine
+
+```
+round_index := next uncovered required focus
+debate_round_focus := spec | wbs | schedule | quality for this round
+
+IF round_index == 1:
+  spawn hypothesis-validator (blind — no decomposition/PlanPacket/scouts/prior debate)
+WHILE NOT ready_for_integrator (harness_debate_round_status with debate_round_focus):
+  follow next_tool exactly (one subagent per batch)
+  IF debate_round_focus == quality OR round_index >= 4:
+    spawn sprint-contract-auditor
+spawn review-integrator → harness_debate_submit_round({ round_index, integrator_draft })
+harness_debate_focus_coverage  // repeat until missing required focuses empty
+harness_debate_consensus
+```
 
-5. `harness_debate_consensus` after round 4.
+Debate agents **must not** call `web_search` / `web_fetch` — cite `artifacts/implementation-research.yaml` instead.
 
-**Never** echo `/harness-debate-*` in bash. **Never** end a turn during Phase 5 with only narration (e.g. "Let me post claims") — the next tool call must be in the **same** assistant message or immediately after `harness-debate-next-step`.
+**Never** end a Phase 5 turn with prose only — next action must be a harness tool or single sequential `subagent`.
 
-**R1 blind rule:** hypothesis-validator prompt must exclude decomposition, scouts, PlanPacket, prior debate.
+**R1 blind rule:** hypothesis-validator sees only task + `PlanHypothesisBrief`.
 
 If R1 `revision_recommended` or `relevance.passes === false`: one `hypothesis` re-spawn, update brief, continue.
 
-**Blockers:** `policy_decision: block` → do not `approve_plan`. `human_required` → `ask_user` before approval.
+**Blockers:** `policy_decision: block` → no `approve_plan`. `human_required` → `ask_user` first.
 
 ## Phase 5b — Revise packet
 
@@ -142,7 +194,7 @@ Set `research_brief.eval` from R1 `hypothesis-validator` output.
 
 ## Phase 6 — Approval + persistence
 
-1. `approve_plan` with `plan_packet`, `human_summary`, `research_brief` (paths/summaries OK).
+1. `approve_plan` with `plan_packet`, `human_summary`, `research_brief` (include `implementation` section). Missing `artifacts/implementation-research.yaml` → **error** on `--risk high`, **warn** otherwise.
 2. On Approve: `create_plan` with same packet (`contract_version: "1.1.0"` + `execution_plan`).
 3. Confirm `plan_ready: true` → `next_command: /harness-run`.
 
@@ -152,4 +204,4 @@ Post-execute adversary: `/harness-critic` only (not plan-phase agents).
 
 - `plan_status`: ready | partial | needs_clarification
 - `plan_review_path` for human review
-- DAG `pass` + 4 debate rounds + consensus not `block` before ready
+- DAG `pass` + required focus areas covered + consensus not `block` before ready

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

@@ -1,6 +1,6 @@
 ---
 description: Execute only against an approved PlanPacket with strict phase gates.
-argument-hint: "[--budget <amount>]"
+argument-hint: ""
 ---
 
 # harness-run
@@ -9,7 +9,7 @@ Orchestrator only — spawn `harness/executor`. Do **not** implement inline.
 
 ## Step 0 — Parse arguments
 
-- optional: `--budget <amount>`
+- `--budget` is reserved/no-op (telemetry-only budgets by default)
 - Do **not** use `--plan` on happy path — load from `[HarnessActivePlan]` / `plan_packet_path`.
 
 If plan not ready:

package/.pi/prompts/planning-rubrics.md

@@ -0,0 +1,31 @@
+# Planning Review Gate rubrics (spawn fragment)
+
+Parent includes this file in debate agent spawn text. Stable check ids by `debate_round_focus`.
+
+## spec
+
+- SC-01: Every acceptance_check maps to scope or execution_plan work_item
+- SC-02: Out-of-scope work is listed in decomposition `excluded`
+- SC-03: Hypothesis brief falsifiability and success metrics are testable
+- SC-04: Risk register covers top technical unknowns
+
+## wbs
+
+- WB-01: Each work_item has typed `done_criteria` (not vague “implement X”)
+- WB-02: No orphan work_items (every item on critical path or sprint_contract)
+- WB-03: `depends_on` is acyclic; parallel_safe only when files disjoint
+- WB-04: wbs_dictionary entry per non-trivial work_item
+
+## schedule
+
+- SH-01: `schedule_metadata.critical_path_work_item_ids` is non-empty for med/high risk
+- SH-02: Phase entry/exit criteria are observable
+- SH-03: Milestones align with acceptance_checks dates where stated
+- SH-04: No impossible parallelism (same file, conflicting owners)
+
+## quality
+
+- QL-01: sprint_contract.done_criteria_types complete (ADR-020)
+- QL-02: Verify/lint/test work_items in early phases when risk ≥ med
+- QL-03: Checkpoint gaps between phases documented
+- QL-04: Keep Quality Left — no “test at end only” without justification

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

@@ -37,6 +37,8 @@ const REQUIRED_ADRS = [
 	"0009-sentrux-rules-lifecycle.md",
 	"0031-harness-run-context.md",
 	"0032-harness-command-orchestration.md",
+	"0037-subagent-submit-tools.md",
+	"0038-budget-telemetry-only.md",
 ];
 
 const REQUIRED_EXTENSIONS = [

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.16.0] — 2026-05-19
+
+### ✨ Features
+
+- add submit pipeline and planning/debate updates
+
+### 🔧 Chores
+
+- refresh graph artifacts after harness updates
+
+## [v0.15.0] — 2026-05-19
+
+### ✨ Features
+
+- **Live widget:** Single-row footer with current/next pipeline phase and plain-language status hints; removes inFlight, policy jargon, and flag rows.
+- **Plan phase:** Implementation researcher, selective debate lanes/eligibility, planning rubrics, ADR 0036, and smoke fixture updates.
+
+### ✅ Tests
+
+- Add `harness-live-widget-status` and `plan-debate-eligibility` tests.
+
 ## [v0.14.0] — 2026-05-18
 
 ### ✨ Features

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -84,7 +84,7 @@
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-spawn-budget.test.mjs test/harness-turn-routing.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-live-widget-status.test.ts test/harness-plan-phase-policy.test.mjs test/harness-subagent-policy.test.mjs test/harness-spawn-budget.test.mjs test/harness-spawn-parse.test.mjs test/harness-schema-validate.test.mjs test/harness-turn-routing.test.mjs test/harness-budget-enforce.test.mjs test/harness-submit-policy.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-debate-eligibility.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs",
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
@@ -103,6 +103,8 @@
 	},
 	"dependencies": {
 		"@posthog/pi": "latest",
+		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1",
 		"croner": "^9.0.0",
 		"jimp": "^1.6.1",
 		"nanoid": "^5.1.5",

package/vendor/pi-subagents/src/subagents.ts

@@ -42,6 +42,13 @@ export interface SpawnAuthForward {
 
 export interface HarnessSubagentsOptions {
 	packageRoot?: string;
+	/** Absolute path to harness-subagent-submit.ts for subprocess-only extension loading (Option A). */
+	harnessSubprocessExtensionPath?: string;
+	/** Extra env vars per subprocess (e.g. HARNESS_RUN_ID, HARNESS_RUN_DIR). */
+	resolveSubprocessEnv?: (
+		task: string,
+		agent: AgentConfig,
+	) => Record<string, string> | undefined;
 	defaultAgentScope?: AgentScope;
 	defaultConfirmProjectAgents?: boolean;
 	beforeExecute?: (
@@ -388,8 +395,11 @@ function terminateProcess(proc: ReturnType<typeof spawn>) {
 
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
-function buildSpawnEnv(packageRoot?: string): NodeJS.ProcessEnv {
-	const env = { ...process.env };
+function buildSpawnEnv(
+	packageRoot?: string,
+	extra?: Record<string, string>,
+): NodeJS.ProcessEnv {
+	const env = { ...process.env, ...extra };
 	env.PI_HARNESS_SUBPROCESS = "1";
 	if (packageRoot) {
 		env.UP_PKG = packageRoot;
@@ -411,6 +421,7 @@ async function runSingleAgent(
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
 	packageRoot?: string,
 	spawnAuth?: SpawnAuthForward,
+	subagentsOptions?: HarnessSubagentsOptions,
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 
@@ -434,8 +445,15 @@ async function runSingleAgent(
 	else if (spawnAuth) args.push("--model", spawnAuth.modelRef);
 	if (spawnAuth?.apiKey) args.push("--api-key", spawnAuth.apiKey);
 	if (agent.thinking) args.push("--thinking", agent.thinking);
+	const harnessExt =
+		agent.extensionsOff &&
+		agent.name.startsWith("harness/") &&
+		subagentsOptions?.harnessSubprocessExtensionPath;
 	if (agent.extensionsOff) {
 		args.push("--no-extensions");
+		if (harnessExt) {
+			args.push("-e", harnessExt);
+		}
 		if (agent.skillsOff) args.push("--no-skills");
 	}
 	if (agent.tools && agent.tools.length > 0) {
@@ -443,7 +461,11 @@ async function runSingleAgent(
 	} else if (agent.extensionsOff) {
 		args.push("--no-tools");
 	}
-	const spawnEnv = buildSpawnEnv(packageRoot);
+	const extraEnv = subagentsOptions?.resolveSubprocessEnv?.(task, agent);
+	const spawnEnv = buildSpawnEnv(packageRoot, {
+		...extraEnv,
+		HARNESS_AGENT_ID: agent.name,
+	});
 
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
@@ -856,6 +878,7 @@ export function createSubagentsExtension(
 							makeDetails("chain"),
 							packageRoot,
 							await resolveSpawnAuth(step.agent),
+							options,
 						);
 						results.push(result);
 
@@ -950,6 +973,7 @@ export function createSubagentsExtension(
 							makeDetails("parallel"),
 							packageRoot,
 							await resolveSpawnAuth(t.agent),
+							options,
 						);
 						allResults[index] = result;
 						doneCount += 1;
@@ -987,6 +1011,7 @@ export function createSubagentsExtension(
 							makeDetails("parallel"),
 							packageRoot,
 							await resolveSpawnAuth(aggregator.agent),
+							options,
 						);
 					}
 
@@ -1038,6 +1063,7 @@ export function createSubagentsExtension(
 						makeDetails("single"),
 						packageRoot,
 						await resolveSpawnAuth(params.agent),
+						options,
 					);
 					const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 					if (isError) {