ADR-0074: Gate 4 Scoring σ 月次モニタリングレポート

• Status: Proposed
• Mode: Standard
• Kruchten Type: Existence/Executive
• Scope: platform
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-26 21:53
• 承認日時 (JST): -
• Deciders: [email protected] (単独)

コンテキスト

1.1 背景 (Background)

ADR-0056 (decision-pipeline-llm-temp-sampling-stage-hybrid-strategy.md) §6.1 は再評価トリガーとして「Gate 4 Scoring の信頼区間幅 (σ) が 5 点 (50 点満点中) 超えていれば、Gate 4 のみ N=10 に拡張検討」を定義した。Phase 4 (PR #1010) で scoring.ts に Self-Consistency N=5 と scoringStdDev 計算を実装済である。

1.2 現状 (Current State / As-Is)

個別 ADR の scoringStdDev は PipelineSessionDO (Durable Object) の state に保存される。DO state へのアクセスは Cloudflare Workers 内部からの stub.fetch() 経由のみ可能で、外部からの直接 SQL クエリやダッシュボード参照はできない。σ 値の月次集計・トレンド可視化・閾値アラートの仕組みは未実装。

1.3 課題 (Problem)

ADR-0056 §6.1 が定義した「σ > 5 で N=10 拡張検討」のトリガー判定が属人化しており、忘却・記憶依存により再評価機会を逸するリスクがある。σ トレンドの可視化が困難で、Gate 4 Scoring 品質の経時変化を把握できない。

1.4 制約・要件 (Constraints & Requirements)

• DO state は外部から直接クエリ不可、Workers 経由のアクセス手段が必要
• 現在の Pipeline 利用は月 5 件程度、Jr 入社 (2026-10) 後は月 15 件超を想定
• KV 書出し失敗が Pipeline 本体に影響してはならない (fire-and-forget)
• 月次区切りは JST (UTC+9) 00:00 基準 (UTC 集計は月初 ADR が前月計上される)
• GitHub Issue 自動作成には repo scope の token が必要 (既存 webhook.ts と共用可能)

1.5 目標 (Goals / To-Be)

σ 値を KV に永続化し、月次集計レポートを自動生成して σ > 5 が 3 ヶ月連続した場合に GitHub Issue を自動作成することで、ADR-0056 §6.1 の N 拡張トリガーを自動化する。Non-Goals: リアルタイムダッシュボード、過去 ADR の遡及集計。

決定

方法 A: KV セッション ID リスト方式 を採用する。Pipeline 完了時に pipeline_consumer.ts から KV namespace SIGMA_LOG (key = sigma:{YYYY-MM}:{sessionId}) に scoringStdDev + 完了日時を追記し、scripts/pipeline-sigma-report.mjs で月次集計・レポート生成・3 ヶ月連続アラートを実装する。レポート出力先は docs/_internal/06_ops/pipeline_sigma_reports/YYYY-MM.md、実行頻度は毎月 1 日 (JST) の手動実行 (将来 cron 化検討)。

判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 3-5 個選定)

K.O. criterion: Must 軸 (#operable, #reliable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

検討した代替案 (Alternatives Considered)

• 案 A: Cloudflare Analytics Engine: Workers Analytics Engine に σ を event として送信し、ダッシュボードで可視化する案。— 不採用理由: 現在の月 5 件程度の ADR 件数では Analytics Engine のセットアップコスト (Workers Paid plan の追加費用 + event schema 設計) が見合わない。月 15 件超 (Jr 入社後) になったら再検討。
• 案 B: 手動月次レビュー: 毎月末に Pipeline Web UI で各セッション結果を目視確認する案。— 不採用理由: 忘れるリスク、σ トレンドの可視化が困難、3 ヶ月連続判定が人間の記憶に依存 (K.O. 不通過)。
• 方法 B: DO アラーム export (本決定の対案): DO アラーム機能で定期 export する案。— 不採用理由: DO は name-based ID のため全セッション列挙に list() が使えず、セッション ID の事前把握が必要。方法 A の KV 書出しの方がシンプルで確実。

影響 (Consequences)

5.1 正の影響 (Good)

• ADR-0056 §6.1 の N 拡張トリガーが自動化され、判断を属人化から解放
• σ トレンドの可視化で Gate 4 Scoring の品質推移を把握可能
• Jr 開発者 (2026-10 入社) の scoring 品質可視化により Pipeline 理解を加速
• 月次実行所要時間 < 10 秒、年間運用コスト 0.2 人日と低負荷

5.2 負の影響 (Bad)

• pipeline_consumer.ts に KV 書出しロジック追加 (既存コードへの変更)
• KV namespace SIGMA_LOG の追加 (wrangler.toml 更新)
• 過去セッションの遡及集計不可: 本 ADR 実装前のセッションは KV にログがないため、初回レポートは実装後の件数のみ
• 初期実装に 1.2 人日が必要

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

• KV 書出し失敗時は try-catch で fire-and-forget (Pipeline 本体に影響させない代わりに、σ ログ欠損リスクを許容)
• σ = 0 / null (rejected=true で early return したセッション) は集計から除外
• 集計タイムゾーンを JST 固定とする (UTC 集計より直感的だが、海外展開時に再設計が必要)
• GitHub Issue 自動作成の token は既存 webhook.ts と共用 (権限拡散を避ける代わりに、token rotation 時の影響範囲が広がる)
• コスト試算:

  項目	工数
  pipeline_consumer.ts に KV σ ログ書出し追加	0.3 人日
  KV namespace 追加 (wrangler.toml)	0.1 人日
  pipeline-sigma-report.mjs (KV 集計 + レポート生成)	0.5 人日
  GitHub Issue 自動作成 (3 ヶ月連続判定ロジック)	0.3 人日
  初期実装合計	1.2 人日
  月次実行所要時間	< 10 秒 (KV list + 5-10 件 read)
  KV コスト	$0.50/百万 read (月 10 件で無視可能)
  年間運用コスト	0.2 人日/年 (閾値調整 + レポート確認)

撤退条件 (Rollback Plan)

• 6 ヶ月間 σ が常に 3 未満ならモニタリング頻度を月次 → 四半期に緩和
• Jr 入社 (2026-10) で月 15 件超なら Analytics Engine への移行を検討
• 撤退時の既存成果物整理:
  • pipeline_sigma_reports/ ディレクトリをアーカイブ
  • Issue label sigma-alert の open Issue を close
  • KV namespace SIGMA_LOG は 90 日保存後に削除
• Review After: 2026-11-26 (6 ヶ月後)

Confirmation (準拠確認 / Fitness Function)

参照 (References)

• 関連 ADR: ADR-0056 (decision-pipeline-llm-temp-sampling-stage-hybrid-strategy) §6.1 — N 拡張トリガー定義
• 関連 PR/Issue: PR #1010 (Phase 4 scoring.ts Self-Consistency N=5 実装)
• 外部資料: Cloudflare Workers KV REST API ドキュメント、Cloudflare Durable Objects state アクセス制約