ADR-0123: DRP frontmatter を common/type/page の3層モデルで定義し lint 強制する

• Status: Accepted
• Mode: Standard
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-08 10:08
• 承認日時 (JST): 2026-06-08 10:26（審査 46/50 PASS → PR #1533 merge により受理）
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

scripts/adr-lint.mjs の frontmatter 強制対象は 7 ディレクトリのみで、docs/_internal/03_decisions/decision_pipeline/（DRP）は非強制のまま放置されている。ADR-0058 で frontmatter lint と ALLOWED_TYPES/STATUSES の SSoT を整備した経緯はあるが、DRP には適用されていない。

§1.2 現状 (As-Is)

実査（2026-06-07、63 件）の結果、id 欠落 29 件、type enum 外 29 件（operator-prompt 17 / implementation-prompt 9 / validation-report 2 / planning 1）、status enum 外 27 件（archived 25 / accepted 1 / ready-to-execute 1）、audience 保有 34 件のみ。

§1.3 課題

共通項目（id・type・status）と種別固有項目（target_session・target_endpoint・adr・verdict 等）が無秩序に混在し、機械判別・全文検索・related 逆引きが安定しない。新規 DRP 文書を追加しても欠落が CI で検出されず、規約が形骸化している。

§1.4 制約・要件

• 既存 7 ディレクトリの強制トリオ（id/type/status）とリポ全体で統一する
• ADR-0058 の doc-consistency rule（enum と doc §6/§7 の双方向同期）を破らない
• 強制 ON の順序を誤って CI を一斉 fail させない
• 移行工数は約 1.5 日以内（Standard 想定）
• 新規 DRP 追加時の運用負荷は 1 件あたり 5 分以内

§1.5 目標 (To-Be)

DRP frontmatter を common/type/page の 3 層モデルで規約化し、adr-lint.mjs で type→必須キー検査を強制する。Non-Goals: _internal/ 全体の一括強制（Phase 2 候補）、audience の必須化。

決定

frontmatter を common / type / page の 3 層モデルとして規約化し、DRP 配下を lint 強制対象に追加する（段階導入の Phase 1）。

1. common 層（全 doc 必須・CI 強制）: id / type / status（既存 7 ディレクトリの強制トリオに一致）。audience は推奨（page 層・任意）。
2. type 層（type 値ごとに必須・CI 強制）:
   • operator-prompt: target_session, target_endpoint, date
   • implementation-prompt: target_session, target_repo, date, adr, adr_status
   • validation-report: target_adr, draft_id, verdict, date
   • spec / how-to / prompt / setup / policy: 追加必須なし（common のみ）
3. page 層: ページ固有キーは自由（強制しない）
4. enum 拡張: ALLOWED_TYPES に operator-prompt / implementation-prompt / validation-report を、ALLOWED_STATUSES に archived / accepted を追加。ready-to-execute は ALLOWED_STATUSES に正式追加し draft（未完成）との意味差を frontmatter-lint_rules.md §7 に明記（盲点 #3 反映）。いずれも §6/§7 と双方向同期（ADR-0058）。
5. SSoT 化: type→必須キーのマッピングを frontmatter-schema.json 等の単一設定ファイルに外出しし、adr-lint.mjs と doc 生成スクリプトの両方が同ファイルを読む構造とする（盲点 #1 反映、二重管理回避）。
6. ENFORCED_FRONTMATTER_DIRS に decision_pipeline/ を追加し、adr-lint.mjs に「type→必須キー」検査を実装する。
7. ディレクトリ×type マトリクス検証: 現 Phase では警告レベルで実装し、強制化は Phase 2 候補（盲点 #2 反映）。
8. id 採番規則: DRP 文書の id は ADR-0117 drp-id-conventions に従い drp-<slug>（kebab-case・ファイル名由来）とする。既存 33 文書がこの形式に準拠済み。backfill 前に全 doc 重複チェック（grep）を実行する（盲点 #5 反映）。※当初 §8 は DRP-YYYYMMDD-NNN と記載していたが、ADR-0117 が DRP- 接頭辞を将来のスコープ修飾子用に予約済みであり既存規約と衝突するため Corrigendum 1 で訂正（下記参照）。
9. archived 文書の変更制限: archived 遷移後の上書きを禁止し、change_log フィールド必須・Git タグによる保存ポイント記録を運用ルールに追加（盲点 #9 反映、電帳法 §10 対応）。

