codex-pr-review

Codex PR レビュー

オーナーシップ

オーケストレーター：

• ウォッチャーの実行、PR 本文のステータス解釈、修正担当への委任、worktree の規律、最終報告を担当します。
• PR のレビューと修正は専用の git worktree で行います。handle-tickets などから呼び出し元が提供した worktree がある場合は、PR ブランチと現在のヘッドを確認してから再利用します。ない場合は、編集やチェックを始める前に作成するか、既存のものを確認します。
• ヘッド SHA、ファイル、テーマ、サブシステム、受理／却下した指摘、プッシュした修正、チェックをラウンドごとに記録し、パターンの繰り返しを検出します。
• 修正担当に渡す情報として、PR URL／番号、ブランチ、worktree、現在の headRefOid、判明している場合は現在のレビュサイクルの鮮度境界、ウォッチャーが最新の feedbackItems と activeCodexThreads、解析済みの優先度、ウォッチャースナップショットの件数、必要に応じて P0／P1 の安全性チェック結果、Review Discipline のスコープ基準、繰り返しのパターンに関する過去の Codex コメント、過去の code-review または review-fix の結果、チェック、プッシュ方針を渡します。指摘を分類するのに十分な仕様の背景を含めます。指摘が特に必要としている場合を除き、新たな包括的 code-review は依頼しません。
• gh pr view、リモートのヘッド SHA、共有 worktree の場合はローカルの状態、判定／リアクションの結果を確認して、修正担当への引き継ぎを検証します。委任したコメントの変更を分析、修正、コミット、プッシュしてはいけません。
• 修正担当のサブエージェントを起動できない場合は、Review Discipline と Severity Handling に従って親側で有効なコメントに対応し、チェックを実行して、代替対応を報告します。

修正担当のサブエージェント：

• 委任せず、渡された作業を直接完了します。PR の状態を更新し、提供された各項目／スレッドの全文を読み、Review Discipline と Severity Handling を適用して、スコープ内の有効なブロッカーを修正し、チェックを実行して、コミットおよびプッシュします。
• 繰り返しのパターンに関する情報を渡された場合は、個別の症状をさらに修正する前に、共通する根本原因を調査します。
• PR URL、開始／終了 SHA、判定、リアクション、修正しない理由、該当する場合は根本原因に関するメモ、ファイル、チェック、コミット、プッシュ結果、プッシュされたリモートのヘッドを確認した直後に記録した UTC タイムスタンプ、ブロッカーを報告します。

Review Discipline

• Codex のフィードバックは助言として扱います。すべての指摘を実際のコードパス、関連ファイル、および外部動作が関わる場合は依存関係のドキュメント／ソース／型と照合して検証します。
• 引き継ぎや修正の前に、スコープの基準を固定します。PR の意図、対象ブランチ／ベース、現在の headRefOid、オーナーの境界、宣言されたレビューユニット／トポロジー、関連するドキュメント／チケット、変更ファイル、テスト以外の LOC を確認します。
• 現在の差分で追加または強化されたドキュメントによって、タスクの契約範囲を広げてはいけません。差分で導入された、より強い約束だけに依存する指摘の場合は、実装の範囲を広げるのではなく、ドキュメントの範囲を狭めます。
• 作業に着手する前に、現在のヘッドに関する各指摘を分類します。
  • in-scope blocker：現在の差分で導入され、同じオーナー境界に影響し、タスクの契約を変えずに修正できる指摘。
  • follow-up：隣接するバグの種類、関連する別の領域、クリーンアップ、またはより広範な強化の対象。
  • blocked：新たなプロトコル／設定／ストレージ／パブリック API の契約、別のオーナー境界、リリースプロセスの変更、またはプロダクト上の判断が必要な指摘。
• 非現実的なエッジケース、推測に基づくリスク、広範な書き換え、過度に複雑な修正は却下します。適切なオーナー境界における小さな修正を優先し、バグの種類を明確に改善できる場合に限ってリファクタリングします。
• 受理した指摘からバグの種類や繰り返しのパターンが判明した場合は、現在の PR のスコープ内で関連する箇所を調べ、実用的であればスコープ内のバグをまとめて修正します。変更対象の領域、オーナー境界、明確なフォローアップの範囲を越えてはいけません。
• セキュリティに関する指摘は、変更によって具体的かつ対処可能なリスクが生じる場合、または重要な安全性チェックが削除される場合に限って報告します。
• スコープの分類または対象を絞った検証が未解決のまま、レビューを契機とした修正コミットを積み重ねたり、プッシュしたりしてはいけません。

