planr 1.9.0 → 1.10.0-alpha.10

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>
@@ -180,8 +206,8 @@ Use $planr-goal to prepare an autonomous goal for the weekly overview feature.
 context (tag: goal-contract).
 
 Goal: ship the weekly overview feature. DONE when every in-scope map item is closed
-with log evidence, all reviews are closed complete, and a live verification log shows
-the feature working in the browser. Iteration budget: 10.
+with implementation evidence, all reviews are closed complete, and canonical Evidence
+coverage proves the feature working in the browser. Iteration budget: 10.
 ```
 
 Mid-project work (a new feature, refactor, or fix on an existing project) works the same — it gets its own feature-scoped plan and extends the existing map. Both journeys with example prompts: [Prompt Recipes](https://planr.so/docs/agents/prompt-recipes). Coding agents inspect progress with the compact default `planr map show` or, preferably, `planr map show --json`. The tree preserves exact dependency vocabulary while marking satisfied edges as `blocks✓`; active `blocks` stay red. The boxed `planr map show --view diagram` renderer is exclusively for human supervision and uses neutral `then` routes once those dependencies are satisfied. Agents must not invoke it. Humans can add `--full` for complete status, title, worker, critical-lane, and pressure details. Interactive map output colors states automatically; `--no-color` and `NO_COLOR` keep it plain.
@@ -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/ARCHITECTURE.md

@@ -22,24 +22,26 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/app/commands.rs`: general CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and shared install command handlers.
 - `src/app/grok.rs`: Grok-specific install orchestration. Owns safe project TOML reconciliation, repository workflow writes, and the explicit no-hooks result.
 - `src/app/prompts.rs`: CLI, MCP, and HTTP prompt output. Host routing prompt composition remains in `src/app/agents.rs`.
-- `src/app/flow.rs`: compound work-flow boundary. Owns evidence log writing (with heartbeat folding), the close transition core, review-request creation, the pick work packet, and the `done` command that chains them for CLI, HTTP, and MCP surfaces.
+- `src/app/flow.rs`: compound workflow boundary. Owns evidence log writing (with heartbeat folding), canonical FeatureRun settlement input normalization, the close transition core, the pick work packet, and the `done` command shared by CLI, HTTP, and MCP surfaces.
 - `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
 - `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
-- `src/app/packages.rs`: package import/export boundary. Owns reusable JSON templates, preview-before-import, review artifact package import, and local-first encrypted bundle metadata.
+- `src/app/packages.rs`: package import/export boundary. Owns reusable JSON templates, preview-before-import, durable ReviewGate package projections, and local-first encrypted bundle metadata.
 - `src/app/http.rs`: localhost HTTP/SSE boundary. Owns HTTP request parsing, routes, SSE stream output, and HTTP response mapping.
 - `src/app/repository.rs`: application data access helpers. Owns Planr query/update helpers over projects, plans, graph items, links, runs, logs, artifacts, events, approvals, search, and map projections.
 - `src/app/lease.rs`: worker lease ownership. Owns the single pick query (`PickFilter`: exclude, work type, plan scope), worker ownership checks, runtime heartbeat/progress/pause state, and stale-pick detection.
-- `src/app/review.rs`: review-gate application logic. Owns review annotations, feedback ingestion, evidence artifacts, review closure, and review target lookup.
+- `src/app/review.rs`: ReviewGate application logic. Owns review annotations, feedback ingestion, scoped evidence, durable attempt completion, finding resolution, and gate lookup.
 - `src/app/recovery.rs`: recovery automation logic. Owns item retry policy configuration, task conditions, stale/timed-out sweeps, retry scheduling, and recovery result projections.
-- `src/app/review_workspace.rs`: local review workspace boundary. Owns the browser review HTML, workspace data projection, and privacy-minimized Git diff evidence.
+- `src/app/execution_run.rs`: canonical FeatureRun and ReviewGate application boundary. Owns run phases, outcome batching and settlement, typed escalation, role leases, durable findings/re-review, and final product review projections.
+- `src/app/execution_state.rs`: canonical `planr.execution_state.v2` read boundary. It projects one run-scoped FeatureRun, active batch, role owner, persisted budget amounts/provenance/digest/deadline, ReviewGate, attempts, findings, stable reason code, and next action for CLI, MCP, HTTP, pick, trace, status, recovery, package, and audit consumers.
 - `src/app/surfaces.rs`: non-CLI runtime surfaces. Owns trace, scrub, artifact, event, debug, export, and import command handlers.
 - `src/app/inspection.rs`: local inspection helpers. Owns debug bundles, context/link snapshots, pick context, secret scans, export value assembly, run recording, search results, and Planr-directory import parsing.
