PR preparation

Use focused local checks before publication and PR CI for broad proof. Open a ready PR as soon as the change builds and its focused tests pass; do not hold it for pre-PR suite runs. The optional completed-evidence modes below describe supported mechanisms, not a requirement to run broad suites before a PR. ClawSweeper reviews are advisory; merge admission does not wait for a bot comment.

Review transitions recognize conflict metadata retained after committed merge or rebase resolutions, including renamed files. Each stage must match its source commit's exact mode and blob at the same path or a unique Git-detected rename source leading to the committed resolution path. Ambiguous or undetected renames still refuse without changing the index; preserve the transition journal for native recovery.

Unknown working-file bytes remain refused, even when empty. Explicitly authorized review-file salvage preserves one selected preimage and restores its journaled source without changing HEAD, the index, journal, or workflow binding. Ordinary replay still owns completion.

For blobless partial clones, checkout first resolves its target without lazy fetching and explicitly fetches a missing commit through the canonical source transport, retaining the blob filter and normal history negotiation. Transition recovery then prefetches missing target blobs in batches of at most 1,024. Only those blob fetches skip local-history negotiation; both fetch paths skip automatic maintenance and leave refs and FETCH_HEAD unchanged. Worktree admission runs after prefetching, followed by one restore so file/directory replacements remain intact. Final checkout disables lazy fetching so a missing object fails visibly. A failed blob prefetch retains the transition journal for retry.

• The default agent handoff leaves OPENCLAW_PR_GATES_REMOTE unset and uses merge-run --auto-merge; explicitly setting OPENCLAW_PR_GATES_REMOTE=github selects the same mode. Preparation records github_pending bound to the published head without successful-proof stamps. Merge requires completed local review, the exact prepared head, and the enforced openclaw/ci-gate; it rejects known failed required checks, accepts pending checks, and skips separate hosted workflow verification and its synchronous CI watcher. GitHub enforces required CI/security checks and reviews; the agent retains responsibility for follow-through. This mode replaces separate scheduled Testbox evidence with the PR's enforced gate; existing completed-evidence modes remain available. Accepted requests return pending, not completion. Follow the maintainer skill's polling cadence, investigate failures and conflicts, and reconcile through native recovery until merge and cleanup are verified. Preserve accepted or uncertain outcome records; never blindly re-arm a request. No implicit admin or REST fallback applies to pending-gate admission; explicitly authorized prior-CI admin admission is a separate mode.

• Gate-mode validation for prepare-run, prepare-gates, and prepare-push happens before PR reads, lock acquisition, or preparation evidence retirement. Select one mode: the GitHub-pending invocation clears OPENCLAW_TESTBOX; completed hosted proof clears OPENCLAW_PR_GATES_REMOTE. Unknown or contradictory selectors must fail without replacing saved evidence. This validation does not block merge-outcome reconciliation, whose retained intent owns recovery.

• Set OPENCLAW_PR_GATES_REMOTE=local only when the old full local gates are explicitly needed. OPENCLAW_TESTBOX=1 with an unset remote selector retains completed hosted mode; combining it with explicit OPENCLAW_PR_GATES_REMOTE=github remains a conflict.

• Normal prepare-init requires incoming-head READY. To resolve a validated incoming NEEDS WORK review with BLOCKER/IMPORTANT findings, explicitly use scripts/pr prepare-correction-init <PR>. This initializes correction preparation only, preserving the incoming review and contributor ancestry. Commit the fixes, then use prepare-correction-review-init to create a separate exact-candidate JSON review template. JSON alone is authoritative; validation renders its summary. Independently review the full corrected candidate and explain resolution of every required incoming finding. Gates, push, sync and merge require that candidate's READY review; changing the candidate or incoming review invalidates it. Discussion/rejection verdicts cannot use this route. This does not change canonical-wrapper trust or permit use of an unlanded wrapper on another PR. Correction publication accepts exact-candidate github_pending as a pending disposition, never successful proof. Publication rebinds its target only through the verified identical-tree local/hosted receipt; sync and merge preserve that binding. Merge still requires exact prepared-head auto-merge admission, the enforced openclaw/ci-gate, and no known failed required checks; live review/security rules remain enforced. Completed gate modes and the separately authorized protected Crabbox pending route remain available.

