orcakit

orcakit

Orca では、git worktree ごとに 1 つのワークスペースが表示されます。カードには、関連付けられたイシュー、ステータス、その中で実行中のターミナルが表示されます。worktree は通常の git worktree（gitkit の規約、issuekit の start、または手動）で作成され、Orca が自動的に検出します。

一方、誰も管理していないのが、両者のずれです。issue-42-add-sso-login という名前の worktree がイシューに紐付かないままサイドバーに表示され、カードには何も表示されません。イシューがクローズされて PR がマージされても、ワークスペースはいつまでも残り、3 週間後にはサイドバーのほとんどが完了済みの作業で埋まっています。orcakit が担うのは、まさにこの調整です。トラッカーと一致するように、Orca に表示される worktree の状態を整えます。

orcakit が踏み越えない一線

worktree の信頼できる情報源は Git です。 orcakit は実作業のために orca worktree create を実行することはなく、パスを独自に作り出すこともありません。worktree の作成には gitkit の規約に沿ったネイティブの git worktree を使うため、Orca がインストールされていないヘッドレス Linux マシンでも同じコマンドを実行できます。orcakit は 1 つ上の層で、Orca だけが把握している情報を扱います。

• メタデータ。関連付けられたイシュー、ワークスペースのステータス、コメント、表示名などです。
• Git では表現できない Orca 側のリソース。ワークスペースに紐付いた実行中のターミナルや、リポジトリのアーカイブ／セットアップフックなどです。

git で worktree を削除すれば十分です。Orca は数秒以内にその変更を検知して、自動的にエントリーを削除します。唯一の例外は Orca が作成したワークスペースです。モード：clean でその理由を説明し、例外の範囲を限定しています。

orcakit がトラッカーを変更することはありません。 状態を判断するためにイシューや PR を読み取りますが、イシューをクローズしたり、ラベルを移動したり、PR を編集したりすることはありません。イシューがまだオープンなのに PR がマージ済みであることを検知した場合、それはトラッカーとのずれとして報告し、手を出さずに issuekit の close に案内します。

実行される場面

• list。「Orca のワークスペースには何がある？」「古くなったワークスペースはどれ？」「Orca のサイドバーを表形式で見せて」。読み取り専用です。
• link。「worktree をそれぞれのイシューに紐付けて」「ワークスペースカードが空欄になっている」「Orca が #42 のワークスペースの用途を把握していない」。
• clean。「Orca のワークスペースを整理して」「イシューがマージ済みのワークスペースを削除して」「サイドバーが完了済みの作業でいっぱいになっている」。
• align。「Orca が新しい worktree をどこに配置すべき？」「Orca に自分の worktree ルートを使わせて」「Orca が独自のフォルダーに worktree を作成するのをやめて」。

モードが明確でない場合は、確認してください。 list は無料ですが、clean はディレクトリを削除します。両者を決して推測で選ばないでください。

このスキルの対象外： worktree の作成（gitkit）、イシューのクローズやマージ後の後片付け（issuekit の close）、Orca のターミナル、ブラウザー、エージェントの操作（orca CLI を直接使うか、インストールされていれば Orca 提供のスキルを使います）。orcakit が扱うのはワークスペースの衛生管理であり、ワークスペースの操作ではありません。

事前確認（すべてのモード）

orca status --json      # app running? runtime reachable?

• orca がインストールされていない → このマシンには Orca がないため、整理するものはありません。そのことだけを伝えて終了してください。代替手段に切り替えてはいけません。Orca がなくてもワークツリーは問題なく使えますし、このワークフローのほかの部分はこのスキルに依存していません。
• ランタイムに接続できない → orca open はアプリを起動して待機します。誰かのマシンでデスクトップアプリを起動する前に、許可を求めてください。
• gh がない、または認証されていない → list は引き続き使えますが、すべての判定が「トラッカーの状態不明」になります。また、clean は PR がマージ済みかどうかを把握することが安全性の前提なので、まったく実行できません。どちらの状態かを伝えて終了し、推測してはいけません。
• orca のフラグまたはセレクターが拒否された → CLI は頻繁に変更されます。操作がサポートされていないと結論づける前に、orca <command> --help を確認してください。目標は契約、つまりリンク、ステータス、削除です。正確なフラグの表記ではありません。

gitkit が作成したものを Orca が認識できるように、外部で作成されたワークツリーも表示する設定が必要です。

orca repo list --json    # each repo carries externalWorktreeVisibility

