ultimate-pi 0.18.1 → 0.19.0

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

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

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

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

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

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

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

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

package/.sentrux/rules.toml

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

package/AGENTS.md

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

package/CHANGELOG.md

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

package/README.md

@@ -64,7 +64,7 @@ If `/harness-review` returns `implementation_gap`, run:
 
 | Command | Purpose |
 |---|---|
-| `/harness-setup [--skip-graphify] [--skip-tools] [--non-interactive] [--force]` | Idempotent project bootstrap: Graphify, harness-web/Scrapling, CLI tools, settings, contracts, Sentrux, model router, and verification. |
+| `/harness-setup [--skip-graphify] [--skip-tools] [--non-interactive] [--force]` | Idempotent project bootstrap: Graphify, harness-web/Scrapling, CLI tools, settings, contracts, Sentrux, harness lens, and verification. |
 | `/harness-auto "<task>" [--quick] [--risk low\|med\|high]` | Strict full pipeline: plan, execute, review, steer when appropriate. |
 | `/harness-plan "<task>" [--risk low\|med\|high] [--quick]` | PM-grade planning: reconnaissance, decomposition, hypothesis, external research, ExecutionPlan, DAG validation, Review Gate debate, `approve_plan`, `create_plan`. |
 | `/harness-run` | Executes the approved active PlanPacket by spawning `harness/running/executor`; no inline implementation. |
@@ -74,19 +74,11 @@ If `/harness-review` returns `implementation_gap`, run:
 | `/harness-trace [--run <id>] [--phase plan\|execute\|evaluate\|adversary\|merge]` | Summarizes run traces and artifact handoffs for replay/forensics. |
 | `/harness-incident --trigger <reason> [--run <id>] [--severity low\|med\|high\|critical]` | Records incident, rollback, and override trail for harness failures. |
 | `/harness-sentrux-steward [--run <id>]` | Ad-hoc architectural intent review for Sentrux manifest/rule alignment. |
-| `/harness-router-tune --evidence <evidence.json> --candidate <candidate-router.json> [--proposal <out.json>]` | Proposes model-router updates from evidence; applies only after explicit approval. |
 | `/graphify [directory]` | Bootstraps or updates the Graphify knowledge graph. |
 | `/wiki-autoresearch [topic]` | Runs autonomous web research and builds a Graphify-backed research wiki. |
 | `/wiki-save` | Saves the current conversation or insight as a structured wiki note. |
 | `/release [patch\|minor\|major] [--dry-run]` | Maintainer release helper. |
 
-Deprecated compatibility aliases:
-
-| Alias | Use instead |
-|---|---|
-| `/harness-eval` | `/harness-review` |
-| `/harness-critic` | `/harness-review` |
-
 ## Harness phases and agents
 
 - **Planning** uses agents under `.pi/agents/harness/planning/` plus parent-led Graphify → `sg` → `ccc` reconnaissance. Legacy tool-tied `planning/scout-*` agents have been removed; planning context is captured in `artifacts/planning-context.yaml`.
@@ -116,8 +108,8 @@ Subagents run isolated from the parent session. They persist canonical YAML thro
 - **No inline execution:** `/harness-run` delegates to `harness/running/executor` only.
 - **No inline review:** `/harness-review` delegates verdicts to isolated reviewing agents.
 - **No auto-merge:** final merge remains a human/operator decision.
-- **Sentrux is observational:** structural baselines and gates inform review; executor does not optimize metrics as a goal.
-- **Router is gated:** `pi-model-router` activates after `/harness-setup` creates `.pi/model-router.json`; run `/reload` after setup or router changes.
+- **Sentrux is the architecture signal:** structural baselines and gates inform review; executor does not optimize metrics as a goal.
+- **pi-lens is edit-time diagnostics:** LSP/lint/format/ast feedback complements Sentrux and does not replace architecture gating.
 
 ## Troubleshooting
 
@@ -129,7 +121,6 @@ Subagents run isolated from the parent session. They persist canonical YAML thro
 | Need to restart safely | Run `/harness-abort [reason]`, then create a fresh plan. |
 | Review says `implementation_gap` | Run `/harness-steer`, then `/harness-review`. |
 | Review says `plan_gap` | Revise with `/harness-plan "<updated task>"`. |