-- `src/app/audit.rs`: goal contract audit boundary. Owns the clause-by-clause `plan audit` verdict (items settled, reviews complete, approvals clear, verification logged) and its human rendering.
+- `src/app/audit.rs`: goal contract audit boundary. Owns the clause-by-clause `plan audit` verdict (items settled, required independent material reviews, exactly one current independent final product review, approvals clear, canonical Evidence coverage) and its human rendering. Claim-only verification logs remain isolated to frozen pre-Evidence compatibility.
 - `src/app/application.rs`: shared surface-mutation boundary. Owns the approval request/approve/deny, context, log, artifact, and close mutations reused verbatim by CLI, MCP, and HTTP handlers so the three surfaces cannot drift.
-- `src/app/repository/`: focused data-access submodules (`item.rs`, `plan.rs`, `project.rs`, `link.rs`, `context.rs`, `evidence.rs`, `search.rs`) split out of `src/app/repository.rs` by entity ownership.
+- `src/app/repository/`: focused data-access submodules (`item.rs`, `plan.rs`, `project.rs`, `link.rs`, `context.rs`, `evidence.rs`, `execution_run.rs`, `search.rs`) split out of `src/app/repository.rs` by entity ownership. Execution-state reads select ReviewGates strictly by run id; project/plan-wide history is never projected as the current run.
 - `src/model.rs`: JSON-facing data transfer types and typed vocabulary. Owns serializable Planr DTOs plus the `ItemStatus`, `WorkType`, `LinkKind`, and `ApprovalStatus` enums with their parsing and display behavior, used by CLI JSON, MCP, HTTP, storage rows, and tests.
 - `src/storage/mod.rs`: SQLite connection boundary. Owns default database path, connection setup, pragma configuration, and storage submodule exports.
 - `src/storage/schema.rs`: SQLite schema boundary. Owns DDL, additive schema upgrade helpers, and schema version recording.
+- `src/storage/execution_run_schema.rs`: the sole persisted compatibility boundary for FeatureRun rollout. It upgrades already-stored review/fix history into durable terminal history, but no application, packet, agent asset, or documentation path produces the superseded live shape.
 - `src/storage/rows.rs`: SQLite row mapping boundary. Owns row-to-DTO and row-to-JSON mapping functions.
 - `src/planpack.rs`: Markdown package generation and parsing. Owns project context templates, product/build plan templates, plan metadata parsing, hashes, search body extraction, and task extraction.
 - `src/agents.rs`: agent profile registry core. Owns `.planr/agents.toml` parsing, registry validation warnings, and the pure advisory `resolve_route` precedence logic (override > work_type > plan > default); no storage or host concerns.
@@ -53,6 +55,40 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
 - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
 
