ADR-0131: ADR 間の関係を型付きの辺として宣言し、整合を機械検査する — グラフ衛生

• Status: Accepted (accepted-with-residual-risks)
• Mode: Standard
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: In Progress (PR #1703 = 辺語彙 + 整合 lint report-only 導入。残: 初期移行・error 昇格・0107 抽出器統合)
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-10 22:30
• 承認日時 (JST): 2026-06-21
• Deciders: [email protected] (単独)

決定の早わかり（Y-statement）

本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

• 文脈: ADR が 129 本に達し、決定の再利用 (ADR-0107)・行き先必須規約 (構造 doc D-1)・審査の送り先解決 (RQ-098) の 3 つが「決定どうしのつながり」のデータを必要としている。
• 問題: 行き先の実在確認が人手レビュー頼みで、見落とせば持ち主のいない前提が審査を通る。決定どうしの図は推測でしか作れず、スコープ外指摘の安全な振り分けも止まっている。
• 問題点と課題（直せる原因 → 発生を止めるためにやること）:
  • 関係が型のない文章として片方向にだけ散在する (機械可読は 3/129 本のみ) → 辺の型 7 種の閉じた語彙で frontmatter に両端宣言する。
  • 参照先の実在・双方向の対称・置き換えと状態の一致を機械検査する仕組みがない → 整合 lint を既存 adr-lint 体系に追加し CI で強制する。
• 前提（解決を課題に立てない与件）:
  • Status/Mode 欠落 (89/107) のバックフィルは ADR-0107 が前提作業として引き受ける。
  • 関係図など生成物の手作業更新禁止の規律は ADR-0130 が所有し、本決定は準拠する側。
• 決定（対応策）: 現状維持や参照節の文章解析でなく、ADR 間の関係を frontmatter に型付きの辺 (typed edges) として両端宣言し、整合 lint を CI で強制する。既存 129 本は初期移行で一括変換する。
• 目的: 行き先の実在・置き換えの連なり・関係図が機械検証可能になり、決定の再利用 (ADR-0107) と審査の送り先解決 (RQ-098) が人の注意力に依存せず機能する状態。
• 代償: 起案時の宣言義務 (数分/件) と lint の保守対象が増える。初期移行の LLM 候補化による意味誤分類は受け入れ検査でも全件保証されない。
• 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

§1.1 背景

ADR が 129 本に達し、「過去の決定を探して再利用できる資産にする」取り組みが進んでいる(ADR-0107)。再利用は 1 本ずつ読むだけでは足りず、「この決定は今も有効か(あとの決定に置き換えられていないか)」「この懸念はどの決定が引き受けているか」という決定どうしのつながりへの問いに答えられて、初めて過去の判断を安心して使い回せる。この達成に向けて、つながりを使う仕組みが 3 つ動き出している。

• ADR-0107(Proposed): どの決定がどの決定を置き換え・参照したかを図で辿れるようにし、同じデータを AI に読ませて、新しい起案のときに関連する過去の決定を自動で提示させる計画。
• 起案規約(構造 doc adr_structure_pyramid_principle.md D-1): 問題点を「前提」として外に送るときは、解決を引き受ける ADR の名指し(行き先)を必須にした。送った先が宙に浮けば、問題の持ち主が消えるため。
• 審査パイプライン(RQ-098 設計): 「この指摘は別の ADR の担当」とされた指摘を、担当 ADR が実在して本当に引き受けているかを確かめてから送る設計を進めている。

3 つに共通して必要なのは、「ADR-X は実在するか・今も有効か・その懸念を扱っているか」に答えられる関係データである。

§1.2 現状 (As-Is)

• 実測 1: 関係を機械が読める形で書いているのは Supersedes メタ欄を持つ 3/129 本のみ。残りは参照節に普通の文章として書かれ(「補完」「並立」「Refine」など言い方も不揃い)、機械には読めない。
• 実測 2: 本文中の ADR-NNNN 参照は延べ 2,506 箇所・129 本全部に及ぶが、どれが置き換え・依存・補完なのか機械では区別できない。
• 実測 3: 実在しないプレースホルダ参照(ADR-β)が 1 本残存し、片方向の置き換え宣言や存在しない ADR への参照を検出する lint がない。

§1.3 課題

3 つが共通して頼る「決定どうしのつながり」が機械で読める形になっておらず、それぞれで実害が出ている。

• 行き先の実在確認が人手レビュー頼みで、見落とせば持ち主のいない前提が審査を通る。
• 決定どうしの図は本文の文章からの推測でしか作れず、信頼できない図になる。
• 指摘の送り先解決が実装できず、スコープ外指摘の安全な振り分けが止まっている。

直せる原因: 関係が、型のない普通の文章として片方向にだけ書かれて散在し、整合(参照先の実在・双方向の対称・置き換えと状態の一致・循環なし)を機械検査する仕組みがないこと。

§1.4 制約・要件

• 時間的与件 — メタデータ欠落: 置き換えと状態の整合検査は各 ADR の Status 記載に依存するが、Status/Mode は 89/107(ADR-0107 実測)で欠落がある。バックフィルは ADR-0107 が前提作業として引き受け済み(行き先 = ADR-0107)。
• スコープ的与件 — 生成物の維持規律: 関係図・索引など辺データから作る生成物の「手作業更新禁止・CI 一致強制」は ADR-0130 が規律として所有する(行き先 = ADR-0130)。本決定の lint・グラフ出力はその規律に準拠する側。
• 既存太字メタ欄(Status 等)は変更しない。追記は ADR-0031(メタデータ後付け範疇)経路に乗せ、本文構造は ADR-0023 のまま不変。
• lint 体系は ADR-0019 既存の adr-lint に追加。

§1.5 目標 (To-Be)

関係の宣言を機械可読な型付き表現に統一し、整合を CI が機械検査する。行き先の実在・置き換えの連なり・決定間の関係図が機械検証可能になり、決定の再利用(ADR-0107)と審査の送り先解決(RQ-098)が人の注意力に依存せず機能する状態。

Non-Goals: 意味的カバレッジ判定(送り先が当該懸念を本当にカバーするか)・運用後の辺の意味整合の恒常監視・関係図/索引ページの生成方式そのものは本決定の外。

決定

ADR 間の関係を、各 ADR 冒頭の YAML frontmatter に型付きの辺(typed edges)として両端宣言し、整合 lint を CI で強制する。 3 モデル調査(RQ-100)が一致した「frontmatter を SSoT・両端宣言・クロスファイル lint」の構成を採用する。

構成要素は 4 点:

1. 辺の型 7 種(+ 逆辺)を閉じた語彙で定義する:

   辺(forward)	inverse	意味
   supersedes	superseded_by	旧決定を全面置換(対象 status → superseded)
   amends	amended_by	修正するが置換しない(対象は accepted のまま)
   refines	refined_by	上位決定のスコープ内の子決定
   depends_on	required_by	対象なしには成立しない
   relates_to	(対称)	緩い相互参照
   conflicts_with	(対称)	両立不可・要解決
   follows_up_on	followed_up_by	具体回答を負う spike/follow-up

   これまでの言い方は写像する(Supersedes 欄→supersedes / 部分 Supersede→amends / Refine→refines / 前提→depends_on / 補完・並立・整合→relates_to / spike→follows_up_on)。

2. SSoT = frontmatter・両端宣言。対称辺と supersede 系は両端宣言を必須にし lint で対称性を強制(adr-tools の両端リンク型)。depends_on は子側のみ宣言し逆引きは生成側で計算。参照節は人が読む説明文として残すが、ADR 間関係の正は frontmatter に一本化する。

3. 整合 lint を既存 adr-lint 体系(ADR-0019)に追加する。error 4 種 = 参照先の実在(dangling 禁止)・非対称辺の逆辺存在(片方向 supersede 禁止)・superseded 状態と superseded_by の一致・置き換え連鎖の非循環。warning 2 種 = superseded な ADR への depends_on・本文参照の frontmatter 未反映。クロスファイル検査は自前 ~200 行(RQ-100 見積)。

4. ADR-0107 抽出器との統合(本 ADR で確定): 抽出器は辺を frontmatter から読み adr-index.json に含める。本文の文章からの推測読み取りはしない。別個のグラフ JSON は作らず元データ 1 つ(ADR-0107 案 A)を維持する。下流(審査の送り先解決など)は同 JSON への照会 — 実在するか・現行形はどれか・懸念を所有するか — で答え、解決できなければ呼び手は保守側(keep)に倒れる(RQ-098 の要求)。

frontmatter 新設の扱い: 辺(横 = ADR 間)専用に新設し、ADR-0117 決定済みの Covers:/Constrains:(縦 = 要件への辺)と同じブロックに同居させる。

適用の手順と時期(段階的施行):

• 新設は即時: 受理日から、新規 ADR は辺フィールドの宣言(該当なしは空配列の明示)を必須とする。起案テンプレ・パイプライン出力に追加。辺を宣言する PR は、相手側 ADR への逆辺追記を同一 PR に含める。
• 整合 lint は二段階で施行: 導入時は報告のみ(warning)で開始し、初期移行の完了をもって error へ昇格する。
• 既存 129 本は初期移行で一括変換: ①機械抽出(既存 Supersedes 欄・Status 行・参照節の言い方を写像) → ②残りは LLM が候補辺に起こす(各辺に抽出元の文章を出典として記録) → ③PR 単位で人間レビュー → ④lint の指摘を解消(ADR-β は実 ID 付与か削除) → ⑤完了判定の前に受け入れ検査: 「relates_to 以外の各型から最低 2 件ずつ」の層別サンプリング(下記盲点①対応・原案の 10 件無作為から変更)で型が抽出元の文章と意味的に一致するか確認(不一致 2 件以上で再レビュー)。辺の型ごとの判定基準(どの表現が refines でどれが depends_on か)は lint とは別のルールブックとして文書化する。

塊の分離: 意味的カバレッジ判定は本決定の外(審査ゲート側の将来決定 = RQ-098 素材・未起案が所有)。運用後の辺の意味整合の恒常監視も本決定の外で、ADR-0117 への対象拡張として個別 ADR で決める(起票義務と期限は Confirmation §)。関係図・索引ページの生成方式は ADR-0130 の規律と ADR-0107 の個別適用が所有する。

判断基準 (Decision Drivers)

3.1 評価軸

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

3.2 評価軸 × 案スコア表

採択案が Must 通過かつ加重和最大で採用。

検討した代替案 (Alternatives Considered)

• 案 X1 現状維持(関係は文章のまま・機械は推測で読み取る): 関係図が推測のままで信頼できず、dangling・片方向 supersede を検出できない。実測 1〜3 が反証。Must (#reliable, #maintainable) で K.O.。
• 案 X2 参照節の文章を機械に解析させて整合検査: 自由記述は drift が常態で機械検証に向かない(RQ-100 で 3 モデルとも否定)。Must で K.O.。
• 案 X3 リポ直下の単一グラフファイルを手で維持: 単一マージ衝突点になり ADR 本体から乖離。手作業の一覧維持は ADR-0130 の規律にも抵触。Must (#maintainable) で K.O.。
• 案 X4 supersedes のみ型化する最小案: 行き先検証・送り先解決に必要な refines/follows_up_on が文章のまま残り、課題の大半(2,506 参照の型なし)が未解決。
• 案 X5 RDF/トリプルストア化: 129 本・単独運用には過剰(RQ-100)。frontmatter からの将来昇格は妨げない。

影響 (Consequences)

§5.1 正の影響 (Good)

• 行き先必須規約(構造 doc D-1)が機械ゲート化する。
• ADR-0107 の関係図・AI 書き出しが信頼できる入力を得る。
• 審査の送り先解決(RQ-098)の前提が整う。
• 起案時の重複・矛盾を機械検知できる。

§5.2 負の影響 (Bad)

• 起案時の宣言義務が増える(数分/件)。
• 型の誤用(なんでも relates_to に逃げる)リスク。
• lint の保守対象が 1 つ増える。
• 初期移行の LLM 候補化で意味誤分類が発生し得る(受け入れ検査の層別サンプリングで型別に閾値管理するが、全件保証ではない)。
• frontmatter と参照節文章の二重管理に伴う drift リスク(warning 残数の月次監視で対応)。
• クロスファイル lint の CI 実行時間が ADR 数増加とともに線形増大するリスク(ベースライン計測と閾値 30 秒を設定、増分チェック設計を調査)。
• 初期移行 PR レビュー工数が見積 3〜4h を超過し ADR-0107 着手が遅延する連鎖リスク(週次マイルストーンで管理)。
• RQ-100 の 3 モデル一致は公開コーパスの多数決であり、frontmatter 両端宣言を後に撤退/簡略化した非公開失敗事例(ADR 200 本超で逆辺追記漏れ常態化等)を見落としている可能性。

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

• 既存 129 本は初期移行で一括変換(本文不変・追記のみ)。
• 辺の型 7 種は初期移行後の実測頻度で削減を再検討する(使われない型は drift 源)。
• lint は構文整合のみを保証し、型の意味の正しさは受け入れ検査と監査拡張で扱う。
• frontmatter と太字メタ欄の二重管理は本決定では作らない(辺のみ frontmatter、Status 等は太字欄のまま)。属性側の統合は将来の別決定。
• ADR-0107 抽出器の adr-index.json 書き出し(Google Sheets 経由がある場合)については辺の中間状態が下流に露出しないようアトミック書き込み(一括 paste_values または named range 上書き、ないし書き込み完了フラグセル)を採用する旨を ADR-0107 側の設計に申し送る。

撤退条件 (Rollback Plan)

• 再評価トリガー:
  • (a) lint の誤検知対応が月 30min を超える状態が 2 ヶ月続く場合。
  • (b) 新規宣言辺に占める relates_to の比率が 80% を超え型が情報を失っている場合。
  • (c) adr-kit(ADR-0019)が型付き辺と整合 lint を標準提供した場合。
  • (d) Confirmation §5 の起票義務(ADR-0117 監査拡張)が期限を超過した場合。
• 対応: (a)(b) は該当 lint ルールを warning へ格下げして原因を個別案件化。(c) は移行を別途起案。(d) は起票の即時実施か本規約の縮退を代表取締役が判定。規約全体の撤回ではない。
• 判定タイミング: 受理から 3 ヶ月後(2026-09 想定)。初期移行の完了確認と兼ねる。
• 判定主体: 代表取締役。
• ロールバック手順: lint の error → warning 格下げは設定変更のみ(~5min)。宣言済み frontmatter 辺はデータとして無害なので残置。

コスト試算

• 初期(main 領分): 辺スキーマ定義 + クロスファイル lint ~200 行 ~3h(RQ-100 見積)。ADR-0107 抽出器への辺読み取り追加 ~1h(抽出器本体 ~3h は ADR-0107 で計上済み・本 ADR は差分のみ)。
• 初期移行(sub + main 分担): 機械抽出スクリプト ~2h。LLM 候補化と人間 PR レビュー ~3〜4h。受け入れ検査(層別サンプリング・relates_to 以外の各型から最低 2 件ずつ) ~0.5h。
• 合計 ~9.5〜10.5h。
• 継続: 起案ごとの辺宣言 ~2min(テンプレ化)。lint 保守は月 30min 未満を運用上限(超過は撤退条件 (a))。
• CI 実行時間目標: PR ごとのクロスファイル lint は 30 秒以内(超過時は増分チェック導入を再検討)。
• 削減効果: 関連 ADR の人手探索(延べ 2,506 参照の追跡)と置き換え確認を排除。行き先検証・送り先解決の人手レビューを機械検査に置換。
• 遅延連鎖の管理: 移行完了の 3 ヶ月判定タイミングから逆算した週次マイルストーンを設定(PR 分割粒度は 1 PR あたり想定レビュー時間 30 分以内を目安、約 1 週あたり 10 本ペース)。

Confirmation

• 検証手段:
  1. adr-lint 拡張(error 4 種)の CI 通過(PR ごと)。
  2. 新規 ADR の辺フィールド必須(欠落は lint error。該当なしは空配列を明示)。
  3. ADR-0107 実装後は adr-index --check が辺を含む adr-index.json の一致を検査(ADR-0130 の 3 点セットに乗る)。
  4. 本文限定参照(warning)の残数を月次で確認し、増加傾向なら起案テンプレ・パイプライン出力の見直しを案件化。
  5. 恒常監視の起票義務: 初期移行の完了判定までに、ADR-0117 の四半期サンプリング監査(参照 10 件無作為抽出・意味的整合確認)を ADR 間の辺へ拡張する個別 ADR を起票する。期限超過は撤退条件 (d) の発火条件。
  6. クロスファイル lint の CI 実行時間ベースラインを受理直後に計測し、30 秒閾値を超えたら増分チェック設計の起票を行う。
• 実行頻度: PR ごと(CI)。月次(warning 残数・lint 保守時間)。受理 3 ヶ月後(初期移行の完了判定)。
• 違反時の対応: dangling は行き先を作るか参照を落とす。片方向は逆辺を追記。状態不整合は status か辺のどちらかを修正。
• 移行の完了確認: 判定タイミングまでに、既存 129 本(受理時点の全数)に辺ブロックが存在し、受け入れ検査(層別サンプリングで relates_to 以外の各型から最低 2 件ずつ、不一致 2 件以上で再レビュー)を通過し、lint の error 昇格が完了していること。

参照 (References)

• 関連 ADR:
  • ADR-0107(Proposed・ADR 資産化): 本決定は出力③関係図・④AI 書き出しの入力データ規約。抽出器スキーマに影響するため main 実装着手前に確定する(本起案の締切根拠)。辺は adr-index.json に統合。Status バックフィル(時間的与件)の行き先。バックフィルの完了時期は ADR-0107 実装側で確定する(本 ADR の受理が 0107 実装着手の前提・バックフィルは初期移行の error 昇格前に完了)。依存は「本 ADR 受理 → 0107 実装 → 初期移行完了」の一方向で循環しない。RQ-098 系ゲートは未起案であり、実装時期は当該起案が所有する(本 ADR は前提となる辺データの整備のみ提供)。
  • ADR-0117(受理済): Covers:/Constrains:(縦 = 要件への辺)の ADR 全体横展開を決定済み。本決定の横の辺(ADR 間)と同じ frontmatter に同居(縦 = 0117 / 横 = 本 ADR)。「ID 参照は frontmatter 限定」「lint は構文的存在確認のみ・意味的整合は四半期サンプリング監査」の整理にも準拠し、横の辺への監査拡張は個別 ADR で起票する(Confirmation §5)。準拠・Refine。
  • ADR-0023(構造標準化): 本文構造は不変。準拠。
  • ADR-0031(メタデータ後付け): 追記は本経路に乗る。準拠。
  • ADR-0019(lint 体系): 整合 lint は本体系に追加。準拠・Refine。
  • ADR-0130(索引類自動生成規律): 辺データから作る生成物(関係図・index)は同規律の対象(スコープ的与件の行き先)。準拠。
• 関連 PR/Issue: RQ-100(3 モデル frontmatter SSoT 調査)、RQ-098(審査パイプライン送り先解決設計)。
• 外部資料: 構造 doc adr_structure_pyramid_principle.md D-1(行き先必須規約)、adr-tools の両端リンク型。
• 半年〜1年後の負債化リスク(将来監視項目):
  • 型の形骸化(撤退条件 (b) の 80% 閾値で監視)。
  • 意味誤分類の固定化(ADR-0117 監査拡張へ送る・Confirmation §5)。
  • frontmatter と参照節の二重管理 drift(warning 残数の月次監視、移行完了後 3 ヶ月で error 昇格の可否を再評価)。
  • パーサ地雷(frontmatter 重複キー等)による docs-build 停止 — 初期移行の一括追記時は docs-build 全件通過を必須チェックに含める。
  • 実装順の逆転(本 ADR の受理を ADR-0107 実装着手の前提に置く)。

Known Limitations / Escalated Residual Risks (HITL ratification required)

本 ADR は Cross-Validation で goalpost ループ検知 (2 連続却下・却下盲点が毎回移動) のため、自動審査を打ち切り「残余リスク付き Accept」として起票された (ADR-0109 Part4)。以下の未解決 critical 盲点は、人間レビュー (この PR の merge = 受理 / close = 却下) で最終判断すること。LLM critic による反復審査では収束しないと判定されたものであり、PR レビューが外部検証器となる。

未解決 critical 盲点:

• 初期移行でLLMが辺の型を大量誤分類しても受け入れ検査10件では統計的に検出できず、誤ったグラフがlint通過済みの正データとして固定される