name: np-flow-merge-gate
description: Gate a branch merge on concurrent work finishing, then decide clean-vs-issues. Use when another agent/session/cron is operating on the same repo (a worktree-agent, a cloud routine, a teammate) and you want to merge a branch without colliding — wait for the repo to go quiet, then merge if the diff is clean or ask the user how to proceed if there are conflicts or forbidden trailers. Trigger phrases: "wait to merge", "merge when the other branch finishes", "is it safe to merge yet".
Merge gate — wait out concurrency, then merge on a clean diff
~/Code/nervepack is a single working tree with one git HEAD. When a second
session (often a .claude/worktrees/agent-* worktree), a cron, or a cloud routine
is committing here too, merging blind risks sweeping their files, orphaning their
commits, or merging a half-finished state. This workflow makes the merge wait for
quiet, then gate on the diff. It is the operational front-end to the
"[concurrent session]" rules in AGENTS.md.
When to use
- You have a branch ready to merge and you know (or suspect) another agent/
branch/cron is active in the same repo.
- The git log/worktree changed under you mid-task (a ref moved, a commit vanished).
- The user says "wait for the other branch to finish, then merge."
The waiter
engine/setup/np-merge-wait.sh blocks until the repo is quiet (all refs + HEAD
- working tree stable across a full poll interval), then checks merge-readiness.
Read-only — it never commits, merges, or pushes.
engine/setup/np-merge-wait.sh --repo ~/Code/nervepack --branch <BR> --base origin/main
Cadence: starts at --interval 60s, adds --backoff 30s each cycle, gives up at
--timeout 1800s (30 min). --settle (default 2) is how many consecutive
identical samples count as quiet. Run it after you've finished your own commits
(your own activity counts as churn and would reset the quiet timer).
Run it in the background and let the host re-invoke you on exit — a 30-minute block
shouldn't hold the foreground.
Exit codes → what you do
| Exit | Meaning | Action |
|---|
0 RESULT: CLEAN | Quiet; branch merges cleanly; no policy issues | Option 1 — proceed. Refresh understanding (git fetch, re-read the diff), then merge. |
2 RESULT: ISSUES | Quiet, but merge conflicts and/or forbidden AI-attribution trailers (coding-rules §6) | Option 2 — stop and notify the user. Summarize the issues and ask whether to (a) gate the merge until the other branch/agent finishes and re-check, or (b) resolve now (rebase out trailers / resolve conflicts). Do not merge unprompted. |
3 RESULT: TIMEOUT | Repo never settled within --timeout | Notify the user. The other work is still going; ask whether to keep waiting (re-run, longer timeout) or intervene. |
Rules carried from the concurrency section
- Never
git add -A/commit -am in a shared tree; stage and commit explicit
paths (git commit -m … -- <paths>).
- Tag a backup (
git tag <name> <sha>) before any reset/rebase, and prefer
committing detachable work from an isolated git worktree off the committed base.
- On a clean (
exit 0) gate, still git fetch and treat origin/main as the
source of truth before merging.
- Strip any forbidden trailer before the merge, never after it lands on
main
(see [[np-kb-testing-ci]] §4 for the filter-branch recipe).
Related: AGENTS.md § "Commit conventions" (no AI attribution), [[np-kb-testing-ci]]
(the filter-branch trailer-scrub recipe), and the AGENTS.md concurrency section this operationalizes.
