# 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`](../../.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

```bash
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:

```bash
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](merging-prs.md) and the relevant sections in [MAINTENANCE.md](../../.github/MAINTENANCE.md).