リリース凍結

• リリース、ベータ、安定版、ホットフィックス、署名、公証、appcast、パッケージ公開、リリースチェックに関する作業では、リリースを妨げる問題、リリースインフラの障害、正確なバックポート、インストール／アップグレードの不具合、データ損失、クラッシュ、または具体的なセキュリティ上の露出のみを修正してください。
• ブロッカーではない Codex の指摘は、リリースブランチの作業範囲を広げる理由ではなく、main でのフォローアップとして扱ってください。

重大度の取り扱い

• Codex の P0／P1 は、必ず最優先で対応してください。現在のヘッドに関する各 P0／P1 について、最終的な処置を決定するまでは、最終的な結果の報告、根本原因調査の引き継ぎ、新たなレビュー依頼を行ってはいけません。古い、すでに修正済み、無効、または対象範囲外の場合は、現在のヘッドに照らして根拠を示し、修正しない理由と妥当性リアクションを記録してください。
• ウォッチャーの出力が制限または切り捨てられている場合、あるいは現在のヘッドに関する未対応のフィードバックが隠れている可能性がある場合は、修正作業がないと判断する前に、対象を絞った P0／P1 の安全確認を実行してください。gh／GraphQL または --full-history による診断を1回実行して、Codex の PR コメント、レビュー本文、レビューコメント、未解決かつ古くないスレッドを確認し、現在のヘッドに関する P0／P1 があれば通常どおり処理してください。
• 表面化した各項目／スレッドについて、最終的な処置を決定してください。処置は、修正してコミット済み、根拠を示して却下、古い／すでに修正済みであることを証明、具体的な修正しない理由を示したフォローアップ／対象範囲外／延期、または継続用パケットによるブロックのいずれかです。
• THUMBS_UP または THUMBS_DOWN は、処置を決定した後にのみ適用してください。P1 ではない同じ指摘が繰り返される場合は、リアクションの前に根本原因／テーマごとにまとめ、修正担当者が一貫した修正を一度に行えるようにしてください。
• THUMBS_DOWN を付ける場合は必ず、指摘に言及し、その処置と根拠を要約した簡潔な GitHub の返信またはコメントを添えてください。
• ウォッチャーが新たに取得した feedbackItems と activeCodexThreads は、ステータスではなく指摘として扱ってください。ウォッチャーの鮮度フィルター（codex_feedback_changed、現在のヘッドの reviewedCommitOid、既存の妥当性リアクションがないこと）を維持してください。以前のヘッドに対する古いコメントは、新しい指摘として表面化した場合、繰り返しパターンの調査に関連する場合、対象を絞った P0／P1 の安全確認で見つかった場合、またはレビュー記録の完了処理の時点でも現在のヘッドで有効な場合を除き、引き継いではいけません。

レビュー記録の完了処理

期待されるヘッドに対する検証成功を報告する前に、未解決の Codex 作成レビュー スレッドを対象に、範囲を限定した完了確認を1回実行してください。解決済みの履歴を再確認するのではなく、未解決のスレッドを取得してください。THUMBS_UP を含め、ウォッチャーの結果が成功していても、この完了確認が終わるまでは暫定的なものです。完了確認の前に、PR が承認済み、PASS、またはマージ可能であると説明してはいけません。

• スレッドの指摘が現在のヘッドに当てはまらない場合は、古い／すでに修正済みの処置を記録し、妥当性リアクションを適用し、必要に応じて返信したうえで、指摘を再度持ち出さずに解決してください。
• 欠陥が現在のヘッドにも残っている場合は、レビュー規律と重大度の取り扱いに従って処理してください。修正担当者のコミットによって期待されるヘッドが変わった場合は、ホスト上の検証を最初からやり直してから、次の完了確認を実行してください。
• Codex が作成したレビュー スレッドが未解決のまま成功を報告してはいけません。完了した確認は、検証済みの正確なヘッドに紐付けられます。