リポジトリで "externalWorktreeVisibility": "hide" が設定されていると、その gitkit ワークツリーはここに記載したすべてのモードで見えません。この設定に対応する CLI フラグはありません。Orca の UI でリポジトリごとに設定します。リポジトリ名を伝えて、ユーザーに設定を変更してもらってください。結果が空でも、ワークツリーのルートが空だと決めつけてはいけません。

Orca がワークスペースについて把握している情報

orca worktree list --json
orca worktree show --worktree "branch:$BRANCH" --json

各レコードには path、branch、linkedIssue、linkedPR、workspaceStatus、isArchived、isMainWorktree、lastActivityAt が含まれます。セレクターは branch:<name>、path:<abs-path>、issue:<number>、active／current です。branch: を優先してください。gitkit がブランチを使ってワークツリーを検索するのと同じ理由で、パスは推測にすぎませんが、ブランチは識別情報だからです。

検出結果の整合性が取れるまでには時間がかかります。数秒前に作成したワークツリーは、worktree list に表示される前でも worktree show で見つかることがあります。削除したワークツリーがしばらく残ることもあります。古い一覧から結論を出さず、再読み込みしてください。

2 種類のワークスペース

以下の内容はすべて、この違いを前提としています。

種類	場所	作成者	削除方法
git ネイティブ	$WORKTREE_ROOT 配下（デフォルトは ~/worktrees/<repo>/<branch>）	gitkit／issuekit の start。git worktree add を使用	git が削除します。Orca は自動的にエントリを削除します
Orca ネイティブ	Orca のワークツリーのベースパス配下（デフォルトは ~/orca/workspaces/<repo>/<name>）	orca worktree create	orca worktree rm。フックとターミナルも処理されます

次の順序で分類し、最初に一致した時点で終了してください。

1. gitkit のマーカーが git ネイティブを示している。 gitkit が作成したワークツリーには、管理ディレクトリ内に gitkit-created ファイルがあります。次のコマンドで確認します：test -e "$(git -C "$WT" rev-parse --absolute-git-dir)/gitkit-created"。
2. Orca のベースパスが Orca ネイティブを示している。ただし、そのベースパスが $WORKTREE_ROOT/<repo> と異なる場合に限ります。
3. それ以外は種類不明。 手動で作成したワークツリーや、align によって両方の種類が同じルート配下に置かれた後で、マーカーがないワークツリーが該当します。内容を報告し、clean ではスキップしてください。両方のツールで共有されるパスから種類を推測してはいけません。

パスのプレフィックスは経験則にすぎず、Orca が記録する事実ではありません。そのため、マーカーによる確認を最初に行います。align では意図的にプレフィックスを重複させます。そのため、align の後はマーカーだけが、2 種類を区別する手段として残ります。

モード：list

読み取り専用です。何も変更せず、何も尋ねません。状態が不明な場合は、まずこのモードを使ってください。

isMainWorktree が false のすべてのワークスペースを取得し、トラッカーと結合します。

orca worktree list --json
gh pr list --head "$BRANCH" --state all --json number,state,url,mergedAt
gh issue view "$N" --json number,state,title,labels     # $N parsed from an issue-<n>-<slug> branch
git -C "$WT" status --porcelain                          # dirty?
git -C "$WT" log --oneline "@{upstream}..HEAD"           # unpushed?

1 つの表にまとめ（ワークスペース、ブランチ、issue、PR、Orca のステータス、git の状態）、各行に判定を付けます。

判定	意味	対応
active	issue または PR がオープンで、作業が進行中	対応不要
unlinked	ブランチ名に issue が含まれているが、linkedIssue が null	link
stale status	Orca のステータスが in-progress だが、PR はマージ済みまたはレビュー中	link
reapable	PR がマージ済みで、issue がクローズ済み、ワークツリーがクリーン	clean
tracker drift	PR はマージ済みだが、issue はまだ オープン	orcakit ではなく、issuekit の close <n> で対応します
dirty	トラッカーの状態にかかわらず、未コミットまたは未プッシュの作業がある	何よりも先に人が対応します
unknown	ブランチ名に issue が含まれず、PR もない	そのままにして、そう報告します

どのモードがどの行を解消するかを最後に示します。作業が失われる可能性がある行なので、該当する場合は dirty を最初に挙げてください。

モード：link

Orca では推測できないメタデータを付与し、ワークスペースのカードに用途が実際に表示されるようにします。

