doc-validator

doc-validator

目的

SDD コーパス内のドキュメント間の関係と整合性を検証します。壊れた相互参照、孤立した成果物、一方向リンク、累積タグの不足、重複または不正な ID、8 層にわたるトレーサビリティマトリクスの完全性を確認します。このスキル自体がバリデーターです。フレームワークには実行時コードは含まれておらず、${CLAUDE_PLUGIN_ROOT}/framework/governance/ および各レイヤーの README.md ファイルに対して宣言的なチェックを実行します。

レイヤー：横断的ユーティリティ（8 層すべてを読み込み、成果物は生成しません）。

使用するタイミング

プロジェクト全体のチェックに使用します。ドキュメント間の関係、累積タグ付け、孤立の検出、双方向リンクの整合性、重複 ID、詳細なトレーサビリティ（任意でリンクを修復）、文章や用語のレビュー、主要リリース前の確認に対応します。コーパス全体を対象とする唯一のバリデーターであり、以前は別々のスキルだったトレーサビリティの詳細確認と修復、文章のレビューもカバーします。

次の場合は使用しないでください：

• 単一ドキュメントの構造／メタデータ／内容の確認には、そのレイヤーの ../doc-<layer>-audit/SKILL.md を使用してください。
• ID 形式のルールの定義には、そのルールを管理する ../doc-naming/SKILL.md を使用してください。（このスキルは ID 形式を適用し、 XDOC-E007 を出力します。ID の確認にはこのスキルを使用してください。 ルールの定義は doc-naming にあります。）

入力：docs_path（必須）、scope（デフォルトは cross-document ／ traceability ／ prose ／ full）、strictness（strict ／ permissive）、 auto_fix（壊れたリンクの修復／安全な場合のカウント再生成）、report_format。

動作

ドキュメント間のチェック

カテゴリ	チェック	エラーコード
LINKS	すべての Markdown／ドキュメントのリンクとアンカーが解決される	XDOC-E001, XDOC-E004
CROSS-REF	引用された各ドキュメント／要素 ID がコーパス内に存在する	XDOC-E001, XDOC-E003
ORPHAN	上流とのつながりがない成果物が存在しない	XDOC-E005
TAGS	8 層の階層に基づき、累積上流タグがすべて揃っている	XDOC-E002
IDS	要素 ID は TYPE.NN.SS.xxxx、ドキュメント参照は SPEC-NN／ADR-NN／IPLAN-NN。重複、レガシー形式、3 セグメント形式、廃止済み形式がない	XDOC-E006, XDOC-E007
MATRIX	8 層にわたるトレーサビリティマトリクスの完全性	XDOC-W001
SECTION	セクションファイル数がメタデータと一致する	SEC-E001…E003, SEC-W001
DIAGRAM	Mermaid エンティティが文章と一致する	DIAG-E001/E002, DIAG-W001/W002
TERM	用語／略語の一貫性	TERM-E001/E002, TERM-W001/W002
COUNT	記載された数が項目別の合計と一致する	COUNT-E001, COUNT-W001
FWDREF	上流から下流への参照がなく、循環もない	FWDREF-E001/E002, FWDREF-W001

SECTION／TERM／COUNT の指摘は通常、自動修正が可能です（カウント／セクションの再生成、用語の標準化）。それ以外の指摘は手動修正が必要なものとして報告されます。

トレーサビリティの詳細確認と修復

ドキュメント間のチェックに加えて、双方向トレーサビリティの全チェックを実行します。

• 双方向の対称性 — A→B のリンクごとに、B→A が存在することを確認します。スコアは (一致したペア数 / 合計数) × 100 です（目標 ≥ 95%）。
• 網羅性と孤立 — BRD を除くすべての成果物に上流が必要です。下流は任意です。下流がないチェーン中間の成果物と、想定外の孤立を検出し、種類別に網羅率を報告します。
• 修復（auto_fix） — 有効にした場合、安全に修正できる問題のみを修復します。欠けている相互リンクの追加、セクション／COUNT メタデータの再生成、用語の標準化が対象です。最初にタイムスタンプ付きのバックアップを書き込み、ロールバックコマンドを出力してください。チェックを満たすためにプレースホルダー ID を捏造してはいけません。構造や内容の不足は、該当する -fixer で修正するものとして報告されます。

