設計: cross-review のラウンドを減らす（出し切り・前のラウンドからの変更・設計の観点・agy を既定から外す）（#542 #786）

issues/issue-542-786-design-decisions.md

@@ -0,0 +1,136 @@
+# #542 #786: cross-review のラウンドを減らす — 決定の記録
+
+設計は [issue-542-786-design.md](issue-542-786-design.md)、要求は [issue-542-786-requirements.md](issue-542-786-requirements.md) にある。決定の根拠にした実測は末尾の「判断に使った実測」にまとめた。
+
+## 決定の記録
+
+### 決定 1: cross-review の既定の母集合から agy を外し、claude / codex / kiro とホストにする
+
+agy が担当になると、テストを背景で起動して結果を残さずに終わることがある。起動し直しても残らなければ `final = error` で
+収束が止まる（#786）。実運用は既に毎回 `--exclude agy` を渡しており、既定を運用に合わせる。形は cross-refactoring の
+`DEFAULT_REFACTOR_RUNTIMES`（#664）にそろえる。「ホストを除いた既定の表」と、ホストを足す関数に分ける。ホストが agy の
+ときは母集合に入る（#892 の「ホストも輪番に入る」を保つ）。
+
+確定仕様 `cross-review-participants-and-seats.md` の「既定の母集合から agy を外さない。外すかは #786 が扱う」は、
+この決定で置き換わる。プロンプトの指示（決定 11）だけで直すことは採らなかった。担当が指示に従うかを確かめる手段が
+無く、従わなかったときの損失（収束の停止）が大きいためである。
+
+### 決定 2: 既定の母集合に無い者を外す指定は、止めずに無視して 1 行で知らせる
+
+今は母集合に無い者を `--exclude` に書くと `AssignmentError` で止まる。決定 1 の後は、今までの `--exclude agy` が
+すべて止まる。`CLAUDE.md` の cross-review 節も利用者の手元の手順も、`--exclude agy` を書いている。そのため止めずに無視する。
+綴りの誤りは今どおり引数の型が止める（終了コード 2。外したつもりの者が残る誤りは、名前の綴りでしか起きないため）。
+
+無視した名前を `excluded` に入れることは採らなかった。外した者と外す必要が無かった者が同じ記録になり、後から
+母集合を読み違える。
+
+判定は共通層（`assignment.resolve_participants`）に置くため、cross-refactoring の `--exclude agy` も同じく中断から
+無視へ変わる。Skill ごとに扱いを分けることは採らなかった。同じ引数の意味が Skill で変わる。
+
+### 決定 3: 1 ラウンド目から「見つけた指摘はすべて出す」を求める
+
+今のプロンプトには、見落としを残さないことを求める文が無い。`launch-reviewer.sh:166` の「全件」は、結果ファイルへ
+全件を書く指示である。1 ラウンド目で出し切らない指摘は、修正の後のラウンドで「新しい指摘」として数えられ、
+ラウンドを 1 つ増やす。#542 は、出力が増えて agy の無進捗の打ち切りに当たることを懸念した。決定 1 で agy が既定から
+外れるため、既定では当たらない。
+
+出す対象は今のまま「修正アクションのある指摘」に限る。nit や良い点まで網羅させることは採らなかった。出力が増えても
+ラウンドは減らない（nit は収束を止めない）。
+
+### 決定 4: 2 ラウンド目以降は、前のラウンドからの変わったファイルの一覧と差分を読むコマンドを渡し、差分の本文は渡さない
+
+後のラウンドの指摘の多くは前の修正が作った穴である（#542 の PR #539、devbase PR #163）。担当に「どこが変わったか」と
+「変わった節とそれを参照する節を先に見る」を渡す。1 つ後のラウンドで出るはずの穴を、同じラウンドで拾える。
+#542 の案のうち、出力を増やさずに効く「修正の後のラウンドへ観点を渡す」を採った。
+
+差分の本文を埋め込むことは採らなかった。設計 PR の修正は 1 ラウンドで数百行になり、2 席 × ラウンド数だけプロンプトが
+増える。担当は作業ツリーで `git diff` を実行できる。「指摘が採られたときに生じる経路も書け」を求めることも
+採らなかった。修正の形を担当が予測する必要があり、当たらないことがある（#542）。
+
+### 決定 5: 設計 PR 向けの観点テンプレートを足し、設計の成果物は増やさない
+
+設計 PR は今 `common` と `docs_only` にしか分類されない。設計の文書に特有の穴を見る観点が渡っていない。特有の穴は、
+3 文書の食い違い・状態の書き手の衝突・外部ツールの挙動の事実誤認の 3 つである。devbase PR #163 では事実誤認 1 件が 2 ラウンドを生んだ。振り返りは
+「経路の一覧を表にしておけば 1 巡で出し切れた」と書いている。観点はレビューの側に置く。
+
+`design` の成果物に「状態を書き換える経路の一覧」を足すことは採らなかった。対象になる設計を見分ける基準が要り、
+すべての設計の手間が増える。レビューの観点なら、状態を持たない設計では当たらずに済む。
+
+見分けはファイル名の規約（`issues/` 配下の `-requirements.md` / `-design.md` / `-design-decisions.md`）で行う。
+ブランチ名（`design/`）で見分けることは採らなかった。観点を組むのは PR の変更ファイルからであり、ブランチ名は
+状態ファイルの分類の入力に無い。
+
+### 決定 6: 既存コメントの控えをラウンドの開始ごとに取り直し、失敗しても止めない
+
+控えは `init` の 1 回しか取っていない。次のラウンドの担当は、同じ実行の前のラウンドの指摘と「対応しました」の返信を
+知らない。直った指摘の近くを別の言い方で再び指摘すると、振動の検知（同じ位置の重なり 0.5 以上）に当たる。
+#908 の実行 2 と #911 は振動で打ち切られた。
+
+取り直しに失敗しても止めないのは、前の控えでも今と同じ条件でレビューできるためである。3 つの取得元の一部だけが失敗したときも前の控えを残す。一部だけの控えで上書きすると、前のラウンドの指摘が重複の検出から消える。`init` の失敗は今どおり
+止める（控えが無いと重複の検出が働かない）。控えを圧縮することは範囲外にした。取り直しで増えるのは同じ実行の
+前のラウンドの行だけで、まず大きさを実装の PR で見る。
+
+### 決定 7: 収束の判定は変えない。新しい指摘が minor だけのラウンドは今も収束する
+
+証拠集約（#156、#732）は、再現していない minor を `insufficient_evidence`、再現した minor を `verified_non_blocking` に
+分け、どちらも新しい指摘として数えない（`_classify_finding`）。そのため新しい指摘が minor だけのラウンドは、今も
+`NEW_FINDINGS=0` で収束し、minor は最終スイープ（Step 7.5）が直す。ラウンドを延ばしているのは、前の修正が作った
+major の穴である。この変更は判定ではなく、担当が受け取るもの（決定 3・4・5・6）でその穴を早く出させる。
+
+`_is_pass`（COMMENT で critical と major が 0 件なら pass）を REQUEST_CHANGES にも広げることは採らなかった。
+新しさの判定が既に minor を数えないため、広げても収束するラウンドは増えない。
+
+### 決定 8: 母集合の全員が見るまで収束しない条件（#631）は採らない
+
+#631 は、1 ラウンドで収束すると母集合の 1 者が PR を一度も見ないことを問題にし、収束の条件へ網羅を足す提案である。
+ラウンドを増やす方向で、#542 と逆向きになる。費用は 1 ラウンドで収束した 37 件のうち 29 件にもう 1 ラウンドずつ
+（約 4 時間）である。
+
+#631 が根拠にした取りこぼし（devbase#171 と #191）は、round 1 が agy + kiro で codex が入らなかった形である。
+決定 1 の後の既定では、ホストが agy 以外なら round 1 は必ず codex + kiro になり、この形は起きない。見ないまま
+収束し得るのは round 1 に座らない 1 者（ホストが claude なら claude）だけになる。
+
+#631 の代案のうち「round 1 に codex を優先して入れる」は、決定 1 の固定順で満たされるため、`review_seats` を
+変えずに済む。#631 の課題は、この決定を記録して閉じる（閉じるのは実装の後）。
+
+### 決定 9: 結果を残さなかった担当を別のランタイムへ振り替えることは、この変更に含めない
+
+#786 の対処の候補のもう 1 つである。決定 1 で既定の担当から agy が外れ、残る担当の結果なしは手元の記録で
+#819 の codex（利用上限）の 2 件だけである。利用上限は振り替えても同じ実行の中で再び当たり得るため、振り替えの
+規則（いつ・誰へ・何回）は別に決める。置き場所の候補の #870（drive の pause と再開）は、本文でこれを扱っていない。
+範囲外の課題 #919 として起票した。
+
+### 決定 10: 振動の検知・`max_rounds`・起動し直しの規則は変えない
+
+振動の閾値（0.5）と近傍の幅（3 行）には実測の根拠がまだ無い（`state.py` のコメント）。この変更は振動の原因の
+1 つ（前のラウンドを知らない担当が同じ場所を再び指摘する）を決定 6 で減らす。閾値を同時に変えると、どちらが
+効いたかを分けられない。`max_rounds` を下げてラウンドを切ることは、減らしたのではなく打ち切っただけになるため
+採らなかった。
+
+### 決定 11: レビュー担当にはテストも背景の処理も起動させず、適用担当にはテストを前景で待たせる
+
+レビューの実行の確かめは、進行側の `verify-findings` が行う。担当は確かめる手順を `suggested_check` に書く。
+担当がテストを走らせても判定には使われず、背景で起動すると結果を書かずに終わる経路になる（#786）。cross-refactoring の
+適用担当は、ラウンドごとに 1 回テストを実行する設計である（`apply.md` の「適用ラウンドの単位で 1 回」）。そのため
+実行を禁じず、前景で終わるまで待つことを求める。
+
+cross-refactoring の既定の参加者からは、#664 で agy を外してある。この指示が効くのは、`--include agy` で戻したときと、
+他の担当が同じ形で終わるときである。
+
+### 決定 12: `--only` で名指しした者は、既定の母集合に無くても参加者にする
+
+決定 1 の後、`--only agy` は「参加者のいずれかを指定してください」で止まるようになる。`--only` は 1 者を名指しする
+指定で、名指しした時点で利用者の意図は明らかである。そのため母集合に無い者でも、足す者として扱う。
+`--exclude` にも書いた名前は、今どおり矛盾として止める。止めて `--include agy` を求めることは採らなかった。
+同じ意図を 2 つの引数で書かせることになる。
+
+## 判断に使った実測
+
+| 対象 | 値 | 出所 |
+| --- | --- | --- |
+| cross-review 88 件のラウンド数（2026-09-01〜09-15） | 1 ラウンド 42%（中央値 8.1 分）/ 2 ラウンド 28%（16.2 分）/ 3 以上 30%（50.2 分、時間の 70%） | #542（集計の方法は #662） |
+| PR #539 の 10 巡の指摘 | 15 → 6 → 2 → 2 → 5 → 2 → 0 → 2 → 3 → 0。3 巡目以降の指摘は、分類した分がすべて前の修正が作った穴 | #542 |
+| 直近の設計 PR の実行ごとの最大ラウンド | #908: 8 / 8 / 5、#843: 7（振動で打ち切り）、#911: 3（振動で打ち切り）、#794: 8、#890: 5 / 3、#902: 3 | 状態ファイルとレビューの見出し |
+| 2 ラウンド目以降のプロンプト | 前のラウンドからの変更を渡していない。既存コメントの控えは `init` の時点のもので、#908 の実行 3 の round 5 のプロンプトに同じ実行の round 1〜4 の指摘が入っていない（プロンプト 61,962 バイトのうち控え 54,957 バイト） | `launch-reviewer.sh` と退避された作業ツリー |
+| 担当の運用 | 2026-09-22 の #803 以降、ほぼすべての実行が `--exclude agy` で codex + kiro の 2 者 | 状態ファイルの `participants` |
+| agy の結果なし | devbase v3.6.0 で 8 回（cross-review 5・cross-refactoring 3）。ai-plugins の手元の記録では NO_RESULT 1 件（#794）、STALLED 0 件 | #786、`monitor-outcomes.jsonl` |