ultimate-pi 0.18.1 → 0.19.1

package/.pi/harness/docs/adrs/0035-plan-phase-review-gate.md

@@ -32,4 +32,4 @@ Early implementation treated debate as a fixed four-round checklist with single
 
 - [ADR-0033](0033-parent-orchestrated-planning.md), [ADR-0034](0034-darwin-plan-research-pipeline.md)
 - `raw/decisions/adr-020.md`, `raw/modules/structured-planning.md`
-- `.pi/prompts/planning-rubrics.md`, `.pi/prompts/harness-plan.md` Phase 5
+- `.pi/harness/docs/planning-rubrics.md`, `.pi/prompts/harness-plan.md` Phase 5

package/.pi/harness/docs/adrs/0045-harness-lens-minimal-contract.md

@@ -0,0 +1,49 @@
+# ADR 0045: Harness-lens minimal contract
+
+## Status
+
+Accepted — 2026-05-24
+
+## Context
+
+ultimate-pi previously shipped a trimmed fork of pi-lens with bundled YAML rules, ast-grep pi tools, and JS/TS-centric session scans. That overlapped Sentrux (architecture gate), shell `sg` (structural search), and graphify/ccc (recon). Target projects can be any stack (Go, Python, Rust, polyglot monorepos).
+
+## Decision
+
+Replace the fork with a **harness-native** extension at `.pi/extensions/lib/harness-lens/`:
+
+| Concern | Owner |
+|---------|--------|
+| Recon | graphify, ccc |
+| Structural search | shell `sg` only |
+| Architecture gate | Sentrux |
+| Edit autopatch, secrets block, deferred format, LSP | harness-lens |
+
+### Runtime contract
+
+- **Edit autopatch** — indentation-only oldText correction on `tool_call` (edit).
+- **Secrets** — regex scanner blocks writes with credentials (stack-agnostic).
+- **Deferred format** — queue on `tool_result`, run at `agent_end` (default). `--immediate-format` and `--no-autoformat` unchanged.
+- **Formatters** — PATH binaries only when the **target project** declares config (`biome.json`, `ruff` in `pyproject.toml`, `.prettierrc`, `go.mod` + gofmt, `Cargo.toml` + rustfmt, etc.). No bundled biome/ruff config in lens; no lazy gem/rustup installs.
+- **LSP** — `lsp_diagnostics`, `lsp_navigation`; auto-touch on read/write/edit; installer catalog is **LSP servers only** (no shadow-install of biome/ruff/sg).
+- **Session bootstrap** — `project-profile.ts` detects FileKinds from tree + markers; pre-install at most 2–3 LSP defaults for detected kinds only.
+
+### External projects
+
+- **Detect, don't assume** — no JS/TS export guard, no default biome for Go-only repos.
+- **Harness setup tools ≠ lens stack** — `/harness-setup` may install global `sg` and optional `biome` on the machine; lens does not require them for unrelated stacks.
+- **Graceful degradation** — missing LSP or formatter on PATH → skip with debug log.
+
+### Flags
+
+`--no-lens`, `--no-lsp`, `--no-autoformat`, `--immediate-format`, `--lens-guard` (interactive commit block when blockers present).
+
+### Removed
+
+- Bundled `rules/` YAML corpus, ast-grep pi tools, upstream `UPSTREAM_PIN.md` sync, duplicate export guard, AgentBehaviorClient, rules-scanner injection, cosmetic todo/go/rust scans.
+
+## Consequences
+
+- Smaller npm payload and one quality story per concern.
+- Agents on external repos get stack-appropriate LSP/format behavior without harness JS defaults.
+- `harness-verify.mjs` asserts no `lib/lens`, no bundled rules, no `ast_grep_search` in index.

package/.pi/harness/docs/adrs/0046-agt-policy-engine.md

