From 118b265492c83845540b5596e102206995ce42a8 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sun, 8 Nov 2026 10:32:12 +0000 Subject: [PATCH] docs(agents): pin the base SHA and lease exactly when working in parallel worktrees Worktrees share refs (including origin/*) and the stash across sessions, so a fetch in one worktree moves origin/main under the others. Record the rule: pin the base SHA once, push with an exact-SHA lease, never use a bare git stash. Co-Authored-By: Claude Opus 5.5 --- .agents/playbook.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/.agents/playbook.md b/.agents/playbook.md index 5e353c7bbef..87179b56b1f 100644 --- a/.agents/playbook.md +++ b/.agents/playbook.md @@ -920,6 +920,26 @@ source changed. Treat the local run as **advisory**: the `npm run build:schemas` in the same tree cannot fail the SDK's schema-root version check mid-run. +### Parallel worktrees + +Git worktrees isolate the working tree, index and `HEAD`. They share the +object store, every ref (including remote-tracking `origin/*`) and the stash. +One session's `git fetch` therefore moves `origin/main` for every other +worktree of the same clone, mid-task. + +- Resolve the base once, right after your first fetch + (`BASE=$(git rev-parse origin/main)`), and use that SHA for every rebase, + diff and test baseline. Do not re-resolve `origin/main` mid-task; refetch + and re-pin deliberately if you need a newer base. +- Force-push with an exact lease: + `git push --force-with-lease=:`. A bare + `--force-with-lease` compares against the shared `origin/`, which + another session may have moved. +- Never use bare `git stash` / `git stash pop`; another session can pop your + entry. Prefer a temporary WIP commit. If you must stash, use + `git stash push -u -m ""` and restore by SHA with + `git stash apply`, then drop your entry by its tag. + ## PR Preparation Checklist Before creating or updating a PR, always: