cleanup

クリーンアップスキル

VCS プロバイダー

このスキルでは、Exarchos MCP アクション（list_prs、get_pr_comments など）を通じて VCS 操作を行います。 これらのアクションは、適切な VCS プロバイダー（GitHub、GitLab、Azure DevOps）を自動的に検出し、処理を振り分けます。 gh／glab／az コマンドは不要です。MCP サーバーがプロバイダーへの振り分けを処理します。

概要

マージ済みのワークフローを、1 回の操作で completed 状態にします。PR スタックのマージ後に HSM ガードをたどる手動の複数ステップの手順に代わるものです。

古くなったワークフローの一括整理

古くなったワークフローや放棄されたワークフローが蓄積している場合に一括整理するには（マージ済みの単一ワークフローを解決する場合とは異なり）、@skills/prune/SKILL.md を使用してください。このスキルは exarchos_orchestrate prune_stale_workflows をドライランモードで実行して候補を表示し、ユーザーの確認後に適用します。オープン中の PR や最近のコミットがあるワークフローは、セーフガードによって自動的に除外されます。

使い分けの目安： cleanup はワークフローごとの処理です（マージ済みの機能 1 件 → completed）。prune は一括処理です（非アクティブなワークフロー N 件 → cancelled）。両者は相互補完的であり、代替ではありません。

トリガー

以下の場合にこのスキルを有効にします：

• ユーザーが cleanup コマンドを実行する
• ユーザーが「cleanup」「ワークフローを解決」「完了としてマーク」と言う
• PR スタックがマージされ、ワークフローの解決が必要になる
• ユーザーが完了した機能をクローズしたい

前提条件

• 非終端フェーズにあるアクティブなワークフロー
• すべての PR が GitHub 上でマージ済みであること

手順

1. 対象のワークフローを特定する

ワークフローの状態を読み取り、現在のフェーズとメタデータを取得します：

exarchos:exarchos_workflow({ action: "get", featureId: "<id>" })

featureId が指定されていない場合は、パイプラインビューを使用してアクティブなワークフローを一覧表示します：

exarchos:exarchos_view({ action: "pipeline" })

パイプラインビューは、デフォルトでリポジトリ単位です。呼び出し元のリポジトリのみが対象です。別のリポジトリで開始されたワークフローは表示されません。応答の unscopedTotal が page.total より大きい場合は、scope: "all" を指定して再クエリし、非表示の行を表示してください。

2. マージ状態を確認する

ワークフローに関連付けられた各 PR がマージ済みであることを確認します。

主な方法 — VCS MCP アクション：

exarchos_orchestrate({ action: "list_prs", state: "merged" })

個々の PR の詳細を確認するには、exarchos_orchestrate({ action: "get_pr_comments", prId: "<number>" }) または VCS プロバイダーのネイティブ API を使用します。

マージ済みの PR から以下を収集します：

• prUrl：PR の URL（スタックされた PR の場合は URL の配列）
• mergedBranches：マージされたヘッドブランチ名

安全確認： マージされていない PR が 1 つでもあれば、明確なエラーメッセージを表示して中止します。

詳細な確認手順については、references/merge-verification.md を参照してください。

2.5. マージ後のリグレッションチェック（参考）

マージ状態を確認した後、マージ後のリグレッションチェックを実行します：

exarchos_orchestrate({
  action: "check_post_merge",
  featureId: "<id>",
  prUrl: "<url>",
  mergeSha: "<sha>",
  repoRoot: "<repo-root>"
})

repoRoot は、マージコミットを含むチェックアウトの絶対パスです。このチェックでは、そのチェックアウトに対してツールチェーンリゾルバーが特定したテストコマンドを実行します。テストコマンドを特定できない場合、テストチェックは失敗し、.exarchos.yml に追加すべき内容が検出結果に示されます。

