# Rule: git worktrees

This project teaches worktrees. It should use them properly.

## One task, one worktree, one agent

```bash
# from the main checkout
git worktree add ../af-task-07 -b refactor/task-07-route-cards
cd ../af-task-07
pnpm install --frozen-lockfile
```

Naming: directory `../af-task-NN`, branch `refactor/task-NN-<slug>`. Both
derived from the task file so the mapping is never ambiguous.

## Why isolation matters here

The migration runs many agents in parallel over the same small set of files
(`tokens.css`, `verify.mjs`, `astro.config.mjs` are contended). Worktrees give
each agent its own working directory over one object store — cheap, and no agent
can see another's half-finished state.

The failure mode without them: two agents both "fix" `verify.mjs`, and the
second overwrites the first's assertions.

## Contended files

These are touched by many tasks. Whoever owns them per the plan is the **only**
writer; everyone else opens an issue in their task report instead of editing:

| File                               | Owner                   |
| ---------------------------------- | ----------------------- |
| `src/styles/tokens.css`            | `design-system-keeper`  |
| `scripts/verify.mjs`               | `verification-engineer` |
| `astro.config.mjs`, `package.json` | `astro-architect`       |
| `src/content/config.ts`            | `content-i18n-migrator` |

## Never rebase a task branch

Not onto `main`, not onto another task branch, not "just to tidy up". A rebase
rewrites every commit with a new SHA, so a branch that others branched from — or
that has already been merged — turns into a duplicate history that no longer
shares an ancestor with the original. Task 03 did this and flattened task 01's
merge into four look-alike commits; it is the same divergent-history trap that
broke the `pages` branch.

To pick up new work from `main`, **merge it in**: `git merge origin/main`. The
extra merge commit is the price of a history that stays true, and it is cheap.

## Before you start

1. `git fetch origin` — then branch from the ref your task file names as its
   base. Do not assume that base is `main`.
2. Read your task file end to end before writing anything.
3. Confirm your task's dependencies are merged. Task files list them.

## Before you finish

1. `pnpm run verify` green — without deleting assertions.
2. The relevant checklist in [`../checklists/`](../checklists/) complete.
3. `git fetch origin && git merge origin/main`, resolve conflicts in your
   worktree. **Merge — never rebase.**
4. Task report: what changed, what you verified, **what you did not do**.

## Cleanup

```bash
cd -                                    # back to the main checkout
git worktree remove ../af-task-07
git branch -d refactor/task-07-route-cards
```

Stale worktrees hold locks and confuse the next agent. `git worktree list`
should be short.

## Never

- Never work directly on `main`.
- Never force-push a shared branch. The `pages` branch is the sole exception,
  and only if CI owns it (see
  [`../context/publishing.md`](../context/publishing.md)).
- Never `git add -A` from the repository root. This repo has untracked local
  scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a
  commit.