ship-it

Ship It

入力：PR 番号または URL。どちらも指定されていない場合は、現在のブランチの PR を使用します（引数なしの gh pr view で解決されます）。現在のブランチに PR がまだない場合は、プッシュして gh pr create で作成してから続行します（メンテナーブランチのみ）。目標：コードレビューで見つかった指摘をすべて修正し、CI をグリーンにした状態で PR をマージします。

0b. 変更に形がある場合は、説明に図を追加する

PR によって何かの「流れ」が変わる場合（リクエスト経路、バックグラウンドジョブ、機能の段階的な動作など）、差分よりも図のほうが早く伝わります。figure スキルを使い、JSON 仕様を書いてアニメーション SVG を 1 つレンダリングし、PR の説明の先頭に配置します。アップロードもクリックも不要で、説明内で再生されます。

ブランチ名ではなく、コミット SHA で参照してください。ブランチがマージ時に削除されると画像も表示されなくなるためです：https://raw.githubusercontent.com/<owner>/<repo>/<sha>/<path>.svg。SVG 自体が変更内容に含まれない場合は、リポジトリにコミットしないでください。レンダリングしたうえで、そこに置くべきものなら PR ブランチにのみコミットし、そうでなければ説明内の画像を、その画像を含むコミットに固定してください。

形のない修正（1 行のガード、依存関係の更新、誤字など）では省略してください。

0. ブロッカーのルール（すべての手順に適用）

ブロッカーとは、その修正が PR の目標に反する指摘です。つまり、コードレビューの原則に照らして、PR が実現しようとしていること自体が誤りである場合（例：PR の目的そのものが raw-SQL ハンドラー、新しいアドバイザリロック、タプルを返す API、SQL でアサートするテスト、銀行ごとのスコープの廃止である場合）、または修正するには機能を磨くのではなく、書き直すか削除する必要がある場合です。

ブロッカーがあったら、直ちに停止してください。 プッシュ、マージ、一部だけの修正はしないでください。PR が何を実現しようとしているのか、どの原則に反しているのか（code-review セクションを引用してください）、考えられる選択肢をユーザーに伝え、AskUserQuestion で確認を求めてください。明示的な回答があった場合にのみ再開してください。

それ以外（必須修正、推奨修正、軽微な指摘）はブロッカーではありません。すべて修正してください。

0c. 開始したものはすべて記録する（すべての手順に適用）

PR の検証のために起動したもの（API、ワーカー、コントロールプレーン、ドキュメントサーバー、pg0 インスタンスなど）は、最後の手順（手順 7）で必ず自分で停止してください。他の人が使っているものには触れないでください。他の Hindsight ワークツリー、サーバー、pytest の実行はこのマシンを共有しています。

• PID がわかる方法でバックグラウンドプロセスを起動し（run_in_background または cmd & echo $!）、それぞれを記録してください。使用したポートも記録してください。
• データベースが必要な場合は、新しく一意な pg0 インスタンス名を付けてください（例：HINDSIGHT_API_DATABASE_URL=pg0://ship-it-pr-<N>）。作成したことも記録してください。すでに存在するインスタンスを再利用する場合は（最初に pg0 list で確認してください）、共有であることを記録してください。
• pkill -f hindsight、pkill -f pytest、killall、または PID が自分のものか確認せずにポートを指定してプロセスを終了することは、絶対にしないでください。ほかのセッションに影響します。

1. PR を読み込む

PR のタイトル、本文、関連 Issue、差分を確認して、目標を把握してください。ブロッカーのルールはこれに依存します。CONFLICTING の場合は、先に origin/main をベースにリベースしてください。競合している PR では CI が一切実行されず、しかも通知されません。

作成者がメンテナーかどうか（リポジトリで write／maintain／admin 権限を持つか。例：nicoloboschi）を確認してください。

2. PR ブランチをチェックアウトする

