planr 1.10.0-alpha.9 → 2.0.0

package/docs/contracts/EVIDENCE_ADAPTER_PROTOCOL_V1.md

@@ -1,98 +0,0 @@
-# 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

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

package/docs/contracts/GROK_INTEGRATION_V1.md

@@ -1,139 +0,0 @@
-# Grok Build Integration Contract v1
-
-Status: frozen for implementation
-
-Frozen: 2026-07-27
-
-Upstream source probe: `xai-org/grok-build` commit
-`b41c75a578f98bddbd326ab02cd53618451d97ee` (2026-07-26)
-
-This contract is the implementation boundary for first-class Grok Build support.
-It reconciles the public xAI documentation, the locally cloned upstream source,
-and Planr's local-first integration rules. Live authenticated verification is a
-separate maintainer-local release gate; it never runs in CI.
-
-## Frozen artifact and discovery policy
-
-`planr install grok` owns exactly the repository paths in the executable
-contract below. Workflow files are copied byte-for-byte from the canonical
-`plugins/planr` sources. There is no second Grok-specific workflow body.
-
-Planr does **not** emit `.grok/plugins/planr` or a Grok plugin manifest in v1.
-Current Grok source discovers project plugins from `.grok/plugins`, but project
-plugins default to disabled and project `.grok/config.toml` does not merge
-`[plugins].enabled`. A repository-local plugin would therefore require
-user-level enablement and would not satisfy one-command project setup. Native
-`.grok/skills/<name>/` and `.grok/agents/*.md` are documented, directly
-discovered project paths and do not depend on Claude compatibility scanners.
-
-Grok's current manifest lookup is still relevant for troubleshooting: a plugin
-root checks `plugin.json`, then `.grok-plugin/plugin.json`, then
-`.claude-plugin/plugin.json`, and finally convention-based component folders.
-That behavior is observed upstream but deliberately not used by Planr v1.
-
-```json
-{
-  "contract_version": 1,
-  "upstream_revision": "b41c75a578f98bddbd326ab02cd53618451d97ee",
-  "artifacts": [
-    {"target": ".grok/config.toml", "source": "generated:grok_project_config", "kind": "mcp"},
-    {"target": ".grok/agents/planr-reviewer.md", "source": "plugins/planr/agents/planr-reviewer.md", "kind": "agent"},
-    {"target": ".grok/agents/planr-worker.md", "source": "plugins/planr/agents/planr-worker.md", "kind": "agent"},
-    {"target": ".grok/skills/planr-goal/SKILL.md", "source": "plugins/planr/skills/planr-goal/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-loop/SKILL.md", "source": "plugins/planr/skills/planr-loop/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-loop/agents/planr-reviewer.md", "source": "plugins/planr/skills/planr-loop/agents/planr-reviewer.md", "kind": "skill_asset"},
-    {"target": ".grok/skills/planr-loop/agents/planr-worker.md", "source": "plugins/planr/skills/planr-loop/agents/planr-worker.md", "kind": "skill_asset"},
-    {"target": ".grok/skills/planr-loop/references/host-dispatch.md", "source": "plugins/planr/skills/planr-loop/references/host-dispatch.md", "kind": "skill_asset"},
-    {"target": ".grok/skills/planr-loop/references/recovery-and-verification.md", "source": "plugins/planr/skills/planr-loop/references/recovery-and-verification.md", "kind": "skill_asset"},
-    {"target": ".grok/skills/planr-plan/SKILL.md", "source": "plugins/planr/skills/planr-plan/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-review/SKILL.md", "source": "plugins/planr/skills/planr-review/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-status/SKILL.md", "source": "plugins/planr/skills/planr-status/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-summary/SKILL.md", "source": "plugins/planr/skills/planr-summary/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-task-graph/SKILL.md", "source": "plugins/planr/skills/planr-task-graph/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-verify-web/SKILL.md", "source": "plugins/planr/skills/planr-verify-web/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr-work/SKILL.md", "source": "plugins/planr/skills/planr-work/SKILL.md", "kind": "skill"},
-    {"target": ".grok/skills/planr/SKILL.md", "source": "plugins/planr/skills/planr/SKILL.md", "kind": "skill"}
-  ],
-  "mcp": {
-    "table": "mcp_servers.planr",
-    "command": "planr",
-    "args": ["mcp"],
-    "enabled": true,
-    "startup_timeout_sec": 30,
-    "tool_timeout_sec": 6000,
-    "env": {"PLANR_MCP_CLIENT": "grok"},
-    "forbidden_fields": ["XAI_API_KEY", "api_key", "auth", "model", "headers", "url"]
-  },
-  "plugin": {
-    "emitted": false,
-    "project_root": ".grok/plugins",
-    "manifest_precedence": ["plugin.json", ".grok-plugin/plugin.json", ".claude-plugin/plugin.json", "convention"],
-    "project_default": "disabled",
-    "project_config_enabled_merged": false
-  },
-  "hooks": {"supported": false, "artifacts": []},
-  "client_all_includes_grok": false,
-  "headless": {"command": "grok --no-auto-update -p \"<prompt>\" --output-format json"}
-}
-```
-
-The generated `.grok/config.toml` table is therefore:
-
-```toml
-[mcp_servers.planr]
-command = "planr"
-args = ["mcp"]
-enabled = true
-startup_timeout_sec = 30
-tool_timeout_sec = 6000
-env = { PLANR_MCP_CLIENT = "grok" }
-```
-
-`PLANR_MCP_CLIENT=grok` is a narrow adapter marker applied by Grok's MCP
-launcher to the Planr child process. Planr may use the exact value as an
-advisory observed-client signal. It is not authentication, authorization, or a
-general worker identity. Ambient `GROK_*` variables are not accepted as the v1
-signal because the probed Grok MCP launcher does not inject a stable one.
-
-## Merge and overwrite policy
-
-- Missing `.grok/config.toml`: create it with only the Planr MCP table.
-- Existing valid config: perform a document-preserving TOML merge. Preserve
-  every foreign table, key, comment, and order; only `mcp_servers.planr` is
-  owned by Planr.
-- Existing different `mcp_servers.planr`: without `--force`, preserve it and
-  report a conflict; with `--force`, replace only that table.
-- Malformed config: fail with a path-and-parse diagnostic and write nothing,
-  including under `--force`.
-- Workflow target missing: write the canonical source. Existing identical
-  content is unchanged. Existing different content is preserved without
-  `--force` and replaced from the canonical source with `--force`.
-- `--no-mcp` omits `.grok/config.toml` reconciliation. `--no-hooks` is accepted
-  for CLI parity but changes no Grok paths because v1 installs no hooks.
-- Dry-run enumerates the same paths the corresponding write would reconcile.
-
-## Security and CI boundary
-
-Repository artifacts contain no xAI credential, token, auth-file path, model
-selection, endpoint, or absolute maintainer path. Planr never reads or copies
-`~/.grok`, `$GROK_HOME`, session data, `auth.json`, or
-`mcp_credentials.json` while installing.
-
-GitHub Actions and release workflows must not install or invoke Grok, reference
-`XAI_API_KEY`, gate on an xAI secret, or perform live inference. Deterministic
-tests parse and compare generated files without Grok installed. Maintainer-local
-release verification may use an existing login, but recorded evidence is
-limited to redacted discovery/origin, diagnostics, and the disposable Planr
-project identity.
-
-The supported inspection and headless syntax is `grok inspect --json` and
-`grok --no-auto-update -p "<prompt>" --output-format json`; `grok exec` is not part of this contract.
-
-## Sources
-
-- https://docs.x.ai/build/features/skills-plugins-marketplaces
-- https://docs.x.ai/build/settings
-- https://docs.x.ai/build/features/mcp-servers
-- https://docs.x.ai/build/cli/reference
-- https://docs.x.ai/build/cli/headless-scripting
-- https://github.com/xai-org/grok-build/tree/b41c75a578f98bddbd326ab02cd53618451d97ee

package/docs/contracts/LINUX_RELEASE_PORTABILITY.json

@@ -1,9 +0,0 @@
-{
-  "affectedReleases": [
-    "1.7.2"
-  ],
-  "affectedThrough": "1.7.2",
-  "correctedFrom": "1.7.3",
-  "noticeSchema": 1,
-  "status": "corrected"
-}