# Nexus Rebase Runbook

Step-by-step workflow for rebasing Nexus fork commits onto new upstream Paperclip releases.

## Prerequisites

- `git rerere` enabled: `git config rerere.enabled true`
- `git range-diff` available (git 2.19+, confirmed 2.39.5 on this machine)
- Upstream remote configured: `git remote add upstream https://github.com/paperclipai/paperclip.git` (if not already)

## Pre-Rebase Checklist

1. Ensure working tree is clean: `git status`
2. Fetch upstream: `git fetch upstream`
3. Record current tip: `git log --oneline -1` (save this SHA as OLD_TIP)
4. Verify all tests pass before rebase: `pnpm test:run`

## Rebase Procedure

```bash
# 1. Fetch latest upstream
git fetch upstream

# 2. Rebase nexus commits onto upstream/master
git rebase upstream/master

# 3. If conflicts arise:
#    - git rerere will auto-apply previously recorded resolutions
#    - For new conflicts: resolve manually, then `git add` + `git rebase --continue`
#    - rerere automatically records new resolutions for future use

# 4. Verify rebase integrity with range-diff
#    ORIG_HEAD is the pre-rebase tip (set automatically by git)
git range-diff upstream/master ORIG_HEAD HEAD
```

## Post-Rebase Verification

1. **range-diff check:** `git range-diff upstream/master ORIG_HEAD HEAD`
   - Every nexus commit should show as "equivalent" (minor offset changes only)
   - Flag any commit showing significant diff changes for manual review
2. **Test suite:** `pnpm test:run` — all tests must pass
3. **Type check:** `pnpm typecheck` (if available) or `pnpm -r run typecheck`
4. **Branding spot check:** `pnpm vitest run --project packages/branding`

## Handling Common Scenarios

### Upstream changed a file we also changed (DISPLAY zone)
- Most common: string changes in UI components
- rerere should handle if previously resolved
- If new: resolve keeping Nexus display string, `git add`, continue

### Upstream added new constants to packages/shared/src/constants.ts
- Our changes are in `packages/branding/` (separate file) — no conflict expected
- If AGENT_ROLE_LABELS format changes upstream, update the DISPLAY zone mapping

### Upstream restructured a file entirely
- range-diff will show the affected nexus commit as "changed"
- Manually verify the nexus change still applies correctly
- Update zone taxonomy if file paths changed

## rerere Cache Notes

- Cache lives in `.git/rr-cache/` (not tracked by git)
- Cache is machine-local — lost on re-clone
- After a fresh clone, first rebase may require manual resolution
- Subsequent rebases at the same conflict points will auto-resolve

## Hook Re-installation

After a fresh clone, the commit-msg hook must be reinstalled:

```bash
# From repo root:
cp scripts/nexus-commit-msg-hook.sh .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```

Or using the install script:

```bash
bash scripts/install-hooks.sh
```