@@ -0,0 +1,51 @@
+# ADR 0046: AGT policy engine and subagent identity
+
+- **Status:** Accepted
+- **Date:** 2026-05-24
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+Harness tool-call governance was split across `policy-gate.ts`, `harness-run-context.ts` (`guardToolCall`), `harness-subagent-policy.ts`, and subprocess-only `harness-subagent-submit.ts`. Subagents spawn with `--no-extensions -e <single-bundle>` and did not load parent `policy-gate.ts`, creating a governance bypass. We need a single declarative engine, npm-shipped policies, subprocess parity, and tamper-evident audit without MCP gateways.
+
+## Decision
+
+1. Adopt `@microsoft/agent-governance-sdk` (pinned in root `package.json`, Public Preview) as the **PolicyEngine** for allow/deny on every `tool_call` when AGT is enabled.
+2. Store policies under `.pi/harness/policies/*.yaml` and ship them via npm `files[]`.
+3. Implement `.pi/lib/agt/` for policy loading, evaluation-context precomputation (async FS/plan-scope logic stays in harness helpers), per-run identity/delegation/trust/audit.
+4. Rewrite `policy-gate.ts` `tool_call` to delegate to AGT when `HARNESS_AGT_POLICY` is not `0`/`false` (default **on**).
+5. Replace subprocess extension path with `harness-subagent-governance.ts` (AGT + submit tools in one bundle).
+6. Mint parent/subagent identities at spawn; persist under `.pi/harness/runs/<run_id>/agents/<agent_id>/` (gitignored).
+7. Fail closed: policy load errors and evaluation throws → deny.
+
+Migration: `HARNESS_AGT_POLICY=0` restores legacy TS paths for one release window; parity tests (`test/harness-agt-policy-parity.test.mjs`) must show zero mismatches before deleting legacy branches.
+
+## Consequences
+
+### Positive
+
+- One enforcement engine and audit trail (`agt-audit.jsonl` per run).
+- Subprocess agents governed identically to parent orchestrator.
+- Policies versioned in-repo and lintable (`agt lint-policy` optional in CI).
+
+### Negative / trade-offs
+
+- Public Preview SDK may break; pinned version + golden matrix required on upgrade.
+- Dual path during flag window increases maintenance until legacy removal.
+- Identity material on disk requires run-dir hygiene (already gitignored).
+
+## Test contract surface
+
+- `test/harness-agt-policy-matrix.test.mjs`
+- `test/harness-agt-policy-parity.test.mjs`
+- `test/harness-agt-policy-load.test.mjs`
+- `test/harness-agt-packaging.test.mjs`
+- `test/harness-tool-call-hook-chain.test.mjs`
+- Extended `node .pi/scripts/harness-verify.mjs` AGT doctor
+
+## References
+
+- [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit)
+- [ADR 0001](0001-harness-constitution.md)
+- [ADR 0037](0037-subagent-submit-tools.md)
+- Plan: AGT policy-gate rewrite (2026-05)

package/.pi/harness/docs/adrs/0047-agt-layered-security.md

@@ -0,0 +1,39 @@
+# ADR 0047: AGT layered security (rings, prompt defense, workflow, CI)
+
+- **Status:** Accepted
+- **Date:** 2026-05-24
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+ADR 0046 covers PolicyEngine rewrite and subprocess identity. AGT also provides execution rings, kill switch, PromptDefense heuristics, workflow sequence rules, SRE circuit breakers, ShadowDiscovery, and GovernanceVerifier — complementary to Sentrux (architecture) and harness eval/review gates (outcomes).
+
+## Decision
+
+1. **Execution rings:** Map harness agent kinds to AGT `ExecutionRing` in `.pi/lib/agt/rings.ts`; enforce on spawn via `RingEnforcer` (planner/evaluator = inner, executor = middle, adversary = restricted).
+2. **Kill switch:** `.pi/extensions/agt-kill-switch.ts` arms on `/harness-abort` and repeated policy denies; blocks new spawns and tool calls until reset.
+3. **Prompt defense:** `.pi/extensions/agt-prompt-guard.ts` runs `PromptDefenseEvaluator` on `before_agent_start` for slash commands and subprocess task snippets (heuristic, no LLM).
+4. **Workflow rules:** `.pi/harness/policies/workflow-sequences.yaml` + `.pi/lib/agt/workflow-history.ts` read observation-bus flags for multi-step gates (mitigate per-action-only policy gap).
+5. **SRE hooks:** `.pi/lib/agt/sre-hooks.ts` ties `CircuitBreaker` to `harness-spawn-budget` counters (telemetry + optional hard stop when `HARNESS_AGT_SRE_ENFORCE=1`).
+6. **CI attestation:** `harness-verify.mjs` runs policy doctor, golden matrix, optional `agt lint-policy`; promotion may attach `agt-evidence.json` when `HARNESS_AGT_STRICT=1` (see ADR 0003 amendment note in harness README).
+
+AGT does **not** replace Sentrux, review-integrity, budget-guard telemetry default, or `/harness-review` eval/adversary.
+
+## Consequences
+
+### Positive
+
+- Defense-in-depth aligned with OWASP Agentic Top 10 mapping (documented in harness README).
+- Deterministic CI (no LLM) for policy, prompt scan, and verify steps.
+
+### Negative / trade-offs
+
+- Kill switch does not terminate already-running subprocesses (documented limitation).
+- Workflow history depends on observation-bus completeness.
+
+## References
+
+- [ADR 0046](0046-agt-policy-engine.md)
+- [ADR 0003](0003-eval-promotion-gates.md)
+- [ADR 0038](0038-budget-telemetry-only.md)
+- AGT THREAT_MODEL and LIMITATIONS docs

