prkit

prkit

現在のブランチのコミットを、きれいな GitHub プルリクエストにまとめます。リポジトリのコミットスタイルに沿ったタイトル、何を変更したか、なぜ変更したかを説明する本文、テスト計画を、推測ではなく実際の差分から作成します。作成にはgh CLIを使い、リポジトリに PR テンプレートがある場合はそれを再利用します。

どのような場合に実行されるか

ユーザーがプルリクエストの作成を求めた場合です。「PR を開いて」「プルリクエストを作成して」「PR を出して」「レビューに提出して」「gh pr create」などが該当します。タイトルと本文だけを求めるリクエスト（「PR の説明文を下書きして」）は下書きのみの手順に進みます。この手順では、プッシュ、コミット、PR や issue の編集は一切行いません。

プレビューと承認

prkit は、ラベルによる例外を除く各変更を事前に提示し、承認を待ちます。対象は、PR の作成または編集と、引き渡されたパスのコミットです。同期処理とそれに伴う強制プッシュは、gitkit の同期ルールに従い、事前プレビューなしで実行されます。ユーザーが記録した承認を引き継いでいる呼び出し元は、その承認で指定された操作のプレビューを満たします。 その一例が afkkit です。ユーザーの無人リクエストは、issue 自身のブランチ上でのコミット、そのブランチのプッシュ、PR を承認するため、prkit はプロンプトなしで引き渡された QA 計画をコミットし、gh pr createを実行して、引き継ぎ時に承認について明示します。指定された範囲外の操作は引き続きプレビューが必要です。無人の呼び出し元はユーザーに代わって承認するのではなく、エスカレーションします。たとえば、公開済みブランチのリベースとその--force-with-lease、別のブランチへのプッシュ、マージが該当します。prkit は、呼び出し元が明示していない承認を推測しません。

下書きのみの手順

ユーザーが求めているのは PR ではなく、タイトルと本文です。この手順では読み取りと出力のみを行います。インデックス、参照、リモート、PR、issue のラベルは変更されません。

1. 冒頭の状態を 1 回の呼び出しで記録します。git rev-parse HEAD && git diff --cached --binary | git hash-object --stdin && git for-each-ref | git hash-object --stdin。-wを付けないhash-objectは何も書き込みません。
2. 事前確認にある読み取り専用チェックを実行します。デフォルトブランチまたは detached HEAD の場合も下書きは作成し、PR を開くにはブランチが必要であることを伝え、何も作成しません。
3. リモート追跡参照が移動するため、git fetchを使わずにコンテキストの収集を行います。git ls-remote origin refs/heads/<base>でリモートのベース先端を読み取り、git rev-parse origin/<base>と比較します。ローカルのベース参照が遅れている場合は、下書きでその旨を伝えます。
4. タイトルと本文の作成と、証拠アーティファクトの埋め込みにあるバンドルの選択および鮮度チェックを適用します。
5. タイトルと本文をコードブロックとして出力します。gh pr viewでブランチ上にオープン中の PR が確認できた場合は、この下書きでその PR のタイトルと本文を置き換えることになると伝えます。

完了条件は、タイトルと本文が出力され、記録コマンドを最後に実行したときに同じコミットと同じ 2 つのハッシュが出力され、git push、git commit、git rebase、gh pr create、gh pr edit、gh issue editのいずれも実行されていないことです。引き継ぎは 1 行で行います。何も変更されていないことと、次の手順はこの下書きから PR を開くよう prkit に依頼することを伝えます。

手順

1. 事前確認

何かを書く前に、ツールとブランチの準備ができていることを確認します。

gh --version        # gh installed?
gh auth status      # authenticated?
git branch --show-current

• ghが見つからない場合、または認証されていない場合は、その旨を伝え、https://cli.github.com／gh auth loginを案内します。回避策を試してはいけません。
• git branch --show-currentが空の場合は停止します。detached HEAD では、PR を開く前にブランチが必要です。ブランチの作成または切り替えを提案します。
• 現在のブランチがデフォルトブランチの場合は停止します。PR にはフィーチャーブランチが必要です。続行する前にgit switch -c <name>で作成することを提案し、ブランチ名はここで考案せず、ブランチ名の決定を担当する gitkit に確認します。issue に関連する作業にはissue-<n>-<slug>を使います。ベースブランチに直接適用した緊急修正にはhotfix-<slug>を使います。それ以外は、リポジトリの慣例またはユーザーが指定する名前をそのまま使います。

