ultimate-pi 0.18.0 → 0.19.0

package/.pi/skills/quality/test-strategy/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: test-strategy
+description: Choose the right test level for a code change. Use when adding features, fixing bugs, refactoring, changing contracts, or improving coverage. Guides unit, integration, contract, characterization, regression, property, and end-to-end test selection without assuming a specific tool or runtime.
+---
+
+# Test Strategy
+
+Use this skill to add useful tests rather than merely more tests.
+
+## Choose test type by risk
+
+- Unit test: pure logic, calculations, policies, branching, invariants.
+- Integration test: storage, filesystem, network, process, or platform/runtime boundary.
+- Contract test: public API, command, event, plugin, module facade, or service boundary.
+- Characterization test: existing unclear behavior before legacy changes.
+- Regression test: bug fix that must not reappear.
+- End-to-end test: critical user journey or cross-boundary behavior not covered otherwise.
+- Property or generative test: broad input space with stable invariants.
+
+## Workflow
+
+1. Identify the behavior that must be proven.
+2. Pick the lowest test level that gives confidence.
+3. Test public behavior and invariants, not incidental implementation details.
+4. Include edge cases: empty, missing, invalid, boundary, duplicate, reordered, and failure paths where relevant.
+5. Ensure tests fail for the bug/change before relying on them.
+6. Keep tests deterministic and readable.
+
+## Avoid
+
+- Snapshot/golden tests that hide important intent.
+- Mock-heavy tests that only verify implementation choreography.
+- Broad end-to-end tests for simple pure logic.

package/.pi/skills/quality/testability-design/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: testability-design
+description: Reshape code so important behavior can be tested simply. Use when code is hard to test due to IO, time, randomness, globals, hidden dependencies, side effects, or platform/runtime coupling. Separates pure logic from effects and introduces stable seams.
+---
+
+# Testability Design
+
+Use this skill when verification is difficult because the design hides seams.
+
+## Workflow
+
+1. Identify behavior worth testing separately from the mechanism that triggers it.
+2. Move pure decisions/calculations away from IO and mutation where practical.
+3. Inject or pass volatile dependencies such as clocks, randomness, environment, storage, network, and external processes.
+4. Replace ambient/global state with explicit inputs or narrow adapters where safe.
+5. Expose behavior through a stable public seam rather than private internals.
+6. Keep tests close to the level of the behavior being guaranteed.
+
+## Good seams
+
+- boundary adapters
+- domain services or policies
+- command/query handlers
+- parser/serializer boundaries
+- workflow step interfaces
+- configuration providers
+- repository/storage ports
+
+## Avoid
+
+- Making private implementation public only for tests.
+- Adding test-only branches to production logic.
+- Over-abstracting every dependency before a real testability problem exists.

package/.pi/skills/systems/concurrency-safety/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: concurrency-safety
+description: Prevent race conditions and unsafe shared-state behavior. Use when modifying async work, parallel execution, queues, locks, caches, background jobs, shared mutable state, transactions, event handlers, or distributed coordination. Emphasizes idempotency, ordering, isolation, and deterministic tests.
+---
+
+# Concurrency Safety
+
+Use this skill when operations may overlap, reorder, duplicate, or observe stale state.
+
+## Workflow
+
+1. Identify shared mutable state and who can access it concurrently.
+2. Identify ordering assumptions and whether they are guaranteed.
+3. Check for duplicate, delayed, retried, or out-of-order execution.
+4. Use appropriate isolation: immutability, ownership, lock, transaction, compare-and-set, queue serialization, or idempotency key.
+5. Keep critical sections small and failure-safe.
+6. Ensure cleanup/release happens on error paths.
+7. Add tests or simulations for duplicate and interleaved operations where practical.
+
+## Review questions
+
+- Can two callers perform this action at once?
+- Can this message/job/event be processed twice?
+- Can a stale read overwrite newer state?
+- Is the operation atomic from the user's perspective?
+- Is there a deadlock, starvation, or resource leak risk?
+
+## Avoid
+
+- Assuming single-thread/process execution unless enforced.
+- Using time sleeps as correctness guarantees.
+- Global mutable state without ownership rules.