• After a native correction publication, a fresh incoming NEEDS WORK review can continue on the existing clean, signed preparation branch with scripts/pr prepare-correction-continue <PR> --expected-head <retained SHA> --expected-tree <tree OID> --incoming-head <hosted SHA> --incoming-review <review JSON OID> --publication-receipt <push|sync> --publication-oid <receipt OID>. Select the exact current .local/review.json and native prepare-push-result.env or prepare-sync-result.env bytes with git hash-object --no-filters. The publication receipt must connect the old incoming preparation to the new hosted head with identical local/hosted trees and preserved ancestry; the hosted head must be an ancestor of the retained candidate. The owner rechecks live PR identity, signed descendants, clean branch, exact metadata and operation custody before replacing authority. It copies and verifies prior preparation, correction, publication, baseline and gate evidence into .local/prep-evidence.*, then retires their active authority without changing HEAD, the index or source files. The fresh incoming review and metadata remain unchanged. Interrupted metadata installation stays in the existing transition journal and can resume only with the same retained identities and evidence; rerun the exact continuation after resolving its reported obstruction. Do not reset the preparation branch or delete retained transition evidence. After continuation, initialize and complete a fresh exact-candidate correction review and run native gates; prior READY reviews and gate stamps remain historical.

• A reviewed, signed correction blocked by its old baseline can use scripts/pr prepare-baseline-refresh <PR> --expected-head <candidate SHA> --baseline <main SHA> [--resolutions <file>]. First integration also accepts the unchanged, signed incoming head after prepare-correction-init when its exact current review is NEEDS WORK with actionable findings. This admission creates a candidate for review; it does not approve or resolve those findings. Its signed binding records incomingSource: true, retains the incoming review bytes, and preserves existing preparation evidence as history. A changed source or an existing baseline binding still requires the corrected-source or successor review contract. The selected baseline must belong to the invocation's privately captured main ancestry. The native owner rechecks the live incoming PR identity, exact preparation branch, clean source, review bytes and operation lock. It derives the complete product delta from the unique source/baseline fork, applies only those paths to the selected baseline, and signs a candidate with the preparation source as first parent and baseline as second parent. It preserves the source commit's Git-parsed Co-authored-by trailers in the generated commit message, including signing requests; it never copies other source trailers or binding markers. Source credit containing control or line-separator characters refuses before a candidate or request is created. It does not perform an unrestricted merge or accept a caller scope list. Content replay uses built-in Git text merging over exact private blob files, independent of worktree attributes or configured merge drivers. Competing add/add, deletion/type changes and NUL-containing binary edits require explicit resolutions. Conflicts require a regular JSON manifest with version: 1, pr, sourceHead, baselineHead, forkBase and resolutions. Each resolution names one computed conflict path and exact base, source and baseline entries ({mode, oid} or null for absence). Its resolved value is either null for deletion or {mode, file, sha256}; file is a regular file relative to the manifest directory, and its exact bytes must match the SHA-256. Missing, extra, stale or duplicate entries refuse. Gitlinks, directory/file collisions and native artifact paths refuse. The command reports resolved Git blob IDs for independent review; it retains those IDs and modes, never mutable resolution filenames. Before replacing active authority, the owner copies and verifies prior preparation/review/build/gate evidence in .local/prep-evidence.*. Incoming review bytes stay unchanged. The existing transition journal retains the signed binding bytes, and recovery validates the same source/target/branch before restoring files and compare-and-swapping the preparation ref. Partial transitions refuse review and publication. Do not delete their journal or retained evidence, reset the branch, or waive operation-lock recovery. After completion, initialize and complete a fresh correction review, then select native gates for that exact candidate before normal publication. Old proof remains historical. Validation reconstructs the immutable refreshed tree and includes the original product paths even when the baseline already contains them, plus every later fixup path. Later signed fixups remain supported; the initial refresh still refuses a second materialization. A separately reviewed source can explicitly use scripts/pr prepare-baseline-successor <PR> --expected-head <SHA> --expected-tree <OID> --expected-review <OID> --predecessor-head <SHA> --predecessor-binding <OID> --baseline <SHA> [--resolutions <file>]. This is new source admission, not a refresh retry: every selected identity must match the signed READY correction and active predecessor. Its signed version-1 binding adds sourceAdmission, retaining the predecessor identity, exact source tree/review, and byte inventory of the entire retained proof chain. Validation recursively reconstructs every predecessor and resolution, preserves the original incoming review and complete product/fixup scope, and rejects changed proof. Recovery can finish only that exact admitted journal; it cannot authorize another successor. Signature, tree, predecessor and transition-state replay completes before live PR revalidation. Invocation-local prepared facts bind exact evidence bytes and worktree state; bounded local checkout, branch, binding and lock checks guard each authority installation, file restoration and final branch CAS. Recovery reconstructs these facts from the same journal rather than accepting persisted facts as new admission; a late refusal retains the journal and already authorized partial installation. The new candidate requires fresh independent correction READY before gates; prior READY/proof remains historical. An unlanded implementation must never self-admit a feature: independently review and land this dependency through the existing trusted wrapper before use. Gate and publication policies are unchanged.

