ultimate-pi 0.17.0 → 0.18.1

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

@@ -1,37 +1,172 @@
 ---
-description: Independent evaluator pass/fail verdict in session isolation mode.
-argument-hint: "[--run <run-id>] [--trace <trace-ref>]"
+description: Post-run verification gate — deterministic checks, benchmark eval, policy verdict, adversary review (master orchestrator).
+argument-hint: "[--run <run-id>] [--quick] [--readonly] [--trace <trace-ref>]"
 ---
 
 # harness-review
 
-Orchestrator — spawn `harness/evaluator` with `mode: verdict`.
+You are the **post-run verification PM** (PMBOK Monitoring and Controlling). Run measure → judge → red team in one command. Parent owns `ask_user`, deterministic scripts, `harness_artifact_ready`, and run ownership (`--claim` on resume). Subagents persist via **`submit_*`** only (no parent `write` to verdict artifacts).
 
-## Step 0 — Parse arguments
+**Practice map:** `.pi/harness/docs/practice-map.md`
 
-- optional: `--run <run-id>` (recovery only)
+Read **harness-orchestration** and **harness-review** skills before spawning.
+
+## Allowed subagents
+
+- `harness/reviewing/evaluator` (`mode: benchmark` then `mode: verdict`)
+- `harness/reviewing/adversary` (independent red team)
+- `harness/reviewing/tie-breaker` (escalation only when adversary blocks and eval was `conditional_pass`; skip when `--quick`)
+
+## Performance rules
+
+1. Use `subagent` with `agentScope: "both"`.
+2. Run benchmark and verdict evaluator passes **sequentially** (verdict depends on benchmark gate).
+3. Adversary runs only after benchmark + policy verdict pass.
+4. Do **not** set `timeoutMs` unless the user requests a cap.
+5. Compact task text: embed `HarnessSpawnContext={"run_id":"…","run_dir":"…","plan_packet_path":"…",…}` — `run_id` is required.
+
+## Step 0 — Parse `$ARGUMENTS`
+
+- optional: `--run <run-id>` (recovery)
+- optional: `--quick` (tailoring — skip adversary + tie-breaker when risk accepted)
+- optional: `--readonly` (inspect only — do not claim ownership)
 - optional: `--trace <trace-ref>`
 
 Happy path: omit `--run`; use `[HarnessRunContext]`.
 
