finish-it

完了させる

1 回のデリバリーを実行します。仕様のソースからプルリクエストを作成し、少なくとも 1 ラウンドを経た後、またはデリバリーでの最初のレビューで対応事項がなく承認された場合はそのレビューの後に、最新の公開済みレビューが現在のヘッドを反映している状態にします。各ステップはそれぞれ新しいコンテキストのサブエージェントで実行されます。共有メモリはフォージのみであるため、ディスクには何も永続化されません。このスキルをプルリクエストで再実行すると、フォージに記録されている状態からデリバリーを再開します。

このスキルでは、次の 3 つの用語を使用します。

• 仕様のソース：プルリクエストで実装するイシュー、チケット、または文書化された仕様です。
• ラウンド：プルリクエストへのフィードバックに対する resolve-review の処理 1 回です。対応事項がなければスキップされ、その後に review-code-publish で再レビューします。
• デリバリー：どのステップからでも開始できる、一連の処理全体です。

境界

このスキルを実行すると、基盤となるスキルが代わりに行うすべての書き込みが許可されます。これには、文章による仕様からのイシュー作成、プルリクエストの作成、レビューの公開、返信、スレッドの解決、対応内容の要約が含まれます。マージやイシューのクローズは行わず、ラベルや担当者にも変更を加えません。

デリバリーは無人で実行されます。基盤となるスキルがユーザーに尋ねる質問は、プルリクエストの作成後にプルリクエストへ投稿されます。停止する場合は、停止したステップとその理由を示します。

implement-publish、review-code-publish、resolve-review、review-code のいずれかがインストール済みスキルに含まれていない場合は、書き込みを行う前に missing-dependency: <name> を出力して停止します。先に 4 つすべてを確認してください。review-bot は任意です。利用できない場合は、認証済みユーザーを使用するフォールバックとして記録し、ゲーティングは行いません。依存関係の不足による停止にはなりません。

プロセス

1. 入力を確定する

docs/agents/issue-tracker.md がある場合は読みます。次の項目を記録します。

• N：要求されたラウンド数の合計。呼び出し文に記載された整数（rounds: 5、「2 rounds」など）を使用し、記載がない場合は3です。0も指定できます。
• ベースブランチ：呼び出し元が指定したブランチ。指定がない場合は、リポジトリのデフォルトブランチです。
• 作成者のID：このセッションがコード、プルリクエスト、返信、対応概要を投稿する際に使用するフォージのログイン名（gh api user --jq .login）。
• レビュアーのID：ここで一度だけ、docs/agents/issue-tracker.md に記載された Reviewing app と Client id、または任意のリテラル Review-token command から解決します。リテラルコマンドがある場合は、review-bot を参照せず、そのまま実行してログイン名を読み取ります（GH_TOKEN=$(sh -c '<review-token command>') gh api graphql -f query='{viewer{login}}' --jq .data.viewer.login）。アプリのトークンでは gh api user は拒否されます。コマンドがない場合、失敗した場合、またはそのトークンで認証できない場合も、エラーにはなりません。リテラルコマンドが指定されていないアプリの場合は、インストール済みであれば、対象リポジトリを <owner>/<repo> として review-bot の Resolve エントリーポイントを呼び出します。対象リポジトリとはベースブランチを所有するリポジトリであり、プルリクエストが作成された後はそのベースリポジトリです。チェックアウトのリモートは使用しません。返されたログイン名とコマンドは、そのまま保持します。スキルが存在しない場合、unavailable の結果が返された場合、またはリテラルコマンドが失敗した場合は、作成者のIDを使用し、その理由をレポートとパケットに記録し、ゲーティングを適用しません。IDの解決によってデリバリーを停止することはありません。アプリもコマンドも指定されていない場合は、作成者のIDを使用します。公開時にトークンが拒否された場合、その書き込みは停止します。
• ゲーティングの承認：レビュアーのIDが、プルリクエストの作成者とは異なるレビュー用アプリの場合に限り、承認済みとなります。これにより、レビューで APPROVE または REQUEST_CHANGES を指定できます。作成者のIDにフォールバックした場合は、自己レビューのルールに従ってレビューが COMMENT として公開されるため、承認は保留されます。この判断をここで記録します。サブエージェントが推測してはなりません。
• ネストされたレビュアーのティア：呼び出しに reviewer tier: <name> が指定されている場合はその名前を使用し、指定がない場合は未設定にします。ティアが未設定の場合、各下位スキルのディスパッチがそれぞれのティアを選択します。名前付きのティアはその選択を上書きし、各ステップでそのティアをレビュアーのディスパッチに引き継ぎます。各ディスパッチでは、選択したティアを明示します。