package/.pi/skills/systems/data-modeling-migrations/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: data-modeling-migrations
+description: Safely evolve stored data and schemas. Use when adding or changing database fields, indexes, files, serialized formats, caches, event payloads, search indexes, or migration scripts. Focuses on compatibility, rollout phases, rollback, existing data, and query behavior.
+---
+
+# Data Modeling and Migrations
+
+Use this skill when code changes persisted or exchanged data.
+
+## Workflow
+
+1. Identify every reader and writer of the data.
+2. Separate schema/format change, data backfill, and code behavior change when risk warrants.
+3. Prefer backward-compatible additions before breaking removals or renames.
+4. Plan behavior while old and new versions coexist.
+5. Validate existing production-like data assumptions.
+6. Add indexes or access paths based on actual query patterns.
+7. Define rollback or recovery for failed migrations.
+8. Add tests for old data, new data, missing fields, and mixed-version compatibility.
+
+## Safety checks
+
+- Is the migration destructive or irreversible?
+- Does it lock or block critical paths?
+- Are defaults correct for existing records?
+- Can old code read new data and new code read old data during rollout?
+- Are caches/search/projections updated or rebuildable?
+
+## Ask before
+
+Destructive deletion, irreversible transformation, broad backfill, or compatibility-breaking format changes.

package/.pi/skills/systems/observability-instrumentation/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: observability-instrumentation
+description: Add useful logs, metrics, traces, events, and diagnostics without noise or data leaks. Use when changing failure paths, background jobs, workflows, integrations, performance-sensitive paths, or production-debuggable behavior. Focuses on actionable signals and safe context.
+---
+
+# Observability Instrumentation
+
+Use this skill to make behavior diagnosable in real environments.
+
+## Signal types
+
+- Logs: discrete decisions, failures, lifecycle transitions, and unusual states.
+- Metrics: counts, durations, rates, queue depth, success/failure, saturation.
+- Traces/spans: cross-boundary request or workflow paths.
+- Audit/events: business-relevant actions that need history.
+- Health checks: readiness, liveness, dependency status.
+
+## Workflow
+
+1. Identify what a maintainer/operator must know when this fails.
+2. Add signals at boundaries and important state transitions.
+3. Include correlation identifiers or stable context when available.
+4. Redact secrets and personal/sensitive data.
+5. Keep labels/cardinality bounded.
+6. Avoid logging tight loops or expected noisy paths at high severity.
+7. Test or inspect that instrumentation executes on success and failure paths.
+
+## Review questions
+
+- Can someone diagnose the failure without reproducing locally?
+- Are logs actionable rather than decorative?
+- Will this create noise, cost, or privacy risk?

package/.pi/skills/systems/performance-measurement/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: performance-measurement
+description: Improve performance with evidence instead of premature optimization. Use when optimizing latency, throughput, memory, startup, storage, queries, algorithms, rendering, build time, or hot paths. Guides baseline measurement, bottleneck isolation, complexity analysis, and regression guards.
+---
+
+# Performance Measurement
+
+Use this skill before and during performance work.
+
+## Workflow
+
+1. Define the performance goal and user/system impact.
+2. Measure a baseline with representative input or workload.
+3. Identify the bottleneck before changing code.
+4. Estimate algorithmic complexity and data-size effects.
+5. Make the smallest optimization that targets the measured bottleneck.
+6. Re-measure and compare against the baseline.
+7. Add a benchmark, regression test, or monitoring signal when future regressions matter.
+8. Preserve readability unless performance evidence justifies complexity.
+
+## Common bottleneck classes
+
+- repeated expensive work
+- inefficient data access pattern
+- unnecessary serialization/parsing
+- blocking IO in hot path
+- unbounded memory growth
+- poor batching/caching strategy
+- algorithmic complexity mismatch
+
+## Avoid
+
+- Optimizing cold paths.
+- Adding caches without invalidation rules.
+- Trading correctness or maintainability for unmeasured speed.