ブランチ名が issue-<n>-<slug> に一致し、linkedIssue が null である、git の情報に基づく各ワークスペースに対して、次を行います。

orca worktree set --worktree "branch:$BRANCH" --issue "$N" --json

また、workspaceStatus をトラッカーの状態に合わせます。Orca で使用する値は todo、in-progress、in-review、done、archived です。ラベルだけではなく、実際の状態に基づいて割り当てます。

トラッカーの状態	workspaceStatus
issue はオープン、PR なし、ブランチにコミットなし	todo
issue はオープン、PR なし、作業をコミット済み	in-progress
PR がオープン	in-review
PR がマージ済み	done
issue がクローズ済みで、PR がマージ済み	done（clean の候補です）

orca worktree set --worktree "branch:$BRANCH" --workspace-status in-review --json

ルール：

• 予定しているすべての set を表にまとめてプレビューしてから、バッチ全体に対する OK を一度だけ確認してください。 ここでは何も破棄されませんが、ユーザーのサイドバーを書き換えるため、予告なしではなく、事前に確認してください。
• すでに設定されている linkedIssue を、異なる値で上書きしないでください。 人間または orca worktree create --issue が意図的に設定したものです。不一致を報告し、そのままにしてください。
• 手書きの comment を上書きしないでください。 空の場合に限り設定してください。
• メインのワークツリーには手を加えないでください。 これは機能開発の作業ではなく、設定されたステータスに意味はありません。
• issue が含まれないブランチはスキップします。件数を伝え、slug からリンクを推測して作成しないでください。

引き継ぎ

このスキルの引き継ぎはすべて、手順を示す文体で書いてください。1 文につき 1 つの指示とし、能動態、現在形を使い、比喩を避けてください。

変更内容。 issue リンクを追加したワークスペース数、ステータスを修正したワークスペース数、スキップしたワークスペース数とその理由を報告してください。

反映先。 Orca のサイドバーです。ディスク上のファイルは移動せず、git の状態も変更していません。

次の手順。 link が done にした項目がある場合、その一式が clean の入力となるため、そこで処理を完了してください。それ以外の場合は終了してください。リンク済みのカードが最終状態であり、その先の手順ではありません。

モード：clean

作業がすでに反映済みのワークスペースを回収します。削除はすべて元に戻せないため、手順は固定です。収集し、条件を確認し、すべてを一度にプレビューし、各行について確認を取り、再確認してから削除します。

1. 適格性を判定する

ワークスペースが候補となるのは、作業がマージ済みであることを証明でき、トラッカーの状態もすでに一致している場合に限られます。

gh pr list --head "$BRANCH" --state merged --json number,url,mergedAt
gh issue view "$N" --json state                       # must be CLOSED

• 主な判定条件。 そのブランチのPRがマージ済みであること。さらに、ブランチ名にIssueが含まれていないか、含まれている場合はそのIssueがすでにクローズ済みであること。
• 副次的な条件。独立したグループとして表示します。 PRが一度も存在しないものの、ブランチがベースブランチに完全にマージされていること（git branch --merged "origin/$BASE"。ベースはgitkitの方法で解決し、mainにハードコードしません）。直接プッシュの場合は該当しますが、証拠としては弱いため、プレビューでは独立したセクションに表示し、主な条件を満たす行には決してまとめません。

オープン中のIssueがあるマージ済みPRは、候補ではありません。 これはトラッカーとの不整合です。一覧に表示し、issuekit の close <n> に振り分けます。これによりIssueをクローズし、依存関係を解消して、ワークツリーも削除します。トラッカーに黙って背を向け、証拠を削除するのではなく、適切に処理できます。

2. 対象外にする

以下は除外対象です。理由とともにプレビューのスキップ対象に表示し、レポートから黙って消えることがないようにします。

• git status --porcelain が空でない場合の、未コミットの変更または未追跡ファイル。
• プッシュされていないコミット、またはアップストリームがまったく設定されていないブランチ。
• メインのワークツリー。常に対象外です。
• 現在自分がいるワークツリー。立っている床を削除することはできません。
• 2種類のワークスペースで定義されている種類不明のワークスペース。推測に基づく削除方法は、どちらも安全ではありません。
• 実行中のOrcaターミナル。orca terminal list --worktree "branch:$BRANCH" --json で検出します。orca terminal stop --worktree "branch:$BRANCH" は、明示的な確認を伴う独立した手順として提示します。整理の副作用として、他の人の実行中プロセスを決して停止しません。