現在のワークツリーで作業してください。新しいワークツリーを作成したり、クローンしたりしないでください。切り替える前に状態（現在のブランチ／コミットと、未コミットの変更）を記録し、手順 6 で元に戻せるようにしてください。未コミットの作業は、WIP コミットまたは一意のタグを付けたスタッシュで退避します（スタッシュスタックはワークツリー間で共有されるため、引数なしの git stash は絶対に使わないでください）。その後、PR のブランチをチェックアウトします（すでにそのブランチにいる場合は省略）。現在のブランチへの変更が入力された場合、未コミットの作業が明らかに PR の一部でなければ、ユーザーに確認してください。

• **メンテナーの PR：**修正はこのブランチ、つまり PR 自身のヘッドにコミットしてプッシュします。別途修正 PR を作成してはいけません。
• **外部（フォーク）の PR：**メンテナーが変更可能であれば、フォークのブランチにもプッシュします。変更できない場合は作業を中断し、ユーザーに今後の進め方（フォローアップ PR を作成するか、コントリビューターに依頼するか）を確認します。

プッシュする前には毎回、作成者がその間にプッシュしていないことを確認してください。新しいコミットがある場合は、そのコミットを読み、自分のコミットをそのヘッドにリベースします。読んでいない作業の上に強制プッシュしてはいけません。

3. レビュー

リポジトリのコードレビュー用スキルを絶対パス <repo>/.claude/skills/code-review/SKILL.md（<repo> = git rev-parse --show-toplevel）から読み、PR の変更（ベース = origin/<baseRefName>）に対して実行してください。すべての指摘事項（必須修正、修正推奨、軽微な指摘）を収集します。

各指摘を手順 0 に従って分類してください。阻害要因があれば作業を中断して確認してください。

4. すべての修正を適用する

• 必須修正だけでなく、すべての指摘を修正してください。PR の範囲内にとどめ、レビューで指摘されていない周辺コードのリファクタリングは行わないでください。
• ./scripts/hooks/lint.sh と、変更したコードを対象とするテストを実行してください（コマンドは CLAUDE.md を参照）。変更に必要であれば、OpenAPI／クライアント／docs-skill を再生成してください。
• 問題がなくなるまで繰り返します。 レビューは一度だけでは不十分です。修正によって新たな指摘が生じることがあり、レビューでは直近のパスで変更された内容しか確認されません。そのため、code-review の全項目で指摘（必須修正、修正推奨、軽微な指摘）が ゼロ になるまで、レビュー → すべてを修正 → 再レビューを繰り返してください。「軽微な指摘だけになった」時点で止めてはいけません。前回より指摘が減ったからといって止めてはいけません。実際に再実行していないレビューの結果をもって完了としてはいけません。早期終了できるのは阻害要因がある場合（手順 0）のみです。その場合は作業を中断して確認してください。
• フォローアップ作業は後回しにせず、ここで完了させてください。 PR を完成させるのに追加作業が必要な場合（レビューや自分が見つけた不足部分、ドキュメントページ、クライアントの再生成、テストなど）は、この ship-it で、このブランチ上で対応してください。今回の変更に属する作業に「フォローアップ PR」という選択肢はありません。本当に別の問題にあたる作業だけを issue にしてください（手順 7）。
• 修正内容を列挙したメッセージでコミットし、PR ブランチにプッシュしてください。

メンテナーの PR にはレビューコメントを投稿しないでください。指摘はチャットでの返信とコミットメッセージに記載します。外部 PR の場合は、プッシュした修正の概要を短くまとめたコメントを 1 件投稿してかまいません。

5. CI が成功するまで待つ

このリポジトリには必須のステータスチェックがありません。gh pr merge --auto は即時にマージし、gh pr checks はその時点までに登録されたチェックのみを報告するため、早い段階で実行された Strix チェックだけでも「成功」と表示されます。プッシュしたヘッド SHA に対する CI ワークフローの実行を確認してください。

SHA=$(gh pr view <N> --json headRefOid --jq .headRefOid)
gh run list --branch <headRefName> --workflow CI --json databaseId,status,conclusion,headSha \
  | jq --arg s "$SHA" 'map(select(.headSha==$s)) | .[0] // empty'