呼び出し元が曖昧なままにしたベースや仕様の情報源は、ここで確定します。ユーザーに質問できないサブエージェント内で確定してはなりません。確定できない場合は、書き込みを行う前に停止します。

2. 配信先を特定する

forge を読み、エントリーテーブルから最初のステップを選びます。数値だけの場合は、issue-tracker のドキュメントにあるとおり、まずプルリクエストを探し、次にイシューを探します。

観測された状態	最初のステップ
散文形式の仕様	イシューを作成し、その後イシューの行へ進む
クローズする未オープンのプルリクエストがないイシュー	実装
オープン中のプルリクエストによってすでにクローズされたイシュー	そのプルリクエストの行
コミットはあるが、プルリクエストもイシューもない現在のブランチ	実装し、implement-publish にブランチとコミットから仕様を推測させる
どのヘッドにもレビューがないプルリクエスト	レビューし、その後ラウンドへ進む
現在のヘッドに対する最新のレビューが Approved ではないプルリクエスト	ラウンドへ進む
最新レビュー以降にヘッドが更新されたプルリクエスト、または最新レビューより新しい対応サマリーがあるプルリクエスト	レビューする。これにより保留中のラウンドを未カウントで終了し、その後ラウンドへ進む

プルリクエストを読む際の注意事項：

• 「最新」とは、forge のタイムスタンプに基づくもので、コメントに最終編集日時がある場合はその日時を使い、あらゆる ID によるレビューと対応サマリーを対象にします。人間によるレビューもレビューです。
• 関連付けられたイシューがないプルリクエストは、プルリクエスト自体のテキストをもとにレビューします。review-code がこれを処理します。
• イシューのオープン中のプルリクエストは gh pr list --state open --search "<number>" で見つけ、本文内のクローズ参照で確認します。

散文形式の仕様からイシューを作成する場合：gh issue create を使い、自分で書いた1行のタイトルと、## Spec 見出しの下に仕様の散文をそのまま記載した本文を指定します。ラベルや担当者は設定しません。イシューを読み返し、その番号を以降のすべてのステップで仕様の参照元として使います。

完了済みラウンドのカウント。 D は、`` トレーラーを含むか、**Addressed** at で始まる一般的なプルリクエストコメントの数です。ID は問いません。残りのラウンド数 = max(1, N − D) です。D と残りの数を記録します。

3. 引き継ぎパケット

すべてのサブエージェントには、同じパケットのみが渡され、それ以前の手順の情報は渡されません。パケットには、リポジトリのパス、ベースブランチ、ヘッドブランチ、プルリクエストの URL、Issue の URL または仕様のソース、ラウンド番号と残りラウンド数、作成者の ID、レビュー担当者の ID と手順 1 の解決結果（フォールバック理由があればその内容を含む）、該当する場合は返された、またはそのままのレビュー・トークン・コマンド、手順 1 のゲート承認、名前付きのネストされたレビュー担当者のティアまたは未設定の状態が含まれます。レビュー担当サブエージェントは解決担当サブエージェントの報告を見ません。解決担当サブエージェントはレビューのテキストを見ません。両者とも forge を読み取ります。

各手順は、会話の内容を一切引き継がない新しいコンテキストの 汎用 サブエージェント 1 つとしてディスパッチします。fork_turns="none" またはホスト側の同等機能を使用してください。各基盤スキルが独自のレビュー担当者または検証担当者をディスパッチするため、汎用にしてください。Agent ツールを持たないタイプは適していません。ディスパッチで選択したティアを明示し、待機可能なルート、フォアグラウンド・ディスパッチ、またはサポートされているジョインを使って実行してください。ツール呼び出しによって、セッションがアクティブなまま完了した報告が返される必要があります。受領確認やエージェント ID は報告の返却ではありません。forge から手順の成果物を読み取るのは、サブエージェントの返却後に限ります。サブエージェントには、パケットとともに名前を指定したスキルを呼び出すこと、名前付きのネストされたレビュー担当者のティアを引き継ぐこと（フィールドが未設定の場合は、基盤スキルに選択させること）、ディスパッチまたは継続のたびに選択する待機可能なルートで、ディスパッチしたすべてのサブエージェントの返却を待つこと（自身のレビュー担当者または検証担当者が実行中のままの報告では、手順は完了していません）、そして最終報告を返すことを指示してください。

