Merge Batch

merge:batch is the maintainer shortcut for merging multiple PRs in order while keeping the GitHub-only squash rule and delegating generated follow-up work to the protected canonical-sync PR lane.

Prerequisites

Start from a clean main that exactly matches origin/main.
For a real merge, require pull-request-only strict branch protection with the four exact GitHub-Actions-owned checks, administrator enforcement, no applicable ruleset bypass actors, and no merge queue. Dry runs remain available without this server-side prerequisite.
Make sure .github/MAINTENANCE.md is the governing policy.
Have gh authenticated with maintainer permissions.
Use this only for PRs that are already expected to merge; conflicting PRs still need the manual conflict playbook.

Basic Usage

npm run merge:batch -- --prs 450,449,446,451

Add --poll-seconds <n> if you want a slower or faster status loop while checks settle.

If a PR changes any tracked file under a canonical skills/<skill-id>/** subtree, review the entire affected subtree at the exact current head commit, then attest to that immutable revision:

npm run merge:batch -- --prs 450 --reviewed-head <40-character-head-sha>

Use --dry-run to exercise local classification without approving a run or merging. An abbreviated or stale attestation is rejected.

CI Intake Contract

Before dependent required jobs do expensive setup or wait work, pr-policy runs the fork-safety classifier from the exact protected-base implementation and fails an unsafe fork diff early.
That CI result is fail-fast evidence, not merge authority. merge:batch independently recomputes the complete decision from trusted main and remains the only command allowed to approve fork runs or merge the PR.
impact_profile is shadow-only telemetry. It never skips a required job, test, review, or merge gate.
Normal source PRs generate derived preview state once in source-validation; artifact-preview verifies the exact-head manifest and digest instead of generating the tree again.
Canonical-sync PRs use the complementary path: pr-policy proves the exact reproduced tree, lightweight source-validation records that boundary, and artifact-preview confirms no generated drift. Final CI and CodeQL still run on the resulting main commit.
Test timing is observational. Local deterministic sharding requires the explicit npm run test:local -- --shard-index N --shard-count M opt-in; required CI remains complete and unsharded.

Happy Path

merge:batch will:

fetch the exact base/head objects and classify the complete raw Git diff
recompute changed-skill evidence with evaluator code materialized from the trusted main commit
reject incomplete evidence coverage, deterministic quality/security/provenance regressions, and base/head drift
allow only exact source_repo transitions recorded in the trusted protected-base provenance exception ledger; unrecorded or malformed transitions still fail closed
for external PRs, poll for asynchronously-created fork runs and approve only runs waiting on action_required when every path, mode, object, size, and workflow identity is allowlisted
for sensitive same-repository source changes, allow the guarded exception only when the PR author is the repository owner and the exact full head SHA is attested; collaborator-authored sensitive changes fail closed under the external safety policy
wait for the latest required checks bound to the exact head SHA
call GitHub's immediate squash-merge endpoint and continue only when it reports merged: true
pull the protected main; its trusted workflow opens a canonical-sync bot PR for generated artifacts and contributor credits when needed

What It Automates

exact-head required-check polling
handoff of post-merge contributor and artifact drift to the canonical-sync PR lane

What It Does Not Automate

PR-body rewriting or normalization
closing or reopening PRs to refresh metadata or workflow runs
conflict resolution on the PR branch
manual judgment for risky skill changes
semantic review when the distinct manual-review-required check is present; the review fingerprint covers the complete nearest skill directory, including nested examples, scripts, lockfiles, references, and assets
README community-source audits when the source metadata is ambiguous
fork-only edge cases that require contributor coordination outside GitHub permissions
base-branch or head drift: stale evidence is discarded, the checkout must be refreshed to the current origin/main, and the batch must be rerun; there is no automatic retry
auto-merge and merge-queue enrollment; deferred merge state is rejected

When To Stop

Stop and switch to the manual playbook when:

the PR is CONFLICTING
merge:batch reports a check failure that needs source changes, not maintainer automation
the PR needs a manual README credits decision
an external PR's local diff contains a symlink, gitlink, executable mode, unknown path/type, oversized blob, or other non-allowlisted change
the workflow run cannot be bound to the intended PR number, current head SHA, pull_request event, and trusted workflow definition
fork approval or branch permissions are missing
effective strict protection for main cannot be proven

In those cases, follow Merging Pull Requests and the relevant sections in MAINTENANCE.md.

5.4 KiB Raw Blame History