PRがマージ済みでも、ワークツリーが空とは限りません。一時ファイル、stashに保存した実験、そしてプッシュされなかった後続コミットは、いずれもPRには含まれませんが、ワークツリーには残っています。

すべてのワークスペースが、候補、理由付きのスキップ対象、またはトラッカーとの不整合を示す行のいずれかになった時点で終了します。

3. プレビューして確認する

候補をすべて1つの表にまとめ、それぞれについて、候補とした根拠（PR番号、マージ日、Issueの状態）、種類（gitネイティブまたはOrcaネイティブ）、lastActivityAtを表示します。その下に、理由付きのスキップ対象を一覧表示します。

その後、削除ごとに個別に確認します。 削除ルールはgitkitが管理します。各ワークツリーと各ブランチにつき1回ずつ確認し、ghで証明されたスカッシュマージの場合を除き、-dを使用します。gitkitがない場合は、行ごとに一度確認し、-dを付けて削除します。各質問には、ワークスペース、ブランチ、PRを明記します。すべての候補行について、ユーザー自身の回答が得られた時点で終了します。

4. 種類ごとに再確認してから削除する

削除の直前に、必ずアクティビティを再確認してください。 プレビューから回答までの間に時間が経過し、ユーザーがそのワークスペースを開いている可能性があります。orca worktree show --worktree "branch:$BRANCH" --json、orca terminal list --worktree "branch:$BRANCH" --json、git -C "$WT" status --porcelain で行を読み直してください。lastActivityAt がプレビュー時の値より新しくなっている、アクティブなターミナルが現れている、またはツリーがクリーンでなくなっている場合は、その行をスキップし、理由を報告してください。

git-native → gitkit のティアダウンに任せます。gitkit はブランチからワークツリーを検索し、削除ルールに従って削除します。gitkit がインストールされていない場合は、次の2つのコマンドだけで完了します。

git -C "$REPO" worktree remove "$WT"
git -C "$REPO" branch -d "$BRANCH"

その後は停止してください。orca worktree rm も実行してはいけません。Orca は検出したエントリを自動的に削除するため、すでに存在しないパスをもう一度削除しようとすると、分かりにくいエラーが発生するだけです。

Orca-native → Orca が所有しているため、Orca で削除します。

orca worktree rm --worktree "path:$WT" --run-hooks --json

orcakit が、git の削除も実行するベンダーコマンドを呼び出すのはここだけです。その理由は限定的です。Orca がこのチェックアウトを作成し、アーカイブフックとターミナルセッションを結び付けており、rm がその3つすべてを順に処理するためです。先に git で削除すると、Orca のメタデータが孤立し、フックも実行されません。この例外は Orca が作成したワークスペースに限られ、gitkit のワークツリーには適用されません。

--force は絶対に使わないでください。 ここでの削除はすべて、ツリーがクリーンで PR がマージ済みであることを条件としています。それでも git が拒否する場合、その拒否自体が情報です。内容を報告し、次の行に進んでください。

確認済みの各行が削除されるか、再確認によってスキップされるか、削除を拒否された時点で終了します。それぞれの結果を記録してください。

5. 引き継ぐ

変更内容。 ワークスペースを種類ごとにいくつ削除したか、いくつスキップしたかを報告してください。スキップしたものは理由とともに名前を挙げます。ダーティーなワークツリーが残った場合、それが報告で最も重要な一文なので、最初に記載してください。

削除先。 削除されたパスと、それに伴って削除されたブランチを伝えてください。Orca のサイドバーには数秒以内に反映されるため、今もエントリが見えていても失敗ではないことを注記してください。

次の対応。 次のいずれか1つを選びます。

• ダーティーなものをスキップした場合 → 何よりも優先します。パスを挙げ、ユーザーに確認するよう伝えてください。古いワークツリーに未反映の作業が残っていることこそ、実際に失われるものです。
• トラッカーの不整合が見つかった場合 → 該当する issue に対して issuekit の close <n> を実行します。それ以外の場合は gh issue close <n> を実行し、手動でティアダウンします。
• クリーンアップするものが残っていない場合 → その旨をはっきり伝えて終了します。次に行うべきことはまったく別の作業です。インストールされていれば、状況を再確認するために statuskit を使い、そうでなければ何もしません。サイドバーの整理は、繰り返す価値のあるループではありません。

モード：align

