np-flow-merge-gate

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.