繰り返し発生するパターン

• 同じ PR の意図に対する Codex のラウンドが 2 回以上、同じファイル、テーマ、サブシステム、不変条件、またはソースコード上の判断に集中している場合は、繰り返し発生するパターンを検出します。これは終端状態ではありません。
• コメントが集中していない場合でも、同じ PR の意図に対するフィードバックラウンドが 3 回完了するごとに、根本原因の調査も実施します。監視側で最新と確認されたフィードバックバッチに最終処置が確定した時点で 1 ラウンドとして数えます。ステータスのみのポーリングや古いフィードバック、重複したフィードバックは数えません。
• いずれかのトリガーが発生したら、コメントごとのループを止め、根本原因をまとめた資料を作成します。これには、複数のヘッドにわたる関連する Codex コメント、採用／却下の処置、現在のコードパス、関連チケット／PRD の意図、追加済みのテスト、繰り返し失敗する原因と疑われる不変条件を含めます。
• コメントが、誤った方向性に起因する症状かどうかを調査します。根本原因が現在のチケット／PRD の契約とオーナーの境界内にある場合は、同じ PR 内で一貫性のある修正を優先します。
• 根本原因の調査中は、意図された動作を証明できるだけの十分な深さで、周辺の実装とテストを読み込みます。実施可能な場合は、次の Codex レビューを依頼する前に、不変条件に焦点を当てたテストを追加または更新します。
• 一貫性のある修正が PR の契約範囲外である場合、オーナーの境界をまたぐ場合、プロダクト上の判断が必要な場合、または新たな公開／プロトコル／ストレージ契約が必要な場合は、対象を絞った最小限の質問と根拠を示して blocked として停止します。その結果を redesign や split と言い換えてはいけません。

ウォッチャーとステータス

• ウォッチャーの実行、レビュー依頼コメント、フィードバックへのリアクションまたは返信、修正担当の割り当て、台帳のクローズを行う前に、必ず PR Head で isDraft を確認してください。ドラフト PR ではホスト型レビューによる副作用は発生させず、呼び出し元に制御を戻します。ホスト型レビューは、呼び出し元が PR を再度有効化した後にのみ再開します。
• ウォッチャーはフォアグラウンドで実行してください：node <skill-dir>/scripts/watch-codex-pr.mjs。完了を起床シグナルとして扱い、gh で再度 PR を確認してください。プロセスに実際のスレッド起床機構が接続されている場合にのみ、バックグラウンドで実行します。
• ウォッチャーのデフォルトの動作：120 秒ごとに最大 30 分間ポーリングし、残り予算が少ない場合は GitHub GraphQL のクォータ回復を待ち、PR メタデータと最近の PR 本文のリアクションのみを含む最小限の GraphQL ステータス確認を使用し、フィードバックスナップショットを最近のコメント／レビュー／スレッドに限定します（--feedback-limit のデフォルトは 50）。現在の head に対するフィードバックが存在する場合は、各間隔で限定されたフィードバックスナップショットを更新し、フィードバックの判定とスレッドの解決を速やかに検出します。
• ウォッチャーのフィードバックスナップショットでは、ウォッチャーが新たに検出した項目のみを feedbackItems と activeCodexThreads に表示します。これには解析済みの priority 値と、PR 本文のリアクションなしで現れた現在の head に対する Codex のフィードバックが含まれます。マーカーのないフィードバックも対応が必要ですが、現在の head の完了を証明するものではありません。合計数と古い項目の数は診断用です。タイムアウトを報告する前に、ウォッチャーは最後に 1 回、範囲を限定したスナップショットを実行します。新しい現在の head に対するフィードバックが存在する場合は、代わりに codex_feedback_changed を出力します。
• codex_approved と codex_review_complete は、検証成功として扱ってください。後者は、現在の head に対する指摘が 1 件以上あり、そのすべてに有効性の判定があり、現在の head に対する Codex のアクティブなスレッドが残っておらず、関連するステータスとフィードバックの証拠が切り捨てられていない場合に出力されます。新しい PR 本文の THUMBS_UP は、statusFreshAfter 以降に発生し、headRefOid が expectedHeadRefOid と一致し続けている場合、期待される head に対する承認として扱ってください。別途 PullRequestReview を要求しないでください。
• ワークフローが管理する push の後、リモートの完全な head SHA を確認し、その後で現在の UTC タイムスタンプを取得してください。--expected-head <sha> --status-fresh-after <timestamp> を付けてウォッチャーを実行し、再開時にも両方の値を引き継いでください。これにより、Codex が新しいレビューサイクルの EYES、THUMBS_UP、または現在の head に対するフィードバックを公開するまで、以前の head の古い THUMBS_UP は無視されます。
• --full-history は、手動診断、対象を絞った P0/P1 安全確認、または証拠の切り捨てによって完了が隠れている可能性がある場合のウォッチャーによる 1 回限りの対象を絞った確認にのみ使用してください。このオプションは PR のすべてのコメント、レビュー、スレッド、リアクションをページングするため、活発な PR では GraphQL クォータを使い切る可能性があります。
• 現在のレビューサイクルにおける Codex の新しい PR 本文リアクションを、そのステータスとして扱ってください。EYES はレビュー中、THUMBS_UP は承認済み、リアクションはないが現在の head に対する Codex のフィードバックがある場合はレビューでコメントが返された状態、リアクションも現在の head に対する Codex のフィードバックもない場合は Codex が PR をレビューしていない状態を意味します。フィードバックに対するリアクションは、有効性を示すマーカーにすぎません。

