file-pr

プルリクエストを作成する

PR は、セッション、差分、チケットを見ていない人が読みます。以下の各条件はすべて、その読者が変更内容を一度読んだだけで理解できるようにするためのものです。

1. 前提条件を確認する

ブランチと、現在の done レディネスカードを読みます。

• ブランチ。 git rev-parse --abbrev-ref HEAD の結果がカードの Branch と完全に一致し、CLAUDE.md のブランチ命名規則を満たしていること。ブランチ名の変更やブランチの切り替えを行うとカードは古くなるため、done に戻ります。
• レディネスカード。 done で定義されている現在の Git カードを必須とします。これには、request、currency、coverage、lane、evidence、verdict、next-action の各フィールドが含まれます。verdict が ready-to-publish で、next action がこのスキルと完全に一致している必要があります。フィールドが欠けている場合や、verdict が異なる場合は done に戻ります。ここでカードを再構成しないでください。
• 公開モード。 ユーザーの公開リクエストに基づき、期待される PR の状態とドラフトモードを確定します。リクエストでドラフト公開が指定されていない場合は、OPEN と isDraft: false を使用します。

ゲートの条件は、ブランチ、カードの存在、期待される状態、ドラフトモードのそれぞれについて結果が記録されていることです。いずれかの確認に失敗した場合は、PR の作成を中止します。

2. ベースを検証して、イシューへのリンクを解決する

done ですでに解決済みの PR のベース ref と正確なベースリモートを使用します。カードに記載された正確なコマンドで記録済みの <base-remote> ref を更新し、そのリモート名、ref 名、リモートのベース tip SHA、merge-base SHA が一致することを確認します。ハードコードまたは置き換えられたリモートを使うとカードは古くなります。別のベース状態や選択肢を使う場合、検証済みの差分が変わるため done に戻ります。

イシューへのリンクは、次のいずれか1つだけを選びます。

• 差分によってイシューが完全に解決される場合：Closes #N
• 一部のみ解決する場合、包括チケットのサブタスクの場合、またはエピックの一部分の場合：Refs #N に加えて、対象となる部分と未解決の部分を記した1行
• イシューの調査中に見つかったものの、解決しない場合：Refs #N とし、その旨を本文に記載

この差分で完了しないイシューに Closes を使ってはいけません。

ゲートの条件は、ベース ref、リモートのベース tip、merge base が更新後のリモート状態と一致し、イシューへのリンクが推測ではなくイシューの出力に基づいていることです。

カードの通用性と引き継ぎの適格性を再検証する

ラベルを信用せず、カードを再計算します。

• アクティブなリクエストのスコープが Originating request と一致すること。
• アクティブなブランチが Branch と完全に一致すること。
• 更新後のベース ref、tip、merge base が PR base ref、Remote base-tip commit、Merge-base commit と一致すること。
• 外部の複合ターゲットすべてについて、新しく取得した信頼できる読み戻しの結果が、記録されたターゲット、バージョン、フィールドと一致すること。
• カードが done の ready-to-publish ルールを満たすこと。

スコープを検証する直前に、git write-tree を通じて done の代替インデックス構築を実行します。クリーンアップの前に、候補差分を実行します。

GIT_INDEX_FILE="$snapshot_index" git diff --cached --no-ext-diff <merge-base> --

スナップショットが Verified content snapshot と一致することを確認します。変更されたすべてのハンクまたは論理的変更を、検証済みのリクエスト行に対応付けます。それらの行に含まれないものは、CLAUDE.md に記載された中止して確認を求めるケースです。その後、done のインデックスクリーンアップを実行します。

Existing PR URL が not-applicable の初回公開カードでは、HEAD が Pre-verification head と一致し、Expected append-only commits が none であることを必須とします。既存 PR を置き換えるカードでは、done で記録された追加のみの遷移とコミット後のコンテンツシールが、現在の HEAD および Verified content snapshot と一致することを必須とします。別のコミットは禁止です。リクエスト、ベース、想定外の head、またはコンテンツスナップショットが変わると、カードは古くなります。不一致がある場合は done に戻ります。

ゲートの条件は、再計算したリクエスト、ブランチ、ベース ref と SHA、head、スナップショット、外部情報の通用性、候補差分、ready-to-publish の verdict がすべてカードと一致することです。

3. タイトルを作成する

形式：<type>(<module>): <description>。モジュール名は、ディレクトリの表記ではなく、ボード上の表記に合わせます。

説明には、誰かが目にすることを記します。何が壊れたのか、または何ができるようになったのかを示します。編集した内容ではありません。

