planr 1.10.0-alpha.7 → 1.10.0-alpha.8

package/docs/ARCHITECTURE.md

@@ -61,7 +61,7 @@ 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 fresh verifier lease over a frozen canonical source digest. Product source is read-only; trusted Evidence can commit only through the source-checked Evidence transaction.
+- `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.

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 and responsible-maker repair 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,75 @@
+# 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 click actions for the batch. Each
+  action has `action = "click"`, an accessibility `role`, and an accessibility
+  `name`.
+
+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. Find each click target in the accessibility tree by its role and name.
+3. Click the center of the target's 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.

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.

package/docs/contracts/EVIDENCE_CONTRACT_V1.md

@@ -21,10 +21,101 @@ Evidence Contract v1 is Planr's local-first contract for proving acceptance crit
 - 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 `kind = verification` log is a claim that can be referenced, but it never satisfies a binding observation.
-- A repository without a binding Evidence policy and without binding plan obligations is explicitly non-binding. A binding plan is `binding_unsatisfied` unless its authoritative active obligations match the declared build-plan criterion set exactly: zero, partial, duplicate, or undeclared bindings all fail closed. Planr returns a hold before leasing or creating a FeatureRun, persists a capability hold when an existing run reaches readiness, rejects coverage settlement, closure, final review, and stop activation, and never substitutes logs or an empty receipt lineage.
+- A repository without a binding Evidence policy and without binding plan obligations is explicitly non-binding. A binding plan is `binding_unsatisfied` unless its authoritative active obligations match the declared build-plan criterion set exactly: zero, partial, duplicate, or undeclared bindings all fail closed. Planr returns a hold before leasing or creating a FeatureRun, persists a capability hold when an existing run reaches readiness, rejects coverage settlement, closure, and stop activation, and never substitutes logs or an empty receipt lineage.
 - Migration is the sole obligation-materialization path. It is explicit, plan-scoped, previewable, idempotent, and accepts only an exact declared criterion binding set before materializing 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.
 
+## Binding Execution Orchestration
+
+The normal public success path is one plan-scoped `evidence verify` broker call. The caller identity
+must differ from the responsible maker. Planr uses that identity for the verifier lease, readiness
+admission, adapter execution, coverage evaluation, and FeatureRun settlement. A coordinator or host
+must not spawn another model to perform this mechanical Evidence phase. The lower-level readiness
+and run services remain diagnostic and application primitives; they do not define a second trusted
+workflow.
+
+Before verification admission, FeatureRun source freeze is legal only when no open ordinary
+implementation outcome remains. Planned `code`, `fix`, `docs`, and `test` share the one domain-owned
+maker-compatible classification. An active source-frozen run that still has open ordinary work and
+has no verifier admission, Evidence attempt, or receipt for its immutable freeze is retired only by
+the typed `premature-source-freeze` transition. Retirement preserves the freeze and all Evidence
+history, releases active ordinary leases, and creates no successor. The repository-owned no-model
+`com.planr.premature_freeze.lifecycle.v1` capability is reserved for the final frozen-source HARDEN
+observation; registering it does not execute or satisfy that observation during BUILD.
+
+An active Verification FeatureRun whose current admission is absent or unequal across the active
+plan/run/revision, freeze, verifier worker/generation, optional item, or admitted/sealed run-index
+digest is retired only by the typed `inconsistent-verification` transition. A current item whose
+status or worker does not match the verifier lease is
+`verification_item_ownership_conflict`. Exact equality rejects retirement. One immediate
+optimistic transaction invalidates but preserves the freeze, ends or preserves-ended the referenced
+batch, releases exact roles, Verification reservations, and the exact observed optional item state,
+preserves every prior Evidence/history identity, emits one typed event, and creates no successor.
+Repetition reads that event and writes nothing. The
+repository-owned `com.planr.inconsistent_verification.retirement.v1` capability is registered during
+BUILD but first executes only after HARDEN supplies the exact focused invariant.
+
+`planr.evidence.run-index.v2` is the sole executable run-index shape. Readiness consumes canonical
+authoritative obligation rows and seals exactly one run for every distinct canonical target within
+each obligation. A run names one `obligation_id`, one target, and sorted non-empty unique
+`requirement_ids`. For each obligation, admission recomputes the target partition and requires the
+run subsets to be disjoint and to form the exact union of authoritative observation requirement
+IDs. Requirements from different obligations never share a run.
+
+Execution, structured and ordinary result validation, receipt observation construction, retry
+predecessor validation, independence, hermetic reuse, and persisted attempt/receipt lineage bind
+only the selected requirement subset plus the sealed source, policy, target, capability,
+environment, execution contract, and run-index digest. Extra, missing, duplicate, foreign-target,
+or cross-subset data fails before trusted receipt persistence. `evidence/coverage` remains the sole
+coverage and closure owner; a run-index result is not a coverage verdict.
+
+A multi-target obligation that would execute a `non_repeatable_one_shot` capability fails readiness
+before launch or durable allowance claim. Host capture consumes the same sealed target/subset
+contract as process execution and owns no first-observation or all-targets-equal policy.
+
+Pre-receipt admission failure persists no attempt, receipt, coverage verdict, or ProductFinding.
+One explicit optimistic plan/run/freeze/revision-scoped FeatureRun repair request has a closed
+reason enum and conditional seal binding. Pre-seal `readiness-blocked` and
+`run-index-seal-failed` require `run_index_digest` to be absent; post-seal pre-receipt
+`sealed-run-rejected` and `capability-admission-failed` require the exact admitted digest. A failed
+readiness lease transaction rolls back before Planr persists its durable capability hold and
+diagnostic, so no unusable verifier lease is committed to create repair context. The repair
+invalidates the active freeze, releases verifier ownership and any present verification-item
+lease, restores the original maker at the next lease generation, starts one repair batch, emits one
+repair event, and projects an optional `verification_item_id`. Post-receipt `product_failed` and
+terminal one-shot exhaustion remain their existing distinct lifecycles.
+
+Satisfied plan coverage settles the active FeatureRun by exact verifier lease generation, active
+immutable freeze, and accepted trusted receipt lineage whose source binding exactly equals that
+freeze. A verification map item is a zero-or-one projection. If one item is picked or running under
+the verifier, settlement closes and logs it in the same transaction; if none exists, settlement
+performs zero item/log mutations. A ready unleased verification item remains fail-closed. The
+transition always reconciles the verification budget wall, applies `VerificationPassed` to
+`Complete` when no ordinary work remains (or `Implementation` if ordinary work reopened),
+persists/releases roles through the canonical repository transaction, and emits one event shape
+with nullable `item_id` and `log_id`. Binding coverage settlement returns `next_action: none` on
+completion and creates no final ReviewGate. `planr plan final-review` is a non-binding-plan flow.
+
+Terminal `non_repeatable_one_shot` exhaustion is also zero-or-one item inside the trusted
+attempt/receipt transaction. Attempt/receipt persistence, budget reconciliation, FeatureRun
+cancellation, and verifier release always commit atomically; item failure/logging occurs only when
+one active projection is present, and ready-unleased remains fail-closed.
+
+Post-receipt ProductFinding repair remains distinct from pre-receipt admission repair. The
+application resolves the verification map item as an optional current plan-path projection for
+routing, maker work packets, settlement, idempotent replay, selective-replay handoff, and verifier
+release. Absence performs no item mutation; only a present eligible item is updated. Durable
+ProductRepair settlement persists invalidation/run/maker/selective-obligation/settlement/freeze
+lineage and no item identity. The lifecycle does not reclassify the outcome or create a receipt.
+
+This is a hard cut: run-index v1, first-observation target inference, all-targets-equal checks,
+item-keyed `pick release --repair`, item-required repair, persisted repair-item identity,
+settlement, final-review, and exhaustion ownership, readers, aliases, fallbacks, shims, and runtime
+compatibility do not exist.
+Completed trusted Evidence v1 receipts remain coverage records because coverage is independent of
+run-index orchestration; unexecuted v1 run indexes and in-flight retry lineage lacking the v2
+execution binding are not translated or inferred.
+
 ## Versioning And Compatibility
 
 - `schema_version` for all v1 objects is `evidence.contract.v1`.
@@ -92,7 +183,10 @@ 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.
-- When a capability explicitly declares `repeatability = non_repeatable_one_shot`, Planr derives `max_attempts = 1`; any conflicting caller declaration is rejected before launch. Before the adapter can spawn, Planr atomically claims one durable allowance scoped to the active FeatureRun source freeze. That claim survives process, receipt, or settlement failure, so every later fresh initial, retry, or concurrent contender for the freeze is rejected without spawning. Its committed non-passing attempt (`attempt_index + 1 = max_attempts`), including `product_failed`, atomically exhausts that FeatureRun verification allowance with the attempt and receipt. Planr records `verification_attempts_exhausted`, releases the verifier lease, exposes no next verification action, and does not create a product-finding repair or replay path. Missing or other repeatability values never infer one-shot behavior.
+- When a capability explicitly declares `repeatability = non_repeatable_one_shot`, Planr derives `max_attempts = 1`; any conflicting caller declaration is rejected before launch. Before the adapter can spawn, Planr atomically claims one durable allowance scoped to the active FeatureRun source freeze. That claim survives process, receipt, or settlement failure, so every later fresh initial, retry, or concurrent contender for the freeze is rejected without spawning. Its committed non-passing attempt (`attempt_index + 1 = max_attempts`), including `product_failed`, atomically exhausts that FeatureRun verification allowance with the attempt and receipt. Planr records `verification_attempts_exhausted`, releases the verifier lease, exposes no next verification action, and does not create a product-finding repair or replay path. A projected verification item is optional: when active it is failed/logged atomically; when absent there is no item/log mutation; when ready but unleased the transaction fails closed. Missing or other repeatability values never infer one-shot behavior.
+- Every other capability also defaults to `max_attempts = 1`. A manifest may explicitly admit a larger bounded value only for a repeatable execution contract. Planr never starts a second attempt merely because a verifier or environment failure was returned; a later execution requires a fresh canonical invocation after the reported external state has materially changed.
+- A fresh canonical invocation may append a superseding admission for the same exact active source freeze only when the previously admitted run-index digest already has both a durable Evidence attempt and receipt. The previous admission and execution history remain immutable. A conflicting admission with no execution receipt is pre-receipt state and remains rejected; it cannot bypass Verification Admission Repair.
+- When source is stale after such a receipt, one canonical broker invocation may perform exactly one observed refresh: invalidate and preserve the old freeze and receipt bindings, release the exact verifier lease, freeze the current source, reacquire verification, and seal again. The broker does not repeat this transition if the replacement source becomes stale.
 - 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.

package/docs/contracts/schemas/com.planr.web.dom_state.v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "schema://com.planr.web.dom_state.v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_ref",
+    "selector",
+    "text",
+    "visible"
+  ],
+  "properties": {
+    "schema_ref": {
+      "const": "schema://com.planr.web.dom_state.v1"
+    },
+    "selector": {
+      "type": "string",
+      "minLength": 1
+    },
+    "text": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "visible": {
+      "type": "boolean"
+    }
+  }
+}

package/docs/fixtures/mcp-contract.json

@@ -35,6 +35,7 @@
     "planr_pick_stale",
     "planr_run_restart",
     "planr_run_resolve_budget_hold",
+    "planr_run_repair_verification_admission",
     "planr_recover_sweep",
     "planr_approval_request",
     "planr_approval_approve",
@@ -54,11 +55,12 @@
     "planr_evidence_capability_show",
     "planr_evidence_run",
     "planr_evidence_import",
+    "planr_evidence_host_capture_admit",
     "planr_evidence_host_capture_import",
-    "planr_evidence_host_capture_run",
     "planr_evidence_attempts",
     "planr_evidence_receipts",
     "planr_evidence_coverage",
+    "planr_evidence_verify",
     "planr_evidence_explain",
     "planr_evidence_readiness",
     "planr_evidence_recover_settlement",
@@ -75,6 +77,7 @@
     "planr_review_ingest",
     "planr_review_evidence",
     "planr_review_gate_close",
+    "planr_review_gate_release",
     "planr_review_findings_resolve",
     "planr_close_item",
     "planr_context_create",

package/npm/bin/planr.js

@@ -18,16 +18,40 @@ function platformTarget() {
 }
 
 const target = platformTarget();
-const candidates = [
+const packagedCandidates = [
   process.env.PLANR_NATIVE_BIN,
   // Published package: per-platform binaries bundled at release time.
   target && path.join(here, "..", "native", target, "planr"),
-  // Repository checkout: local cargo builds.
-  path.join(packageRoot, "target", "release", "planr"),
-  path.join(packageRoot, "target", "debug", "planr"),
 ].filter(Boolean);
 
-const binary = candidates.find(candidate => fs.existsSync(candidate));
+function repositoryBuildCandidates() {
+  if (!fs.existsSync(path.join(packageRoot, "Cargo.toml"))) {
+    return [];
+  }
+  const metadata = spawnSync(
+    "cargo",
+    ["metadata", "--no-deps", "--format-version", "1"],
+    { cwd: packageRoot, encoding: "utf8" },
+  );
+  if (metadata.status !== 0) {
+    return [];
+  }
+  try {
+    const targetDirectory = JSON.parse(metadata.stdout).target_directory;
+    if (typeof targetDirectory !== "string" || targetDirectory.length === 0) {
+      return [];
+    }
+    return [
+      path.join(targetDirectory, "release", "planr"),
+      path.join(targetDirectory, "debug", "planr"),
+    ];
+  } catch {
+    return [];
+  }
+}
+
+const binary = packagedCandidates.find(candidate => fs.existsSync(candidate))
+  ?? repositoryBuildCandidates().find(candidate => fs.existsSync(candidate));
 
 if (!binary) {
   if (!target) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.7",
+  "version": "1.10.0-alpha.8",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,7 @@
     "verify:release-script": "node scripts/test-release-script.mjs",
     "verify:change-classifier": "node scripts/test-verification-policy.mjs",
     "verify:runner": "node scripts/test-verification-runner.mjs",
+    "verify:single-session-loop": "node scripts/test-planr-risk-based-guidance.mjs --single-session-loop",
     "verify:ci-router": "node scripts/test-ci-router.mjs",
     "verify:docs-deployment": "node scripts/test-docs-deployment.mjs",
     "classify:changes": "node scripts/classify-changes.mjs",
@@ -64,7 +65,6 @@
     "docs:verify-clean-install": "pnpm --filter @planr/docs verify:clean-install",
     "docs:evidence-examples:generate": "cargo build --bin planr && pnpm --filter @planr/docs evidence-examples:generate",
     "docs:evidence-examples:check": "cargo build --bin planr && pnpm --filter @planr/docs evidence-examples:check",
-    "verify:switchloom-cross-product": "node scripts/verify-switchloom-cross-product.mjs",
     "docs:reference:generate": "cargo build --bin planr && pnpm --filter @planr/docs reference:generate",
     "docs:verify-reference": "cargo build --bin planr && pnpm --filter @planr/docs reference:check && pnpm --filter @planr/docs verify:reference"
   },

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.10.0-alpha.7",
+  "version": "1.10.0-alpha.8",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.7",
+  "version": "1.10.0-alpha.8",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",

package/plugins/planr/agents/pi/planr-worker.md

@@ -20,15 +20,13 @@ Planr rolls its internal three-outcome ExecutionBatch atomically; that boundary
 a host stop. Within that run, do not run binding Evidence readiness, collection,
 or an opportunistic live smoke for a mutable implementation item. Use ordinary
 changed-file checks, keep the same maker through stable source freeze, write a compact durable handoff only at a genuine stop, and stop.
-A fresh verification-only worker first leases `planr pick --plan <plan-id>
---work-type verification --json`, then runs readiness under that same identity and
-executes only `readiness.run_index.repository_path`. Product source remains read-only
-by the canonical Evidence SOURCE_PATHS digest. `planr evidence run` enforces that digest before trusted
+The coordinator runs the handoff packet's `commands.verify` command without another model.
+Product source remains read-only by the canonical Evidence SOURCE_PATHS digest. `planr evidence verify` enforces that digest before trusted
 receipt commit; source mismatch records a failed non-covering attempt and zero
 new trusted receipts. When `mode` is `finding_repair`, repair the named findings
 for the same ReviewGate, log the changed files and commands on its scoped outcome,
 resolve those finding ids, and stop for re-review. No review or fix map item exists.
-Product findings require coordinator re-freeze and leased readiness before selective Evidence replay unless
+Product findings require coordinator re-freeze and another brokered verify call before selective Evidence replay unless
 a material review requires exact-source Evidence earlier. Log changed files and the real verification
 commands you ran. Settle ordinary outcomes with `planr done --next` inside the
 authorized run and plain `planr done` when standalone; Planr materiality decides

package/plugins/planr/agents/planr-worker.md

@@ -22,16 +22,15 @@ empty pick, or budget. Planr rolls its internal three-outcome ExecutionBatch ato
 that boundary is not a host stop.
 Within that run, do not run binding Evidence readiness, collection, or an opportunistic live smoke for a
 mutable implementation item. Use ordinary changed-file checks, keep the same maker
-through stable source freeze, write a compact durable handoff only at a genuine stop, and stop. A fresh
-verification-only worker first leases `planr pick --plan <plan-id> --work-type verification --json`,
-then runs readiness under that same identity and executes only `readiness.run_index.repository_path`.
+through stable source freeze, write a compact durable handoff only at a genuine stop, and stop. The
+coordinator runs the handoff packet's `commands.verify` command without another model.
 Product source remains read-only by the canonical Evidence SOURCE_PATHS digest.
-`planr evidence run` enforces that digest before trusted receipt commit; source
+`planr evidence verify` enforces that digest before trusted receipt commit; source
 mismatch records a failed non-covering attempt and zero new trusted receipts.
 When `mode` is `finding_repair`, repair the named findings for the same ReviewGate,
 log the changed files and commands on its scoped outcome, resolve those finding ids,
 and stop for re-review. No review or fix map item exists. Product findings require
-coordinator re-freeze and leased readiness before selective Evidence replay unless a material review requires
+coordinator re-freeze and another brokered verify call before selective Evidence replay unless a material review requires
 exact-source Evidence earlier.
 Log changed files and the real verification commands you ran. Settle ordinary outcomes
 with `planr done --next` inside the authorized run and plain `planr done` when standalone;

package/plugins/planr/skills/planr/SKILL.md

@@ -45,7 +45,7 @@ Evaluate top to bottom; pick the first row that matches both intent and state:
 | new idea, PRD, scope, architecture | no plan, or plan needs refinement | `planr-plan` |
 | new feature, refactor, or fix on an existing project | project exists, scope has no plan yet | `planr-plan` (feature-scoped plan, then extend the map) |
 | plan exists but no map / map needs structure, dependencies, breakdown | build plan checked, map missing or stale | `planr-task-graph` |
-| ReviewGate pending or leased | open gate in the active FeatureRun | `planr-review` |
+| ReviewGate pending or leased | explicit material gate in the active FeatureRun | `planr-review` |
 | ReviewGate has findings | active FeatureRun returns `work_packet.mode: "finding_repair"` to its responsible maker | `planr-work` |
 | implement, fix, continue work | ready items exist on the map | `planr-work` |
 | implement, but nothing is ready | all items blocked | `planr-status`, then report blockers to the user |
@@ -54,7 +54,7 @@ Evaluate top to bottom; pick the first row that matches both intent and state:
 
 - Route to exactly one skill per dispatch. If the request spans stages (idea -> running feature), route to `planr-loop` and let the loop sequence the stages.
 - Explicit delivery language such as "implement", "work autonomously until complete", or "finish this" outranks missing plan or map state and routes to `planr-loop`. Never turn a delivery request into a prep-only handoff.
-- Never skip a stage: no map items without a checked build plan, no FeatureRun completion without its required ReviewGates, and no review verdict without evidence.
+- Never skip a stage: no map items without a checked build plan, no FeatureRun completion without Binding Evidence or any explicitly required material ReviewGates, and no review verdict without evidence.
 - When delegating to a subagent, prompt it with a skill reference plus item id (for example: `Use $planr-work on item <id>`), never with a hand-written workflow prompt.
-- The maker never reviews its own work. Reviews run through `planr-review` in a separate agent or subagent whenever the host supports it.
+- The maker never reviews its own material ReviewGate. Reviews run through `planr-review` in a separate agent or subagent only when the plan or a protected-risk transition explicitly requires one.
 - If intent is genuinely ambiguous and state allows multiple routes, ask the user one short question instead of guessing.