chore(agents): note stale-local-branch-from-squash-merge git gotcha

A second lesson from this session's main reconciliation: a local main that
looked "12 ahead / 6 behind" was actually stale, its commits already
squash-merged upstream. patch-id (git cherry) misreports them as not
upstream; verify by content and reset + cherry-pick the genuinely-new
commits instead of rebasing superseded ones over later upstream fixes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ChipWolf

home/dot_agents/AGENTS.md

@@ -63,6 +63,7 @@ Always edit the source, not the deployed file. When updating any memory file: re
 - **Before opening a PR: clean up history.** Squash messy work-in-progress or AI-attributed commits into a clean, atomic commit sequence on the branch. The branch is yours until `gh pr create` succeeds.
 - **Once a PR is open: never amend or force-push.** Use follow-up commits so reviewers see exactly what changed between their review and your response. The branch now belongs to the reviewer; rewriting it erases the diff they expect to see. Preserve every change as a separate commit.
 - **Renovate auto-merge needs platform prerequisites, not just `automerge: true`.** With a restrictive top-level `schedule`, Renovate's own merge step only runs inside that window, so green PRs can sit unmerged for days. To merge whenever checks pass, rely on GitHub-native auto-merge (`platformAutomerge`, default true): it requires the repo's "Allow auto-merge" setting enabled AND branch protection on the target branch with the CI checks marked required. Set those required checks non-strict (do not require the branch be up to date) so a rebase schedule cannot deadlock merges, and leave admins exempt so the owner's direct pushes still work. Diagnose "automerge configured but PRs piling up" by correlating the last successful auto-merge against recent `schedule`/config commits, then verify the fix non-destructively by enabling auto-merge on a failing PR: GitHub should accept it but hold it (BLOCKED), not merge.
+- **A "diverged" local branch may just be stale from squash-merges.** When a local branch (often `main`) reports N ahead / M behind and a rebase conflicts, do not assume the local commits are valuable unpushed work. Squash-merged commits keep their original SHAs locally but get a different patch-id upstream, so `git cherry` / patch-id matching reports them as "not upstream" even when their content is already merged (the rebase itself may still auto-drop a few as "already upstream"). Verify by content against the upstream tip (`git diff origin/main HEAD -- <file>`, or grep the upstream blob for the feature), not by patch-id. If the work is already upstream, back up the branch then reset it to the upstream tip and cherry-pick only the genuinely-new commits, rather than rebasing: replaying superseded commits conflicts needlessly and can regress later upstream fixes (for example a CI repair that touched the same files).
 
 ---