copilot-pr-autopilot

Copilot PR Autopilot

GitHub のあらゆるプルリクエストを、エージェントが役目を果たすまで Copilot によるコードレビューの反復ラウンドにかけます。つまり、Copilot の指摘すべてにエージェントからの返信（修正した旨の報告、理由を添えた対応見送り、またはユーザーへの明示的なエスカレーション）がある状態にします。未解決のスレッドが残っている場合、それは人間のマージ担当者への意図的な引き継ぎであり、ループの失敗ではありません。リポジトリに依存せず、Copilot Code Review が有効なあらゆるリポジトリで動作します。gh CLI がインストールされ、認証済みのマシンから実行してください（「前提条件」を参照）。

このスキルを使う場面

• ユーザーが PR で「Copilot にレビューを依頼」または「Copilot のレビューループを実行」と依頼した場合。
• PR の機能が完成しており、ユーザーが自動レビューを繰り返して最終的な正確性チェックをしたい場合。
• PR に対する以前の Copilot レビューで未解決のスレッドが残っており、トリアージ、修正、返信、解決が必要な場合。

このスキルを使わない場面

• PR の設計を進めている最中の場合。構成が安定するまで待ってください。そうしないと、ラウンドごとに指摘内容が変わり続けます。
• ユーザーが求めているのが人間のレビュアーからのフィードバックであり、Copilot からのものではない場合。

前提条件

• gh CLI がインストールされ、対象リポジトリで認証されていること。
• PowerShell が PATH にあること。Windows PowerShell 5.1 以降（powershell.exe）または PowerShell 7 以降（pwsh）。どちらもテスト済みです。
• 主なユースケースは Copilot Code Review です（01-request-review.ps1 は GraphQL の requestReviewsByLogin を使って Copilot を起動します）。ただし、必須ではありません。リポジトリまたはアカウントで Copilot が有効になっていないために 01-request-review.ps1 が失敗した場合でも、エージェントはステップ 3〜8 を単一のイテレーションとして一度実行することで、既存のレビュースレッド（人間、advanced-security など）を解決できます。その場合は、起動と待機を省略してください。「Copilot が利用できない」状態を自動検出する機能はありません。トリガーが失敗した後にエージェントが判断します（スクリプトだけでは API の状態から「Copilot が無効」なのか、「Copilot は有効だがまだ起動していない」だけなのかを確実に判別できません）。

権限：フルループを実行できるユーザー

複数ラウンドのオートパイロット全体（ステップ 1 → 9 → 1）を実行するには、対象リポジトリで Triage または Write の権限が必要です。Copilot ボットをレビュアーとして追加するための GitHub の唯一の公開 API（requestReviewsByLogin）には、その権限が必要だからです。この PR のコミット履歴にある公開 REST API と GraphQL API の情報に基づいて確認済みです。書き込み権限がない場合にボットレビュアーを指定する公開 API の方法はありません。

あなたの立場…	利用できる機能
Triage / Write 権限を持つリポジトリのコラボレーター	フルループ：01 で Copilot を起動し、02 で待機し、04〜08 でトリアージ／修正／返信を行い、01 に戻ります。手動操作は不要です。
外部 PR 作成者（書き込み権限なし）	01 は、次に取るべき操作を明示したエラーを出して終了します。-SingleIteration モードを使い、現在の指摘すべてに一度で対応してください。その後、Copilot の横にある UI の 🔄 をクリックするか、実質的な変更を含むコミットをプッシュしてください（多くのリポジトリでは、synchronize イベントによって Copilot が自動的に起動します）。その後、02 を再実行して確認してください。

単一イテレーションモードでは、OpenThreadsAwaitingReply == 0（エージェント側の作業が完了している状態）の場合に限り、ループの収束を示すブール値が Converged: true になります。その後、メンテナー側で再トリガーすることで、追加ラウンドを進めます。

すべてのスクリプトは scripts/_lib.ps1 をドットソースし、読み込み時に Assert-GhReady を実行します。gh が見つからない、または gh auth status が失敗した場合、スクリプトは作業を一切行う前に停止し、インストールコマンドと gh auth login を示す、次に取るべき操作が明確なエラーメッセージをひとつ出します。エージェントはそのメッセージを一字一句そのままユーザーに伝え、ループを停止してください。再試行したり、回避策を使ったりしてはいけません。

ステップごとのワークフロー

