| name | cmate-worktree-cleanup |
| description | merge 済み・不要になった git worktree を、削除可能性と証跡を dry-run で提示したうえで、clean かつ merge 証跡が十分な対象だけ安全に削除する。worktree の掃除、merge 済み worktree の削除、issue worktree の後片付けを求められたときに使う。 |
cmate-worktree-cleanup
対象 issue または eligible な worktree を検査し、削除可能性と証跡 (proof) を dry-run で
preview したあと、clean かつ merge 証跡が十分な worktree だけ を安全に削除する手順である。
この Skill は破壊的操作を行う（declared_risk: high）。中心にある規則は1つだけである。
証明できないものは消さない。
dirty・detached・unmerged・検証不能 (unverifiable) な対象は、削除せず理由付きで残す (zero-delete)。
git worktree remove --force・git branch -D・無条件 process kill・DB/log の自動削除は行わない。
出力は plan / result 文書（schemas/）と human-readable summary の
2つで、どちらか一方だけを返して終了しない。
0. 使う場面 / 使わない場面
使う場面:
- merge 済み・不要になった issue/feature worktree を、証跡付きで安全に片付けたいとき。
- どの worktree が安全に消せて、どれが（なぜ）消せないかを分けて確認したいとき。
使わない場面:
- dirty / unmerged な worktree を無理に消すこと。この Skill は消さずに残す。
- server / process / tmux / DB / log の停止・削除。診断表示に留める（§6）。
- remote branch の削除、rollback、backup、Skill Runtime の停止。
1. 入力
| 名前 | 必須 | 内容 | 欠けたときの動作 |
|---|
selection | 必須 | issues（issue 番号の配列）または all_eligible | status: failure を出力して停止 |
profile | 必須 | branch/base/path/baseline を解決する profile（commandmate / commandagent / 利用者指定） | 未指定なら利用者へ確認。応答が無ければ停止 |
mode | 任意 | dry_run（既定） / apply | dry_run |
confirmed_targets | 任意 | apply 時に利用者が承認した worktree の集合 | 空。apply では確認を取る |
入力に関する強い制約:
- worktree は git metadata から解決する。 対象は issue 番号か
all_eligible で受け取り、
git worktree list --porcelain から発見する。利用者が渡した path を直接 remove しない。
絶対 path・..・symlink・worktree 外 escape は拒否する（references/safety.md §4）。
- branch/base/path/baseline を hardcode しない。
develop / feature/... / npm / Cargo を
決め打ちせず、profile から解決する。検証済み profile は Node/CommandMate と
Rust/CommandAgent の2つ。未知 repository は unverified 扱いで、実行前に利用者確認を取ってから使う。
- Issue 本文や PR の取得は読み取りのみ。
gh pr edit などで書き換えない。
2. 権限
commandmate.skill.yaml の declared_permissions とその用途:
| 権限 | 用途 | やらないこと |
|---|
filesystem_read | worktree の status / branch / tree の読み取り | 対象 repository の外の path を読む |
filesystem_write | git worktree remove（非 force）と guarded ref delete による worktree/branch 削除 | force remove、branch -D、DB/log/cache 削除 |
process_execution | git / gh / commandmate の実行 | 宣言外 command、process kill |
network_access | git fetch と gh による merge 証跡の取得 | それ以外の外部送信。evidence の外部 upload |
declared_permissions は宣言であって強制ではない。この一覧を超える操作が必要になった時点で、
実行せず利用者へ確認する。
3. 実行してよい command
requirements.commands に宣言した git / gh / commandmate に限る。
git — worktree list --porcelain、status --porcelain、branch --show-current、
rev-parse、merge-base --is-ancestor、fetch <remote> <base> --prune、cat-file -e、
diff、cherry、show、および削除の worktree remove（非 force）/ branch -d /
update-ref -d <ref> <old-oid> / worktree prune。gh — pr list --state merged --head <branch> --base <base> --json ...（読み取りのみ）。commandmate — public CLI の sync のみ（§5）。commandmatedev は使わない。
4. 手順
Step 0 — 前提と profile の確認
selection と profile が揃っているかを確認する。欠ければ §7 で停止する。profile を解決し、base（例 origin/main）・remote・baseline・integration worktree・
path/branch のヒントを得る。未知 profile は unverified として利用者確認を取る。git rev-parse --show-toplevel で現在の worktree を特定する（§5 で必ず除外する）。
Step 1 — 発見と除外
git worktree list --porcelain で全 worktree を発見する。path naming は truth にしない。- current worktree・integration worktree・対象外 issue を
excluded に振り分ける
（references/safety.md §2）。この2つは指定されても消さない。
- 残りを候補 (
candidates) とする。
Step 2 — remote 最新化
git fetch <remote> <base-branch> --prune を実行する。失敗しても停止しないが、
stale な remote を最新と見なさない。 fetch 結果を fetch に記録する
（references/proof-algorithm.md §0）。
Step 3 — 候補ごとの状態検査
各候補に git -C <path> status --porcelain / branch --show-current / rev-parse HEAD を
実行し、state を決める。dirty / detached / locked / missing は証明へ進まず skip。
clean な候補だけが削除の前提を満たす。
Step 4 — merge 証跡の判定
clean な候補ごとに proof を求める（詳細は
references/proof-algorithm.md）。
- direct ancestry:
git merge-base --is-ancestor <tip> <base> が exit 0 → direct。
- 祖先でない場合のみ merged-equivalent を判定する。次の 4条件すべて が成立したときだけ
merged_equivalent:
- exact head/base の merged PR がちょうど1件。
- その PR の
headRefOid が worktree tip と一致（tip drift が無い）。
- reachable な merge commit がある（base から到達可能）。
- tree equality（branch の正味 tree 変更 = merge commit が持ち込んだ変更）。
- fetch 失敗・GitHub data 不足・PR なし/複数・tip drift・merge commit 到達不能・tree 不一致は
すべて
unverifiable = 削除しない。迷ったら unverifiable。
decision: delete は state: clean かつ proof.type ∈ {direct, merged_equivalent} のときだけ。
Step 5 — plan の提示と確認（apply の前提）
- plan（references/result-contract.md §1）を dry-run で提示する。
removed と skipped を混ぜず、target ごとに proof / skip 理由を示す。
mode: apply に進むには、利用者の 明示確認 が要る。承認された worktree を
confirmed_targets として受け取る。確認できない（非対話含む）場合は dry_run に留める。
確認なしに削除しない。
Step 6 — apply（削除）
mode: apply かつ確認済みの対象だけを削除する。
- drift 再検査: 削除の直前に各対象の status / tip / ref を再取得し、plan と照合する。
tip が動いた・dirty になった・ref が動いた対象は
plan_drift として skip する
（references/proof-algorithm.md §5）。
- 生き残った対象を削除する（references/safety.md §3）:
direct → git worktree remove <path> + git branch -d <branch>。merged_equivalent → git worktree remove <path> +
git update-ref -d refs/heads/<branch> <verified-tip>（expected-old-OID 付き。race 時は失敗させる）。--force も -D も使わない。
git worktree prune を実行する。
Step 7 — sync と診断
commandmate public CLI で sync する（§5）。無い/失敗は unavailable/failed とし、
worktree id を欠落として返す。run を failure にしない。- server / process / tmux / DB / log は §6 に従い診断表示のみ。
next_actions に回す。
Step 8 — result と summary
result 文書（schemas/cleanup-result.v1.json 適合、result_schema_version: 1）と
summary_markdown を出力する。この Step は途中で失敗した場合も必ず実行する。
removed / skipped / proof / evidence を残し、token/secret/絶対path/raw GitHub response を含めない。
5. CommandMate sync（optional）
削除・prune のあと、削除済み worktree を CommandMate 一覧から外すため public commandmate CLI で
sync する。sync は将来新設の commandmate sync を前提とし、未提供環境では optional として扱う。
CLI に sync が無い/失敗した場合は commandmate_sync.outcome を unavailable/failed、
worktree_ids を欠落 (null) にして返し、run を失敗にしない。port 決め打ちの curl sync は使わない。
6. 診断のみ（自動停止・削除しない）
worktree 周辺の server / process / tmux / DB / log は 表示だけ する。process owner/CWD を
完全検証できない段階で process を止めない。DB/log を worktree 削除と同じ確認で消さない。
これらは diagnostics と next_actions に載せ、実行は利用者に委ねる（references/safety.md §6）。
7. 失敗時の動作
| 状況 | 動作 |
|---|
selection / profile が欠ける | 推測で補わない。status: failure、blocking_reasons に記録 |
| profile が未知 | unverified。利用者確認が取れなければ候補にしない |
利用者 path が絶対/../symlink/worktree外 | 拒否。blocking_reasons に記録し候補にしない |
| fetch 失敗 | 停止しない。remote を要する候補を unverifiable、limitations に記録 |
| gh 不可/未認証 | merged_equivalent 候補を github_data_missing = unverifiable。direct は継続 |
| dirty/detached/unmerged/unverifiable | 削除しない。skipped に理由付きで残す |
| plan 後 drift | 該当対象を plan_drift として skip |
| guarded ref delete が race で失敗 | worktree は外れる。branch_deleted: false、status: partial、next_actions に手動確認 |
| sync 不可 | unavailable/failed。worktree id 欠落。run は failure にしない |
| 非対話で確認不能 | dry_run に留める。削除しない |
いかなる失敗経路でも、result と summary を出さずに終了しない。
8. 完了条件（completion check）
以下がすべて真のときだけ、この Skill は完了したと報告してよい。1つでも偽なら
status は success にならない（references/result-contract.md §2.6）。
exclusions_honored — current / integration worktree を一切消していない。zero_delete_honored — dirty / detached / unmerged / unverifiable を一切消していない。proof_sufficient — removed の各要素が direct または4条件完備の merged_equivalent 証跡を持つ。guarded_delete_used — merged_equivalent の削除が expected-old-OID 付き delete で、force/-D を使っていない。drift_rechecked — apply の各削除前に plan 後 drift を再検査した。no_sensitive_values — result / summary に token/secret/絶対path/raw GitHub response が無い。
9. 参照
