Worktree

One checkout per piece of work. The shared checkout stays on whatever the
person left it on, and the branch you create comes off the default branch as
it is on origin right now, not off whatever HEAD happens to be.

Two callers, two paths. Find out which you are first: an agent run carries
HIVE_RUN_ID in its environment; a terminal session does not.

Before either path

REPO=<absolute path of the project checkout>
git -C "$REPO" fetch origin --prune
DEFAULT=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo main)

Refuse to continue if the shared checkout has uncommitted changes on the branch
you were going to base on. That is a question for the person, not a thing to
branch over.

In a session

1. Prefer the native EnterWorktree tool. It creates the worktree and switches
   the session into it. It also names the branch worktree-<slug>, which is
   not the branch the plan asked for, so rename it at once:

   git branch -m "<branch>"

   The shipper finds the PR by branch name; a branch named worktree-… is one
   nobody will look for.

2. Without the tool, fall back to git. .worktrees/ must be ignored before
   anything lands in it:

   git -C "$REPO" check-ignore -q .worktrees || echo '.worktrees/' >> "$REPO/.git/info/exclude"
   git -C "$REPO" worktree add "$REPO/.worktrees/<slug>" -b "<branch>" "origin/$DEFAULT"

3. Install dependencies the way the repository does (pnpm install,
   npm ci, whichever its lockfile says), then run the cheapest static check
   it has and confirm it is green. A red baseline is not yours to fix and not
   yours to build on; report it.

As an agent (builder, fixer)

Agents have no EnterWorktree and must never write inside the project's
tree. Git allows one worktree per branch, so look first: git -C "$REPO" worktree list --porcelain. A branch already checked out somewhere (the
builder's worktree, before merge-pr removes it) is worked on there,
never duplicated. Otherwise the worktree lives in your own working directory:

WT="$HOME/.hive/work/<agent>/<repo-name>-<slug>"
git -C "$REPO" worktree add "$WT" -b "<branch>" "origin/$DEFAULT"

For a fixer on an existing PR branch, git allows one worktree per branch and
the person's own checkout, the first entry of worktree list, may be the one
holding it. That checkout is never an agent's. Work in a detached tree at
the branch's tip instead, and push to the branch by name:

git -C "$REPO" fetch origin
git -C "$REPO" worktree add --detach "$WT" "origin/<branch>"
git -C "$WT" push origin HEAD:<branch>      # after each round's commits

Then, for an agent worktree under $HOME/.hive/work/, new or reused, write
$WT/.hive/.gitignore containing the single line * if it is not there.
Never in a worktree that is not yours. .hive/ is the Hive's
working folder (plans, specs, a builder's progress notes). Ignored from the
start, it never shows as untracked, and merge-pr's teardown removes the
worktree without --force.

Then install and baseline as above. Put the path in every ledger_post you
write for the job, as meta.worktree, with the project checkout it was cut
from as meta.checkout (the repo path your job named): the shipper tears
the worktree down after the merge, and term <your name> in the console puts
a person's terminal on it, under the project the checkout maps to.

Every command from here on is cd "$WT" && … or git -C "$WT" …, and every
commit is preceded by git -C "$WT" branch --show-current reading the branch
you were given. A subagent you dispatch gets WT in its prompt and the same
rule.

Tearing down

Not yours, unless you are the one who made it and the work is abandoned.
merge-pr removes the worktree and the branch after the merge. If you must:

git -C "$REPO" worktree remove "$WT"

A refusal means uncommitted files. Stop and say so. Never --force. The one
exception is merge-pr's teardown of an agent worktree whose only leftovers
are under .hive/, and it is merge-pr's to make.

Red flags

• Branching off the current branch instead of origin/<default>.
• A worktree-<slug> branch left unrenamed.
• Working in the project's own checkout from an agent run.
• git worktree remove --force to make a refusal go away (merge-pr's .hive/-only case is the one exception).