guards(git): reviving a stale branch can silently reverse a later fix — 75 of 87 revivable branches carry one #17178

Problem

A stale branch does not merely lag main — it can carry a reversal of a fix that landed after
it. Reviving one, or resolving its conflicts in its own favour, silently removes the later fix.

This was found while triaging the local branch backlog, and it is not rare.

Verified case

issue-15165-search-recursion is the ideal-looking revival candidate: 6 files touched, 3 unlanded,
focused commits that name their issue. Its entire residual diff in
autobot-backend/knowledge/search.py is one hunk replacing

logger.warning("ChromaDB filtered query failed (%s); no results, never an unfiltered retry (#16662)", exc)
return {"ids": [[]], "documents": [[]], "metadatas": [[]], "distances": [[]]}

with a fallback that does kwargs.pop("where", None) and re-queries unfiltered. That reverses
#16662: the where filter is what scopes results to the permitted set, so the retry returns
documents the caller is not entitled to see. The branch predates #16662 and never learned about it.

The recursion fix those commits advertise had already landed on main by another path, so the
regression is the only residue. Two further branches (issue-15455-ratchet-2b,
train/2026-09-13-batch2b) carry the same stale hunk. Recorded on #15165.

Scale

Of 118 local branches carrying genuinely unlanded work, 87 are tightly scoped (≤8 unlanded files)
and therefore look revivable. 75 of those 87 hold at least one file predating a later fix. 12 are
clean.

A hit means the branch's copy of a file predates a later fix — a revival hazard, not a proven
regression. A clean rebase keeps main's line. It bites when the branch's version is taken
wholesale or a conflict is resolved toward the branch, which is exactly what "update the branch and
continue" invites. Small and focused is what makes a branch dangerous; nobody merges an obviously
dead 2,000-file branch.

Why the existing guards miss it

Every structural test calls these branches unlanded work: commits are unreachable from main, the
diff is non-empty, the commit subjects cite a real open issue. Only the content distinguishes
"work that never landed" from "a fix that was superseded and would now regress". Nothing currently
looks at that.

Acceptance criteria

• A guard that, given a branch, reports any file whose content predates a fix main already
  carries, and names the later issue — runnable before a branch is revived or rebased
• The detector's two mandatory filters are implemented and tested: issue references capped at
  the repository's real maximum issue number (#800000 and #336791 are CSS hex colours, and
  an uncapped scan flags ~95% of branches), and hub files excluded (ratchet baselines,
  known-large lists, .secrets.baseline, .github/) since every stale branch churns those
• The guard distinguishes nothing found from did not look in its output
• Documented rule in the git/branch developer docs: never git checkout <branch> -- <file>;
  resolve conflicts toward main unless the branch's version adds something stateable
• The 75 flagged branches are each dispositioned with evidence, or the list is regenerated and
  re-triaged if the backlog has moved

Related

• perf(api): /api/knowledge_base/search stops answering under concurrent load — hidden for the life of the file by a swallowed timeout #15165 — the verified case, with the full hunk
• security(kb): the ownership helpers fail open and misread shared and group facts #16662 — the tenancy fix that would be reversed
• Branches and worktrees drift from base unchecked: 0 of 86 worktrees current, 73 no longer merge #15306 — branches and worktrees drift from base unchecked
• chore(git): 113 stashes — 18 stranded, now rescued to branches; each needs an owner and a verdict #14078 — stash/branch rescue doctrine