ループ

1. gh pr view --json number,url,headRefName,headRefOid,baseRefName,state,isDraft,mergeStateStatus,reactionGroups を使って PR を特定します。
2. 編集やチェックを始める前に、PR ブランチ用の専用ワークツリーを作成または確認します。呼び出し元からワークツリーが提供されている場合は、それを再利用します。すべての修正担当者向けパケットと最終報告に、ワークツリーと現在の headRefOid を記録します。
3. Codex を待つ前にマージコンフリクトを解決します。コミットしてプッシュし、ループを再開します。
4. 呼び出し元が、期待される HEAD に変更がないことを前提に、より新しいローカルチェックポイントを明示的に指定した場合は、チェックポイント更新サイクルを 1 回実行します。現在の UTC タイムスタンプを新しいレビューサイクルの鮮度境界として記録し、その直後に PR コメントを @codex review と完全一致する内容で 1 件だけ追加してから、期待される HEAD と境界を指定して通常のウォッチャーループを実行します。ウォッチャーは、その境界とリクエストのタイムスタンプを組み合わせます。この許可は、そのリクエストを 1 件投稿することで一度だけ使用します。通常の修正担当者によるプッシュや通常の再開では、この分岐に入りません。
5. ウォッチャーが検証成功を報告した場合は、gh pr view --json headRefOid,state,isDraft,statusCheckRollup で PR を再確認し、その headRefOid がウォッチャーの current.headRefOid と一致し、isDraft が false であることを確認します。HEAD が異なる場合は、新しい HEAD とそのレビューサイクル境界を起点に再開します。PR がドラフトの場合は、再有効化のために呼び出し元へ返します。その HEAD に対して Review Ledger Closure を実行します。クロージャーによって HEAD が変わった場合は、ホスト上の検証を再開します。変わらなかった場合は、headRefOid,isDraft を再確認し、headRefOid が引き続き期待される HEAD と一致し、isDraft が引き続き false であることを確認してから、git fetch --all --prune --tags を実行し、検証モードを報告します。表現を整えるため、または別の意見を得るために、追加のレビューを依頼してはいけません。
6. Codex がレビュー中の場合は、ウォッチャーを実行して PR を再確認します。ウォッチャーの出力に現在の HEAD に対する feedbackItems または activeCodexThreads が含まれている場合は、Review Discipline と Severity Handling に従って対応します。現在のステータスが引き続きレビュー中のままウォッチャーがタイムアウトした場合は、停止して Codex が応答停止またはタイムアウトしたと報告します。新しい入力がない限り、同じ HEAD に対してウォッチャーを再実行してはいけません。
7. PR 本文にステータスがない場合は、サイレントスタート確認として --timeout 300 を指定してウォッチャーを実行し、PR を再確認します。Codex にレビューを依頼するか判断する前に、現在の HEAD に対するフィードバックがあれば対応します。
8. 5 分間のサイレントスタート確認で PR 本文にステータスがなく、Codex による現在の HEAD に対するトップレベルの PR コメント、レビュー、インラインコメント、レビューコメントスレッドもない場合は、PR コメントを @codex review と完全一致する内容で 1 件追加し、その後ウォッチャーを再実行します。このサイクルがタイムアウトした場合は、Codex を利用不可、無効、または応答停止と報告します。
9. 新しいフィードバックへの対応ごとに、新しい修正担当サブエージェントを 1 つ起動します。複数の新しい修正担当者を使うのは、ワークツリーが分離されている場合、または修正が明確に重複せず、プッシュ順序が明示されている場合に限ります。オーケストレーターは修正を委任します。修正担当者を起動できない場合に限り、親エージェントが修正します。
10. 修正担当者が修正をプッシュするか、コード変更は不要と報告した後、スコープの基準に照らしてそのラウンドを分類し、ラウンド履歴を更新します。同じファイル、テーマ、サブシステム、または不変条件に関するフィードバックが繰り返される場合、次の限定的な修正担当者による対応またはレビュー依頼の前に Repeated Patterns を実行します。また、フィードバック対応のラウンドが完了するたびに 3 ラウンドごとにも実行します。根本原因への修正をプッシュした場合は、現在の PR HEAD を起点に再開し、Codex が検証できるようにします。
11. Codex による検証が成功するか、タイムアウトするか、GitHub 側の制約でブロックされるか、根本原因を調査した後も実際のブロッカーが残っている場合に限り、停止します。

