planr 1.10.0-alpha.2 → 1.10.0-alpha.4

package/docs/ARCHITECTURE.md

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

package/docs/RELEASE.md

@@ -25,7 +25,9 @@ full candidate verification and independent review on that exact commit.
 `scripts/release.sh` is the only supported publication path. It runs on clean
 `main`, requires every version and generated reference to already match the
 requested version, verifies an independently green CI run and human approval
-for the exact `HEAD` SHA, and only then creates and pushes the annotated tag.
+for the exact `HEAD` SHA, and verifies that the changelog predecessor's local
+tag object exactly matches the tag ref returned by `origin`. Only then does it
+create and push the annotated tag.
 It does not replay the Rust, docs, or packaging suites already proven by that
 CI run. Security, secret, dependency, and workflow scanners are deliberate
 local maintainer preflight commands rather than automatic pull-request or push
@@ -49,8 +51,9 @@ contains only `approval_id`, `source_sha`, `version`, `decision: "approved"`,
 queries the recorded GitHub Actions run and rejects a stale SHA, non-main or
 non-push run, failed conclusion, repository mismatch, or non-approved decision.
 
-External evaluation is conditional. When the evaluated workflow subject or its
-explicit evaluation policy changed since the previous release tag, also set:
+External evaluation is a stable-release gate. When the evaluated workflow
+subject or its explicit evaluation policy changed since the previous release
+tag, a stable release also requires:
 
 ```bash
 export PLANR_RELEASE_EVAL_SUITE="$HOME/projects/planr-evals/suites/planr-lean-skills-dogfood.suite.json"
@@ -94,8 +97,8 @@ The two scripts enforce, in order:
 3. frozen workspace synchronization cannot change `pnpm-lock.yaml`;
 4. the candidate build synchronizes `Cargo.lock`, then regenerates and strictly checks both references without Git mutation;
 5. candidate source, changelog, contracts, and generated files are committed and independently reviewed before publication approval;
-6. publication requires clean `main`, the exact prepared versions/references, a committed changelog section, and no existing tag;
-7. publication validates the exact-SHA CI and approval receipts; when the evaluated subject or policy changed, the reviewed candidate binary also validates the sanitized eval receipt and recomputed comparison;
+6. publication requires clean `main`, the exact prepared versions/references, a committed changelog section, an exact local predecessor tag matching `origin`, and no existing target tag;
+7. publication validates the exact-SHA CI and approval receipts; a stable release whose evaluated subject or policy changed also validates the sanitized eval receipt and recomputed comparison;
 8. publication creates and pushes only the annotated `vx.y.z` tag for that reviewed commit.
 
 Two independent gates back the script:
@@ -122,7 +125,18 @@ The changelog section requirement applies verbatim (`## [1.2.0-alpha.1]`). What
 - npm publishes under the **`alpha` dist-tag** instead of `latest`: plain `npm install -g planr` keeps resolving stable, testers opt in with `npm install -g planr@alpha`.
 - The **Homebrew tap never moves** on pre-release tags.
 
-Only `-alpha.N`, `-beta.N`, and `-rc.N` suffixes are accepted; everything else the script rejects.
+Only canonical SemVer core numbers and `-alpha.N`, `-beta.N`, or `-rc.N`
+suffixes are accepted. Numeric identifiers have no leading zero unless the
+identifier is exactly `0`.
+
+Pre-release publication deliberately does not require a model-evaluation
+receipt before publication. It still requires a clean exact commit on `main`,
+the authenticated green CI promotion receipt, human approval bound to that SHA
+and version, synchronized manifests and generated references, and the committed
+changelog/release contracts. After publication, install that exact prerelease
+and dogfood the installed artifact. That dogfood evidence informs and gates the
+next promotion decision; it is never fabricated from the pre-publication source
+tree. Stable publication keeps the conditional evaluation gate described above.
 
 ## Automated Release Pipeline
 

package/docs/SWITCHLOOM_COMPATIBILITY.md

@@ -35,7 +35,7 @@ Future Switchloom work, including thread `019f8a71-5b6c-7c41-9850-7050516fcee4`,
 
 The stable compatibility promise is limited to Planr's boundary: consume provider-neutral declarations when present, keep requested values separate from effective evidence, reject requested-only metadata as proof, avoid owning external lifecycle, and continue operating when routing files are absent.
 
-Any future mismatch in package identity, generated artifacts, Planr declaration parsing, route-audit semantics, host evidence, source-worktree mutation, or security posture should become a new finding or fix item rather than an optimistic compatibility claim.
+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
 