移行順序: schema 外出し → id backfill 29 件 + type 別キー補完 → enum 拡張 + doc §6/§7 同期 → enforced dir 追加 → CI 強制 ON。順序を逆にすると既存全件が一斉に fail する。backfill PR は type 別 10 件以下 の単位に分割し、各 PR に CI log URL を添付（盲点 #4 反映）。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸（#maintainable / #reliable）の score < 3 は不採用。

3.2 評価軸 × 案スコア表

案D は加重和最高だが、既存 adr-lint.mjs カスタムロジックとの統合コスト・YAML パース方式の差異により Phase 1 では見送り、Phase 2 で再評価（盲点 #7 反映）。

検討した代替案 (Alternatives Considered)

• 案A: 文書規約のみ（lint 強制なし） — 強制なしでは新規追加時の欠落を検出できず、現状と同じく形骸化する（#reliable K.O. 不通過）。
• 案B: 全 _internal/ を一括強制 — 118 件規模の backfill が必要で Phase 1 スコープ超過。DRP に限定して効果検証後に Phase 2 で横展開（#operable 不可）。
• 案C: common に audience も必須化 — audience 保有は 34/63 で必須化すると 29 件の追加 backfill が発生し、既存 7 ディレクトリの強制トリオと乖離する。推奨どまり。
• 案D: JSON Schema (Draft-07) + AJV による宣言的検証 — if/then 構文で type→必須キーを宣言的に記述でき、スキーマがドキュメントを兼ねるため長期保守性で優位。ただし既存 adr-lint.mjs カスタムロジックとの統合コスト、YAML anchor/alias パース方式の差異検証が必要なため Phase 2 候補とする（盲点 #7 反映）。

影響 (Consequences)

§5.1 正の影響 (Good)

• DRP 文書の機械判別・検索・related 逆引きが安定する
• 新規 DRP 文書の frontmatter 欠落を CI が自動ブロックする
• type ごとの必須キーが明文化され、起案テンプレートの自動生成が可能になる
• common 層が既存 7 ディレクトリと一致し、規約がリポ全体で統一される
• frontmatter-schema.json の SSoT 化により、新 type 追加時の更新箇所が 1 箇所に集約される

§5.2 負の影響 (Bad)

• 既存の id backfill 29 件・type 別キー補完・status 正規化 27 件の初期工数が発生する
• ALLOWED_TYPES / ALLOWED_STATUSES 拡張に伴い frontmatter-lint_rules.md の同期更新が必要
• backfill PR を type 別 10 件以下に分割するため PR 件数が増え、レビュー回数が増加する
• archived 文書の change_log フィールド必須化により、既存 25 件の archived backfill が追加発生する

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

• 強制 ON 順序リスク: 順序を誤ると CI が一斉 fail する → 移行順序を ADR に明記して回避
• enum 拡張と doc 同期ずれ: doc-consistency rule が fail する → 同一 PR で両方を変更
• グローバル enum の誤付与リスク: operator-prompt 等が既存 7 ディレクトリに誤付与される懸念（盲点 #2）→ ディレクトリ×type マトリクス検証を警告レベルで現 Phase 実装、強制は Phase 2
• YAML パーサ挙動差: anchor/alias・block scalar の展開差で誤通過の可能性（盲点 #6）→ adr-lint.mjs テストスイートに fixture 3 種以上追加し CI で実行（Confirmation 項目）
• sunk cost 効果: 違反 0 件 KPI 達成後に実態乖離が進んでもダミー値で回避される懸念（盲点 #8）→ Review After 議題に「ダミー値・空文字件数の計測（grep クエリ）」を明示
• AJV 採用見送り: 案D は将来検討、現 Phase は既存実装拡張で進める