ループ： ステップ 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 の順に進み、Converged: false の場合は ステップ 1 に戻ります。ステップ 9 が Converged: true を返すまで 1→9 のラウンドを繰り返し、その後に限りステップ 10 を 1 回実行して task_complete を呼び出します。10 ラウンドごとに、親エージェントはループに戻る前にラウンド上限の再確認ゲートを実行します — これまでのラウンドをすべて再確認し、ループが PR の当初のスコープから逸脱していたら停止します。

各ラウンドではステップ 1〜9 を実行します。ステップ 10 は収束後に 1 回だけ行うクリーンアップです。親エージェントが調整を行い、各サブエージェントのステップは、制限付きの予算で新しいコンテキストから実行されます。横断的なプロトコル（時間制限、延長、単一反復へのフォールバック）については、orchestration.mdを参照してください。

1. レビューをリクエスト (親エージェント) — 01-request-review.mdを参照
2. レビューを待つ (サブエージェント、上限 20 分) — 02-wait.mdを参照
3. 未解決スレッドを一覧表示して分類 (サブエージェント、5 分) — 03-list-threads.mdを参照
4. トリアージ (サブエージェント、5 スレッド以下につき 5 分) — 04-triage.mdを参照
5. 修正 (サブエージェント、並列実行は最大 5 件、各 5 分) — 05-fix.mdを参照
6. リポジトリの規約に従ってビルドとテストを実行 (サブエージェント、10 分) — 06-build-test.mdを参照
7. コミットしてプッシュ (親エージェント) — 07-commit-push.mdを参照
8. 返信（常に）と解決（条件付き） (サブエージェントが下書きし、親エージェントが投稿) — 08-reply-resolve.mdを参照
9. 収束を確認 (サブエージェント、3 分) — 09-convergence.mdを参照
   • Converged: false → もう一度ステップ 1 に戻ります（再トリガー、待機、一覧表示、トリアージ、修正、プッシュ、返信、再確認）。各ラウンドでは、前のラウンドの HEAD に対する Copilot の指摘に対応します。Copilot から新たな指摘がなくなり、すべての未解決スレッドにエージェントが返信した時点でループは終了します。
   • Converged: true → ループを終了し、ステップ 10 を 1 回実行して、証拠とともに task_complete を呼び出します。
   • 10 ラウンドごと（10、20、30…）→ ループに戻る前にラウンド上限の再確認ゲートを実行します。 PR の当初のスコープに照らしてこれまでのラウンドをすべて再確認し、判定を選択します：CONTINUE（続行）、REVERT-AND-SHIP（逸脱したコミットを取り消し、スコープ内のコミットを反映）、または HAND-OFF（ユーザーにエスカレーション）。これは、ボットによるレビューのループが暴走するのを止めるサーキットブレーカーです。
10. 古い項目をクリーンアップ (親エージェント、収束後に 1 回) — 10-cleanup.mdを参照

収束はスクリプトが単一の Converged: true ブール値として算出します。これが true を返すまで task_complete を呼び出さないでください。完了メッセージには証拠（HeadOid、LatestCopilotReview.commitOid、submittedAt）を出力してください。

注意事項

同梱スクリプトは、厳密な正しさの不変条件（copilot_work_started イベント ID によるトリガーの検知、HEAD との一致＋未対応件数ゼロ＋HEAD 時点のレビューを Converged の条件とすること、単一イテレーションのフォールバックセマンティクス、PR 状態のガード）を適用します。スクリプトを信頼してください。自分で条件を再導出しないでください。以下の注意事項では、スクリプトでは判断できない事項を説明します。

• すべてのオープンスレッドに返信し、ループが対応方針を決定する場合にのみ解決してください。 fix と decline のスレッドには返信して解決します。escalate-to-user のスレッドには分析内容を返信しますが、スレッドは OPEN のままにします（08-reply-and-resolve.ps1 -NoResolve）。そうすることで、人間のマージ担当者が対応できます。08-reply-resolve.md を参照してください。
• Copilot のスレッドはループが対応し、人間／advanced-security／その他のボットのスレッドは既定で escalate-to-user にします。 人間のレビューコメントを自動解決すると、未対応の懸念が隠れてしまうことがあります。判定基準については 04-triage.md を参照してください。
• PR ごとではなく、ラウンドごとに焦点を絞ったコミットを 1 つ作成してください。 複数のラウンドをまとめると、どの指摘がどの変更につながったのかという監査証跡が失われ、git bisect にも支障が出ます。07-commit-push.md を参照してください。
• 修正をプッシュする前に、リポジトリ独自のコマンドでビルド／テスト／リントを実行してください（CONTRIBUTING／AGENTS／README／package.json／Makefile に従います）。確認手順については 06-build-test.md を参照してください。
• 仮定上のエッジケースに対応するために Copilot の指摘が設計を過剰に複雑化する場合は、根拠を文章で示して反論してください。 すべての提案を自動的に受け入れると設計が損なわれます。04-triage.md の decline の手順を参照してください。
• gh api graphql -F の型変換、git stash push -m の位置引数解析、レビュアー変更処理に関する 3 つの GraphQL の落とし穴など、スクリプト作成時の注意点は references/api-quirks.md に記載されています。スクリプトを変更する前に読んでください。

