chore(maintainers): Document merge-batch workflow

Add a short maintainer guide for merge:batch and link it from the
existing merge policy docs.

Lock in the source-validation CI fixes discovered during the
merge-batch end-to-end exercise so shallow checkout and missing
base-branch fetch regressions fail the workflow contract test.

.github/MAINTENANCE.md

@@ -237,7 +237,7 @@ We used this flow for PRs [#220](https://github.com/sickn33/antigravity-awesome-
 
 **Maintainer shortcut for batched PRs:**
 
-- Use `npm run merge:batch -- --prs 450,449,446,451` to automate the ordered maintainer flow for multiple PRs.
+- Use `npm run merge:batch -- --prs 450,449,446,451` to automate the ordered maintainer flow for multiple PRs. See [docs/maintainers/merge-batch.md](../docs/maintainers/merge-batch.md) for the short usage guide.
 - The script keeps the GitHub-only squash merge rule, handles fork-run approvals and stale PR metadata refresh, waits only on fresh required checks, retries `Base branch was modified`, and runs the mandatory post-merge `sync:contributors` follow-up on `main`.
 - It is intentionally not a conflict resolver. If a PR is conflicting, stop and follow the manual conflict playbook.
 

docs/maintainers/merge-batch.md

@@ -0,0 +1,55 @@
+# Merge Batch
+
+`merge:batch` is the maintainer shortcut for merging multiple PRs in order while keeping the GitHub-only squash rule and the post-merge contributor sync.
+
+## Prerequisites
+
+- Start from a clean `main`.
+- Make sure [`.github/MAINTENANCE.md`](/Users/nicco/Projects/antigravity-awesome-skills/.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.
+
+## Happy Path
+
+`merge:batch` will:
+
+- refresh the PR body when the Quality Bar checklist is missing
+- close and reopen the PR if stale metadata needs a fresh `pull_request` event
+- approve fork runs waiting on `action_required`
+- wait for the fresh required checks on the current head SHA
+- merge with GitHub squash merge
+- pull `main`, run `sync:contributors`, and push a README-only follow-up if needed
+
+## What It Automates
+
+- PR body normalization against the repository template
+- stale PR metadata refresh
+- required-check polling for the current PR head
+- the post-merge contributor sync step
+- the retry loop for `Base branch was modified`
+
+## What It Does Not Automate
+
+- conflict resolution on the PR branch
+- manual judgment for risky skill changes
+- README community-source audits when the source metadata is ambiguous
+- fork-only edge cases that require contributor coordination outside GitHub permissions
+
+## 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
+- fork approval or branch permissions are missing
+
+In those cases, follow [Merging Pull Requests](/Users/nicco/Projects/antigravity-awesome-skills/docs/maintainers/merging-prs.md) and the relevant sections in [MAINTENANCE.md](/Users/nicco/Projects/antigravity-awesome-skills/.github/MAINTENANCE.md).

docs/maintainers/merging-prs.md

@@ -9,6 +9,7 @@
 - Do **not** integrate a PR by squashing locally, pushing to `main`, and then closing the PR. That would show "Closed" and the contributor would not get proper credit.
 - Before merging, require the normal PR checks from [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) to be green. If the PR touches `SKILL.md`, also require the separate [`skill-review` workflow](../../.github/workflows/skill-review.yml) to pass.
 - For PRs that touch `SKILL.md` or risky guidance, require a real manual logic review in addition to the automated checks. Confirm the instructions, failure modes, and `risk:` label make sense before merging.
+- For ordered multi-PR maintainer batches, use [Merge Batch](merge-batch.md) as the operational shortcut and keep this document as the policy reference.
 
 ## If the PR has merge conflicts
 
@@ -77,5 +78,6 @@ Only if merging via GitHub is not possible (e.g. contributor unreachable and you
 
 ## References
 
+- [Merge Batch](merge-batch.md)
 - [GitHub: Creating a commit with multiple authors](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors)
 - [GitHub: Merging a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request)

tools/scripts/tests/automation_workflows.test.js

@@ -133,11 +133,26 @@ assert.match(
   /- name: Audit npm dependencies[\s\S]*?run: npm audit --audit-level=high/,
   "CI should run npm audit at high severity",
 );
+assert.match(
+  ciWorkflow,
+  /source-validation:[\s\S]*?- uses: actions\/checkout@v4[\s\S]*?with:[\s\S]*?fetch-depth: 0/,
+  "source-validation should use an unshallowed checkout so base-branch diffs have a merge base",
+);
+assert.match(
+  ciWorkflow,
+  /source-validation:[\s\S]*?- name: Fetch base branch[\s\S]*?run: git fetch origin "\$\{\{ github\.base_ref \}\}"/,
+  "source-validation should fetch the PR base branch before changed-skill README credit checks",
+);
 assert.match(
   ciWorkflow,
   /- name: Verify README source credits for changed skills[\s\S]*?run: npm run check:readme-credits -- --base "origin\/\$\{\{ github\.base_ref \}\}" --head HEAD/,
   "PR CI should verify README source credits for changed skills",
 );
+assert.match(
+  ciWorkflow,
+  /source-validation:[\s\S]*?- name: Fetch base branch[\s\S]*?- name: Install npm dependencies[\s\S]*?- name: Verify README source credits for changed skills/,
+  "source-validation should fetch the base branch before running the changed-skill README credit check",
+);
 assert.match(
   ciWorkflow,
   /main-validation-and-sync:[\s\S]*?- name: Audit npm dependencies[\s\S]*?run: npm audit --audit-level=high/,