bizlp frontmatter Lint Rule Reference (ADR-0058 / 4 rule + 許容値 SSoT)

Status: SSoT (ADR-0058 で確立、2026-05-22) 対象: docs/ 配下 7 ディレクトリ (78 files) の起案者・レビュアー・AI Agent (Claude / Gemini / GPT) 検証: scripts/adr-lint.mjs Phase 4 本体 + scripts/adr-lint-doc-consistency.mjs (本 doc ↔ code ↔ _meta/templates/ の 3 way 整合、Phase 2 で実装予定) 根拠 ADR:

• ADR-0058 — frontmatter Lint Rule Reference SSoT 確立
• ADR-0054 — 10 節構造の確立
• ADR-0039 — frontmatter 起源 (Phase 4-b)

1. Purpose & Scope

本 doc は scripts/adr-lint.mjs:179-220 に実装された 全 4 frontmatter rule + 許容値 2 表 (types 19 種 / statuses 8 種) + type 層必須キー (ADR-0123) + Enforced Directories 8 件 の規約を 1 箇所に集約した Single Source of Truth (SSoT) である。ADR-0039 §移行計画 Phase 4-b に分散していた根拠を、Discovery (Summary Table) + Detail (各 rule 深掘り) + 許容値表の三層構造で集約する。

対象読者:

• doc 起案者: docs/{domains,architecture,research,data,operations,_meta,_nav}/ 配下に新規 .md を追加する前に §4 Summary Table と §6 / §7 許容値表を読む
• PR レビュアー: CI で fm-* rule が fail した時の rule 解釈根拠として参照
• AI Agent: doc 起案・レビュー時に frontmatter 構造を機械判別する根拠
• Jr 入社時 (2026-10): onboarding 主要参照先 (CLAUDE.md / git_workflow.md と並ぶドキュメント運用 SSoT)

Non-Goals: adr-lint.mjs 本体の autofix 実装 / 過去 ADR-0039 / ADR-0058 本文の書き換え (本 doc から過去 ADR への片方向参照リンクのみ追加、Immutability 遵守)。

2. Severity Legend

3. Category Legend

全 4 rule とも validation カテゴリ。将来 metadata (例: related: の link 存在検証) や structure (例: YAML インデント整合) 系 rule が追加された場合は本表を拡張する。

4. Summary Table (Discovery Layer)

集計: error 5 件 / warn 1 件 / 対象: 7 既存ディレクトリ + decision_pipeline/ (§8 参照、_meta/templates/ は lint 対象外)。type 層 3 層モデルは ADR-0123 で追加。

5. Validation Rules (Detail)

5.1 fm-missing

id: fm-missing
severity: error
category: validation
since: 2026-05-14  # ADR-0039 採択日
status: active
fixable: false
description: frontmatter (---) ブロックが冒頭に存在
related_adrs: [ADR-0039, ADR-0058]

Rationale

ENFORCED_FRONTMATTER_DIRS (§8) 配下の .md は冒頭に YAML --- ブロックが必須。これにより AI Agent が doc 種別 (type) と運用状態 (status) を機械判別でき、人間レビュー前の自動振り分け・検索・分類が可能になる。違反すると AI Agent が doc 性格を読み取れず、検索 index 構築や related: 逆引きが破壊される。

❌ FAIL Example

# 仕様書タイトル

本文...

✅ PASS Example

---
id: spec-feature-x
type: spec
status: active
---

# 仕様書タイトル

References

• ADR-0039 §移行計画 Phase 4-b: frontmatter 必須化 (line 124)
• scripts/adr-lint.mjs:208: 実装本体 (if (!fm) return [{ rule: 'fm-missing', ... }])
• 起源: arc42 + MADR ハイブリッド構造の機械判別要件 (ADR-0039 §決定)

5.2 fm-required

id: fm-required
severity: error
category: validation
since: 2026-05-14
status: active
fixable: false
description: 必須キー id / type / status が存在
related_adrs: [ADR-0039, ADR-0058]

Rationale

frontmatter ブロック内に id / type / status の 3 キーが必須。id は doc 内部参照と link rewriting の anchor、type は AI Agent の自動分類根拠、status は廃止 doc の検索除外に使用する。1 つでも欠けると Site Generator (scripts/docs-build.mjs) の nav 整合性 check や related: 逆引きが破綻する。任意フィールド (related / audience / legacy_id / date) は本 rule の対象外。

❌ FAIL Example

---
type: spec
status: active
---

# id 欠落

---
id: spec-x
status: active
---

# type 欠落

✅ PASS Example

---
id: spec-feature-x
type: spec
status: active
related:
  - ../../adr/0042-...md
legacy_id: ""
---

References

• ADR-0039 §75: 「全ファイルに id / type / status / related / legacy_id を含む frontmatter を必須化」
• scripts/adr-lint.mjs:209-211: 実装本体 (for (const key of ['id', 'type', 'status']) { if (!fm[key]) errs.push(...) })

