ultimate-pi 0.17.0 → 0.18.1

package/.pi/lib/harness-ui-state.ts

@@ -1,5 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { shouldEmitBlockingBudgetExhausted } from "./harness-budget-enforce.js";
+import {
+	extractCompletionStatuses,
+	getLatestRunContext,
+	nextStepAfterOutcome,
+} from "./harness-run-context.js";
 
 export type HarnessPhase =
 	| "plan"
@@ -99,6 +104,8 @@ export interface HarnessUiState {
 	};
 	traceRunId: string | null;
 	nextRecommendedCommand: string | null;
+	/** Set when active-run.json exists but this session has not run /harness-use-run yet. */
+	crossSessionResumeCommand: string | null;
 }
 
 const DEFAULT_STATE: HarnessUiState = {
@@ -126,6 +133,7 @@ const DEFAULT_STATE: HarnessUiState = {
 	},
 	traceRunId: null,
 	nextRecommendedCommand: null,
+	crossSessionResumeCommand: null,
 };
 
 const RELEVANT_CUSTOM_TYPES = new Set([
@@ -301,17 +309,61 @@ export function createStateFromEntries(entries: unknown[]): HarnessUiState {
 				: null;
 
 	const runCtx = latest.get("harness-run-context") as
-		| { next_recommended_command?: string }
+		| {
+				phase?: HarnessPhase;
+				plan_ready?: boolean;
+				plan_id?: string | null;
+				run_id?: string;
+				next_recommended_command?: string | null;
+				last_completed_step?: string | null;
+				last_outcome?: string | null;
+				status?: string;
+		  }
 		| undefined;
-	state.nextRecommendedCommand =
-		typeof runCtx?.next_recommended_command === "string"
-			? runCtx.next_recommended_command
-			: null;
+	if (runCtx?.plan_ready) {
+		state.planApproved = true;
+		if (typeof runCtx.plan_id === "string") state.planId = runCtx.plan_id;
+	}
+	if (runCtx?.phase) {
+		state.phase = runCtx.phase;
+	}
+	if (typeof runCtx?.run_id === "string") {
+		state.traceRunId = runCtx.run_id;
+	}
+	if (runCtx) {
+		const persisted = runCtx.next_recommended_command;
+		if (typeof persisted === "string" && persisted.startsWith("/")) {
+			state.nextRecommendedCommand = persisted;
+		} else {
+			const statuses = extractCompletionStatuses(entries);
+			state.nextRecommendedCommand = nextStepAfterOutcome({
+				phase: state.phase,
+				planStatus: runCtx.plan_ready ? "ready" : null,
+				lastCompletedStep: runCtx.last_completed_step,
+				lastOutcome: runCtx.last_outcome,
+				executionStatus: statuses.executionStatus,
+				evalStatus: statuses.evalStatus,
+				aborted: runCtx.status === "aborted",
+			});
+		}
+	} else {
+		state.nextRecommendedCommand = null;
+	}
 
 	state.flowSubstate = deriveFlowSubstate(state);
 	return state;
 }
 
+/** Fingerprint for widget refresh — not just session entry count. */
+export function harnessUiEntriesFingerprint(entries: unknown[]): string {
+	const latest = pickLatestCustomEntries(entries);
+	return JSON.stringify({
+		len: entries.length,
+		policy: latest.get("harness-policy-state") ?? null,
+		run: latest.get("harness-run-context") ?? null,
+	});
+}
+
 export type HarnessStatusSeverity =
 	| "accent"
 	| "warning"
@@ -323,8 +375,6 @@ export const HARNESS_PHASE_ORDER: readonly HarnessPhase[] = [
 	"plan",
 	"execute",
 	"evaluate",
-	"adversary",
-	"merge",
 ] as const;
 
 export function formatHarnessPhaseLabel(phase: HarnessPhase): string {
@@ -332,13 +382,11 @@ export function formatHarnessPhaseLabel(phase: HarnessPhase): string {
 		case "plan":
 			return "plan";
 		case "execute":
-			return "build";
+			return "run";
 		case "evaluate":
-			return "eval";
 		case "adversary":
-			return "review";
 		case "merge":
-			return "merge";
+			return "review";
 	}
 }
 
@@ -348,6 +396,25 @@ export function nextHarnessPhase(phase: HarnessPhase): HarnessPhase | null {
 	return HARNESS_PHASE_ORDER[index + 1] ?? null;
 }
 
+function mainPhaseCommandForStatus(state: HarnessUiState): string | null {
+	const command = state.nextRecommendedCommand;
+	if (!command) return null;
+	const normalized = command.toLowerCase();
+
+	if (normalized.includes("/harness-plan")) {
+		return normalized.includes("revise")
+			? "/harness-plan (mode: revise)"
+			: "/harness-plan";
+	}
+	if (normalized.includes("/harness-review")) return "/harness-review";
+	if (normalized.includes("/harness-run-status")) {
+		return state.phase === "execute" ? "/harness-review" : null;
+	}
+	if (normalized.includes("/harness-run")) return "/harness-run";
+	if (normalized.includes("/harness-steer")) return "/harness-run";
+	return null;
+}
+
 function truncateStatusCommand(command: string, maxLen = 40): string {
 	if (command.length <= maxLen) return command;
 	return `${command.slice(0, maxLen - 3)}...`;
@@ -357,6 +424,12 @@ export function deriveHarnessStatusHint(state: HarnessUiState): {
 	text: string;
 	severity: HarnessStatusSeverity;
 } {
+	if (state.crossSessionResumeCommand) {
+		return {
+			text: `Resume: ${truncateStatusCommand(state.crossSessionResumeCommand)}`,
+			severity: "warning",
+		};
+	}
 	if (state.budgetExhausted) {
 		return { text: "Budget limit reached", severity: "error" };
 	}
@@ -372,9 +445,10 @@ export function deriveHarnessStatusHint(state: HarnessUiState): {
 	) {
 		return { text: "Waiting for your input", severity: "warning" };
 	}
-	if (state.nextRecommendedCommand) {
+	const mainPhaseCommand = mainPhaseCommandForStatus(state);
+	if (mainPhaseCommand) {
 		return {
-			text: `Next: ${truncateStatusCommand(state.nextRecommendedCommand)}`,
+			text: `Next: ${truncateStatusCommand(mainPhaseCommand)}`,
 			severity: "accent",
 		};
 	}
@@ -392,32 +466,51 @@ export function deriveHarnessStatusHint(state: HarnessUiState): {
 	}
 	switch (state.phase) {
 		case "execute":
-			return { text: "Implementing changes", severity: "accent" };
+			return { text: "Running changes", severity: "accent" };
 		case "evaluate":
-			return { text: "Running checks", severity: "accent" };
 		case "adversary":
-			return { text: "Review gate", severity: "accent" };
+			return { text: "Reviewing changes", severity: "accent" };
 		case "merge":
-			return { text: "Ready to finish", severity: "accent" };
+			return { text: "Review complete", severity: "accent" };
 		default:
 			return { text: "Planning", severity: "muted" };
 	}
 }
 
 export class HarnessUiStateStore {
-	private lastEntriesLen = -1;
+	private lastFingerprint = "";
+	private crossSessionResumeCommand: string | null = null;
 	private cachedState: HarnessUiState = {
 		...DEFAULT_STATE,
 		severity: { ...DEFAULT_STATE.severity },
 	};
 
-	/** Refresh from session entries with a lightweight length-based memoization. */
+	public setCrossSessionResumeCommand(command: string | null): void {
+		this.crossSessionResumeCommand = command;
+	}
+
+	private applyCrossSessionOverlay(state: HarnessUiState): HarnessUiState {
+		if (!this.crossSessionResumeCommand) {
+			return { ...state, crossSessionResumeCommand: null };
+		}
+		return {
+			...state,
+			crossSessionResumeCommand: this.crossSessionResumeCommand,
+		};
+	}
+
+	/** Refresh from session entries; recompute when harness policy/run context changes. */
 	public refresh(ctx: ExtensionContext): HarnessUiState {
 		const entries = ctx.sessionManager.getEntries();
-		if (entries.length !== this.lastEntriesLen) {
+		const fingerprint = harnessUiEntriesFingerprint(entries);
+		if (fingerprint !== this.lastFingerprint) {
 			this.cachedState = createStateFromEntries(entries);
-			this.lastEntriesLen = entries.length;
+			this.lastFingerprint = fingerprint;
+			if (getLatestRunContext(entries)) {
+				this.crossSessionResumeCommand = null;
+			}
 		}
+		this.cachedState = this.applyCrossSessionOverlay(this.cachedState);
 		return this.cachedState;
 	}
 

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

@@ -18,15 +18,15 @@ If task missing:
 
 ## Orchestration (required) — same session
 
-Follow **harness-plan** performance rules (`subagent` with parallel `tasks`, `agentScope: "both"`).
+Follow **harness-plan** performance rules (`subagent` with `agentScope: "both"`). Use parallel `tasks` only for Phase 3.5 research (≤2 lanes) when subprocesses are needed. Never parallelize decompose∥hypothesis or debate lanes — precheck enforces this.
 
-1. **Plan** — follow `/harness-plan` (parallel scouts → parallel decompose/hypothesis → draft PlanPacket → debate rounds → parent `approve_plan` + `create_plan`). No second approval pass.
-2. **Execute** — `subagent({ agent: "harness/executor", task: "<HarnessSpawnContext mode execute>" })`; summarize handoff bullets only (do not paste full subprocess log).
-3. **Eval** — `subagent({ agent: "harness/evaluator", task: "<mode benchmark>" })` after parent scripts if needed.
-4. **Review** — `subagent({ agent: "harness/evaluator", task: "<mode verdict>" })` when strict gates require.
-5. **Adversary** — `subagent({ agent: "harness/adversary", ... })`. **Skip when `--quick`**.
-6. **Tie-breaker** — `subagent({ agent: "harness/tie-breaker", ... })` only if debate unresolved and **not** `--quick`.
-7. **Parent** — apply locked strict gates below; commit/PR only if all pass.
+1. **Plan** — follow `/harness-plan` (context → lakes/synthesis or sequential framing → research → plan-verify → `approve_plan()` + `create_plan()`). One approval.
+2. **Execute** — `harness/running/executor` with `executor_strategy` from packet (default `single_pass` for low/med).
+3. **Review** — always **`/harness-review`** after execute (no benchmark fail-fast).
+4. **Steer loop** — while `review-outcome.remediation_class === implementation_gap` and `steer_attempt < HARNESS_STEER_MAX_ATTEMPTS`: `/harness-steer` → `/harness-review` (tiered adversary on attempts 2+).
+5. **Parent** — apply locked strict gates; commit/PR only when `remediation_class: pass`.
+
+Do **not** call separate `/harness-eval` or `/harness-critic` (deprecated aliases of `/harness-review`).
 
 Review agents run in isolated subprocesses via `subagent` (same parent session).
 
@@ -47,10 +47,10 @@ Block commit/PR if any fails: plan gate, execution in scope, evaluator pass, adv
 
 ## Notes
 
-- `--quick` reduces breadth (skips semantic scout, post-run adversary, tie-breaker), never core safety gates on plan approval or evaluator.
+- `--quick` reduces breadth (skips semantic coverage in planning context, post-run adversary, tie-breaker), never core safety gates on plan approval or evaluator.
 - High risk/ambiguity → stop and recommend manual `/harness-plan` with `ask_user`.
 - Interrupt: `/harness-abort [reason]` then `/harness-plan`.
-- Artifact refs under active run dir; `/harness-run-status` or `/harness-trace-last` for handoff.
+- Artifact refs under active run dir; use `/harness-trace` for handoff and forensics.
 
 ## Completion
 

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

@@ -1,37 +1,10 @@
 ---
-description: Adversarial reviewer command with reproducible, merge-blocking findings.
+description: "Deprecated alias — use /harness-review (includes adversary phase)."
 argument-hint: "[--run <run-id>] [--trace <trace-ref>] [--risk low|med|high]"
 ---
 
 # harness-critic
 
-Orchestrator — spawn `harness/adversary`.
+**This command is deprecated.** Run **`/harness-review`** instead — Phase 4 runs `harness/reviewing/adversary` after benchmark and policy verdict pass (skip with `--quick`).
 
-## Step 0 — Parse arguments
-
-- optional: `--run <run-id>` (recovery only)
-- optional: `--trace <trace-ref>`, `--risk low|med|high`
-
-Happy path: omit `--run`.
-
-## Orchestration (required)
-
-1. Build `HarnessSpawnContext` with `mode: adversary`, run artifacts, plan path, trace refs.
-2. Spawn:
-
-```
-subagent({ agentScope: "both", agent: "harness/adversary", task: "…" })
-```
-
-3. Parse `AdversaryReport` JSON from tool result; parent persists for severity policy.
-
-## Parent rules
-
-- Assume hidden regressions until disproven (in subagent).
-- No new Pi session required.
-
-## Completion
-
-- `block_merge` decision
-- Top findings with repro pointers
-- `recommendation`: `proceed`, `conditional_pass`, or `block`
+If you must continue this turn only: forward to `/harness-review` with the same `$ARGUMENTS` (omit `--quick` if you need adversary). Do not spawn adversary in isolation unless the user explicitly requested adversary-only review.

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

@@ -1,43 +1,10 @@
 ---
-description: Run focused benchmark/eval checks and emit structured harness verdict artifacts.
-argument-hint: "[--run <run-id>] [--baseline <ref>] [--suite <name>]"
+description: "Deprecated alias — use /harness-review (post-run master orchestrator)."
+argument-hint: "[--run <run-id>] [--quick] [--trace <trace-ref>]"
 ---
 
 # harness-eval
 
-Orchestrator — run deterministic scripts in parent if needed, then spawn `harness/evaluator` with `mode: benchmark`.
+**This command is deprecated.** Run **`/harness-review`** instead — it orchestrates deterministic gates, benchmark eval, policy verdict, and adversary review in one flow (ADR 0039).
 
-## Step 0 — Parse arguments
-
-- optional: `--run <run-id>` (recovery only)
-- optional: `--baseline <ref>`, `--suite <name>`
-
-Happy path: omit `--run`; use active run from `[HarnessRunContext]`.
-
-If no active run:
-
-`No active run. Finish /harness-plan and /harness-run first, or use /harness-run-status.`
-
-## Orchestration (required)
-
-1. Load plan scope from `[HarnessActivePlan]` (read-only).
-2. Parent may run: project tests, `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` — capture output paths.
-3. Build `HarnessSpawnContext` with `mode: benchmark`, artifact paths, metrics files.
-4. Spawn:
-
-```
-subagent({ agentScope: "both", agent: "harness/evaluator", task: "<HarnessSpawnContext + eval brief>" })
-```
-
-5. Parse eval JSON from tool result; parent writes structured artifacts under run dir.
-6. Do not edit `plan-packet.yaml`.
-
-## Parent rules
-
-- Treat executor output as untrusted; pass artifact paths only.
-- No new Pi session required — subagent has isolated context.
-
-## Completion
-
-- `eval_status`: `pass` or `fail`
-- `next_command`: `/harness-review` on pass; `/harness-plan` or `/harness-incident` on fail
+If you must continue this turn only: forward all work to `/harness-review` with the same arguments (`$ARGUMENTS`). Do not spawn a separate benchmark-only pass unless the user explicitly asked for benchmark-only diagnostics.

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

@@ -1,38 +1,45 @@
 ---
-description: PM-grade harness plan — scouts, implementation research, ExecutionPlan, DAG validation, selective Review Gate debate, approval.
+description: PM-grade harness plan — planning context, 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>/`.
+You are the **planning orchestrator** (agent-native; ADR 0042). Produce an execution baseline (`plan-packet.yaml` + `plan-review.md`) with **lake-sized** outcomes and path-first tools. Parent owns gates: `ask_user`, `approve_plan({ human_summary? })`, `create_plan()`, plan-verify, and scoped writes under `.pi/harness/runs/<run_id>/`.
 
-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.
+**Practice map:** `.pi/harness/docs/practice-map.md` — phase → proven practice → agent → spawn topology.
+
+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`, `planning-context.yaml`, and integrator patches.
 
 ## Allowed subagents
 
-- `harness/planning/scout-graphify`
-- `harness/planning/scout-structure`
-- `harness/planning/scout-semantic` (skip when `--quick`)
+- `harness/planning/planning-context` (optional — prefer parent tools for Phase 1)
 - `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)
-- `harness/planning/plan-evaluator`
-- `harness/planning/plan-adversary`
-- `harness/planning/sprint-contract-auditor`
-- `harness/planning/review-integrator`
+- `harness/planning/implementation-researcher` (optional when parent can spike inline)
+- `harness/planning/stack-researcher` (optional when parent can spike inline)
+- `harness/planning/plan-synthesizer` (low/med — merges framing + hypothesis + execution plan)
+- `harness/planning/execution-plan-author` (high risk or synthesizer decline)
+- `harness/planning/hypothesis-validator` (debate R1 only — blind verifier)
+- `harness/planning/plan-evaluator` (inspector)
+- `harness/planning/plan-adversary` (red team)
+- `harness/planning/sprint-contract-auditor` (DoD auditor)
+- `harness/planning/review-integrator` (recorder / integration PM)
 
 Read **harness-debate-plan** skill before Review Gate rounds.
 
+## Team topology (spawn laws)
+
+1. Parallel `tasks` only for **independent** merges (implementation ∥ stack research; plan-evaluator ∥ plan-adversary for `parallel_probes`). **Never** parallelize decompose ∥ hypothesis.
+2. Max **2** research lanes, **1** debate agent, **1** optional `planning-context` subagent per `subagent` call.
+3. Downstream agents **read** upstream artifacts — do not re-derive (see practice-map anti-patterns).
+
 ## Performance rules
 
-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.
+1. Use `subagent` with `agentScope: "both"` and parallel `tasks` only where the practice map allows.
+2. Each `subagent` call blocks until subprocesses finish.
 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 + research + debate pipeline without skipping lanes for budget.
+4. Choose tools and subprocesses by task need — do not spawn lanes for ceremony. Hard gates (DAG, debate, approval) are never skipped 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`
@@ -40,60 +47,87 @@ Read **harness-debate-plan** skill before Review Gate rounds.
 - task (required)
 - `--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, **Phase 3.5 implementation research**, stack research, execution plan, DAG validation, or **Review Gate debate**.
+`--quick` skips **semantic** coverage in planning context and post-run adversary only — **never** skip adequate reconnaissance (`planning-context.yaml`), decompose, hypothesis, Phase 3.5 **artifacts**, execution plan, DAG validation, or **Review Gate debate**.
 
 ## Active plan context
 
 Use `[HarnessActivePlan]` / `[HarnessRunContext]` only. On revise: preserve `plan_id` / `task_id`. Canonical paths: `plan-packet.yaml`, `research-brief.yaml`, `artifacts/*.yaml`.
 
-## Phase 0 — Semantic index (automatic)
+## Phase 0 — Tooling / fast feedback (automatic)
 
-Do **not** run `ccc index` or `ccc search --refresh`. The harness runs incremental `ccc index` before subagent spawns. Proceed directly to Phase 1 scouts.
+**Practice:** Invest in iteration speed (Pragmatic Programmer).
 
-## Phase 1 — Parallel scouts
+Do **not** run `ccc index` or `ccc search --refresh`. The harness runs incremental `ccc index` before subagent spawns when you use subprocesses. Proceed to Phase 1.
 
-```json
-{
-  "agentScope": "both",
-  "tasks": [
-    { "agent": "harness/planning/scout-graphify", "task": "<HarnessSpawnContext + graphify lane>" },
-    { "agent": "harness/planning/scout-structure", "task": "<HarnessSpawnContext + structure lane>" }
-  ]
-}
+## Phase 1 — Reconnaissance before WBS (parent-led, default)
+
+**Practice:** Shared context before scope decomposition — use the right tools for the job (graphify → sg → ccc → read per `AGENTS.md`).
+
+**Default (no subprocess):** As parent, gather reconnaissance with tools as needed for the task:
+
+1. Read `graphify-out/GRAPH_REPORT.md` when present; use `graphify query` / `explain` / `path` for architecture and cross-module relationships.
+2. Use `sg -p '…'` for structural surfaces (handlers, types, exports).
+3. Use `ccc search` for semantic implementation matches (unless `--quick` — set `coverage.semantic.status: skipped`).
+4. Write `artifacts/planning-context.yaml` via `write_harness_yaml` with `schema_version: "1.0.0"`, `status`, `summary`, `coverage` (architecture + structure required; semantic per risk/quick), `findings`, `evidence_refs`, `open_questions`.
+
+**Optional subprocess:** Spawn **at most one** `harness/planning/planning-context` when the brief is large or you need context isolation.
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/planning-context.yaml"] })`.
+
+## Phase 2a — WBS / scope decomposition (sequential)
+
+**Practice:** PMBOK scope / WBS; Berkun — how the team divides work.
+
+```
+subagent({ agentScope: "both", agent: "harness/planning/decompose", task: "<HarnessSpawnContext + path to planning-context.yaml>" })
 ```
 
-Add `harness/planning/scout-semantic` to `tasks` unless `--quick`. Require graphify + structure success. Semantic lane uses `ccc search` only (see `scout-semantic` agent).
+Gate: `harness_artifact_ready({ paths: ["artifacts/decomposition.yaml"] })`.
+
+Decompose **prior_art** is **internal only** (from Phase 1). External prior art arrives in Phase 3.5.
+
+## Phase 2b — Hypothesis-driven approach (sequential)
 
-After scouts: `harness_artifact_ready({ paths: ["artifacts/scout-graphify.yaml", "artifacts/scout-structure.yaml", ...] })`.
+**Practice:** Lean exploration — falsifiable claim before plan detail (DARWIN / ADR 0034).
 
-## Phase 2 & 3 — Decompose + hypothesis (parallel)
+**Requires** `artifacts/decomposition.yaml`. Do **not** spawn in parallel with decompose.
 
-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`.
+```
+subagent({ agentScope: "both", agent: "harness/planning/hypothesis", task: "<HarnessSpawnContext + path to artifacts/decomposition.yaml + planning-context summary>" })
+```
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/hypothesis.yaml"] })`.
 
-Decompose **prior_art** is **internal only** (from scouts). External prior art arrives in Phase 3.5.
+## Phase 3.5 — Spike / external solution research (required artifacts)
 
-## Phase 3.5 — External solution research (required)
+**Practice:** Lean — external patterns before commitment.
 
-**MUST** run unless you document a `human_required` waiver in the run trace. Parallel batch:
+**Required outcome:** `artifacts/implementation-research.yaml` and `artifacts/stack.yaml` for med/high risk (recommended for low). **Not** required subprocesses.
+
+**Parent may:** run web research inline and write artifacts via `write_harness_yaml`, or spawn researchers when external spike warrants isolation:
 
 ```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>" }
+    { "agent": "harness/planning/implementation-researcher", "task": "…" },
+    { "agent": "harness/planning/stack-researcher", "task": "…" }
   ]
 }
 ```
 
 - 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.
+- **Partial failure:** if one lane fails, re-spawn that lane once; if still failing write `artifacts/plan-phase-status.yaml` with `plan_status: partial` and `ask_user`. Do not proceed to Phase 4b without both research artifacts unless `artifacts/plan-phase-waiver.yaml` records an explicit waiver.
 - **Web dedup:** implementation owns patterns/repos; stack owns libraries/versions — no overlapping queries.
 
+Document `human_required` waiver in the run trace only when research is genuinely blocked.
+
 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 4 — Draft shell
+## Phase 4 — Draft shell + fork resolution
+
+**Practice:** Crucial Conversations — pool of shared meaning when forks exist.
 
 Build draft `PlanPacket` (`contract_version: "1.1.0"`):
 
@@ -104,7 +138,9 @@ Initialize `research-brief.yaml` with decomposition + hypothesis + Phase 3.5 mer
 
 **`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
+## Phase 4b — Schedule + WBS detail
+
+**Practice:** CPM / `depends_on` scheduling (Kerzner).
 
 ```
 subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author", task: "<HarnessSpawnContext + PlanImplementationResearchBrief + PlanStackBrief + decomposition/hypothesis>" })
@@ -112,7 +148,9 @@ subagent({ agentScope: "both", agent: "harness/planning/execution-plan-author",
 
 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)
+## Phase 4c — Deterministic quality gate (hard stop)
+
+**Practice:** Harness engineering — never trust the model for graph validity.
 
 ```bash
 node .pi/scripts/validate-plan-dag.mjs --packet .pi/harness/runs/<run_id>/plan-packet.yaml --write
@@ -120,7 +158,29 @@ 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 4d — Debate eligibility (before Review Gate)
+## Phase 4e — Architectural intent (optional, risk-tailored)
+
+**Practice:** Architecture governance + integrated change control — evolve **intent** (manifest), not rules.toml, when scope adds bounded contexts.
+
+Spawn **`harness/sentrux-steward`** when **any** apply (after Phase 4b, before Phase 4c):
+
+- Execution plan adds top-level paths not covered by `.pi/harness/sentrux/architecture.manifest.json` layer globs
+- Debate eligibility will use `quality` focus and structural coupling is plausible
+- Prior run reported `sentrux check` failures on a new boundary class
+
+```
+subagent({ agentScope: "both", agent: "harness/sentrux-steward", task: "<HarnessSpawnContext + planning-context + execution-plan-draft + scope paths>" })
+```
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/sentrux-manifest-proposal.yaml"] })`.
+
+If `change_class` ≠ `none` and `human_required` → `ask_user` before manifest edits. Chair applies patch, runs `harness-sentrux-bootstrap.mjs --force`, emits `harness-architecture-changed`. See `/harness-sentrux-steward`.
+
+Do **not** spawn on every plan or when changes stay inside existing layer globs.
+
+## Phase 4d — Tailor process to risk
+
+**Practice:** PMBOK tailoring.
 
 ```
 harness_plan_debate_eligibility({ risk_level, material_fork, dag_pass: true, ... })
@@ -147,11 +207,13 @@ Profiles:
 
 Med/low non-fork plans with clear stack and no implementation `open_questions` default to **fast** (consolidated). Escalate to threaded rounds only when integrator sets `review_gate_ready: false` or records blockers.
 
-`--quick`: skip scout-semantic; cap web research (≤2 searches, ≤3 fetches); prefer **fast** eligibility when DAG passes; use consolidated Review Gate when profile is fast.
+`--quick`: skip semantic coverage in planning context; cap web research (≤2 searches, ≤3 fetches); prefer **fast** eligibility when DAG passes; use consolidated Review Gate when profile is fast.
+
+## Phase 5 — Structured inspection / Review Gate (Fagan-style)
 
-## Phase 5 — Review Gate debate (profile-aware, pi-messenger, even with `--quick`)
+**Practice:** Code Complete collaborative construction; Fagan inspection with rubrics in `planning-rubrics.md`. Parent is **chair**; one debate agent per `subagent` batch.
 
-**Forbidden:** parallel `subagent` calls for any debate lane agent in one batch. One lane agent per tool batch, in order.
+**Forbidden:** parallel `subagent` calls for any debate lane agent in one batch.
 
 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.
@@ -169,10 +231,10 @@ Each required focus must appear in submitted review artifacts (`review-round-rN.
 ```
 round_index := 1
 debate_round_focus := all
-spawn hypothesis-validator (blind)
+spawn hypothesis-validator (blind verifier)
 WHILE NOT ready_for_integrator (harness_debate_round_status round_index=1):
-  follow next_tool (validation-turn, adversary-brief, sprint-audit in parallel-friendly order; one subagent per batch)
-spawn review-integrator → write artifacts/review-round-consolidated.yaml → harness_debate_submit_round
+  follow next_tool (inspector, red team, DoD auditor — one subagent per batch)
+spawn review-integrator (recorder) → harness_debate_submit_round
 IF review_gate_ready false OR blockers: escalate — threaded round per missing focus (spec/wbs/schedule/quality)
 harness_debate_focus_coverage → harness_debate_consensus
 ```
@@ -184,11 +246,11 @@ 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)
+  spawn hypothesis-validator (blind — no decomposition/PlanPacket/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 sprint-contract-auditor (DoD)
 spawn review-integrator → harness_debate_submit_round({ round_index, integrator_draft })
 harness_debate_focus_coverage  // repeat until missing required focuses empty
 harness_debate_consensus
@@ -210,13 +272,13 @@ Apply `recommended_packet_patches` from last integrator round. Re-run `validate-
 
 Set `research_brief.eval` from R1 `hypothesis-validator` output.
 
-## Phase 6 — Approval + persistence
+## Phase 6 — Baseline approval (EVM performance baseline)
 
-1. `approve_plan` with `plan_packet`, `human_summary`, `research_brief` (include `implementation` section). Missing `artifacts/implementation-research.yaml` → **error** on `--risk high`, **warn** otherwise.
+1. `approve_plan` with `plan_packet`, `human_summary`, `research_brief` (include `implementation` section). Tool blocks when reconnaissance/research/decomposition are missing, planning context is `partial`/`failed`, or `plan-phase-status` is not `ready` (unless `plan-phase-waiver.yaml`).
 2. On Approve: `create_plan` with same packet (`contract_version: "1.1.0"` + `execution_plan`).
 3. Confirm `plan_ready: true` → `next_command: /harness-run`.
 
-Post-execute adversary: `/harness-critic` only (not plan-phase agents).
+Post-execute review: `/harness-review` (not plan-phase agents).
 
 ## Completion