+## FeatureRun Execution Boundary
+
+Every live worker decision is a typed work packet:
+
+- `kind: "outcome"` is ordinary maker work; `mode: "finding_repair"` returns named findings to the same responsible maker and ReviewGate without creating a fix item.
+- `kind: "review_gate"` is independently leased checker work. Attempts and findings remain children of that gate, never graph items.
+- `kind: "verification"` is a coordinator-owned verifier lease over a frozen canonical source digest. Product source is read-only; trusted Evidence can commit only through the source-checked Evidence transaction. The coordinator calls `evidence verify` without another model.
+- Releasing verification is an application-owned transition: the item lease, FeatureRun verifier role, and verification budget reconcile atomically back to `source_frozen`. `pick release --repair <reference>` additionally invalidates the frozen candidate and routes a fresh repair batch to the recorded maker; the failed verifier lease is never resumed.
+- An accepted material checkpoint is source-bound after any product or admission repair. Repair settlement preserves the prior attempt, reopens the same gate with the active freeze revision/digest and repair-obligation lineage, and leaves verification unleaseable until a fresh independent acceptance of that exact binding.
+- `kind: "hold"` is an admission or capability stop. A driver must report its classification and next action; it cannot reinterpret the hold as permission to replace the maker, weaken verification, or open an ad hoc review.
+
+All four packets embed the same run-scoped `planr.execution_state.v2` projection. Host skills, generated roles, installed copies, and Stop hooks render that state but own no lifecycle or budget policy. Ordinary maker settlement uses plain `planr done`; only an allowed protected-risk interrupt uses structured escalation. Review findings are logged and resolved on the existing gate. Evidence runs once after stable source freeze and selectively reruns only invalidated obligations after a product repair.
+
+The one exception is persisted database input in `src/storage/execution_run_schema.rs`. Existing user databases may contain historical review/fix graph rows, so the schema upgrade consumes them once into terminal history. That read boundary does not justify aliases, fallback commands, dual DTOs, or live legacy producers elsewhere.
+
+## Planr 2.0 Immutable Budget Boundary
+
+The Planr 2.0 budget authority is one immutable `planr.feature_run_budget_contract.v2` created atomically with each FeatureRun. Bounded contracts contain a persisted UTC run-start anchor, complete wall-seconds/tool-call/token totals, exact maker/verification/review/repair/release allocations, per-dimension metering requirements, and a canonical digest. Unbounded mode is an explicit contract with no numeric limits or reserves. Every admitted bounded task carries positive maxima for all three dimensions and an overflow-checked absolute UTC deadline.
+
+Ownership is singular and dependencies are one-way:
+
+- `src/usage_policy.rs` owns the provider-neutral contract types, validation, provenance, phase protection, snapshots, and pure checked arithmetic.
+- `src/execution_policy.rs` owns pure admission over typed concurrency plus persisted budget snapshots.
+- `src/app/execution_run.rs` resolves authored policy once and binds the immutable contract to run creation.
+- `src/app/feature_run_evidence.rs` owns transactional reservation, append-only observation, reconciliation, phase release, and hold sequencing.
+- `src/app/execution_state.rs` owns the sole `planr.execution_state.v2` projection reused by CLI, MCP, HTTP, work packets, trace, status, generated roles, and skills.
+- Storage owns insert-only persistence and integrity mechanics; host adapters only enforce supplied maxima/deadlines and report observations with provenance.
+
+Runtime decisions never reload `.planr/policy.toml`, fabricate allowances, infer trusted usage from projections, synthesize missing active-run state, or expose a compatibility budget DTO. Missing, invalid, corrupt, or unenforceable budget state is a typed hold before dispatch.
+
+An incompatible active FeatureRun is retired only through the plan-scoped application lifecycle in `src/app/execution_run.rs`. Pure eligibility and policy-cancel state changes live in `src/execution_run.rs`; `src/app/repository/execution_run.rs` ends the batch and leases, updates the run with optimistic concurrency, and records provenance in one transaction. CLI, MCP, and HTTP only transport the closed `incompatible-budget` reason and reuse the canonical result. Restart never writes a budget contract or successor run; a later ordinary pick remains the sole atomic run-plus-contract creation path.
+
+A compatible budget-held FeatureRun resumes only through `planr run resolve-budget-hold --plan <id>`, owned by `src/app/feature_run_evidence.rs`. The application transaction revalidates the immutable contract, persisted snapshot, active reservation deadlines, exact held phase, canonical role owner, and lease generation before restoring that phase. Incompatible contracts require restart; capability holds, corrupt state, expired deadlines, missing reservations, unrepaired ceilings, and owner mismatches remain held. MCP and HTTP transport the same typed application result without policy or arithmetic.
+
 ## Eval Contract V1/V1.1 Ownership
 
 The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until implementation promotes it into code. Its V1.1 efficiency-evidence amendment is additive and keeps the same owner split:
@@ -72,7 +108,7 @@ The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until
 - Mutations shared by more than one surface (CLI, MCP, HTTP) belong in `src/app/application.rs`; surface handlers must call the shared helper instead of repeating SQL.
 - Markdown templates belong in `planpack.rs`; command handlers should request generated file sets instead of embedding large template bodies.
 - Agent install metadata and MCP schema descriptors belong in `src/integrations.rs`; client-specific strings should not drift across command handlers and docs.
