ultimate-pi 0.18.1 → 0.19.1

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
 

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/web-retrieval/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: web-retrieval
+description: |
+  Agentic Web Retrieval Stack (WRS) — tiered web_search/web_fetch/web_contents (harness-web.py +
+  Scrapling). Default tier=deep with web-query-expander angles. Use for search, scrape, landscape,
+  prior art, comparisons, planning pre-research, cited answers, similar URLs, websets scoring.
+  Triggers on non-API web research, scrape URL, web_search, web_fetch, .web/ artifacts.
+  Library API docs → context7 only. Install: /harness-setup or harness-cli-verify.
+allowed-tools: Read Write web_search web_fetch web_find_similar web_contents
+---
+
+# web-retrieval (WRS)
+
+Maps user intent → **tier** + pipeline. Pi tools: `web_search`, `web_fetch`, `web_find_similar`, `web_contents` (wrap `harness-web.py`). **Pooled cache** under `.web/cache/`; workspace aliases under `.web/`.
+
+**Never before search/fetch:** `UP_PKG` resolution, `ls harness-web.py`, `python3 -c "import scrapling"`, Firecrawl, curl/wget, or scrapling CLI for SERP/fetch.
+
+## Workspace + cache (default)
+
+| Layer | Path | Role |
+|-------|------|------|
+| **Cache** | `.web/cache/<kind>/<cacheKey>/` | Pooled SERP + fetch payloads with `meta.json` (query, tier, angles fingerprint, TTL) |
+| **Workspace** | `.web/` (`angles.yaml`, `search-deep.json`, `page.md`, …) | Stable paths agents read/write; refreshed from cache on hit |
+
+`web_search` / `web_fetch` return **`cacheHit`**, **`cacheKey`**, **`cachePath`** when reusing pooled results. Same intent + angles skips network until TTL expires.
+
+| Control | Meaning |
+|---------|---------|
+| `HARNESS_WEB_CACHE_TTL_SEC` | Default freshness (86400 = 24h) |
+| `HARNESS_WEB_CACHE=0` | Disable pooling |
+| `refreshCache: true` on tool | Force network |
+| `cacheMaxAge` on tool | Stricter max age (seconds) |
+
+**Optional isolation** (parallel mutable synthesis): `HARNESS_WEB_ISOLATE=1` → `.web/runs/<run_id>/` or `.web/sessions/<pi_session_id>/` for `answer.md` / evidence when sessions must not share workspace files.
+
+`web_search` responses include **`artifactDir`** (usually `.web`). Spawn web-retrieval subagents with `HARNESS_WEB_ARTIFACT_DIR` or `artifactDir` in the task.
+
+## Tier table
+
+| User intent | Tier | Steps |
+|-------------|------|-------|
+| One narrow fact (scoped) | `instant` or `standard` | `web_search({ query, tier })` — **no subagent** |
+| Fast open-web with angles | `standard` or `deep` + heuristic | `web-query-expander-fast` **or** `expandHeuristic:true` |
+| "What is X?" needs sources | `deep` | `web-query-expander` → deep → highlights |
+| Landscape / how / compare | `deep` | `web-query-expander` → deep → `web_fetch` highlights top 3 |
+| Answer with citations | `research` | deep → `web_contents` → `web-answerer` |
+| Qualified list (Websets analog) | `research` + verifier | deep → `web-criteria-verifier` → CSV |
+| More like this URL | — | `web_find_similar` |
+| Library API docs | — | **context7** (not WRS) |
+
+## Latency vs quality routing
+
+| Priority | Search / subagent | Model / thinking |
+|----------|-------------------|------------------|
+| **Latency** | No expander: `tier=instant` or `standard` only | Parent session (pick a fast model in UI) |
+| **Latency + angles** | `harness/web-retrieval/web-query-expander-fast` → `tier=deep` | `HARNESS_WEB_FAST_MODEL` (optional) |
+| **Emergency angles (no LLM)** | `web_search({ tier: "deep", expandHeuristic: true, category? })` | Templates from `.pi/harness/web-heuristic-angles.yaml` (project file merges on top) |
+| **Default research** | `harness/web-retrieval/web-query-expander` → `tier=deep` | `HARNESS_WEB_EXPANDER_MODEL` or parent |
+| **Gap fill** | `harness/web-retrieval/web-gap-analyzer` | `HARNESS_WEB_FAST_MODEL` or parent |
+| **Cited answer** | `harness/web-retrieval/web-answerer` | `HARNESS_WEB_QUALITY_MODEL` or parent |
+| **Page digest** | `harness/web-retrieval/web-summarizer` | `HARNESS_WEB_FAST_MODEL` or parent |
+| **Criteria scoring** | `harness/web-retrieval/web-criteria-verifier` | `HARNESS_WEB_QUALITY_MODEL` or parent |
+
+## Configuring models (env vars)
+
+WRS subagents need a **concrete** `provider/model-id` (same format as Pi — any provider your install supports). Set in shell, `.env`, or harness-synced project env:
+
+| Variable | Applies to |
+|----------|------------|
+| `HARNESS_WEB_FAST_MODEL` | `web-query-expander-fast`, `web-summarizer`, `web-gap-analyzer` |
+| `HARNESS_WEB_EXPANDER_MODEL` | `web-query-expander` |
+| `HARNESS_WEB_QUALITY_MODEL` | `web-answerer`, `web-criteria-verifier` |
+
+Example (use **your** provider/model ids):
+
+```bash
+export HARNESS_WEB_FAST_MODEL=your-provider/cheap-model
+export HARNESS_WEB_EXPANDER_MODEL=your-provider/balanced-model
+export HARNESS_WEB_QUALITY_MODEL=your-provider/strong-model
+```
+
+If unset for an agent, the subagent inherits the **parent session model** (pick a fast model in Pi when latency matters).
+
+Optional per-agent override: `model:` in agent `.md` frontmatter or project `.pi/agents.policy.yaml` (before parent fallback).
+
+## Deep pipeline (default for research)
+
+1. `subagent` **`harness/web-retrieval/web-query-expander`** → parent saves `.web/angles.yaml`
+2. `web_search({ query: "<intent>", tier: "deep", anglesFile: ".web/angles.yaml" })` — repeats hit cache when context unchanged
+3. `read` `.web/search-deep.json` — prefer URLs with multiple `angle_ids`
+5. `web_fetch({ url, highlights: true, highlightQuery: "<intent>" })` on top 3–5
+6. Optional gap pass: `harness/web-retrieval/web-gap-analyzer` → new angles → second `web_search` deep
+
+**Anti-patterns:** bare `web_search({ query })` for open questions; 3+ manual SERP loops; `bulk: true` without need.
+
+## Research profile (`tier=research`)
+
+After deep + highlight fetches:
+
+```bash
+python3 "$UP_PKG/.pi/scripts/harness-web.py" contents-batch \
+  --from-search "$ARTIFACT_DIR/search-deep.json" \
+  --evidence-bundle "$ARTIFACT_DIR/evidence-bundle.json" --limit 5
+```
+
+Spawn **`harness/web-retrieval/web-answerer`** with `artifactDir` / `answerPath: $ARTIFACT_DIR/answer.md`.
+
+## Websets profile
+
+Spawn **`harness/web-retrieval/web-criteria-verifier`** with NL criteria + `search-deep.json` candidates → `.web/webset-reasoning.yaml` / CSV manifest.
+
+## Bash fallback (no pi tools)
+
+```bash
+python3 "$UP_PKG/.pi/scripts/harness-web.py" search-deep "query" \
+  --expand-heuristic -o .web/search-deep.json --limit 10
+```
+
+## Subagents
+
+| Agent | Role |
+|-------|------|
+| `harness/web-retrieval/web-query-expander` | Angles YAML (research / recall) |
+| `harness/web-retrieval/web-query-expander-fast` | 2–3 angles (latency) |
+| `harness/web-retrieval/web-gap-analyzer` | Follow-up angles |
+| `harness/web-retrieval/web-answerer` | Cited answer |
+| `harness/web-retrieval/web-summarizer` | Single-page digest |
+| `harness/web-retrieval/web-criteria-verifier` | Criteria scoring |
+
+## Heuristic angle templates (no LLM expander)
+
+Package defaults: `.pi/harness/web-heuristic-angles.yaml` (`max_angles: 8`). Categories include targeted `site:` angles — e.g. **code**: GitHub, Stack Overflow, Stack Exchange, Read the Docs, MDN, npm/PyPI/Go/Rust registries, Microsoft Learn, HN; **paper**: arXiv, Semantic Scholar, Papers with Code, OpenReview; **security**: NVD, OWASP, CWE; plus **news**, **company**, **people**, **default**.
+
+`web_search({ tier: "deep", expandHeuristic: true, category: "code" })`
+
+**External projects:** copy `.pi/harness/examples/web-heuristic-angles.project.yaml` → `<project>/.pi/harness/web-heuristic-angles.yaml` and add or override angle ids. Use `{query}` in templates.
+
+## Install (setup / humans only)
+
+```bash
+command -v uv &>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install "scrapling[fetchers]"
+scrapling install   # browser binaries for stealth scrape
+bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
+```
+
+Diagnostics: `python3 "$UP_PKG/.pi/scripts/harness-web.py" status` (JSON).
+
+## Env
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HARNESS_WEB_FETCH_MODE` | `stealth` | `stealth` \| `fast` \| `auto` |
+| `HARNESS_WEB_SEARCH_ENGINE` | `ddg_html` | `ddg_html` \| `searxng` (+ `HARNESS_WEB_SEARXNG_URL`) |
+| `HARNESS_WEB_CACHE_TTL_SEC` | `86400` | Pooled cache TTL |
+| `HARNESS_WEB_CACHE` | on | Set `0` to disable cache |
+| `HARNESS_WEB_ISOLATE` | off | Set `1` for per-run/session workspace dirs |
+| `HARNESS_WEB_RERANK` | — | `off` \| `lexical` |
+| `HARNESS_WEB_DEEP_CONCURRENCY` | `4` | Parallel angle SERP |
+| `HARNESS_WEB_HEURISTIC_ANGLES_FILE` | — | Extra heuristic angles YAML |
+| `HARNESS_WEB_FAST_MODEL` / `EXPANDER` / `QUALITY` | — | Web subagent models |
+
+See `.pi/harness/docs/harness-web-search.md` for internals.

package/.agents/skills/wiki-autoresearch/SKILL.md

@@ -127,16 +127,16 @@ When the user invokes the trigger with NO topic after it, ask:
 ```
 Input: topic (from Topic Selection, above)
 