説明全体として使用禁止：improve、update、handle、refactor、fix logic、clean up、various fixes。

仕組み：書き換える	成果：リリースする
fix(portions): correct filter logic	fix(portions): portion totals skipped orders placed after cutoff
feat(auth): update session handling	feat(auth): stay signed in across browser restarts

タイトルには、それを目にする人を記します。正直に答えると「差分を読む人」だけになる場合、タイトルが仕組みを示しているため、書き換えてください。

ゲート条件は、目にする人が明記され、説明に使用禁止の語が単独で使われていないことです。

4. 本文を作成する

何が問題だったのか、次に何が変わったのかに答える、平易な文章を2〜4文で冒頭に書きます。差分を開かない人にも伝わる内容にしてください。冒頭に見出しを置かず、箇条書きにはせず、省略もしないでください。

次に、実際に内容のあるセクションだけを含めます。

• 変更内容。 検証済みのリクエスト行ごとに、成果を中心とした箇条書きを1つ作成します。差分から追加内容を推測しないでください。
• 検証方法。 根拠インデックスに記載された正確な観察結果だけをもとにします。該当する not-applicable の理由を含め、根拠を捏造しないでください。
• QA の記録。 変更が UI に表示され、browser-qa の録画パスがわかっている場合、録画に合成データまたは編集済みデータしか含まれていないか、ユーザーが公開を明示的に承認している場合に限り、作成時に --attach <path> を付けて録画を添付します。バックエンドのみの変更では添付しません。添付には gh v2.99.0 以降が必要です。push や create の副作用を伴う操作の前に gh --version で要件を満たしていることを確認してください。インストール済みのバージョンが古い場合は、UI に表示される PR を録画なしで公開せず、gh のアップグレードのために done に戻ってください。ユーザーが明示的に決定した場合に限り、添付なしで公開できます。その場合も、アップグレード後に遅れて添付する必要があります。
• リスクまたはスコープに関する注記。 本当に不確かな点、移行した点、または意図的に先送りした点がある場合に限ります。
• セクション2の課題リンク。

見出しの下に何もない場合、その見出しは削除します。小規模な PR では、導入段落、検証方法、リンクだけにします。内部の準備状況テーブルを PR 本文に貼り付けないでください。

本文の文体と、エージェント、パイプライン、セッションへの言及を禁止するルールは、CLAUDE.md に記された人間が作成したルールに従います。

ゲート条件は、導入段落だけで内容が伝わり、記載されたすべての見出しに内容があることです。

5. 結果を初見で確認する

セッションの文脈を知らない人になったつもりで、作成したタイトルと本文を一度読みます。各基準について、結果を明記してください。

• タイトル。 誰がその内容を目にするのか。
• 導入文。 何が問題だったのか、何が変わったのかを、差分なしで伝えているか。
• 用語。 ファイル、フラグ、用語はすべて、初出時に説明されているか。
• 前の記述への参照。 「前述のとおり」「上記」「先の課題」といった表現がないか。
• 検証。 何が実行されたかを説明しているか。何が動作するはずかではなく。
• 文体。 決まり文句、em ダッシュや en ダッシュ、エージェントやセッションへの言及がないか。

結果を明記していない基準は、確認していない基準です。基準を満たしていない場合は書き直し、再度読みます。例外として注記したまま公開してはいけません。

ゲート条件は、6つすべての基準に結果が明記され、失敗している基準がないことです。

6. コミットして公開する

認証済みの gh repo view ... --json id,nameWithOwner で $repository を解決し、ベースリポジトリとして記録します。有効なリモートとは、git remote get-url --all <remote> と git remote get-url --push --all <remote> から取得した順序付きの完全なフェッチ先とプッシュ先のセットがあり、認証情報を除去して正規化したすべてのエンドポイントを、認証済みの gh repo view ... --json id,nameWithOwner で解決すると、共通のリポジトリ ID と nameWithOwner に一致するものです。エンドポイントのスキームが HTTPS または SSH 以外の場合、解決できても無効です。認証情報が平文でネットワーク上を流れるためです。解決時にリダイレクトをたどった場合、最終的なホスト、所有者、リポジトリが意図した対象と一致しなければ、そのリモートは無効です。プッシュの出力にリダイレクトが示された場合は、その最終 URL も同じ方法で解決し、プッシュが反映されたものとして記録する前に、HTTPS を使用し、意図したホスト、所有者、リポジトリと一致することを要求します。認証情報は保持せず、順序付きの正規化セットまたはそのダイジェストと、解決済み ID のみを保持します。