-- DTO and vocabulary-enum changes belong in `src/model.rs`; JSON response shapes should reuse those DTOs before adding ad hoc maps.
+- General graph DTO and vocabulary-enum changes belong in `src/model.rs`; FeatureRun/ExecutionBatch/ReviewGate status projection changes belong in `src/app/execution_state.rs`. JSON response shapes reuse those owners before adding ad hoc maps.
 - Item status, work type, link kind, and approval status values are typed enums; new states must be added to the enum, not smuggled in as strings.
 - Utility code must stay narrow. If a helper starts owning product behavior, move it to the owning module instead of growing `util.rs`.
 - Do not add catch-all `common`, `shared`, or broad utility modules. New modules must name a durable ownership boundary.
@@ -81,10 +117,10 @@ The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until
 
 Planr remains a single crate for V1 because:
 
-- there is one deployable binary and no separate service or reusable library boundary;
+- one crate owns the CLI and its optional companion executables;
 - the current behavior contract is tighter when CLI, MCP, HTTP, storage, and docs ship together;
 - module-level ownership gives the needed architecture separation without duplicating Cargo settings or release packaging;
-- npm, release, and external consumer tests assume one native binary named `planr`.
+- npm, release, and external consumer tests treat `planr` as the product entry point. They also package provider-specific companion executables when Planr ships them.
 
 A Cargo workspace was tried and reverted: it produced anemic crates whose only job was being a layer, plus re-export shims in the binary. A workspace should be introduced only after a concrete deployable, reuse, compilation, or team ownership boundary exists and package/release scripts are updated in the same change.
 

package/docs/RELEASE.md

@@ -24,25 +24,47 @@ 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 verifies that the changelog predecessor's local
+tag object exactly matches the tag ref returned by `origin`. Only then does it
+create and push 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 a stable-release gate. When the evaluated workflow
+subject or its explicit evaluation policy changed since the previous release
+tag, a stable release also requires:
+
 ```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
@@ -75,8 +97,8 @@ The two scripts enforce, in order:
 3. frozen workspace synchronization cannot change `pnpm-lock.yaml`;
 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;
+6. publication requires clean `main`, the exact prepared versions/references, a committed changelog section, an exact local predecessor tag matching `origin`, and no existing target tag;
+7. publication validates the exact-SHA CI and approval receipts; a stable release whose evaluated subject or policy changed 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:
@@ -103,7 +125,18 @@ The changelog section requirement applies verbatim (`## [1.2.0-alpha.1]`). What
 - npm publishes under the **`alpha` dist-tag** instead of `latest`: plain `npm install -g planr` keeps resolving stable, testers opt in with `npm install -g planr@alpha`.
 - The **Homebrew tap never moves** on pre-release tags.
 
-Only `-alpha.N`, `-beta.N`, and `-rc.N` suffixes are accepted; everything else the script rejects.
+Only canonical SemVer core numbers and `-alpha.N`, `-beta.N`, or `-rc.N`
+suffixes are accepted. Numeric identifiers have no leading zero unless the
+identifier is exactly `0`.
+
+Pre-release publication deliberately does not require a model-evaluation
+receipt before publication. It still requires a clean exact commit on `main`,
+the authenticated green CI promotion receipt, human approval bound to that SHA
+and version, synchronized manifests and generated references, and the committed
+changelog/release contracts. After publication, install that exact prerelease
+and dogfood the installed artifact. That dogfood evidence informs and gates the
+next promotion decision; it is never fabricated from the pre-publication source
+tree. Stable publication keeps the conditional evaluation gate described above.
 
 ## Automated Release Pipeline
 
@@ -145,6 +178,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 +202,10 @@ cat dist/planr-*/SHA256SUMS
 The artifact contains:
 
 - `planr`
+- `planr-browser-harness-adapter`
+- `scripts/host-capability-experiment.mjs`
+- `scripts/host-capability-runtime/v1/schemas/*.schema.json`
+- `scripts/planr-host-capability-validator`
 - `README.md`
 - `LICENSE.md`
 - `SHA256SUMS`
@@ -187,13 +229,18 @@ npm pack --dry-run
 The package must include:
 
 - `npm/bin/planr.js`