トラブルシューティング

問題	解決方法
スクリプトが prerequisite missing — gh CLI is not on PATH を出力する	gh をインストールします（Windows では winget install GitHub.cli、macOS では brew install gh、Linux ではパッケージマネージャーを使用するか、https://cli.github.com からダウンロードします）。その後、gh auth login を実行します。メッセージをユーザーに伝え、ループを停止してください。再試行しないでください。
スクリプトが prerequisite missing — gh CLI is not authenticated を出力する	gh auth login を実行します。ユーザーが認証を完了するまでループを停止してください。
トリガーに失敗する、または copilot_work_started イベントが発生しない	実質的な（空白文字だけではない）コミットをプッシュします。synchronize での自動割り当てが、最も確実なトリガーです。失敗が続く場合、そのリポジトリまたはアカウントで Copilot Code Review が有効になっていない可能性があります（リポジトリの Settings → Code & automation → Copilot、またはアカウントレベルの Copilot Pro/Pro+ を確認してください）。
約 10 分待っても新しいレビューがない	直近の却下後、または差分が軽微で抑制された場合の待機期間が原因です。実質的なコミットをプッシュして再試行してください。Copilot がまだレビュアーとして指定されている間は InFlight が報告されるため、やみくもに 01-request-review.ps1 を再実行しないでください。
オープンリストに古い未解決スレッドがある	想定どおりです。未解決状態を正とします。他のオープンスレッドと同様に、返信して解決してください。10-cleanup-outdated.ps1 は最後の安全策としてのみ使用します。
指摘を修正するか却下するか判断できない	references/04-triage.md を参照してください。
「修正済み」「却下」「ドリフト」に対する返信文の例が必要	templates/ 配下のテンプレートを参照してください：reply-fix.md、reply-decline.md、reply-drift.md、reply-partial.md。

参考資料

• references/orchestration.md — 処理全体に関わるループ制御：時間制限と延長プロトコル、 サブエージェントへの委任マップ、単一イテレーションへのフォールバック、 ループ全体に関する注意事項。
• 各ステップの仕様（ステップごとに NN-*.md が1つ）： references/01-request-review.md (親)、 references/02-wait.md、 references/03-list-threads.md、 references/04-triage.md（修正するか却下するかの 判断基準を含む）、 references/05-fix.md、 references/06-build-test.md、 references/07-commit-push.md (親)、 references/08-reply-resolve.md、 references/09-convergence.md（ラウンド上限に 達した場合の要約ゲートを含む）、 references/10-cleanup.md (親)。
• references/api-quirks.md — 検証済みのGitHub APIの動作、行き詰まりやすい箇所、レビュー担当者の 変更に関するGraphQLの落とし穴。
• テンプレート（返信の種類ごとに1つ）： templates/reply-fix.md — 修正を受け入れるパターン； templates/reply-decline.md — 理由を添えて却下するパターン； templates/reply-drift.md — PRの説明／コメント／テスト計画とのずれを認めるパターン； templates/reply-partial.md — 後続対応を保留する部分修正。処理全体に関わる返信のガイダンスと アンチパターンは references/08-reply-resolve.mdにあります。
• scripts/_lib.ps1 — 共通ヘルパー（Invoke-Gh、 Invoke-GhGraphQL、Resolve-RepoCoords）。すべてのスクリプトから ドットソースされます。
• scripts/01-request-review.ps1 — Copilotレビューを開始し、 copilot_work_startedイベントで処理が開始されたことを確認します。
• scripts/02-check-review-status.ps1 — PRのCopilotレビュー状態を一度だけスナップショットとして取得し、 3つすべての条件を満たした場合にのみConverged: trueを出力します。
• scripts/03-list-open-threads.ps1 — すべてのレビュー担当者（Copilot、 人間、github-advanced-securityなど）による、未解決のPRレビュースレッドをすべて取得します。
• scripts/08-reply-and-resolve.ps1 — 1回の呼び出しで返信を投稿し、スレッドを解決します。
• scripts/10-cleanup-outdated.ps1 — 古くなったCopilotスレッドに対するセーフティネットです。