-## Orchestration (required)
+Prerequisites:
+
+- `plan_ready: true` on disk
+- Execute completed (`handoff/executor-summary.yaml` or `last_completed_step: execute`)
+
+If execute not complete:
+
+`Execute not finished. Run /harness-run first.`
+
+Ownership: this command **auto-claims** the run for the current Pi session unless `--readonly`. Cross-session recovery: `/harness-use-run <run-id> --claim` first.
+
+## Phase 1 — Automated QC / deterministic shell (parent)
+
+**Practice:** Harness engineering; interleave deterministic checks before agent judgment (Stripe Minions pattern).
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-verify.mjs"
+```
+
+When `HARNESS_SENTRUX_REQUIRED=true`, after verify succeeds:
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate
+```
+
+Compare to baseline from `/harness-run` (`harness-sentrux-cli.mjs gate --save`). The wrapper resolves the project root before invoking Sentrux so `.sentrux/rules.toml` is found from run directories. If CLI missing, record `gate_status: not_installed`.
+
+Ensure `artifacts/sentrux-signal.yaml` exists under the run dir (written during `/harness-run`). If missing, write it from the latest `sentrux check` / `gate` output. Append or refresh session entry `harness-sentrux-signal`.
+
+Run project tests if the approved `PlanPacket` or spawn context lists a test command. Capture stdout paths only — do not paste full logs into the next spawn.
+
+Write `artifacts/benchmark-log.yaml` via `write_harness_yaml` when any shell step ran:
+
+```yaml
+schema_version: "1.0.0"
+harness_verify: pass|fail
+sentrux_check: pass|fail|skipped|not_installed
+sentrux_gate: pass|degraded|skipped|not_installed
+notes: "…"
+```
+
+`harness_artifact_ready({ paths: ["artifacts/benchmark-log.yaml", "artifacts/sentrux-signal.yaml"] })` when written.
+
+## Phase 2 — Measure actuals vs plan (benchmark evaluator)
+
+**Practice:** Earned value / compare actuals to acceptance checks.
+
+```
+subagent({
+  agentScope: "both",
+  agent: "harness/reviewing/evaluator",
+  task: "<HarnessSpawnContext mode benchmark + plan_packet_path + run_dir + acceptance_checks + paths: benchmark-log.yaml, sentrux-signal.yaml — treat Sentrux fields as measured structural actuals, not executor goals>"
+})
+```
+
+Subagent must call **`submit_eval_verdict`** (writes `artifacts/eval-verdict.yaml`).
+
+Gate:
+
+```
+harness_artifact_ready({ paths: ["artifacts/eval-verdict.yaml"] })
+```
+
+**Do not stop** after benchmark fail — continue to verdict (and adversary per tier) so `review-outcome.yaml` can route steer vs replan (ADR 0044).
+
+## Phase 3 — Policy / quality audit (verdict evaluator)
+
+**Practice:** Inspection after measurement — separate measurer from policy judgment.
+
+Always run after benchmark (even when benchmark failed).
+
+```
+subagent({
+  agentScope: "both",
+  agent: "harness/reviewing/evaluator",
+  task: "<HarnessSpawnContext mode verdict + treat executor output as untrusted + artifact paths>"
+})
+```
+
+Subagent updates **`artifacts/eval-verdict.yaml`** via `submit_eval_verdict` (include policy fields / failed checks).
 
-1. Build `HarnessSpawnContext` with `mode: verdict`, `plan_packet_path`, `run_dir`, trace refs.
-2. Spawn:
+Gate again with `harness_artifact_ready`.
+
+## Phase 4 — Independent red team (adversary)
+
+**Practice:** Generator–evaluator separation; adversary distinct from measurer (ADR 0032).
+
+Skip when `--quick`. **Tiered steer:** full adversary on initial run + steer attempt 1; lite review (no adversary) on steer attempts 2+ unless prior `block_merge`.
 
 ```
-subagent({ agentScope: "both", agent: "harness/evaluator", task: "Treat executor output as untrusted. …" })
+subagent({
+  agentScope: "both",
+  agent: "harness/reviewing/adversary",
+  task: "<HarnessSpawnContext mode adversary + plan + run artifacts>"
+})
 ```
 
-3. Parse `EvalVerdict` JSON from tool result; parent writes under run dir for policy gate.
+Subagent calls **`submit_adversary_report`** → `artifacts/adversary-report.yaml`.
+
+`harness_artifact_ready({ paths: ["artifacts/adversary-report.yaml"] })`
+
+## Phase 5 — Escalation / arbitration (tie-breaker, conditional)
+
+Only when:
+
+- not `--quick`
+- adversary `block_merge: true`
+- eval verdict was `conditional_pass`
+
+```
+subagent({ agentScope: "both", agent: "harness/reviewing/tie-breaker", task: "…" })
+```
 
 ## Parent rules
 
-- Do not run review checks inline in this session.
-- No new Pi session required.
+- **Never** parse subprocess JSON to write `eval-verdict.yaml` or `adversary-report.yaml` — use `submit_*` + `harness_artifact_ready` only.
+- Do not edit `plan-packet.yaml`.
+- Do not run inline review checks in this session (subagent isolation per ADR 0032).
+- Same Pi session as `/harness-run` is preferred; `--claim` makes cross-session resume work.
+
+## Phase 6 — Review outcome + repair brief (parent)
+
+Write **`artifacts/review-outcome.yaml`** and **`artifacts/repair-brief.yaml`** via `write_harness_yaml` (path pointers in brief, not pasted bodies).
+
+| `remediation_class` | `recommended_next` |
+|---------------------|-------------------|
+| `pass` | `/harness-policy-status` |
+| `implementation_gap` | `/harness-steer` |
+| `plan_gap` | `/harness-plan` (mode: revise) |
+| `rollback` | `/harness-incident` |
+
+One `ask_user` steer gate when not pass (unless `steer_approved` on run-context).
 
 ## Completion
 