5.3 fm-type-enum

id: fm-type-enum
severity: error
category: validation
since: 2026-05-14
status: active
fixable: false
description: type 値が ALLOWED_TYPES (19 種、§6) に含まれる
related_adrs: [ADR-0039, ADR-0058, ADR-0123]

Rationale

type 値は §6 Allowed Types Reference の 19 種に限定される。任意値を許すと AI Agent が「research-foo」「spec-v2」のような表記揺れ造語を作り、type: フィルタ検索が機能しなくなる。新 type 追加は schema + doc 同時更新 (scripts/frontmatter-schema.json の allowedTypes + 本 doc §6 表 + 該当する _meta/templates/*.md) を必須とし、scripts/adr-lint-doc-consistency.mjs の 3 way CI で機械強制する (ADR-0123: SSoT は schema へ移行)。

❌ FAIL Example

---
id: spec-x
type: specification   # spec ではなく specification
status: active
---

---
id: research-x
type: invalid-type   # ALLOWED_TYPES に未登録 (架空の値)
status: active
---

✅ PASS Example

---
id: spec-x
type: spec       # §6 #1
status: active
---

References

• ADR-0039 §移行計画: type 区分
• scripts/frontmatter-schema.json allowedTypes: 定義本体 (19 種、SSoT・ADR-0123)
• scripts/adr-lint.mjs checkFrontmatter: 実装本体 (if (fm.type && !ALLOWED_TYPES.has(fm.type)) errs.push(...))
• §6 Allowed Types Reference: 19 種の意味と主な配置先

5.4 fm-status-enum

id: fm-status-enum
severity: error
category: validation
since: 2026-05-14
status: active
fixable: false
description: status 値が ALLOWED_STATUSES (8 種、§7) に含まれる
related_adrs: [ADR-0039, ADR-0058, ADR-0123]

Rationale

status 値は §7 Allowed Statuses Reference の 8 種 (active / deprecated / superseded / draft / proposed / archived / accepted / ready-to-execute) に限定される。任意値を許すと「廃止」「old」「working」のような表記揺れが発生し、検索 index で「現役 doc のみ」を絞り込めなくなる。deprecated (非推奨だが残置) と superseded (後継 doc に置換) の使い分けは ADR-0039 の運用方針に従う。

❌ FAIL Example

---
id: spec-x
type: spec
status: unknown-state    # ALLOWED_STATUSES に未登録 (架空の値)
---

---
id: spec-x
type: spec
status: deprecate   # ALLOWED_STATUSES の表記揺れ (架空の値)
---

✅ PASS Example

---
id: spec-x
type: spec
status: active      # §7 #1
---

---
id: spec-x-old
type: spec
status: superseded  # 後継 doc に置換済 (related: で後継を指す)
---

References

• ADR-0039: status 区分
• scripts/frontmatter-schema.json allowedStatuses: 定義本体 (8 種、SSoT・ADR-0123)
• scripts/adr-lint.mjs checkFrontmatter: 実装本体 (if (fm.status && !ALLOWED_STATUSES.has(fm.status)) errs.push(...))
• §7 Allowed Statuses Reference: 8 種の意味

6. Allowed Types Reference

ALLOWED_TYPES (19 種、SSoT=scripts/frontmatter-schema.json allowedTypes):

新 type 追加時の手順 (3 way 整合必須):

1. scripts/frontmatter-schema.json の allowedTypes に追加 (SSoT・ADR-0123)
2. 本表 §6 に行を追加 (#, Type, Description, 主な配置先)
3. type 層必須キーがあれば frontmatter-schema.json の typeRequiredKeys に定義 + §6.1 に追記
4. 該当する _meta/templates/*.md のテンプレートを追加 or 既存テンプレの type: 値を整合
5. scripts/adr-lint-doc-consistency.mjs の 3 way CI が schema ↔ doc §6 ↔ templates 整合を検証

6.1 Type 層必須キー (ADR-0123 3 層モデル)

scripts/frontmatter-schema.json の typeRequiredKeys。common 層 (id/type/status) に加え、以下の type は固有キーが error で必須 (fm-type-required-key):

その他の type (spec / how-to / prompt / setup / policy 等) は common のみで type 層追加なし。ディレクトリ×type マトリクス検証は現 Phase では warn (fm-dir-type-matrix)、強制化は Phase 2 候補。

7. Allowed Statuses Reference

ALLOWED_STATUSES (9 種、SSoT=scripts/frontmatter-schema.json allowedStatuses):

注: ADR 本体の ## Status セクション (Proposed / Accepted / Rejected / Superseded / Umbrella) とは別軸 (frontmatter は小文字、ADR 本体は Capitalize)。frontmatter の status: は doc 運用ライフサイクルを表し、ADR 自体の決定ライフサイクル (MADR) とは独立だが、proposed / umbrella は ADR Status と意味が重なる (ADR-0050 / ADR-0152 由来の運用整合)。

7.1 Recommended audience values (任意 · 非強制)

audience は 任意フィールドであり lint 強制対象外（§5.2 / commonRequired は id/type/status のみ・scripts/frontmatter-schema.json に audience 不在）。下記は「値を書く場合の推奨値域」であって、欠落は違反ではない。

ADR-0045 ↔ ADR-0123 の整合: ADR-0045 §1.5 は type/status/audience の3点必須化を目標としたが、後発の ADR-0123 が common 必須トリオを id/type/status に確定し、audience 必須化（案C）を明示的に却下（保有34/63で必須化は29件の追加 backfill + 既存7ディレクトリの強制トリオと乖離）。したがって frontmatter モデルの現行正典は ADR-0123であり、audience は「推奨・任意」に確定（2026-06-09 doc セッションで再確認・確定）。

ADR-0129 による役目の限定（読み分け用途は終了）: エージェント設定（CLAUDE.md / .claude/rules/）の読み分けでは audience frontmatter は役目を終えた。読み分けの正式手段はファイル配置と path-scoped rules（paths glob）（ADR-0129 が決定・ADR-0123 の該当用途を supersede）。audience 値そのものは引き続き人間向けドキュメントの読者明示（および将来の RAG メタデータ用途）として有効で、本節の推奨値域はその用途に対する規約。

推奨値域（3値）:

実 frontmatter の audience 値（2026-06-09 実測・frontmatter ブロック内のみ集計）: both(98) / agent(25) / human(3) / non-engineer(1)。表記揺れは実質 1 件のみ。

正規化（実対象 1 件）:

訂正（2026-06-09）: 本節初版は RQ-045/046 の研究結果ファイル本文（human \| agent \| both / [solo, jr, agent, auditor] / developer \| operator \| future-self / internal 等、audience enum を論じた本文）を frontmatter と誤検出し「7 件の outlier」と記載していた。当該ファイルはそもそも frontmatter を持たず（2026-06-09 の Phase 2 backfill で id/type/status を付与・本文は不変）、実 frontmatter の audience outlier は non-engineer の 1 件のみだった。

audience に main/doc（ワークスペース役割）を入れない: 「doc はこの doc を読み飛ばし可」という役割別の読み分けは human/agent とは別軸であり、ディレクトリ所有（workspace_rules.md ファイルマトリクス）と nested CLAUDE.md で扱う（ADR-0045 Phase 2 handover item 5）。これは上記 ADR-0129 の決定（読み分けはファイル配置と paths が正式手段）と同じ方向で、エージェント向けの読み分けを audience frontmatter に背負わせない。audience を main/doc に転用すると既存 ~128 件の全 backfill が発生し ADR-0123 の「audience=任意」とも衝突する。

将来 lint で値検証したくなったら（任意・main 領分）: scripts/frontmatter-schema.json に allowedAudiences: ["both","agent","human"] を追加し、adr-lint.mjs で「audience が存在する場合のみ enum 検査」する optional rule を足す（presence は引き続き非必須）。scripts/ は doc read-only のため main 申し送り。

8. Enforced Directories

scripts/adr-lint.mjs ENFORCED_FRONTMATTER_DIRS (8 ディレクトリ):

lint 対象外: _meta/templates/*.md は除外 (!f.includes('/templates/'))。テンプレートは adr-lint-doc-consistency.mjs 3 way 整合 check で別軸検証。

lint 適用外ディレクトリ: docs/adr/ (別の 14 rule で検証) / docs/_internal/ の DRP 以外 (frontmatter 規約緩和の暫定領域、_internal/ 全体の強制は ADR-0123 Phase 2 候補)。

9. Legacy / Deprecated

該当 rule なし。本 doc 起案時点 (2026-05-22) で全 4 rule が status: active。Deprecated 化された rule が出た場合は本節に「deprecated 日付」「代替 rule への移行手順」「最終削除予定日」を記載する。

既知の 3 way 整合 follow-up (Phase 2 で対応済)

Phase 1 起案時、_meta/templates/synthesis.md の frontmatter が以下の ALLOWED_TYPES / STATUSES 外の値を使用していた:

• type: research-synthesis ← ALLOWED_TYPES (13 種) に未登録
• status: proposed ← ALLOWED_STATUSES (4 種) に未登録

Phase 2 で採択した方針 (案 a): ALLOWED_TYPES を 14 種に、ALLOWED_STATUSES を 5 種に拡張 (ADR-0050 標準 Synthesis テンプレを既存値域として正規化)。synthesis テンプレ・RQ-050/051/052 既存 synthesis 3 件は変更せず、code と doc 側を拡張。3 way 整合 CI (scripts/adr-lint-doc-consistency.mjs) が以降ガード。

10. Changelog