package/docs/contracts/EVAL_CONTRACT_V1.md

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

package/docs/contracts/EVIDENCE_CONTRACT_V1.md

@@ -1,8 +1,8 @@
 # Evidence Contract v1
 
-Status: frozen for implementation
+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.
+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
 
@@ -88,6 +88,7 @@ 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.
 - 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/V1_1_DIFFERENTIATION_CONTRACT.md

@@ -6,7 +6,7 @@ Generated: 2026-06-09
 
 This contract defines the Planr-owned V1.1 acceptance baseline. It turns the remaining product gaps into implementation-ready requirements without relying on external product names, copied command vocabulary, or hidden context.
 
-V1.1 is complete only when Planr can prove these capabilities from its own CLI, MCP, HTTP, local review workspace, docs, tests, and real consumer usage.
+V1.1 is complete only when Planr can prove these capabilities from its own CLI, MCP, HTTP, durable FeatureRun/ReviewGate state, docs, tests, and real consumer usage.
 
 ## Product Outcome
 
@@ -38,7 +38,7 @@ Acceptance:
 ### Automatic Pick Recall
 
 - REQ-V11-RECALL-001: `planr pick` and `planr_pick_item` must return a compact task-start package.
-- REQ-V11-RECALL-002: The package must include ranked relevant project contexts, upstream logs or handoffs, linked plan references, active blockers or unlocks, review/fix history, and deeper-read commands.
+- REQ-V11-RECALL-002: The package must include ranked relevant project contexts, upstream logs or handoffs, linked plan references, active blockers or unlocks, ReviewGate history, and deeper-read commands.
 - REQ-V11-RECALL-003: Recall ranking must search item title, description, linked plan metadata, contexts, logs, and review summaries.
 - REQ-V11-RECALL-004: Pick recall must be size-bounded and avoid source file content, prompt transcripts, secret-looking values, and large artifacts by default.
 - REQ-V11-RECALL-005: Possible file conflicts must be surfaced from recent logs, artifacts, and active picked/running work when enough path evidence exists.
@@ -64,19 +64,19 @@ Acceptance:
 - A failed retryable item returns to ready only after the documented delay.
 - A postcondition appears in review and close-preview output before the item closes.
 
-### Local Browser Review Workspace
+### Durable FeatureRun Review Gates
 
-- REQ-V11-REVIEW-UI-001: Planr must ship a local browser workspace reachable from the local HTTP server or an explicit CLI command.
-- REQ-V11-REVIEW-UI-002: The workspace must support plan/package review, plan revision diff, item review detail, inline annotations, and approve/request-changes feedback.
-- REQ-V11-REVIEW-UI-003: When Git evidence is available, the workspace must show scoped file changes or a clear explanation of missing diff context.
-- REQ-V11-REVIEW-UI-004: Feedback must write Planr review annotations, review artifacts, and map-native fix/follow-up review items through existing review rules.
-- REQ-V11-REVIEW-UI-005: The workspace must remain local-first and must not require a hosted account or network service.
+- REQ-V11-REVIEW-001: FeatureRun settlement must create or reuse durable ReviewGates according to materiality and structured escalation policy.
+- REQ-V11-REVIEW-002: ReviewGate attempts must record independent reviewer identity, verdict, findings, and immutable attempt history.
+- REQ-V11-REVIEW-003: When Git evidence is available, review evidence must show scoped file changes or a clear explanation of missing diff context.
+- REQ-V11-REVIEW-004: Findings must pause settlement, remain durable on the gate, and return the same gate to pending re-review only after explicit resolution.
+- REQ-V11-REVIEW-005: Final product review must use exactly one accepted independent plan-scoped ReviewGate and project consistently through CLI, MCP, HTTP, audit, status, package, and trace surfaces.
 
 Acceptance:
 
-- A reviewer can open a local URL, annotate a plan or item, request changes, and see the map create follow-up work.
-- A clean review can write an artifact and close the review item through Planr state.
-- Browser smoke tests prove the workspace renders and can exercise the annotation flow.
+- A reviewer can lease a ReviewGate, inspect scoped evidence, and record either acceptance or durable findings.
+- A maker can resolve named findings and the same gate becomes available for independent re-review.
+- An accepted final ReviewGate makes the canonical plan audit clause pass without creating review/fix map items.
 
 ### Scoped Git And PR Review
 
@@ -89,8 +89,8 @@ Acceptance:
 Acceptance:
 
 - A dirty worktree with unrelated files does not let an agent claim broad ownership.
