ADR-0119: 審査パイプラインに「コード実査グラウンディング」を導入する（verify_in_code の actionability 分離 + evidence pack 規約 + 起案テキスト肥大化防止）

• Status: Accepted
• Mode: Standard
• Kruchten Type: Existence/Executive
• Scope: platform
• Implementation Status: Done (Phase 0 PR #1532 / Phase B PR #1541 / Phase C-flip PR #1600, #1603 / Phase D PR #1613, #1614)
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-04 23:56
• 承認日時 (JST): 2026-06-05 (PR #1455 merge = 受理・JST 00:21)
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

審査パイプライン（DRP）はコードを読む step を持たない。drp/src/graph.ts の全ノードは LLM テキスト処理であり、Gate 2 consistency が参照するのも ADR コーパスのみ。このため盲点検出（Gate 1）や Cross-Validation が「コードを 5 分読めば白黒つく仮説」を生成しても、パイプライン内に検証手段がなく、CV がそれを Must 毀損として差し戻す構造的非対称がある。

§1.2 現状 (As-Is)

実測 1（2026-06-04・docs 差分ビルド draft = 後の ADR-0112）: CV 4 連続差し戻し（score 44→46→47→48 と上昇しつつ critical は毎回新種 = goalpost パターン）。うち round3 の critical「glossary 注入粒度」は人間のコード実査 5 分で反証できた（scripts/docs-build.mjs の注入は buildPage 内側・GLOSSARY は起動時 fresh ロード・nodemon プロセス再起動型 → 差分 N ページなら注入も N ページ分のみ）にもかかわらず、検証経路がないため差し戻し 1 周 約 16 分 + LLM 課金 約 $0.5 を消費した。

実測 2（同日・同 draft）: 盲点対応の追記が起案テキスト本文に永続蓄積するラチェット構造により、生 context が v1→v4 で 3.5KB→13KB（3.7 倍） に膨張した。ADR-0115 / 0116 / 0117 の v2 再投入でも同じパターン（差し戻し対応 = 生テキストへの追記）が発生しており、再投入のたびに本文が肥大して以後の全 gate のトークン消費とレビュー認知負荷が増える。

頻度ベースライン（telemetry 全件実測・2026-05-29〜06-04・schema v8・テスト draft と dry-run を除外した実案件 72 run）: 却下 45 回（62%）、うち Cross-Validation 却下 35 回（却下の 78%）・scoring 閾値未達 5・triage/起案前ゲート 5。CV 却下 35 ラウンドの critical をサンプル実査して分類した結果、**約 1/3〜1/2（12〜18 ラウンド）が「コード/ドキュメント実査または 1 回の実測で白黒つく仮説」**だった（例: 「chat UI 固有の付随処理の所在」= src 実査で確認可 / 「LangGraph 内部メタデータ依存」= 公式ドキュメント確認 / 「CI 環境での決定論性が未証明」= CI 1 回の diff=0 実測で解消）。残りは判断・思弁系（3 モデル訓練データバイアス・法務確認の先送り等）と正当ギャップで、これらは evidence では消えない。

なお 06-01 の集中却下（1 日 29 回）の根本原因は非決定ループそのもの（盲点一致率 6%・多重却下 7/7 が goalpost）で ADR-0109 bounded rounds が止血済み。0109 適用後（06-03 以降）のベースで数えると CV 差し戻し 13 ラウンド中 4〜7 ラウンド（3〜5 割）が本提案の evidence 経路で回避可能だった: 確実 4 = コード実査反証の実証 1 件（2026-06-04・round3 glossary 注入を実査 5 分で反証）+ body-only 割引型 3 件（緩和は本文に存在するのに raw 根拠なしとして割引され差し戻し/escalate に至ったもの。ADR-0114 v3・ADR-0116 v2 ×2）。同日 goalpost escalate は 3 件（ADR-0112/0115/0116）でうち 1〜2 件は evidence 経路があれば escalate 自体不要だった。

§1.3 課題

• CV がコード実査で白黒つく仮説を Must 毀損として差し戻す構造的非対称により、1 周 16 分 + $0.5 を浪費する。
• 差し戻し対応が起案テキスト本文に永続蓄積するラチェット構造で本文が肥大化し（実測 3.7 倍）、以後の全 gate のトークン消費とレビュー認知負荷が増える。

§1.4 制約・要件

• non-goal: 審査ノードへの repo read ツール付与（エージェント化）は本 ADR のスコープ外。token 管理・実行時間・agentic 制御の設計が必要で、本 ADR の 8 週運用実績を見て別 ADR で判断する。
• ADR-0088 / 0091 の起案テキスト必須節（コスト試算/撤退条件/Confirmation）は変更しない（Conflict 回避）。
• evidence の認証境界は既存 DRAFTS_KV と同一（公開エンドポイントなし・現行 Basic 認証 → ADR-0110 の CF Access 移行に追従）に置く。新たな公開面を作らない。
• LLM 追加コスト: なし（evidence はプロンプト数 KB の増加のみ）。

§1.5 目標 (To-Be)

• CV finding を「コード実査で白黒つく仮説」と「判断・思弁系」に分離し、前者は evidence 提示で解消できる検証要求として扱う。検証事実は本文と分離した evidence フィールドに蓄積し、本文ラチェット肥大を構造的に遮断する。
• Non-Goals: 審査ノード自体の repo 読み取り化／CV プロンプトでの git history 直接アクセス／evidence の真偽自動判定。

決定

CV の actionability 区分に verify_in_code を追加して「即差し戻し」から分離し、起案テキストに「検証済みの前提」節を規約化し、検証事実は KV draft の別フィールド evidence（必須属性: 対象コミット SHA または最終更新日時・検証日／上限 10 エントリ／draft DELETE で同時削除）に保存して CV プロンプトが参照する 3 構成を導入する。evidence は検証日 8 週超または対象ファイルが evidence のコミットより後に変更されている場合は期限切れとして再検証要求を返す。実装は CV プロンプト SSoT・CV ノード・operator_guide・/drafts API・telemetry schema に限定する。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸の score < 3 は不採用。

3.2 評価軸 × 案スコア表

検討した代替案 (Alternatives Considered)

• 案 a（現状維持）: 差し戻しのたびに人間がコード実査して生テキストに織り込む — 実測どおり 1 周 16 分 + $0.5 の浪費と本文肥大が続き、#efficient で K.O.。
• 案 b（repo read ツールの即時導入）: 根本解だが、Workers 上の LLM ノードに repo アクセスを与える設計（認可・タイムアウト・コスト暴走防止）が大きく、検証要求の分離だけで得られる効果を測る前に投資するのは過剰。non-goal として明示し先送り。
• 案 c（早期 CV プリゲート統合）: CV を socratic 直後に軽量 2 段化して fail-fast する案。プリゲート化しても検証経路がなければ同じ非対称が残るため、本件（evidence 経路の整備）が先。プリゲートは別途再検討（統合余地は影響節に記録）。
• 構成要素単独の比較（スコアリング講評対応）: 採択案の 2 要素は対で機能するため単独導入は不採用。verify_in_code 分離のみ（evidence pack なし）— 検証要求に応える置き場が本文しかなく、再投入のたびに本文へ織り込む現行ラチェット（実測 3.7 倍肥大）が残存（#efficient 3 相当）。evidence pack のみ（区分なし）— 検証事実を置けても CV の差し戻し判定が「即 revise_adr」のままで参照する契機がなく、構造的非対称が未解消（#efficient 2 相当）。本丸は evidence pack（肥大遮断 + body-only 割引の回避）であり、verify_in_code 区分はその参照経路を CV 判定に接続する配線という関係。

影響 (Consequences)

§5.1 正の影響 (Good)

• コード実査で反証可能な仮説による差し戻し（実測 1 周 16 分 + $0.5）を削減。0109 適用後のベースで 13 ラウンド中 4〜7 ラウンドが回避対象。
• 検証事実が本文と分離されることで、再投入時の本文ラチェット肥大（実測 3.5KB→13KB の 3.7 倍）を構造的に遮断。以後の全 gate のトークン消費とレビュー認知負荷を削減。
• evidence の必須属性（コミット SHA/最終更新日時・検証日）と期限切れ判定により、古い evidence が「検証済み事実」として無条件参照され誤通過が永続する経路（コメント/コード乖離は平均 14 週で発生 — Tufano et al. 2019）を遮断。
• 撤退時は CV プロンプト KV 差し替えで 0.25 人日以内に revert 可能。

§5.2 負の影響 (Bad)

• verify_in_code 区分判定の LLM 精度未実測リスク（Gate 1 critical-1）: 区分付与は LLM プロンプト処理であり、「12〜18 ラウンド該当」分類は人間判断ベース。LLM の文脈依存分類タスクは精度がばらつく（Zhao et al. 2023）ため、本来 verify_in_code とすべき仮説が revise_adr に分類され続けると KPI① が未達になる。緩和: 過去 35 件の CV 却下ラウンドの critic 文を投入し、LLM 付与区分と人間判定の一致率を F1 で計測するパイロットを着手時に実施。precision ≥ 0.7 を撤退条件の前提として明示し、未達なら本格運用前に分岐 OFF。
• git history 非参照による SHA 比較の限界（Gate 1 high-2）: CV ノードは git history へのアクセスを持たず（non-goal）、参照可能なのは evidence に記録された SHA と検証日のみ。rebase・squash・force-push で SHA が消えると比較対象が不在になる。緩和: 「SHA 不在または参照不能な場合は evidence を即時 stale 扱い」フォールバック仕様を実装に明記、ユニットテストに存在しない SHA ケースを必ず含める。コミット SHA 比較の能動的更新（週次 scheduled CI で git log 走査）は本フェーズ非実装とし、現フェーズは検証日 8 週時間条件 + SHA 不在 → 即 stale のみで運用することを明記。
• ROI 試算の楽観性（Gate 1 high-3）: 「1 件/日」は 0109 適用前のピークを含む。0109 適用後の定常ペースは 8 日間で 4〜7 ラウンド = 0.5〜0.9 件/日。Hofstadter's Law を考慮し実装工数 2.75〜3.25 人日は 1.5〜2 倍（4〜6.5 人日）に膨らみうる。再試算: 定常ペース 0.7 件/日 × 16 分 = 約 1.9 時間/週の削減 → 工数 5 人日（40 時間）回収に約 21 週。8 週判定では工数回収は完了しない前提で、KPI 改善傾向のみで判定する。
• 週次アラートの分母小・誤報リスク（Gate 1 high-4）: verify_in_code 指定が週 3〜4 件のとき 1 件未解消で 25% アラート発火、平均 2〜3 週で無視される（Google SRE Book ch.6）。緩和: 「当該週指定件数 5 件未満は issue 起票スキップ、累積 10 件超過時点で初回判定」という分母フィルタを Confirmation 節に組み込む（下記参照）。
• evidence 真偽の自動検証不能・利益相反リスク（Gate 1 medium-5）: CV プロンプトは evidence の真偽を確認できない。ソロ運用では起案者自身が記入・通過させる利益相反が成立しうる。緩和: この限界をリスクとして明記し、誤通過発覚時の遡及調査手順（該当 draft の KV エントリ復元・evidence 内容と実コードの差分照合・該当 critic を verify_in_code に分類した CV ラウンドの telemetry 抽出）を撤退条件の「原因調査 issue 起票」内容として具体化。
• evidence 要約統合の劣化リスク（Gate 1 medium-6）: 10 エントリ超過時の要約で SHA・関数名が抽象化されると、本 ADR が解決しようとする body-only 割引と同型の問題を evidence 層で再発させる。緩和: 要約統合の実行主体は人間手動を既定とし、LLM 自動要約を採用する場合でも必ず保持する必須フィールド: コミット SHA・ファイルパス・検証日を実装仕様に明記、ユニットテストで保持を確認。
• 閾値引き下げ amendment による撤退回避（Gate 1 medium-7）: 解消率 29% で「プロンプト調整で改善できる」確証バイアスのもと閾値を下げる amendment は典型的なサンクコスト回避失敗パターン（Arkes & Blumer 1985）。緩和: 「延長後の判定で閾値を変更する場合は閾値変更の ADR を別途起票し、現 ADR の amendment では閾値を下げられない」を撤退条件に明記。
• 外部アクセス付与の単独承認リスク（Gate 1 medium-8）: ソロ運用中の外部監査時に担当者が単独で KV アクセスを付与し内部関数名を含む evidence が開示されるシナリオ。緩和: 「外部アクセス付与時は付与前に本 ADR の amendment を起票し受理を待つ」を承認フローとしてアクセス制御節に明記。

§5.3 中立・トレードオフ (Neutral / Trade-offs)

• 案 c（CV 早期プリゲート統合）の余地は残る。本 ADR の 8 週運用で evidence 経路の効果が確認できたら、プリゲート + verify_in_code の組み合わせを別 ADR で再検討する。
• ADR-0076（CV 導入）に対する Refine（Supersede しない）。ADR-0109（bounded rounds + HITL escalate）とは補完関係（escalate は出口、本件は上流対策）で、escalate 件数 KPI を共有（DOC-OPS-20）。
• ADR-0117（DRP 層別 docs）の §7 検証層と evidence 記録形式は将来整合させる。本 ADR では KV フィールドのみ定義。
• ADR-0110 の Basic 認証 → CF Access 移行に evidence の認証境界も追従するため、本 ADR 固有の認可設計は持たない。

撤退条件 (Rollback Plan)

• 導入後 8 週で、verify_in_code 指定 finding のうち evidence 提示で解消された比率が 30% 未満なら分岐を OFF（プロンプト KV 差し替えで revert・0.25 人日以内）。運用規約（②）のみ残す。
• パイロット precision 前提: 着手時パイロット（過去 35 件 CV 却下を投入し LLM 区分と人間判定の F1 計測）で precision < 0.7 なら本格運用を開始せず分岐 OFF。
• evidence pack 起因の誤通過（受理後に実装と矛盾が発覚）が 2 件以上で即 OFF + 原因調査 issue 起票。原因調査の最低項目: 該当 draft の KV エントリ復元・evidence 内容と実コードの差分照合・該当 critic を verify_in_code に分類した CV ラウンドの telemetry 抽出。
• 導入後 8 週の draft 生 context サイズ中央値が導入前（直近 10 draft 中央値を着手時に記録）より増加していたら、肥大化防止設計（③）を見直す。
• 判定は telemetry の actionability 区分記録を正とし、件数が 8 週で 10 件未満なら判定を 4 週延長する（分母不足の暫定判定禁止）。延長は最大 1 回まで・延長後も 10 件未満なら自動 OFF をデフォルトとする（サンクコストによる撤退回避の構造的防止 — Kahneman 2011）。自動 OFF を覆して継続する場合は本 ADR への明示的な追記（amendment）を要し、ソロ運用の独立性限界を補うため判定結果と理由を月次セルフチェックログへ記録して非同期レビュー可能にする。
• 閾値変更の禁止: 延長後の判定で 30% 閾値を変更する場合は閾値変更の ADR を別途起票し、現 ADR の amendment では閾値を下げられない（サンクコスト回避失敗パターンの構造的防止 — Arkes & Blumer 1985）。
• 外部アクセス承認フロー: 外部委託・監査人への KV アクセス付与時は付与前に本 ADR の amendment を起票し受理を待つ。担当者の単独付与は禁止。
• 長期負債の点検（Review After: 2026-12-01・固定日付）: 8 週判定とは独立に、(a) evidence 蓄積による KV 値肥大（上限 10 エントリ運用が機能しているか）(b) 週次アラートのトイル化（誤報率・無視率）(c) non-goal（repo read ツール）の再評価、を点検する。運用接点を最小化するため本点検は 2026-12 の月次セルフチェックに同梱して実施する（独立イベントを増やさない・Policy Alignment 推奨対応）。

コスト試算

初期実装（main 領分中心）:

回収見込み: 0109 適用後の定常ペース 0.5〜0.9 件/日（中央値 0.7 件/日 × 16 分 ≒ 1.9 時間/週の削減）で、補正後工数 5 人日（40 時間）の回収に約 21 週。8 週判定時点では工数回収は完了しない前提で、KPI の改善傾向のみで継続可否を判定する。LLM 追加コストは evidence のプロンプト数 KB 増のみ（トークン増は KPI ③ の context 非増加で監視）。撤退時 revert は 0.25 人日（プロンプト KV 差し替え）。

Confirmation

• 検証手段: telemetry に verify_in_code 指定件数・evidence 解消件数・差し戻し周回数・draft 生 context サイズを記録。週次の scheduled CI が解消率を自動集計し、30% を下回ったら GitHub issue を自動起票する（月次手動集計のみでは閾値違反を最大 12 週見逃すため。手動集計は backstop に降格）。分母フィルタ: 当該週の verify_in_code 指定件数が 5 件未満の場合は issue 起票をスキップし、累積件数が 10 件を超えた時点で初回判定を行う（Google SRE Book ch.6 の誤報率対策）。operator_guide 規約は新規起案 3 件のサンプル確認。evidence の期限切れ再検証要求の発火は kill しない（解消扱いを外すだけ）こと、および SHA 不在/参照不能ケースが即 stale 扱いになることをユニットテストで確認。要約統合時のコミット SHA・ファイルパス・検証日の保持もユニットテストで確認。evidence 真偽の機械検証（Policy Alignment 推奨対応）: 週次 scheduled CI が evidence 記載のコミット SHA の実在（git cat-file -e）と記載ファイルパスの実在を機械チェックし、不在なら当該 evidence を stale 扱い + issue 起票する — ソロ運用の利益相反（起案者が自分で evidence を記入し通過させる経路）を人間判断でなく機械検証で構造的に抑制する（真偽の完全検証は不能のまま = §5.2 の限界明記は維持）。
• パイロット: 着手時に過去 35 件の CV 却下ラウンドの critic 文を CV プロンプトに投入し、LLM 付与区分と人間判定の一致率を F1 で計測。precision ≥ 0.7 を本格運用開始の前提とする。
• 実行頻度: 週次自動アラート（分母フィルタ付き） + 月次セルフチェック（backstop） + 8 週時点で撤退条件判定。長期負債点検は 2026-12 月初。
• 違反時対応: 撤退条件参照（プロンプト KV 差し替えで即 revert 可能）。
• KPI:
  • ①「コード実査で反証可能だったのに差し戻された critical」0 件/8 週（ベースライン: 0109 後の 06-03〜04 で確実 4 ラウンド・うち実証 1 件）
  • ② goalpost ループ起因 escalate の週次件数がベースライン（直近 1 週で 3 件）から減少
  • ③ draft 生 context サイズ中央値の非増加
  • ④ verify_in_code 解消率 ≥ 30%

参照 (References)

• 関連 ADR:
  • ADR-0076（Cross-Validation ゲート導入）: 本件は CV の判定能力を拡張する Refine（Supersede しない）
  • ADR-0109（bounded rounds + HITL escalate）: 補完関係。escalate 件数 KPI（DOC-OPS-20）を共有
  • ADR-0088 / 0091（起案前ゲート）: 「検証済みの前提」節は任意節として追加、既存必須節は変えない（Conflict なし）
  • ADR-0117（DRP 層別 docs）: evidence の記録形式は将来 §7 検証層の規約と整合させる
  • ADR-0110（Basic 認証 → CF Access・Proposed）: evidence の認証境界は DRAFTS_KV と同一のため 0110 の移行に追従
• 関連 PR/Issue: PR #1455（本 ADR 起票）/ DOC-OPS-19（TODO_future.md §7 — 本起案の発端・2026-06-04 PR #1400 で起票）/ DOC-OPS-20（ADR-0109 amendment — escalate 件数 KPI の測定共有先）
• 外部資料:
  • Tufano et al. 2019（コメント/コード乖離は平均 14 週で発生）
  • Zhao et al. 2023（LLM 文脈依存分類の精度ばらつき）
  • Google SRE Book ch.6（誤報率高アラートの無視化）
  • Kahneman 2011（損失回避バイアスと複数条件 AND の撤退率低下）
  • Arkes & Blumer 1985（サンクコスト効果）