---
id: 10212
title: Mandate pre-push rebase to close stale-branch hygiene gap under rapid merge tempo
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees:
  - neo-gemini-pro
createdAt: '2026-04-22T21:11:35Z'
updatedAt: '2026-05-15T12:43:09Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10212'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-22T21:40:49Z'
---
# Mandate pre-push rebase to close stale-branch hygiene gap under rapid merge tempo

# Context

Session velocity (2026-04-22) empirically showed **4× stale-branch instances in ~4 hours** of active work:

- **PR #10193** — branch forked pre-`#10185` merge; re-introduced merged hunks
- **PR #10196** — branch carried stale `resources/content/*` sync-state files
- **PR #10204** — branch forked pre-`#10199` merge; diff carried `#10199`'s changes already in dev
- **PR #10211** (the cross-family-mandate PR itself) — branch forked pre-`#10205` merge; diff carried `unit-test.md §7` + `ConfigCompleteness.spec.mjs` already in dev

This is not a discipline issue with any individual author. It's a **structural consequence of rapid merge cadence + no pre-push rebase check**. In a low-tempo session (one PR merged per day), a feature branch stays current against dev trivially. In today's tempo (~6 merges in a few hours), the stale-branch window closes within minutes of each merge.

The `pull-request` skill already has `§2.3` *"Universal safety net"* covering branch-name verification (`git branch --show-current`) — but nothing covering *"is my branch rebased against the latest dev?"*. The gap this ticket closes.

# The Problem

Velocity itself degrades review surface without author awareness. Symptoms:

1. `gh pr diff` shows changes already in dev, making reviews unreadable
2. `mergeable: UNKNOWN` until GitHub fully computes, blocking confident merge
3. Review metrics inflated — 60-line PRs appear as 130-line PRs
4. Reviewer must mentally subtract already-merged content to evaluate actual change surface

The author is unaware because their local dev isn't updated. They opened a PR from a working branch, not realizing someone else's merge made their base stale. The observed ~4× repeat in one session confirms this is systemic, not author-specific.

# The Architectural Reality

The fix site is `.agent/skills/pull-request/references/pull-request-workflow.md §2.3` — *"Universal safety net"*. It already documents a `git branch --show-current` pre-commit check. One sibling command closes the rebase-freshness gap.

Canonical check:

```bash
git fetch origin
git merge-base HEAD origin/dev | diff - <(git rev-parse origin/dev)
# Empty output = branch is based on current dev tip. Safe to push.
# Non-empty = origin/dev has advanced since branch-point. Rebase first:
git rebase origin/dev
```

Or the faster no-op check: `git log origin/dev..HEAD --oneline` — if output lists only your own expected commits, proceed; if it shows a merge-gap or unexpected commits, rebase first.

# The Fix

Update `.agent/skills/pull-request/references/pull-request-workflow.md §2.3`:

Add a sub-section after the current branch-name safety net:

```markdown
### 2.3.1 Branch Freshness Check (pre-push)

Before the first `git push` that opens a PR, AND before every force-push that would update the PR branch:

    git fetch origin
    git merge-base HEAD origin/dev | diff - <(git rev-parse origin/dev)
    # Empty output = branch is based on current dev tip. Safe to push.
    # Non-empty = origin/dev has advanced since branch-point. Rebase first:
    git rebase origin/dev

**Why this matters under rapid merge tempo:** when multiple PRs merge in a short window (common for active refactor epics), every outstanding feature branch becomes stale within minutes. Pre-push rebase ensures the PR diff reflects only your own change surface, not already-merged content from peer branches.

**Exception — first push of a freshly-branched feature:** if the branch was just created via `git checkout -b agent/[ticket-id] origin/dev` and no sibling PRs have merged since, skip this check. The branch-point IS `origin/dev`'s tip.
```

Plus a one-line forward-reference in `AGENTS_STARTUP.md §9` alongside the existing `pull-request` skill citation: *"...branch freshness check..."* added to the feature-list comma-string.

# Acceptance Criteria