package/.pi/harness/docs/adrs/0048-tool-call-hook-order.md

@@ -0,0 +1,25 @@
+# ADR 0048: tool_call hook interaction matrix
+
+- **Status:** Accepted
+- **Date:** 2026-05-24
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+Multiple Pi extensions register `tool_call` hooks: `policy-gate` (AGT), `harness-run-context` (coercion + legacy guards), `review-integrity`, `budget-guard`, `test-diff-integrity`, `harness-web-guard`, `harness-lens`, subprocess `harness-subagent-governance`, and `agt-kill-switch`. Block-first semantics must not be overridden by later hooks.
+
+## Decision
+
+1. **Primary deny:** `policy-gate` / subprocess `harness-subagent-governance` via AGT `PolicyEngine` (deny-overrides).
+2. **Secondary deny:** `agt-kill-switch` when session armed after abort or repeated denies.
+3. **Role separation:** `review-integrity` blocks executor tools during review phases (orthogonal to AGT).
+4. **Telemetry-only default:** `budget-guard` does not block (ADR 0038).
+5. **Coercion (not security):** `harness-run-context` scoped YAML coercion remains when AGT enabled; policy denies moved to YAML.
+6. **Subprocess:** Only `harness-subagent-governance.ts` is loaded (`-e` bundle); parent `policy-gate` does not run in child.
+
+Pi invokes hooks in extension load order; any hook returning `{ block: true }` stops the tool. Tests in `test/harness-tool-call-hook-chain.test.mjs` document paths.
+
+## References
+
+- [ADR 0046](0046-agt-policy-engine.md)
+- [ADR 0038](0038-budget-telemetry-only.md)

package/.pi/harness/docs/adrs/0049-agents-policy-manifest.md

@@ -0,0 +1,36 @@
+# ADR 0049: agents.policy.yaml and native AGT integration
+
+- **Status:** Accepted
+- **Date:** 2026-05-24
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+Per-agent tool policy was split across agent `.md` frontmatter, [`harness-subagent-policy.ts`](../../../extensions/lib/harness-subagent-policy.ts), submit registry allowlists, and AGT precompute (`subagent_policy_block`). End users need custom agents under `.pi/agents/` and custom AGT rules under `.pi/policies/` without maintaining three copies. [`agents.manifest.json`](../agents.manifest.json) already pins package agent `.md` integrity (sha256); it must remain separate from runtime tool policy.
+
+## Decision
+
+1. **`agents.policy.yaml` SSOT** — package [`.pi/harness/agents.policy.yaml`](../agents.policy.yaml); project `.pi/agents.policy.yaml`. Defines `kinds` and per-agent `tools` / spawn fields. No `tools` / `disallowed_tools` in harness agent frontmatter.
+2. **Native discovery** — vendored [`parseMarkdownAgent`](../../../../vendor/pi-subagents/src/agents.ts) applies policy via [`.pi/lib/agents-policy`](../../../lib/agents-policy.ts) (same loader as AGT and verify).
+3. **AGT** — `createAgtPolicyEngine({ packageRoot, projectRoot })` loads package `.pi/harness/policies/` then project `.pi/policies/`. `tool_allowed` comes only from agents-policy; remove `subagent_policy_block` / delete `harness-subagent-policy.ts`.
+4. **Subprocess scope** — `subprocessGovernanceExtensionPath` loads governance for **all** subagents when `isAgtGovernanceActive(projectRoot)`; parent `policy-gate` AGT only during harness sessions (`isHarnessProjectEnabled()` + harness flow).
+5. **Submit registry** — implementation only (schema + artifact paths); allowlists live in `agents.policy.yaml`.
+6. **Verify** — extend [`harness-agents-manifest.mjs`](../../../scripts/harness-agents-manifest.mjs) for policy↔manifest alignment.
+
+## Consequences
+
+### Positive
+
+- One edit surface per agent capability; project extensions without forking harness.
+- Integrity manifest unchanged; supply-chain and policy concerns separated.
+
+### Negative / trade-offs
+
+- Vendored pi-subagents delta must be preserved on `npm run vendor:sync-subagents`.
+- Agents without policy entry fail closed in subprocess (doctor requires entries for spawnable project agents).
+
+## References
+
+- [ADR 0046](0046-agt-policy-engine.md)
+- [ADR 0048](0048-tool-call-hook-order.md)
+- [ADR 0037](0037-subagent-submit-tools.md)