-| Router profile missing | Complete `/harness-setup`, run `/reload`, then check `.pi/model-router.json`. |
 | Sentrux missing | Install/configure Sentrux or keep it skipped; harness verification still reports the status. |
 
 Optional integrations can be configured by copying `.env.example` to `.env`; `/harness-setup` appends missing keys without overwriting existing values.

package/THIRD_PARTY_NOTICES.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.18.1",
+	"version": "0.19.0",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -46,6 +46,7 @@
 		".pi/lib",
 		".pi/sounds",
 		".pi/harness/env.harness.template",
+		".pi/harness/policies",
 		".pi/harness/specs",
 		".pi/harness/docs",
 		".pi/harness/sentrux",
@@ -53,10 +54,12 @@
 		".pi/harness/evolution",
 		".pi/harness/corpus",
 		".pi/harness/agents.manifest.json",
+		".pi/harness/agents.policy.yaml",
+		".pi/harness/examples",
+		".pi/lib/harness-lens",
 		".pi/harness/README.md",
 		".pi/npm/package.json",
 		".pi/npm/.gitignore",
-		".pi/model-router.example.json",
 		".pi/settings.example.json",
 		".pi/auto-commit.json",
 		".pi/SYSTEM.md",
@@ -66,7 +69,6 @@
 		"CHANGELOG.md",
 		"README.md",
 		"THIRD_PARTY_NOTICES.md",
-		"vendor/pi-model-router",
 		"vendor/pi-subagents",
 		"vendor/pi-vcc"
 	],
@@ -74,8 +76,7 @@
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/00-harness-project-control.ts .pi/extensions/custom-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-context-mode-policy.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/00-posthog-network-bootstrap.ts .pi/extensions/lib/posthog-client.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/harness-plan-approval.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/lib/plan-approval/types.ts .pi/extensions/lib/plan-approval/schema.ts .pi/extensions/lib/plan-approval/validate.ts .pi/extensions/lib/plan-approval/format-plan.ts .pi/extensions/lib/plan-approval/dialog.ts .pi/extensions/lib/plan-approval/render.ts .pi/extensions/lib/plan-approval/create-plan.ts .pi/extensions/harness-subagents.ts .pi/extensions/lib/harness-subagents-bridge.ts .pi/extensions/lib/harness-cocoindex-refresh.ts .pi/extensions/lib/harness-subagent-auth.ts .pi/extensions/lib/harness-subagent-policy.ts .pi/extensions/lib/harness-subagent-precheck.ts .pi/extensions/lib/harness-spawn-budget.ts .pi/extensions/lib/spawn-policy.ts vendor/pi-subagents/src/agents.ts vendor/pi-subagents/src/subagents.ts .pi/extensions/review-integrity.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-debate-tools.ts .pi/extensions/lib/debate-bus-core.ts .pi/extensions/lib/debate-bus-state.ts .pi/extensions/lib/plan-debate-gate.ts .pi/extensions/lib/plan-debate-id.ts .pi/extensions/lib/plan-messenger.ts .pi/extensions/lib/plan-debate-envelope.ts .pi/extensions/lib/plan-review-integrator-rules.ts .pi/extensions/lib/plan-scope-guard.ts .pi/extensions/lib/plan-debate-write-guard.ts .pi/extensions/lib/plan-debate-lane.ts .pi/extensions/lib/plan-debate-round-status.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/extensions/lib/harness-web/run-cli.ts",
-		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/lib/agt/config.ts .pi/lib/agt/policy-engine.ts .pi/lib/agt/build-evaluation-context.ts .pi/lib/agt/evaluate-policy.ts .pi/lib/agt/legacy-evaluate.ts .pi/lib/agt/identity-registry.ts .pi/lib/agt/delegation.ts .pi/lib/agt/trust-run-store.ts .pi/lib/agt/audit-run-sink.ts .pi/lib/agt/rings.ts .pi/lib/agt/workflow-history.ts .pi/lib/agt/sre-hooks.ts .pi/lib/agt/kill-switch-state.ts .pi/lib/agt/index.ts .pi/extensions/agt-prompt-guard.ts .pi/extensions/agt-kill-switch.ts .pi/extensions/harness-subagent-governance.ts .pi/lib/harness-agt-tool-guard.ts .pi/lib/harness-subagent-submit-register.ts .pi/extensions/00-harness-project-control.ts .pi/extensions/custom-system-prompt.ts .pi/lib/harness-run-context.ts .pi/lib/harness-spawn-policy.ts .pi/lib/harness-context-mode-policy.ts .pi/lib/harness-ui-state.ts .pi/extensions/harness-run-context.ts .pi/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/00-posthog-network-bootstrap.ts .pi/lib/posthog-client.ts .pi/lib/posthog-node.d.ts .pi/lib/harness-posthog.ts .pi/lib/harness-paths.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/harness-plan-approval.ts .pi/lib/ask-user/schema.ts .pi/lib/ask-user/types.ts .pi/lib/ask-user/validate.ts .pi/lib/ask-user/dialog.ts .pi/lib/ask-user/fallback.ts .pi/lib/ask-user/render.ts .pi/lib/plan-approval/types.ts .pi/lib/plan-approval/schema.ts .pi/lib/plan-approval/validate.ts .pi/lib/plan-approval/format-plan.ts .pi/lib/plan-approval/dialog.ts .pi/lib/plan-approval/render.ts .pi/lib/plan-approval/create-plan.ts .pi/extensions/harness-subagents.ts .pi/lib/harness-subagents-bridge.ts .pi/lib/harness-cocoindex-refresh.ts .pi/lib/harness-subagent-auth.ts .pi/lib/agents-policy.ts .pi/lib/agt-governance-active.ts .pi/extensions/subagent-governance.ts .pi/lib/agt-tool-guard.ts .pi/lib/harness-subagent-precheck.ts .pi/lib/harness-spawn-budget.ts vendor/pi-subagents/src/agents.ts vendor/pi-subagents/src/subagents.ts .pi/extensions/review-integrity.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/policy-gate.ts .pi/extensions/budget-guard.ts .pi/extensions/debate-orchestrator.ts .pi/extensions/harness-debate-tools.ts .pi/lib/debate-bus-core.ts .pi/lib/debate-bus-state.ts .pi/lib/plan-debate-gate.ts .pi/lib/plan-debate-id.ts .pi/lib/plan-messenger.ts .pi/lib/plan-debate-envelope.ts .pi/lib/plan-review-integrator-rules.ts .pi/lib/plan-scope-guard.ts .pi/lib/plan-debate-write-guard.ts .pi/lib/plan-debate-lane.ts .pi/lib/plan-debate-round-status.ts .pi/extensions/harness-live-widget.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/harness-web-tools.ts .pi/extensions/harness-web-guard.ts .pi/lib/harness-web/run-cli.ts",
 		"vendor:sync-vcc": "bash .pi/scripts/vendor-sync-pi-vcc.sh",
 		"vendor:sync-subagents": "bash .pi/scripts/vendor-sync-pi-subagents.sh",
 		"release": "bash .pi/scripts/release.sh",