§5.4 ステークホルダー別影響 (Stakeholder Impact)

採点 #5 の指摘（影響が単独 Decider に偏り、レビュアー側が薄い）を受けて整理する。1 人法人のため Decider と一次レビュアーは同一人物だが、役割ごとに影響が異なる。

レビュアー側の主リスクは「backfill PR 分割が 1 人運用で自己レビュー形骸化しやすい」点であり、CI ゲートの厳格性（必須キー検証 + fixture テスト）で担保する設計とする（テナント層評価の留意事項と一致）。

コスト試算

採点 #8 の指摘（一括 1.5 日では根拠が粗い）を受け、決定で拡張したタスク（schema 外出し・archived change_log・PR 分割）を含めて実測ベースで分解する。

• frontmatter-schema.json 外出し（type→必須キー定義 + adr-lint/doc 生成スクリプト双方の読込配線）: 約 0.5 日
• adr-lint.mjs 改修（3層検証 + type→必須キー検査 + ディレクトリ×type マトリクス警告）: 約 0.5 日
• enum 拡張（ALLOWED_TYPES 3 値 / ALLOWED_STATUSES 3 値）+ frontmatter-lint_rules.md §6/§7 双方向同期: 約 0.5 時間
• YAML anchor/alias・block scalar fixture 3 種以上 + テスト追加: 約 0.25 日
• id backfill 30 件（drp-<slug> 採番 / ADR-0117 準拠 + 全 doc 重複チェック）: 約 0.5 日
• type 別キー補完 + status 正規化 27 件: 約 0.5 日
• archived 25 件の change_log 補完 + Git タグ保存ポイント記録: 約 0.5 日
• backfill PR 分割（type 別 10 件以下・複数 PR）のレビュー・CI log 添付: 約 0.25 日
• 合計: 約 3 日（当初の 1.5 日想定から、schema 外出し・archived change_log・PR 分割の追加スコープ分を加算）
• 運用コスト: 新規 DRP 文書追加時の追加記入は 1 件あたり 5 分以内

撤退条件 (Rollback Plan)

採点 #7 の指摘（強制 OFF は 1 行で明確だが enum/schema/archived 制限の戻し手順が薄い）を受け、構成要素ごとに段階的な戻し手順を定義する。全要素が独立に巻き戻し可能で、backfill 済みデータは破壊せず温存する設計とする。

段階的ロールバック手順（影響の小さい順）

1. CI 強制のみ無効化（最小）: ENFORCED_FRONTMATTER_DIRS から decision_pipeline/ を削除する 1 行で即座に無効化。検証ロジック・enum・schema・backfill 済みデータは温存され、再有効化は同 1 行の復活のみ。
2. type→必須キー検証の縮小: frontmatter-schema.json の該当 type エントリを削除/縮小（schema 外出し済みのため adr-lint.mjs 改修不要）。doc §6/§7 を同一 PR で同期。
3. enum 拡張の撤回: ALLOWED_TYPES / ALLOWED_STATUSES から追加 6 値を削除する場合、先に該当値を使う既存文書を別 enum 値へ再正規化してから削除する（逆順だと既存全件 fail）。doc §6/§7 を同一 PR で同期（doc-consistency rule 維持）。
4. archived 制限の解除: change_log 必須化と上書き禁止運用ルールを撤回。既に付与した change_log フィールド・Git タグは温存（残置は無害）。
5. schema ファイルの完全撤去（最大）: frontmatter-schema.json を削除し adr-lint.mjs の読込配線を revert。これは ADR 全体の撤回に相当し、上記 1〜4 を全て実施した後に行う。

backfill 済みデータの扱い

id（drp-<slug>）・type 別キー・正規化済み status は、強制 OFF 後も有効な frontmatter として残置する（削除不要・監査証跡として有益）。戻す必要が生じるのは enum から値を削除する場合のみで、その際は手順 3 の再正規化で対応する。

