ultimate-pi 0.18.0 → 0.19.0

package/.agents/skills/harness-debate-plan/SKILL.md

@@ -78,4 +78,4 @@ Resume: `harness_debate_round_status({ round_index: N })` → run listed `next_t
 
 Do not `approve_plan` on `policy_decision: block`. On `human_required` → `ask_user` first.
 
-Rubrics: `.pi/prompts/planning-rubrics.md`.
+Rubrics: `.pi/harness/docs/planning-rubrics.md`.

package/.agents/skills/harness-decisions/SKILL.md

@@ -9,8 +9,7 @@ description: Structured user decisions via ask_user for harness setup, planning,
 
 - `/harness-setup` — missing project `.env`, other bootstrap forks
 - `/harness-plan` or harness-auto **plan** phase — scope, risk, acceptance ambiguity
-- Orchestrator receives `human_required` from evaluator, adversary, tie-breaker, or meta-optimizer
-- `/harness-router-tune` — approve / reject / edit a router proposal before apply
+- Orchestrator receives `human_required` from evaluator, adversary, or tie-breaker
 
 ## Decision handshake
 
@@ -72,4 +71,4 @@ Parent orchestrator calls **`approve_plan`** with the full `plan_packet` (scroll
 
 - **Parent orchestrator** during `/harness-plan` — `ask_user` for clarification; **`approve_plan`** then **`create_plan`** for the plan file.
 - `harness/planning/*` (scouts, decompose, hypothesis, hypothesis-eval) — JSON only; no `ask_user` / `approve_plan` / `create_plan`.
-- `harness/evaluator`, `harness/adversary`, and `harness/tie-breaker` — emit `human_required`; the **parent orchestrator** calls `ask_user`.
+- `harness/reviewing/evaluator`, `harness/reviewing/adversary`, and `harness/reviewing/tie-breaker` — emit `human_required`; the **parent orchestrator** calls `ask_user`.

package/.agents/skills/harness-governor/SKILL.md

@@ -14,11 +14,12 @@ description: Enforce harness governance phases, policy gates, budgets, and promo
 ## Workflow
 
 1. Read current phase from `/harness-policy-status` or session `harness-policy-state`.
-2. Check ADRs: constitution (0001), eval promotion (0003), Sentrux (0006), drift (0007), rules lifecycle (0009).
-3. For promotion: require eval pass, no abort lock, debate consensus if escalated, Sentrux when `HARNESS_SENTRUX_REQUIRED=true` (`artifacts/sentrux-signal.yaml` from `/harness-run`, not executor self-report).
-4. **Intent vs observation:** Manifest/layer/boundary changes → `/harness-sentrux-steward` proposal + chair approval + ADR when material, then `sentrux-rules-sync --force`. `sentrux check`/`gate` degradation after execute → replan or fix code — do not tune manifest on a single noisy gate.
-5. After approved manifest edits: `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` or `/harness-sentrux-sync`; emit `harness-architecture-changed` for the extension.
-5. Run `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` before claiming release readiness.
+2. Check ADRs: constitution (0001), eval promotion (0003), Sentrux (0006), drift (0007), rules lifecycle (0009), AGT policy (0046), AGT security layers (0047).
+3. Tool allow/deny is enforced by AGT `PolicyEngine` + `.pi/harness/policies/*.yaml` (parent `policy-gate`, subprocess `harness-subagent-governance`). Disable with `HARNESS_AGT_POLICY=0`. Audit: `.pi/harness/runs/<run_id>/agt-audit.jsonl`.
+4. For promotion: require eval pass, no abort lock, debate consensus if escalated, Sentrux when `HARNESS_SENTRUX_REQUIRED=true` (`artifacts/sentrux-signal.yaml` from `/harness-run`, not executor self-report).
+5. **Intent vs observation:** Manifest/layer/boundary changes → `/harness-sentrux-steward` proposal + chair approval + ADR when material, then `sentrux-rules-sync --force`. `sentrux check`/`gate` degradation after execute → replan or fix code — do not tune manifest on a single noisy gate.
+6. After approved manifest edits: `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` or `/harness-sentrux-sync`; emit `harness-architecture-changed` for the extension.
+7. Run `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` before claiming release readiness (includes AGT policy doctor).
 
 ## Spec Distiller integration
 

package/.agents/skills/harness-orchestration/SKILL.md

@@ -40,7 +40,7 @@ Harness subprocesses load **`harness-subagent-submit`** (`PI_HARNESS_SUBPROCESS=
 | Command | `agent` |
 |---------|---------|
 | `/harness-plan` | Parent: planning context (tools) → decompose → hypothesis → Phase 3.5 artifacts → PlanPacket → eligibility + Review Gate → `approve_plan` + `create_plan` |
-| `/harness-run` | `harness/executor` (single worker) |
+| `/harness-run` | `harness/running/executor` (single worker) |
 | `/harness-review` | Parent verify → `evaluator` benchmark → `evaluator` verdict → `adversary` → optional `tie-breaker` (ADR 0039) |
 | `/harness-eval` | **Deprecated** → `/harness-review` |
 | `/harness-critic` | **Deprecated** → `/harness-review` |
@@ -48,7 +48,7 @@ Harness subprocesses load **`harness-subagent-submit`** (`PI_HARNESS_SUBPROCESS=
 
 ## Review isolation
 
-Spawn `harness/evaluator` / `harness/adversary` via `subagent` in the **same** parent session. `review-integrity` allows `subagent` when `agent` is in the review set.
+Spawn `harness/reviewing/evaluator` / `harness/reviewing/adversary` via `subagent` in the **same** parent session. `review-integrity` allows `subagent` when `agent` is in the review set.
 
 ## ask_user policy
 
@@ -56,8 +56,8 @@ Spawn `harness/evaluator` / `harness/adversary` via `subagent` in the **same** p
 |------|------------|
 | Parent orchestrator | Yes (plan clarification, `approve_plan`, router tune) |
 | `harness/planning/*` | No — `human_required` in output if stuck |
-| `harness/evaluator`, `harness/adversary`, `harness/tie-breaker` | `human_required` in subprocess JSON |
-| `harness/executor` | No — parent handles governance |
+| `harness/reviewing/evaluator`, `harness/reviewing/adversary`, `harness/reviewing/tie-breaker` | `human_required` in subprocess JSON |
+| `harness/running/executor` | No — parent handles governance |
 
 ## Spawn pattern (`/harness-plan`)
 

package/.agents/skills/harness-review/SKILL.md

@@ -21,20 +21,20 @@ description: >-
 
 | Phase | Practice | Actor | Artifact |
 |-------|----------|-------|----------|
-| 1 | Automated QC + Sentrux fitness functions | Parent | `harness-verify.mjs`, `sentrux gate .`, `benchmark-log.yaml`, `sentrux-signal.yaml` |
-| 2 | Measure actuals (EVM) | `harness/evaluator` benchmark | `eval-verdict.yaml` |
+| 1 | Automated QC + Sentrux fitness functions | Parent | `harness-verify.mjs`, `harness-sentrux-cli.mjs gate`, `benchmark-log.yaml`, `sentrux-signal.yaml` |
+| 2 | Measure actuals (EVM) | `harness/reviewing/evaluator` benchmark | `eval-verdict.yaml` |
 | 2b | Controlling | Parent | Write `review-outcome.yaml`; route via `remediation_class` (not fail-fast abort) |
 | 6 | Outcome | Parent | `review-outcome.yaml` → `/harness-steer` or replan |
-| 3 | Policy audit | `harness/evaluator` verdict | same YAML |
-| 4 | Red team | `harness/adversary` | `adversary-report.yaml` |
-| 5 | Arbitration | `harness/tie-breaker` | only if block + conditional_pass |
+| 3 | Policy audit | `harness/reviewing/evaluator` verdict | same YAML |
+| 4 | Red team | `harness/reviewing/adversary` | `adversary-report.yaml` |
+| 5 | Arbitration | `harness/reviewing/tie-breaker` | only if block + conditional_pass |
 
 ## Phase 1 — Sentrux (structural actuals)
 
 When `HARNESS_SENTRUX_REQUIRED=true` (default in `.env.example`):
 
-1. `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` — rules drift + `sentrux check` when CLI installed.
-2. `sentrux gate .` — compare to baseline saved during `/harness-run`.
+1. `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` — rules drift + Sentrux check when CLI installed.
+2. `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate` — compare to baseline saved during `/harness-run`.
 3. Write `artifacts/sentrux-signal.yaml` and append session entry `harness-sentrux-signal` (observation bus / PostHog).
 4. Optional `artifacts/benchmark-log.yaml` fields: `sentrux_check`, `sentrux_gate`, `harness_verify`.
 

package/.agents/skills/harness-sentrux-setup/SKILL.md

@@ -18,7 +18,7 @@ description: Bootstrap Sentrux architectural rules for harness projects — seed
 | **Bootstrap** | `harness/sentrux-bootstrap`, `harness-sentrux-bootstrap.mjs` | Greenfield seed + first sync |
 | **Steward** | `harness/sentrux-steward`, `/harness-sentrux-steward` | Proposes manifest changes (`artifacts/sentrux-manifest-proposal.yaml`); chair applies |
 | **Sync** | `sentrux-rules-sync.mjs`, `/harness-sentrux-sync` | Regenerates `rules.toml` from manifest after intent change |
-| **Observation** | `/harness-run`, `/harness-review` | `sentrux gate --save` / `check` / `gate` → `artifacts/sentrux-signal.yaml` |
+| **Observation** | `/harness-run`, `/harness-review` | `harness-sentrux-cli.mjs gate --save` / `check` / `gate` → `artifacts/sentrux-signal.yaml` |
 
 Never auto-sync manifest from directory trees. Material manifest edits need steward evidence + chair approval (ADR 0009).
 
@@ -39,6 +39,7 @@ Custom TOML **outside** `# --- harness:managed:start/end ---` is preserved on ev
 | First-time / harness-setup (idempotent) | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"` |
 | After manifest edits | `node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs" --force` |
 | CI / verify only | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --check` |
+| Run/review Sentrux observation | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` / `gate [--save]` |
 | In pi session | `/harness-sentrux-sync` (extension; uses `--force`) |
 
 **Bootstrap vs `--force`:** Default bootstrap/sync skips rewriting `rules.toml` when the manifest hash is unchanged. Use `--force` (or `/harness-sentrux-sync`) after changing `architecture.manifest.json` or when verify reports drift.
@@ -51,7 +52,7 @@ Custom TOML **outside** `# --- harness:managed:start/end ---` is preserved on ev
    node "$UP_PKG/.pi/scripts/harness-sentrux-bootstrap.mjs"
    ```
 3. Optional: `sentrux plugin add-standard` (language plugins; harness-setup Step 2.8).
-4. `sentrux check .` — fix violations or tune manifest `max_cc` / layers.
+4. `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` — fix violations or tune manifest `max_cc` / layers.
 5. Commit `.sentrux/rules.toml` and project-specific `architecture.manifest.json`.
 
 ## External repos
@@ -63,6 +64,6 @@ Do **not** copy ultimate-pi's layer paths blindly into unrelated layouts — edi
 ## References
 
 - ADR 0009 — `.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md`
-- Scripts — `.pi/scripts/sentrux-rules-sync.mjs`, `harness-sentrux-bootstrap.mjs`
+- Scripts — `.pi/scripts/sentrux-rules-sync.mjs`, `harness-sentrux-bootstrap.mjs`, `harness-sentrux-cli.mjs`
 - Agents — `harness/sentrux-bootstrap` (setup), `harness/sentrux-steward` (intent proposals)
 - Specs — `sentrux-manifest-proposal.schema.json`, `sentrux-signal.schema.json`

package/.agents/skills/harness-steer/SKILL.md

@@ -8,7 +8,7 @@ description: Post-review repair loop via harness-steer and executor repair mode
 Use after `/harness-review` when `artifacts/review-outcome.yaml` has `remediation_class: implementation_gap`.
 
 1. Read `repair-brief.yaml` and `plan_packet_path` (paths only).
-2. Set policy phase `execute`; spawn `harness/executor` with `mode: repair`.
+2. Set policy phase `execute`; spawn `harness/running/executor` with `mode: repair`.
 3. Always follow with `/harness-review`.
 
 See `.pi/prompts/harness-steer.md` and `.pi/harness/docs/adrs/0044-harness-steer-loop.md`.

package/.agents/skills/sentrux/SKILL.md

@@ -35,22 +35,22 @@ sentrux plugin add-standard
 
 ## Core workflows (project root)
 
-Run from the **target repo root** (where `.sentrux/rules.toml` lives).
+Run from the **target repo root** (where `.sentrux/rules.toml` lives), or prefer the bundled wrapper when invoked by harness commands from run directories.
 
 | When | Command | Notes |
 |------|---------|-------|
-| CI / pre-commit | `sentrux check .` | Exit 0 = pass, 1 = violations |
-| Before agent work | `sentrux gate --save .` | Save session baseline |
-| After agent work | `sentrux gate .` | Detect degradation vs baseline |
+| CI / pre-commit | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` | Exit 0 = pass, 1 = violations |
+| Before agent work | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save` | Save session baseline |
+| After agent work | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate` | Detect degradation vs baseline |
 | Explore structure | `sentrux` or `sentrux .` | GUI treemap (optional) |
 
 Typical agent loop:
 
 ```bash
-sentrux gate --save .
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate --save
 # … agent edits …
-sentrux check .          # rules still pass?
-sentrux gate .           # structural regression?
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check  # rules still pass?
+node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate   # structural regression?
 ```
 
 If `check` fails, fix violations or tune manifest constraints (see **Rules** below). If `gate` reports degradation, inspect changed modules before merging.
@@ -73,7 +73,7 @@ Custom TOML outside `# --- harness:managed:start/end ---` is preserved on sync.
 |-------|------|
 | `sentrux-rules-sync` extension | Session start: warns if `rules.toml` drifts; auto-sync after plan/merge phases |
 | `/harness-sentrux-sync` | Force-regenerate rules from manifest (pi command) |
-| `harness-verify.mjs` | Runs `sentrux check .` when rules present |
+| `harness-verify.mjs` | Runs rules sync and Sentrux checks when rules are present |
 | **observation-bus** | Maps `harness-sentrux-signal` custom entries → evaluator observations |
 | **harness-eval** | Evaluate phase may require a Sentrux quality signal (stub or future MCP) per ADR 0006 |
 
@@ -90,7 +90,7 @@ High level: **execute** uses CLI gate/check around edits; **evaluate** consumes
 - Assume Sentrux **MCP** tools (`scan`, `session_start`, `health`, etc.) exist in **Pi** — they do not; use CLI only
 - Edit or rely on `.pi/mcp.json` for Pi sessions
 - Duplicate bootstrap/sync steps from **harness-sentrux-setup**
-- Skip `sentrux check .` after large refactors when `.sentrux/rules.toml` exists
+- Skip the root-resolving Sentrux check after large refactors when `.sentrux/rules.toml` exists
 
 ## References
 

package/.pi/PACKAGING.md

@@ -6,7 +6,7 @@ Aligned with [pi packages](https://github.com/badlogic/pi-mono/blob/main/package
 
 | Key | Paths | Notes |
 |-----|-------|--------|
-| `extensions` | `.pi/extensions` | TypeScript extensions (loaded by pi) |
+| `extensions` | `.pi/extensions` | TypeScript extensions loaded by pi, including the harness lens wrapper |
 | `skills` | `.agents/skills`, `.pi/skills` | Agent Skills + pi-local skills |
 | `prompts` | `.pi/prompts` | Slash-command prompt templates |
 
@@ -20,9 +20,9 @@ Pi does **not** define `scripts`, `agents`, or `providers` in the manifest.
 
 We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts never ship:
 
-- No `.pi/harness/runs/`, local `model-router.json`, or `firecrawl/.env`
+- No `.pi/harness/runs/`, `.pi/harness/.lens/` runtime config/cache, or `firecrawl/.env`
 - Ship `.pi/settings.example.json`, not `.pi/settings.json` (dev checkout uses `".."` local package)
-- Include **`vendor/pi-model-router/`** ([`pi-model-router`](https://github.com/yeliu84/pi-model-router), MIT) — see repo [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md); refresh with `npm run vendor:sync-router`
+- Include **`.pi/lib/harness-lens/`** (harness-native lens: edit autopatch, secrets, deferred format, LSP) — loaded through `.pi/extensions/harness-lens.ts`; findings flow to harness PostHog telemetry
 - Include **`vendor/pi-vcc/`** ([`pi-vcc`](https://github.com/sting8k/pi-vcc), MIT; inspired by [lllyasviel/VCC](https://github.com/lllyasviel/VCC)) — loaded via `.pi/extensions/ultimate-pi-vcc.ts`; refresh with `npm run vendor:sync-vcc`
 - Include **`vendor/pi-subagents/`** (vendored from [narumiruna/pi-extensions](https://github.com/narumiruna/pi-extensions) `pi-subagents`) — loaded via `.pi/extensions/harness-subagents.ts`; refresh with `npm run vendor:sync-subagents`
 
@@ -37,4 +37,4 @@ We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts n
 
 Runtime pi extensions are regular `dependencies` (installed by `npm install` when pi installs the package). We do **not** use `bundledDependencies`: bundling pre-installs `node_modules` and breaks `npm install -g` / `pi update` for native modules such as `koffi` (empty stub dir, postinstall fails).
 
-`@earendil-works/pi-coding-agent` (and sibling `@earendil-works/pi-ai`, `pi-tui`, `pi-agent-core` used by the vendored router) are provided by the Pi install / hoisted from the peer; ultimate-pi lists the latter three as `devDependencies` for `npm run check:ts`.
+`@earendil-works/pi-coding-agent` (and sibling `@earendil-works/pi-ai`, `pi-tui`, `pi-agent-core` used by bundled extensions and vendored integrations) are provided by the Pi install / hoisted from the peer; ultimate-pi lists the latter three as `devDependencies` for `npm run check:ts`.

package/.pi/SYSTEM.md

@@ -1,37 +1,44 @@
-# Ultimate Pi Coding Agent — System Prompt
+# Harness Coding Agent — System Prompt
 
 You are an enterprise coding agent. Optimize for correctness, minimal diffs, and token efficiency.
 
----
-## Voice
-- Default to concise, direct language.
-- Use caveman mode only when the user explicitly asks for it.
-- Keep commands, paths, code, logs exact.
-
-## Primary Goal
-- Complete user request fully.
-- Preserve repo stability.
-- Prefer smallest safe change.
+Scope: this file is the reusable harness-level instruction set. It must work when copied into or invoked from external projects. Keep it project-agnostic. Put repository-specific paths, ownership, local conventions, and project facts in the active project's `AGENTS.md` or equivalent local instruction file.
 
+---
 ## Instruction Order
 1. System/developer rules.
 2. This file.
 3. User request.
 4. Local conventions from repo files.
 
+---
+## Core Operating Rules
+- Be concise and direct; keep commands, paths, code, and logs exact.
+- Complete the user's request while preserving repo stability.
+- Think before coding: state assumptions, ask when unclear, and surface tradeoffs instead of guessing.
+- For multi-step work, state a brief plan with verification points.
+- Prefer the smallest safe change; avoid speculative features, abstractions, configurability, rewrites, and adjacent cleanup.
+- Every edit must map to the objective. If the plan changes or a better path appears, pause and explain.
+- Match existing style. Remove only unused code that your change created; mention unrelated issues separately.
+- Before edits, consult the graph and relevant local contract/project docs when present.
+- For blocking harness forks, call `ask_user`; never silently default on web-provider mode, `.env` creation, scope, or risk.
+- Validate outcomes with targeted checks/tests, inspect outputs, and never claim unverified success.
+- No placeholders, TODO stubs, mock behavior, or partial implementations unless explicitly requested.
+- Report changed files, why they changed, verification performed, and residual risks/next steps.
+
 ---
 ## Web Policy (Mandatory)
 
 > [!warning] No raw HTTP
-> Route **all** web through [[context7]] (API/library docs) or **`web_search` / `web_fetch`** ([[scrapling-web]]). No `curl`, `wget`, Firecrawl, or scrapling CLI preflight.
+> Route **all** web through [[context7]] for API/library docs or **`web_search` / `web_fetch`** via [[scrapling-web]] for non-API web. Do not use `curl`, `wget`, Firecrawl, or scrapling CLI preflight.
 
 ### API / Library Docs — context7 ONLY
-- `ctx7 library <name> <query>` then `ctx7 docs <id> <query>`
-- context7 owns: function signatures, class APIs, config options, stdlib, framework specs.
-- **Never** use quality-sites or web_fetch for API docs.
+- `ctx7 library <name> <query>` then `ctx7 docs <id> <query>`.
+- context7 owns function signatures, class APIs, config options, stdlib, and framework specs.
+- Never use quality-sites or web_fetch for API docs.
 
-### All Non-API Web — web_search + web_fetch
-See `.agents/skills/scrapling-web/SKILL.md`. **No preflight:** never resolve `UP_PKG`, `ls harness-web.py`, or `python3 -c "import scrapling"` before searching.
+### Non-API Web — web_search + web_fetch
+Use the harness web-search/fetch tools and the `scrapling-web` skill when available. No preflight: never probe package paths, list harness scripts, or import Scrapling before searching.
 
 | Task | Tool |
 |------|------|
@@ -39,121 +46,48 @@ See `.agents/skills/scrapling-web/SKILL.md`. **No preflight:** never resolve `UP
 | Scrape page | `web_fetch` (`url`, optional `fast: true`) |
 | Map links | `web_fetch` (`url`, `mode: map`) |
 
-- **Artifacts:** default under `.web/`; use `read` for full JSON/markdown.
-- **Fallback** (tools unavailable): `python3 "$UP_PKG/.pi/scripts/harness-web.py" …` per scrapling-web skill.
-- **Setup diagnostics only:** `harness-web.py status` (JSON config).
-- **Quality sites:** check `.agents/skills/wiki-autoresearch/references/quality-sites.md` before citing non-API sources. Prefer Tier 1 (StackOverflow, GitHub issues, engineering blogs, arxiv). Exclude AI content farms, mirrors, stale packages.
-- **Research:** use `/wiki-autoresearch <topic>` for deep research. Results are graphified into `graphify-out/`.
+- Artifacts default under the active project's `.web/`; use `read` for full JSON/markdown artifacts.
+- If tools are unavailable, use the installed harness web fallback documented by the `scrapling-web` skill.
+- Run setup diagnostics only when troubleshooting web tooling.
+- Check local quality-site guidance when present before citing non-API sources. Prefer Tier 1 sources; exclude AI content farms, mirrors, and stale packages.
+- For deep research, use `/wiki-autoresearch <topic>` when available and store outputs in the active project's configured research/wiki/graph locations.
 
 ### Missing CLI fallbacks
-- harness-web / Scrapling missing: `uv tool install "scrapling[fetchers]" && scrapling install` then re-run `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"`
-- Context7 missing: `npm install -g ctx7@latest`
+- harness-web / Scrapling missing: `uv tool install "scrapling[fetchers]" && scrapling install` then re-run the harness CLI verification command documented locally.
+- Context7 missing: `npm install -g ctx7@latest`.
 
 ---
-## Graphify-First Workflow (Mandatory)
+## Codebase Exploration Workflow
 
 > [!tip] Graph before grep
-> **Always** build or consult the Graphify knowledge graph before codebase exploration.
-> The graph reveals structure, god nodes, and surprising connections that raw
-> search cannot. 71.5× token reduction on mixed corpora.
-
-### Graphify Knowledge Graph
-
-Graphify builds a queryable knowledge graph from code, docs, papers, and diagrams.
-It identifies core concepts (god nodes), community structure, and cross-domain
-connections via tree-sitter AST analysis + LLM semantic extraction.
-
-| Step | Command | When |
-|------|---------|------|
-| Build graph | `graphify .` | First session, or after major code changes |
-| Update graph | `graphify . --update` | After a few file changes (incremental) |
-| Query graph | `graphify query "question"` | Understanding relationships, architecture |
-| Trace paths | `graphify path "A" "B"` | How two concepts connect (includes call chains) |
-| Explain node | `graphify explain "Concept"` | Deep dive — shows all callers, callees, references |
-| DFS trace | `graphify query "who calls X" --dfs` | Follow a specific call/dependency chain |
-| Read report | Read `graphify-out/GRAPH_REPORT.md` | Fastest path to codebase understanding |
-
-**Call graph tracing via graphify:**
-Graphify's tree-sitter AST extraction captures `calls`, `implements`, and `references`
-edges at build time. Use these to answer call-graph questions without external tools:
-- **Who calls `functionName`?** → `graphify explain "functionName"` (shows all inbound `calls` edges)
-- **What does `functionName` call?** → `graphify explain "functionName"` (shows all outbound `calls` edges)
-- **How does `Auth` reach `Database`?** → `graphify path "Auth" "Database"` (shortest call chain)
-- **Trace a dependency chain deep** → `graphify query "how does X depend on Y" --dfs`
-
-**Semantic code search (two lanes):**
-- **Architecture / relationships** → graphify (`query`, `explain`, `path`, `GRAPH_REPORT.md`)
-- **Implementation by meaning** → CocoIndex Code (`ccc search --limit N "concept"`)
-
-Examples:
-- **Find code by meaning** → `ccc search --limit 10 "authentication session validation"`
-- **Who calls X / cross-module path** → `graphify explain "X"` or `graphify path "A" "B"`
-- **Cross-file surprises** → `graphify query "what unexpected connections exist"`
-
-**Order of operations for codebase exploration:**
-1. Read `graphify-out/GRAPH_REPORT.md` (god nodes, surprises, suggested questions)
-2. Run `graphify query` / `explain` / `path` for architecture and call graphs
-3. Use `sg -p 'pattern'` for structural code search
-4. Use `ccc search --limit N` for conceptual implementation chunks when graphify/sg are insufficient
-5. Read individual files last — scouts and graph already narrowed the set
-
-**Indexing:** Harness runs incremental `ccc index` before subagent spawns. Use `ccc search` only in agents; run `ccc index` at session start or after large edits on parent turns. Never use `ccc search --refresh` in scouts. `/skill:ccc` for full CLI reference.
-
-### Fallback Search (when graph doesn't cover it)
-
-> [!note] Graphify + ccc split responsibilities
-> Graphify owns call graphs and cross-module relationships. `ccc` owns AST-aware
-> semantic chunks. Only fall back to `find`/`grep` for exact literals or non-code files.
-
-| Tool | When | Command |
-|------|------|---------|
-| `sg -p` | **Structural code search** — AST pattern matching | `sg -p 'pattern' --lang typescript` |
-| `sg scan` | Rule-based code scanning (use project rules in `sgconfig.yml`) | `sg scan` |
-| `ccc search` | **Semantic chunks** — implementation by meaning | `ccc search --limit 10 "query"` |
-| `find` | File discovery by name/glob only | `find . -name "*.ts"` |
-| `grep` | **Last resort** — exact literal string matching in non-code files only | `grep -F "exact string"` |
-
-- **Always prefer ast-grep (`sg`) over grep for code search.** ast-grep understands code structure via tree-sitter — it matches patterns, not strings.
-- Never use grep for code search. grep is only for: log files, non-code text files, exact byte-level matching when AST patterns can't work.
-- Always use `--limit N` on `ccc search` to cap output and save context.
-- Graphify is primary for architecture. ast-grep is secondary for structure. ccc is semantic implementation search. grep is last resort.
-- Do NOT install or use grepai/seagoat/mgrep for call-graph traces or semantic
-  search — graphify already handles both.
+> Always build or consult the Graphify knowledge graph before codebase exploration. The graph is for architecture, relationships, and call paths; ast-grep is for structural code search; ccc is for semantic implementation chunks.
+
+### Graphify
+- First session or stale graph: run `graphify .` or the local equivalent.
+- After significant code changes: run `graphify . --update` or the local equivalent.
+- Before reading source files for codebase questions: read `graphify-out/GRAPH_REPORT.md` when present.
+- For relationships/call paths: use `graphify query`, `graphify explain`, or `graphify path` before raw search.
+- For graphify command variants or project-specific graph rules, follow local docs in `AGENTS.md` or equivalent.
+
+### Search order
+1. `graphify query` / `graphify explain` / `graphify path` for architecture and call graphs.
+2. `sg -p 'pattern'` for structural code search; add `--lang` when needed.
+3. `ccc search --limit N "query"` for semantic implementation search.
+4. `find` for file discovery by name/glob only.
+5. `grep -F` only for exact literals in logs, generated text, or non-code files.
+
+Rules:
+- Prefer ast-grep over grep for code; grep is not code search.
+- Always cap `ccc search` with `--limit N`.
+- Do not install or use grepai/seagoat/mgrep for call-graph traces or semantic search; Graphify and ccc cover those lanes.
 
 ---
 ## Agent Routing
 
-> [!tip] Dynamic discovery
-> Use [[agent-router]] skill to discover agents live, match tasks to specialists, and dispatch.
-> Never hardcode agent lists — `find .pi/agents -name '*.md'` tells you what's actually available.
-
----
-## Prompt-Engineering Execution Rules
-1. Restate objective + constraints before major changes.
-2. Make an explicit plan for multi-step tasks.
-3. For blocking harness forks, call `ask_user` (never silently default on Firecrawl mode, `.env` creation, scope, or risk).
-4. Prefer deterministic commands and pinned paths.
-5. Validate outcomes with targeted checks/tests.
-6. Report: changed files, why, verification, risks/next steps.
-
----
-## Change Discipline (Mandatory)
-- Run `graphify . --update` after significant code changes to keep the knowledge graph current.
-- Document design/governance decisions near the harness surfaces under `.pi/harness/` (for example, contract docs in `.pi/harness/specs/` and incident artifacts in `.pi/harness/incidents/`).
-- Before code edits, consult the graphify graph (`graphify query`) and relevant harness contract docs.
-- Make surgical diffs only. No unrelated edits.
-- If unrelated issue found, log separately. Do not auto-fix.
-
----
-## Operating Discipline
-- Do not overthink. When in doubt, respond directly. Simple requests get simple answers.
-- Avoid over-engineering. Only make changes directly requested or clearly required.
-- Never speculate about code, files, or configurations you have not opened or read.
-- If a task has multiple valid approaches, pick the simplest and note the alternative.
-- Scope answers to what was asked. Do not expand into adjacent topics unless requested.
+Use [[agent-router]] to discover agents live, match tasks to specialists, and dispatch. Never hardcode agent lists; discover agents from the active project's configured agent directories.
 
 ---
 ## Git / Delivery Rules
 - Keep commits scoped and atomic.
 - Prefer readable commit messages.
-- Never rewrite user history unless explicitly asked.
+- Never rewrite user history unless explicitly asked.

package/.pi/agents/harness/incident-recorder.md

@@ -1,6 +1,5 @@
 ---
 description: Harness incident recorder compiling structured IncidentRecord drafts from run context.
-tools: read, grep, find, ls, submit_human_required
 extensions: false
 thinking: medium
 max_turns: 15

package/.pi/agents/harness/planning/decompose.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase DeepMind-style problem decomposition (read-only).
-tools: read, grep, find, ls, bash, submit_decomposition_brief
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 12
@@ -23,7 +21,7 @@ Read `HarnessSpawnContext` and the merged **scout lane JSON** in the spawn promp
 
 1. Read Phase 1 reconnaissance from spawn context paths — prefer `artifacts/planning-context.yaml`; legacy `artifacts/scout-*.yaml` lanes are accepted when present.
 2. Synthesize findings into constraints, prior art, and tensions — cite `key_paths` / `evidence_refs` when available.
-3. **Graphify dedup:** If `planning-context.yaml` has `coverage.architecture.status` of `ok`, or legacy `scout-graphify.yaml` has `status: ok`, do **not** run `graphify query` / `graphify explain` / `graphify path`. If architecture coverage is missing or failed, you may run read-only `graphify query` / `sg -p` (no `graphify update`, installs, or redirects).
+3. **Graphify dedup:** If `planning-context.yaml` has `coverage.architecture.status` of `ok`, do **not** run `graphify query` / `graphify explain` / `graphify path`. If architecture coverage is missing or failed, you may run read-only `graphify query` / `sg -p` (no `graphify update`, installs, or redirects).
 4. Do not read `.pi/harness/specs/*.schema.json` from disk.
 
 ## Phase 1 — DeepMind-style decomposition

package/.pi/agents/harness/planning/execution-plan-author.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase ExecutionPlan generator (PM-grade WBS + DAG).
-tools: read, grep, find, ls, submit_execution_plan_brief
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: high
 max_turns: 18

package/.pi/agents/harness/planning/hypothesis-validator.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase blind hypothesis validation (debate R1 only).
-tools: read, grep, find, ls, submit_hypothesis_validation
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 10

package/.pi/agents/harness/planning/hypothesis.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase DARWIN hypothesis generation (read-only).
-tools: read, grep, find, ls, bash, submit_hypothesis_brief
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 14

package/.pi/agents/harness/planning/implementation-researcher.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase external solution / prior-art research (web + in-repo, read-only writes via parent).
-tools: read, grep, find, ls, bash, web_search, web_fetch, submit_implementation_research
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 14

package/.pi/agents/harness/planning/plan-adversary.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase adversarial verification on ExecutionPlan.
-tools: read, grep, find, ls, submit_adversary_brief
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 14

package/.pi/agents/harness/planning/plan-evaluator.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase Validation Checks evaluator (neutral pass/fail).
-tools: read, grep, find, ls, submit_validation_turn
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 14
@@ -13,7 +11,7 @@ max_turns: 14
 
 Score the ExecutionPlan against Validation Checks for one Review Gate round. Emit stable `checks[]` with ids and messenger-ready `claim_ids`. You are not an advocate for the plan.
 
-Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`. Use rubric ids from `.pi/prompts/planning-rubrics.md` for that focus.
+Parent passes `debate_round_focus`: `spec` | `wbs` | `schedule` | `quality`. Use rubric ids from `.pi/harness/docs/planning-rubrics.md` for that focus.
 
 ## Process
 

package/.pi/agents/harness/planning/planning-context.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase optional reconnaissance subagent — graphify, sg, ccc (read-only). Prefer parent tool use.
-tools: read, bash, ls, submit_planning_context
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent, grep, find
 extensions: false
 thinking: low
 max_turns: 12

package/.pi/agents/harness/planning/review-integrator.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase Review Gate integrator (round → debate bus).
-tools: read, grep, find, ls, submit_review_round_draft
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 12

package/.pi/agents/harness/planning/sprint-contract-auditor.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase ADR-020 sprint contract auditor.
-tools: read, grep, find, ls, submit_sprint_audit
-disallowed_tools: write, edit, bash, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 12

package/.pi/agents/harness/planning/stack-researcher.md

@@ -1,7 +1,5 @@
 ---
 description: Plan-phase stack research (ctx7 + web, read-only file writes via parent).
-tools: read, grep, find, ls, bash, web_search, web_fetch, submit_stack_brief
-disallowed_tools: write, edit, ask_user, approve_plan, create_plan, subagent
 extensions: false
 thinking: medium
 max_turns: 16

package/.pi/agents/harness/{adversary.md → reviewing/adversary.md}

@@ -1,8 +1,6 @@
 ---
 description: Adversarial harness reviewer focused on breaking assumptions and surfacing regressions.
-tools: read, grep, find, ls, submit_adversary_report
 extensions: false
-disallowed_tools: ask_user
 thinking: high
 max_turns: 20
 ---

package/.pi/agents/harness/{evaluator.md → reviewing/evaluator.md}

@@ -1,8 +1,6 @@
 ---
 description: Independent harness evaluator producing structured pass/fail verdicts.
-tools: read, grep, find, ls, submit_eval_verdict
 extensions: false
-disallowed_tools: ask_user
 thinking: high
 max_turns: 20
 ---

package/.pi/agents/harness/{tie-breaker.md → reviewing/tie-breaker.md}

@@ -1,8 +1,6 @@
 ---
 description: Final arbiter for unresolved evaluator vs adversary debates within budget limits.
-tools: read, grep, find, ls, submit_human_required
 extensions: false
-disallowed_tools: ask_user
 thinking: high
 max_turns: 15
 ---

package/.pi/agents/harness/{executor.md → running/executor.md}

@@ -1,8 +1,6 @@
 ---
 description: Harness executor that implements only within approved PlanPacket scope.
-tools: read, write, edit, bash, grep, find, ls, submit_executor_handoff
 extensions: true
-disallowed_tools: ask_user
 thinking: medium
 max_turns: 20
 ---

package/.pi/agents/harness/sentrux-bootstrap.md

@@ -1,6 +1,5 @@
 ---
 description: Bootstrap Sentrux rules for a harness project — seed architecture manifest, sync merge-safe rules.toml, verify sentrux check.
-tools: read, bash, grep, find, ls
 extensions: true
 thinking: low
 max_turns: 12