planr 1.10.0-alpha.13 → 1.10.0-alpha.14

package/docs/contracts/BROWSER_HARNESS_ADAPTER_V1.md

@@ -1,6 +1,8 @@
 # Browser Harness adapter v1
 
-Status: frozen for `planr-browser-harness-adapter` v1.
+Status: historical. The current adapter hard-cuts to
+`BROWSER_HARNESS_ADAPTER_V2.md`; it does not accept this v1 payload schema or
+its shared-action/final-observation execution shape.
 
 This reference defines Planr's first process adapter for the external
 `browser-harness` tool. The adapter implements
@@ -76,10 +78,7 @@ 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
+## Historical 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.
+The executable v1 fixture was removed with the v2 hard cut. The maintained
+provider-free fixture lives under `tests/fixtures/evidence/browser-harness/v2/`.

package/docs/contracts/BROWSER_HARNESS_ADAPTER_V2.md

@@ -0,0 +1,120 @@
+# Browser Harness adapter v2
+
+Status: frozen for `planr-browser-harness-adapter` v2.
+
+This reference defines Planr's provider-neutral process adapter for the
+external `browser-harness` tool. The adapter implements
+`EVIDENCE_ADAPTER_PROTOCOL_V1.md`. Planr Core owns execution and trust; this
+adapter owns only the closed browser scenario and its structured observations.
+
+## Capability
+
+The adapter supports `com.planr.web.dom_state` observations with payload schema
+`schema://com.planr.web.dom_state.v2`.
+
+Every requirement uses a CSS selector in `subject`. Its `expected` object may
+select only these mechanically observed fields:
+
+- exact normalized `text` and rendered `visible` state;
+- `contains_text` and `excludes_text` lists;
+- a named local-storage document's presence, transaction count, and equality
+  to an earlier scenario snapshot;
+- selected option text keyed by visible select label;
+- unnamed-control and unlabelled-field counts;
+- horizontal page overflow;
+- browser runtime/console error and external-request counts.
+
+Exactly one requirement in a batch carries a closed `state_transitions`
+declaration with `scenario_id` and `steps`. Every sibling carries only the
+matching `scenario_ref`; declaration position has no semantic meaning. This
+keeps one sealed scenario in the work packet without making the first
+observation an authority or duplicating a large action list. All requirements
+use the same optional execution method. The scenario contains 1 to 256 steps
+from this exact action set:
+
+- `fill` or `select` one control by CSS `subject` or exact visible `label`;
+- `click` one control by accessibility role and name (or the closed
+  button-or-link role `control`), optionally within a container containing
+  exact scope text;
+- `reset` one named application storage key and navigate the bound target;
+- `snapshot_storage` under one bounded scenario-local ID;
+- `reload` the current document;
+- `viewport` with a bounded width and height;
+- `checkpoint` with one or more sealed requirement IDs and an optional prior
+  storage snapshot comparison.
+
+There must be exactly one declaration and every reference must resolve to it.
+Checkpoint requirement IDs are unique across the scenario and their union must
+equal the exact sealed batch requirement set. A checkpoint can reference only
+a storage snapshot created earlier in the same scenario. Arbitrary JavaScript,
+unknown actions, unsealed requirements, mixed scenarios, mixed execution
+methods, and foreign targets are rejected before Browser Harness starts.
+
+## 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 capability manifest can allow the Browser Harness connection variables,
+including `BU_NAME`, `BU_CDP_URL`, and `BU_CDP_WS`. Planr binds the captured
+connection configuration to the capability instance and forwards it through
+the process environment only when the host independently names each variable in
+`PLANR_ADAPTER_ENV_ALLOWLIST`. If no connection variable is present, Browser
+Harness uses its configured default connection. Planr does not infer or start a
+browser product. A host may additionally classify local, non-secret connection
+configuration in `PLANR_ADAPTER_PUBLIC_ENV_ALLOWLIST`. Remote endpoints or
+credentials remain non-public unless the host explicitly decides otherwise.
+
+The program:
+
+1. Opens one blank tab and enables Page, Runtime, Network, and Log observation.
+2. Navigates to the exact Planr-bound HTTP or HTTPS target.
+3. Executes the one sealed scenario in that tab.
+4. At each checkpoint, stabilizes and evaluates all named requirements
+   together for at most 750 ms.
+5. Applies one 15-second total scenario deadline; it never applies a separate
+   timeout per requirement.
+6. Returns one structured result containing exactly one actual for every
+   sealed requirement.
+7. Closes the tab on every exit path.
+
+The generated program inserts scenario and requirement data only as JSON. A
+requirement cannot add executable Python or JavaScript.
+
+## Result and trust
+
+Each actual conforms to
+`docs/contracts/schemas/com.planr.web.dom_state.v2.schema.json`. Planr Core
+validates the schema and evaluates the expected predicate independently for
+each requirement. One failed checkpoint observation therefore produces a
+trusted non-passing receipt without discarding passing siblings.
+
+If every requirement selects the `browser-harness` agent skill, the adapter
+also returns the matching supervised invocation record. This record becomes
+trusted only after Planr validates the observed process and every sealed
+binding. It never assigns provenance or coverage itself.
+
+## Capture and resource policy
+
+The successful path disables Browser Harness recordings and does not capture
+screenshots or traces. Structured DOM, storage, selection, accessibility,
+layout, runtime, and request observations are the retained proof for this
+non-visual capability. The adapter uses one tab and one Browser Harness process
+per batch.
+
+The adapter does not advertise a visual observation type. Screenshots cannot
+upgrade this capability into visual Evidence.
+
+## Version transition
+
+V2 is a hard cut. The active adapter accepts only
+`schema://com.planr.web.dom_state.v2` and the exact checkpoint scenario. It has
+no runtime fallback for v1 shared actions followed by independent five-second
+polls. Historical v1 receipts remain immutable records; they do not create a
+second active adapter path.
+
+## Canonical live fixture
+
+`tests/fixtures/evidence/browser-harness/v2/form.html` and
+`form-request.json` exercise the provider-free live boundary: one existing HTTP
+target, one Browser Harness session, bounded label-driven actions, one explicit
+checkpoint, one structured DOM postcondition, and no model provider.

