converge-reviews

レビューの収束

有効なレビュー証拠は再利用し、変更されたカバレッジのみを無効にし、スコープが安定した後はレビューと修正を3ラウンド行って停止します。この上限こそがループを止める要因だと考えています。上限がなければ、各ラウンドで変更されていないコードについて新たな指摘が見つかり続け、レビューが終わりません。このスキルはレビュー状態を調整します。コードのレビューや修正の適用、外部イシューの作成は行いません。

1. レビューパケットを1つ受け取る

開始する前に、次のすべてが必要です。

• 元となる依頼またはチケット。
• レビューのベースと現在のヘッド、またはそれに相当するローカルのベースライン。
• 正確なスコープのパスと現在のコンテンツ／差分ハッシュ。
• レビュアーの一覧と観点。
• 安定したID、重大度、元のレビュアー、証拠、処置を含む指摘。
• 以前の収束台帳があればその内容。

呼び出し元がより詳細な指摘状態をすでに管理している場合は、指摘の本文をコピーせず、その成果物と指摘IDを参照します。PRの指摘ステータスについては、review-prの指摘状態ファイルを引き続き正式な情報源とします。

ゲート。 すべてのレビュアーが把握され、すべての指摘がスコープ、レビュアー、処置のいずれかに確実にひも付いていること。

2. スコープとカバレッジを特定する

安定したスコープとは、元となる依頼、レビューのベースライン、ソート済みパス、レビュアーの一覧、観点の正規ハッシュです。現在のコンテンツ／差分ハッシュを、レビュー済みスナップショットとして、また各カバレッジエントリーにも記録します。

収束状態は、呼び出し元が許可されたレビュー成果物の中で保持します。該当する成果物がなく、ワークフローでローカルのレビュー状態を管理する権限がある場合は、.claude/review-state/local-<scope-id>.ymlを使用し、そのディレクトリを無視対象にします。それ以外の場合は、ファイルを作成せずにブロックをインラインで出力します。保存するのは次の内容のみです。

convergence:
  scope_id: <stable ID>
  origin: <request or ticket>
  baseline: <base SHA or local baseline>
  snapshot: <head and content/diff hash>
  paths: [<reviewed paths>]
  reviewers: [<reviewer and lens>]
  round: <1..3>
  coverage: [<path or component, lens, reviewed hash, source round>]
  findings: [<finding ID, severity, normalized_status, disposition, source>]
  closure_check: not-needed | available | passed | failed
  result: continue | converged | blocked-at-cap | follow-up-proposed
  next_action: <exact next action>

同じスナップショットと契約であれば、ラウンドを増やさずに記録済みの結果を再利用します。記録済みの指摘に対する修正は、同じスコープを継続します。新しい要件、新しいレビュー観点、または実質的に新しいコンポーネントが加わった場合は、ラウンド1の子スコープを作成します。変更されていない親スコープのカバレッジ上の有効なブロッカーは引き継ぎ、上限に達した親スコープをリセットすることはできません。外観上の変更、生成物、無関係な変更によって、ラウンドをリセットしたりカバレッジを無効にしたりすることはありません。

レビュー済みのコンテンツ、パス、または観点が変更されたカバレッジのみを無効にします。対象のコンテンツが変更されるまでは、影響を受けないレビュアーの証拠を保持します。

ゲート。 各カバレッジエントリーが、ハッシュと契約が一致するものとして再利用されるか、再レビュー対象としてマークされていること。

3. ラウンドを調整する

安定したIDで指摘を統合します。元のレビュアーと処置の履歴を保持します。指摘のステータスは、引き続き呼び出し元が正式に管理します。呼び出し元のステータスには書き戻さず、調整時にnormalized_statusを導出します。active、regression、および呼び出し元固有の未解決状態はopenに、resolved、dismissed、wontfixはclosedに、follow-upは現在のスコープ外のdeferredに対応付けます。

予定されていたレビュアー全員から結果が返るか、明示的に対応不可と記録され、かつ呼び出し元がすべての指摘を調整した場合にのみ、1ラウンドとして数えます。結果を選ぶ前に、修正、却下、再発、そして新たに無効となったカバレッジを記録します。

ゲート。 台帳には、前回のラウンドから何が変わったのかが説明され、以前のすべての指摘またはカバレッジエントリーについて、有効なままか、変更されたか、終了したかの理由が示されていること。

4. 結果を 1 つ返す

• continue：完了したラウンドが 3 回未満で、次に行う修正または影響を受けるレビュー範囲が具体的に示されています。
• converged：未解決の Critical または Serious の指摘がなく、価値のある Moderate または Minor のフォローアップも残っておらず、必要な範囲がすべて最新の状態です。
• blocked-at-cap：第 3 ラウンドが完了しており、未解決の Critical または Serious の指摘が少なくとも 1 つ残っています。レビューの反復を停止し、ブロッカーを解消するための具体的な修正を示します。その修正後、該当するブロッカー ID と変更箇所のみを対象とした、解消確認を 1 回実施できます。この確認ではカバレッジと対応状況を更新しますが、新たな指摘を洗い出すことはなく、第 4 ラウンドとしても数えません。確認が失敗した場合は、明示的に新しい計画またはスコープが決定されるまで、ブロック状態を維持します。
• follow-up-proposed：未解決の Critical または Serious の指摘はなく、価値のある Moderate または Minor の指摘がフォローアップ作業として提案されています。ユーザーが外部への issue 作成を承認するまで、提案はローカルにとどめます。承認後、issue を作成する前に preflight-mutations を実行します。

第 3 ラウンドは、固定されたスコープに対する厳格な上限です。表現を変えた指摘、変更されていないカバレッジに対する別のレビュアーによるレビュー、または見た目だけの差分は、いずれも同じラウンドの繰り返しとみなし、第 4 ラウンドとはみなしません。ブロッカーの解消確認を 1 回行えるのは、名前を指定した修正を検証するためだけです。カバレッジを広げたり、新しい指摘を出したりすることはできません。

この契約を適用するのは呼び出し元です。呼び出し元は、continue の場合にのみ影響を受けるレビュー範囲を再実行し、converged の場合は処理を進め、blocked-at-cap の場合は停止し、follow-up-proposed の場合は提案と承認が必要な境界を提示します。上限に達した後、名前を指定したブロッカーを修正した場合、closure_check: available が 1 回限りの対象を絞った確認を指示するシグナルです。呼び出し元は対象のブロッカー ID と変更箇所のみを渡し、round は変更せず、新しい指摘の洗い出しは拒否します。

完了です。 台帳は最新で、変更のないエビデンスは再利用され、影響を受ける範囲が明示され、固定スコープのラウンド数は 3 回以下であり、呼び出し元には結果と次のアクションがそれぞれ 1 つだけ返されています。