• PR source acquisition binds the full head SHA authenticated by live PR metadata. An existing direct task-owned destination ref at that exact commit can be reused with Git's checked-out/rebasing branch checks; absent, moved, symbolic, or hidden refs retain canonical-origin fetching and its filter/error behavior. Publication verification uses the retained pr-<PR> ref, avoiding another fetch when it already matches the prepared head. Both paths verify the exact commit and recheck that head SHA, branch, and repository identity stayed unchanged during acquisition. GitHub's asynchronous refs/pull/<PR>/head projection is not source authority. All review, prepare, publication, and merge fetches use this owner without changing the private main checkpoint or shared tracking refs.

• Main freshness belongs to one scripts/pr operation: nested entry/review guards share a captured main SHA; gate selection, publication after gates, and merge verification after CI each refresh it. Capture the canonical origin's main from the PR worktree's private FETCH_HEAD, never a later shared-ref read. Main refreshes never write shared origin/main. Cold provisioning fetches into its existing per-PR temp/pr-<PR> branch without writing canonical FETCH_HEAD, then fully initializes from that seed before the private checkpoint; the seed is not checkpoint authority. Checkout budgets scale with the measured tree allocation (at least 4 KiB per file), with a four-hour ceiling; the same measurement grants Git at least 30 seconds and at most 30 minutes for signal cleanup before force-kill. Provisioning advertises its measured cleanup allowance over the existing lock-notification pipe so the outer supervisor also joins cleanup after an interrupt; the second-signal force escape is unchanged. Allocation leases, template records, and configuration observation use canonical-repo .local/pr-state, independently of the operator's state-directory environment. Failed native provisioning may remove only its exclusively reserved, unchanged directory after the Git runner settles and the shared cleanup owner proves no admin entry belongs to that path; ordinary rejection removes only an empty reservation, while interruption permits partial checkout removal; registered hook state, preexisting damage, uncertain process cleanup, and changed authority remain preserved. Directory cleanup never releases the failed operation lock. Every standalone command and newly provisioned worktree starts fresh; coalescing must not skip containment, transition recovery, exact-head checks, or the separate Crabbox authority windows.

• Native gate planning derives one candidate/main fork base from that captured snapshot and passes it through pnpm check --base to all ratchets. Incoming review identity and prior publication receipts do not select the check base; keep those bindings intact when a prepared candidate incorporates main.

• When explicitly selecting the optional local full-test gate mode, scope OPENCLAW_BUILD_PRIVATE_QA=1 to its initial pnpm build child so ordinary test preparation can reuse complete artifacts. Keep the full build profile, freshness checks, and managed-Gateway fences; do not export the flag across check/test workers. Docs-only builds and remote/hosted gate modes retain their existing inputs.

For baseline-bound corrections, publication verifies every prepared commit outside the hosted head and the exact baseline authenticated by its signed refresh binding. Inherited baseline history does not require additional local signer trust; task commits on either merge parent still require valid signatures. Missing or changed baseline authority refuses publication before transport selection.

Review initialization retains and verifies the previous PR metadata and associated review in .local/review-evidence.* before replacing either metadata file. A failed retention leaves the active identity unchanged. Keep that history while the correction remains unfinished; it does not approve a new incoming head.

Correction continuation also supports a published correction followed by a native baseline refresh that retired its active incoming-review copy. The existing prepare-correction-continue command derives publication lineage from the exact signed baseline binding and its named retained archive. It keeps that historical lineage separate from the snapshot used to retire or recover current metadata. Missing original metadata is never reconstructed, and this route does not replay the old baseline review as current approval. Continuation authenticates an existing native baseline binding and checks its baseline against the invocation's private canonical-main checkpoint before excluding inherited main history from signature verification; every other new commit, including task commits on side parents, still requires a valid signature. An ordinary merge of main without that signed native binding does not qualify for this exclusion. Recovery repeats the same verification from retained evidence. A genuine fresh incoming NEEDS WORK review, the existing publication and live-identity checks, and a new candidate READY review and gates are still required.