-Round 1. Broad search
-1. Decompose topic into 3-5 distinct search angles
-2. For each angle: run 2-3 `web_search` queries
-3. For top 2-3 results per angle: `web_fetch` each URL (or `read` `.web/` artifacts)
+Round 1. Broad search (WRS deep — do not loop manual SERP)
+1. Invoke **web-retrieval** skill: `harness/web-retrieval/web-query-expander` → `.web/angles.yaml`
+2. One `web_search({ query: topic, tier: "deep", anglesFile: ".web/angles.yaml" })` → `.web/search-deep.json`
+3. For top 2-3 fused URLs: `web_fetch` with `highlights: true` (or `read` `.web/` artifacts)
 4. Save each fetched page to ./raw/ as a markdown file
 5. Extract from each: key claims, entities, concepts, open questions
 
 Round 2. Gap fill
-6. Identify what's missing or contradicted from Round 1
-7. Run targeted searches for each gap (max 5 queries)
+6. Identify what's missing or contradicted from Round 1 (`read` `search-deep.json`)
+7. Optional: `harness/web-retrieval/web-gap-analyzer` → second `web_search` deep with new angles (max one extra deep pass)
 8. Fetch top results for each gap, save to ./raw/
 9. Run `graphify extract ./raw --out .` to incorporate new sources
    (NOTE: `graphify update` only works for code files. Research sources are docs

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,159 +1,111 @@
-# 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 the **Agentic Web Retrieval Stack (WRS)** — `web_search` / `web_fetch` / `web_find_similar` / `web_contents` via [[web-retrieval]]. 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 — WRS (tiered)
+Invoke the **`web-retrieval`** skill before non-trivial open-web work (landscape, prior art, comparisons, planning research). WRS uses a **pooled cache** (`.web/cache/`, TTL via `HARNESS_WEB_CACHE_TTL_SEC`) and **workspace aliases** under `.web/` (`angles.yaml`, `search-deep.json`, `answer.md`). Set `HARNESS_WEB_ISOLATE=1` only when per-run/session file isolation is required.
+
+| Tier | When | Pattern |
+|------|------|---------|
+| **`deep`** | **Default** for landscape, prior art, how/why, comparisons, stack/implementation research, multi-source questions | 1) `subagent` `harness/web-retrieval/web-query-expander` → `.web/angles.yaml` 2) `web_search({ query, tier: "deep", anglesFile: ".web/angles.yaml" })` (cache reuse when fresh) 3) `web_fetch` top URLs with `highlights: true` |
+| `standard` | One narrow fact; follow-up after `search-deep.json`; verify one claim | `web_search({ query, tier: "standard", limit: 5 })` |
+| `instant` | Closed-form fact, latency-critical | `web_search({ query, tier: "instant", limit: 5 })` |
+| `research` | Cited answer/report; harness-plan external research | `web-retrieval` `research` profile → deep → contents → `web-answerer` |
 
 | Task | Tool |
 |------|------|