+- `npm/bin/planr-browser-harness-adapter.js`
+- `npm/bin/native-launcher.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/`
 - `README.md`
 - `LICENSE.md`
 
-`npm/native/` platform binaries exist only in the `npm-publish` CI job; the local dry-run does not include them.
+`npm/native/` platform binaries exist only in the `npm-publish` CI job. The published package includes `planr`, `planr-browser-harness-adapter`, and `planr-host-capability-validator` for each platform. The local dry-run does not include these binaries.
 
 ## Install Smoke
 

package/docs/SWITCHLOOM_COMPATIBILITY.md

@@ -1,46 +1,14 @@
-# Switchloom Compatibility
+# Archived Switchloom v0.3.2 Compatibility Evidence
 
-This report records Planr-side compatibility evidence for the exact public `switchloom@0.3.2` package. It is intentionally narrow: Planr verifies the package identity, repository-local declaration boundary, and its own consumption/proof semantics. It does not turn Switchloom internals, generated semantic role names, routes, doctor output, or runtime telemetry into a future contract.
+This document records a historical compatibility check performed for the external `switchloom@0.3.2` package. It is not a current Planr release gate or a promise about future Switchloom artifacts, routes, role names, host telemetry, or lifecycle behavior.
 
-## Exact v0.3.2 Behavior Verified
+The historical check established only that the pinned v0.3.2 package could generate repository-local `.planr/agents.toml` and `.planr/policy.toml` declarations that the Planr version at that time consumed successfully. The accompanying one-off cross-product oracle has been removed from Planr.
 