Existing PR URL が指定されている場合は、コミット、プッシュ、作成をスキップし、リモートの列挙前に ${CLAUDE_SKILL_DIR}/references/existing-pr-reuse.md を読み込みます。このファイルには、そのブランチで既存 URL に対して実行する gh pr view の読み取り、複数一致と一致なしの場合の処理を含むヘッド ID に基づくリモート照合、凍結、再検証、調整の要件、追加のプッシュなしでリモートのヘッドを示す証拠となる情報、ならびに後述のページ分割された候補検索と、後続のカードに対するタイトルまたは本文の編集の動作が記載されています。

Existing PR URL が指定されていない場合は、リモートを選択する前に、現在のブランチに設定されたアップストリームを確認します。完全に設定され、解決可能なアップストリームで、ブランチ参照が公開ブランチと一致する場合、そのリモートが有効なときに限り、指定されたリモートを選択します。不正形式、不完全、または解決不能な設定済みアップストリームは reconcile-required です。アップストリームが存在しないことを確定できた場合は、有効なリモートを列挙します。有効なリモートが 1 つなら自動選択し、複数ある場合は具体的な <remote>: <nameWithOwner> (<id>) を選択肢として、必要に応じてページ分割しながら AskUserQuestion を使用します。選択肢が複数ページにわたる場合は、互いに重複しない選択肢のセットに分けてページ分割します。有効なリモートがない場合は、Configure one valid publication remote or bind the branch upstream, then rerun file-pr. と表示して停止します。選択した有効なリモートによって、ヘッドリポジトリの ID と <head-owner> が確定します。ベースリポジトリと同じ場合も、異なる場合もあります。

選択したリモートの順序付き完全なエンドポイントセットと、ベースおよびヘッドの個別の ID を、ガードおよび無効化条件として記録します。各プッシュと、権威ある読み戻しの直前に再列挙します。追加、削除、順序変更、解決失敗、またはヘッドリポジトリの不一致があれば、reconcile-required です。名前付きリモートへのプッシュで、その設定済みの完全なプッシュ先セットを対象にできるのは、その凍結済みセットが引き続き一致する場合に限ります。

初回の公開では、git-commit の直前、またはコミットが不要な場合はプッシュの直前に、セクション 1～2 に記載されたブランチ、ヘッド、更新済みのベース参照と SHA、混在した外部読み戻し、代替インデックスのスナップショットの各チェックを繰り返します。スナップショットが変更されていない場合に限り、完了済みのハンク集計を再利用します。スナップショットが変更されていれば done に戻ります。検証済みスナップショットが HEAD^{tree} と異なる場合は、検証済みのリクエスト行に対して、封印済みインデックスモードで git-commit を呼び出します。Verified content snapshot を渡し、ステージされたツリーがそれと一致することを要求し、コミット前の追加のステージングを禁止します。作成されたすべての SHA を記録します。done で定義された追記専用の遷移コマンドを実行します。祖先関係、マージ、順序付きリストの完全一致に関する基準をすべて満たす必要があります。リベース、マージ、または記録されていないコミットがあれば done に戻ります。正確な順序付きリストを、カードとともに返される公開証拠の Expected append-only commits に追加します。 初回公開では、プッシュする前に、アクティブなブランチが引き続き Branch と一致し、混在する外部ターゲットをすべて改めて取得し、その最新状態が引き続き一致することを必須とします。その後、done のコミット後コンテンツシールを実行します。git status --porcelain=v1 --untracked-files=all と git rev-parse HEAD^{tree} の正確な出力を記録します。ステータス出力は空でなければならず、ツリー SHA は Verified content snapshot と完全に一致しなければなりません。それ以外の場合は done に戻ります。

初回公開では、git symbolic-ref --quiet HEAD が refs/heads/<card-branch> と一致し、そのブランチ参照と HEAD が同じ SHA を指す場合に限り、push-attempt SHA を固定します。正確なリモート参照を照会し、SHA が 1 つ返されるか、存在しないことが権威ある形で確認されることを必須とします。存在する場合、その SHA が push-attempt SHA の祖先であることを必須とします。プッシュの直前に、カード 1 件のみを含むインライン呼び出しで preflight-mutations を実行します。そのアクションでは、push-attempt SHA を正確な参照にプッシュします。そのガードと無効化条件には、アクティブなシンボリック参照、ブランチ参照の SHA、HEAD の SHA、選択されたリモート名、順序を保持した完全な fetch および push エンドポイントのセットとリポジトリ ID、個別のベースおよびヘッドのリポジトリ ID、正確なリモート SHA または不存在、混在する外部ターゲットの最新状態を含めます。その読み戻しには、以下の正確な git ls-remote クエリを使用します。グローバルルールに基づく許可済みの file-pr 呼び出しが、認可の根拠となります。結果は個別に適用します。すべての無効化条件が一致している ready の場合のみ続行し、confirmation-required の場合は確認を求め、blocked の場合は停止します。コマンドの直前に、アクティブなシンボリック参照、ブランチ参照、HEAD、選択されたリモートの識別情報を再読み込みします。いずれかが変化した場合、その試行は無効になります。