package/.pi/skills/systems/reliability-design/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: reliability-design
+description: Design code for predictable behavior under faults. Use when touching IO, storage, queues, events, workflows, services, retries, timeouts, background jobs, distributed state, or operator-facing failures. Applies reliability, fault tolerance, partial failure, degradation, and recovery thinking.
+---
+
+# Reliability Design
+
+Use this skill when code must keep working, fail safely, or recover under imperfect conditions.
+
+## Workflow
+
+1. Identify failure modes: dependency down, timeout, duplicate work, partial write, stale read, invalid state, resource exhaustion, human/operator error.
+2. Decide desired behavior for each important failure: reject, retry, compensate, degrade, queue, alert, or fail fast.
+3. Add timeouts and cancellation where waits can hang.
+4. Add retries only when operations are safe or idempotent.
+5. Preserve enough state/context for recovery.
+6. Add observability for failures and recovery paths.
+7. Test representative failure modes.
+
+## Design checks
+
+- Is there a single source of truth for critical state?
+- Can the operation run twice safely?
+- What happens if the process stops halfway?
+- What does the caller see during partial failure?
+- How will an operator or developer diagnose this?
+
+## Avoid
+
+- Infinite retries.
+- Hidden partial success.
+- Treating network/storage/process calls as always reliable.

package/.sentrux/rules.toml

@@ -23,9 +23,9 @@ order = 0
 
 [[layers]]
 name = "contracts"
-paths = [".pi/harness/specs/*", ".pi/harness/docs/*"]
+paths = [".pi/harness/specs/*", ".pi/harness/docs/*", ".pi/harness/policies/*", ".pi/harness/agents.policy.yaml", ".pi/harness/examples/*"]
 order = 1
-# Harness schemas, ADRs, and governance docs
+# Harness schemas, ADRs, AGT policies, and agents.policy SSOT
 
 [[layers]]
 name = "runtime"
@@ -41,9 +41,15 @@ order = 3
 
 [[layers]]
 name = "tooling"
-paths = [".pi/scripts/*", "test/*"]
+paths = [".pi/scripts/*"]
 order = 4
-# Harness CLI scripts and tests
+# Harness CLI scripts
+
+[[layers]]
+name = "foundation"
+paths = [".pi/lib/*"]
+order = 5
+# Shared harness/AGT libraries (imported by extensions and scripts)
 
 [[boundaries]]
 from = ".agents/skills/*"
@@ -65,6 +71,16 @@ from = ".pi/harness/specs/*"
 to = ".pi/extensions/*"
 reason = "Contracts are data-only JSON schemas; extensions implement behavior"
 
+[[boundaries]]
+from = ".pi/lib/*"
+to = ".pi/extensions/*"
+reason = "Foundation lib must not import extension modules"
+
+[[boundaries]]
+from = ".pi/harness/policies/*"
+to = ".pi/extensions/*"
+reason = "Declarative AGT YAML must not depend on extension implementation"
+
 [[boundaries]]
 from = ".pi/scripts/*"
 to = ".agents/skills/*"

package/AGENTS.md

@@ -4,6 +4,11 @@ Purpose: Agentic coding harness — architecture, research, decisions, implement
 Owner: pi-mono + user
 Created: 2026-05-14
 
