docs(wave): rule 9 gates every merge of main and scopes stacked PRs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
This commit is contained in:
Claude (rules-merge-main)
2026-10-08 22:08:02 -07:00
committed by Edward Langley
parent 74e66b34bb
commit 2e5b0e9234
+29 -8
View File
@@ -102,17 +102,38 @@ not in a second copy.
where each came from). Close the old branch rather than force-pushing it:
`AGENTS.md`, "Shipping a wave".
9. **Merge main as soon as you can, and keep merging it.** The user:
"Agents should merge main asap" and, asked the point, "Reduces conflicts"
(2026-10-09). `git fetch gh`, then merge the new `gh/main` SHA (rule 7's
re-pin, done on purpose) at the start of a task, before every push, and
every time you resume. Main only gets further from your base, and a
conflict met early is small. Never `origin/main`, never rebase, never
squash (rule 8). Commit the merge through `scripts/agent-git`.
"Agents should merge main asap" and, when asked why, "Reduces conflicts"
(2026-10-09 UTC; bd memory `agents-merge-main-asap`, written by the
orchestrator; PR #335). Those two quotations are the user's words. The
timing below is the orchestrator's operationalisation of them.
- **When.** `git fetch gh`, then merge the new `gh/main` SHA (rule 7's
re-pin, done on purpose) at the start of a task, before the first review
request, before every push to a PR under review, and every time you
resume. Main only gets further from your base, and a conflict met early
is small. Never `origin/main`, never rebase, never squash (rule 8).
Commit the merge through `scripts/agent-git`.
- **After every merge of main, clean or not**, re-run the gates (see
"Gates") on the merged tree, not on each side, and diff the test names
against your pre-merge HEAD to see that none was lost. A clean merge is
the dangerous case: it can delete a test module or break a shared test
file with no conflict marker.
- **Re-measure your baseline** after a mid-task merge, and report it
against the merged SHA, so main's changes are not read as yours.
- **Resolve a conflict by hand.** For each conflicted file, diff the
result against both parents and the merge base, so a side's
non-conflicting changes are not lost to a whole-file `--ours` or
`--theirs`. Check that no test name was lost. Then re-run the gates
(see "Gates") on the merged tree, not on each side.
`--theirs`.
- **A stacked PR merges its base branch, not `gh/main`.** GitHub diffs it
against that base, so merging a `gh/main` ahead of the base puts main's
commits in its diff (the #145/#148 symptom, which rule 3's numstat
cannot see). The orchestrator retargets it to main once the base lands.
- **The exception is narrow.** A durability push of WIP (see "Commit
early") need not wait for a merge of main that conflicts. If you cannot
resolve the conflict yet, push the WIP to a separate wip branch, never
to the PR.
- **Each merge-and-push moves the head SHA** an in-flight review is aimed
at. Reviewers re-fetch the tip before posting, but do not merge main
only to push a reply.
- The mechanics are `AGENTS.md`, "Shipping a wave" (merge `gh/main`, never
`origin/main`) and "Merging many PRs at once" (diff each parent; two
clean changes to one test file can still fail together). Not restated here.