ADR-0059: docs-nav-lint に R5 prefix-cross-doc-consistency rule を追加 (ADR-0055 拡張)

• Status: Accepted
• Mode: Standard
• Scope: platform
• Kruchten Type: Existence/Property
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-22 18:14
• 承認日時 (JST): 2026-05-22 18:30 (Pipeline 通常 flow v2 49/50 通過)
• Deciders: [email protected] (単独)

コンテキスト

1.1 背景 (Background)

ADR-0055 (PR #861/#862, 2026-05-19/20) で _config.json の nav prefix を <NS>.<group_number>.<page_index> 形式に刷新し、docs-nav-lint.mjs R4 で _config.json 内の prefix-group 整合を CI 検証している。一方、TOC として機能する docs/index.md の section header (A.01 architecture/ / I.05 05_how-to/ 等、PR #877 で整合化) と _config.json group prefix の機械整合は手動レビューに依存している。

1.2 現状 (Current State / As-Is)

• docs-nav-lint.mjs R1-R4 が _config.json 内整合を検証する。
• docs/index.md の section header (現 13 個) と _config.json group prefix (現 ~40 グループ) のクロスドキュメント整合は手動レビューに依存。
• PR #877 (2026-05-20) で docs/index.md 13 個の section header を ADR-0055 形式に 手動で更新 (~30min 実測)。これは sub session の audit (handover §Step 4-b) で偶然発覚した構造的脆弱性。

1.3 課題 (Problem)

片方を変更したときに整合が崩れるリスクが残存し、見過ごし得る漏れリスクがある。

痛みの定量化 (proxy 実測 + 推定 + 再評価タイミング):

• 実測サンプル (n=1): PR #877 (2026-05-20) で docs/index.md 13 section header の手動更新に ~30min (session log proxy ベース)
• 年間想定発生頻度: 6-12 回/年 (新 group 追加 / nav prefix 変更想定) → ~2.5-5h/年の手動 audit 工数
• 集計手順 (再現可能化):
  1. 過去 PR を gh pr list --search 'docs/index.md ## A.' で抽出
  2. 各 PR の diff から手動更新 section header 数を集計
  3. 平均処理時間 ~2-3min/section × 件数 = 工数推定
• 信頼区間: 実測 1 件のみのため推定区間は ±50% (1.25-7.5h/年)
• 再評価タイミング: Jr 入社 (2026-10) 後 2 ヶ月 (2026-12) で実測 n≥5 件に到達した時点で本 §1.3 を更新、信頼区間を狭める。1 年後 (2027-05-22) Review After にも明記

1.4 制約・要件 (Constraints & Requirements)

• ADR-0055 (NS prefix 形式) / ADR-0051 (docs-nav-lint.mjs SSoT 構造) と整合すること。
• ADR Immutability 原則を遵守 (ADR-0055 への corrigendum での吸収は不可)。
• 既存 docs-nav-lint workflow に統合可能であること (新規 workflow を増やさない)。
• 個人開発フェーズの保守コストに見合うこと (依存追加は最小限)。
• 将来の Jr 入社 (2026-10) 時に規約として説明可能であること。

1.5 目標 (Goals / To-Be)

• docs/index.md の section header と _config.json group prefix のクロスドキュメント整合を CI で機械検証する。
• 手動 audit 工数 ~2.5-5h/年を撤廃する。
• Non-Goals: ADR-0057 (docs-link-check.mjs) との統合 / 個別 rule 別ファイル分割 (将来検討)。

決定

scripts/docs-nav-lint.mjs に R5 (prefix-cross-doc-consistency) rule を追加し、docs/index.md の ^## <NS>.<group_number> 形式 section header が _config.json 内の group prefix と整合するかを regex 方式で検証する。既存 docs-nav-lint workflow と同 job に統合し、.docs-nav-lint-allowlist.json に index_md_section_special_cases フィールドを新設して special case を扱う。初期は WARN で運用し、3 ヶ月後に false-positive 0 + true-positive ≥ 1 を満たせば ERROR に昇格する。

判断基準 (Decision Drivers)

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

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

3.2 評価軸 × 案スコア表

加重和は K.O. 通過候補 (採択案 / 案 X3) のタイブレーク用。採択案が #maintainable (依存追加なし) で X3 を上回り選定。

検討した代替案 (Alternatives Considered)

• 採用案 (R5 を docs-nav-lint.mjs に追加, regex 方式, 同 job 統合):
  • Good: ADR-0055 の自然延長、R4 と同 pattern、保守コスト最小、CI 起動オーバーヘッドゼロ
  • Bad: docs/index.md のフォーマット規約に依存 (将来 index.md 形式変更時に rule 改修必要)
• 案 X1: 手動レビュー継続 (DOC-OPS-02 のまま):
  • Good: 工数ゼロ
  • Bad: 構造的脆弱性が残存、PR #877 のような事後修正が発生し続ける、年間 ~2.5-5h の audit 工数
  • 不採用理由: K.O. 不通過 (#reliable = 1, 構造的検出不能)
• 案 X2: ADR-0055 への corrigendum で吸収 (新規 ADR を起案しない):
  • Good: ADR 数増えない
  • Bad: ADR Immutability 原則と齟齬 (corrigendum は誤字修正範囲、新 rule 追加は越える)、ADR-0031 (Kruchten Type 遡及追加) と比較すると本件は機能追加なので別 ADR が筋
  • 不採用理由: K.O. 不通過 (#suitable = 1, Immutability 違反)
• 案 X3: Markdown AST (remark/unified) 方式:
  • Good: 厳密な header 解析、コードブロック内擬似 header 誤検出回避
  • Bad: 依存追加 (remark / unified)、対象 1 ファイル単純 regex で十分、過剰設計
  • 不採用理由: K.O. は通過するが #maintainable で採択案に劣る (加重和 0.745 < 0.918)

実装方式選定詳細

検証ロジック

1. R5 検証対象: docs/index.md の ^## <NS>.<group_number> 形式 section header
2. 検証内容: section header の <NS>.<group_number> 部分が _config.json 内に存在する group prefix と一致するか
3. 違反例: docs/index.md に ## A.99 nonexistent-group/ があるが _config.json には arc42.99_* group が存在しない → FAIL (error)
4. 違反例: _config.json に arc42.07_deployment (= A.07) があるが docs/index.md に ## A.07 * section が存在しない → WARN (削除済 group の可能性、または index.md 未更新)

Special case 除外機構 (allowlist 設計)

.docs-nav-lint-allowlist.json に index_md_section_special_cases フィールド (string[] of regex patterns) を新規追加:

{
  "files": [...],
  "patterns": [...],
  "index_md_section_special_cases": [
    "^## トップレベル$",
    "^## ナビゲーション補助$"
  ]
}

R5 実行時、上記 regex にマッチする section header は <NS>.<group_number> 形式を満たさなくても skip。初期想定 ≤ 5 件、超過時は ADR 再評価。

影響 (Consequences)

5.1 正の影響 (Good)

• TOC (docs/index.md) と nav SSoT (_config.json) の機械整合が確立される。
• 手動 audit 工数 ~2.5-5h/年を撤廃。
• docs/index.md 更新漏れの構造的防止 (PR #877 と同種の事後修正が発生しなくなる)。
• ADR-0055 の自然延長として、ADR-0051 (docs-nav-lint.mjs SSoT 構造) パターンを補強。
• 将来 stakeholder (Jr 入社 2026-10) への規約説明が CI 出力で機械的に可能。

5.2 負の影響 (Bad)

• docs/index.md のフォーマット規約 (H2 section header) に依存し、将来 index.md 形式変更時に rule 改修が必要。
• false-positive リスクがあり、special case の allowlist 運用が発生する。
• docs-nav-lint.mjs が docs-nav-lint.mjs:167 → ~200-220 行に肥大化 (将来 R6-RN 追加で 500 行超過する負債化リスク)。
• 継続運用コスト: 新 group 追加時の R5 違反対応 ~5-10min/件 × 6-12 件/年 = ~1-2h/年。

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

• R5 を error 化 vs warn 化: 初期は WARN (3 ヶ月運用) → false-positive 0 + true-positive ≥ 1 なら ERROR 昇格。
• Deciders / 利害関係者: Decider = 代表取締役 (単独)、事実上のレビュアー = sub workspace audit (handover §Step 4-b)、将来 stakeholder = Jr 入社 (2026-10)。
• 改修対象: scripts/docs-nav-lint.mjs (+30-50 行)、.docs-nav-lint-allowlist.json (+ 1 フィールド)。
• 検証対象: docs/index.md の section header (現 13 個)、docs/_config.json の group prefix (現 ~40 グループ)。
• CI 結合: 既存 docs-nav-lint workflow に統合 (新規 workflow なし)。

コスト試算

検証可能な完了条件

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証手段: scripts/docs-nav-lint.mjs の R5 ロジック + 既存 .github/workflows/docs-nav-lint.yml への組み込み。.docs-nav-lint-allowlist.json の index_md_section_special_cases 配列サイズも同 lint で監視 (≤ 5 件超過時に WARN)。
• 実行頻度: PR ごと (docs/index.md または docs/_config.json 変更時にトリガ)、加えて main への push 時。
• 違反時の対応: ERROR なら PR マージブロック、WARN なら通知のみ。false-positive と判定なら .docs-nav-lint-allowlist.json の index_md_section_special_cases に regex 追加 (allowlist 上限 5 件超は ADR 再評価)。

撤退条件 (Rollback Plan)

• 3 ヶ月後 (2026-08-22): R5 違反検出件数 + false-positive 率を評価。false-positive が常態化 (allowlist 5 件超) なら revert PR で R5 削除 + DOC-OPS-02 を TODO_future.md §7 で再 open。
• 6 ヶ月後 (2026-11-22): 採用ツール (docs-nav-lint.mjs) の総行数が 500 行超なら個別 rule 別ファイル分割を検討 (ADR-0054 §X5 パターン)。
• 撤退判断指標:
  • false-positive 率 > 30% (常態化) → revert
  • 3 ヶ月で違反検出 0 件 + 真の broken 0 件 → 「過剰防衛」と判断、WARN 維持 or 削除
  • docs-nav-lint.mjs 維持コストが他 rule の 2 倍超 → 撤退

長期影響 / Review After

• Review After:
  • 3 ヶ月後 (2026-08-22): WARN → ERROR 昇格判断、false-positive 率評価
  • 6 ヶ月後 (2026-11-22): docs-nav-lint.mjs 総行数 / rule 数の肥大化評価
  • 1 年後 (2027-05-22): ADR-0057 docs-link-check.mjs との将来統合検討
• 負債化リスク:
  • リスク 1: lint rule 群肥大化 (R1-R5 → 将来 R6-RN 追加で docs-nav-lint.mjs が 500 行超過) → individual rule 別ファイル分割パターン (ADR-0054 §X5 で確立) への移行検討
  • リスク 2: docs/index.md フォーマット規約の将来変更 (例: H2 → H3 への階層化、別ファイルへの TOC 切り出し) で R5 改修が必要
  • リスク 3: ADR-0057 (docs-link-check.mjs) との将来統合 (docs-lint-suite.mjs umbrella script、ADR-0057 §7.2 で言及済) で R5 も移行対象

参照 (References)

• 関連 ADR:
  • ADR-0055 (Refines): NS prefix 形式の根拠、R4 の前例
  • ADR-0051 (基盤): docs-nav-lint.mjs 全般、R1-R4 の SSoT 構造
  • ADR-0031 (比較対照): Kruchten Type 遡及追加パターンと本件 (新規 rule) の Immutability 観点比較
  • ADR-0057 (将来統合候補): docs-link-check.mjs、§7.2 で 3 ADR 統合可能性に言及
  • ADR-0054 (パターン参照): §X5 個別 rule 別ファイル分割パターン
• 関連 PR/Issue:
  • PR #877 (実問題発生事例): docs/index.md 13 section header 手動更新 (~30min)
  • PR #861/#862 (ADR-0055 実装): R4 の前例
  • TODO_future.md §7 DOC-OPS-02 (本 ADR の起票元): 本 ADR Accepted 時に「完了 (PR #NNN)」マーク
• 外部資料: -

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

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v1 (53 行版) で 39/50 差し戻し → 8 採点項目に対応する改善反映 v2 → 49/50 で Standard 閾値 40 + Critical 閾値 45 双方クリア。ADR-0056 §8 / ADR-0058 §11 / ADR-0057 §8 で確立した §audit history パターンの 第四適用例 (本 ADR は ADR-0057/0058 と異なり通常 flow で auto-PR 生成された第一例)。デフォルトでは折りたたまれており、▶ をクリックで展開する。

Status 遷移

• v1 起案 (2026-05-22 KV 投入) → Pipeline 通常 flow 39/50 差し戻し
• v2 改善 (8 採点項目に対応) → Pipeline 再投入 → 49/50 通過 → auto-PR #904 生成 (Proposed)
• 本 PR で Status: Proposed → Accepted に更新、§1.3 改善余地 1 件を同時反映