package/.pi/harness/docs/adrs/0050-agentic-web-retrieval-stack.md

@@ -0,0 +1,46 @@
+# ADR 0050: Agentic Web Retrieval Stack (WRS)
+
+- **Status:** Accepted
+- **Date:** 2026-05-26
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+Harness agents treated `web_search` as single-query SERP, yielding poor recall on ambiguous research questions. Exa-style outcomes (multi-angle discovery, fusion, evidence, synthesis) are needed without Exa API, MCP, or a neural index at Exa scale.
+
+## Decision
+
+Introduce **WRS** as the default non-API web layer:
+
+1. **Tiers** on `web_search`: `instant`, `standard`, **`deep`** (default for research), `research`.
+2. **Planning subagents** under `.pi/agents/harness/web-retrieval/` — e.g. `harness/web-retrieval/web-query-expander` produces `.web/angles.yaml`; parent runs `web_search(tier=deep, anglesFile=…)`.
+3. **Python fusion**: parallel metasearch per angle (DDG HTML or SearXNG) + RRF (`k=60`) + optional lexical rerank.
+4. **Extension tools**: `web_find_similar`, `web_contents`, `web_fetch` highlights.
+5. **Synthesis subagents** (same directory): `web-answerer`, `web-gap-analyzer`, `web-criteria-verifier`, `web-summarizer`, `web-query-expander-fast`.
+6. **web-retrieval** skill as canonical workflow; **SYSTEM.md** mandates deep default and anti-patterns.
+7. **context7** remains sole path for library API documentation.
+8. **User model routing:** env vars `HARNESS_WEB_FAST_MODEL`, `HARNESS_WEB_EXPANDER_MODEL`, `HARNESS_WEB_QUALITY_MODEL` (any Pi `provider/model-id`); else parent session or agent `model:` override.
+9. **Pooled local cache:** `.web/cache/` keyed by search/fetch context with TTL (`HARNESS_WEB_CACHE_TTL_SEC`); workspace aliases under `.web/`. Optional `HARNESS_WEB_ISOLATE=1` for per-run/session dirs.
+
+Subagents are **not** spawned inside tool `execute()`; parent orchestrates expander → deep → fetch.
+
+## Consequences
+
+### Positive
+
+- Higher recall on landscape / prior-art questions without paid search APIs.
+- Path-first `.web/` artifacts for harness-plan debate.
+- Contract checks in `harness-verify.mjs` keep guidance aligned with tools.
+
+### Negative / trade-offs
+
+- Deep search is slower (N parallel SERP calls).
+- Heuristic `--expand-heuristic` is weaker than expander subagent (templates from mergeable `.pi/harness/web-heuristic-angles.yaml`; projects extend via same path under their repo).
+- No embedding index; O3 precision is approximate vs Exa neural search.
+
+## References
+
+- `.pi/harness/docs/harness-web-search.md`
+- `.agents/skills/web-retrieval/SKILL.md`
+- `.pi/extensions/harness-web-tools.ts`
+- Plan: `.cursor/plans/exa-style_harness_web_fd231183.plan.md`

package/.pi/harness/docs/adrs/README.md

@@ -26,11 +26,16 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0038](0038-budget-telemetry-only.md) | Budget caps telemetry-only by default | Accepted |
 | [0039](0039-harness-post-run-review-gate.md) | `/harness-review` master post-run gate | Accepted |
 | [0040](0040-practice-grounded-orchestration.md) | Practice-grounded orchestration & team topology | Accepted |