git push --force-with-lease="refs/heads/<card-branch>:<expected-remote-sha-or-empty>" "<push-remote>" "<push-attempt-sha>:refs/heads/<card-branch>"
git ls-remote --heads "<push-remote>" "refs/heads/<card-branch>"

プッシュを試みるたびに、コマンドの終了コードが 0 以外の場合や結果が不明な場合も含め、選択されたリモートの識別情報を再確認し、正確な git ls-remote 読み戻しを一度実行します。その権威ある SHA が push-attempt SHA と一致する場合に限り、landed-push SHA を記録します。古い SHA や予期しない SHA、読み戻しができない場合、またはリモートの識別情報が変わった場合は reconcile-required です。公開を停止し、プッシュコマンドの結果だけを根拠に再試行してはなりません。

初回公開では、アクティブなシンボリック参照、ブランチ参照の SHA、HEAD が、固定した試行時点の状態と一致することを再確認します。リモートの読み戻しに成功していても、ローカルの変化があれば、残りの公開処理は無効になります。その後、${CLAUDE_SKILL_DIR}/references/upstream-binding.md を読み込みます。この初回公開の分岐に進んだ場合に限り、このファイルには、ブランチの上流状態を解決する 2 つの git config プローブ、ABSENT、reconcile-required、権威ある no-op の分類、読み戻しを伴うガード付きバインドコマンド、およびプッシュが反映された後にバインドに失敗した場合の remote landed / upstream not bound の処置が記載されています。

最終本文をファイルに書き込み、その SHA-256 ダイジェストを記録します。以前の試行が存在するかどうかを判断する前に、権威あるページネーション付き REST クエリを通じて、ベースリポジトリ内のすべての PR を取得します。

gh api --paginate --slurp "repos/$repository/pulls?state=all&per_page=100"

すべてのページが正常に返され、完全に解析できることを必須とします。いずれかのページでエラーが発生した場合、続きの取得ができない場合、またはページネーションが不完全な場合は reconcile-required です。完全な結果をローカルで head.repo.id == <selected-head-repository-id> および head.ref == <head-branch> によって正確に絞り込み、残ったレコードを既存の候補フィールドに対応付けます。merged_at が null でなければ MERGED とし、そうでなければ OPEN または CLOSED の状態をそのまま保持します。 既存の PR URL がない場合は、アクティブなシンボリック参照、ブランチ参照の SHA、HEAD が landed-push SHA と一致するかを再確認し、すべての状態にわたって保持されている候補をすべて照合します。OPEN の候補で head SHA が誤っているもの、または複数の open 候補がある場合は reconcile-required となり、作成を中止します。有効な open 候補が 1 つある場合は、要求された base、状態、draft モードに一致するか、明示的な base の再バインドまたは公開判断の手順に進みます。その URL を記録し、編集前にバインドするため done に戻ります。異なる head SHA の CLOSED または MERGED の候補は履歴上のものであり、ブランチの再利用を妨げません。landed-push SHA の closed または merged の候補がある場合は、明示的に再オープンするか、新しいブランチを作成するか、公開しないかを判断する必要があります。今回の試行に対する open 候補がなく、closed または merged の候補もないことが、全状態を含む完全な結果で確認できた場合にのみ作成します。作成を試みた結果、使用可能な URL が返されない場合も、同じ全ページのクエリと正確なローカルフィルターを使用します。