package/docs/contracts/EVIDENCE_ADAPTER_PROTOCOL_V1.md

@@ -27,10 +27,40 @@ 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
+Planr reserves the complete `PLANR_` environment variable namespace. An adapter
 request does not use environment variables for target, environment, or contract
 bindings.
 
+A process capability can declare `permissions.environment` as
+`read_env:NAME[,NAME]`. This repository-authored declaration is necessary but
+not sufficient. The host or user must independently include every requested
+name in `PLANR_ADAPTER_ENV_ALLOWLIST`; repository content cannot change that
+authorization. A manifest that reads host variables must also declare
+`permissions.secrets = host_allowlist` to acknowledge that values remain
+host-authorized even when a variable name appears non-secret.
+
+Planr captures only the intersection of the manifest request and the host
+authorization. The capability instance and sealed run index bind the variable
+names, the host's public/non-public classification, and a digest of the present
+values. Planr does not persist the values in that binding. At execution, Planr
+clears the process environment, adds `PATH`, and forwards the captured values. A
+changed value, classification, or host authorization invalidates the sealed run
+before the adapter starts. Requested names in the complete `PLANR_` namespace
+are invalid because only Planr Core can own that namespace.
+
+Forwarded values are non-public by default. The host may independently list
+known non-secret configuration names in `PLANR_ADAPTER_PUBLIC_ENV_ALLOWLIST`.
+This list does not authorize access; it must remain a subset of the names that
+the manifest requests and `PLANR_ADAPTER_ENV_ALLOWLIST` authorizes. Before
+result validation, Planr rejects an adapter result that exposes an exact
+non-public value, records `verifier_failed`, and redacts that value from durable
+stdout and stderr excerpts while retaining the digests of the observed output.
+Forwarded adapter values are never passed to a supervised target process.
+
+This allowlist configures the adapter transport. It does not replace the
+`target`, `environment`, or `execution_contract_digest` fields in the sealed
+request.
+
 ## `planr.evidence.adapter-request.v1`
 
 The request has these fields:
@@ -85,10 +115,22 @@ provenance or coverage.
 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.
+extra observations, or a schema mismatch.
+
+An `actual` object that is valid for its registered payload schema but does not
+satisfy the requirement's expected predicate is a product observation, not a
+protocol rejection. Planr preserves that validated `actual`, assigns `failed`
+only to that observation, records `product_failed` for its coverage gap, and
+creates a trusted non-passing receipt. Other observations from the same exact
+execution retain their own validated outcomes. The containing attempt is
+failed when any selected observation fails.
+
+Planr records failed attempts. A runtime target binding failure is
+`target_mismatch`; malformed or schema-invalid observation data is
+`schema_mismatch`. Neither code may replace `product_failed`, and one failed
+observation may not contaminate sibling observations with a receipt-wide gap.
+No non-passing result can create a trusted passing receipt or satisfy complete
+coverage.
 
 ## Version transition
 

package/docs/contracts/EVIDENCE_CONTRACT_V1.md

@@ -190,7 +190,8 @@ Required fields:
 - 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 repository adapter registration may additionally declare one exact `execution_contract.target_lifecycle` with `kind = supervised_process`, a bare executable, arguments, an optional repository-relative working directory, and bounded TCP readiness. The repository or user owns that command; Planr never infers a framework or package manager. When omitted, the target remains externally managed. When present, Planr requires the sealed loopback endpoint to be unreachable before launch, resolves and starts the declared process only after Evidence admission, waits for that endpoint to become ready, runs the adapter, and tears down the complete target process tree on every exit path. Startup, readiness, or premature-exit failure produces a failed attempt with `external_dependency_unavailable`; it cannot satisfy coverage.