サブエージェントの報告は申告です。各手順の後、次に進む前に、forge からその手順の成果物を読み取ってください。成果物がない場合、手順内のサブエージェントが保留中であることを示す報告（early-handback: <step>）、手順の成果物ルールで認められない基盤スキルの名前付き停止、または解決できない仕様のソースやベースブランチは、手順の失敗です。失敗した手順があればデリバリーを終了し、手順と理由に加えて、該当するフェーズ、判明している場合は保留中のエージェント ID、欠けている成果物を記載した報告を返してください。手順は再試行せず、スキップもしません。オーケストレーター自身による forge への書き込みは 1 回だけ試みます。結果が曖昧な場合は、1 回だけ再試行する前に対象を読み取り、その後は再度書き込まずに失敗を報告してください。

4. 実装

サブエージェントには、仕様のソース、ベースブランチ、パケット内の現在のブランチを指定して implement-publish を呼び出すよう指示してください。

成果物：ブランチをヘッドとする、オープン状態のプルリクエストが正確に 1 件あること。その URL とヘッド SHA をパケットに記録してください。implement-publish は、ローカルレビューで最終コミットが承認された後にのみ公開します。そのため、人にしか答えられない質問など、満たせないゲートがある場合はプルリクエストが作成されず、手順は失敗となります。

5. レビュー

サブエージェントには、仕様のソースを指定して、プルリクエストに対し review-code-publish を呼び出すよう指示してください。

成果物：レビュー担当者の ID によるレビューで、そのレビュー対象のヘッドがプルリクエストの現在のヘッドと一致していること。ログイン名を比較する際は、両側の末尾の [bot] を無視してください。GitHub の REST の記録にはこのサフィックスが付きますが、GraphQL の author.login では省略されるため、正規化せずに比較すると、アプリ自身のレビューと一致しません。review-code-publish の duplicate-review 停止は、すでに存在するそのようなレビューを示しているため、レビュー手順は成功です。そのレビューを forge から読み取ってください。ステータス、未解決の質問、異議のある指摘を記録してください。

6. ラウンド

このデリバリーでステップ 5 を実行し、以下の空の台帳チェックが成立する現在のヘッドでレビューが Approved の場合は、ラウンドを実行せずに報告してください。対処事項が何もない変更されていないヘッドを再レビューしても、同じ結果を繰り返すだけだからです。それ以外の場合は、残りの各ラウンドを順番に繰り返します。

1. 空の台帳チェック。 現在のヘッドで、最新のレビューが Approved であり、未解決の質問も異議のある指摘も記載されておらず、未解決のレビューコメントも、プルリクエストの作成者からの返信がないままフィードバックを保留しているコメントもありません。すべての条件を満たす場合は、解決ステップをスキップしてレビューに進みます。この場合もラウンドとして数えます。
2. チェックアウトを準備します。 フェッチし、ワーキングツリーがクリーンであることを確認して、プルリクエストのヘッドブランチを現在のヘッドでチェックアウトします。作業ツリーが汚れている場合は停止し、クリーンアップは行いません。
3. 解決します。 サブエージェントに、プルリクエストで resolve-review を実行するよう指示します。成果物は、このパスで投稿した対処サマリー、または同じヘッドを対象に更新した既存のサマリーです。その最終編集日時は、このラウンドで対処するレビューより後であり、addressed head= がプッシュ済みのヘッドと一致し、そのヘッドはローカルのヘッドと一致している必要があります。このラウンドでコミットを追加したかどうかを記録します。
4. 新しいヘッドで、ステップ 5 と同様にレビューします。
5. ラウンドを数え、現在のヘッドでレビューが Approved となり、空の台帳チェックが成立したら早期に停止します。このデリバリーの 2 ラウンド目以降では、ラウンドで進展がなかった場合も早期に停止します。進展がないとは、コミットが追加されておらず、レビューに残っている未解決項目が、人の対応を待つ異議のある指摘または質問のみであることを指します。ラウンドを開始した場合、デリバリーの最初のラウンドは必ず実行します。最初から Approved になっていたプルリクエストも対象です。

7. 報告

プルリクエストの URL とヘッド SHA、最終レビューのステータス、このデリバリーで実行したラウンド数と開始時に検出した D、異議のある指摘、未解決の質問、および停止したステップとその理由を報告して終了します。ファイルの位置情報はすべて、報告したヘッドにおける forge の不変リンクとします。