2. コンテキストを集める

gitkit からベースブランチを取得し、そのブランチで実際に何が変更されたかを読みます。その差分がタイトルと本文の素材になります。まずフェッチして、以下で参照するすべてのものが古いローカルコピーではなく、実際のリモート状態になるようにします。

git fetch origin                                         # refresh remote-tracking refs before anything else
git log origin/<base>..HEAD --format='%s%n%b'            # commits in this PR, with their bodies
git diff origin/<base>...HEAD --stat                     # files touched

コミットだけでは変更内容がわからない場合に限り、完全な差分（git diff origin/<base>...HEAD）を読みます。 このワークフローで作成されたブランチでは、たいていコミットだけでわかります。commitkit が変更内容そのものに基づいて各メッセージを作成しているため、ログは PR 本文に必要な内容を正確に要約しており、元の差分から改めて説明を作ると、何倍ものコストがかかるうえに、説明の質も下がります。コミットメッセージが簡素または一般的な場合（wip や fix typo のようなコミットが並ぶブランチ、またはこのワークフロー以外で行われた作業）、統計情報にコミットメッセージでは説明できないファイルが含まれる場合、あるいはテスト計画の具体的な詳細が必要な場合は、完全な差分を確認してください。どちらの場合も、ロックファイル、ビルド出力、ベンダーディレクトリは除外します。

ベース参照の解決は gitkit に任せます。 ここで基準を独自にたどり直すのではなく、gitkit にベースを尋ねてください。デフォルトブランチが develop や trunk のリポジトリも実在するため、間違えると空、または膨大な差分が気づかないうちに生成されます。gitkit が使えない場合は、gh repo view --json defaultBranchRef -q .defaultBranchRef.name が信頼できる代替手段です。回答を得られないときは推測せずに尋ねてください。現在のブランチを gitkit が返したベースと照合し、一致する場合は中止します。

スタック内のレイヤーでは、ベースはリポジトリのデフォルトではなく、その下のブランチです。 このブランチがスタック内のレイヤーである場合、gitkit は親ブランチを返します。その場合、以下の origin/<base> はすべてそのブランチを指します。これには2つの意味があります。差分がスタック全体ではなく、そのレイヤー固有の小さな変更になります。これがスタックを使う目的です。また、「現在のブランチとベースが一致する」という中止条件には該当しません。レイヤーのベースがそのレイヤー自身になることはないためです。ブランチがレイヤーかどうかは推測せず、gitkit に確認してください。gitkit が使えない場合は、既存の PR に対して gh pr view --json baseRefName を実行する方法が代替手段です。通常のブランチは、これまでどおり動作します。

ローカルの <base> は古い可能性があるため、最新のフェッチ済みリモート先端である origin/<base> と比較してください。そうしないと、タイトル、本文、ファイル一覧が、すでにマージ先ではなくなったコミットを基準に作成されます。

コミット、ブランチ名（例：issue-123-fix-login）、差分を使って、変更の範囲、種類、関連する課題番号（#123、fixes #123）を判断します。明らかに関連する課題があり、それを見つけられない場合は、番号を作り上げずに尋ねてください。

3. ベースブランチと同期する

プッシュする前に、ブランチが取得したばかりのベースの先端と同期していることを確認してください。古いブランチから PR を開くと、古いコードがマージされたり、GitHub に「このブランチには競合があります」というバナーが表示されたりします：

git rev-list --left-right --count origin/<base>...HEAD   # "<behind>\t<ahead>"; left > 0 means behind