Orca が、gitkit が決して参照しない場所にワークツリーを作成するのをやめましょう。Orca のデフォルトは ~/orca/workspaces/<repo>/<name>、gitkit の規約は $WORKTREE_ROOT/<repo>/<branch> です（環境で別の場所が指定されていない場合は ~/worktrees）。ルートが二つあると、ユーザーのワークツリーが二つの場所に分散します。align の後は、どちらも一つのルートを共有するため、パスから両者を見分けられなくなります。その代わり、clean は 二種類のワークスペース に従い、gitkit のマーカーで分類します。

orca project setups --json                                  # find the setup id for the repo
orca project setup-update --setup "$SETUP_ID" \
  --worktree-base-path "$WORKTREE_ROOT/$(basename "$REPO")" --json

推測せずに確認します。 セットアップ一覧にはベースパスが表示されず、Orca がそのパスにリポジトリ名を追加するかどうかも、どこにも記載されていません。そのため、リポジトリごとに一度、使い捨てのワークツリーで実際に確認します。

orca worktree create --repo "path:$REPO" --name orcakit-align-check --no-parent --json
# read the path it reports:
#   .../worktrees/<repo>/orcakit-align-check    → correct
#   .../worktrees/<repo>/<repo>/orcakit-…       → doubled; re-set the base to "$WORKTREE_ROOT"
orca worktree rm --worktree "name:orcakit-align-check" --json

このスキルで orca worktree create を使うのはこれ一度だけで、パスを読み戻すためだけに実行します。そのため、ユーザーに確認してから実行し、使い捨てのワークツリーはその場で削除します。確認が拒否された場合や実行できない場合は、ベースパスは設定したものの、確認できていないと伝えてください。確認できていない状態で、設定が収束したと報告してはいけません。

既存のワークツリーには手を加えません。 すでに ~/orca/workspaces の下にあるワークツリーは、これまでどおり動作します。git は絶対パスを保存しており、手動で移動するには git worktree repair が必要です。align で変更するのは、次のワークツリーの作成先だけです。「整合済み」は「移行済み」のように聞こえますが、実際にはそうではないことを、はっきり伝えてください。

引き継ぎ

変更内容。 ベースパスを設定したリポジトリと、使い捨てのワークツリーで作成先のパスを確認できたかどうかを報告します。

設定先。 リポジトリごとの新しいベースパスを示し、既存のワークスペースは元の場所に残っていることを念押しします。

次の手順。 ルートが一つになったので、list を実行して全体を一つの表で確認するとよいでしょう。ほかに対応事項がなければ、ここで終了します。これはリポジトリごとに一度だけ行う設定であり、定期的に行う作業ではありません。

注意事項

• orcakit はマシンごとに設定され、常に任意です。 マシンに Orca がなければ何も行わず、ワークフロー内のほかの処理が Orca に依存することもありません。アプリのないすべてのマシンで動かなくなるため、gitkit、issuekit などが Orca を呼び出すことはありません。これはチェーンの一部ではなく、実行する掃除ツールです。
• paseokit は兄弟であり、後継ではありません。 同じワークツリーを Paseo に同期します。Paseo のモデルは逆で、Paseo は何も検出せず、ディレクトリがなくなった項目だけを削除します。そのため、paseokit は登録と回収を行い、orcakit は情報を補完してクリーンアップします。Paseo に関する事実は paseokit が管理します。どちらもマシンごとに設定され、任意です。一方が他方を呼び出すことはありません。
• ワークツリーに関する情報は gitkit が管理します。 デフォルトのパス規約がここに記載されているのは、gitkit のないマシン向けに移植可能なフォールバックとして宣言するためだけです。ブランチ名、ベース参照の解決、削除ルールなど、それ以外の情報はすべて gitkit が管理します。ここにある gitkit の情報のほかのコピーは、すべて不具合です。
• トラッカーに関する情報は issuekit が管理します。 orcakit はワークスペースを判断するために issue と PR の状態を読み取りますが、それらを書き込むことはありません。
• 破壊的な手順は事前にプレビューして確認し、読み取り専用の手順はそのまま実行します。 list では確認を求めません。link は一括処理をプレビューします。clean は候補をすべてプレビューした後、gitkit の削除ルールに従い、各削除を個別に確認します。align は使い捨てのワークツリーを作成する前に確認します。
• シェルを利用できませんか？ その場合、orca CLI や gh を使うことはできません。ユーザーから得た情報をもとに判断し、実行してもらうための正確なコマンドをコードブロックで示してください。実行できなかったワークスペースを、リンクした、または削除したと報告してはいけません。