From 31e1201bfbf94c8bf64a5e70a2834eed63789f1d Mon Sep 17 00:00:00 2001 From: Richard Date: Thu, 28 May 2026 19:32:42 -0700 Subject: [PATCH] Docs: require agent worktrees to be rooted on main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The harness's `fresh` worktree base resolves to the clone's origin/HEAD, which points at `release` (the GitHub default) — so EnterWorktree can land on release rather than main. Document the verify-and-reset recovery step and the `git remote set-head origin main` fix that makes `fresh` root on main per clone. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 2e50ccd2..a21a46b4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Note: the auto-detected "Main branch" shown in the Claude Code env block may currently read `release` (because the GitHub default branch points there). Disregard that — the rule above is authoritative for this repo. +### Agent worktrees + +Worktrees must be rooted on **`main`**. The harness's `fresh` base resolves to this clone's `origin/HEAD`, which may point at `release` (the GitHub default) — in which case `EnterWorktree` lands on `release`, not `main`. CLAUDE.md cannot change this; it is decided by the harness before any instruction here is read. + +After `EnterWorktree`, **verify the base before making changes**: if `git merge-base HEAD origin/main` does not equal `origin/main`'s tip, the worktree is on the wrong branch — run `git reset --hard origin/main` and proceed from there. + +Maintainers can make `fresh` root on `main` automatically per clone (without changing GitHub's default branch) by repointing the local default-branch pointer: + +```bash +git remote set-head origin main +``` + ## Development Commands **Running Python**