ultimate-pi 0.18.0 → 0.19.0

package/.pi/harness/docs/adrs/0045-phase-scoped-agent-directories.md

@@ -0,0 +1,33 @@
+# ADR 0045: Phase-scoped harness agent directories
+
+Status: Accepted
+Date: 2026-05-24
+
+## Context
+
+Harness prompts had accumulated mixed agent ids such as `harness/executor`, `harness/evaluator`, and legacy planning `scout-*` agents. The current orchestration model is phase-scoped:
+
+- planning context is parent-led or handled by `harness/planning/planning-context`
+- execution is a single running agent
+- post-run review is handled by reviewing agents
+
+Flat run/review agent ids made prompt intent less obvious and left legacy planning scout agents discoverable even after ADR 0041 moved reconnaissance to parent tool use plus `planning-context.yaml`.
+
+## Decision
+
+Use phase-scoped agent directories and ids for run/review orchestration:
+
+- `.pi/agents/harness/running/executor.md` → `harness/running/executor`
+- `.pi/agents/harness/reviewing/evaluator.md` → `harness/reviewing/evaluator`
+- `.pi/agents/harness/reviewing/adversary.md` → `harness/reviewing/adversary`
+- `.pi/agents/harness/reviewing/tie-breaker.md` → `harness/reviewing/tie-breaker`
+
+Remove the legacy planning `scout-graphify`, `scout-structure`, and `scout-semantic` agents. Planning reconnaissance is represented by `artifacts/planning-context.yaml` only.
+
+## Consequences
+
+- `/harness-run` must spawn only `harness/running/executor`.
+- `/harness-review` must spawn only agents under `harness/reviewing/`.
+- Submit-tool allowlists, precheck/topology policy, review-integrity policy, tests, and `agents.manifest.json` track the new ids.
+- When post-run review records `next_recommended_command: "/harness-plan (mode: revise)"`, review-integrity treats `harness/planning/*` subagents as a phase handoff, not a review-isolation violation.
+- Old scout YAML artifacts no longer satisfy plan approval readiness; `artifacts/planning-context.yaml` is required unless explicitly waived.

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/README.md

@@ -26,10 +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/graphify-kb-updater-runbook.md

@@ -6,7 +6,8 @@
 
 The approved operating model is **hybrid allowlist auto-promotion with conservative staging**:
 
-- Daily local automation may auto-promote only explicitly approved allowlisted public sources with complete provenance and rights/access metadata.
+- Daily local automation may auto-promote only explicitly approved allowlisted public sources (`article`, `repo`, or `release`) with complete provenance and rights/access metadata.
+- Repository and release candidates are metadata-specific source classes; they do not inherit generic article behavior and must be authorized by `allowed_source_classes` on the allowlist entry.
 - Books, transcripts, YouTube/video material, paid/copyrighted/mirrored material, unclear-license content, and unknown open-web sources remain staged until manually approved.
 - Competitor monitoring is a curated taxonomy/watchlist/reporting signal, not an exhaustive crawler.
 - Pi-agent-open integration is intentionally limited/deferred: opening Pi should do at most a low-latency, no-network stale check. It must not perform synchronous web discovery, promotion, or Graphify mutation.
@@ -24,9 +25,11 @@ Allowlist auto-promotion requires all of the following:
 
 1. `.pi/harness/corpus/graphify-kb-updater.config.json` has `auto_promote_allowlist: true`.
 2. The candidate domain is present in `allowlist` with `approved: true`.
-3. The candidate itself has `approved: true`.
-4. `rights_access` is complete.
-5. The candidate is not a risky source class that requires manual review.
+3. If the allowlist entry has `allowed_source_classes`, it includes the candidate `kind` (`article`, `repo`, or `release`).
+4. The candidate itself has `approved: true`.
+5. `provenance.origin` and `provenance.locator` are complete.
+6. `rights_access` is complete.
+7. The candidate is not a risky source class that requires manual review.
 
 Risky source classes (`book`, `transcript`, `youtube`) always require explicit approval and complete rights/access metadata. Raw HTTP shell paths are forbidden; keep discovery/fetch through approved harness web/API abstractions and verify with `.pi/scripts/harness-web-policy-guard.mjs`.
 
@@ -66,12 +69,13 @@ node .pi/scripts/harness-web-policy-guard.mjs
 
 1. Review dry-run JSON: candidate count, source counts, competitor labels, duplicate/skipped/blocked counts, stale warnings, planned promotions, and graph action.
 2. For a candidate, add it to `.pi/harness/corpus/graphify-kb-updater.config.json` `review_queue` with:
-   - `kind` (`article`, `paper`, `book`, `transcript`, or `youtube`)
+   - `kind` (`article`, `repo`, `release`, `paper`, `book`, `transcript`, or `youtube`)
    - `title`
    - `url` or `path`
    - `approved: true`
    - `rights_access` object with all required fields
    - optional `competitor_labels` or provenance notes.
