Merge Queue Readiness
Trigger
Before adding the PR to the merge queue (or before the final push if the repo uses a merge queue).
Protocol
- Fetch latest main:
git fetch origin main
- Run the simulation command (preferred):
/swarm ci-simulate [<pr-ref>]
The optional positional <pr-ref> is the PR branch/ref to simulate (defaults to the current branch). It does NOT accept --base/--head flags. The command runs fixed local gates: bun run typecheck, bun run lint, bun run build, then a full-batch bun test. It creates a temporary detached worktree under os.tmpdir()/swarm-ci-simulate (a SIBLING of the project root, not project-relative), merges the PR ref, runs the gate sequence, removes the worktree, and prunes metadata. It does not accept arbitrary shell commands and does NOT replicate CI's quarantine/retry semantics — it is a fast pre-merge signal, not a CI parity check.
- Manual fallback: If the command is unavailable, create a temporary simulation worktree (do NOT mutate the PR branch). The default worktree base is a SIBLING of the project root (
<parent>/.swarm-worktrees/), overridable via the worktree_dir config; on Windows, very long paths may be shortened to os.tmpdir()/swwt/.... Place the worktree under that base. Do NOT hardcode /tmp — it does not exist on Windows.git worktree add ../.swarm-worktrees/merge-sim origin/main
cd ../.swarm-worktrees/merge-sim
git merge <pr-branch> --no-edit
- Run integration + unit tests against the merged result:
bun test tests/integration --timeout 120000
bun test tests/unit --timeout 120000
(Use per-file loops for hot modules per AGENTS.md invariant 6)
- Battery tree receipts (#3605 AC7): if a gate-sensitive local battery is part of your evidence, it must bind to the merged result. Receipts are produced by
scripts/ci/run-test-battery.ts and bind to the tree the battery RAN on, so the battery itself must run inside the merged-result worktree (step 3/4 tree, before its teardown): run the battery there, then validate bash scripts/ci/check-battery-tree-receipt.sh <receipt.json> <merged-worktree-root> against that same tree. The receipt is a tree-binding freshness token, NOT proof the battery passed — read the battery's own pass/fail summary alongside it. A TREE-RECEIPT: mismatch or unknown-file refusal means the battery validated a tree this simulation is NOT validating — re-run the battery inside the merged-result worktree before queueing. Scope: /swarm ci-simulate does NOT run the battery or the receipt check and tears its worktree down automatically, so AC7 battery evidence can only be gathered on the MANUAL worktree path (steps 3–4, before its teardown); this repository's own tooling (scripts/ci/) — consumer projects should use their repo's equivalent.
- If failures: Fix on the PR branch, re-push, re-simulate. Always run the cleanup step (7) before re-simulating or on any exit path — do not leave the simulation worktree behind.
- Cleanup for manual fallback (run on EVERY exit path, including failure): Prefer non-force
git worktree remove ../.swarm-worktrees/merge-sim. If the removal is blocked or fails, surface the block to the user (the worktree guard fails closed for safety) and run git worktree prune.
- Only after simulation passes, add PR to the merge queue.
Why this matters
PR-branch CI and merge-group CI test DIFFERENT things:
- PR-branch: tests the PR head commit in isolation
- Merge-group: tests a temporary merge of PR head + latest main
Integration tests that pass on the PR branch may fail in merge-group context due to test interactions exposed by the merged result.
Automation
/swarm ci-simulate automates the merge-result worktree, merge, command run,
worktree removal, and metadata prune. Use the manual protocol only when the
command is unavailable or the repo needs bespoke setup.
1---2name: merge-queue-readiness3description: Pre-queue merge-group CI simulation. Triggered before adding a PR to a GitHub merge queue. Prevents merge-queue kick-outs from integration test failures.4metadata:5 source: https://skillmd.com/skills/zaxbyhub/merge-queue-readiness6 audience: swarm-plugin7---89# Merge Queue Readiness1011## Trigger12Before adding the PR to the merge queue (or before the final push if the repo uses a merge queue).1314## Protocol151. **Fetch latest main:** `git fetch origin main`162. **Run the simulation command (preferred):**17 ```18 /swarm ci-simulate [<pr-ref>]19 ```20 The optional positional `<pr-ref>` is the PR branch/ref to simulate (defaults to the current branch). It does NOT accept `--base`/`--head` flags. The command runs fixed local gates: `bun run typecheck`, `bun run lint`, `bun run build`, then a full-batch `bun test`. It creates a temporary detached worktree under `os.tmpdir()/swarm-ci-simulate` (a SIBLING of the project root, not project-relative), merges the PR ref, runs the gate sequence, removes the worktree, and prunes metadata. It does not accept arbitrary shell commands and does NOT replicate CI's quarantine/retry semantics — it is a fast pre-merge signal, not a CI parity check.213. **Manual fallback:** If the command is unavailable, create a temporary simulation worktree (do NOT mutate the PR branch). The default worktree base is a SIBLING of the project root (`<parent>/.swarm-worktrees/`), overridable via the `worktree_dir` config; on Windows, very long paths may be shortened to `os.tmpdir()/swwt/...`. Place the worktree under that base. Do NOT hardcode `/tmp` — it does not exist on Windows.22 ```23 git worktree add ../.swarm-worktrees/merge-sim origin/main24 cd ../.swarm-worktrees/merge-sim25 git merge <pr-branch> --no-edit26 ```274. **Run integration + unit tests against the merged result:**28 ```29 bun test tests/integration --timeout 12000030 bun test tests/unit --timeout 12000031 ```32 (Use per-file loops for hot modules per AGENTS.md invariant 6)335. **Battery tree receipts (#3605 AC7):** if a gate-sensitive local battery is part of your evidence, it must bind to the merged result. Receipts are produced by `scripts/ci/run-test-battery.ts` and bind to the tree the battery RAN on, so the battery itself must run inside the merged-result worktree (step 3/4 tree, before its teardown): run the battery there, then validate `bash scripts/ci/check-battery-tree-receipt.sh <receipt.json> <merged-worktree-root>` against that same tree. The receipt is a tree-binding freshness token, NOT proof the battery passed — read the battery's own pass/fail summary alongside it. A `TREE-RECEIPT: mismatch` or `unknown-file` refusal means the battery validated a tree this simulation is NOT validating — re-run the battery inside the merged-result worktree before queueing. Scope: `/swarm ci-simulate` does NOT run the battery or the receipt check and tears its worktree down automatically, so AC7 battery evidence can only be gathered on the MANUAL worktree path (steps 3–4, before its teardown); this repository's own tooling (`scripts/ci/`) — consumer projects should use their repo's equivalent.346. **If failures:** Fix on the PR branch, re-push, re-simulate. Always run the cleanup step (7) before re-simulating or on any exit path — do not leave the simulation worktree behind.357. **Cleanup for manual fallback (run on EVERY exit path, including failure):** Prefer non-force `git worktree remove ../.swarm-worktrees/merge-sim`. If the removal is blocked or fails, surface the block to the user (the worktree guard fails closed for safety) and run `git worktree prune`.368. **Only after simulation passes,** add PR to the merge queue.3738## Why this matters39PR-branch CI and merge-group CI test DIFFERENT things:40- PR-branch: tests the PR head commit in isolation41- Merge-group: tests a temporary merge of PR head + latest main4243Integration tests that pass on the PR branch may fail in merge-group context due to test interactions exposed by the merged result.4445## Automation46`/swarm ci-simulate` automates the merge-result worktree, merge, command run,47worktree removal, and metadata prune. Use the manual protocol only when the48command is unavailable or the repo needs bespoke setup.