planr 1.8.0 → 1.10.0-alpha.1

package/README.md

@@ -2,7 +2,7 @@
 
 ![Planr — turn chaotic agent work into a verified task graph](public/planr_banner1.webp)
 
-Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, Grok Build, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
+Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, Grok Build, Pi, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
 
 [**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
 
@@ -53,7 +53,7 @@ curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/instal
 > On an affected Linux release, build from source on the target distribution or upgrade to v1.7.3.
 <!-- planr:linux-release-portability:end surface=README schema=1 -->
 
-Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin. Grok Build is a separate explicit opt-in and is not included by `all`:
+Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin. Grok Build and Pi are separate explicit opt-ins and are not included by `all`:
 
 ```bash
 planr project init "My Product" --client all
@@ -61,6 +61,16 @@ planr project init "My Product" --client all
 
 Manual downloads, from-source builds, and client wiring details: [Install Guide](https://planr.so/docs/getting-started/installation).
 
+To add Pi's native Agent Skills and optional pi-subagents roles to a trusted repository, select it explicitly:
+
+```bash
+planr install pi --dry-run
+planr install pi
+planr project init "My Product" --client pi
+```
+
+Planr writes repository-local `.pi/skills/` workflow assets and optional `.pi/agents/` roles only. It does not install Pi, pi-subagents, MCP config, hooks, global settings, provider credentials, or session state. Full setup and trust guidance: [Pi integration](https://planr.so/docs/integrations/pi).
+
 ## Install The Plugin (Skills)
 
 The plugin under `plugins/planr` carries the ten Planr workflow skills. Optional model-routing declarations live in repository-local files such as `.planr/agents.toml` and `.planr/policy.toml`; external tools may manage those files, but Planr does not install or invoke a routing engine. The `planr` CLI (above) is required separately.
@@ -123,6 +133,22 @@ Planr writes portable `.grok/config.toml` MCP configuration plus native `.grok/a
 
 </details>
 
+<a id="install-pi"></a>
+<details>
+<summary><strong>Pi</strong></summary>
+
+Preview or install the repository-local Pi integration:
+
+```bash
+planr install pi --dry-run
+planr install pi
+planr doctor --client pi --json
+```
+
+Planr writes native `.pi/skills/` workflow assets and optional `.pi/agents/` role files for `pi-subagents`. It writes no MCP configuration, hooks, extension package, global Pi settings, provider credentials, model pin, or session reference. Pi is intentionally explicit opt-in and is not part of `--client all`. See the [Pi integration guide](https://planr.so/docs/integrations/pi).
+
+</details>
+
 <a id="install-plugin-opencode"></a>
 <details>
 <summary><strong>opencode</strong></summary>
@@ -200,6 +226,7 @@ The watcher is likewise a human-only observer. It defaults to the condensed diag
 
 ## What's new
 
+- **1.9.0 — First-class Pi integration:** Added an explicit repository opt-in that installs native Pi Agent Skills plus optional `pi-subagents` worker/reviewer roles without treating Pi as an MCP host. The integration writes no Pi global settings, hooks, provider credentials, model pin, or session reference, and `--client all` remains unchanged for existing Codex, Claude Code, Cursor, and Grok setup. See the [Pi integration guide](https://planr.so/docs/integrations/pi), [Pi contract](docs/contracts/PI_INTEGRATION_V1.md), and [1.9.0 changelog](CHANGELOG.md#190---2026-07-27).
 - **1.8.0 — First-class Grok Build integration:** Added an explicit repository opt-in that installs portable project MCP configuration plus native Grok agents and all ten Planr workflow skills. The integration writes no plugin, hooks, model setting, xAI credentials, or provider runtime dependency; authenticated verification remains maintainer-local and never runs in CI. See the [Grok Build guide](https://planr.so/docs/integrations/grok-build) and [1.8.0 changelog](CHANGELOG.md#180---2026-07-27).
 - **1.7.2 — Reproducible release candidates:** Locked the pnpm workspace inventory, made external eval fixtures self-contained, refreshed reviewed workflow runtimes, and made all four published architectures execute the exact tagged version before upload. Model-backed evaluation remains a local, candidate-bound maintainer gate; this patch makes no unmeasured speed or quality claim. See the [1.7.2 changelog](CHANGELOG.md#172---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
 - **1.7.1 — Leaner agent guidance and safer local releases:** Slimmed the hot-path Planr skills while preserving their execution and review contracts, moved maintainer benchmark inputs and results outside the public repository, added a fail-closed local release-evidence gate without API keys in CI, and verified the optional external Switchloom v0.3.2 integration. The public 1.7 eval CLI remains available in this patch. See the [1.7.1 changelog](CHANGELOG.md#171---2026-07-25) and [release guidance](https://planr.so/docs/operations/release).
@@ -220,7 +247,7 @@ Full documentation lives at [planr.so/docs](https://planr.so/docs).
 - [Plugins and Model Routing](https://planr.so/docs/plugins) · [Recipes](https://planr.so/docs/guides/recipes)
 - [Integrations and Host Hooks](https://planr.so/docs/integrations)
 - [CLI Reference](https://planr.so/docs/reference/cli) · [MCP Reference](https://planr.so/docs/reference/mcp)
-- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor) · [Grok Build](https://planr.so/docs/integrations/grok-build)
+- [Codex](https://planr.so/docs/integrations/codex) · [Claude Code](https://planr.so/docs/integrations/claude-code) · [Cursor](https://planr.so/docs/integrations/cursor) · [Grok Build](https://planr.so/docs/integrations/grok-build) · [Pi](https://planr.so/docs/integrations/pi)
 - [Daily Worker Loop](https://planr.so/docs/guides/daily-worker-loop)
 - [Task Graph Model](https://planr.so/docs/concepts/graph-and-readiness)
 - [Architecture](https://planr.so/docs/contributing/architecture)

package/docs/RELEASE.md

@@ -24,25 +24,44 @@ full candidate verification and independent review on that exact commit.
 
 `scripts/release.sh` is the only supported publication path. It runs on clean
 `main`, requires every version and generated reference to already match the
-requested version, reruns the local eval and deterministic gates, and rejects
-any command that changes the reviewed source. Only then does it create and push
-the annotated tag. Editing manifests by hand or publishing an unprepared commit
-skips this ownership boundary.
+requested version, verifies an independently green CI run and human approval
+for the exact `HEAD` SHA, and only then creates and pushes the annotated tag.
+It does not replay the Rust, docs, or packaging suites already proven by that
+CI run. Security, secret, dependency, and workflow scanners are deliberate
+local maintainer preflight commands rather than automatic pull-request or push
+CI evidence. Editing manifests by hand or publishing an unprepared commit skips
+this ownership boundary.
 
 ```bash
 scripts/prepare-release-candidate.sh 1.2.0
 ```
 
+```bash
+export PLANR_RELEASE_CI_RECEIPT=/path/to/downloaded/promotion-receipt.json
+export PLANR_RELEASE_APPROVAL=/path/to/exact-sha-release-approval.json
+scripts/release.sh 1.2.0 "one-line release summary"
+```
+
+Download `release-promotion-<sha>` from the successful `CI` run for the exact
+main commit. The approval file uses schema `planr.release-approval.v1` and
+contains only `approval_id`, `source_sha`, `version`, `decision: "approved"`,
+`approved_by`, and `approved_at` in addition to `schema_version`. Publication
+queries the recorded GitHub Actions run and rejects a stale SHA, non-main or
+non-push run, failed conclusion, repository mismatch, or non-approved decision.
+
+External evaluation is conditional. When the evaluated workflow subject or its
+explicit evaluation policy changed since the previous release tag, also set:
+
 ```bash
 export PLANR_RELEASE_EVAL_SUITE="$HOME/projects/planr-evals/suites/planr-lean-skills-dogfood.suite.json"
 export PLANR_RELEASE_EVAL_RECEIPT=/path/to/sanitized-release-eval-receipt.json
 export PLANR_RELEASE_EVAL_DB=/path/to/planr-evals/results/eval.sqlite
-scripts/release.sh 1.2.0 "one-line release summary"
+export PLANR_RELEASE_PLANR_BIN=/path/to/reviewed/candidate/planr
 ```
 
 Maintainer benchmarks, baselines, model/effort runs, and results live outside
 the public repository in `~/projects/planr-evals`; that workspace and its exact
-layout are not a Planr runtime contract. All three paths above are explicit so a
+layout are not a Planr runtime contract. All external evaluation paths above are explicit so a
 release cannot silently use the product repository's ordinary `.planr` database
 or a stale bundled suite. The receipt is a short-lived local pointer containing
 only `schema_version`, comparison and candidate-run identities, suite and
@@ -76,7 +95,7 @@ The two scripts enforce, in order:
 4. the candidate build synchronizes `Cargo.lock`, then regenerates and strictly checks both references without Git mutation;
 5. candidate source, changelog, contracts, and generated files are committed and independently reviewed before publication approval;
 6. publication requires clean `main`, the exact prepared versions/references, a committed changelog section, and no existing tag;
-7. the candidate binary validates the sanitized receipt and recomputed comparison, then deterministic tests, package, and security gates run without changing source;
+7. publication validates the exact-SHA CI and approval receipts; when the evaluated subject or policy changed, the reviewed candidate binary also validates the sanitized eval receipt and recomputed comparison;
 8. publication creates and pushes only the annotated `vx.y.z` tag for that reviewed commit.
 
 Two independent gates back the script:
@@ -145,6 +164,11 @@ scripts/ci-local.sh
 scripts/security-local.sh
 ```
 
+`scripts/security-local.sh`, `cargo audit --deny warnings`, and local
+`zizmor .` are on-demand maintainer checks. Pull-request and push workflows do
+not install or execute BetterLeaks, Trivy, TruffleHog, cargo-audit, zizmor, or
+equivalent dependency/security scanners.
+
 The external consumer E2E suite must pass when available on the release machine.
 Pull-request CI separately builds both Linux architectures through the canonical
 containerized release script, runs the full portability contract without
@@ -164,6 +188,9 @@ cat dist/planr-*/SHA256SUMS
 The artifact contains:
 
 - `planr`
+- `scripts/host-capability-experiment.mjs`
+- `scripts/host-capability-runtime/v1/schemas/*.schema.json`
+- `scripts/planr-host-capability-validator`
 - `README.md`
 - `LICENSE.md`
 - `SHA256SUMS`
@@ -187,6 +214,9 @@ npm pack --dry-run
 The package must include:
 
 - `npm/bin/planr.js`
+- `scripts/host-capability-experiment.mjs`
+- `scripts/host-capability-runtime/v1/schemas/*.schema.json`
+- `scripts/planr-host-capability-validator`
 - `docs/`
 - `docs/fixtures/mcp-contract.json`
 - `plugins/`

package/docs/contracts/EVIDENCE_CONTRACT_V1.md

@@ -0,0 +1,283 @@
+# Evidence Contract v1
+
+Status: frozen for implementation
+
+Evidence Contract v1 is Planr's local-first contract for proving acceptance criteria. It defines the durable vocabulary for proof obligations, observation requirements, capability declarations, execution attempts, untrusted proposals, trusted receipts, coverage verdicts, policy, presets, waivers, statuses, compatibility, and extension naming. It does not add public commands by itself and does not grant closure authority until later implementation slices wire the contract into storage, audit, review, trace, pick, and active-goal enforcement.
+
+## Ownership
+
+- Product and build plans own authored acceptance criteria and the reviewed `ProofObligation` records bound to those criteria.
+- The Evidence domain owns `ProofObligation`, `ObservationRequirement`, `VerificationCapabilityManifest`, `VerificationCapabilityInstance`, `EvidenceAttempt`, `UntrustedEvidenceProposal`, `EvidenceReceipt`, `CoverageVerdict`, `EvidencePolicy`, `ProofPreset`, and `EvidenceWaiver`.
+- Planr assigns trusted provenance only from Planr-observed execution, verified host events, accepted MCP attestation, validated artifact import, or explicit approval-backed user attestation.
+- Public JSON, agent-authored JSON, adapter stdout, logs, and artifacts may propose claims, but they cannot construct trusted provenance, execution identity, freshness, target binding, receipt digest, or closure authority.
+- `src/canonical_json.rs` is the future single production owner for RFC 8785/JCS-compatible canonical bytes and SHA-256 digests used by this contract.
+- `src/execution.rs` is the future shared owner for bounded process execution, cancellation, process-tree cleanup, output limits, and stdout/stderr digests.
+- CLI, MCP, HTTP, docs, audit, hooks, review, trace, and pick surfaces are renderers or consumers. They must use the same Evidence application service and cannot implement alternate coverage decisions.
+
+## Existing-System Boundaries
+
+- Eval remains the owner of comparative candidate evaluation, immutable eval runs, case results, samples, comparisons, invalidations, and eval evidence references. Eval evidence keeps `closure_authority = false`; an eval verdict may support review but cannot close or reopen Planr work by itself.
+- Route Audit remains the owner of requested, resolved, and effective routing evidence. Evidence may consume a mapped provenance view, but it must not copy requested route declarations into effective execution proof.
+- Agent Profiles, model-routing capability classes, usage-policy capability classes, MCP protocol capabilities, and context tags are dispatch or protocol metadata. They are not verification capability instances and do not prove runtime availability.
+- Planr logs remain narrative and supporting records. A legacy `kind = verification` log is preserved as a claim and can be referenced, but it never automatically satisfies a binding observation.
+- Pre-Evidence plans and non-binding scopes keep their historical closure compatibility until an operator explicitly migrates a plan into binding Evidence. Migration is plan-scoped, previewable, idempotent, and materializes ordinary immutable `ProofObligation` rows; it must not rewrite plans, logs, reviews, artifacts, or historical claims.
+- Planr artifacts remain files or references with digests. An artifact alone is not trusted evidence unless a trusted receipt binds it to the source revision, target, environment, execution identity, observation results, and policy.
+
+## Versioning And Compatibility
+
+- `schema_version` for all v1 objects is `evidence.contract.v1`.
+- Additive optional fields are allowed only when old readers can ignore them without changing coverage, trust, freshness, or closure decisions.
+- Status enum values, failure reason codes, provenance source kinds, namespace rules, digest algorithms, and trusted/untrusted boundaries are frozen for v1.
+- Removing fields, renaming statuses, weakening required trust checks, changing digest semantics, or treating legacy logs as binding proof requires a new major contract.
+- Unknown object kinds, observation types, schema versions, status values, provenance kinds, or namespaces are invalid for trusted coverage unless an explicit project extension registers them.
+- Canonical JSON bytes and digests are computed over the object without non-contractual display fields. The frozen schema fixture in `docs/contracts/fixtures/evidence/v1/schemas/evidence-contract-v1.schema.json` names each object's required fields.
+
+## Contract Digests
+
+Digest preimages use RFC 8785/JCS canonical JSON bytes over the contract object after the digest field being produced is removed. No other contract field is implicitly excluded.
+
+- `EvidenceReceipt.receipt_digest`: hash the complete receipt object without the top-level `receipt_digest` field. Source, target, environment, capability, provenance, execution identity, observations, attempts, artifacts, raw result, config digest, fixture disclosure, permissions, sandbox, proof gaps, and timings all remain in the preimage.
+- `EvidencePolicy.policy_digest`: hash the complete policy object without the top-level `policy_digest` field. Defaults, presets, observation schema registrations, adapter registrations, extension namespaces, trust/freshness/fixture/completion/layering policy all remain in the preimage. Nested `PolicyLayer.policy_digest` values are included as references to already-materialized lower-layer policies and must not repeat the enclosing policy digest.
+
+The canonical fixture vectors are executable through `node scripts/verify-evidence-contract-vectors.mjs`.
+
+## Namespaces And Extensions
+
+Built-in observation types and proof presets are starter vocabulary only. They are conveniences for common API, process, browser, desktop, mobile, deployment, filesystem, database, queue, and artifact cases, not a closed enum.
+
+Observation type names and preset names use one of these namespaces:
+
+- `planr.*`: reserved for Planr-owned built-ins.
+- `mcp.*`: reserved for MCP attestation vocabulary that Planr validates.
+- `host.*`: reserved for verified host-native capture contracts.
+- Reverse-domain namespaces such as `com.example.queue.job.processed`.
+- Project-local namespaces such as `project.queue.job.processed` inside the repository that defines them.
+
+Custom observation types must reference a versioned JSON Schema and a registration digest in repository-local Evidence policy. Unknown, unregistered, or unavailable custom types remain uncovered and cannot be silently accepted as a weaker built-in.
+
+## Object Model
+
+### ProofObligation
+
+A reviewed, binding or advisory contract for one acceptance criterion.
+
+Required fields:
+
+- `id`, `schema_version`, `criterion_id`, `plan_id`, optional `item_id`.
+- `title`, `binding`, `observations`, `fixture_policy`, `freshness_policy`, `assurance_policy`.
+- `policy_digest`, `config_digest`, `created_at`, and optional `supersedes`.
+
+`binding = true` means closure must evaluate Evidence coverage. `binding = false` may be rendered as guidance but cannot block or satisfy closure.
+
+### ObservationRequirement
+
+One atomic fact that must be observed.
+
+Required fields:
+
+- `id`, namespaced `type`, `subject`, `expected`, `target`, `environment`, `runtime_target`.
+- Optional `payload_schema`, `state_transitions`, `persistence`, `negative_assertions`, `freshness_policy`, and `assurance_policy`.
+
+The `type` says what fact is being observed, not which tool must observe it. Tool preference belongs in policy.
+
+### VerificationCapabilityManifest
+
+A versioned static declaration from an adapter, host, or attestor.
+
+Required fields:
+
+- `id`, `schema_version`, `version`, `adapter_kind`, `adapter_digest`.
+- Supported surfaces, observation type/schema/digest triples, interactions, artifacts, runtime targets, provenance path, permissions, costs, determinism, repeatability, independence, blind spots, and availability probe contract.
+- Process adapters declare a closed `availability_probe.kind = process` contract with executable name, arguments, optional working directory, timeout, stdout/stderr byte limits, and the payload schema binding for emitted observations.
+
+A manifest is a claim about what a method can observe. It is not proof that the method is available now.
+
+### VerificationCapabilityInstance
+
+A runtime availability snapshot for one exact manifest, host, surface, version, environment, and permission set.
+
+Required fields:
+
+- `id`, `schema_version`, `manifest_id`, `manifest_digest`, `host`, `surface`, `host_version`, `adapter_version`, `environment`, `permissions`, `availability`, `probe_result`, `observed_payload_contract`, `limitations`, `captured_at`.
+
+`probe_result.probe_execution_id` is the single authoritative runtime probe execution identity for a capability instance. A separate top-level probe execution ID is not part of the contract.
+
+Instances expire or become stale when manifest, host, environment, permission, schema, or policy inputs change.
+
+### EvidenceAttempt
+
+An immutable record of each verification attempt.
+
+Required fields:
+
+- `id`, `schema_version`, `criterion_id`, `obligation_id`, `capability_instance_id`.
+- `started_at`, `ended_at`, `status`, resolved command or tool call, exit/signal/error details, retry lineage, stdout/stderr digests, raw result reference, artifact references, and output bounds.
+
+Attempts are durable whether they pass, fail, time out, abort, skip, become unavailable, or end inconclusively. A later passing attempt does not erase earlier failures.
+
+Attempt status and execution result must agree: `passed` requires clean exit code `0`; `failed` requires a non-zero exit code; `timed_out`, `skipped`, and `unavailable` require no exit code or signal and the matching error value; `aborted` requires no exit code plus an abort signal and error; `inconclusive` requires a completed exit with an inconclusive error marker.
+
+### UntrustedEvidenceProposal
+
+Adapter, host, import, or agent input before Planr assigns provenance.
+
+Required fields:
+
+- `id`, `schema_version`, `source_kind`, `submitted_at`, `claims`, `artifact_refs`, `producer_metadata`.
+
+Forbidden authoritative fields:
+
+- Trusted provenance, execution identity, source revision binding, target digest binding, environment identity, freshness result, policy result, coverage result, receipt digest, or closure authority.
+
+### EvidenceReceipt
+
+The trusted outer envelope created only by Planr or an accepted attestation verifier after validation.
+
+Required fields:
+
+- `id`, `schema_version`, `criterion_id`, `obligation_id`, `receipt_status`.
+- Source revision/tree state, target digest/URI/deployment ID, environment identity, vantage point.
+- Capability manifest and instance digests, Planr-assigned provenance, execution/tool-call ID.
+- Observation results, attempt IDs and retry history, artifact references and digests.
+- Fixture/mock disclosure, permission and sandbox state, proof gaps, started/ended timestamps, and `receipt_digest`.
+
+Receipts can satisfy coverage only when trusted, fresh, policy-compliant, target-matched, schema-valid, and observation-equivalent to the requirement.
+
+### CoverageVerdict
+
+The canonical coverage result for a criterion, item, plan, or goal.
+
+Required fields:
+
+- `id`, `schema_version`, `scope`, `evaluated_at`, `status`, `observation_coverage`, `validation_details`, `suggested_next_action`, `actionable_now`.
+
+Allowed statuses:
+
+- `satisfied`: every binding observation is covered by trusted, fresh, policy-compliant receipts.
+- `unsatisfied`: one or more observations lack sufficient proof and a product or test failure is indicated.
+- `blocked`: proof cannot currently be produced because a required capability, permission, sandbox, environment, or dependency is unavailable.
+- `inconclusive`: attempted evidence cannot decide the required observation.
+- `waived`: every remaining binding gap is covered by a valid scoped waiver.
+- `stale`: previously sufficient evidence was invalidated by source, target, environment, policy, adapter, schema, configuration, or freshness change.
+
+Gap coverage must match the verdict status:
+
+- `unsatisfied` uses `missing` or `unsatisfied` gap entries with missing/product/verifier/policy/trust/schema/fixture/waiver/unsupported-observation reasons.
+- `blocked` uses `blocked` gap entries with capability, permission, sandbox, environment, dependency, or runtime-target reasons.
+- `inconclusive` uses `inconclusive` gap entries with timeout, abort, inconclusive-result, or verifier-failed reasons.
+- `waived` uses `waived` gap entries, requires `waiver_id`, and records the underlying waived reason rather than `waiver_missing` or `waiver_expired`.
+- `stale` uses `stale` gap entries with stale source, target, environment, policy, adapter schema, or configuration reasons.
+
+### EvidencePolicy, ProofPreset, EvidenceWaiver
+
+Repository policy lives in `.planr/evidence.yaml`. It owns defaults, named presets, observation schema registrations, adapter registrations, trust/freshness/fixture/completion policy, and extension namespaces.
+
+Adapter registrations bind the manifest ID, repository-local manifest path, manifest digest, observation types, payload schema bindings, provenance path, and closed execution contract used by Planr-observed process adapters.
+
+Policy layer scope uses the frozen `EvidenceScope` chain. Repository policy defaults and extension declarations are document-level policy. Product-level policy is represented by `goal`, plan-level policy by `plan`, item-specific branches by `item`, and criterion-level policy by `criterion`.
+
+Policy layers may strengthen lower-level requirements. Weakening requires an explicit waiver. Waivers include identity, reason, scope, exact observation IDs, source/target binding, created-at, expires-at, approval reference, and audit trail.
+
+## Status And Failure Vocabularies
+
+`EvidenceAttempt.status` values:
+
+- `passed`, `failed`, `skipped`, `timed_out`, `aborted`, `unavailable`, `inconclusive`.
+
+`EvidenceReceipt.receipt_status` values:
+
+- `trusted`, `rejected`, `untrusted`, `stale`, `superseded`.
+
+`VerificationCapabilityInstance.availability.status` values:
+
+- `available`, `unavailable`, `degraded`, `permission_denied`, `sandbox_blocked`, `unsupported`, `probe_failed`.
+
+Coverage gap/failure reason codes:
+
+- `missing_observation`, `missing_capability`, `permission_denied`, `sandbox_blocked`, `environment_unavailable`, `external_dependency_unavailable`, `product_failed`, `verifier_failed`, `timed_out`, `aborted`, `inconclusive_result`, `stale_source`, `stale_target`, `stale_environment`, `stale_policy`, `stale_adapter_schema`, `stale_configuration`, `target_mismatch`, `schema_mismatch`, `manifest_mismatch`, `untrusted_provenance`, `fixture_disallowed`, `mock_disallowed`, `insufficient_assurance`, `waiver_missing`, `waiver_expired`, `unknown_observation_type`, `unsupported_runtime_target`.
+
+Legacy/operator aliases are rendered as aliases only and resolve to the canonical codes above: `capability_unavailable` -> `missing_capability`, `dependency_unavailable` -> `external_dependency_unavailable`, `policy_failed` -> `stale_policy`, `trust_failed` -> `untrusted_provenance`, and `stale_evidence` -> `stale_source`. Unknown legacy reasons are classified as `verifier_failed` rather than `product_failed`.
+
+Explicit pre-Evidence migration input uses `schema_version = "planr.evidence.migration.v1"`, a single `plan_id`, and an `obligations[]` array of full `ProofObligation` objects whose `plan_id` matches the migration plan and whose `binding` is `true`. Preview is non-mutating. Apply is atomic for the migration payload: any conflict or malformed obligation leaves the plan with no newly bound partial obligations. Reapplying an identical payload is `unchanged`.
+
+Process adapters may report a host boundary failure only with an exact single-field JSON line on stdout or stderr:
+
+- `{"planr_adapter_boundary":"permission_denied"}`
+- `{"planr_adapter_boundary":"sandbox_blocked"}`
+
+Planr treats those structured lines as adapter boundary signals for failed process attempts and capability probes. Numeric exit codes alone do not imply `sandbox_blocked`; shell exit code 126 remains permission denied.
+
+## Trust And Provenance Rules
+
+- Public deserialization always produces an `UntrustedEvidenceProposal` or authored policy object, never a trusted receipt.
+- Adapter output can report observed facts and artifact references, but Planr binds the actual source revision, target, environment, execution identity, timings, retries, sandbox, permissions, output bounds, and receipt digest.
+- Requested route metadata, declared agent profile metadata, and model names are not effective execution proof.
+- A user approval can attest a fact only through the waiver or user-attestation path, with identity, reason, scope, expiry where applicable, and audit trail. It cannot silently convert agent JSON into Planr-observed execution.
+- Artifacts referenced by trusted receipts require content digests and repository/root containment or explicit external URI policy.
+- Fixture and mock use must be disclosed and accepted by policy for the exact observation.
+
+## Canonical Fixtures
+
+The v1 frozen fixtures are:
+
+- `docs/contracts/fixtures/evidence/v1/schemas/evidence-contract-v1.schema.json`
+- `docs/contracts/fixtures/evidence/v1/examples/proof-obligation.json`
+- `docs/contracts/fixtures/evidence/v1/examples/verification-capability-manifest.json`
+- `docs/contracts/fixtures/evidence/v1/examples/verification-capability-instance.json`
+- `docs/contracts/fixtures/evidence/v1/examples/evidence-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/examples/untrusted-evidence-proposal.json`
+- `docs/contracts/fixtures/evidence/v1/examples/evidence-receipt.json`
+- `docs/contracts/fixtures/evidence/v1/examples/coverage-verdict.json`
+- `docs/contracts/fixtures/evidence/v1/examples/evidence-policy.json`
+- `docs/contracts/fixtures/evidence/v1/examples/proof-preset.json`
+- `docs/contracts/fixtures/evidence/v1/examples/evidence-waiver.json`
+- `docs/contracts/fixtures/evidence/v1/negative/available-empty-probe-capability.json`
+- `docs/contracts/fixtures/evidence/v1/negative/mismatched-probe-execution-id-capability.json`
+- `docs/contracts/fixtures/evidence/v1/negative/empty-trust-bindings-receipt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/failed-zero-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/forged-trusted-receipt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/timed-out-zero-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/aborted-zero-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/skipped-zero-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/unavailable-zero-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/inconclusive-clean-exit-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/passed-empty-attempt.json`
+- `docs/contracts/fixtures/evidence/v1/negative/unbound-waiver.json`
+- `docs/contracts/fixtures/evidence/v1/negative/minimal-policy-missing-owned-inputs.json`
+- `docs/contracts/fixtures/evidence/v1/negative/policy-default-preset-unregistered.json`
+- `docs/contracts/fixtures/evidence/v1/negative/policy-weakening-without-waiver.json`
+- `docs/contracts/fixtures/evidence/v1/negative/satisfied-empty-coverage-verdict.json`
+- `docs/contracts/fixtures/evidence/v1/negative/unsatisfied-coverage-without-gap.json`
+- `docs/contracts/fixtures/evidence/v1/negative/process-probe-missing-output-limits.json`
+- `docs/contracts/fixtures/evidence/v1/negative/adapter-registration-missing-execution-contract.json`
+- `docs/contracts/fixtures/evidence/v1/negative/waived-coverage-missing-waiver-id.json`
+- `docs/contracts/fixtures/evidence/v1/negative/waived-coverage-forbidden-gap-reason.json`
+- `docs/contracts/fixtures/evidence/v1/negative/blocked-coverage-with-stale-reason.json`
+- `docs/contracts/fixtures/evidence/v1/negative/inconclusive-coverage-with-blocked-reason.json`
+- `docs/contracts/fixtures/evidence/v1/negative/stale-coverage-with-inconclusive-reason.json`
+
+Replayable schema validation:
+
+```bash
+set -e
+schema='docs/contracts/fixtures/evidence/v1/schemas/evidence-contract-v1.schema.json'
+node scripts/verify-evidence-contract-vectors.mjs
+npx --yes ajv-cli@5.0.0 validate --spec=draft2020 --validate-formats=false -s "$schema" -d 'docs/contracts/fixtures/evidence/v1/examples/*.json'
+for fixture in docs/contracts/fixtures/evidence/v1/negative/*.json; do
+  case "$fixture" in
+    *policy-default-preset-unregistered.json)
+      npx --yes ajv-cli@5.0.0 validate --spec=draft2020 --validate-formats=false -s "$schema" -d "$fixture"
+      echo "$fixture accepted by schema for semantic validation"
+      continue
+      ;;
+  esac
+  if npx --yes ajv-cli@5.0.0 validate --spec=draft2020 --validate-formats=false -s "$schema" -d "$fixture" >/tmp/planr-evidence-negative.out 2>&1; then
+    cat /tmp/planr-evidence-negative.out
+    echo "unexpected valid negative fixture: $fixture" >&2
+    exit 1
+  fi
+  echo "$fixture rejected as expected"
+done
+```
+
+Later implementation slices must use these fixtures as no-drift inputs for production canonicalization, schema validation, and coverage behavior.

package/docs/contracts/PI_INTEGRATION_V1.md

@@ -0,0 +1,164 @@
+# Pi Integration Contract v1
+
+Status: frozen for implementation
+
+Frozen: 2026-07-27
+
+Upstream source probes:
+
+- `earendil-works/pi` `main` commit
+  `a597371bda2af70372d1323d550483b5f4a0ae36` (2026-07-27).
+- Pi release `v0.82.1` commit
+  `b4f293684bba718d59cc1157679bcf6157b3a7f5` (2026-07-27).
+- `nicobailon/pi-subagents` `main` commit `73fb2fc` (2026-07-27).
+
+The Pi repository currently publishes release tags ahead of the fetched
+`main` version line, so this contract records both: `main` is the requested
+source probe, while `v0.82.1` is the latest released runtime/API baseline.
+
+This contract is the implementation boundary for first-class Pi support.
+It follows Pi's native extension model instead of treating every coding agent
+as an MCP host. Pi core deliberately ships without MCP, subagents, plan mode,
+or permission popups. It natively discovers Agent Skills and can run their CLI
+workflows through its built-in `bash` tool.
+
+## Frozen artifact and discovery policy
+
+`planr install pi` owns exactly the repository paths in the executable
+contract below. Workflow files are copied byte-for-byte from the canonical
+`plugins/planr/skills` sources. Pi-specific role bodies exist only because
+`pi-subagents` frontmatter is not interchangeable with Claude/Cursor role
+frontmatter: it uses `thinking`, explicit tool/skill inheritance controls, and
+project agents under `.pi/agents/**/*.md`.
+
+Pi loads `.pi/skills/` only after the repository is trusted. Interactive Pi
+asks for trust; non-interactive `-p`, JSON, and RPC runs ignore untrusted
+project resources by default. A headless operator who has deliberately chosen
+to trust the repository passes `--approve` for that run. Planr never writes
+Pi's user trust store or `.pi/settings.json`.
+
+`pi-subagents` is optional. When installed, it discovers both Planr roles.
+Without it, the role files are inert and the same Planr skills remain usable
+in the parent Pi session or separate Pi processes.
+
+```json
+{
+  "contract_version": 1,
+  "pi_main_revision": "a597371bda2af70372d1323d550483b5f4a0ae36",
+  "pi_release": {
+    "tag": "v0.82.1",
+    "revision": "b4f293684bba718d59cc1157679bcf6157b3a7f5"
+  },
+  "pi_subagents_revision": "73fb2fc",
+  "artifacts": [
+    {"target": ".pi/agents/planr-reviewer.md", "source": "plugins/planr/agents/pi/planr-reviewer.md", "kind": "agent"},
+    {"target": ".pi/agents/planr-worker.md", "source": "plugins/planr/agents/pi/planr-worker.md", "kind": "agent"},
+    {"target": ".pi/skills/planr-goal/SKILL.md", "source": "plugins/planr/skills/planr-goal/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-loop/SKILL.md", "source": "plugins/planr/skills/planr-loop/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-loop/agents/planr-reviewer.md", "source": "plugins/planr/skills/planr-loop/agents/planr-reviewer.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/agents/planr-worker.md", "source": "plugins/planr/skills/planr-loop/agents/planr-worker.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/references/host-dispatch.md", "source": "plugins/planr/skills/planr-loop/references/host-dispatch.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/references/recovery-and-verification.md", "source": "plugins/planr/skills/planr-loop/references/recovery-and-verification.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-plan/SKILL.md", "source": "plugins/planr/skills/planr-plan/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-review/SKILL.md", "source": "plugins/planr/skills/planr-review/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-status/SKILL.md", "source": "plugins/planr/skills/planr-status/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-summary/SKILL.md", "source": "plugins/planr/skills/planr-summary/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-task-graph/SKILL.md", "source": "plugins/planr/skills/planr-task-graph/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-verify-web/SKILL.md", "source": "plugins/planr/skills/planr-verify-web/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-work/SKILL.md", "source": "plugins/planr/skills/planr-work/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr/SKILL.md", "source": "plugins/planr/skills/planr/SKILL.md", "kind": "skill"}
+  ],
+  "mcp": {"supported": false, "artifacts": []},
+  "extensions": {"emitted": false, "artifacts": []},
+  "hooks": {"supported": false, "artifacts": []},
+  "settings": {"emitted": false, "artifacts": []},
+  "trust": {
+    "project_resources_require_trust": true,
+    "interactive": "Pi prompts the operator",
+    "headless": "pass --approve only after choosing to trust the repository"
+  },
+  "observed_client": {
+    "environment": "PI_CODING_AGENT",
+    "accepted_value": "true",
+    "stored_value": "pi",
+    "advisory_only": true
+  },
+  "client_all_includes_pi": false,
+  "headless": {
+    "command": "pi --approve --model <provider/model> --thinking <level> -p \"<prompt>\""
+  }
+}
+```
+
+## Pi role contract
+
+Both role files use `pi-subagents` project-agent frontmatter:
+
+- `name` is exactly `planr-worker` or `planr-reviewer`;
+- `systemPromptMode: replace`;
+- `inheritProjectContext: true`;
+- `inheritSkills: false`;
+- `skills` names exactly `planr-work` or `planr-review`;
+- the worker tool allowlist includes read/search, `bash`, `edit`, and `write`;
+- the reviewer tool allowlist includes read/search and mutation-capable `bash`,
+  but omits the `edit` and `write` tools;
+- the reviewer declares `acceptanceRole: read-only` and
+  `completionGuard: false`, so pi-subagents treats the bash-enabled validator
+  as non-implementation work without changing its tool access;
+- no role pins `model`, `thinking`, `fallbackModels`, provider credentials, or
+  extensions.
+
+Model and thinking selection remain external host policy. Operators can use
+Pi or `pi-subagents` settings/overrides, while Planr records only requested and
+observed evidence.
+
+## Merge and overwrite policy
+
+- Missing target: write the canonical packaged source.
+- Existing identical content: unchanged.
+- Existing different content: preserve without `--force`; replace only that
+  target with `--force`.
+- `--no-mcp` and `--no-hooks` are accepted for install-command parity but
+  change no Pi path because the v1 artifact set contains neither.
+- Dry-run enumerates the same paths the corresponding write reconciles.
+- `project init --client pi` provisions the same skills and roles without
+  writing any other Pi artifact.
+- `--client all` remains the legacy Codex, Claude Code, and Cursor expansion.
+
+## Runtime observation boundary
+
+Pi documents that commands launched by its built-in tools receive
+`PI_CODING_AGENT=true`. Planr accepts only that exact value as advisory
+`runs.observed_client=pi`. Other values and other ambient `PI_*` variables are
+ignored. The marker is not authentication, authorization, proof of model,
+proof of `pi-subagents`, or worker identity.
+
+Pi has no Planr hook in v1. Run `planr prime` manually after startup or
+compaction when a fresh state block is useful. Agent Skills remain the primary
+entry point: `/skill:planr` explicitly loads the router, while natural-language
+requests may trigger Pi's skill discovery.
+
+## Security and CI boundary
+
+Planr installation must not read or write:
+
+- `~/.pi`, Pi auth files, provider keys, OAuth tokens, sessions, transcripts,
+  prompts, responses, model catalogs, package caches, or trust decisions;
+- `.pi/settings.json`, `.pi/extensions/`, `.pi/prompts/`, or an MCP config;
+- global `pi install`, `pi config`, package enablement, or user settings.
+
+Release and CI workflows do not install/invoke Pi, `pi-subagents`, a provider,
+or a live model. Deterministic tests parse the frozen contract, compile/write
+assets into disposable repositories, and validate CLI/docs output.
+
+## Sources
+
+- `packages/coding-agent/README.md` at Pi `v0.82.1`: project trust, skills,
+  extensions, packages, philosophy, CLI, and `PI_CODING_AGENT`.
+- `packages/coding-agent/docs/skills.md` at Pi `v0.82.1`.
+- `nicobailon/pi-subagents` README at `73fb2fc`: project agent discovery,
+  prompt assembly, frontmatter, and model overrides.
+- `nicobailon/pi-subagents` `test/unit/agent-frontmatter.test.ts` and
+  `test/unit/path-resolution.test.ts` at `73fb2fc`.
+- https://github.com/earendil-works/pi
+- https://github.com/nicobailon/pi-subagents