文章のレビュー（scope: prose）

トレーサビリティとは無関係に、次の4つの観点から、単一のファイルまたはフォルダーの文章品質をレビューします。

• DATA — 記載された件数／ステータス／日付の整合性を内容と照合します（例：「5つの機能」と記載されているのに、列挙されているのは4つ、last_updated が created より前）。
• REF — インラインリンク／アンカー／タグ形式の解決を確認します。
• TYPO — 誤字、重複語、壊れた Markdown を確認します。
• TERM — 未定義の頭字語、一貫性のない用語、主観的な用語を確認します。

重大度は strictness に従います。strict では、DATA／REF／TYPO／TERM の指摘はすべてエラー（処理をブロック）です。permissive では警告になります。ドメイン用語に関する TERM の誤検出を抑制するには、プロジェクトの glossary（.aidoc/profile.yaml。Adaptation を参照）を適用してください。ドキュメントの公開またはコミット前に使用してください。

累積タグの階層

レイヤー	成果物	必須の上流タグ
1	BRD	なし
2	PRD	@brd
3	EARS	@brd、@prd
4	BDD	@brd、@prd、@ears
5	ADR	@brd、@prd、@ears、@bdd
6	SPEC	+ @adr (5)
7	TDD	+ @spec (6)
8	IPLAN	+ @tdd (7)

準拠先：${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml（required_tags）および ${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md。

ID 形式の適用（IDS）

要素 ID は4セグメント形式 TYPE.NN.SS.xxxx（TYPE ∈ {BRD, PRD, EARS, BDD, ADR, TDD}）、ドキュメントレベルの参照はハイフン形式 SPEC-NN／ADR-NN／IPLAN-NN を必須とします。従来の3セグメント要素 ID、数値のタイプコード方式、廃止された12レイヤー成果物への参照は拒否し、それぞれに XDOC-E007 のフラグを付けてください。../doc-naming/SKILL.md を参照してください。

品質ゲート

ERROR は処理をブロックします（終了コード 2）。WARNING は --strict の場合のみ処理をブロックします（終了コード 1）。INFO は参考情報です。プロジェクト全体のゲートは、クロスリファレンスエラーがゼロ、孤立項目がゼロ、双方向準拠率および累積タグ準拠率がそれぞれ100%、重複 ID がゼロであることです。出力は統合レポート（markdown／json／text）で、各指摘、そのコード、および修正のヒントを記載します。

適応

検証の前に、プロジェクトの適応プロファイル（.aidoc/profile.yaml）を読み込んでください。このスキルで宣言されている設定を適用してください。

• active_layers — スキップ可能なレイヤー（BDD／ADR）が無効になっている場合は、設計上存在しないものとして扱ってください。カスケードを適用し（下流の required_tags／can_reference からそのレイヤーを除外し）、累積タグ、孤立項目、双方向チェックで意図的な欠落をエラーとしてフラグ付けしないようにします。
• glossary — プロジェクトで推奨される用語を使って、文章レビューでドメイン用語に関する TERM の指摘を正規化し、抑制してください（許容される用語について誤検出しないようにします）。

未知のキーや対象範囲外のキーは無視してください。プロファイルがない場合は、フレームワークのデフォルトを使用します。 準拠先：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

関連リソース

• ガバナンス：${CLAUDE_PLUGIN_ROOT}/framework/governance/DOC_GOVERNANCE_CORE.md · ${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md · ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• レイヤーレジストリ：${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml
• レイヤーごとの準拠先：${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md
• ID 形式の準拠先：../doc-naming/SKILL.md
• 単一ドキュメントのゲート：../doc-brd-audit/SKILL.md … ../doc-iplan-audit/SKILL.md
• ワークフローのルーティング：../doc-flow/SKILL.md · 図：../charts-flow/SKILL.md