-- Public npm metadata for `switchloom@0.3.2` resolved from the npm registry:
-  - `dist.integrity`: `sha512-g96AZIFKXpG1toAO+Gri1sjD8q0SxFxtRSLAcRcSVRGDCZ/dUtERepsOB+cSHHH7hUsT0jSKZYPfNqiLvfKk9Q==`
-  - `dist.shasum`: `d7d72c74ac3ecd5a3e355edd8e297284cba04403`
-  - `dist.tarball`: `https://registry.npmjs.org/switchloom/-/switchloom-0.3.2.tgz`
-- `npm pack switchloom@0.3.2 --pack-destination /private/tmp --json` returned a 9-entry package with the expected native binaries, wrapper, provenance file, README, license, and package manifest.
-- The packed tarball at `/private/tmp/switchloom-0.3.2.tgz` had SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`.
-- The reviewed oracle contract expects the v0.3.2 Planr integration bundle `balanced-codex-openai@1.0.0+2.0.0`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 10 managed artifacts, 7 Codex-native roles, and 5 Planr work-type routes.
-- Repository docs now document the safe external operator flow with explicit `switchloom@0.3.2` commands, no normal-guidance `apply --yes`, and a caveat that the v0.3.2 tagged README preserves stale `0.3.1` examples.
-- The immutable live oracle used isolated source clone `/private/tmp/planr-switchloom-source.6gbzx2/source` and completed with `SWITCHLOOM_SOURCE_ROOT=/private/tmp/planr-switchloom-source.6gbzx2/source SWITCHLOOM_TARBALL=/private/tmp/switchloom-0.3.2.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp npm run verify:switchloom-cross-product`, exit 0. The live root is `/private/tmp/planr-switchloom-cross-product-Lbluca`, with oracle receipt `/private/tmp/planr-switchloom-cross-product-Lbluca/oracle-receipt.json`.
-- The retained replay of the same root and isolated source clone exited 0 and wrote `/private/tmp/planr-switchloom-cross-product-Lbluca/replay-receipt.json`. Replay first asserts the current source fingerprint matches the retained live receipt, then separately verifies the source remains unchanged during replay.
-- The live and replay receipts bind the same Switchloom source fingerprint before and after each mode: HEAD `8ff05776085d3175211e080143c513c5173abaa4`, clean status SHA256 `e3b0c442...`, inventory SHA256 `790de1be...`, file-hash SHA256 `97a26b12...`, and 303 paths. The maintainer's original sibling Switchloom worktree was not modified for this proof.
-- The successful live oracle proves exact package tarball SHA256 `0c04e94fc4372845edf395b3ea51139b8a4b46f34404940e06b3f4ec3ce22d20`, bundle SHA256 `bf48f502080ff444ccb67bc4eeacc9391e77dbf5f0f8f277814e9abc2443e6c8`, 7 profiles, 5 routes, 10 managed artifacts, Planr declaration consumption, Planr audit, uninstall and unrouted Planr behavior, no-auth fail-closed behavior, requested-only rejection, global sentinel preservation, and routing ownership.
-- The successful live oracle proves separate native maker and reviewer execution: maker `model_routing_terra_high` on `gpt-5.6-terra` with high effort, reviewer `model_routing_sol_high` on `gpt-5.6-sol` with high effort. Hidden spawn messages are intentionally opaque; the proof is exact successful parent `agent_type`, `task_name`, and `fork_turns` metadata correlated with matching direct child role rollouts, repo-local skill reads, and item-specific Planr evidence. It does not claim plaintext hidden-message recovery.
-- One malformed parent `spawn_agent` attempt in the retained live root was retained as a diagnostic and not counted as a successful spawn. The oracle still requires exactly two successful routed spawns and still rejects default, wrong-role, missing-role, or extra successful child execution.
-- A separate fresh root, `/private/tmp/planr-switchloom-cross-product-gHtZQI`, was correctly rejected: Codex claimed `spawn_agent` was unavailable and directly handled the work, producing 0 successful routed spawns. That run is negative evidence for host stochastic failure detection, not a passing compatibility run.
+Planr's stable boundary remains:
 
-## Stable Planr Boundary
+- Planr works without Switchloom or routing declarations.
+- Planr treats profiles, routes, model names, efforts, and fallbacks as provider-neutral repository data.
+- Requested routing metadata is not effective execution proof.
+- External tools own their install, compilation, generated host files, reload requirements, and uninstall lifecycle.
 
-- Planr Core is provider-neutral. It reads `.planr/agents.toml`, `.planr/policy.toml`, and route-audit evidence, but does not install, invoke, compile, apply, or uninstall Switchloom output.
-- `.planr/agents.toml` profiles, routes, model names, efforts, role names, and fallback chains are opaque data to Planr. Planr may place requested routing data in pick packets, but requested-only values are not effective execution proof.
-- `--profile` records the profile a worker reports for a run. Genuine runtime proof belongs in route-audit evidence that separates requested, host-resolved, and effective dimensions.
-- Missing effective host evidence remains explicitly unavailable. Planr must not infer it from generated declarations, policy files, or worker claims.
-- External lifecycle remains external: Switchloom owns compile, apply, generated host roles, host reload requirements, and uninstall. Planr validates its own consumption with `planr agents check` and records evidence through logs/reviews.
-- Planr works without routing declarations. After an external uninstall, unrouted Planr fallback behavior remains the stable Core contract.
-
-## Not Guaranteed For Future Switchloom Work
-
-Future Switchloom work, including thread `019f8a71-5b6c-7c41-9850-7050516fcee4`, may change semantic role names, route names, doctor output, generated artifacts, runtime telemetry, and host-specific evidence shape. Planr must not contract those as stable.
-
-The stable compatibility promise is limited to Planr's boundary: consume provider-neutral declarations when present, keep requested values separate from effective evidence, reject requested-only metadata as proof, avoid owning external lifecycle, and continue operating when routing files are absent.
-
-Any future mismatch in package identity, generated artifacts, Planr declaration parsing, route-audit semantics, host evidence, source-worktree mutation, or security posture should become a new finding or fix item rather than an optimistic compatibility claim.
-
-## Verification Notes
-
-- Rust formatting, clippy, full serial cargo tests, e2e, eval-contract, and routing-ownership tests passed when run outside the sandbox where HTTP/process tests are permitted.
-- Docs reference generation, typecheck, reference verification, maintenance verification, and Node 22 production build passed. Node 26 production docs builds hung in the optimized Next build phase and were terminated; the Node 22 build is the relevant repository runtime.
-- npm package dry-run passed using a temp npm cache because the user npm cache contains root-owned files.
-- Privacy checks passed. The docs app Next.js runtime was upgraded from `16.2.10` to `16.2.11` in `apps/docs/package.json` and `pnpm-lock.yaml`; the lockfile change is limited to Next core/env/SWC and mechanically recalculated peer snapshots. `npm run security:check` passed with BetterLeaks reporting no leaks and Trivy reporting 0 vulnerabilities for both `Cargo.lock` and `pnpm-lock.yaml`.
-- The immutable source clone proof supersedes earlier retained-replay-only evidence. Earlier concurrent external mutation and missing-receipt attempts were treated as real failures and are not counted as passing evidence.
+For current Switchloom behavior, consult the external project and its versioned documentation. Any future compatibility claim requires a new bounded check owned by that integration; Planr does not retain a permanent package-specific oracle.

package/docs/contracts/BROWSER_HARNESS_ADAPTER_V1.md

@@ -0,0 +1,85 @@
+# Browser Harness adapter v1
+
+Status: frozen for `planr-browser-harness-adapter` v1.
+
+This reference defines Planr's first process adapter for the external
+`browser-harness` tool. The adapter implements
+`EVIDENCE_ADAPTER_PROTOCOL_V1.md`. Planr Core does not depend on this adapter.
+
+## Capability
+
+The adapter supports `com.planr.web.dom_state` observations with the payload
+schema `schema://com.planr.web.dom_state.v1`.
+
+Each requirement uses these fields:
+
+- `subject`: A CSS selector for the observed element.
+- `expected.text`: The exact trimmed `textContent`, if text is required.
+- `expected.visible`: The required rendered visibility, if visibility is
+  required.
+- `state_transitions`: A shared array of at most 64 closed actions for the
+  batch. A `click` action has an accessibility `role` and `name`. A `fill` or
+  `select` action has a CSS selector `subject` and a string `value`.
+
+All requirements in one batch must use the same transition array and the same
+optional execution method. The adapter rejects arbitrary actions, arbitrary
+JavaScript, mixed methods, and unsupported observation types before it starts
+the browser tool.
+
+## Execution
+
+An availability probe runs `browser-harness --version`. A real Evidence run
+starts `browser-harness` once and sends one generated Python program over
+stdin. The program completes these steps in one browser session:
+
+1. Open the bound HTTP or HTTPS target.
+2. Apply bounded fill and select actions through native DOM value setters and
+   input/change events.
+3. Find each click target in the accessibility tree by its role and name, then
+   click the center of its CDP box model.
+4. Read each DOM postcondition until it passes or the five-second observation
+   window ends.
+5. Return one structured result for the full requirement batch.
+6. Close the tab.
+
+The generated program inserts requirement data only as JSON. A requirement
+cannot add executable Python or JavaScript.
+
+## Result
+
+Each `actual` object contains:
+
+```json
+{
+  "schema_ref": "schema://com.planr.web.dom_state.v1",
+  "selector": "#status",
+  "text": "B",
+  "visible": true
+}
+```
+
+Planr Core validates this object against the registered JSON Schema. Core then
+evaluates the requirement's `expected` predicate.
+
+If every requirement selects the `browser-harness` agent skill, the adapter
+also returns the matching supervised invocation record. This record is adapter
+output. It becomes trusted only after Planr validates the observed process and
+all sealed bindings.
+
+## Capture policy
+
+The v1 success path disables Browser Harness recordings. The generated program
+does not call screenshot, recording, or trace helpers. The structured DOM
+observation is the retained proof for a non-visual criterion.
+
+The adapter does not advertise a visual observation type. Planr therefore
+rejects it during capability matching for a visual requirement. A recording or
+screenshot cannot upgrade `com.planr.web.dom_state` into visual Evidence.
+
+## Canonical live fixture
+
+`tests/fixtures/evidence/browser-harness/v1/form.html` and
+`form-request.json` exercise the provider-free live boundary: one existing HTTP
+target, one Browser Harness session, bounded fill/select/click actions, and one
+structured DOM postcondition. The fixture requires a dedicated headless browser
+endpoint and never starts a model provider.