• 遅れがゼロ：何もする必要はありません。ブランチをプッシュするに進んでください。
• 遅れている：origin/<base> をブランチに取り込む必要があります。同期ルールは gitkit が管理し、リベース（git rebase origin/<base>）で解決して、PR の差分をすっきりさせます。スタック内ではリベースが連鎖します（gh stack rebase --upstack）。このレイヤーをリプレイすると、その上のすべてのレイヤーも移動するためです。1 つのブランチだけをリベースして上位レイヤーが存在しなくなったコミットを指したままにならないよう、gitkit に任せてください。ブランチが公開済みかどうかにかかわらず、同期は OK なしで実行されます。gitkit が確認を求めるのは、競合への判断が必要な場合やリースが拒否された場合など、問題が起きたときだけです。gitkit がない場合は、リベースして --force-with-lease でプッシュし、そのような問題があれば中断してください。
• リベース時の競合：リベースが競合で停止した場合は、自分で解決してください。ユーザーが競合中のファイルを編集することはありません。競合しているファイルを一覧表示します（git diff --name-only --diff-filter=U）。競合解決のルールは gitkit が管理します。機械的に解決できるものは確認を求めずに書き込み、判断が必要な解決についてはユーザーに確認してから、選択された内容を書き込みます。gitkit がない場合、追加的な競合はそのまま解決し、どちらかの側のコードを削除する解決については事前に確認してください。その後、リベースを完了します（git rebase --continue）。作業ツリーがクリーンになり、同期が完了するまでは、プッシュも PR の作成も行わないでください。ユーザーが同期を断った場合、PR に競合が表示される可能性があると伝え、確認を得た場合に限り続行してください。

リベースが問題なく完了したら、差分を読み直さないでください。 リベースはコミットを新しいベースに適用し直すものであり、コミットの内容や動作を変えるものではありません。そのため、上で導き出したタイトルと本文は引き続きブランチの内容を正しく表しています。例外は、競合を解決したリベースです。そこでリプレイ中に実際の編集を行っており、解決後の結果は読んだ内容と実質的に異なるためです。ブランチ全体ではなく、競合解決で変更したファイルだけを読み直してください（git diff origin/<base>...HEAD -- <paths>）。

4. ブランチをプッシュする

まず、引き渡されたパスをコミットします。 呼び出し元から、ブランチに含めるファイルが渡されている場合（多くは qakit が作成し、引き継ぎ時に名前を示した（直接、または afkkit 経由で）手動 QA 計画 docs/qa/NNNN-qa-<slug>-YYYY-MM-DD.md）、そのファイルがまだ未コミットなら、残したままにしたり、別の何かに処理させたりせず、ここでコミットしてください。prkit はすでに git を扱うステップであり、パスも渡されているので、あらためて探す必要はありません：

git add -- <handed-in path> && \
git commit -m "docs(qa): add manual QA plan for <feature>" -- <handed-in path> && \
git show --name-only --format= HEAD

末尾のパス指定によって、そのパスだけがコミットされます。すでにステージされているほかのファイルはステージされたままになり、コミットには含まれません。パス指定でのコミットでは、そのパスの作業ツリー上のコピーが使われます。引き渡されたファイル全体を含めるため、ここではそれが正しい方法です。git show の行には、引き渡されたパスだけが正確に表示されていなければなりません。 出力にほかのパスが含まれている場合はコミットが誤っているため、プッシュする前に中断して報告してください。

対象は呼び出し元が名前を指定したパスだけです。これは作業ツリーをまとめてコミットしてよいという許可ではありません。誰も言及していない未コミットの作業には、引き続き注意事項のルールが適用されるため、その存在を伝えて提案し、黙ってコミットしないでください。

PR から指定できるようにするには、リモートブランチが存在していなければなりません：

git push -u origin HEAD

ブランチをリベースした後（ベースブランチと同期する）、リモートが通常のプッシュを拒否した場合は、git push --force-with-lease を使用してください（--force 単独は絶対に使用しないでください）。ここでは確認を求めないでください。gitkit の同期ルールでは、確認なしでリベースとリース付きプッシュを実行します。例外はリースが拒否された場合です。これはほかの誰かがプッシュしたことを意味するため、取得して相手のコミットを表示し、再試行する前に確認してください。

5. タイトルと本文を書く

