merge

プルリクエストをマージする

現在のリクエストによる変更を、プルリクエスト、検証済みのマージ、安全なローカルクリーンアップまで進めます。必要なコミット、同期、公開、PR 作業を完了してください。ベースの同期には pull スキル、プルリクエストの作成または更新には pr スキル、マージ後のクリーンアップには clean-branches スキルを使用します。

このスキルには pull、pr、clean-branches が必要です。作業を始める前に、それぞれがインストールされていることを確認してください。見つからないものがある場合は作業を中止し、インストールコマンド npx skills@latest add toy-crane/skills --skill <name> を、プロジェクトで指定されているパッケージマネージャーのランナーを使って報告してください。

現在のリモートの状態を起点にします。無関係な作業を保持し、このリクエストの変更だけを論理的な Conventional Commits としてコミットしてください。指定されたベース、またはリモートが提示するデフォルトブランチを解決します。変更またはそのプルリクエストがすでにマージされている場合は、新たに作成せず、その結果を確認して報告してください。既存のオープン PR がある場合は、その最新のヘッドを取得し、リモートで確認したコミットと対象範囲内のローカル作業の両方を保持して、チェックアウトを同期します。意図する組み合わせが明確でない場合は、リベースまたは公開の前に障害として報告してください。その後、検証、公開、レビュー可能な状態の PR の作成または更新に進む前に、解決したリモートとベースを指定して pull を実行してください。pull は、取得したベースにリベースしたチェックアウト、または安全にリベースできなかった場合の具体的な障害を返します。 無関係なローカル作業を保持してください。同期を可能にするために、黙ってコミット、スタッシュ、または破棄してはいけません。意図する結果が明確な場合にのみ競合を解決してください。それ以外の場合は作業を復元可能な状態に保ち、障害として報告してください。公開前に最終的な HEAD を検証し、書き換えた履歴を公開する場合は、直前に確認したリモートの PR ブランチの状態に対してのみ行ってください。 リポジトリの AGENTS.md または CLAUDE.md に ## Issue tracker セクションがある場合は、リンクされている詳細な規約があればそれを読みます。以前から使われているインラインの規約も使用できます。別途セットアップスキルをインストールする必要はありません。このセクションがない場合、このスキルのすべての Issue 関連手順を省略してください。トラッカーが設定されている場合は、マージ前に、ブランチが存在していて squash によってトレーラーが削除される前に、ブランチのコミットから Spec-Folder: docs/specs/<slug>/ トレーラーを読み取り、以下の手順に備えて各フォルダーを保持してください。

pr で PR を作成または更新する

同期後の HEAD を検証したら、解決したリモートとベースを指定して pr スキルを実行してください。ブランチを公開してレビュー可能な状態の PR を作成するか、オープン PR を再利用し、その本文と根拠を最終的な変更内容（Issue へのリンクを含む）に合わせて更新します。公開を伴うため、実行前に検証してください。pr は PR の URL を返して完了しますが、ここでは中間手順です。報告して終了せず、続けて下記のマージを行ってください。変更そのものによって本文が古くなった場合に限り、再度実行してください。リベースでヘッドが変わっただけの場合は再実行しないでください。

トラッカーが設定されている場合は、マージ前にリモートの PR 上で、以下の照合手順が読み取る内容を確認してください。PR に含まれる各 spec フォルダーには、spec.md の Issue: <tracker>:<id> 行で指定され、PR 本文でも繰り返されている Issue が 1 件ずつ対応している必要があります。また、PR が実装を提供する場合に限り、本文に規約に沿ったクローズ参照を記載します。リンク先の規約を読めない場合は、Issue に関する操作を推測したり、Issue がリンク済みまたはクローズ済みだと主張したりせず、不足している情報を報告してください。

マージとクリーンアップ