-- Review artifacts show which files were considered and which were excluded.
-- File and line annotations survive export/import.
+- ReviewGate attempts show which evidence was considered and which files were excluded.
+- Durable findings and file/line annotations survive package projection.
 
 ### Distribution And Client Setup
 
@@ -109,10 +109,10 @@ Acceptance:
 
 ### Templates And Review Packages
 
-- REQ-V11-TEMPLATE-001: Export/import must support map items, links, plans, contexts, logs, review artifacts, and metadata.
+- REQ-V11-TEMPLATE-001: Export/import must support map items, links, plans, contexts, logs, durable ReviewGate projections, and metadata.
 - REQ-V11-TEMPLATE-002: Templates must include package requirements metadata, Planr version, creation timestamp, source project name, and optional tags.
 - REQ-V11-TEMPLATE-003: Import must preview what will be created or skipped before mutating existing projects.
-- REQ-V11-TEMPLATE-004: Review packages must preserve annotations, findings, artifacts, and file references.
+- REQ-V11-TEMPLATE-004: Review packages must preserve ReviewGate attempts, findings, annotations, and file references.
 - REQ-V11-TEMPLATE-005: Encrypted local bundle sharing may be implemented without hosted infrastructure; if not implemented in V1.1, docs must capture the accepted local-first format and explicit future scope.
 
 Acceptance:
@@ -149,7 +149,7 @@ Required repository checks:
 - `scripts/ci-local.sh`
 - MCP stdio contract smoke
 - HTTP/SSE smoke
-- local browser review workspace smoke
+- durable ReviewGate cross-surface smoke
 - forbidden-reference scrub over public repo paths
 
 Required consumer checks in `~/projects/planr-test`:

package/docs/contracts/fixtures/evidence/v1/examples/evidence-policy.json

@@ -1,7 +1,7 @@
 {
   "id": "epolicy-default-v1",
   "schema_version": "evidence.contract.v1",
-  "policy_digest": "sha256:c1a2a26ece3ee7a3cf3166cd849664d723fe2fffda2dc0773b2c92dc8d1ae8c1",
+  "policy_digest": "sha256:4dc9ebefae0d8334a19d958a456d5633d615025e7643f999dfda6d4c30bfc613",
   "defaults": {
     "preset_id": "preset-http-health",
     "binding": true,
@@ -23,15 +23,6 @@
           "target": {
             "kind": "local_service",
             "uri": "http://127.0.0.1:4173/health"
-          },
-          "environment": {
-            "kind": "local",
-            "id": "dev-shell",
-            "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-          },
-          "runtime_target": {
-            "kind": "process",
-            "id": "planr-doc-fixture"
           }
         }
       ]

package/docs/contracts/fixtures/evidence/v1/examples/proof-obligation.json

@@ -20,15 +20,6 @@
         "kind": "local_service",
         "uri": "http://127.0.0.1:4173/health"
       },
-      "environment": {
-        "kind": "local",
-        "id": "dev-shell",
-        "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-      },
-      "runtime_target": {
-        "kind": "process",
-        "id": "planr-doc-fixture"
-      },
       "payload_schema": {
         "schema_ref": "planr.api.http.response@v1"
       },
@@ -60,8 +51,5 @@
     "min_receipt_status": "trusted",
     "allow_user_attestation": false
   },
-  "policy_digest": "sha256:c1a2a26ece3ee7a3cf3166cd849664d723fe2fffda2dc0773b2c92dc8d1ae8c1",
-  "config_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-  "created_at": "2026-07-28T12:00:00Z",
   "supersedes": null
 }

package/docs/contracts/fixtures/evidence/v1/examples/proof-preset.json

@@ -13,15 +13,6 @@
       "target": {
         "kind": "local_service",
         "uri": "http://127.0.0.1:4173/health"
-      },
-      "environment": {
-        "kind": "local",
-        "id": "dev-shell",
-        "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-      },
-      "runtime_target": {
-        "kind": "process",
-        "id": "planr-doc-fixture"
       }
     }
   ]

package/docs/contracts/fixtures/evidence/v1/negative/adapter-registration-missing-execution-contract.json

@@ -23,15 +23,6 @@
           "target": {
             "kind": "local_service",
             "uri": "http://127.0.0.1:4173/health"
-          },
-          "environment": {
-            "kind": "local",
-            "id": "dev-shell",
-            "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-          },
-          "runtime_target": {
-            "kind": "process",
-            "id": "planr-doc-fixture"
           }
         }
       ]

