Plan zero-write Issue lifecycle restoration from an exact receipt

[proerror77]

Parent

#455

What to build

Add the read-only plan-restore operation after #607 and #608. Before any metadata mutation is authorized, it accepts the exact verified preflight bundle plus an approved canonical forward plan, derives the complete inverse, and emits a content-addressed reverse plan. After mutation, it accepts that exact reverse plan plus the content-addressed post-state receipt, verifies every identity, independently re-reads live GitHub state, refuses concurrent or provenance drift, and prints the already-bound reverse patch while performing zero writes.

Acceptance criteria

• Before any metadata write is authorized, the pre-mutation mode validates the exact preflight bundle and approved forward plan, then records a content-addressed reverse plan containing the complete inverse for every supported mutable field; missing, incomplete, or mismatched inverse operations fail closed.
• The receipt binds repository/controller/target, preflight digest, post-state digest, forward-plan digest, reverse-plan digest, default-branch identity, API/page inventory, counts, and per-Issue passed operation receipts.
• The forward and reverse plans exactly match the supported preflight-to-receipt changes; unsupported Issue fields, PR metadata, label-catalog, comments/events, or closing-reference drift fail closed.
• Live state must equal the exact receipt identity before the bound reverse patch is printed; any concurrent body/label/assignee/state/relationship or provenance drift exits nonzero.
• The printed canonical reverse patch contains only Issue body, labels, assignees, native parent/sub-issue and blocked-by/blocking relationships, and state; comments/events remain verification-only provenance.
• Focused tests prove pre-mutation inverse completeness, receipt tamper rejection, provenance drift refusal, exact reverse-plan identity, zero filesystem/GitHub writes, and absence of any apply or mutation operation.

Blocked by

#608 must merge first.

Out of scope

• Executing the printed patch or authorizing restoration.
• Creating or mutating the retained evidence PR.
• Correcting the 54 legacy violations or changing Enable the Issue Lifecycle required check after a green observation window #460/branch protection.

[proerror77]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add a zero-write restoration planner bound to exact preflight, forward-plan, reverse-plan, receipt, and live-state identities.

Current behavior:
The repository can capture a canonical content-addressed Issue/PR graph and independently verify it locally or against live GitHub. It cannot yet derive and retain the complete inverse before mutation, validate a post-state receipt against that inverse, or print an independently drift-checked restoration patch.

Desired behavior:
Add the read-only plan-restore operation. Its pre-mutation mode accepts the exact verified bundle and approved canonical forward plan, rejects unsupported or incomplete inverses, and emits the content-addressed reverse plan before any metadata write can be authorized. Its dry-run restoration mode accepts that exact reverse plan and post-state receipt, verifies every bound identity, independently re-reads live GitHub, refuses concurrent or provenance drift, and prints the complete canonical reverse patch while performing zero filesystem or GitHub writes.

Key interfaces:

• The existing preflight verifier remains the authority for bundle, digest, schema, scope, graph, pagination, and provenance validation.
• The canonical forward plan and reverse plan must bind every supported Issue body, label, assignee, state, parent/sub-issue, and blocked-by/blocking operation; unsupported PR metadata, label-catalog, comment/event, or closing-reference changes fail closed.
• The post-state receipt binds repository/controller/target, preflight/post-state/forward/reverse digests, default-branch identity, API/page inventory, counts, and per-Issue passed operation receipts.
• The public CLI exposes planning and dry-run output only; no apply or mutation operation exists.

Acceptance criteria:

• Pre-mutation planning verifies the exact bundle and approved forward plan, then emits a complete content-addressed inverse; missing, mismatched, or unsupported operations fail closed.
• Receipt and plan identities are canonical and mutually bound, including exact repository/controller/target, default branch, provenance inventory, counts, and per-Issue receipts.
• Live readback must equal the exact receipt before the already-bound reverse patch is printed; any mutable-field or provenance drift exits nonzero.
• The printed patch is complete for supported Issue metadata and performs zero GitHub/filesystem writes.
• Focused tests prove inverse completeness, tamper/drift rejection, exact identity, zero writes, and absence of any apply path.

Out of scope:

• Applying or authorizing restoration, mutating a retained evidence PR, or adding a new storage service.
• Correcting the 54 legacy violations, changing Reconcile existing GitHub issue metadata against the lifecycle contract #459 execution state, or changing Enable the Issue Lifecycle required check after a green observation window #460/branch protection.

[proerror77]

This was generated by AI during triage.

Agent Brief clarification: zero-write and carrier boundary

