ADR-0091: ADR 起案の数値必須化を拡張: 要追記禁止 + 撤退/完了条件に定量値必須 (ADR-0088 拡張)

• Status: Accepted
• Mode: Standard
• Kruchten Type: Executive/Property
• Scope: platform
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-30 00:41
• 承認日時 (JST): 2026-05-30 00:55 (Pipeline 通常 flow Standard 45/50 通過 + Consistency INFO、PR #1157 マージ)
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

ADR-0088 がコスト試算の起案前必須化で churn を削減した一方、再投入 churn の次のドライバとして「未確定プレースホルダの残存」と「撤退条件・完了条件が数値化されていない」ことが浮上した。Gate4 採点はこれらを §7_rollback / §9_completion / §5_impact で減点するが、起案前に強制されないため抜け落ちる。

§1.2 現状 (As-Is)

定量根拠 (2026-05-29 実測): 直近 4 起案 (section-structure / consolidate-rq / progressive-gates / 本起案の初回) がすべて 39/50 (閾値 40) で差し戻し。最弱は一貫してプレースホルダ残存 + rollback/completion の数値欠落。n=4 の小標本・単一時点で Gate4 採点者の交絡可能性は残るため、導入前に直近 20〜30 件の差し戻し理由を分類して主因を再確認する。

§1.3 課題

39 帯 churn (39/50 連続差し戻し) の主因が起案前に検出されず、再採点コスト (~6.7 分 + Opus / 回、直近 4 件で計 ~27 分 + Opus 4 回) が累積している。merged ADR の撤退条件・完了条件が定量化されていないため、ロールバック判断・完了判定が再現可能でない。

§1.4 制約・要件

• ADR-0088 の 3 層機構 (起案前ゲート + §4.1 テンプレ + adr-lint backstop) と一貫した規律であること。
• ルール定義は adr-lint.mjs に単一集約し、起案前ゲートは同モジュールをライブラリ呼び出し (設定ドリフト回避)。
• 各ルールは独立に warning/error/無効を切替可能。
• 適用は本 ADR マージ日以降の新規 ADR のみ。
• スキャンはセクション本文に限定し、コードブロック/Non-Goals/引用/コメントを除外 (意図的プレースホルダの誤検出回避)。
• 追加 LLM/インフラコストなし (正規表現検査のみ)。

§1.5 目標 (To-Be)

Standard 以上の ADR 起案で (1) 未確定プレースホルダ禁止、(2) 撤退条件に数値閾値 1 つ以上、(3) 完了条件に観測可能 KPI 1 つ以上 を起案前にハード制約として強制し、Gate4 差し戻し率を低下させる。Non-Goals: 数値「妥当性」検査・要約品質検査 (Gate1/Gate4 に委ねる)。

決定

ADR-0088 の 3 層機構 (起案前ゲート + §4.1 テンプレ + adr-lint backstop) を流用し、Standard 以上の起案に 3 ルール (no-placeholder-marker / rollback-has-quantity / confirmation-has-kpi) を追加する。ルール定義は adr-lint.mjs に単一集約、起案前ゲートはライブラリ呼び出しで一元化。各ルールは独立に warning/error/無効を切替可能とし、適用は本 ADR マージ日以降の新規 ADR のみ。スキャンはセクション本文に限定しコードブロック/Non-Goals/引用/コメントを除外する。

前提確定ゲート (Acceptance Criteria・マージ前提条件): #reliable の前提を「仮定」で済ませず、以下を実装着手前のハード条件とする (事後確認に回さない)。

1. 診断の確定 (n=4 過剰適合の解消): 直近 20〜30 件の差し戻し理由を分類し「プレースホルダ/数値欠落」が主因であることを確認するまで実装を開始しない。主因と支持されなければ本 ADR のルール設計を見直す (撤回 or 対象ルール変更)。分類は本 ADR の Acceptance Criteria であり PR チェックリスト必須項目。
2. ベースライン確定: 実装開始前に §7_rollback / §9_completion の Gate4 採点データ (直近 20〜30 件) を手動集計し平均・分散を Context に記録する。これが無いと 8 週後の「導入前比」が計算不能なため、ベースライン記録を完了するまでルールを error 化しない (warning 止まり)。
3. 実行ランタイムの確定 (GAS 非該当): drp は Cloudflare Workers (nodejs_compat) 上で動作し、Google Apps Script ではない (ADR-0019/0066)。GAS の 6 分/90 分/プロパティ 50KB 制限は本件に非該当。adr-lint.mjs は Worker ランタイムで実行され、正規表現スキャンは ADR 1 本 (数千字) あたり数十 ms オーダーで Worker CPU time 制限に十分なヘッドルームがある。直近 20〜30 件の一括診断は CI (GitHub Actions の Node.js) で実行し Worker 経路に乗せない。
4. fail-closed (全終了経路を block): 起案前ゲートが adr-lint.mjs を呼ぶ際、(a) import 失敗 (ESM/CJS 境界)、(b) lint 関数の例外送出、(c) タイムアウト のいずれでも素通り (fail-open) させず block (fail-closed) する。catch で握り潰さず明示的に exit code≠0 / throw を返すフローを実装 (ハッピーパス以外の全経路を block に倒す)。Node.js は package.json engines を major+minor で固定し、Renovate/Dependabot の更新 PR には「import 失敗をモックした fail-closed 統合テスト」を必須 CI チェックとして紐付け、バージョン更新で fail-open に無音反転しないことを担保 (盲点対応)。

✅ AC-1 / AC-2 充足 (baseline 取得済・2026-05-30): 着手前 baseline を docs/_internal/adr-0088-ext-baseline.json に取得・コミット済 (PR #1174)。

• AC-1 (診断の確定): verdict = SUPPORTED。Gate4 score 由来 reject 14 件中 14 件 (100%) が numeric-missing または placeholder を含み、「プレースホルダ/数値欠落が主因 (過半超)」仮説を支持。撤回トリガー (§5.3 の「50% 未満なら撤回」) に非該当 → 実装続行可。なお Cross-Validation 起因 reject 13 件 (全 27 件中 48.1%) は ADR-0076 既存ゲート起因のため本 ADR スコープ外として分母から除外 (primary_share.scope 参照)。
• AC-2 (ベースライン確定): §7_rollback / §9_completion を含む Gate4 採点 baseline = n 27 / mean 40.93 / stddev 3.68 / median 39 (min 34 / max 48)。8 週後「導入前比」算出の基準として記録済 → ルールの error 化が可能 (warning 止まりの前提条件を解除)。
• 参照: baseline 取得・分析コミット 3e46099 (PR #1174) / adr_0091_verdict + gate4_baseline フィールド。

判断基準 (Decision Drivers)

3.1 評価軸

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

3.2 評価軸 × 案スコア表

加重和は K.O. 通過候補のタイブレーク用 (Suhr 1999 CBA 準拠)。

検討した代替案 (Alternatives Considered)

• 案 A: adr-lint backstop のみ (起案前ゲートなし) — Gate4 差し戻し後に検出する従来形。churn 削減効果が薄く、起案前カット (本 ADR の目的) を達成しないため不採用。K.O. 不通過。
• 案 B: LLM セマンティック検査 — 日本語表記揺れ網羅性は高いが、追加 LLM コスト発生・判定の非決定性で再現性が低く、起案ごとに遅延発生。正規表現の限界が確認されてからの follow-up とする。

影響 (Consequences)

§5.1 正の影響 (Good)

• 39 帯 churn の主因を起案前カット。
• merged ADR の撤退・完了が一律に測れる。
• ADR-0088 と一貫した規律。
• 39 帯の無駄な再採点 (~6.7 分 + Opus / 回、直近 4 件で計 ~27 分 + Opus 4 回) を削減。
• 直接金銭支出 0 円 (個人開発・自工数、追加 LLM/インフラコストなし)。

§5.2 負の影響 (Bad)

• 起案者に数値 1 つの負担 (「粗くて可」で緩和)。
• 日本語表記揺れ (全角・漢数字・「数件」「約半数」、セクション名揺れ) による誤検知 → 実装前に FP/FN テストマトリクス作成・全角/漢数字正規化を先行。
• adr-lint.mjs 自体のバグ (ReDoS、Unicode 正規化例外、ESM 解決失敗) が起案パイプライン全体を停止させる最悪ケース。ReDoS 耐性テスト (長大入力・悪意ある入力) を FP/FN マトリクスに含め、Worker ランタイム上での fail-closed 動作を検証する専用 E2E テストを wrangler dev で実装し CI に組み込む。lint 基盤障害時の手動バイパス手順は §6 撤退条件に追加。
• 日本語プレースホルダ表現の網羅性不足 (「要確認」「未定」「後日」「検討中」「追って記載」「※別途」「適宜」等) による False Negative 多発リスク。禁止リストに最低限「要確認」「未定」「後日」「検討中」を追加し、FN 率>5% なら LLM セマンティック検査への移行判断基準とする。

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

• 形式的数値の水増し (Jr が通過目的で根拠なき数値) → §4.1 に「根拠不明時の書き方」例示 + Gate4 採点軸に「数値の根拠説明」追加。ただし数値の存在を評価していた同一採点軸での独立評価可否は未検証。Gate4「数値の根拠評価軸」を現行採点プロンプトから分離した独立チェックとして設計。20〜30 件分類は1 人運用のため人的第三者は置かず、別プロンプト/別モデルでの再分類＋時間差(24h)での自己再評価で独立性を代替する(会社方針「複数評価者前提を持ち込まない」に準拠)。
• ルール二重実装の設定ドリフト → adr-lint.mjs 単一ソース + ライブラリ呼び出しで一元化。
• 規約分散 → ADR-0024/0036 を amends 明記 + 逆参照。
• n=4 過剰適合のサンクコスト圧力 → 分類結果の撤回トリガーを事前に定量化して属人判断を機械化(例:「プレースホルダ/数値欠落が全差し戻しの 50% 以上を占めない場合は本 ADR を撤回」)、PR チェックリストに明記。1 人運用のため人的二重確認は置かず、この定量トリガーと 24h クーリングオフ後の時間差自己再評価でサンクコストバイアスを抑える。
• 診断前提条件の充足判定に技術的歯止めなし → ベースラインデータ (直近 20〜30 件の分類結果) を docs/_internal/adr-0088-ext-baseline.json にコミットすることを CI 必須チェックとし、ファイル不在時はルールの error 化を技術的にブロック。
• telemetry 集計障害 → telemetry 集計ロジックのユニットテストを必須化、ベースラインデータを外部 (リポジトリ内 CSV など) にもバックアップ、4 週レビュー前に telemetry の動作確認を「前提確定ゲート」に追加。
• 「粗くて可」と ≥99% KPI の矛盾 (グッドハートの法則) → 完了条件 KPI から「割合 ≥99%」の単独評価を避け、§7/§9 Gate4 平均点上昇を主 KPI として再定義。§4.1 に「許容される数値の最低基準」を具体例 3 パターン以上 (オーダーマグニチュード推定・文献引用・類似案件実績) で例示。
• 8 週間の統計的検出力不足 → 8 週間の想定起案件数を実績ログから算出し、§7/§9 平均点変化を検出するための最小効果量と検出力を計算。サンプル不足時はレビュー期間延長または差し戻し理由分類割合 (より感度の高い指標) への変更を検討。

影響範囲 (変更対象・関係者)

amends (部分上書き): ADR-0024 (テンプレ構造) / ADR-0036 (Confirmation) に数値要件を上乗せ。両 ADR の Front Matter に逆参照を追加 (規約参照先の分散防止)。

コスト試算 (内訳・金額換算)

金額換算: 個人開発のため直接金銭支出 0 円 (自工数)。機会費用換算で ~16.5h ≒ 2.75 人日。追加 LLM/インフラコストなし (正規表現検査のみ)。

撤退条件 (Rollback Plan)

1 ルールの失敗が他ルールの撤回を自動誘発しない設計。

• 誤ブロック率 10% の根拠: 想定全ブロック ~30 件/月 のうち許容誤ブロック 3 件/月 からの逆算。
• 各ルールは個別に warning/error/無効を切替 (feature 単位ロールバック)。
• 判定担当: 代表取締役 (プライマリ) + 代表取締役 (バックアップ) の 2 名。telemetry からルール別誤ブロック率・§7/§9 Gate4 平均点を自動集計し、4 週・8 週時点で Slack 通知 + カレンダー事前登録。
• lint 基盤自体の障害時の手動バイパス手順: adr-lint.mjs/起案前ゲートが ReDoS・Unicode 例外・ESM 解決失敗等で停止した場合、24h 以内に手動レビュー (代表取締役承認) で代替起案を可能とする。fail-open アノマリ検知 (ゲート通過数急増アラート) を telemetry に追加し、無音反転を検知。
• 判定担当不在時のエスカレーション: レビュー期日を GitHub Issue または scheduled workflow として自動化し、期日超過時は当該ルールを自動的に warning に降格するデッドマンスイッチを実装検討。
• Review After: 2026-07-24 (8 週後) / 2026-08-29 (3 ヶ月後)。

完了条件 (観測可能 KPI)

• 起案前ゲート通過後の起案でプレースホルダ残存率 = 0%。
• 撤退条件/完了条件に数値を含む新規 ADR の割合 (補助指標、単独成功定義としない)。
• 主 KPI: §7_rollback / §9_completion の Gate4 平均点が導入前比で上昇 (telemetry scoring_detail 前後比較)。
• 検証: adr-lint (CI 全 PR) / ゲート差し戻しログ (telemetry) / 4 週・8 週レビューの scoring 前後比較。

長期影響 / 負債化シナリオ

• 正規表現メンテの累積: 日本語表記揺れ対応で正規表現が肥大化し、誤検知パッチを重ねるほど可読性・保守性が劣化。半年で「誰も触れない正規表現」化するリスク → FP/FN テストマトリクスを資産として維持し、表記正規化を前段に集約。adr-lint.mjs のルール数に上限 (例: 最大 10 ルール) を設け、新ルール追加時には既存ルールの廃止または統合をセットで検討する「ルール予算」制度を導入。3 ヶ月後の Review After でルール数・行数・テストケース数を計測し、増加率が閾値を超えた場合は LLM ベースの検査への移行を検討。
• 形式的数値の水増し文化の定着: 強制が長期化すると「通過用ダミー数値」が常態化し、ルールが品質でなく形式を量産する逆効果に → Gate4「数値の根拠説明」軸 + 月次サンプリングで検出。
• ADR タイプ別の過剰負担: Minor/Docs 系にも一律適用され負担過多になる可能性 (根拠 n=4 は Standard 構造変更系に偏る) → 4 週レビューで ADR タイプ別の誤ブロック率・効果を計測し Minor 適用要否を判断。

Confirmation (Fitness Function)

• 検証手段: (1) adr-lint.mjs の 3 ルール CI 実行 (全 PR、fail-closed)、(2) 起案前ゲート (drp triage/draft) でのライブラリ呼び出し、(3) telemetry によるルール別ブロック件数・誤ブロック率・§7/§9 Gate4 平均点の自動集計、(4) FP/FN テストマトリクス (日本語表記揺れ・除外パーサ・ReDoS 耐性) を CI 必須チェック、(5) ベースラインファイル (docs/_internal/adr-0088-ext-baseline.json) 存在チェック (不在時は error 化ブロック)。
• 実行頻度: CI は全 PR・全 push、telemetry 集計は 4 週時点・8 週時点で Slack 通知、Review After (2026-07-24 / 2026-08-29) で手動レビュー。
• 違反時対応: fail-closed で起案 block (exit code≠0 / throw)、手動バイパスは 24h 以内・代表取締役承認。撤退条件トリガー該当時は当該ルールを warning 降格または無効化 (独立切替)。

参照 (References)

• 関連 ADR:
  • ADR-0088 (コスト試算必須化): 同機構 (起案前ゲート + §4.1 + adr-lint) を流用・拡張
  • ADR-0024 (テンプレ構造) / ADR-0036 (Confirmation): 本 ADR が amends (部分上書き)、両 ADR に逆参照追加
  • ADR-0019 / ADR-0066: 実行ランタイム (Cloudflare Workers, nodejs_compat) 根拠
• 関連 PR/Issue: 実証データ — section-structure / consolidate-rq / progressive-gates + 本起案初回 の 4 連続 39/50 (2026-05-29、n=4 小標本・導入前 20〜30 件分類で再確認)
• 外部資料: Suhr 1999 CBA (加重和正規化)、arc42 Q42 9 タグ
• follow-up: 数値「妥当性」検査・要約品質検査はスコープ外 (Gate1/Gate4 に委ねる)、FN 率>5% 時の LLM セマンティック検査移行検討

11. 参照: Pipeline 審査履歴 (2026-05-30 実行時, 通常 flow)

Decision Pipeline で本草案を通常 flow (retroactive=false) で審査した結果。Gate4 45/50 + Consistency INFO。4 回目の投入で、ランタイムを Cloudflare Workers と断定して GAS 制限の誤検知(ハルシネーション)を解消、fail-closed を全終了経路に拡張して Cross-Validation を通過した。