package/docs/contracts/EVAL_CONTRACT_V1.md

@@ -1586,7 +1586,7 @@ Required fields:
 - `evidence_ref` string.
 - `target_kind` string enum: `run | comparison`.
 - `target_id` string.
-- `planr_attachment_kind` string enum: `log | review | artifact`.
+- `planr_attachment_kind` string enum: `log | artifact`.
 - `planr_attachment_id` string.
 - `item_id` string.
 - `created_at` RFC 3339 timestamp.

package/docs/contracts/EVIDENCE_ADAPTER_PROTOCOL_V1.md

@@ -0,0 +1,98 @@
+# Evidence adapter protocol v1
+
+Status: frozen for the `planr.evidence.adapter-request.v1` request and the
+`planr.structured_observation_results.v2` result.
+
+This reference defines the process protocol between Planr Core and a registered
+Evidence adapter. It extends `EVIDENCE_CONTRACT_V1.md`. It does not change the
+Evidence domain schema.
+
+## Trust ownership
+
+Planr Core creates the adapter request, starts the registered process, and
+validates the result. The adapter reports observations. It cannot assign
+provenance, decide coverage, or close work.
+
+Planr treats adapter output as untrusted input until all execution and binding
+checks pass. A valid JSON result without a Planr-observed process execution
+cannot create trusted Evidence.
+
+## Process transport
+
+Planr starts the adapter with bounded time, stdout, and stderr limits. Planr
+writes one JSON request to stdin and then closes stdin. The adapter writes one
+JSON result to stdout.
+
+An availability probe starts the same executable with closed, empty stdin. The
+adapter can use that invocation to check runtime availability. A probe result
+cannot satisfy an Evidence requirement.
+
+Planr reserves the `PLANR_EVIDENCE_` environment variable namespace. An adapter
+request does not use environment variables for target, environment, or contract
+bindings.
+
+## `planr.evidence.adapter-request.v1`
+
+The request has these fields:
+
+- `schema_version`: `planr.evidence.adapter-request.v1`.
+- `request_id`: A new Planr-assigned ID for this process execution.
+- `request_digest`: The SHA-256 canonical JSON digest of the request without
+  `request_digest`.
+- `obligation_id` and `criterion_id`: The exact Evidence obligation identity.
+- `requirements`: The selected `ObservationRequirement` objects. The array
+  includes each subject, expected value, target, payload schema, and optional
+  execution method.
+- `target` and `environment`: The runtime bindings selected by Planr.
+- `fixture_disclosure`: The fixture and mock disclosure admitted by policy.
+- `assurance_policy`: The policy that controls required capture strength.
+- `result_contract`: The registered outer result schema binding.
+- `execution_contract_digest`: The digest of the registered process contract.
+- `execution_binding`: The sealed run-index subset and its requirement IDs.
+- `retry`: The exact attempt number, maximum attempts, and predecessor IDs.
+
+The request contains no provider-specific fields. A Browser Harness, native
+browser, Playwright, mobile, desktop, game-engine, API, or CLI adapter receives
+the same request shape.
+
+## `planr.structured_observation_results.v2`
+
+A structured adapter result has these required fields:
+
+- `schema_version`: `planr.structured_observation_results.v2`.
+- `request_id` and `request_digest`: Exact copies from the current request.
+- `target`, `observed_target`, and `environment`: The declared and observed
+  runtime identity.
+- `execution_contract_digest`: An exact copy from the current request.
+- `fixture_disclosure`: The actual fixture and mock use.
+- `observations`: One result for every selected requirement and no other
+  results.
+
+Each observation contains only `requirement_id`, `type`, and `actual`. The
+`actual` object names its payload schema. Planr validates the object against the
+registered JSON Schema and evaluates the expected predicate.
+
+If a requirement selects an agent skill as its execution method, the result
+also includes the structured `agent_skill` invocation record required by the
+Evidence domain contract. The supervised adapter creates this record. Agent or
+user JSON cannot submit it through another trusted path.
+
+Adapters can include diagnostic top-level fields. Diagnostics do not affect
+provenance or coverage.
+
+## Failure behavior
+
+Planr rejects the result if the process fails or if any required binding does
+not match. This includes a stale request ID, a stale request digest, a wrong
+target, a wrong environment, a wrong execution contract, missing observations,
+extra observations, a schema mismatch, and an unsatisfied expected predicate.
+
+Planr records the failed attempt. Planr does not create a trusted passing
+receipt from that result.
+
+## Version transition
+
+`planr.structured_observation_results.v2` replaces
+`planr.structured_observation_results.v1`. Planr does not keep a second trusted
+compatibility path. Adapter manifests and policy registrations must use the v2
+schema reference and artifact name.