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.

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
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

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 drift: stale evidence is discarded and the batch must be rerun
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.

3.9 KiB Raw Blame History