fast-forwarding-branches

Fast-forwarding the primary checkout

One job: keep the primary checkout's integration branch at the remote tip, safely, on a loop. Fast-forward when it is clean; report loudly and change nothing when it is not.

Why this lane exists (it explains every rule below)

Agents work in worktrees cut from the primary checkout. Everything a fresh worktree inherits — git hooks, repo scripts, CI config, the skills and agents themselves — comes from the primary's branch. So a primary that has drifted a week behind hands every newly-created worktree a stale base, and the staleness is invisible until something breaks oddly. One cheap pull --ff-only per tick keeps the base honest.

The second half matters just as much. Because agents are supposed to be in worktrees, the primary checkout should normally be clean. If a fast-forward is refused because local changes would be overwritten, that is not a routine condition to work around — it means uncommitted work is sitting in the primary. Clobbering it would destroy someone's work. So the refusal is the product of this lane: surface it, and stop.

Project bindings

Project-agnostic; the adopting project defines these in its own CLAUDE.md.

Placeholder	Meaning
<integration-branch>	The branch the primary checkout is expected to sit on (e.g. main)
<remote>	The remote to pull from (almost always origin)

The tick — run exactly this

Safe by construction: --ff-only never rewrites, merges, or clobbers anything — it refuses instead. The branch guard leaves a primary that is on some other branch completely alone. Run this from anywhere inside the repo (the primary checkout or any worktree — it resolves the primary itself):

PRIMARY="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
BRANCH="$(git -C "$PRIMARY" rev-parse --abbrev-ref HEAD)"

if [ "$BRANCH" != "<integration-branch>" ]; then
  echo "ff tick: skipped — primary is on '$BRANCH', not <integration-branch>"
else
  BEFORE="$(git -C "$PRIMARY" rev-parse --short HEAD)"
  git -C "$PRIMARY" pull --ff-only <remote> <integration-branch> 2>&1 | tail -8
  AFTER="$(git -C "$PRIMARY" rev-parse --short HEAD)"
  echo "ff tick: $BEFORE -> $AFTER"
fi