@@ -84,7 +85,7 @@
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/posthog-client.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/harness-vcc-settings.test.ts test/harness-run-context-postrun.test.mjs test/harness-tool-payload.test.mjs test/harness-live-widget-status.test.ts test/harness-project-toggle-tui.test.ts test/harness-plan-phase-policy.test.mjs test/harness-context-mode-policy.test.mjs test/harness-subprocess-bootstrap.test.mjs test/harness-subagent-policy.test.mjs test/harness-subagent-precheck-topology.test.mjs test/plan-approval-readiness.test.mjs test/harness-spawn-budget.test.mjs test/harness-spawn-parse.test.mjs test/harness-schema-validate.test.mjs test/harness-turn-routing.test.mjs test/harness-budget-enforce.test.mjs test/harness-submit-policy.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-debate-eligibility.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs test/review-integrity-revise-handoff.test.mjs test/harness-plan-revise-reset.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/harness-subagent-precheck.test.mjs test/sentrux-rules-sync.test.mjs test/harness-budget-guard.test.mjs && node .pi/harness/evals/smoke/smoke-harness-plan.mjs --fixture && npx -y tsx --test test/posthog-client.test.mjs test/harness-agt-policy-load.test.mjs test/harness-agt-policy-matrix.test.mjs test/harness-agt-policy-parity.test.mjs test/harness-agt-packaging.test.mjs test/harness-tool-call-hook-chain.test.mjs test/harness-vcc-settings.test.ts test/harness-run-context-postrun.test.mjs test/harness-tool-payload.test.mjs test/harness-live-widget-status.test.ts test/harness-project-toggle-tui.test.ts test/harness-plan-phase-policy.test.mjs test/harness-context-mode-policy.test.mjs test/harness-subprocess-bootstrap.test.mjs test/harness-subagent-policy.test.mjs test/harness-subagent-precheck-topology.test.mjs test/plan-approval-readiness.test.mjs test/harness-spawn-budget.test.mjs test/harness-spawn-parse.test.mjs test/harness-schema-validate.test.mjs test/harness-turn-routing.test.mjs test/harness-budget-enforce.test.mjs test/harness-submit-policy.test.mjs test/harness-project-agents-policy.test.mjs test/plan-approval-format.test.mjs test/plan-approval-dialog.test.mjs test/plan-approval-sync.test.mjs test/plan-create-plan.test.mjs test/plan-review-format.test.mjs test/debate-plan-phase.test.mjs test/plan-debate-eligibility.test.mjs test/plan-messenger-gate.test.mjs test/plan-debate-lane-apply.test.mjs test/review-integrity-revise-handoff.test.mjs test/harness-plan-revise-reset.test.mjs",
 		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
