Implement durable resumable PR publication (stacked on #119)

[Protonmatter]

Outcome

Implements the owner-approved durable PR publication specification and plan from #119. Stacked on #119: this PR targets docs/durable-pr-publication-20260925, not master. Source publication tooling is implemented; the original missing Earth candidate for #116 remains unrecovered and unchanged. No merge or deployment is requested or performed.

The entry point is tools/publish_pr_candidate.py with inspect, prepare, execute, and resume. Six production modules separate strict intent/reconciliation, binary recovery packets and immutable journals, native Git transport, API object staging, concrete GitHub CLI integration, and operator commands. Contributor instructions and the existing PR template now require verified publication evidence.

Specification and traceability

• Design and plan: docs/superpowers/specs/2026-09-25-durable-pr-publication-design.md and docs/superpowers/plans/2026-09-25-durable-pr-publication.md.
• Acceptance scope: PUB-01 through PUB-12 as defined in Add durable resumable PR publication and recovery #119; local implementation evidence does not imply live qualification of every transport.
• Existing daily-feed adapter, generated-data allowlist, CI workflows, Pages release policy, renderer, textures, and branch protection are unchanged.
• Non-goals: reconstructing missing Earth artwork/source, modifying Add optional Enhanced Earth oceans, raised clouds and shadows #116, creating credentials, enabling daily-feed writes, merging or deploying.

Correctness and risk

• Freeze exact committed source; verify all tracked working bytes, modes, path allowlist, Git OIDs, SHA-256 and parent/tree identities.
• Persist binary-safe incremental bundles, exact changed blobs and checkpoints in an explicitly confirmed persistent store outside the checkout. Checkpoints use create-only writes, readback, hash chaining, file/directory fsync and an operation lock.
• Native transport uses exact expected-head leases plus ancestry and remote endpoint checks; API transport requires GraphQL updateRefs/beforeOid for existing heads. A bridge without CAS may create only an explicitly absent new branch and never silently downgrades an existing-ref update.
• Lost responses are reconciled by remote readback. API-created commit IDs are checkpointed before readback; source and published SHA remain separate when identity metadata differs.
• PR identity/ownership and all pages are checked before reuse/creation. A lost creation response does not cause blind duplicate creation.
• Source publication and CI observation/success are separate. CI evidence is bound to the source/base/PR and test-merge identities; old, diagnostic, skipped, pending or unrelated runs do not count as passing.
• Failure reports use unknown (source_published: null) rather than claiming that no remote side effect occurred.
• Runtime uses Python standard library, Git and an existing authorized gh login. No new runtime dependency or service.

Limitations: the concrete store is an operator-declared persistent filesystem; ChatGPT Library persistence still requires an authorized bridge, not hidden access from the script. API parents must already exist remotely; native Git carries otherwise unpublished history. API mode rejects unsupported signed/encoding commit headers. The authoring runtime must actually use the helper; CI cannot recover bytes that were never uploaded.

Deferred minor: subprocess output is bounded after capture, not streamed; unusually noisy local hooks may consume memory before rejection. Physical Windows/network-filesystem durability is unqualified; a simulated lock test is not physical-device evidence.

Rollback: remove these new tool/test/doc files and the appended PR-template section. No application or data migration occurs.

UI and UX

No application UI change. Operator output exposes prepared, persisted, remote-ref verified, PR verified and CI states separately. Documentation includes PowerShell usage and same-operation resume without copying SHAs manually.

Validation evidence

• 98 new publication tests passed with no failures or skips.
• Tests use real isolated local Git/bare remotes and a 1,677,824-byte non-UTF-8 payload; cover deletion/restoration of the original working directory, stale leases, competing writers, redirected remotes, hidden working-file changes, corrupted packets, missing prerequisites, storage failures, API response loss, normalized commit IDs, duplicate PR prevention and CI mismatches.
• Fresh restored-source verification after the original execution container became unavailable: all 98 tests passed again in 14.774 s.
• New-tool coverage only: statements 862/868 (99.31%); branches 157/160 (98.125%); combined 99.12%.
• 13 Python files syntax-checked; three authored Markdown files checked; git diff --check passed.
• Seven important self-review findings were reproduced with failing regressions, fixed, and retested.
• Independent reviewer: unavailable; this was self-review.
• Full SOL tests/coverage: not run locally. The checkout contained selected files because native GitHub cloning failed DNS resolution. Actual invocations of tools/validate_docs.py and tools/validate_sdlc.py failed because those files were unavailable there; logs retained. No Rust, Node, full-repository or live GraphQL success is claimed.
• Hosted CI: assess this PR's actual head/run; no result inferred from Add durable resumable PR publication and recovery #119.
• Live native/GraphQL transport qualification and physical Windows/network-filesystem durability remain open.

Commands:

PYTHONPATH=tools python -m coverage run --branch --source=tools -m unittest discover -s tests/python -p 'test_pr_publication*.py' -v
98 tests passed; exit 0.

PYTHONPATH=tools python -m unittest discover -s tests/python -p 'test_pr_publication*.py' -v
Restored exact source packet: 98 tests passed; exit 0.

Publication identity and recovery

The exact 16-file overlay was stored outside the execution container before GitHub mutation. It was read back and checksum verified. Each subsequent tree/commit/ref result has a retained immutable checkpoint. Rebuilding the final tree from the recorded parent tree and all 16 locally verified blob OIDs returned the identical staged tree.

• Remote parent: 7d843fadcb22de6e23237c12f5661eccb26499d2
• Published source commit: 0759f8dd1fe24e2ff8cfb166f9f61a6684573f09
• Verified tree: cc183af075df907196e2148aa2a5658b75373010
• Operation ID: durable-pr-implementation-20260925
• Packet SHA-256: 436ed0a0ceff96a0acfe37313ccfaefd9322a9663cfd604bef11428238e99f59
• Publication route for this PR: connected app, verified immutable object staging and create-only new branch. This is not a claim of live existing-ref CAS qualification.
• Exact private recovery storage IDs and test logs retained in the owner's Library, not exposed here.

Documentation

• Operator guide docs/PR_PUBLICATION.md, root AGENTS.md and PR-template publication fields added.
• Recovery boundaries and missing Earth source are explicit.
• Existing CI/release workflows and daily-feed activation holds remain unchanged.

[Protonmatter]

Pre-merge review pass for the owner's approved #120 -> #119 -> master integration.

Reviewed the six publisher modules, operator/agent instructions, and regression suite from the retained source packet (SHA-256 436ed0a0ceff96a0acfe37313ccfaefd9322a9663cfd604bef11428238e99f59). Fresh execution: PYTHONPATH=tools python -m unittest discover -s tests/python -p 'test_pr_publication*.py' -v -> 98 tests, zero failures/skips, 17.441 s. Reviewed expected-head/ancestry checks, binary packet validation, immutable checkpoint writes, lost-response reconciliation, PR identity, and CI/source SHA separation. No additional blocking issue identified in this pass. This is an author-side review, not an independent approval or live transport qualification.

Fresh GitHub observation: CI 36154468542, Coverage 36154468193, Docs 36154467819 completed successfully for source head 0759f8dd1fe24e2ff8cfb166f9f61a6684573f09. CI run metadata confirms PR #120 and base 7d843fadcb22de6e23237c12f5661eccb26499d2.

Retained limitations: live native/GraphQL publish-resume qualification, physical Windows/network filesystem durability, and automatic Library bridge integration remain unqualified; the previously disclosed post-capture subprocess output bound remains a deferred minor. No default activation or removal of these limits is implied by merging source.

The merge will use the reviewed source SHA as its expected-head precondition and a merge commit into #119's branch. #119 must receive fresh combined-head validation before a separate master merge. Rendering PRs and #116 recovery remain held.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-25T16:53:57.172368Z	0759f8d	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.