Publish a candidate for required proof

Some package proofs require a remotely addressable candidate before the review can become READY. For that case, an independent correction reviewer can authorize scripts/pr prepare-publish-for-proof <PR> without resolving the proof finding. The command publishes only the exact signed commit; it does not run proof, approve the correction, create successful gate stamps, or authorize merging.

Keep the correction recommendation NEEDS WORK and each pending incoming finding's resolution empty. Add this exact typed record under correction in .local/correction-review.json:

{  "proofPublication": {    "version": 1,    "kind": "published-candidate-proof",    "headSha": "<candidate commit SHA>",    "treeOid": "<candidate tree OID>",    "workflowSource": "<admitted workflow commit SHA>",    "workflowBinding": "<current workflow binding OID>",    "expectedHostedHead": "<observed PR head SHA>",    "pendingFindings": [      {        "id": "R2",        "evidence": "The exact published package must demonstrate the required upgrade behavior."      }    ]  }}

Use full lowercase 40-character object IDs. Enumerate every current IMPORTANT finding and its concrete required evidence. Every other incoming required finding must be resolved. Unresolved BLOCKER findings, unvalidated issues, incomplete finding sets, and changed source or review authority refuse publication.

If the retained workflow predates this command, first land the capability through ordinary review and qualification. Then use the existing exact-identity prepare-workflow-successor command with --for-proof, naming that authenticated current-main workflow in the review record. It preserves the same candidate, review, predecessor binding, and atomic operation-lock/binding transaction. The record keeps the predecessor binding OID; the successor binds those exact review bytes. Neither an unlanded implementation nor a manual binding edit can authorize the transition.

Publication requires an open PR with no auto-merge request, queue membership, retained merge outcome, or unresolved execution. Unknown observations refuse; the command does not cancel another operation. It requires Git transport and valid signatures, rejects unsigned overrides and same-tree commit aliases, and does not fall back to GraphQL after a Git failure. An uncertain push remains incomplete. After independently reconciling the hosted OID, an explicit invocation can record an already-published exact candidate without another push.

The existing prepare-push-result.env records PUSH_PURPOSE=proof, the exact review OID, and pending finding IDs alongside publication identity. It is not a qualified prep.env. Normal gates, push, sync, and merge still require a genuine READY correction review. After obtaining the enumerated proof, independently resolve those findings for the exact candidate and run ordinary qualification.

Refresh a retained candidate for pending proof

When required proof prevents READY, explicitly use the existing baseline producer:

scripts/pr prepare-baseline-refresh <PR> --for-proof \  --expected-head <source-SHA> --expected-tree <source-tree-OID> \  --expected-review <source-review-OID> --source-review <source-review.json> \  --baseline <canonical-main-SHA>

This explicit producer invocation selects authenticated current official-main workflow code through the existing native selection descriptor and private qualification fetch. It does not replace the retained workflow binding. Land and independently review this capability first; an unlanded wrapper cannot admit itself, and developer-wrapper opt-in still grants no authority.

The source review must be a fresh independent exact-source correction review with that same typed pending-proof authorization, incoming review, workflow source, workflow binding, and hosted lease. The default source-review file is .local/correction-review.json; an explicit file lets the reviewer supply new source-review bytes without overwriting an older correction review.

To credit additional verified contributors without rewriting the signed source, add --coauthors <file> to this explicit --for-proof invocation. The regular UTF-8 JSON file contains an array of Name <email> identities, for example:

["Ada Example <[email protected]>", "Renée Example <[email protected]>"]

The file is snapshotted relative to the caller’s working directory before checkout or evidence retirement; use an absolute path across native handoffs. Names and addresses must be single-line values without control or Unicode line separators. Existing source trailers remain unchanged and first; additions are deduplicated by case-insensitive email, retaining the first requested spelling. The requested metadata is part of the signed baseline binding and candidate identity. Interrupted and completed retries must select the same metadata; changing the file cannot change the admitted transition. This is attribution, not approval: the new candidate still requires fresh exact-source review. Omitting the option preserves source-only credit. Other baseline commands do not accept it.

