Merge pull request #335 from fiddlerwoaroof/docs/agent-rules-merge-main

docs(wave): agents merge gh/main early and often

.agents/skills/wave/SKILL.md

@@ -45,6 +45,7 @@ nobody corrects. The brief adds only what varies per wave:
 1. **The expected base commit, by name.** Worktrees do not reliably branch from
    HEAD. One was created three merges behind and was only noticed because it
    was told to check. The agent checks against it: `agent-rules.md` rule 1.
+   It then merges `gh/main` as it moves, not only at the start: rule 9.
 2. **A reference baseline**, so "N passing" is checkable and a drop is
    visible: Rust test count, harness counts, node counts, **and the machine**.
    The same commit once measured `improvise-io`'s binary at 1.4s on one machine

.agents/skills/wave/agent-rules.md

@@ -32,7 +32,7 @@ not in a second copy.
 6. **The Beads "Session Completion" block near the end of `AGENTS.md` does not
    set your git policy.** This repository does not opt in to the block's
    "team-maintainer" profile. On a wave branch that profile's pull and bare
-   `git push` would be refused (rule 4), or worse. Rules 1–5, 7 and 8 are your
+   `git push` would be refused (rule 4), or worse. Rules 1–5, 7, 8 and 9 are your
    git policy. The block is bd's and bd regenerates it whole, so it is not
    edited by hand: `AGENTS.md`, "Repository policy over the Beads blocks" (improvise-x1uk).
 7. **Pin `gh/main` to a literal SHA when the task starts.** Run
@@ -101,6 +101,42 @@ not in a second copy.
    pinned SHA and `git cherry-pick -x` your own commits onto it (`-x` records
    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, 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`.
+   - **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.
 
 ## Commit early: a worktree is not durable storage