ce-worktree

Worktree による分離

現在の作業を分離されたワークスペースで行い、ユーザーのメインのチェックアウトに影響を与えないようにします。現在、ほとんどのコーディングハーネスはセッション開始時にデフォルトで worktree を作成するため、通常はすでに分離されています。

完了条件： 呼び出し元が既存または新規作成の分離されたツリーで作業しており、そのパスとブランチが報告されていること。そうでなければ、阻害要因が報告されていること。

操作順序：既存の分離を検出する -> ネイティブの worktree ツールを優先する -> 通常の git にフォールバックする。 ハーネスから認識できない worktree は決して作成しないでください。

呼び出し元の要件に応じて選ぶ 2 つのモード：

• 新規作業（デフォルト）。 ref の指定がない場合は、ベース（trunk）から新しいブランチを作成します。ユーザーが worktree オプションを選んだときに、ce-work と ce-code-review が使う方法です。
• 既存の ref を分離する。 呼び出し元が PR の head、ブランチ、またはコミットを指定した場合は、新しいブランチを作成せず、その ref に worktree を関連付けます。ブランチをチェックアウトできる worktree は、同時に 1 つだけです。 指定された ref がすでにどこかでチェックアウトされている場合（多くの場合、プライマリチェックアウトの現在のブランチです）は、2 つ目の worktree を作成しないでください。すでに <path> でチェックアウトされていることを報告し、呼び出し元に対応を委ねます（その場所で作業するか、クリーンな別ツリーがどうしても必要な場合に限り、同じコミットを指す detached worktree を作成します）。

Step 0：既存の分離を検出する

解決済みの 絶対パスの git dir と、解決済みの 絶対パスの common git dir を比較します。Git は現在のディレクトリによって絶対パスと相対パスを使い分けます（通常のチェックアウトのサブディレクトリでは、--git-dir は絶対パスを返す一方、--git-common-dir は相対パスを返す場合があります）。そのため、文字列をそのまま比較すると「すでに分離されている」という誤った判定になります。

git rev-parse --absolute-git-dir                     # absolute git dir for this worktree
(cd "$(git rev-parse --git-common-dir)" && pwd -P)   # absolute shared (common) git dir

同じ -> 通常のチェックアウトです。Step 1 に進みます。

異なる -> リンクされた worktree、またはサブモジュールです。git rev-parse --show-superproject-working-tree で判別します。

• 空でない -> サブモジュールです。通常のチェックアウトとして扱い、Step 1 に進みます。
• 空 -> すでに分離されています。worktree のパス（git rev-parse --show-toplevel）と現在のブランチを報告してから、その場で作業します。worktree の中からさらに worktree を作ると誤ったツリーに作成され、現在の worktree を作成したハーネスから認識されません。既存の ref を分離するモードでは、worktree を入れ子にするのではなく、その ref をここでチェックアウトします（すでに現在のブランチである場合を除きます）。

Step 1：ハーネスのネイティブ worktree ツールを優先する

ハーネスにネイティブの worktree プリミティブ（たとえば EnterWorktree / WorktreeCreate ツール、/worktree コマンド、または --worktree フラグ）がある場合は、それを使って終了します。ネイティブツールは worktree の配置、追跡、クリーンアップを行うため、ハーネスが管理できます。ハーネスに内緒で git worktree add を実行すると、ハーネスが認識、移動、クリーンアップできない幽霊状態が作られます。

ステップ 2：Git フォールバック

ネイティブツールがなく、かつステップ 0 で既存の隔離環境が見つからなかった場合にのみ実行します。

1. リポジトリのルートから実行します： cd "$(git rev-parse --show-toplevel)"。以下のパスはリポジトリルートからの相対パスですが、スキルはユーザーの現在のディレクトリから実行されます。これを行わないと、.worktrees/<branch> と .gitignore の編集がサブディレクトリ（例：src/.worktrees/...）に配置されます。
2. 作業内容をもとに、意味のあるブランチ名を選びます（例：feat/login、fix/email-validation）。不透明な自動生成の名前は使わないでください。ベースには、origin のデフォルトブランチを使用し、存在しない場合は main を使用します。
3. 作成前に .worktrees/ が Git の追跡対象外になっていることを確認します： git check-ignore -q .worktrees/ — 末尾にスラッシュを付けます。これにより、ディレクトリがまだ存在しなくても、既存のディレクトリ専用の .worktrees/ ルールが適用されます（スラッシュがないと確認に失敗し、正しく設定されたリポジトリを汚してしまいます）。追跡対象外でない場合は、.gitignore に .worktrees/ の行を追加します。
4. git fetch origin <from-branch> でベースを更新します。これは失敗しても処理を続行します。origin リモートがない場合、リモート名が異なる場合、またはローカルブランチのみの場合も中止せず、ローカルの参照を使用して続行します。
5. モードに応じてワークツリーを作成します。
   • 新しい作業： git worktree add -b <branch-name> .worktrees/<branch-name> origin/<from-branch>（origin/<from-branch> が存在しない場合は、ローカルの <from-branch> 参照を使用します）。
   • 既存のブランチまたはタグ： git worktree add .worktrees/<slug> <target-ref>。
   • PR： ローカルブランチとしてチェックアウトします。git fetch origin pull/<n>/head:pr-<n> を実行してから、git worktree add .worktrees/pr-<n> pr-<n> を実行します。切り離された FETCH_HEAD は絶対に使用しないでください。修正ループのコミットが PR の更新ではなく孤立してしまいます。（PR へのプッシュ追跡を行う場合は、切り離して作成します。git worktree add --detach .worktrees/pr-<n> を実行してから、そのディレクトリに cd し、gh pr checkout <n> を実行します。これならフォークにも安全に対応できます。）
   • Git がその参照はすでに別の場所でチェックアウトされていると報告した場合は、上記の「1 ブランチにつき 1 ワークツリー」のルールに従い、2 つ目のワークツリーを強制的に作成しないでください。
6. ワークツリーに cd し、パスとブランチを報告します。

git worktree add がサンドボックスまたは権限エラーで失敗した場合、要求された隔離環境は存在しません。現在のチェックアウトで処理を続行しないでください。ユーザーが隔離を選んだのは、まさにそれを避けるためです。失敗を報告し、「現在のチェックアウトで作業する」か「停止して権限の問題を解決する」などの選択肢を提示して質問します。現在のツールリストにすでにある、ホストのブロッキング質問ツールを使用してください（ホスト固有の名前ではなく、機能に基づいて選びます）。現在のツールリストに存在することは、そのツールが利用できる証拠です。利用できるか確認するために、ユーザー向け質問ツールを呼び出してはいけません。一致するツールがリストにあるものの未読み込みの場合は、別のホストのツール名を探さず、ホストのツール検出機能を使ってその機能を読み込みます。そのようなツールがリストにない場合、または実際に質問を呼び出してエラーが発生した場合に限り、チャットで番号付きの選択肢を提示し、返信を待ちます。確認を省略してはいけません。また、代替パスを自動的に再試行してはいけません。