複数のコミットが意味のある独立した単位であり、ベースブランチに残す価値がある場合に限り、リベースマージで複数のコミットを保持します。それ以外の場合は、スカッシュマージを使用します。 GitHub でコミットがベースと競合してプルリクエストをリベースマージできない場合は、上記のプルリクエストブランチでの pull 同期を繰り返します。 意図した統合結果が確定したら競合を解決し、無関係なローカル作業を保持したうえで、直前に確認したプルリクエストブランチの状態に対してのみ、書き換えた履歴を公開します。意図が不明確な場合や、リモートブランチが予期せず変更された場合は、プルリクエストを開いたままにして、障害となっている点を報告します。

プルリクエストのヘッドを更新した後は、現在のヘッドに対する検証だけを使用します。それ以前の CI 結果では新しいコミットを検証できません。GitHub がマージを許可する前に要求しない、関連するチェックを完了します。リポジトリで許可され、GitHub が現在のベースに対するチェックを必須にしている場合（ブランチの最新化を必須にする、またはマージキューを使用する場合など）で、GitHub が必須とする要件のみが未完了の場合に限り、自動マージを有効にします。有効になったことを確認し、リモートから MERGED と報告されるまで待ちます。現在のベースに対する検証が必須でない場合、自動マージを利用できない場合、またはプルリクエストがすでにマージ可能な場合は、関連する CI、必須チェック、レビューを完了してから、現在のヘッドとベースを再確認し、選択した方法で直接マージします。gh pr merge --auto は、すでにマージ可能なプルリクエストをすぐにマージする場合があります。これは一般的な待機用フラグではありません。自動マージの有効化に失敗した場合は、プルリクエストを再評価し、検証と要件を満たした後に限り、直接マージします。

待機中は、現在のヘッド、ベース、関連する CI、必須チェック、レビューを再確認します。ヘッドまたはベースが変更された場合は、マージ可能かどうかを再評価し、現在のヘッドに対する検証をやり直します。有効化リクエストのヘッド一致オプションを指定しても、その後の自動マージがそのヘッドに固定されるわけではありません。書き込みアクセス権を持つ人がプッシュすると、自動マージが有効なままになる場合があります。ベースのみが変更された場合や、同じヘッドに対して遅れてチェックが実行された場合を含め、新たにエージェント側の検証または必須ではない検証が必要になったときは、プルリクエストが開いている間に保留中の自動マージを無効にし、検証を待つ前に解除されたことを確認します。マージする意図を確認できなくなり、作業を停止する必要がある場合も、自動マージを無効にします。CI の失敗や未達の要件が原因でプルリクエストを開いたまま終了する前に、保留中の自動マージを無効にし、解除されたことを確認します。それらの障害を報告し、回避してはなりません。必須チェックとレビューを尊重しつつ、リポジトリが要求していないレビューを依頼してはなりません。また、マージが成功したかどうかは、リモートのプルリクエスト状態を正とします。

リモートから MERGED と報告された後に限り、マージされたブランチだけをクリーンアップします。マージされたブランチ、存在する場合はそのワークツリー、フェッチしたベース、マージされたプルリクエストのヘッドコミットを指定して clean-branches を実行します。これにより、スカッシュされたブランチも削除できます。このコマンドは、プロジェクトで宣言されたクリーンアップコマンドを実行し、内部でまだ作業しているものがない場合に限り、ワークツリーとローカルブランチを削除します。このセッションで作業しているフォルダー、未コミットの変更があるブランチ、またはベースに含まれないコミットがあるブランチは保持します。検証済みのマージ結果とともに、holder プロセスや保持されたブランチも含め、結果の行を報告します。他のワークツリー、プロセス、ユーザーの変更は保持します。マージされたブランチがリンクされたワークツリーにあった場合、clean-branches はベースの正規チェックアウトを変更しないため、その後、現在のホストが提供する安全な方法を使って、リモートのマージ済み状態に合わせます。ブランチがプライマリチェックアウトにあった場合は、clean-branches がすでにその処理を行っています。

Issue トラッカーと仕様フォルダーの状態を同期する