package/docs/contracts/fixtures/evidence/v1/negative/policy-default-preset-unregistered.json

@@ -23,15 +23,6 @@
           "target": {
             "kind": "local_service",
             "uri": "http://127.0.0.1:4173/health"
-          },
-          "environment": {
-            "kind": "local",
-            "id": "dev-shell",
-            "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-          },
-          "runtime_target": {
-            "kind": "process",
-            "id": "planr-doc-fixture"
           }
         }
       ]

package/docs/contracts/fixtures/evidence/v1/negative/policy-weakening-without-waiver.json

@@ -23,15 +23,6 @@
           "target": {
             "kind": "local_service",
             "uri": "http://127.0.0.1:4173/health"
-          },
-          "environment": {
-            "kind": "local",
-            "id": "dev-shell",
-            "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555"
-          },
-          "runtime_target": {
-            "kind": "process",
-            "id": "planr-doc-fixture"
           }
         }
       ]

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

@@ -687,10 +687,7 @@
         "observations",
         "fixture_policy",
         "freshness_policy",
-        "assurance_policy",
-        "policy_digest",
-        "config_digest",
-        "created_at"
+        "assurance_policy"
       ],
       "additionalProperties": false,
       "properties": {
@@ -739,15 +736,6 @@
         "assurance_policy": {
           "$ref": "#/$defs/JsonObject"
         },
-        "policy_digest": {
-          "$ref": "#/$defs/Digest"
-        },
-        "config_digest": {
-          "$ref": "#/$defs/Digest"
-        },
-        "created_at": {
-          "$ref": "#/$defs/Timestamp"
-        },
         "supersedes": {
           "anyOf": [
             {
@@ -767,9 +755,7 @@
         "type",
         "subject",
         "expected",
-        "target",
-        "environment",
-        "runtime_target"
+        "target"
       ],
       "additionalProperties": false,
       "properties": {
@@ -789,12 +775,6 @@
         "target": {
           "$ref": "#/$defs/TargetBinding"
         },
-        "environment": {
-          "$ref": "#/$defs/EnvironmentBinding"
-        },
-        "runtime_target": {
-          "$ref": "#/$defs/RuntimeTarget"
-        },
         "payload_schema": {
           "$ref": "#/$defs/JsonObject"
         },

package/docs/documentation/COVERAGE.md

@@ -4,7 +4,7 @@ This is the canonical inventory that maps shipped public surfaces to repository
 
 ## Published route inventory
 
-The site currently owns 66 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+The site currently owns 67 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
 
 | Section | Published routes |
 | --- | --- |
@@ -14,7 +14,7 @@ The site currently owns 66 MDX routes. Next.js also emits the landing page and f
 | Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/grok-build`, `/docs/integrations/pi`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
 | Plugins | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/evidence-trust-model`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
-| Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/evidence-scenarios`, `/docs/guides/recipes` |
+| Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/feature-run-work-packets`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/evidence-scenarios`, `/docs/guides/recipes` |
 | Reference | `/docs/reference`, `/docs/reference/cli`, `/docs/reference/cli-generated`, `/docs/reference/mcp`, `/docs/reference/mcp-schemas-generated`, `/docs/reference/http-api`, `/docs/reference/evidence`, `/docs/reference/configuration-and-storage`, `/docs/reference/data-and-status`, `/docs/reference/outputs-and-errors`, `/docs/reference/support-matrix`, `/docs/reference/maintenance` |
 | Contributing | `/docs/contributing`, `/docs/contributing/repository-setup`, `/docs/contributing/architecture`, `/docs/contributing/docs-authoring`, `/docs/contributing/testing`, `/docs/contributing/security-and-privacy` |
 | Operations | `/docs/operations`, `/docs/operations/release`, `/docs/operations/versioning-and-migrations`, `/docs/operations/docs-deployment`, `/docs/operations/health-and-diagnostics`, `/docs/operations/rollback`, `/docs/operations/documentation-governance` |
@@ -35,7 +35,7 @@ The site currently owns 66 MDX routes. Next.js also emits the landing page and f
 | Binding Evidence trust model | `src/evidence/`, `src/app/evidence.rs`, `docs/contracts/EVIDENCE_CONTRACT_V1.md` | `/docs/concepts/evidence-trust-model`, `/docs/reference/evidence`, `/docs/guides/evidence-scenarios` |
 | Reviews, approvals, fix chains | `src/app/review.rs`, `src/app/flow.rs`, `src/app/application.rs` | `/docs/concepts/reviews-and-approvals`, `/docs/guides/review-and-fix-loops` |
 | Recovery, conditions, packages, closure | `src/app/recovery.rs`, `src/app/packages.rs`, `src/app/flow.rs` | `/docs/concepts/recovery-packages-and-closure`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse` |
-| Worker loop, handoff, recipes | application flow and lease owners | `/docs/guides/daily-worker-loop`, `/docs/guides/handoff-and-resume`, `/docs/guides/recipes` |
+| Worker loop, typed FeatureRun packets, handoff, recipes | FeatureRun application flow and lease owners | `/docs/guides/daily-worker-loop`, `/docs/guides/feature-run-work-packets`, `/docs/guides/handoff-and-resume`, `/docs/guides/recipes` |
 | Copy-paste Evidence scenarios | `apps/docs/scripts/generate-evidence-examples.mjs`, `tests/fixtures/evidence/docs/` | `/docs/guides/evidence-scenarios` |
 
 ## CLI, MCP, HTTP, and data contracts
@@ -91,7 +91,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 
 ## Audit completion checklist
 
-- [x] All 66 current MDX routes are explicitly inventoried.
+- [x] All 67 current MDX routes are explicitly inventoried.
 - [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
 - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
 - [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.

package/docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -20,7 +20,7 @@ This file records the implemented route and navigation contract. Routes are publ
 
 ## Implemented route tree
 
-The 66 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
+The 67 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
 
 ```text
 /docs
@@ -53,6 +53,7 @@ The 66 MDX files below are the current page tree and must agree with every `meta
 │   └── recovery-packages-and-closure
 ├── guides
 │   ├── daily-worker-loop
+│   ├── feature-run-work-packets
 │   ├── parallel-coordination
 │   ├── handoff-and-resume
 │   ├── review-and-fix-loops
@@ -124,7 +125,6 @@ The inventory covers these retired route families:
 | `/docs/guides/review-and-fix-loop` | `/docs/guides/review-and-fix-loops` |
 | `/docs/guides/interruptions-and-recovery` | `/docs/guides/recover-interrupted-work` |
 | `/docs/guides/import-export-and-templates` | `/docs/guides/packages-and-reuse` |
-| `/docs/guides/local-review-workspace` | `/docs/guides/recipes` |
 | `/docs/guides/host-hooks` | `/docs/integrations` |
 | `/docs/guides/model-routing` | `/docs/reference/configuration-and-storage` |
 | `/docs/reference/cli/index` | `/docs/reference/cli` |

package/docs/fixtures/mcp-contract.json

@@ -12,6 +12,7 @@
     "planr_plan_split",
     "planr_plan_check",
     "planr_plan_audit",
+    "planr_plan_final_review",
     "planr_plan_link",
     "planr_map_build",
     "planr_item_create",
@@ -32,6 +33,8 @@
     "planr_pick_pause",
     "planr_pick_resume",
     "planr_pick_stale",
+    "planr_run_restart",
+    "planr_run_resolve_budget_hold",
     "planr_recover_sweep",
     "planr_approval_request",
     "planr_approval_approve",
@@ -47,7 +50,6 @@
     "planr_evidence_obligation_list",
     "planr_evidence_obligation_show",
     "planr_evidence_migrate",
-    "planr_evidence_rebind",
     "planr_evidence_classifications",
     "planr_evidence_capability_list",
     "planr_evidence_capability_show",
@@ -60,6 +62,7 @@
     "planr_evidence_coverage",
     "planr_evidence_explain",
     "planr_evidence_readiness",
+    "planr_evidence_recover_settlement",
     "planr_eval_suite_check",
     "planr_eval_run",
     "planr_eval_show",
@@ -71,9 +74,9 @@
     "planr_log_add",
     "planr_review_annotate",
     "planr_review_ingest",
-    "planr_review_artifact",
     "planr_review_evidence",
-    "planr_review_close",
+    "planr_review_gate_close",
+    "planr_review_findings_resolve",
     "planr_close_item",
     "planr_context_create",
     "planr_search",
@@ -130,9 +133,10 @@
     "planr mcp",
     "planr review annotate",
     "planr review ingest",
-    "planr review artifact",
     "planr review evidence",
     "planr review close",
+    "planr review findings",
+    "planr plan final-review",
     "planr eval suite-check",
     "planr eval compare",
     "planr eval gate",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.10.0-alpha.2",
+  "version": "1.10.0-alpha.4",
   "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.2",
+  "version": "1.10.0-alpha.4",
   "author": {
     "name": "instructa"
   },

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

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