+## Instruction Boundaries
+
+- `.pi/SYSTEM.md` is the reusable harness-level agent prompt and should remain project-agnostic for external projects.
+- Keep ultimate-pi-specific paths, ownership, local conventions, and repository facts in this `AGENTS.md` file (or nearby project docs), not in `.pi/SYSTEM.md`.
+
 ## Structure
 
 - graphify-out/ → Knowledge graph (run `graphify update .` to build)

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+### ✨ Features
+
+- **Harness lens:** Integrate selected pi-lens capabilities through a harness-owned extension, store lens state under `.pi/harness/.lens`, and route lens findings through harness PostHog telemetry instead of standalone lens health/telemetry surfaces.
+- **Graphify KB updater:** Productize conservative daily discovery/promotion with explicit repo/release taxonomy, allowlist source-class gates, operator review queue reporting, scheduler smoke validation, and safe Graphify refresh controls.
+
+## [v0.19.0] — 2026-05-24
+
+### ✨ Features
+
+- **Harness:** `agents.policy.yaml` as per-agent tool SSOT with manifest alignment; subprocess `subagent-governance` bundle and AGT `tool_allowed` enforcement.
+- **Harness:** Consolidate shared modules under `.pi/lib/` (moved from `.pi/extensions/lib/`); update imports, packaging, verify, and tests.
+- **Harness:** AGT-backed policy gate with subprocess governance bundle (extends v0.18.x AGT work).
+
+### 🔧 Chores
+
+- Apply Biome organize-imports and format fixes across moved harness library files.
+- Commit pending harness architecture and context tooling updates.
+
+## [v0.18.1] — 2026-05-24
+
+### 🔧 Chores
+
+- Ignore local project runtime config.
+- Fix harness review revise flow and widget UX.
+- Add harness project toggle controls.
+
 ## [v0.18.0] — 2026-05-23
 
 ### ✨ Features

package/README.md

@@ -2,102 +2,129 @@
 
 > The **ultimate AI coding harness** on top of [**pi.dev**](https://pi.dev).
 
-`ultimate-pi` is a pi package that adds a governed coding workflow: plan first, then implement, then independent review—so agents cannot silently skip planning or merge unsafe changes.
+`ultimate-pi` adds a governed coding workflow to Pi: bootstrap the repo, plan with evidence, execute only against an approved PlanPacket, then run an independent review gate before merge.
 
 ## Quick start
 
-**Requirements:** Node 18+, npm 9+, git.
+**Requirements:** Node 18+, npm 9+, git, and Pi.
 
-1. **Install** (from your project directory):
+1. Install the package in your project:
 
 ```bash
 pi install npm:ultimate-pi
 /reload
 ```
 
-2. **Bootstrap** (once per project):
+2. Bootstrap the harness once per project:
 
 ```text
 /harness-setup
 ```
 
-3. **Run a task** (full pipeline in one command):
+3. Run the strict end-to-end pipeline:
 
 ```text
 /harness-auto "implement feature X safely"
 ```
 
-That runs: plan → execute → evaluate → adversary → policy decision. It does **not** auto-merge.
+`/harness-auto` runs plan → execute → review → optional steer loop. It may prepare commit/PR work when gates pass, but it never auto-merges.
 
-If something blocks, inspect status (no run id needed):
+## Core workflow
+
+### Recommended: one command
 
 ```text
-/harness-run-status
-/harness-policy-status
-/harness-trace-last
+/harness-auto "your task" [--quick] [--risk low|med|high]
 ```
 
-## Commands
-
-| Command | What it does |
-|---------|----------------|
-| `/harness-setup` | One-time project bootstrap (tools, harness dirs, extensions) |
-| `/harness-auto "<task>"` | End-to-end pipeline (recommended) |
-| `/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`; spawns isolated `harness/evaluator`) |
-| `/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 replan path |
-
-## Manual workflow
-
-Use this when you want each step separate:
+Use this for most feature, fix, and refactor work. The parent orchestrator handles the phase handoffs and keeps active run context in `.pi/harness/active-run.json` plus run artifacts under `.pi/harness/runs/`.
+
+### Manual: phase by phase
 
 ```text
-/harness-plan "your task"
+/harness-plan "your task" [--risk low|med|high] [--quick]
 /harness-run
