ultimate-pi 0.6.1 → 0.7.0

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

@@ -97,6 +97,7 @@ export interface HarnessUiState {
 		testIntegrity: number | null;
 	};
 	traceRunId: string | null;
+	nextRecommendedCommand: string | null;
 }
 
 const DEFAULT_STATE: HarnessUiState = {
@@ -123,6 +124,7 @@ const DEFAULT_STATE: HarnessUiState = {
 		testIntegrity: null,
 	},
 	traceRunId: null,
+	nextRecommendedCommand: null,
 };
 
 const RELEVANT_CUSTOM_TYPES = new Set([
@@ -135,6 +137,7 @@ const RELEVANT_CUSTOM_TYPES = new Set([
 	"harness-test-integrity-flag",
 	"harness-run-trace",
 	"harness-trace-state",
+	"harness-run-context",
 ]);
 
 function asNumber(value: unknown): number | null {
@@ -284,6 +287,14 @@ function createStateFromEntries(entries: unknown[]): HarnessUiState {
 				? traceState.run_id
 				: null;
 
+	const runCtx = latest.get("harness-run-context") as
+		| { next_recommended_command?: string }
+		| undefined;
+	state.nextRecommendedCommand =
+		typeof runCtx?.next_recommended_command === "string"
+			? runCtx.next_recommended_command
+			: null;
+
 	state.flowSubstate = deriveFlowSubstate(state);
 	return state;
 }

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

@@ -13,8 +13,9 @@ Safely abort the current harness run in this session.
   - `phase: plan`
   - `approvedPlan: false`
   - `planId: null`
-- records abort metadata for observability.
-- enables a hard safety lock that blocks mutating tools until a new approved plan is attached.
+- clears active run `plan_ready` (plan files may remain on disk for forensics)
+- records abort metadata for observability
+- enables a hard safety lock that blocks mutating tools until a new approved plan is attached
 
 ## Usage
 
@@ -27,8 +28,8 @@ Examples:
 
 ## Safety guarantees
 
-- no mutating work should continue under the previous run context.
-- a fresh approved plan is required before mutation can resume.
+- no mutating work should continue under the previous run context
+- a fresh approved plan is required before mutation can resume
 
 ## Next step
 
@@ -36,6 +37,8 @@ Run:
 
 `/harness-plan "<task>"`
 
-Then proceed with:
+Then:
 
-`/harness-run --plan <path-to-plan-packet.json>`
+`/harness-run`
+
+(No `--plan` or run id required — the harness restores active context after replan.)

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

@@ -22,7 +22,7 @@ If task is missing, stop and return:
 
 ## Process contract
 
-1. Build and approve plan packet before any mutation.
+1. Build and approve plan packet at the canonical active-run path before any mutation (extension allocates one `run_id` for the auto pipeline).
 2. Execute only approved scope with rollback artifacts.
 3. Run independent evaluator then adversarial reviewer.
 4. Apply severity policy + strict pre-PR gates.
@@ -71,13 +71,13 @@ Block commit/PR if any gate fails:
 - `--risk` can tighten behavior, never disable adversary.
 - If risk/ambiguity is high, auto-fallback to manual `harness-plan` and use `ask_user` for blocking forks.
 - If execution must be interrupted safely, run `/harness-abort [reason]`, then restart with `/harness-plan "<task>"`.
-- Always output trace bundle ID and incident/rollback references.
+- Always output artifact references (`plan`, `eval`, `adversary`, `consensus`, `rollback`) and incident paths when applicable — do not ask the user to copy a run id; point to `/harness-run-status` or `/harness-trace-last` for phase handoff.
 
 ## Completion behavior
 
 End with a deterministic handoff block:
 
 1. `Pipeline status` (pass/fail per strict gate).
-2. `Trace bundle` and artifact references (`plan`, `eval`, `adversary`, `consensus`, `rollback`).
+2. Phase trace summary and artifact references (`plan`, `eval`, `adversary`, `consensus`, `rollback`) under the active run directory.
 3. `Policy outcome` (`pass`, `conditional_pass`, `block`, or `human_required`) with one-line rationale.
 4. `Next action` (open PR, replan, rollback, or human override path).

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

@@ -1,6 +1,6 @@
 ---
 description: Adversarial reviewer command with reproducible, merge-blocking findings.
-argument-hint: "--run <run-id> [--trace <trace-ref>] [--risk low|med|high]"
+argument-hint: "[--run <run-id>] [--trace <trace-ref>] [--risk low|med|high]"
 ---
 
 # harness-critic
@@ -11,12 +11,10 @@ Run adversarial review against the candidate result.
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--run <run-id>`
+- optional: `--run <run-id>` (recovery only)
 - optional: `--trace <trace-ref>`, `--risk low|med|high`
 
-If `--run` is missing, stop and return:
-
-`Usage: /harness-critic --run <run-id> [--trace <trace-ref>] [--risk low|med|high]`
+On the happy path, **omit `--run`**. Use active run context. Prefer a session isolated from execute.
 
 ## Process
 

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

@@ -1,28 +1,33 @@
 ---
 description: Run focused benchmark/eval checks and emit structured harness verdict artifacts.
-argument-hint: "--run <run-id> [--baseline <ref>] [--suite <name>]"
+argument-hint: "[--run <run-id>] [--baseline <ref>] [--suite <name>]"
 ---
 
 # harness-eval
 
-Run focused evaluations for the run and produce structured artifacts.
+Run focused evaluations for the active harness run and produce structured artifacts.
 
 ## Step 0 — Parse arguments
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--run <run-id>`
+- optional: `--run <run-id>` (recovery only — active run is used when omitted)
 - optional: `--baseline <ref>`, `--suite <name>`
 
-If `--run` is missing, stop and return:
+On the happy path, **omit `--run`**. The extension injects the active run from session + project `active-run.json`.
 
-`Usage: /harness-eval --run <run-id> [--baseline <ref>] [--suite <name>]`
+If no active run exists, stop and return:
+
+`No active run. Finish /harness-plan and /harness-run first, or use /harness-run-status.`
+
+Run in a **new Pi session** after execute (review-integrity isolation).
 
 ## Process
 
-1. Run plan-aligned acceptance checks plus focused regressions.
-2. Collect evaluator-compatible metrics and guard outcomes.
-3. Emit structured artifacts keyed by run ID.
+1. Load plan scope from `[HarnessActivePlan]` (read-only).
+2. Run plan-aligned acceptance checks plus focused regressions.
+3. Collect evaluator-compatible metrics and guard outcomes.
+4. Emit structured artifacts under the active run directory.
 
 ## Requirements
 
@@ -35,17 +40,12 @@ If `--run` is missing, stop and return:
 - Do not overthink simple benchmark outcomes; report measured results directly.
 - Only evaluate the requested run/suite/baseline scope.
 - Never report synthetic metrics; include only measured values.
+- Do not edit `plan-packet.json` in this phase.
 
 ## Output
 
-- Benchmark/eval summary table.
-- Structured verdict artifacts referenced by run ID.
-- Pass/fail recommendation for policy gate consumption.
+Structured eval verdict and summary metrics.
 
 ## Completion behavior
 
-End with a compact evaluator handoff:
-
-- measured metrics (`success_rate`, `cost_per_task`, regression guard status)
-- verdict (`pass`/`fail`)
-- artifact paths keyed by run ID
+End with `eval_status` (`pass` or `fail`) and `next_command` (`/harness-review` on pass; `/harness-plan` or `/harness-incident` on fail).

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

@@ -1,6 +1,6 @@
 ---
 description: Create incident record with rollback and override trail for harness failures.
-argument-hint: "--run <run-id> --trigger <reason> [--severity low|med|high|critical]"
+argument-hint: "--trigger <reason> [--run <run-id>] [--severity low|med|high|critical]"
 ---
 
 # harness-incident
@@ -11,12 +11,14 @@ Create a structured incident record for blocked or failed harness runs.
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--run <run-id>`, `--trigger <reason>`
-- optional: `--severity low|med|high|critical`
+- required: `--trigger <reason>`
+- optional: `--run <run-id>` (recovery only), `--severity low|med|high|critical`
 
-If required flags are missing, stop and return:
+If `--trigger` is missing, stop and return:
 
-`Usage: /harness-incident --run <run-id> --trigger <reason> [--severity low|med|high|critical]`
+`Usage: /harness-incident --trigger <reason> [--run <run-id>] [--severity low|med|high|critical]`
+
+Use active run when `--run` is omitted.
 
 ## Process
 

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

@@ -18,12 +18,25 @@ If task is missing, stop and return:
 
 `Usage: /harness-plan "<task>" [--risk low|med|high] [--budget <amount>] [--quick]`
 
+Do **not** require or accept `--plan` on this command.
+
+## Active plan context
+
+If `[HarnessActivePlan]` is present in context:
+
+- Read the current PlanPacket from the injected `plan_packet_path` first.
+- Treat the user task as **revise/amend** of that packet (not a greenfield plan), unless `/harness-new-run` was used.
+- After drift replan or post-abort, update the same canonical file.
+
+If no prior plan file exists, create PlanPacket at the canonical path from `[HarnessRunContext]`.
+
 ## Process
 
 1. Parse the requested task and extract concrete scope and constraints.
 2. If ambiguity blocks safe execution planning, call `ask_user` (harness-decisions skill). Stop with `needs_clarification` if the user cancels.
 3. Build a `PlanPacket` that is valid against `.pi/harness/specs/plan-packet.schema.json`.
-4. Include rollback artifacts in all required forms.
+4. **Write** the PlanPacket JSON to the canonical `plan_packet_path` before completing.
+5. Include rollback artifacts in all required forms.
 
 ## Hard requirements
 
@@ -35,6 +48,7 @@ If task is missing, stop and return:
   - prepared revert branch name
   - patch bundle path
 - Set risk level to `high` if uncertainty, broad blast radius, or policy-sensitive surfaces are involved.
+- Do **not** embed `plan_id=` in the user prompt for policy sync — the extension sets `approvedPlan` from the written file.
 
 ## Guardrails
 
@@ -51,7 +65,7 @@ Return:
    - assumptions
    - acceptance checks
    - rollback plan
-2. A valid JSON `PlanPacket` object.
+2. Confirmation that PlanPacket was written to the canonical path.
 
 Do not proceed to execution from this command.
 
@@ -61,4 +75,5 @@ Always end with:
 
 - one-line `plan_status` (`ready` or `needs_clarification`)
 - the final `risk_level` used
-- explicit `next_command` recommendation (`/harness-run --plan ...` or clarification request)
+- explicit `next_command` recommendation: `/harness-run` when `ready` (never `/harness-run --plan …`)
+- if `needs_clarification`, tell the user they may reply in plain language or run `/harness-plan` again with updates

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

@@ -1,6 +1,6 @@
 ---
 description: Independent evaluator pass/fail verdict in session isolation mode.
-argument-hint: "--run <run-id> [--trace <trace-ref>]"
+argument-hint: "[--run <run-id>] [--trace <trace-ref>]"
 ---
 
 # harness-review
@@ -11,12 +11,11 @@ Produce an independent evaluator verdict.
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--run <run-id>`
+- optional: `--run <run-id>` (recovery only)
 - optional: `--trace <trace-ref>`
 
-If `--run` is missing, stop and return:
-
-`Usage: /harness-review --run <run-id> [--trace <trace-ref>]`
+On the happy path, **omit `--run`**. Use active run context from `[HarnessRunContext]`.
+Run in a **new Pi session** after execute when possible.
 
 ## Process
 

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

@@ -20,7 +20,7 @@ If required args are missing, stop and return:
 
 ## Process
 
-1. Validate evidence completeness and guard status.
+1. Validate evidence completeness and guard status. Evidence may live under `.pi/harness/runs/<run_id>/` for the active harness run when produced by `/harness-eval` (resolve via active run context or explicit paths — no run id required on the happy path).
 2. Generate a proposal artifact only (no live router mutation).
 3. Require explicit human approval metadata before any apply step.
 

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

@@ -1,37 +1,36 @@
 ---
 description: Execute only against an approved PlanPacket with strict phase gates.
-argument-hint: "--plan <path-to-plan-packet.json> [--budget <amount>]"
+argument-hint: "[--budget <amount>]"
 ---
 
 # harness-run
 
-Execute implementation only after an approved plan exists.
+Execute implementation only after an approved plan exists in active run context.
 
 ## Step 0 — Parse arguments
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--plan <path-to-plan-packet.json>`
 - optional: `--budget <amount>`
 
-If `--plan` is missing, stop and return:
+Do **not** parse `--plan` on the happy path. Load the PlanPacket from `[HarnessActivePlan]` / injected `plan_packet_path` only.
 
-`Usage: /harness-run --plan <path-to-plan-packet.json> [--budget <amount>]`
+If the extension reports plan not ready, stop and return:
+
+`Run /harness-plan first — no approved plan in active run context.`
+
+Advanced recovery only: `--plan <path>` must live under the active run directory (extension validates).
 
 ## Process
 
-1. Validate `--plan` input and confirm it is a valid approved `PlanPacket`.
+1. Load PlanPacket from the injected canonical path and confirm it is valid.
 2. Execute only within approved scope.
 3. Run focused validations mapped to approved acceptance checks.
 4. Produce rollback artifacts and handoff references for downstream gates.
 
-## Required input
-
-- `--plan` must point to a valid `PlanPacket`.
-
 ## Gate behavior
 
-- Refuse execution if no valid plan packet is provided.
+- Refuse execution if active plan is not ready (extension blocks before the agent runs).
 - Keep edits strictly within approved scope.
 - If scope drift appears, stop and return to `harness-plan`.
 - For **implementation forks** inside approved scope, call `ask_user` with 2–4 options. For plan-level ambiguity, stop and return to `harness-plan`.
@@ -58,3 +57,4 @@ End with:
 1. `execution_status` (`completed`, `blocked`, or `scope_drift`).
 2. `validation_summary` (pass/fail with command evidence).
 3. `handoff_ready` booleans for evaluator/adversary prerequisites.
+4. `next_command`: **New Pi session → `/harness-eval`** when execution completed successfully.

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

@@ -17,7 +17,7 @@ Bootstraps the complete ultimate-pi agentic harness: Graphify knowledge graph, C
 | Provider detection from `OPENAI_*` / `ANTHROPIC_*` env only | Wrong for pi users — keys live in `~/.pi/agent/auth.json`. Use `harness-generate-model-router.mjs` (Pi `ModelRegistry.getAvailable()`). |
 | Re-running 2.1–2.8 manually after CLI verify | Wasteful — trust `harness-cli-verify.sh` output; only fix reported ✗ lines. |
 | Overwriting `AGENTS.md` after graphify | Graphify appends a section — **merge**, do not replace (Step 4.3). |
-| `sentrux-rules-sync` without project manifest | Use **`harness-sentrux-bootstrap.mjs`** (Step 4.4) — seeds manifest + idempotent rules sync. |
+| `sentrux-rules-sync` without project manifest | Use **`harness-sentrux-bootstrap.mjs`** (Step 4.2) — seeds manifest + idempotent rules sync. |
 | Re-running bootstrap with `--force` on unchanged manifest | Wasteful but safe — default bootstrap skips when hash unchanged; `--force` only after manifest edits. |
 | `graph.json` uses `links`, not `edges` | Step 6 stats: `g.get('edges', g.get('links', []))`. |
 | Guessing harness-web / `.env` defaults when `ask_user` is available | **Mandatory `ask_user`** at Step 4.0 unless `--non-interactive`. |
@@ -319,7 +319,7 @@ Install all 52 language plugins:
 sentrux plugin add-standard 2>/dev/null || echo "Plugins already installed or failed"
 ```
 
-Ensure the **sentrux** Pi skill is linked (see Step 4.2). **Rules.toml bootstrap runs in Step 4.3** (idempotent, merge-safe).
+**Rules.toml bootstrap runs in Step 4.2** (idempotent, merge-safe). Sentrux CLI workflows use the package **`sentrux`** skill (`.agents/skills/sentrux`); no symlink into `.pi/skills/` required.
 
 ## Step 3 — Pi Extension Packages
 
@@ -496,29 +496,7 @@ Ensure `.gitignore` contains:
 !.sentrux/rules.toml
 ```
 
-### 4.2 — Sentrux Pi skill
-
-Pi does **not** load `.pi/mcp.json`. Agents use Sentrux via the **CLI** and the **`sentrux`** skill.
-
-From **project root**, ensure the skill is discoverable (idempotent):
-
-```bash
-UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
-SKILL_SRC="$UP_PKG/.agents/skills/sentrux"
-SKILL_DST=".pi/skills/sentrux"
-if [ -d "$SKILL_SRC" ] && [ ! -e "$SKILL_DST" ]; then
-  ln -s "../../.agents/skills/sentrux" "$SKILL_DST"
-  echo "✓ linked $SKILL_DST → sentrux skill"
-elif [ -e "$SKILL_DST" ]; then
-  echo "✓ sentrux skill already present at $SKILL_DST"
-else
-  echo "✗ missing $SKILL_SRC — reinstall ultimate-pi"
-fi
-```
-
-After `/reload`, agents can invoke **`/skill:sentrux`** for install paths, `sentrux check`, `sentrux gate --save` / `sentrux gate`, and harness integration. **context-mode** remains a separate `npm:context-mode` package in `.pi/settings.json` (its own MCP bridge inside that extension).
-
-### 4.3 — Sentrux rules bootstrap (required)
+### 4.2 — Sentrux rules bootstrap (required)
 
 **Skill:** invoke **harness-sentrux-setup** before hand-editing rules or manifest.
 
@@ -552,7 +530,7 @@ Set up structural regression baseline (optional):
 sentrux gate --save . 2>/dev/null || echo "Baseline will be saved on first gate run"
 ```
 
-### 4.4 — Project AGENTS.md
+### 4.3 — Project AGENTS.md
 
 **Do not overwrite** an existing `AGENTS.md` — graphify bootstrap may have appended a `## Graphify` section. If missing, create minimal onboarding content; if present, only add harness subsections that are absent.
 
@@ -681,7 +659,7 @@ Output summary table:
 | biome | ✓/✗ | Project config: found/default |
 | ast-grep | ✓/✗ | AST-aware code search (`sg`)
 | gh CLI | ✓/✗ | Auth: yes/no |
-| sentrux | ✓/✗ | CLI + plugins; rules via Step 4.3 bootstrap |
+| sentrux | ✓/✗ | CLI + plugins; rules via Step 4.2 bootstrap |
 | Sentrux rules.toml | ✓/✗ | `.sentrux/rules.toml` synced from manifest |
 | pi extensions | ✓/✗ | 4 packages |
 | model router | ✓/✗ | Package + config verified, activation via `/router profile auto` |

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

@@ -1,6 +1,6 @@
 ---
 description: Query and summarize harness run traces for replay and forensics.
-argument-hint: "--run <run-id> [--phase plan|execute|evaluate|adversary|merge]"
+argument-hint: "[--run <run-id>] [--phase plan|execute|evaluate|adversary|merge]"
 ---
 
 # harness-trace
@@ -11,12 +11,10 @@ Retrieve and summarize trace artifacts for a run.
 
 Read `$ARGUMENTS` and parse:
 
-- required: `--run <run-id>`
+- optional: `--run <run-id>` (recovery only)
 - optional: `--phase plan|execute|evaluate|adversary|merge`
 
-If `--run` is missing, stop and return:
-
-`Usage: /harness-trace --run <run-id> [--phase plan|execute|evaluate|adversary|merge]`
+On the happy path, **omit `--run`**. Phase traces live at `trace-<phase>.json` under the active run directory.
 
 ## Process
 

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

@@ -16,6 +16,7 @@ const ADRS = join(ROOT, ".pi", "harness", "docs", "adrs");
 
 const REQUIRED_SCHEMAS = [
 	"harness-run-record.schema.json",
+	"harness-run-context.schema.json",
 	"harness-posthog-event.schema.json",
 	"observation.schema.json",
 	"run-trace.schema.json",
@@ -32,10 +33,12 @@ const REQUIRED_ADRS = [
 	"0007-interactive-drift-monitor.md",
 	"0008-harness-posthog-telemetry.md",
 	"0009-sentrux-rules-lifecycle.md",
+	"0031-harness-run-context.md",
 ];
 
 const REQUIRED_EXTENSIONS = [
 	"harness-telemetry.ts",
+	"harness-run-context.ts",
 	"trace-recorder.ts",
 	"observation-bus.ts",
 	"drift-monitor.ts",
@@ -192,6 +195,21 @@ async function main() {
 	if (!(await fileExists(libPath))) fail("missing lib/harness-posthog.ts");
 	ok("lib/harness-posthog.ts");
 
+	const runCtxLib = join(ROOT, ".pi", "lib", "harness-run-context.ts");
+	if (!(await fileExists(runCtxLib))) fail("missing lib/harness-run-context.ts");
+	ok("lib/harness-run-context.ts");
+
+	const runCtxFixture = join(SMOKE, "run-context.fixture.json");
+	if (!(await fileExists(runCtxFixture))) {
+		fail("missing run-context.fixture.json");
+	}
+	const runCtxData = JSON.parse(await readFile(runCtxFixture, "utf-8"));
+	if (runCtxData.schema_version !== "1.0.0") {
+		fail("run-context fixture schema_version must be 1.0.0");
+	}
+	if (!runCtxData.run_id) fail("run-context fixture missing run_id");
+	ok("run-context.fixture.json");
+
 	const fixture = JSON.parse(
 		await readFile(join(SMOKE, "run-record.fixture.json"), "utf-8"),
 	);

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [v0.7.0] — 2026-05-17
+
+### ✨ Features
+
+- **Harness run context:** track active run and canonical plan path in session; short slash commands without `--run` or `--plan`; project `active-run.json` for forked eval sessions; ADR 0031.
+- **System prompt extension:** load packaged `.pi/SYSTEM.md` by default with optional workspace `.pi/system.md` override.
+
+### 📖 Documentation
+
+- **README and harness prompts:** manual workflow without run IDs; `harness-run-status`, `harness-new-run`, `harness-use-run` helpers.
+
+### 🔧 Chores
+
+- **harness-setup:** remove Sentrux skill symlink step; rules bootstrap only.
+
 ## [v0.6.1] — 2026-05-17
 
 ### 🐛 Fixes

package/README.md

@@ -29,11 +29,12 @@ pi install npm:ultimate-pi
 
 That runs: plan → execute → evaluate → adversary → policy decision. It does **not** auto-merge.
 
-If something blocks, inspect the last run:
+If something blocks, inspect status (no run id needed):
 
 ```text
-/harness-trace-last
+/harness-run-status
 /harness-policy-status
+/harness-trace-last
 ```
 
 ## Commands
@@ -42,15 +43,18 @@ If something blocks, inspect the last run:
 |---------|----------------|
 | `/harness-setup` | One-time project bootstrap (tools, harness dirs, extensions) |
 | `/harness-auto "<task>"` | End-to-end pipeline (recommended) |
-| `/harness-plan "<task>"` | Plan only (no code changes) |
-| `/harness-run --plan <file>` | Execute an approved plan |
-| `/harness-eval --run <run-id>` | Evaluation summary |
-| `/harness-review --run <run-id>` | Independent review verdict |
-| `/harness-critic --run <run-id>` | Adversarial review |
-| `/harness-trace --run <run-id>` | Full trace for a run |
-| `/harness-trace-last` | Summary of the most recent run |
+| `/harness-plan "<task>"` | Create or **revise** the active plan in context (no plan path to copy) |
+| `/harness-run` | Execute the active plan from context (**no `--plan`** on happy path) |
+| `/harness-eval` | Eval for active run (optional `--run`; **new session** after execute) |
+| `/harness-review` | Independent review (optional `--run`) |
+| `/harness-critic` | Adversarial review (optional `--run`) |
+| `/harness-trace` | Trace summary (optional `--run`) |
+| `/harness-run-status` | Where you are + what to run next (no run id shown) |
+| `/harness-new-run` | Abandon current run and start fresh |
+| `/harness-use-run <id>` | Advanced recovery only |
+| `/harness-trace-last` | Last phase / handoff (no run id) |
 | `/harness-policy-status` | Current policy / block reasons |
-| `/harness-abort [reason]` | Stop and return to plan-only mode |
+| `/harness-abort [reason]` | Stop and replan path |
 
 ## Manual workflow
 
@@ -58,15 +62,24 @@ Use this when you want each step separate:
 
 ```text
 /harness-plan "your task"
-/harness-run --plan .pi/harness/runs/<run-id>/plan-packet.json
-/harness-eval --run <run-id>
-/harness-review --run <run-id>
-/harness-critic --run <run-id>
+/harness-run
+# New Pi session (review isolation):
+/harness-eval
+/harness-review
+/harness-critic
 ```
 
+The harness **remembers the active run and plan** per project — you do not pass `plan-packet.json` paths or run ids between steps. The live widget shows phase/policy; after each step the agent (and UI notify) suggests the next command.
+
+Recovery: `--run` and `--plan` remain for scripts; `/harness-use-run` and `/harness-run-status` for operators.
+
 ## Defaults you should know
 
+- **System prompt** — [`.pi/extensions/00-ultimate-pi-system-prompt.ts`](.pi/extensions/00-ultimate-pi-system-prompt.ts) sets the base prompt from packaged [`.pi/SYSTEM.md`](.pi/SYSTEM.md), or from your workspace override **`.pi/system.md`** (lowercase) if you create one. Nothing is copied into your project by default. After upgrading the package or editing either file, run **`/reload`**.
 - **Model routing (vendored + gated)** — [`pi-model-router`](https://github.com/yeliu84/pi-model-router) ships inside this package (`vendor/pi-model-router/`). [`.pi/extensions/pi-model-router-harness.ts`](.pi/extensions/pi-model-router-harness.ts) activates it **only after** `.pi/model-router.json` exists (generation: `/harness-setup` Step 3.5), so **`router/auto` does not appear** beforehand. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). [`.pi/scripts/harness-sync-model-router.mjs`](.pi/scripts/harness-sync-model-router.mjs) may set **`defaultProvider`/`defaultModel`** to **`router`/`auto`** when the project sets no default — run **`/reload`** afterward. Do **not** add `npm:@yeliu84/pi-model-router` to `.pi/settings.json`; it duplicates the fork. Maintainer refresh: **`npm run vendor:sync-router`**.
+- **Active run + plan context** — PlanPacket lives at a fixed path per run; the extension injects it for `/harness-plan` (revise) and `/harness-run` (execute). Session state plus `.pi/harness/active-run.json`; no run ids or plan paths to copy.
+- **Review isolation** — run evaluate/review/critic in a **new session** after execute (see troubleshooting).
+- **Concurrent plans** — a second `/harness-plan` while a run is active is blocked until `/harness-abort` or `/harness-new-run` (except drift replan / amend after `needs_clarification`).
 - **Plan before mutate** — write/edit/shell that changes the repo is blocked until execute phase.
 - **No auto-merge** — you decide when to open or merge a PR.
 - **Structured runs** — each run writes artifacts under `.pi/harness/runs/` for replay and audit.
@@ -78,7 +91,11 @@ Optional: copy [`.env.example`](.env.example) to `.env` if you use PostHog or ot
 | Problem | Try |
 |---------|-----|
 | Setup fails | `node --version` (need 18+), rerun `/harness-setup` |
+| "No active run" on eval | Finish plan+run first, or `/harness-run-status`; open a new session for eval |
+| Forgot where you left off | `/harness-run-status` |
+| Second plan rejected | `/harness-abort` or `/harness-new-run` |
 | Blocked in evaluate/review | Run review in a fresh session (isolation from execute) |
+| High plan drift | `harness-drift-replan` or abort then replan (ADR 0007) |
 | Budget / scope stop | `/harness-budget-status`, narrow the task or split the plan |
 | Test integrity warning | `/harness-test-integrity-last`, fix or justify test changes |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.6.1",
+	"version": "0.7.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -73,7 +73,7 @@
 		"@mariozechner/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/00-ultimate-pi-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
 		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
 		"vendor:sync-vcc": "bash .pi/scripts/vendor-sync-pi-vcc.sh",
 		"release": "bash .pi/scripts/release.sh",