For a previously published correction whose fresh incoming review has advanced but whose preparation context still names the earlier incoming head, also select --incoming-head <hosted-SHA> --incoming-review <fresh-review-OID> --publication-receipt <push|sync> --publication-oid <receipt-OID>. The existing continuation owner validates the complete retained receipt chain and derives the new incoming context. It installs nothing before baseline admission. Only history in the invocation's private canonical-main checkpoint is excluded from signature verification; every other task commit on every parent must verify. An ordinary unbound continuation still refuses inherited history it cannot authenticate.

The existing materializer creates a new signed descendant, never modifies the retained source, and requires a unique fork and nonempty product delta. Its version-2, purpose: "proof" signed binding retains the exact source review, source/tree, incoming review, workflow, lease, canonical checkpoint, reconstructed tree, and historical preparation/receipt inventory. Context installation, evidence retirement, restoration, branch CAS, and recovery stay in the existing baseline transition journal. Superseded publication receipts stay historical when the incoming context advances. Repeat an interrupted operation with exactly the same selected identities; a different request cannot adopt its journal.

The source review authorizes materialization only. The producer initializes a new, unapproved exact-candidate review through the existing correction-review owner while it still owns current-main execution. Complete that independent review for the new candidate; if the retained workflow predates this capability, use the existing exact-identity prepare-workflow-successor --for-proof operation to advance it to the authenticated current-main workflow named by that new review. Only that new exact-candidate typed NEEDS WORK authorization can use prepare-publish-for-proof. No successful gate or qualified preparation is created. Ordinary gates, push, sync, and merge still require READY. --for-proof does not select baseline succession or remote signing; those combinations, duplicate options, and unknown options refuse before locking. Qualified version-1 refresh, successor, and signing contracts are unchanged.

Signing a baseline on another host

When the preparation host can verify signatures but the signing key is available only on another authorized host, use the native request and continuation commands:

scripts/pr prepare-baseline-signing-request <PR> --expected-head <SHA> --baseline <SHA> --signer <key-fingerprint> [--resolutions <file>]scripts/pr prepare-baseline-signing-continue <PR> --request <request-OID> --signed-commit <file>

For a successor, add the same --expected-tree, --expected-review, --predecessor-head, and --predecessor-binding identities required by prepare-baseline-successor. Both commands use canonical wrapper code and a fresh operation lock. The existing synchronous signing commands remain available.

The request command prints Awaiting signature and the path .local/prepare-baseline-signing.<request-OID>.json. It preserves the active preparation authority and branch. Keep that exact request and its printed OID. It contains the expected signing-key fingerprint, exact unsigned commit bytes in base64, the baseline binding, checkout identity, and the retained proof inventory. SHA-256 SSH fingerprints and full uppercase OpenPGP fingerprints are supported. Select the fingerprint from the operator's authorized signing key; a matching author email alone does not identify that key.

Transfer only the required Git objects and request through an already authorized transport. On the signing host, use ordinary git commit-tree -S in a task-owned object store with the request's exact tree, ordered parents, author and committer identities, timestamps, and message. Return the complete git cat-file commit output without trimming or rewriting bytes. Do not splice a detached signature into a synthetic commit. The wrapper neither supplies a remote execution bridge nor grants new host or credential access.

Continuation verifies the full signature, expected key, and exact unsigned payload, reconstructs the tree and retained review authority, and rechecks the live PR, evidence, checkout, branch, and current operation lock. A saved request is never authority to install a candidate. Changed inputs refuse without replacing evidence. A partial transition retains the existing native journal; repeat continuation with the same request OID and signed commit after resolving the reported condition. It resumes only that target, without new timestamps or another signing request. After installation, complete fresh correction review and native gate qualification before publication.

Baseline admission also supports a candidate already published by native prepare-push or prepare-sync. Its verified publication receipts identify the expected hosted head while the original incoming review stays unchanged. Signing continuation and interrupted transition recovery validate those receipts from the retained source evidence, including after active preparation metadata has been retired. A matching local and hosted head without a publication receipt does not authorize baseline admission. Installation preserves the verified publication receipts for later successors and publication, while retiring the previous candidate's review and gate authority.

The source must extend the recorded hosted head. A distinct GitHub commit alias with an identical tree is insufficient for a new baseline parent. Admission also requires a native push or sync result for the selected hosted head: prep.env alone records completed publication but is retired when the baseline changes. These conditions refuse before changing the source or creating a request. Retain the evidence and resolve the reported publication or ancestry condition first.