+| [0045](0045-harness-lens-minimal-contract.md) | Harness-lens minimal contract (edit safety, LSP, deferred format) | Accepted |
 | [0041](0041-intelligent-planning-reconnaissance.md) | Intelligent planning reconnaissance (tools over tool-scouts) | Accepted |
 | [0042](0042-agent-native-orchestration.md) | Agent-native orchestration (lakes, plan-verify probes, synthesizer) | Accepted |
 | [0043](0043-path-first-harness-tools.md) | Path-first harness tool contracts | Accepted |
 | [0044](0044-harness-steer-loop.md) | Post-run steer loop (repair vs plan revise) | Accepted |
 | [0045](0045-phase-scoped-agent-directories.md) | Phase-scoped harness agent directories | Accepted |
+| [0046](0046-agt-policy-engine.md) | AGT policy engine + subagent identity | Accepted |
+| [0047](0047-agt-layered-security.md) | AGT layered security (rings, prompt defense, CI) | Accepted |
+| [0048](0048-tool-call-hook-order.md) | tool_call hook interaction matrix | Accepted |
+| [0049](0049-agents-policy-manifest.md) | agents.policy.yaml SSOT + native discovery | Accepted |
 
 ## Practice map
 

package/.pi/harness/docs/harness-web-search.md