-/harness-eval
-/harness-review
-/harness-critic
+/harness-review [--quick]
 ```
 
-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.
+Manual mode is useful when you want to inspect or approve each handoff. On the happy path you do **not** pass `--plan` or a run id; the harness restores the active PlanPacket and run context.
 
-Recovery: `--run` and `--plan` remain for scripts; `/harness-use-run` and `/harness-run-status` for operators.
+### Repair loop
 
-## Defaults you should know
+If `/harness-review` returns `implementation_gap`, run:
 
-- **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** — `/harness-eval`, `/harness-review`, and `/harness-critic` spawn isolated subagents (`inherit_context: false`); stay in the same session (see ADR 0032).
-- **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.
+```text
+/harness-steer
+/harness-review
+```
 
-Optional: copy [`.env.example`](.env.example) to `.env` if you use PostHog or other integrations wired by `/harness-setup`.
+`/harness-steer` uses `artifacts/repair-brief.yaml` and respawns the executor in repair mode without widening the approved plan scope.
+
+## Command reference
+
+| Command | Purpose |
+|---|---|
+| `/harness-setup [--skip-graphify] [--skip-tools] [--non-interactive] [--force]` | Idempotent project bootstrap: Graphify, harness-web/Scrapling, CLI tools, settings, contracts, Sentrux, harness lens, and verification. |
+| `/harness-auto "<task>" [--quick] [--risk low\|med\|high]` | Strict full pipeline: plan, execute, review, steer when appropriate. |
+| `/harness-plan "<task>" [--risk low\|med\|high] [--quick]` | PM-grade planning: reconnaissance, decomposition, hypothesis, external research, ExecutionPlan, DAG validation, Review Gate debate, `approve_plan`, `create_plan`. |
+| `/harness-run` | Executes the approved active PlanPacket by spawning `harness/running/executor`; no inline implementation. |
+| `/harness-review [--run <id>] [--quick] [--readonly] [--trace <ref>]` | Post-run verification gate: deterministic checks, benchmark evaluator, policy verdict, adversary, optional tie-breaker. |
+| `/harness-steer [--attempt N]` | Post-review repair pass for `implementation_gap`; executor reads `repair-brief.yaml`, then you re-run `/harness-review`. |
+| `/harness-abort [reason]` | Safely aborts the active run, clears plan readiness, and re-locks mutation until a fresh plan is approved. |
+| `/harness-trace [--run <id>] [--phase plan\|execute\|evaluate\|adversary\|merge]` | Summarizes run traces and artifact handoffs for replay/forensics. |
+| `/harness-incident --trigger <reason> [--run <id>] [--severity low\|med\|high\|critical]` | Records incident, rollback, and override trail for harness failures. |
+| `/harness-sentrux-steward [--run <id>]` | Ad-hoc architectural intent review for Sentrux manifest/rule alignment. |
+| `/graphify [directory]` | Bootstraps or updates the Graphify knowledge graph. |
+| `/wiki-autoresearch [topic]` | Runs autonomous web research and builds a Graphify-backed research wiki. |
+| `/wiki-save` | Saves the current conversation or insight as a structured wiki note. |
+| `/release [patch\|minor\|major] [--dry-run]` | Maintainer release helper. |
+
+## Harness phases and agents
+
+- **Planning** uses agents under `.pi/agents/harness/planning/` plus parent-led Graphify → `sg` → `ccc` reconnaissance. Legacy tool-tied `planning/scout-*` agents have been removed; planning context is captured in `artifacts/planning-context.yaml`.
+- **Running** uses `.pi/agents/harness/running/executor.md` via agent id `harness/running/executor`.
+- **Reviewing** uses `.pi/agents/harness/reviewing/` via `harness/reviewing/evaluator`, `harness/reviewing/adversary`, and `harness/reviewing/tie-breaker`.
+- **Support agents** such as `harness/incident-recorder`, `harness/sentrux-steward`, and `harness/trace-librarian` remain under `.pi/agents/harness/`.
+
+Subagents run isolated from the parent session. They persist canonical YAML through `submit_*` tools; the parent gates with `harness_artifact_ready` and writes only orchestrator-owned merge artifacts.
+
+## Artifacts and layout
+
+| Path | Description |
+|---|---|
+| `.pi/harness/active-run.json` | Active run pointer for happy-path commands. |
+| `.pi/harness/runs/<run_id>/plan-packet.yaml` | Approved execution baseline. |
+| `.pi/harness/runs/<run_id>/research-brief.yaml` | Planning evidence and research merge. |
+| `.pi/harness/runs/<run_id>/artifacts/` | Planning context, decomposition, research, benchmark, verdict, adversary, repair, and Sentrux artifacts. |
+| `.pi/harness/runs/<run_id>/handoff/executor-summary.yaml` | Executor handoff written by `submit_executor_handoff`. |
+| `.pi/harness/incidents/` | Incident records and rollback/override trail. |
+| `.pi/harness/docs/adrs/` | Harness architectural decisions. |
+| `.pi/harness/specs/` | Artifact contracts and schemas seeded into projects. |
+
+## Safety defaults
+
+- **Graph before grep:** planning consults `graphify-out/GRAPH_REPORT.md` and Graphify queries before raw file reads.
+- **Plan before mutate:** mutating tools are blocked until `/harness-plan` approves and creates a plan.
+- **No inline execution:** `/harness-run` delegates to `harness/running/executor` only.
+- **No inline review:** `/harness-review` delegates verdicts to isolated reviewing agents.
+- **No auto-merge:** final merge remains a human/operator decision.
+- **Sentrux is the architecture signal:** structural baselines and gates inform review; executor does not optimize metrics as a goal.
+- **pi-lens is edit-time diagnostics:** LSP/lint/format/ast feedback complements Sentrux and does not replace architecture gating.
 
 ## Troubleshooting
 
 | Problem | Try |
-|---------|-----|
-| Setup fails | `node --version` (need 18+), rerun `/harness-setup` |
-| "No active run" on eval | Finish plan+run first, or `/harness-run-status` |
-| Forgot where you left off | `/harness-run-status` |
-| Second plan rejected | `/harness-abort` or `/harness-new-run` |
-| Blocked in evaluate/review | Spawn review via Agent (`harness/evaluator` / `harness/adversary`); do not run review tools inline in execute phase |
-| 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 |
+|---|---|
+| Setup fails | Confirm `node --version` is 18+, `npm --version` is 9+, then rerun `/harness-setup`. |
+| No approved plan | Run `/harness-plan "<task>"`, then `/harness-run`. |
+| Need to inspect handoff | Run `/harness-trace` or inspect `.pi/harness/runs/<run_id>/`. |
+| Need to restart safely | Run `/harness-abort [reason]`, then create a fresh plan. |
+| Review says `implementation_gap` | Run `/harness-steer`, then `/harness-review`. |
+| Review says `plan_gap` | Revise with `/harness-plan "<updated task>"`. |
+| Sentrux missing | Install/configure Sentrux or keep it skipped; harness verification still reports the status. |
+
+Optional integrations can be configured by copying `.env.example` to `.env`; `/harness-setup` appends missing keys without overwriting existing values.
 
 ## Contributing
 
-Local development, harness internals, and quality gates: [CONTRIBUTING.md](./CONTRIBUTING.md) and [`.pi/harness/README.md`](.pi/harness/README.md).
+Local development, harness internals, and quality gates: [CONTRIBUTING.md](./CONTRIBUTING.md), [`.pi/scripts/README.md`](.pi/scripts/README.md), and [`.pi/harness/docs/adrs/`](.pi/harness/docs/adrs/).

package/THIRD_PARTY_NOTICES.md

@@ -1,31 +1,22 @@
-# Third-party notices
-
-## pi-model-router (vendored)
-
-- **Project:** https://github.com/yeliu84/pi-model-router  
-- **License:** MIT ([vendor/pi-model-router/LICENSE](vendor/pi-model-router/LICENSE))  
-- **Pinned revision:** See [vendor/pi-model-router/UPSTREAM_PIN.md](vendor/pi-model-router/UPSTREAM_PIN.md)  
-- ultimate-pi loads it from [`vendor/pi-model-router`](vendor/pi-model-router); import specifiers were adapted for `@earendil-works/pi-coding-agent` and related Pi packages.
-
 ## pi-vcc (vendored)
 
-- **Project:** https://github.com/sting8k/pi-vcc  
-- **Conceptual basis:** https://github.com/lllyasviel/VCC (View-oriented Conversation Compiler)  
-- **License:** MIT (see upstream repository)  
-- **Pinned revision:** See [vendor/pi-vcc/UPSTREAM_PIN.md](vendor/pi-vcc/UPSTREAM_PIN.md)  
-- ultimate-pi loads it from [`vendor/pi-vcc`](vendor/pi-vcc) via [`.pi/extensions/ultimate-pi-vcc.ts`](.pi/extensions/ultimate-pi-vcc.ts). Harness configuration is env-only: `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG` ([`.pi/extensions/lib/harness-vcc-settings.ts`](.pi/extensions/lib/harness-vcc-settings.ts)). Maintainer refresh: `npm run vendor:sync-vcc`.
+- **Project:** https://github.com/sting8k/pi-vcc
+- **Conceptual basis:** https://github.com/lllyasviel/VCC (View-oriented Conversation Compiler)
+- **License:** MIT (see upstream repository)
+- **Pinned revision:** See [vendor/pi-vcc/UPSTREAM_PIN.md](vendor/pi-vcc/UPSTREAM_PIN.md)
+- ultimate-pi loads it from [`vendor/pi-vcc`](vendor/pi-vcc) via [`.pi/extensions/ultimate-pi-vcc.ts`](.pi/extensions/ultimate-pi-vcc.ts). Harness configuration is env-only: `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG` ([`.pi/lib/harness-vcc-settings.ts`](.pi/lib/harness-vcc-settings.ts)). Maintainer refresh: `npm run vendor:sync-vcc`.
 
 ## pi-subagents (vendored)
 
-- **Project:** https://github.com/narumiruna/pi-extensions (`extensions/pi-subagents`)  
-- **npm:** `@narumitw/pi-subagents@0.1.26`  
-- **License:** MIT ([vendor/pi-subagents/LICENSE](vendor/pi-subagents/LICENSE))  
-- **Pinned revision:** See [vendor/pi-subagents/UPSTREAM_PIN.md](vendor/pi-subagents/UPSTREAM_PIN.md)  
+- **Project:** https://github.com/narumiruna/pi-extensions (`extensions/pi-subagents`)
+- **npm:** `@narumitw/pi-subagents@0.1.26`
+- **License:** MIT ([vendor/pi-subagents/LICENSE](vendor/pi-subagents/LICENSE))
+- **Pinned revision:** See [vendor/pi-subagents/UPSTREAM_PIN.md](vendor/pi-subagents/UPSTREAM_PIN.md)
 - ultimate-pi loads it from [`vendor/pi-subagents`](vendor/pi-subagents) via [`.pi/extensions/harness-subagents.ts`](.pi/extensions/harness-subagents.ts) with harness discovery, spawn gates, and subprocess env. Maintainer refresh: `npm run vendor:sync-subagents`.
 
 ## CocoIndex Code (CLI + skill)
 
-- **Project:** https://github.com/cocoindex-io/cocoindex-code  
-- **License:** Apache-2.0  
-- **Install:** `uv tool install 'cocoindex-code[full]'` (see `/harness-setup` §2.4)  
+- **Project:** https://github.com/cocoindex-io/cocoindex-code
+- **License:** Apache-2.0
+- **Install:** `uv tool install 'cocoindex-code[full]'` (see `/harness-setup` §2.4)
 - ultimate-pi vendors the upstream agent skill at [`.agents/skills/ccc/`](.agents/skills/ccc/) and bootstraps indexes via [`.pi/scripts/harness-cocoindex-bootstrap.sh`](.pi/scripts/harness-cocoindex-bootstrap.sh). Replaces deprecated `@beaconbay/ck-search`.