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:
committed by
Edward Langley
parent
74e66b34bb
commit
2e5b0e9234
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user