@@ -102,14 +103,21 @@
 		"yaml": "^2.8.0"
 	},
 	"dependencies": {
+		"@ast-grep/napi": "^0.42.2",
+		"@microsoft/agent-governance-sdk": "^3.7.0",
 		"@posthog/pi": "latest",
 		"ajv": "^8.17.1",
 		"ajv-formats": "^3.0.1",
 		"croner": "^9.0.0",
 		"jimp": "^1.6.1",
+		"minimatch": "^10.2.5",
 		"nanoid": "^5.1.5",
 		"posthog-node": "^5.30.6",
-		"undici": "^7.16.0"
+		"tree-sitter-wasms": "^0.1.13",
+		"typebox": "^1.1.38",
+		"undici": "^7.16.0",
+		"vscode-jsonrpc": "^8.2.1",
+		"web-tree-sitter": "^0.25.10"
 	},
 	"overrides": {
 		"@mariozechner/pi-agent-core": "npm:@earendil-works/pi-agent-core@0.74.1",

package/vendor/pi-subagents/src/agents.ts

@@ -3,6 +3,7 @@
  */
 
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
@@ -294,6 +295,42 @@ function resolvePackageAgentsDir(
 	return null;
 }
 
+function resolveProjectRootFromCwd(cwd: string): string {
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+	if (!projectAgentsDir) return cwd;
+	const piDir = path.dirname(projectAgentsDir);
+	return piDir.endsWith(`${path.sep}.pi`) ? path.dirname(piDir) : cwd;
+}
+
+type ApplyAgentPolicyFn = (
+	agent: AgentConfig,
+	packageRoot: string,
+	projectRoot: string,
+) => AgentConfig;
+
+let cachedApplyPolicy: ApplyAgentPolicyFn | null | undefined;
+
+function applyAgentsPolicyIfAvailable(
+	agent: AgentConfig,
+	packageRoot: string | undefined,
+	projectRoot: string,
+): AgentConfig {
+	if (!packageRoot) return agent;
+	if (cachedApplyPolicy === undefined) {
+		try {
+			const req = createRequire(path.join(packageRoot, "package.json"));
+			const mod = req("./.pi/lib/agents-policy.mjs") as {
+				applyAgentPolicyToConfig?: ApplyAgentPolicyFn;
+			};
+			cachedApplyPolicy = mod.applyAgentPolicyToConfig ?? null;
+		} catch {
+			cachedApplyPolicy = null;
+		}
+	}
+	if (!cachedApplyPolicy) return agent;
+	return cachedApplyPolicy(agent, packageRoot, projectRoot);
+}
+
 export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
@@ -316,6 +353,7 @@ export function discoverAgents(
 	}
 
 	const agentMap = new Map<string, AgentConfig>();
+	const projectRoot = resolveProjectRootFromCwd(cwd);
 
 	for (const agent of BUILT_IN_AGENTS) {
 		agentMap.set(agent.name, { ...agent });
@@ -331,7 +369,13 @@ export function discoverAgents(
 					? "project"
 					: "user";
 		const parsed = parseMarkdownAgent(id, file.content, source, file.filePath);
-		if (parsed) agentMap.set(parsed.name, parsed);
+		if (!parsed) continue;
+		const withPolicy = applyAgentsPolicyIfAvailable(
+			parsed,
+			packageRoot,
+			projectRoot,
+		);
+		agentMap.set(withPolicy.name, withPolicy);
 	}
 
 	return {