リモートで MERGED が報告された後、かつリポジトリの AGENTS.md または CLAUDE.md に ## Issue tracker セクションがある場合に限り、ベースブランチ上の仕様フォルダーに合わせて トラッカーの状態を更新します。慣例で定められたツール、 Issue ID の形式、および操作を使用してください。両方のファイルを読み、最初に見つかったセクションと、存在する場合はそこからリンクされた詳細な慣例を使用します。 セクションがない場合は、この作業をすべてスキップしてください。

マージ範囲で docs/specs/<slug>/ フォルダーの差分を確認し、タイトルではなく、各フォルダーの spec.md にある Issue: 行で対応する Issue を特定します。この作業では Issue を作成しません。行がないフォルダーには、まだ Issue がありません。spec.md が変更された Issue については、慣例に従って範囲が限定された仕様セクションのみを更新し、タイトルと本文のそれ以外のすべての部分を維持してから、内容を再確認します。エージェントが作成した Issue も、人が作成したものと同様に扱います。タイトルは、その後の仕様タイトルの変更には追従しません。Blocked by の行が変更された場合は、そのブロッカーごとのフォルダーにある Issue: 行からブロッカーを特定し、ブロック関係を置き換えます。フォルダーを削除しても、その Issue はクローズしません。実装が完了したと確認できた場合に限り、Issue をクローズします。

実装を実際に含む PR の後は、トラッカーの自動クローズ動作にかかわらず、Spec-Folder トレーラーに記載された実装済みフォルダーの各 Issue が未クローズならクローズします。デフォルト以外のブランチへのマージ、トレーラーのないスカッシュコミットメッセージ、またはクローズ参照のないトラッカーでは、そうしないと Issue が未クローズのままになることがあります。仕様のみのマージでは、そのコミットにトレーラーが含まれていても Issue をクローズしません。小規模な実装を直接含む PR では、仕様フォルダーやトレーラーがない場合があります。その場合は、現在の PR の正確な Issue: 行、差分、および検証結果を確認し、それらから実装の完了が確認できたときは、その Issue をただちにクローズします。行があるだけでは Issue をクローズしません。更新後のトラッカー状態を検証し、クローズに失敗した場合は再試行が必要だと報告します。仕様のみの PR がマージされた後は、Issue をオープンのままにし、慣例で定められた準備完了操作を使って PR のレビュー中または作業中のシグナルを解除し、実装準備完了の非アクティブ状態にします。より新しいアクティブな実装がないか先に確認し、すでに開始している作業を決して降格させないでください。implement が特別な再開リクエストなしでその Issue を引き受けられることを確認するため、結果の状態を検証します。慣例にこの操作がない場合、または更新に失敗した場合は、Issue の準備ができていると決めつけず、引き継ぎがブロックされていることを報告します。

トラッカーの失敗によって、検証済みのマージが取り消されることはありません。どの操作が失敗したのか、その理由とともに報告します。後続の実行では、マージ済み PR の本文から正確な Issue: <tracker>:<id> 行を検索し、その ID で各 Issue を取得します。未クローズの Issue は、その PR の差分と検証結果から実装が実際に完了したと確認できる場合に限り、クローズを再試行します。仕様にリンクした PR やトレーラーだけでは不十分です。マージ済みの仕様のみの PR については、Issue にレビュー中またはアクティブのシグナルが残っていて、より新しい実装が開始されていない場合、記録された準備完了操作を再試行します。証拠が不足している場合や再試行に失敗した場合は報告します。このキャッチアップ処理により、スカッシュマージ後に元のブランチやトレーラーがなくなっても対応できます。

最後に、マージ済みのプルリクエスト URL、マージ戦略、検証済みのリモート状態、クリーンアップの結果、および作成・更新・クローズしたトラッカー Issue を報告します。クリーンアップまたはトラッカーの失敗は、すでに検証済みのマージを誤って報告しないよう、明示したままにしてください。