• タイトル：1行で、リポジトリのコミットスタイルに合わせた命令形にします（git log に合わせます。多くの場合、feat(auth): add SSO login のような Conventional Commits 形式です）。末尾にピリオドは付けません。
• ホットフィックスブランチのタイトル：hotfix-<slug> という名前のブランチでは、種別に hotfix を使うため、タイトルは hotfix(scope): restore session cookie on refresh となります。バグの深刻さではなくブランチ名によって種別が決まるため、PR リストで両者を見比べやすくなります。PR タイトルのリントで種別が Conventional Commits のセットに照らして検証されるリポジトリでは、fix(scope): に戻し、その旨を一度だけ明記します。
• 本文：.github/pull_request_template.md（または PULL_REQUEST_TEMPLATE.md）がある場合は、それを読み、セクションとチェックボックスに正確に従って記入します。ない場合は、変更内容と理由をまとめた1段落の Summary、Changes の箇条書き、そして検証方法または実行する項目のチェックボックスを記載した Test plan を使います。該当する課題がある場合は、本文で参照します（Closes #123）。
• ユーザーに代わって行った決定を先に記載します。 呼び出し元から、ユーザーに確認せずに決めた前提や判断（無人実行の Assumptions、ビルドプロンプトの「代わりに行った決定」など）が渡された場合は、本文の最初のセクションで Summary より上に、またはテンプレートの最初のセクションの先頭に記載します。レビュアーがまず確認すべき内容であり、長い本文の末尾に埋もれやすい部分です。
• ホットフィックスの本文：ユーザーが目にした症状と、その引き金となった事象から始め、その後に修正内容を記載します。ロールバック用に、リバートコマンド（git revert <sha>）を示す Rollback 行を追加します。ホットフィックスは時間に追われてマージされるため、レビュアーがすぐに元に戻す方法を確認できる必要があります。テスト計画も記載し、検証できなかった内容は明確に述べます。
• スタックマップ：レイヤーブランチのみを対象にします。このレイヤーの位置、直下のブランチと PR、先にマージされるものを示す短いセクションを追加します。GitHub にはスタックのナビゲーションが表示されるため、2～3行に収めます。このセクションは、ナビゲーションが表示されない通知メールで PR を読む人が差分を理解できるようにするものです。この PR のターゲットは trunk ではなく直下のレイヤーであることを明記します。trunk をベースにしていると思い込んだレビュアーには、差分が未完成に見えてしまうためです。
• レイヤーブランチでは、Closes #123 は記載されていても、リターゲットされるまでは機能しません。 GitHub がクローズキーワードを有効にするのは、リポジトリの デフォルトブランチ をターゲットにする PR のみです。そのため、別のベースを指定している間はキーワードは単なるテキストとなり、課題へのリンクは登録されません。それでも Closes #123 は記載してください。直下のレイヤーがマージされて GitHub がこの PR を trunk にリターゲットすると、キーワードが自動的に有効になるためです。そのうえで、スタックマップにもこの仕組みを明記し、フォールバック情報が PR に残るようにします。このレイヤーがクローズする課題を示し、リターゲット後にリンクが登録されることを記載してください。サイドバーに課題へのリンクが表示されないと、レビュアーが参照漏れだと思い、重複した参照を追加してしまうためです。

6. 証明アーティファクトを埋め込む（存在する場合）

この手順は任意で、verifykit の証明バンドルが存在する場合にのみ実行します。verifykit は docs/verify/NNNN-verify-<slug>-YYYY-MM-DD/（slug は関連付けられた issue 番号、そうでなければ機能の slug。古いバンドルには NNNN- の連番はありません）に、すぐに埋め込める proof.md を含む日付付きバンドルを残します。該当するものが複数ある場合は、連番が最も大きいものを使い、連番がなければ作成日が最も新しいものを使います。それでも同率の場合は、どの実行を使うか確認してください。

選択したバンドルは、このブランチの HEAD を示している場合にのみ埋め込みます。 verifykit は、固定行 commit: <full sha>、dirty: <yes|no>、url:、および captured: を含むバンドルの notes.md を開きます。dirty: no と記録され、記録されたコミットが HEAD と同じか、ドキュメントのみの差分で HEAD と異なる場合、そのバンドルは最新です。

git diff --quiet <recorded commit> HEAD -- . ':!docs/qa' ':!docs/verify'   # exit 0 = no code change since the capture