@@ -0,0 +1,97 @@
+# Harness Web Retrieval Stack (WRS)
+
+Internal reference for multi-angle search, fusion, and agent workflows. User-facing procedures: **web-retrieval** skill (install + env).
+
+## Outcomes (Exa analog)
+
+| Outcome | Primitive |
+|---------|-----------|
+| Discovery / recall | `search-deep` + RRF |
+| Precision | Multi-angle + optional `HARNESS_WEB_RERANK=lexical` |
+| Evidence / highlights | `web_fetch(highlights)` |
+| Similar pages | `find-similar` CLI / `web_find_similar` |
+| Synthesis | `evidence-bundle` + `web-answerer` |
+
+## CLI
+
+```bash
+python3 .pi/scripts/harness-web.py search-deep "query" \
+  --angles-file .web/angles.yaml -o .web/search-deep.json
+python3 .pi/scripts/harness-web.py search-deep "query" --expand-heuristic -o .web/search-deep.json
+python3 .pi/scripts/harness-web.py find-similar "https://example.com" -o .web/search-deep.json
+python3 .pi/scripts/harness-web.py contents-batch --from-search .web/search-deep.json -o .web/contents/
+```
+
+## Python modules
+
+- `harness_web/query_angles.py` — parse expander YAML
+- `harness_web/multi_search.py` — parallel per-angle SERP
+- `harness_web/rank.py` — normalize URL, RRF, lexical rerank
+- `harness_web/deep_search.py` — orchestration
+- `harness_web/highlights.py` — excerpt scoring
+- `harness_web/evidence_bundle.py` — merge for answerer
+
+## Artifacts
+
+**Cache** (pooled): `.web/cache/<kind>/<cacheKey>/` with `meta.json` (search context, `createdAt`, `expiresAt`, `hitCount`).
+
+**Workspace** (default `.web/`): tool aliases agents read. `web_search` / `web_fetch` set `cacheHit`, `cacheKey`, `cachePath` in details.
+
+| Env / param | Effect |
+|-------------|--------|
+| `HARNESS_WEB_CACHE_TTL_SEC` | Default TTL (86400) |
+| `HARNESS_WEB_CACHE=0` | Disable cache |
+| `refreshCache: true` | Bypass cache |
+| `cacheMaxAge` | Max reuse age (seconds) |
+| `HARNESS_WEB_ISOLATE=1` | Per-run/session dirs (legacy) |
+
+| File | Content |
+|------|---------|
+| `angles.yaml` | Expander output |
+| `search-deep.json` | Fused SERP + scores + `angle_ids` |
+| `evidence-bundle.json` | URLs + snippets + highlights |
+| `answer.md` | Cited synthesis |
+
+## Subagents (`.pi/agents/harness/web-retrieval/`)
+
+| Spawn id | Role |
+|----------|------|
+| `harness/web-retrieval/web-query-expander` | Angles YAML (default research) |
+| `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 angles config (user-extensible)
+
+Emergency templates for `expandHeuristic:true` / `--expand-heuristic` load from YAML:
+
+| File | Role |
+|------|------|
+| `<package>/.pi/harness/web-heuristic-angles.yaml` | Built-in defaults (code → github, stackoverflow, …) |
+| `<project>/.pi/harness/web-heuristic-angles.yaml` | **Your** extensions (merged on top) |
+
+Copy [examples/web-heuristic-angles.project.yaml](../examples/web-heuristic-angles.project.yaml) into an external project’s `.pi/harness/` to add sites per category or define new categories (use `category` on `web_search`).
+
+Query templates use `{query}` as the user search string. Same `id` in a category replaces the package angle.
+
+Optional: `HARNESS_WEB_HEURISTIC_ANGLES_FILE=/path/to/custom.yaml` (merged last).
+
+## Environment
+
+| Variable | Default |
+|----------|---------|
+| `HARNESS_WEB_SEARCH_ENGINE` | `ddg_html` |
+| `HARNESS_WEB_DEEP_CONCURRENCY` | `4` |
+| `HARNESS_WEB_RERANK` | `off` |
+| `HARNESS_WEB_FAST_MODEL` | expander-fast, summarizer, gap-analyzer |
+| `HARNESS_WEB_EXPANDER_MODEL` | full query expander |
+| `HARNESS_WEB_QUALITY_MODEL` | answerer, criteria-verifier |
+| `HARNESS_WEB_HEURISTIC_ANGLES_FILE` | Extra heuristic angles YAML (merged last) |
+| `HARNESS_PROJECT_ROOT` | Project root for `.pi/harness/web-heuristic-angles.yaml` |
+| `HARNESS_PKG_ROOT` | Package root for default heuristic YAML |
+
+Values use Pi `provider/model-id` format (any provider your install supports). Unset → subagent inherits parent session model. See **web-retrieval** skill.
+
+ADR: [0050-web-retrieval-retrieval-stack.md](adrs/0050-web-retrieval-retrieval-stack.md)

package/.pi/harness/env.harness.template

@@ -13,6 +13,15 @@ HARNESS_WEB_SEARCH_ENGINE=ddg_html
 # HARNESS_WEB_PROXY=
 # HARNESS_WEB_RATE_LIMIT_MS=2000
 # HARNESS_WEB_TIMEOUT_MS=30000
+# Heuristic angles (--expand-heuristic): edit <project>/.pi/harness/web-heuristic-angles.yaml
+# Optional override path (merged after package + project):
+# HARNESS_WEB_HEURISTIC_ANGLES_FILE=
+# Pooled WRS cache (Firecrawl-style freshness); workspace aliases under .web/
+# HARNESS_WEB_CACHE_TTL_SEC=86400
+# HARNESS_WEB_CACHE=0
+# HARNESS_WEB_ISOLATE=1
+# HARNESS_PROJECT_ROOT=
+# HARNESS_PKG_ROOT=
 
 # --- VCC compaction (env-only; no JSON config files) ---
 # Default: VCC handles /compact and auto-compaction. Set false for Pi LLM compaction:
@@ -21,7 +30,6 @@ HARNESS_WEB_SEARCH_ENGINE=ddg_html
 
 # --- PostHog (optional) ---
 # Project key — required for harness_* telemetry when HARNESS_TELEMETRY_ENABLED=true
-# WSL2: ultimate-pi loads 00-posthog-network-bootstrap.ts (IPv4 fetch for *.posthog.com).
 # If flush still fails, set POSTHOG_ENABLED=false or fix outbound HTTPS to PostHog.
 # POSTHOG_API_KEY=
 # POSTHOG_HOST=https://us.i.posthog.com

package/.pi/harness/evolution/README.md

@@ -1,11 +1,10 @@
 # Harness evolution (Phase 3)
 
-Self-healing and meta-optimization read **JSONL first** (`.pi/harness/runs/*/events.jsonl`), not PostHog.
+Self-healing reads **JSONL first** (`.pi/harness/runs/*/events.jsonl`), not PostHog.
 
 ## Components
 
 - `self-healing-rules.json` — pattern → suggested remediation
-- `meta-optimizer.mjs` — scans run index, proposes router/tuning deltas; run `node "$UP_PKG/.pi/harness/evolution/meta-optimizer.mjs"` (see `.pi/scripts/README.md`).
 - `chaos-drill.md` — manual chaos / failure injection checklist
 
 PostHog `harness_*` events are for dashboards; JSONL is the optimization source of truth per ADR 0008.

package/.pi/harness/examples/agents.policy.project.yaml

@@ -0,0 +1,19 @@
+# Example project override — copy to <project>/.pi/agents.policy.yaml
+# Merges on top of package .pi/harness/agents.policy.yaml (same agent ids win on project keys).
+
+apiVersion: harness.toolkit/v1
+
+agents:
+  my-custom-scout:
+    kind: planner
+    tools_add:
+      - web_search
+      - web_fetch
+    extensions: false
+    max_turns: 12
+
+  my-custom-runner:
+    kind: executor
+    tools_add:
+      - submit_executor_handoff
+    extensions: true

package/.pi/harness/examples/policies/custom-deny-bash.yaml

@@ -0,0 +1,9 @@
+# Example project AGT rule — copy to <project>/.pi/policies/custom-deny-bash.yaml
+# Loaded after package .pi/harness/policies/*.yaml when createAgtPolicyEngine runs.
+
+policies:
+  - name: deny-rm-rf-in-subagents
+    description: Block recursive rm -rf in subprocess tool calls
+    effect: deny
+    priority: 200
+    condition: is_subprocess == true && tool_name == "bash" && contains(tool_input.command, "rm -rf")

package/.pi/harness/examples/web-heuristic-angles.project.yaml

@@ -0,0 +1,22 @@
+# Example project extension — copy to:
+#   <your-project>/.pi/harness/web-heuristic-angles.yaml
+#
+# Merges on top of package .pi/harness/web-heuristic-angles.yaml.
+# Same angle id in a category replaces the package entry; new ids append.
+
+version: 1
+
+categories:
+  code:
+    # Add Rust-specific angles (keeps github + stackoverflow from package defaults)
+    - id: docs_rs
+      query: "{query} site:docs.rs"
+      rationale: Official Rust API docs
+    - id: crates_io
+      query: "{query} site:crates.io"
+      rationale: Crate ecosystem
+  # Package already ships category=security; extend or override ids here:
+  # security:
+  #   - id: cisa_kev
+  #     query: "{query} site:cisa.gov/known-exploited-vulnerabilities"
+  #     rationale: CISA KEV catalog

package/.pi/harness/policies/bash-denylists.yaml

@@ -0,0 +1,5 @@
+apiVersion: governance.toolkit/v1
+name: harness-bash-denylists
+description: Planning scout bash patterns (precomputed in context).
+default_action: allow
+rules: []

package/.pi/harness/policies/defaults.yaml

@@ -0,0 +1,51 @@
+apiVersion: governance.toolkit/v1
+name: harness-defaults
+description: Fail-closed default; explicit allow when no harness blocks fire.
+default_action: deny
+rules:
+  - name: deny-abort-mutation
+    priority: 2000
+    ruleAction: deny
+    condition: abort_mutating_block == true
+    description: harness-abort lock blocks mutating tools
+  - name: deny-plan-mutation
+    priority: 1900
+    ruleAction: deny
+    condition: plan_mutation_block == true
+  - name: deny-context-mode
+    priority: 1800
+    ruleAction: deny
+    condition: context_mode_block == true
+  - name: deny-tool-not-in-manifest
+    priority: 1700
+    ruleAction: deny
+    condition: tool_allowed == false
+    description: tool not allowed by agents.policy.yaml for this agent
+  - name: deny-spawn-policy
+    priority: 1650
+    ruleAction: deny
+    condition: spawn_policy_block == true
+  - name: deny-mutating-bash-phase
+    priority: 1600
+    ruleAction: deny
+    condition: mutating_bash_phase_block == true
+  - name: deny-eval-plan-packet-write
+    priority: 1550
+    ruleAction: deny
+    condition: eval_plan_packet_write_block == true
+  - name: deny-bash-web-bypass
+    priority: 1500
+    ruleAction: deny
+    condition: bash_web_block == true
+  - name: deny-bash-planning-heavy
+    priority: 1450
+    ruleAction: deny
+    condition: bash_planning_deny == true
+  - name: deny-bash-planning-json-artifact
+    priority: 1440
+    ruleAction: deny
+    condition: bash_planning_json_block == true
+  - name: allow-no-blocks
+    priority: 100
+    ruleAction: allow
+    condition: abort_mutating_block == false and plan_mutation_block == false and context_mode_block == false and tool_allowed == true and spawn_policy_block == false and mutating_bash_phase_block == false and eval_plan_packet_write_block == false and bash_web_block == false and bash_planning_deny == false and bash_planning_json_block == false

package/.pi/harness/policies/orchestrator.yaml

@@ -0,0 +1,18 @@
+apiVersion: governance.toolkit/v1
+name: harness-orchestrator
+description: Parent orchestrator submit_* and plan tools.
+default_action: allow
+rules:
+  - name: deny-parent-submit
+    priority: 2100
+    ruleAction: deny
+    condition: is_parent_orchestrator == true and is_submit_tool == true
+    description: submit_* is subprocess-only
+  - name: deny-subprocess-create-plan
+    priority: 2050
+    ruleAction: deny
+    condition: is_subprocess == true and tool_name == 'create_plan'
+  - name: deny-subprocess-approve-plan
+    priority: 2050
+    ruleAction: deny
+    condition: is_subprocess == true and tool_name == 'approve_plan'

package/.pi/harness/policies/phases.yaml

@@ -0,0 +1,10 @@
+apiVersion: governance.toolkit/v1
+name: harness-phases
+description: Phase hints for workflow (enforced via precomputed flags in defaults).
+default_action: allow
+rules:
+  - name: phase-metadata-plan
+    priority: 1
+    ruleAction: log
+    condition: harness_phase == 'plan'
+    description: informational only

package/.pi/harness/policies/roles.yaml

@@ -0,0 +1,5 @@
+apiVersion: governance.toolkit/v1
+name: harness-roles
+description: Role matrix enforced via subagent_policy_block precompute.
+default_action: allow
+rules: []

package/.pi/harness/policies/web-guard.yaml

@@ -0,0 +1,5 @@
+apiVersion: governance.toolkit/v1
+name: harness-web-guard
+description: Web fetch bypass blocks (precomputed bash_web_block).
+default_action: allow
+rules: []

package/.pi/harness/policies/workflow-sequences.yaml

@@ -0,0 +1,9 @@
+apiVersion: governance.toolkit/v1
+name: harness-workflow-sequences
+description: Multi-step workflow gates (observation-bus flags); extend as needed.
+default_action: allow
+rules:
+  - name: log-execute-phase
+    priority: 1
+    ruleAction: log
+    condition: harness_phase == 'execute'

package/.pi/harness/sentrux/architecture.manifest.json

@@ -16,9 +16,15 @@
 		},
 		{
 			"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,
-			"description": "Harness schemas, ADRs, and governance docs"
+			"description": "Harness schemas, ADRs, AGT policies, and agents.policy SSOT"
 		},
 		{
 			"name": "runtime",
@@ -39,9 +45,15 @@
 		},
 		{
 			"name": "tooling",
-			"paths": [".pi/scripts/*", "test/*"],
+			"paths": [".pi/scripts/*"],
 			"order": 4,
-			"description": "Harness CLI scripts and tests"
+			"description": "Harness CLI scripts"
+		},
+		{
+			"name": "foundation",
+			"paths": [".pi/lib/*"],
+			"order": 5,
+			"description": "Shared harness/AGT libraries (imported by extensions and scripts)"
 		}
 	],
 	"boundaries": [
@@ -65,6 +77,16 @@
 			"to": ".pi/extensions/*",
 			"reason": "Contracts are data-only JSON schemas; extensions implement behavior"
 		},
+		{
+			"from": ".pi/lib/*",
+			"to": ".pi/extensions/*",
+			"reason": "Foundation lib must not import extension modules"
+		},
+		{
+			"from": ".pi/harness/policies/*",
+			"to": ".pi/extensions/*",
+			"reason": "Declarative AGT YAML must not depend on extension implementation"
+		},
 		{
 			"from": ".pi/scripts/*",
 			"to": ".agents/skills/*",

package/.pi/harness/specs/observation.schema.json

@@ -37,7 +37,8 @@
 				"drift-monitor",
 				"sentrux",
 				"evaluator",
-				"harness-telemetry"
+				"harness-telemetry",
+				"agt-policy"
 			]
 		},
 		"kind": {