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.

• The default agent handoff uses OPENCLAW_PR_GATES_REMOTE=github and merge-run --auto-merge. Preparation records github_pending bound to the published head without successful-proof stamps. Merge requires completed 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.

• 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, completed ClawSweeper review, 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.

• 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>]. 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 prior correction as first parent and baseline as second parent. 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; a second baseline materialization in the same preparation is refused. 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. 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.