選択した head が base リポジトリであるか、そのフォークネットワークに属していることを、権威あるリポジトリメタデータで確認します。無関係な head がある場合は作成を中止します。プリフライトの前に、作成経路を 1 つに確定します。同じリポジトリの head には gh pr create --head <branch> を使用します。選択した head リポジトリが base リポジトリでない場合は、作成経路を確定する前に ${CLAUDE_SKILL_DIR}/references/fork-creation-lanes.md を読み込みます。ここには、認証ユーザー所有と組織所有のフォーク経路、安定 ID による所有者タイプと所有関係の判定（それ以外の関係をすべてブロックします）、および REST の head_repo 作成形式が記載されています。PR を作成する直前に、インラインの単一項目カードを新規作成して preflight-mutations を呼び出します。その対象は、正確な base リポジトリと選択した head リポジトリです。アクションには、確定した作成経路、base、head リポジトリとブランチ、landed-push SHA、タイトル、本文パスとダイジェスト、さらに記録用の添付先パスが確定している場合はそのパスとデータ承認、SHA-256 ダイジェスト、バイトサイズ、期待される OPEN 状態、期待される draft モードを記録します。ガードには、両方の完全なエンドポイントセットとそれぞれのリポジトリ ID、base と head のリポジトリ ID、アクティブなシンボリック参照、ブランチ参照の SHA と HEAD が引き続き landed-push SHA にあること、検証済みのリモートブランチ、記録された base の先端、全ページにわたる完全な候補結果と正確なフィルター、open 候補がないこと、および今回の試行に同じ head SHA の候補がないことの確認を含めます。読み戻しには、以下の正確な gh pr view クエリを使用します。同じ結果契約に基づき、この結果を個別に適用します。ローカル参照、HEAD、エンドポイントセット、base または head の ID、作成経路、タイトル、本文パス、ダイジェスト、記録用の添付先パス、承認、ダイジェスト、サイズ、状態、draft モードのいずれかが変更された場合、カードは無効になります。PR カードが ready でなくても、landed push の証拠は消去されません。

バインドされた draft モードが isDraft: true の場合に限り、作成コマンドに --draft を追加します。

同じリポジトリの場合：

gh pr create --repo "$repository" --base "$base" --head "$head_branch" --title "$title" --body-file "$body_path" [--attach "$recording_path"] [--draft]

`--attach` needs gh v2.99.0 or later and uploads the file to GitHub, WebM included, so the body carries no local path. Video cap is 10 MB on Free plans, 100 MB on paid. Immediately before creating with `--attach`, recompute the recording SHA-256 and byte size and require both to match the frozen card values.

以下の 10 フィールドのクエリを使い、すべての経路で同じ方法で読み戻します。このリストを唯一の参照元とします。references/existing-pr-reuse.md と references/fork-creation-lanes.md はこのリストを参照し、再掲しません。

gh pr view <pr-url> --repo "$repository" --json url,title,body,baseRefName,baseRefOid,headRefName,headRefOid,headRepository,state,isDraft

確定した経路のみを実行します。曖昧な結果が返された後に、他の例を代替手段として使用してはいけません。 PR の title が固定値と一致することを必須とします。録画が添付されていない場合は、body が固定された本文と完全に一致することを必須とします。録画が添付されている場合は、固定された本文テキストがそのまま保たれ、アップロードされた録画への参照が含まれることを必須とします。調整の際も、その参照を保持し、本文を固定されたバイト列に戻して編集しないでください。headRepository.id が選択したヘッドリポジトリ ID と一致し、headRefName が Branch と一致し、headRefOid が landed-push SHA と一致し、baseRefOid が Remote base-tip commit と一致することを必須とします。URL、ベース名、state、isDraft が公開リクエストと一致することを必須とします。公開を受け入れる前に、アクティブなシンボリック参照、ブランチ参照の SHA、HEAD が landed-push SHA と一致することを再確認します。PR が正式に特定されたら、作成された URL をすぐに landed として記録します。リポジトリ、ベース、ヘッド、状態、ドラフトモードが一致し、タイトルまたは本文のみが異なる場合は、既存の PR を正確に編集する処理を事前確認し、編集後に読み戻します。ベースが一致しない場合は、その URL と観測された値を使って、done の既存 PR の再バインド処理に進みます。作成処理を再度実行してはいけません。状態またはドラフトモードが一致しない場合は、明示的な公開判断を求めて停止します。黙って再オープン、クローズ、変換、または別の PR の作成をしてはいけません。次の done 実行に向けた公開証跡として、2 枚のシングルステップカード、プッシュの着地結果、PR の観測値、順序付きコミットリスト、正確なコマンドを記録します。正式な検索で PR が作成されたかどうかを特定できない場合は、作成処理を reconcile-required とし、再試行してはいけません。

URL を出力し、CI、レビュー、公開レーン、最終行の評価のために done に戻ります。マージしてはいけません。PR を開くことは公開の遷移であり、タスク全体の完了ではありません。

前提条件が満たされ、ベースの最新性と課題リンクが実際の出力に基づいており、タイトルと本文がコールドリードに合格し、リモートブランチと PR がローカルの公開内容に一致し、全体の完了を主張せずに証跡が done に戻された場合、引き継ぎは成立します。