+   - for repo/release auto-promotion, an allowlist entry whose `allowed_source_classes` includes `repo` or `release`.
 3. For local files, you may place `<file>.rights.json` beside the source, but risky classes still require explicit approval before promotion.
 4. Run `--apply --refresh-graph`.
 5. Promoted sources land under `raw/graphify-kb-updates/<kind>/` with `.provenance.json` sidecars.
@@ -108,6 +112,7 @@ Each run reports:
 - `last_run_at`
 - `candidate_count`, `promoted_count`, `blocked_count`, `skipped_count`, `duplicate_skips`, `failure_count`
 - `counts.by_kind`, `counts.by_source_type`, `counts.by_competitor_label`, `counts.allowlisted`
+- `staged_count`, `review_queue_count`, and `review_queue` items with reason codes and next actions
 - `stale_warnings`
 - `changed_existing_count` for same URL/path content changes
 - `graph.action`, `graph.exit_status`, and Graphify report path when refreshed
@@ -117,6 +122,7 @@ Review these fields before enabling unattended mode and after every config chang
 
 ## Troubleshooting
 
+- `missing_complete_provenance`: add `provenance.origin` and `provenance.locator`.
 - `missing_rights_access_approval`: add complete rights/access metadata.
 - `manual_approval_required`: set `approved: true` after source and rights review.
 - `duplicate_unchanged`: candidate was already promoted and content hash is unchanged.

package/.pi/harness/docs/practice-map.md

@@ -70,7 +70,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 |------|----------|-------------------|-------|
 | Gate | Change control | `plan_ready` required | Parent |
 | Pre-work | Fitness baseline | `sentrux gate --save` | Parent |
-| Work | Single implementer | `executor_strategy` | `harness/executor` |
+| Work | Single implementer | `executor_strategy` | `harness/running/executor` |
 | Post-work | Observation | `sentrux check` / signal artifact | Parent |
 | Handoff | Generator–evaluator | `submit_executor_handoff` | Executor |
 | Next | Always verify | **`/harness-review`** (not replan on blocked) | Parent routing |
@@ -95,7 +95,7 @@ See also: [ADRs](adrs/README.md), [ADR 0040](adrs/0040-practice-grounded-orchest
 |------|----------|-------|
 | 0 | Read review + repair briefs | Parent |
 | 1 | Policy phase → `execute` | Parent |
-| 2 | Repair scope | `harness/executor` `mode: repair` |
+| 2 | Repair scope | `harness/running/executor` `mode: repair` |
 | 3 | Re-verify | `/harness-review` |
 
 ## Anti-patterns

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/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/harness-spawn-context.schema.json

@@ -14,7 +14,7 @@
 		"agent": {
 			"type": "string",
 			"minLength": 1,
-			"description": "Target subagent id, e.g. harness/planning/scout-graphify"
+			"description": "Target subagent id, e.g. harness/running/executor"
 		},
 		"mode": {
 			"type": "string",

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

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

package/.pi/lib/agents-policy.d.mts

@@ -0,0 +1,70 @@
+export function packageAgentsPolicyPath(packageRoot: string): string;
+export function projectAgentsPolicyPath(projectRoot: string): string;
+export function projectPoliciesDir(projectRoot: string): string;
+
+export interface AgentPolicySpec {
+	kind: string;
+	effectiveTools: string[];
+	extensionsOff: boolean;
+	readOnly: boolean;
+	maxTurns?: number;
+	thinking?: string;
+	submitTool?: string;
+}
+
+export interface AllowsAgentToolInput {
+	packageRoot: string;
+	projectRoot: string;
+	agentId: string;
+	toolName: string;
+	toolInput?: Record<string, unknown>;
+	isSubprocess?: boolean;
+	isParentOrchestrator?: boolean;
+}
+
+export function loadAgentsPolicyMerged(
+	packageRoot: string,
+	projectRoot: string,
+): {
+	schemaVersion: string;
+	kinds: Map<string, unknown>;
+	agents: Map<string, unknown>;
+	defaults: unknown;
+};
+
+export function resolveEffectiveTools(
+	agentId: string,
+	merged: ReturnType<typeof loadAgentsPolicyMerged>,
+): AgentPolicySpec;
+
+export function getAgentPolicySpec(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): AgentPolicySpec | null;
+
+export function getAgentKind(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): string;
+
+export function isHarnessPlanningAgent(agentId: string): boolean;
+
+export function harnessSubagentPhaseHint(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): string | null;
+
+export function allowsAgentTool(input: AllowsAgentToolInput): boolean;
+
+export function applyAgentPolicyToConfig<T extends { name: string }>(
+	agent: T,
+	packageRoot: string,
+	projectRoot: string,
+): T;
+
+export function findProjectRootFromAgentsDir(projectAgentsDir: string): string;
+
+export function isAgtGovernanceActive(projectRoot: string): boolean;