+- A process capability may declare `permissions.environment = read_env:NAME[,NAME]` together with `permissions.secrets = host_allowlist`. The host or user must independently authorize every requested name through `PLANR_ADAPTER_ENV_ALLOWLIST`; a repository declaration alone cannot expose a host value. Planr forwards only present values in that intersection to the Evidence adapter, never to a supervised product target. Forwarded values are non-public by default; the host may classify known non-secret configuration names through `PLANR_ADAPTER_PUBLIC_ENV_ALLOWLIST`, which never grants read access by itself. The capability environment and sealed run index bind the requested names, public classification, and a digest of the values. A value, classification, or authorization change makes the sealed adapter environment stale. The binding never stores raw values, the complete `PLANR_` namespace is reserved, and an adapter output that contains an exact non-public forwarded value fails closed and is redacted before result validation.
+- A repository adapter registration may additionally declare one exact `execution_contract.target_lifecycle` with `kind = supervised_process`, a bare executable, arguments, an optional repository-relative working directory, and bounded TCP readiness. The repository or user owns that command; Planr never infers a framework or package manager. When omitted, the target remains externally managed. When present, Planr requires the sealed loopback endpoint to be unreachable before launch, resolves and starts the declared process only after Evidence admission, waits for that endpoint to become ready, runs the adapter, and tears down the complete target process tree on every exit path. On Unix, Planr observes leader exit without reaping it, terminates the still-identity-anchored process group, and only then reaps the leader; it never signals a released numeric process-group ID. Startup, readiness, or premature-exit failure produces a failed attempt with `external_dependency_unavailable`; it cannot satisfy coverage.
 - Availability probes cannot declare a target lifecycle. They test only whether the Evidence capability itself is available and never start the product under verification.
 
 A manifest is a claim about what a method can observe. It is not proof that the method is available now.
@@ -246,6 +247,16 @@ Required fields:
 
 Receipts can satisfy coverage only when trusted, fresh, policy-compliant, target-matched, schema-valid, and observation-equivalent to the requirement.
 
+`receipt_status = trusted` describes provenance and binding integrity, not a
+passing product result. One Planr-observed execution may produce one trusted
+receipt with mixed observation outcomes. Every schema-valid `actual` is
+preserved and evaluated independently: a satisfied predicate is `passed`; an
+unsatisfied predicate is `failed` with the canonical `product_failed` coverage
+gap. Mixed siblings do not inherit that gap. Complete coverage remains
+unsatisfied until every binding observation is covered by a passing result.
+Target-binding errors remain `target_mismatch`; malformed or schema-invalid
+observation payloads remain `schema_mismatch`.
+
 ### CoverageVerdict
 
 The canonical coverage result for a criterion, item, plan, or goal.
@@ -296,6 +307,10 @@ Policy layers may strengthen lower-level requirements. Weakening requires an exp
 
 - `trusted`, `rejected`, `untrusted`, `stale`, `superseded`.
 
+Receipt status and observation outcome are orthogonal. In particular,
+`trusted` never means `passed`; it can identify a trusted non-passing receipt
+whose validated observations include one or more `failed` outcomes.
+
 `VerificationCapabilityInstance.availability.status` values:
 
 - `available`, `unavailable`, `degraded`, `permission_denied`, `sandbox_blocked`, `unsupported`, `probe_failed`.

package/docs/contracts/fixtures/evidence/v1/schemas/evidence-contract-v1.schema.json

@@ -847,10 +847,17 @@
           "$ref": "#/$defs/JsonObject"
         },
         "state_transitions": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/JsonObject"
-          }
+          "oneOf": [
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/JsonObject"
+              }
+            },
+            {
+              "$ref": "#/$defs/JsonObject"
+            }
+          ]
         },
         "persistence": {
           "$ref": "#/$defs/JsonObject"

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

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "schema://com.planr.web.dom_state.v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_ref",
+    "selector",
+    "text",
+    "visible",
+    "contains_text",
+    "excludes_text",
+    "storage",
+    "selected",
+    "accessibility",
+    "layout",
+    "runtime"
+  ],
+  "properties": {
+    "schema_ref": {
+      "const": "schema://com.planr.web.dom_state.v2"
+    },
+    "selector": {
+      "type": "string",
+      "minLength": 1
+    },
+    "text": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "visible": {
+      "type": "boolean"
+    },
+    "contains_text": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "excludes_text": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "storage": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "key",
+            "present",
+            "transaction_count",
+            "matches_snapshot"
+          ],
+          "properties": {
+            "key": {
+              "type": "string",
+              "minLength": 1
+            },
+            "present": {
+              "type": "boolean"
+            },
+            "transaction_count": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "matches_snapshot": {
+              "type": "boolean"
+            }
+          }
+        }
+      ]
+    },
+    "selected": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "accessibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "unnamed_controls",
+        "unlabelled_fields"
+      ],
+      "properties": {
+        "unnamed_controls": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unlabelled_fields": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "horizontal_overflow"
+      ],
+      "properties": {
+        "horizontal_overflow": {
+          "type": "boolean"
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "error_count",
+        "external_request_count"
+      ],
+      "properties": {
+        "error_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "external_request_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.13",
+  "version": "1.10.0-alpha.14",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {

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.13",
+  "version": "1.10.0-alpha.14",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.13",
+  "version": "1.10.0-alpha.14",
   "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",