このチェックは参考情報です。検出結果は報告されますが、クリーンアップを妨げることはありません。検出結果がある場合は、続行する前にユーザーが把握できるよう記録してください。

3. クリーンアップアクションを実行する

収集したデータを使って MCP クリーンアップアクションを呼び出します：

exarchos:exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  prUrl: "<url-or-array>",
  mergedBranches: ["branch1", "branch2"]
})

この呼び出し 1 回で、以下を実行します：

• synthesis.prUrl と synthesis.mergedBranches を後から補完する
• ブロック中のレビュー状態をすべて強制的に approved に解決する
• 共通のクリーンアップ経路を通じて completed に遷移する
• イベントストアに workflow.cleanup イベントを発行する

4. ワークツリーのクリーンアップ

統制されたガベージコレクター prune_worktrees を使って、ワークフローに関連するすべてのワークツリーを回収します。アドホックな git worktree remove は使用しないでください。

GC の実行タイミング — synthesize の後（INV-12）。 ワークフローが合成段階に達すると、統制されたワークツリーは回収可能になります。クリーンアップはマージ後（synthesize の完了後）に実行するため、このタイミングで回収するのが自然です。 next_actions プロジェクションでは、synthesis 以降、同じ prune_worktrees のドライラン機能を利用できます。

prune_worktrees はフェイルクローズの安全チェックを実行し（未保存の作業があるワークツリーの削除を拒否します）、削除したワークツリーごとに worktree.remove.requested／worktree.remove.executed のイベントペアを自動で出力します。まずドライランを実行し（デフォルトの動作です。候補、回収可能なバイト数、グループ化されたスキップ理由を報告し、何も削除しません）、その後に適用します。

// Dry-run (default) — preview candidates, delete nothing
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>" })

// Apply — reclaim the delete-eligible candidates
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>", dryRun: false })

ワークツリーがすでに削除されている場合も、適切に処理してください。GC がワークツリーをスキップした場合（たとえば、コミットされていない作業がある場合）は、再適用する前に報告された理由を解決してください。変更のあるワークツリーを手作業で強制削除してはいけません。

5. ブランチの同期

マージ済みのローカルブランチを削除します。

git fetch --prune
git branch -d <merged-branch-1> <merged-branch-2> ...

6. 完了を報告する

概要を出力します。

## Cleanup Complete

**Feature:** <featureId>
**Transition:** <previousPhase> → completed
**PRs merged:** <count>
**Worktrees removed:** <count>
**Branches synced:** ✓

ドライラン

dryRun: true を使用すると、状態を変更せずにクリーンアップの実行内容をプレビューできます。

exarchos:exarchos_workflow({
  action: "cleanup",
  featureId: "<id>",
  mergeVerified: true,
  dryRun: true
})

エラー処理

エラー	原因	解決方法
STATE_NOT_FOUND	無効な featureId	アクティブなワークフローについて、パイプラインビューを確認します（デフォルトではリポジトリ単位です。ワークフローが別のリポジトリにある可能性がある場合は、scope: "all" を追加します）
ALREADY_COMPLETED	ワークフローはすでに完了しています	対応は不要です
INVALID_TRANSITION	ワークフローはキャンセルされています	キャンセル済みのワークフローはクリーンアップできません
GUARD_FAILED	mergeVerified が false です	クリーンアップの前に、PR がマージ済みであることを確認します

アンチパターン

しないこと	代わりにすること
実装中の逃げ道としてクリーンアップを使う	PR のマージ後にのみ使用します
マージ確認を省略する	GitHub API を使って必ず確認します
マージ後に HSM ガードを手動で確認する	クリーンアップを使用します
クリーンアップ後もワークツリーを残す	プロセスにワークツリーの削除を含めます

Exarchos の統合

クリーンアップアクションはイベントを自動で出力します。手動で出力してはいけません。

• workflow.cleanup — フェーズが completed に変わる際に、MCP クリーンアップアクションによって出力されます