実行がまだない場合は、引き続き待ちます（実行がないまま約 15 分経過したら諦めて報告してください）。実行が completed になったら、ジョブごとに判定します（gh run view <id> --json jobs）。failure が 0 件であることを確認してください。PR が API／エンジンに関係する場合、test-api (1..3/3)、Core LLM tests、LLM 受け入れテストマトリックスは skipped ではなく success でなければなりません。これらのパス以外の変更では、変更フィルターによるスキップは正当です。oracle-client のジョブは不安定なことが知られており、cancelled になっても無視してください。

フォーク PR では、シークレットがないため test-api と LLM ジョブがスキップされます。 マージ前に上流ブランチでスイート全体を実行してください。main へのマージでは CI がまったく実行されません。

git push origin HEAD:ci/pr-<N>-verify
gh workflow run CI --ref ci/pr-<N>-verify   # exactly ONCE — a second dispatch cancels the first

PR／修正が原因の失敗であれば、修正してプッシュし、手順 5 に戻ってください。既知の不安定要因であれば（ジョブログを確認し、PR のコードに触れていないことを確かめてください）、実行が完了してから gh run rerun <id> --failed を 1 回実行します。 原因を特定できない理由で CI が引き続き失敗する場合は、作業を中断して報告してください。失敗した状態でマージしてはいけません。

6. ワークツリーを復元してからマージする

まず、ワークツリーを作業開始時の状態に戻します。元のブランチ／コミットに切り替え、退避した作業を再適用してください（WIP コミットを元に戻す／タグ付きのスタッシュを適用してから削除する）。ブロッカーや失敗により途中で終了する場合も、同様にしてください。先に復元しておけば、別のワークツリーが保持している可能性のある main を --delete-branch がチェックアウトしようとする事態も防げます。

gh pr merge <N> --squash --delete-branch
git push origin --delete ci/pr-<N>-verify   # if you created it

7. クリーンアップし、イシューを登録して報告する

ブロッカーや CI の失敗により途中で終了する場合も、これを実施してください。

自分が開始したものだけを停止してください。 ステップ 0c で記録した各 PID を終了します（kill <pid> を実行し、終了したことを確認してください。応答がない場合に限り kill -9 <pid> を実行します）。終了する前に、ps -p <pid> -o command= を実行し、まだ自分のプロセスであることを確認してください。pg0 の各インスタンスについて：

• この ship-it のために作成したもの → pg0 drop --name <name> -f（停止してデータを削除します）。
• 共有または既存のもの → 手を加えないでください。停止も削除もしないでください。

次に、自分が起動したものが残っていないことを確認します。使用した各ポートについて lsof -nP -iTCP:<port> -sTCP:LISTEN を実行してください。

実際のプロジェクトの問題はイシューに登録してください。 レビュー、テスト、または CI の待機中に、この PR の対象でもローカル環境の問題でもない問題に遭遇したかもしれません。たとえば、不安定なテスト、近くのコードのバグ、壊れたスクリプト、誤ったドキュメント、常に失敗する CI ジョブなどです。それぞれについて：

1. 重複を避けるため、まず検索します：gh issue list --state open --search "<keywords>"。
2. 該当するイシューがなければ、作成します：gh issue create --title ... --body ...。本文には、発生すること、再現方法（コマンドまたは手順）、期待される動作、コード内の該当箇所を記載します。簡潔にまとめてください。

ローカルの問題（自分の環境、ツールの不足、使用中のポート、古い .env）はイシューではありません。ユーザーの対応が必要な場合に限り、レポートで触れてください。

報告：

• PR のリンクと、マージを判断した CI の実行。
• 修正した問題（各 1 行）と、意図的に残したものがあればその理由。
• プロジェクトで見つかったイシュー — 作成した各イシュー（リンクと 1 行の説明）と、作成せずに既存のイシューを見つけた場合はそのイシューを、明確に区別して記載します。該当なしの場合は「なし」と記載してください。
• 停止・削除したものと、そのままにした共有 pg0 インスタンス。

gh pr edit に関する注意

このリポジトリでは失敗します。「Projects (classic)」の非推奨に関する GraphQL エラーで処理が中断され、何も変更されないままです。説明を編集するには、代わりに REST API を使用してください：

gh api -X PATCH repos/<owner>/<repo>/pulls/<N> -F [email protected]