ガードレール

• サイレントな5分間の開始確認後に行う単一の @codex review フォールバック、変更されていない想定ヘッド上に明示的に新しいローカルチェックポイントがある場合に呼び出し元が承認したチェックポイント更新リクエスト1件、またはユーザーから明示的に依頼された場合を除き、Codex にレビューを依頼したり、レビューを要求したりしないでください。
• 通常のレビューサイクルでは --full-history を実行しないでください。範囲を限定したスナップショットが途中で切り詰められた場合は、P0/P1 の安全性チェックが必要な場合、またはユーザーから古い Codex の履歴を監査するよう明示的に依頼された場合を除き、新たに範囲を限定したフィードバックを取得して続行してください。
• 対象範囲内のブロッカーに必要なファイルのみ変更してください。
• リポジトリのワークフローで明示的に必要とされていない限り、強制プッシュしないでください。
• Codex が同じテーマに関する2回目の指摘を見つけたというだけで、作業を止めないでください。根本にある方針を調査してください。

ターミナルでの報告

• すべての最終結果について、PR URL、Codex による検証の有無、検証に成功した場合は検証モード、merge_ready、想定および観測された PR ヘッド SHA、判明している場合はレビューサイクルの鮮度境界、現在の PR の状態、ローカルの git データを取得したかどうか、プッシュしたコミット、P0/P1 の安全性チェックを実施したかどうか、繰り返しパターンの調査を実施したかどうか、レビュー台帳のクローズ結果と成功した場合のヘッド、そして対応した Codex コメントを優先度と処置別（修正／受け入れ、却下、古い／修正済み、フォローアップ、ブロック、延期）に、妥当性に対する反応と修正しない理由を添えて記載してください。
• 検証に成功していない最終結果では、merge_ready: false、PR URL、ブランチ、ベース、想定および観測された PR ヘッド SHA、判明している場合はレビューサイクルの鮮度境界、関連するチケットまたは PRD の URL、現在の PR の状態、チェックとマージ可能性、Codex の処置、ファイル／テーマ／コメントごとにまとめた根拠、P0/P1 の処置、該当する場合は根本原因の調査メモ、プッシュしたコミット、次のアクションと担当者を含む継続用パケットを記載してください。
• blocked の場合は、次の最小限のアクションを選んでください。プロダクト／スコープに関する質問への回答、契約変更の承認、適切な担当者の境界への作業移管、GitHub／チェック／マージのブロッカーの修正、または Codex／GitHub の利用再開を待つことです。作業が引き続き対象範囲内であれば、延期せず同じ PR で続行してください。