撤退トリガー

• 強制 ON 後 3 ヶ月時点で DRP 文書追加時の運用負荷が想定（1 件あたり 5 分以内）を 2 倍超過する場合、type 層必須キーを縮小して再評価する（手順 2）
• type 別必須キーが実態と乖離し例外（lint 警告モード or grep で計測したダミー値・空文字）が 5 件を超えたら表を見直す（手順 2）
• Review After: 2026-09-07（3 ヶ月後）に「ダミー値・空文字件数」「例外件数」「新規 DRP 追加時の平均所要時間」を計測

Confirmation

• 検証手段: ① adr-lint.mjs の CI 実行で decision_pipeline/ 配下の frontmatter lint 違反が 0 件 ② 新規 PR で common/type 必須キーを欠いた DRP 文書を追加すると CI が fail（fixture テスト含む）③ adr-lint-doc-consistency rule pass（frontmatter-schema.json ↔ frontmatter-lint_rules.md §6/§7 一致）④ id 重複・欠落 0 件 ⑤ YAML anchor/alias・block scalar を含む fixture 3 種以上が CI で実行され全 pass
• 実行頻度: PR ごと（CI 自動）+ 月次（id 重複監査）+ Review After（2026-09-07）に sunk cost 指標を含む包括レビュー
• 違反時対応: CI fail は merge ブロック。doc-consistency rule 違反は同一 PR で同期修正。Review After で例外 5 件超なら撤退条件発動し type 層必須キーを縮小再評価。

参照 (References)

• 関連 ADR: ADR-0058 (frontmatter lint と ALLOWED_TYPES/STATUSES SSoT を extend), ADR-0041 (type-first プロセスを DRP に適用), ADR-0115 (知識層の責務分離・DRP 文書管理方針と整合), ADR-0117 (drp-id-conventions・DRP 文書 id 形式の正典)
  • ADR-0129 (エージェント設定の階層化) — エージェント設定 (CLAUDE.md / .claude/rules) の読み分け機構は ADR-0129 が supersede。読み分けの正式手段はファイル配置と paths frontmatter であり、本 ADR の audience frontmatter はその用途では役目を終える。人間向けドキュメントの frontmatter 規約 (本 ADR の common/type/page 3 層モデル) は引き続き有効。
• 関連 PR/Issue: PR #1533（本 ADR の起案 PR）
• 外部資料: 電帳法 §10（archived 文書の訂正前原本保存義務）, 中小企業会計指針, JSON Schema Draft-07（案D 参考）

Corrigendum

Corrigendum 1 (2026-06-08): id 採番規則を ADR-0117 drp-id-conventions に委譲

• 訂正内容: §8 の id 形式を DRP-YYYYMMDD-NNN → drp-<slug>（ADR-0117 drp-id-conventions 準拠）に訂正。コスト試算・撤退条件の同形式参照も追従。
• 理由: 当初 §8 の DRP-YYYYMMDD-NNN は審査パイプラインの盲点 #5（id 採番規則が未定義）を埋めるため body-gen が生成した値だが、起案時に既存の ADR-0117 drp-id-conventions（2026-06-04 受理・DRP 文書 id の正典）を参照していなかった。同規約は (1) 既存 33 文書が drp-<slug> 形式で準拠済み、(2) DRP- 接頭辞を将来の全社展開時のスコープ修飾子用に予約、と定めており、DRP-YYYYMMDD-NNN を採用すると同一ディレクトリに 2 体系が混在し ADR-0117 違反かつ本 ADR の KPI「id 一貫性」に反する。
• 検出経緯: 実装着手時（id backfill 前）の既存規約照合で発覚。審査の consistency ゲートは「CONFLICT なし・INFO」と判定しており、ADR 横断の id 形式衝突を検出できていなかった（審査取りこぼしの実例として記録）。
• 影響範囲: 決定の本旨（common/type/page 3層モデル + lint 強制）は不変。id の形式パラメータのみの訂正。