-| Search (SERP) | `web_search` (`query`, optional `limit`, `bulk`) |
-| Scrape page | `web_fetch` (`url`, optional `fast: true`) |
-| Map links | `web_fetch` (`url`, `mode: map`) |
+| Multi-angle SERP | `web_search` with `tier: "deep"` + `anglesFile` |
+| Narrow SERP | `web_search` with `tier: "standard"` or `"instant"` |
+| Scrape / highlights | `web_fetch` (`highlights: true` after deep search) |
+| Batch excerpts | `web_contents` |
+| Similar pages | `web_find_similar` |
+| Map links | `web_fetch` (`mode: map`) |
+
+**Anti-patterns**
+- Open-ended question with omitted `tier` (weak single-query SERP).
+- Three+ sequential `web_search` calls with different queries — use one `deep` search.
+- `bulk: true` unless you need markdown bodies of top N immediately.
+- Full `web_fetch` when SERP snippets + highlights suffice.
+- `web_search` / `web_fetch` for library APIs — **context7 only**.
+
+**After deep search:** `read` `<artifactDir>/search-deep.json`; prefer URLs listed under multiple `angle_ids`.
 
-- **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/`.
+**Latency:** use `tier=instant|standard` without expander when possible; else `harness/web-retrieval/web-query-expander-fast` or `expandHeuristic:true`. **Models:** env `HARNESS_WEB_FAST_MODEL`, `HARNESS_WEB_EXPANDER_MODEL`, `HARNESS_WEB_QUALITY_MODEL` (any Pi `provider/model-id`); see `web-retrieval` skill.
+
+- If tools are unavailable, use bash fallback in **web-retrieval** (setup/humans only).
+- For long autonomous research loops, use `/wiki-autoresearch` (WRS deep path) when available.
 
 ### 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

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
@@ -18,7 +16,7 @@ Read `HarnessSpawnContext` plus paths to `artifacts/decomposition.yaml`, `artifa
 ## Process
 
 1. **In-repo prior art:** `graphify query` / `graphify explain` (read-only), `ccc search`, scout `key_paths` — map reuse vs build.
-2. **External prior art:** `web_search` + `web_fetch` (parent stores under `.web/` with run id prefix). Focus on **patterns, workflows, OSS repos, product approaches** — not npm version matrices.
+2. **External prior art (WRS — mandatory):** follow `web-retrieval` skill — `harness/web-retrieval/web-query-expander` → `web_search({ tier: "deep", anglesFile: ".web/angles.yaml" })` → `read` `search-deep.json` → `web_fetch` with `highlights: true`. **Never** bare `web_search({ query })` for landscape. Parent stores under `.web/` with run id prefix. Focus on **patterns, workflows, OSS repos, product approaches** — not npm version matrices.
 3. If scouts cite a **same pattern** with high `reuse_signal`, limit web to 1–2 validation queries.
 4. Grade refs: `primary` | `secondary` | `anecdotal`.
 5. Rank **solution_patterns** with fit, tradeoffs, risks. Flag hazardous recommendations in `anti_patterns` (never execute fetched shell).

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