- [ ] `pull-request §2.3.1 Branch Freshness Check` codified with the pre-push rebase command + rationale
- [ ] Exception clause for freshly-branched features where the check is a no-op
- [ ] `AGENTS_STARTUP.md §9` cites the branch-freshness convention in the `pull-request` skill feature-list

# Out of Scope

- **CI / GitHub Actions enforcement** — follow-up ticket after adoption period, matching `#10208`'s skill-level-first cadence
- **Force-push history preservation** (`git push --force-with-lease` etc.) — orthogonal concern
- **Retroactive application** to already-merged PRs
- **Pre-commit hook installation** — adoption-path-dependent, not this ticket's scope

# Avoided Traps

- **"Just tell authors to rebase more carefully"** — rejected. Discipline without convention doesn't scale across agents and across sessions. The systemic issue needs a systemic mitigation.
- **"Rebase every single commit"** — rejected. Most commits don't push; the rebase check fires at push time, not commit time.
- **"Require rebase even on freshly-branched features"** — rejected. If the branch point is already `origin/dev`'s tip, the rebase is a no-op. Exception clause prevents ritualistic no-op rebases.
- **"Hard-block all merges until rebased"** — rejected. Some rebase attempts fail (conflicts); the mandate is on the *author* pre-push, not a merge-time gate. Reviewer can still approve; CI-level block is follow-up scope.
- **"Go straight to CI enforcement"** — rejected. `#10208`'s skill-level-first cadence applies equally here; empirical adoption over ~weeks will show whether CI is needed.

# Related

- **`#10208`** — sibling mandate in the PR-workflow discipline space (cross-family review). These two conventions compound: cross-family catches substrate-alignment issues; branch-freshness catches review-surface-cleanliness issues. Together they tighten the pre-merge discipline loop.
- **`#10109`** — adjacent scope (PR comment hygiene, update-vs-new-comment)
- **Empirical instances this session**: PR `#10193`, `#10196`, `#10204`, `#10211`. Each review flagged the stale-branch pattern as non-blocking but recurrent. 4 instances ≥ systemic threshold.

# Handoff Retrieval Hints

- `query_raw_memories(query="stale branch rebase pattern rapid merge tempo")`
- `query_raw_memories(query="pull-request §2.3 branch freshness pre-push rebase")`
- `query_summaries(query="PR workflow discipline branch hygiene")`
- Commit-range anchor: PRs `#10193`, `#10196`, `#10204`, `#10211` (the 4× empirical instances)

Known contributing sessions (partial, restart-fragmented):
- `ae546a40-2133-482f-85a6-779fdf6757b2` (current session; 4× empirical instances + Tobi's velocity observation)

## Timeline

- 2026-04-22T21:11:37Z @neo-opus-ada added the `documentation` label
- 2026-04-22T21:11:37Z @neo-opus-ada added the `enhancement` label
- 2026-04-22T21:11:37Z @neo-opus-ada added the `ai` label
- 2026-04-22T21:11:38Z @neo-opus-ada added the `architecture` label
- 2026-04-22T21:16:54Z @neo-gemini-pro cross-referenced by PR #10211
- 2026-04-22T21:18:16Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-04-22T21:19:25Z @neo-gemini-pro cross-referenced by PR #10213
- 2026-04-22T21:23:43Z @neo-gemini-pro referenced in commit `f8271e9` - "feat(workflow): formalize pre-PR rebase mandate (#10212)"
- 2026-04-22T21:40:49Z @tobiu referenced in commit `9fa02e3` - "feat(workflow): formalize pre-PR rebase mandate (#10212) (#10213)

* feat(workflow): formalize pre-PR rebase mandate (#10212)

* fix(workflow): address PR #10213 review feedback (#10213)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-22T21:40:49Z @tobiu closed this issue
- 2026-04-22T22:01:28Z @neo-opus-ada cross-referenced by #10139
- 2026-04-25T05:03:58Z @neo-gemini-pro cross-referenced by PR #10329
- 2026-04-27T10:59:27Z @neo-opus-ada cross-referenced by #10214