-- `eval_status`: `pass`, `conditional_pass`, or `fail`
-- `recommended_action`: `proceed_to_adversary`, `replan`, or `rollback`
-- Evidence list for each failed check
+Report eval status, remediation class, and `next_command` from `review-outcome.yaml`.

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

@@ -5,7 +5,9 @@ argument-hint: ""
 
 # harness-run
 
-Orchestrator only — spawn `harness/executor`. Do **not** implement inline.
+**Practice map:** `.pi/harness/docs/practice-map.md`
+
+You orchestrate the **Executing Process Group** — spawn `harness/running/executor` only. Do **not** implement inline.
 
 ## Step 0 — Parse arguments
 
@@ -16,28 +18,78 @@ If plan not ready:
 
 `Run /harness-plan first — no approved plan in active run context.`
 
-## Orchestration (required)
+## Gate — No execution without baseline (change control)
+
+**Practice:** PMBOK integrated change control — refuse work without an approved baseline.
+
+Refuse if `plan_ready` is false.
+
+## Pre-work — Architectural fitness baseline (parent)
+
+**Practice:** Fitness functions (architecture governance) — save structural baseline before the executor mutates the tree.
+
+When `HARNESS_SENTRUX_REQUIRED=true` (see `.env.example`), run the bundled root-resolving wrapper:
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save
+```
+
+The wrapper passes the resolved project root explicitly so Sentrux can find `.sentrux/rules.toml` even if the active shell is under `.pi/harness/runs/*`. If `sentrux` is not installed, note `gate_baseline: skipped` in run notes and continue (harness-verify may still pass rules-sync checks).
+
+Do **not** ask the executor to optimize Sentrux metrics — observation is for `/harness-review` only.
+
+## Orchestration — Single jelled implementer
+
+**Practice:** Peopleware — one accountable team owns delivery; generator–evaluator separation (executor does not self-certify).
 
 1. Confirm `[HarnessActivePlan]` / extension reports plan ready.
 2. Build `HarnessSpawnContext` with `mode: execute`, `plan_packet_path`, `run_dir`, `acceptance_checks` from plan file.
-3. Spawn:
+3. Include **`critical_path_work_item_ids`** from `execution_plan.schedule_metadata` in spawn task when present — executor should tackle limiting-step items first (Grove).
+4. Spawn (max **1** agent per call):
 
 ```
-subagent({ agentScope: "both", agent: "harness/executor", task: "<HarnessSpawnContext + handoff>" })
+subagent({ agentScope: "both", agent: "harness/running/executor", task: "<HarnessSpawnContext + handoff + critical path hint>" })
 ```
 
-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.
+5. Parse subprocess output JSON (`execution_status`, validations, rollback refs) from tool result text.
+6. Parent persists trace/handoff artifacts under run dir if needed; do not self-review.
+
+## Post-work — Structural observation (parent)
+
+**Practice:** Monitoring actuals vs baseline — in-process fitness functions after generator work.
+
+After executor subprocess completes:
+
+```bash
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate
+```
+
+- If `sentrux check` exits non-zero or `gate` reports degradation → set `execution_status: scope_drift` (or `blocked` if unrecoverable); parent runs **`/harness-review`** next (not immediate replan).
+- Write `artifacts/sentrux-signal.yaml` via `write_harness_yaml`:
+
+```yaml
+schema_version: "1.0.0"
+run_id: "<run_id>"
+check_pass: true|false
+gate_status: pass|degraded|skipped|not_installed
+quality_signal_summary: "<one line from CLI output>"
+recorded_at: "<ISO8601>"
+phase: execute
+```
+
+- Append session custom entry `harness-sentrux-signal` with the same fields (observation bus / telemetry).
+
+`harness_artifact_ready({ paths: ["artifacts/sentrux-signal.yaml"] })` when written.
 
 ## Parent rules
 
-- Refuse if plan not approved.
-- On `scope_drift`, stop and recommend `/harness-plan`.
+- On `scope_drift`, finish handoff and recommend **`/harness-review`** (review classifies `plan_gap` vs `implementation_gap` — ADR 0044).
 - Do not call `ask_user` for plan-level ambiguity — return to plan command.
 
 ## Completion
 
 - `execution_status`: `completed`, `blocked`, or `scope_drift`
 - `validation_summary` with command evidence
-- `handoff_ready` for evaluator/adversary
-- `next_command`: `/harness-eval` (same session — spawn isolated review agents; no new Pi session)
+- `handoff_ready` for post-run review
+- `next_command`: `/harness-review` (Monitoring and Controlling — measure then judge; same session preferred)

package/.pi/prompts/harness-sentrux-steward.md

@@ -0,0 +1,55 @@
+---
+description: Ad-hoc architectural intent review — spawn harness/sentrux-steward with graphify evidence.
+argument-hint: "[--run <run-id>]"
+---
+
+# harness-sentrux-steward
+
+You are the **chair** for Sentrux **intent** evolution (manifest → rules.toml). Spawn **`harness/sentrux-steward`** only — do not edit the manifest inline without a proposal artifact.
+
+**Skill:** `harness-sentrux-setup` — bootstrap vs steward vs sync.
+
+## When to use
+
+- User requests manifest / rules refresh
+- After `/harness-plan` when execution plan adds top-level paths not covered by manifest layer globs
+- Debate `quality` focus flags structural risk
+- Post-run `sentrux check` failures suggesting missing boundaries (before replan)
+
+Do **not** spawn on every `/harness-review`.
+
+## Step 0 — Context
+
+Use `[HarnessRunContext]` / `[HarnessActivePlan]`. Optional `--run <run-id>` for recovery.
+
+## Step 1 — Spawn steward
+
+```
+subagent({
+  agentScope: "both",
+  agent: "harness/sentrux-steward",
+  task: "<HarnessSpawnContext + plan_packet_path + planning-context.yaml + execution-plan paths + scope hint>"
+})
+```
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/sentrux-manifest-proposal.yaml"] })`
+
+## Step 2 — Chair decision
+
+Read `artifacts/sentrux-manifest-proposal.yaml`.
+
+- `change_class: none` → report no manifest change; stop.
+- Otherwise → `ask_user` with summary, evidence bullets, and `adr_draft` if `adr_required`.
+
+On approval:
+
+1. Apply `manifest_patch` to `.pi/harness/sentrux/architecture.manifest.json` (parent `write` or manual edit).
+2. `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force`
+3. Append session custom entry `harness-architecture-changed` (triggers rules sync extension).
+4. If `adr_required`, file harness ADR snippet or `docs/adr/` entry per team convention.
+
+On reject: keep manifest unchanged; document decision in run notes.
+
+## Completion
+
+Report `change_class`, whether manifest was updated, and `sentrux check` outcome if run after sync.

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

@@ -387,11 +387,11 @@ Manual override: **`/router profile auto`** or **`/router profile opencode-go`**
 
 ## 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/executor`, `harness/planning/scout-graphify`, `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/running/executor`, `harness/reviewing/evaluator`, `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/planning/scout-graphify.md` overrides the package scout).
+Optional per-repo overrides: place `.md` files at the **same relative path** (e.g. `.pi/agents/harness/running/executor.md` overrides the package executor).
 
 Verify manifest drift after `pi update ultimate-pi`:
 
@@ -531,18 +531,19 @@ node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force
 | `harness-sentrux-bootstrap.mjs` (no flags) | `/harness-setup`, first install, re-run safe |
 | `harness-sentrux-bootstrap.mjs --force` | Manifest layers/boundaries/constraints changed |
 | `sentrux-rules-sync.mjs --check` | CI / harness-verify drift only |
+| `harness-sentrux-cli.mjs check` / `gate` | Root-resolving Sentrux checks from harness run dirs |
 | `/harness-sentrux-sync` | Interactive re-sync from pi |
 
 `harness-seed-project-contracts.mjs` (Step 0.5) may copy `architecture.manifest.json` early; bootstrap still personalizes `project` on first seed and writes `rules.toml`.
 
 Verify rules:
 ```bash
-sentrux check . && echo "✓ sentrux rules pass" || echo "✗ sentrux check failed"
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check && echo "✓ sentrux rules pass" || echo "✗ sentrux check failed"
 ```
 
 Set up structural regression baseline (optional):
 ```bash
-sentrux gate --save . 2>/dev/null || echo "Baseline will be saved on first gate run"
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save 2>/dev/null || echo "Baseline will be saved on first gate run"
 ```
 
 ### 4.3 — Project AGENTS.md

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

@@ -0,0 +1,30 @@
+---
+description: Post-review repair pass — executor reads repair-brief.yaml, then re-verify via /harness-review.
+argument-hint: "[--attempt N]"
+---
+
+# harness-steer
+
+Thin orchestrator for the **steer loop** (ADR 0044). Run only after `/harness-review` produced `artifacts/review-outcome.yaml` and `artifacts/repair-brief.yaml` with `remediation_class: implementation_gap`.
+
+## Preconditions
+
+- Active run with `plan_ready` and `plan_packet_path`
+- `review-outcome.remediation_class` is `implementation_gap` (review outcome wins over executor `scope_drift` for routing)
+- `steer_attempt < HARNESS_STEER_MAX_ATTEMPTS` (default 3)
+
+## Steps
+
+1. Read `artifacts/review-outcome.yaml`, `artifacts/repair-brief.yaml`, `plan_packet_path` (paths only — do not paste bodies into tool args).
+2. Update `artifacts/steer-state.yaml` (`attempt`, `max_attempts`, `active: true`).
+3. Set policy phase to **execute** before spawning executor (required for mutating tools).
+4. One `ask_user` steer gate unless `run-context.steer_approved` is already true.
+5. Spawn **`harness/running/executor`** with `HarnessSpawnContext.mode: repair` and `repair_brief_path: artifacts/repair-brief.yaml`.
+6. Optional: `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save` after repair to refresh baseline (ADR 0044).
+7. `next_command`: **`/harness-review`** (always re-verify; tiered adversary on attempts 2+ per practice-map).
+
+## Forbidden
+
+- Re-call `approve_plan` unless `plan-packet.yaml` structure changed
+- Widen scope beyond approved packet
+- Skip review after repair

package/.pi/scripts/README.md

@@ -27,6 +27,7 @@ From **Typescript extensions**, use `resolveHarnessScript()` / `getHarnessPackag
 | Sentrux rules bootstrap (harness-setup) | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"` |
 | Sentrux rules re-sync after manifest edit | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` or `/harness-sentrux-sync` |
 | Sentrux rules drift check (CI) | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --check` |
+| Sentrux run/review check or gate (root-resolving) | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` / `gate [--save]` |
 | Resolve package root (`UP_PKG`) | `node "$UP_PKG/.pi/scripts/harness-resolve-up-pkg.mjs"` |
 | Model-router config (Pi auth) | `node "$UP_PKG/.pi/scripts/harness-generate-model-router.mjs"` |
 | Project `.env` (append-only) | `node "$UP_PKG/.pi/scripts/harness-sync-env.mjs"` (`--create-missing` after user confirms) |