新規 gate の段階導入プロトコル

対象 Issue: #1557（親 #1556）

新しい gate や hook を追加するときの導入手順を規範として固定する。新規 gate をいきなり必須化すると、誤検知で workflow 全体が止まる。特に閾値を持つ検出系（jscpd など）は較正前の必須化が review loop を壊す。この文書は導入 mode を report_only と required の 2 値で定義し、report_only の計測を経てから required へ昇格する手順と、その昇格条件の書き方を定める。

この文書は手順の規範であり、既存 gate の挙動は変えない。新規 gate を追加する Issue / PR は、ここで定義する mode と昇格条件の書き方に沿って導入方針を記載する。

導入 mode

新規 gate は必ず次のどちらかの mode で導入する。

• report_only（観測のみ、停止しない）: gate は判定を実行し、結果を観測 artifact として残すが、required_action を追加せず、workflow の完了判定も止めない。検出しても workflow は通常どおり次工程へ進む。誤検知や閾値の妥当性を、実運用の workflow を止めずに計測するための mode。
• required（失敗で停止する）: gate が失敗したときに required_action を追加し、完了判定を拒否する。required_action が残る限り、その workflow は successful completion として扱われない。較正済みで誤検知が許容範囲に収まった gate だけをこの mode にする。

新規 gate は原則 report_only から始め、後述の昇格条件を満たしたときに required へ昇格する。

動作差

report_only は「観測 artifact は残すが required_action を足さず completion も止めない」、required は「失敗時に required_action を足して completion 判定を拒否する」という違いだけを持つ。判定ロジック自体は同じで、失敗の扱いが report_only と required で分かれる。

report_only の gate が required_action を残して停止することは、mode 定義に反する動作なので許さない。「report-only なのに required_action が残って停止する」状態は mode 実装のバグとして扱う。

report_only での計測

required へ昇格する前に、report_only mode で運用しながら次を計測して観測 artifact に残す。

• gate を通した対象数（実行回数）
• 検出（失敗判定）が出た件数
• そのうち誤検知だった件数（実装者・レビュアーが「この検出は妥当でない」と判断した件数）
• 閾値を持つ gate は、閾値を変えたときに検出件数と誤検知件数がどう動くか

この計測は較正のための入力であり、report_only の時点では workflow を止めないので、計測期間中に workflow の運用が阻害されない。

required への昇格条件の書き方

新規 gate の昇格条件は、次を満たす形で書く。曖昧な「十分に安定したら」ではなく、artifact から機械的または明示的に確認できる条件にする。

• 計測範囲: report_only で計測した対象数の下限（例: 直近の PR / workflow 実行を N 件以上）
• 誤検知の上限: 昇格を許す誤検知率または誤検知件数の上限（閾値を持つ gate は採用する閾値も明記する）
• 判断主体: 昇格を承認する主体（実装者の自己申告だけにしない。親 Issue #1556 の判定分離の方針に沿い、計測 artifact を根拠にした承認を求める）
• 昇格後の後退条件: 昇格後に誤検知が想定を超えた場合に report_only へ戻す条件

閾値を持つ検出系（jscpd など）は、較正前に required にしない。report_only の計測で閾値を確定し、その閾値と誤検知の上限を昇格条件に明記してから required へ昇格する。

Issue / PR への記載

新規 gate を追加する Issue / PR は、次を本文に記載する。

• 導入時の mode（report_only から始めるのが原則）
• required へ昇格する場合の昇格条件（上記「昇格条件の書き方」に沿う）
• 閾値を持つ gate は、report_only で計測する項目と、採用予定の閾値の決め方

これにより、gate ごとに場当たりで必須化を判断せず、mode と昇格条件を事前に固定してから導入できる。

この protocol に従う gate

本 Issue 群（親 #1556）で追加する次の gate は、この protocol に従って導入する。

• #1559 sandbox HOME 実インストール smoke
• #1560 e2e-workflow-gate の verifier 分離
• #1561 jscpd によるクローン検出
• #1563 multi-review finding 修正の verify pass

各 gate の Issue / PR は、採用する導入 mode と昇格条件をこの文書に沿って記載する。