ドキュメントの除外により、QA 計画のコミットとバンドル自体のコミットは、キャプチャ後に取り込めます。commit: 行がない、dirty: yes である、記録されたコミットを git diff で解決できない（rebase によって書き換えられた）、またはキャプチャ後にコードが変更されているバンドルは、古いものです。古いバンドルからは何も埋め込まず、引き継ぎ時にどのバンドルが古かったかとその理由を伝えてください。修正するには verifykit を再実行します。選択した最新の証明を、本文の Proof セクションに挿入します。画像は SHA 固定のインライン表示可能な raw URL とともに、非表示の refs/verify-assets/* ref にすでに公開されているため、ここでアップロードする作業はありません。フラグメントをそのまま埋め込んでください。バンドルがない場合は、この手順全体を省略し、これまでどおり PR を開きます。バンドルが存在しても、その proof.md がローカルパスを指している場合（非公開リポジトリなどで verifykit が公開できなかった場合）は、リンク切れを埋め込まず、手動添付用のローカルアーティファクトパスを列挙した短い注記を追加してください。

7. PR を作成または更新する

重複作成ではなく更新できるよう、まずこのブランチに既存の PR があるか確認します。

gh pr view --json url,state 2>/dev/null

• コマンドが state が OPEN の PR を返した場合：2 つ目を開くのではなく、gh pr edit --title "…" --body-file <file> で更新します。
• PR が存在しない場合、または返された PR がマージ済み／クローズ済みの場合：本文を一時ファイルに書き込み、新しい PR を作成します。チェックボックスを含む複数行の Markdown を --body で渡すと不安定ですが、--body-file は確実です。

gh pr create --base <base> --title "…" --body-file <bodyfile>
# add --draft when the user wants a draft, or the work is incomplete

本文ファイルにはシステムの一時ディレクトリ内のパスを使い、その後削除してください。

スタックの複数の階層を一度に開くには、コマンドを 1 つ実行するだけです。 gh stack submit は、各ブランチを正しい base に設定して、ブランチごとに PR を作成します。これは gh pr create を 1 つずつ実行する方法では手間がかかり、間違えやすい作業です。これは prkit が担うスタック機能の一部であり、gitkit は PR を開くことがないため、意図的に実行しません。

gh stack submit --auto        # a PR per layer, bases already correct

上記のとおり、送信前に各階層のタイトルと本文を記述してください。単一の階層を開く場合は、通常の gh pr create --base <parent> のままです。こちらのほうが簡単で、上の階層には影響しません。

階層ごとに、クローズリンクを確認して報告します。 階層 PR の作成または更新直後に、階層ごとに 1 回実行します。base がデフォルトブランチの PR では、実行を完全に省略してください。

gh api graphql -f query='{repository(owner:"<owner>",name:"<repo>"){pullRequest(number:<n>){closingIssuesReferences(first:5){nodes{number}}}}}'

• 階層で結果が空でも、それが想定どおりであり、失敗ではありません。 事実として報告し、解決までの流れも伝えてください。下の階層がマージされると、GitHub がこの PR のターゲットをデフォルトブランチに変更し、その時点で Closes #123 キーワードが登録されます。問題はなく、修正も不要です。
• 階層で空でない結果が返された場合、GitHub はすでに PR のターゲットを変更しています。 返された issue 番号を報告してください。
• リンクを強制するために PR のターゲットを trunk に変更しないでください。 スタックが依存する base が失われ、階層の小さな差分がチェーン全体の差分に変わってしまいます。デフォルト以外の base でリンクを登録する API はありません。gh issue develop と createLinkedBranch ミューテーションは、すでに存在するブランチをどちらも拒否します。下の階層がマージされるのを待つ方法が唯一の手段です。

8. 関連するイシューを進める

PR を開くと、関連するイシューは作業中からレビュー待ちに移ります。そのため、ライフサイクルラベルを in-progress → in-review に変更します（PR が開いたときに issuekit の sync モードが行うのと同じ遷移です）。この操作は、イシューを参照する PR がある場合、つまり［コンテキストの収集］(#2-gather-context) で見つかった #123 / Closes #123 がある場合にのみ行います。該当するものがなければ、この手順全体をスキップしてください。

• issuekit がインストールされている場合は、そちらを優先してください。 issuekit を呼び出してラベルを調整し、トラッカーのロジックを一元化します。そうでなければ、同等の gh 呼び出しを自分で実行します。

gh issue edit <n> --remove-label in-progress --add-label in-review

• 確認を求めずに実行してください。 すべての手順とすべての呼び出し元において、ラベルの書き込みは prkit のプレビュー規則の対象外です。ラベルは変更が容易で、見えるうえ、1 つのコマンドで元に戻せます。また、PR がレビューのために開かれているのに、イシューがまだ作業中であることを示しているほうが、誰も確認していないラベルより問題です。変更を提案してからではなく、引き継ぎ時にラベルの変更を報告してください。
• この遷移の対象となる開始状態は 2 つだけで、それ以外は対象外です。どちらの場合も置き換えます。 in-progress が付いたイシューは、上記のように変更します。ready が付いたイシューは、同じ形式の --remove-label ready --add-label in-review で変更し、イシューが未着手の状態で届いたことを引き継ぎ時に伝えます。PR は issuekit の start が実行されていない作業に対しても開けるため、ready は正当な開始状態です。人が作業を行っただけの場合は、これが通常のケースです。ready は start 後に残る状態ではありません。start は ready を in-progress に置き換えるため、PR を開いた時点でイシューに ready が付いたままなら、そのイシューには start が実行されていません。
• 別のライフサイクルラベルと並べて追加してはいけません。 issuekit のマップでは、ステータスラベルは常に 1 つだけです。そのため、ready, in-review と表示されるイシューは、より詳しい状態ではなく、壊れた行です。後続の各リーダーはライフサイクルラベルを単一の値として扱うため、2 つ目のラベルがあると、statuskit、sync、ready ガードの間で、同じイシューの状態に対する判断が食い違います。
• それ以外のライフサイクル状態は遷移ではなく、状態のずれです。 blocked、needs-planning、triage、needs-info、すでに in-review の場合、またはライフサイクルラベルがない場合は、そこで止めて何も変更しないでください。見つかった状態を報告します。人が対応している場合は確認し、無人実行の場合はエスカレーションしてください。誰も確認していないラベルを付けることは、ラベルを付けないことより問題です。
• prkit のその他の操作では、引き続きプレビューを行います。 対象外となるのはラベルの書き込みだけです。PR の作成と、引き渡されたパスのコミットには、［プレビューと認可］(#preview-and-authorization) が適用されます。
• リポジトリに in-review ラベルがない場合は、repokit を使うようユーザーに案内するか、gh label create in-review --color 5319E7 --description "a PR is open, awaiting review or merge" を提示し、不足を補うために独自の変更を加えないでください。この例外で省略されるのは確認の要求だけであり、プロビジョニングの確認ではありません。

9. この PR によってスタック可能になるもののブロックを解除する

PR を作成すると、この issue に依存して待機していた issue に取り組めるようになります。コードがまだマージされていなくても、ブランチ上に存在するためです。依存先は blocked → stacked に移行し、レビューが終わるまで待機する代わりに、このブランチから切ったレイヤーを土台にして作業できます。PR が、ほかの何かが依存している issue をクローズするときにのみ、これを実行します：

gh issue view <n> --json blocking                              # issues waiting on this one
gh issue view <dep> --json blockedBy,labels                    # every prerequisite of one dependent
gh pr list --state open --json number,headRefName,isDraft      # open PRs, read once
gh issue edit <dep> --remove-label blocked --add-label stacked

依存先が状態を切り替えるのは、すべての前提条件がそれを許可するときだけです。 blocked ラベルが付いた各依存先について、この issue だけでなく、すべての前提条件を確認します。この issue 以外の前提条件は、それがクローズ済みであるか、または未クローズかつドラフトではない PR が、このブランチにすでに含まれるブランチ上にある場合（git merge-base --is-ancestor origin/<head> HEAD）に、状態の切り替えを許可します。そうであれば、このブランチから切った 1 つのレイヤーにすべての前提条件が含まれるためです。前提条件の PR は、issue-<p>- で始まる head ブランチから特定します。gh 2.94.0 より前のバージョンでは、blockedBy の代わりに本文の Blocked by #N の行を確認します。

• 前提条件が未クローズで PR がない → 依存先は blocked のままにし、どの前提条件がブロックしているか報告します。
• 別の前提条件に独自の未クローズ PR があり、そのブランチがこのブランチに含まれていない → 依存先にはスタックの親が 2 つ必要になりますが、レイヤーに親は 1 つしかありません。依存先は blocked のままにし、両方の PR を報告します。どちらも選びません。

in-review への切り替えと同じラベル免除のもとで、確認を求めずに実行します。これらのラベルは、ユーザーが指定したものとは別の issue に付け替えるため、結果全体を 1 行で説明します：

PR #51 を作成しました → #52 と #53 は blocked → stacked に移行するため、どちらも今すぐ issue-51-oidc-provider から切ったレイヤー上で作業を開始できます。#49 にはまだ PR がないため、#54 は blocked のままです。

• リポジトリに stacked がない → repokit または gh label create stacked --color 006B75 --description "prerequisite is in flight with an open PR; workable now on a branch stacked on it" を案内し、この不足を回避して変更を加えないでください。
• 依存先がない、または PR がドラフトである → この手順を完全にスキップします。ドラフトは、作業の土台にする準備ができていません。

完了条件：この issue のすべての依存先が、すべての前提条件を確認したうえで stacked に移行するか、ブロックしている前提条件または競合するスタックの親を明示して blocked のままになっていること。

10. 引き継ぐ

この節は手順書の文体で記述します。1 文につき指示は 1 つ、能動態、現在形を使い、比喩は使いません。

変更点。 作成または更新した PR（タイトルと番号）、同期リベースを実行したかどうか、提出されたパスをコミットしたかどうか、証明のセクションを埋め込んだか、または古くなっているためバンドルをスキップしたか、関連する issue を in-review に切り替えたか、stacked に移行した依存先、およびその理由とともに blocked のままになった依存先を報告します。呼び出し元の承認によってプレビューに代わった場合は、呼び出し元と、承認の対象となった操作を明記します。

反映先。 PR の URL と、その PR が参照するブランチを示します。設定されている場合は CI が実行されることに触れます。レイヤー上にある場合は、対象のブランチを明記し、trunk ではないことを伝えます。さらに、レイヤー上にある場合はクローズリンクの確認結果も報告します。issue のリンクは現時点では機能せず、下位レイヤーがマージされて GitHub がこの PR の参照先を変更した後に登録されることを伝えます。

次の手順。 PR はレビュー待ちになったため、次の作業はレビュアー側に移ります。mergekit がインストールされている場合は start <n> で PR をワークツリーに取得し、ローカルでレビューと QA を行います。それ以外の場合は GitHub でレビューします。ただし、stacked に移行したばかりの依存先がそれより優先されます。レビュー中にユーザーがすぐに始められる作業だからです。優先度が最も高い依存先に対して issuekit start <n> を提案します。該当する場合は、次の軽微なフォローアップを最初に提案します。自動実行はしません。gh pr edit --add-reviewer <user>、--add-label <label>、またはドラフトの場合は gh pr ready を提案します。prkit の役割はここで終了です。

注意事項

• 明示的な依頼がない限り、PR を絶対にマージ、クローズ、または強制プッシュしないでください。PR の作成や編集は問題ありませんが、依頼がない限り gh pr merge は実行しないでください。
• コミットされていない変更は PR に含まれません。git status に、ユーザーが含めたいと思われるステージ済みまたは未ステージの作業が表示された場合、黙って残したり、確認せずにコミットしたりせず、まずそのことを伝えて、先にコミットするか尋ねてください。
• ブランチがベースブランチより先行していない（コミットがない）場合は、そこで終了し、PR を作成するものがないことを伝えてください。
• Proof の埋め込みは任意であり、単独で完結します。 prkit は verifykit の proof.md を読み取って埋め込むだけで、公開処理そのものは実行しません（公開処理は verifykit の担当で、独自の同梱スクリプトを使用します）。古いバンドルもバンドルがない場合と同じように扱い、引き継ぎメッセージでその旨を 1 行記載します。verifykit のバンドルがなければ Proof セクションは作成されず、prkit はこれまでどおり動作します。
• 関連付けられた Issue の状態変更は任意であり、プレビューのルールの対象外です。状態の切り替えは PR が Issue を参照している場合に限り行われ、issuekit がインストールされていれば優先して使用し、なければ通常の gh issue edit にフォールバックします。in-progress または ready の場合は確認なしで実行し、それ以外の状態では拒否します。PR が正当に開始される状態はこの 2 つだけだからです。この例外は手順に適用されるものであり、呼び出し元には適用されません。キーボードの前にいる人間でも、無人のオーケストレーターでも、動作はまったく同じで、prkit がこの範囲を広げることはありません。関連付けられた Issue がなければ、prkit はこれまでどおり PR を作成します。
• シェルや gh を利用できない場合（ブラウザベースのエージェントなど）、プッシュも gh の呼び出しもできません。その場合は、ユーザーが提示した差分を読み、完成した PR のタイトルと本文をコードブロックで出力してください。ユーザーがそれを GitHub の「New pull request」フォームに貼り付けられるようにします。