• plan-restore is stdout-only. Pre-mutation planning reads the verified preflight bundle plus canonical forward plan and prints exact canonical reverse-plan bytes; it creates or overwrites no file and calls no mutating GitHub route. The caller owns any later persistence and SHA-256 sidecar.
• Dry-run restoration additionally reads the exact saved reverse plan, canonical receipt, and verified post-state four-file bundle. It cross-binds raw-byte SHA-256 identities, repository/controller/target, default branch, API/media/page inventory, counts, and every passed operation receipt; it then performs an independent live capture and prints the already-bound reverse plan only when live equals the receipt.
• Each forward operation has one full supported precondition and target for one Issue. The supported state is body, label names, assignee logins, state plus state reason, and canonical parent/blocked-by edges; sub-issue/blocking edges are derived once from those canonical directions. Missing, extra, duplicate, conflicting, no-op, unknown-Issue, PR, or unsupported-field operations fail closed.
• PR metadata, label catalog, closing references, and unsupported Issue fields are not restorable. Comments/events are provenance-only and may only be exact receipt-bound append-only records caused by passed operations; no reverse operation deletes or recreates them. Any other pre/post difference or any receipt/live difference fails closed.
• No retained evidence PR exception is authorized in Plan zero-write Issue lifecycle restoration from an exact receipt #609. Creating or updating such a PR changes the complete captured PR graph and would violate strict equality. Until a separate durable carrier contract resolves that self-reference without weakening verification, Reconcile existing GitHub issue metadata against the lifecycle contract #459 remains needs-info; Plan zero-write Issue lifecycle restoration from an exact receipt #609 must not claim to unblock the 54-item mutation batch.
• Every identity/schema/digest/scope/ref/API/media/page/rate-limit/operation mismatch exits nonzero with no artifact on stdout and no filesystem/GitHub write. There is no apply operation.

[proerror77]

Agent Brief clarification: rate-limit and relationship scope

This clarification supersedes only the earlier phrase rate-limit mismatch:

• Dynamic X-RateLimit-Remaining, X-RateLimit-Used, and X-RateLimit-Reset values are operational telemetry, not content identity. An independent readback consumes quota, so exact preflight/receipt/live equality for those counters is impossible by construction.
• The existing Capture content-addressed Issue lifecycle preflight evidence #607 v1 four-file bundle does not record rate-limit telemetry. plan-restore therefore keeps the existing read boundary: any GitHub rate-limit or other non-success response fails closed before output, with exit 2, empty stdout, and zero filesystem/GitHub writes.
• Persisting rate-limit telemetry would require a separately reviewed evidence-schema contract. It is not added to Plan zero-write Issue lifecycle restoration from an exact receipt #609 and does not unblock Reconcile existing GitHub issue metadata against the lifecycle contract #459.
• Native parent/sub-issue and blocked-by/blocking planning is limited to relationships inside the exact target repository. A cross-repository relationship fails closed before Issue-number projection so same-number Issues cannot be conflated.

All other requirements in the prior Agent Brief and clarification remain unchanged.

[proerror77]

Completion evidence

Acceptance checks: PR #628 squash-merged to main from exact head 058ab4c5b066c6eeb3c07c9a0dd8b401439c12ee at merge commit 25b6e6d15b5bffc7fb0894a87a07dbcf7e616e5b; the public plan-restore CLI now verifies the exact four-file bundle, preflight manifest and graph identities, canonical forward and reverse plans, post-state receipt/bundle, derived Issue metadata and native repository-local relationships, receipt-bound append-only provenance, and independent live state before printing canonical reverse bytes; strict failure cases exit 2 with empty stdout and no filesystem/GitHub mutation, and no apply operation exists; focused preflight, lifecycle audit/contract/workflow/reconciliation/status-reconciliation, Rust CI scope-selector, Ruby/Bash syntax, shellcheck, scoped actionlint, and diff checks passed; Matt Standards and Spec reviews each reported 0 findings at the exact merged head; required Monorepo CI gate job 91534878928, Prediction Markets CI gate job 91534928918, and Security Summary Report job 91534950854 passed; Issue Lifecycle Audit job 91534809293 and Status Reconciler job 91534809391 passed; zero review threads or actionable review findings remained; the merged remote head branch was deleted. No full live repository capture/readback, metadata apply, retained-evidence PR exception, or legacy reconciliation occurred; #459 remains enhancement + needs-info + runtime, and #460, required checks, branch protection, and the 54-item legacy work queue are unchanged. Result: passed