Imported from feel-flow/ff-dev-toolkit (plugins/ff-dev-toolkit/skills/validate-docs/SKILL.md). Install upstream with npx skills add feel-flow/ff-dev-toolkit --skill validate-docs. Copyright stays with the author.

/validate-docs — AI仕様駆動開発ドキュメント検証

プロジェクトの docs/ ディレクトリが AI仕様駆動開発のコア7文書要件を満たしているか検証します。

プラグインルートの固定（必須）

同梱resourceを参照する前に FF_DEV_TOOLKIT_ROOT を一度だけ解決し、実行中は変更しない。

• Claude Codeでは、その呼び出しでホストが渡した ${CLAUDE_PLUGIN_ROOT} を使う
• Codexなど他ホストでは、実際に読み込んだこの SKILL.md の絶対パスを FF_DEV_TOOLKIT_SKILL_FILE として固定し、そこから ../.. を解決する

このskillを実行するAI hostは、Bash tool呼び出しを組み立てるとき、skill loaderが返した実値で FF_DEV_TOOLKIT_SKILL_FILE="<このSKILL.mdの絶対パス>"; export FF_DEV_TOOLKIT_SKILL_FILE を実行し、同じshell script bodyでresourceを呼び出す。placeholderのまま実行したり、cache pathを推測して埋めたりしない。 plugin内ドキュメントの正本は、読み込んだこの SKILL.md のdirectoryを基準にした plugin root固定契約 である。consumerへコピーされた docs/ や物理CWDを基準に解決しない。 review系resource（setup-multi-agent.sh / multi-agent.sh / multi-review.sh）を直接呼ぶhostだけが、同節のresolver + guard fence全体を読み、handoff設定・guard・resource呼び出しを同じshell script bodyで実行する。そのhostはtask workspace repository rootも FF_DEV_TOOLKIT_PROJECT_ROOT として同じBash tool呼び出しへ渡し、現在の物理CWDおよび git rev-parse --show-toplevel と一致することを実行前に確認する。review以外のresourceはこのreview専用guardを実行せず、固定したroot配下で各skillが指定するresourceだけを呼出直前に検証する。以下のBash例は、同じtool bodyで固定済みrootを使うcommand断片として扱う。

解決後は同じ絶対パスだけを使い、cache / marketplace / 旧インストール領域を走査して選ばない。 version sortによる版の選び直しや、sidecarを使った別実体への切替も行わない。 解決済みrootまたは必要resourceが消失・不整合になった場合は、別versionへfallbackせず 「ff-dev-toolkit更新後にこのskillを再呼び出してください」と案内して停止する。

固定したrootが消えた状態で手順を先へ進めないため、同梱resourceを呼ぶBash tool呼び出しの本文冒頭で次のguardを実行する。手順書のguardは実行環境の set -e を仮定できないので、|| の右辺で false を返す形ではなくifで構造的に停止する。

if [ -z "${FF_DEV_TOOLKIT_ROOT:-}" ] || [ ! -d "${FF_DEV_TOOLKIT_ROOT}" ]; then
  echo "ff-dev-toolkit更新後にこのskillを再呼び出してください（plugin rootが解決できません）" >&2
  exit 2
fi

本コマンドの検証規則（必須3文書と条件付き4文書の N/A 判定・兆候検出・同義見出しの内容判定・空セクションの状態明記・Frontmatter スキーマ・スコア算出・プレースホルダー免除区分）が drift しないことは、plugins/ff-dev-toolkit/tests/validate-docs/verify.sh（節スコープの条文ピン）と plugins/ff-dev-toolkit/tests/validate-docs-placeholders/verify.sh（境界の機械照合）で検証する。規則の文言・節番号を変えたら tests/validate-docs/verify.sh を追随させること。

検証項目

1. コア文書の存在チェック

コア7文書のうち、常に必須なのは MASTER・PROJECT・ARCHITECTURE の3文書です。残る4文書（DOMAIN・PATTERNS・TESTING・DEPLOYMENT）は、判断マトリクス上必要になった時点で作成すればよく、未作成の場合は N/A（未達ではない）として扱います。

N/A にできるのは、判断マトリクス上も不要な場合だけです。未作成の条件付き文書に次の必要性の兆候がある場合は、N/A ではなく ❌（不足）として報告し、作成を求めてください:

• DOMAIN 未作成なのに、ビジネスルール・エンティティ定義が他の文書やコードコメントに散在している
• PATTERNS 未作成なのに、コーディング規約への言及が複数文書にある
• TESTING 未作成なのに、テストコードが存在する
• DEPLOYMENT 未作成なのに、CI/CD 設定や本番環境が存在する

なお、7文書すべての整備はより成熟した準拠状態として推奨されます（兆候がなく未作成 = N/A の場合は減点しない）。

補助ドキュメント（推奨）:

docs/06-reference/DECISIONS.md が存在する場合は、ADR 番号の重複と見出し ↔ 決定ログ表の不一致を bash "${FF_DEV_TOOLKIT_ROOT}/tests/docs-gates/adr-number-scan.sh" docs/06-reference/DECISIONS.md で追加検査する（rc=0 のみ合格。rc=1 は見出し・表の不整合、rc=2 は抽出不能として報告する）。

2. 文書別必須セクションチェック

存在する各コア文書について、標準が定める必須セクションに対応する内容があるか確認します（未作成の条件付き文書はスキップ = N/A）。

判定ルール:

• 見出しの文字列一致ではなく、内容の責務で判定する。同義見出し（上表の例のほか、番号prefix ## 9. 状態遷移 や見出しレベルの違い ### も許容）に該当内容があれば充足とする。ただし見出し名だけで充足と即断せず、該当内容が実際に書かれているかを確認し、充足と判定した根拠（対応する見出しと内容の要旨）を出力に含める（例: 「ステークホルダー分析」に対象ユーザーの記述がなければ「対象ユーザー」は未充足）
• 空セクションの状態明記チェック: 必須セクションが実質空（見出しのみ、またはテンプレートのプレースホルダーのみ）の場合、「該当なし」「未定」などの状態が明記されていれば ✅（状態明記あり）、明記がなければ ❌（空セクション）として指摘する
• ARCHITECTURE の技術スタックは、各技術にバージョンが明記されているかまで確認する

3. MASTER.md 追加チェック（公式実装は標準より厳格）

本ツールキットのテンプレートを前提に、標準の必須セクションに加えて以下も確認します。これらは公式実装（ff-dev-toolkit）が AI との協業品質のために追加している項目であり、標準の要求そのものではありません:

• プロジェクト識別情報: プロジェクト名、バージョン、最終更新日
• 技術スタック要約: FE/BE/DB/Infra のいずれかが記載
• 守るべきルール: 命名規則 or コーディング規約の記載
• 情報不足時の必須確認プロトコル: 推論禁止ルールの記載

4. 各ドキュメントの内容チェック

存在する各ドキュメントに以下の最低限の内容があるか確認します:

• 空ファイルでないこと: 各ファイルに10行以上の実質的な内容があること
• 見出し構造: ## レベルの見出しが1つ以上あること
• プレースホルダーの残存: [プロジェクト名] 等のテンプレート由来の角括弧プレースホルダー、frontmatter の "@your-github-handle"・"YYYY-MM-DD"、{{ }}、TODO TBD が残っていないこと。ただし /init-docs の置換ポリシーで意図的に残される未確定値（[金額]・[SLA値]・[x.x.x] 等、プロジェクト情報では埋まらないもの）は「未確定値プレースホルダー（実装進行に伴い充足予定）」として別枠で報告する
• 検査対象外（閉じた区間のみ）: 判定の前に次を検査対象から外す。(1) 閉じたコードフェンス（開始行から対応する閉じ行まで）(2) 閉じた HTML コメント（<!-- から --> まで）(3) 同一行内で対になった単一バックティックのインラインコードスパン。規則の正本は本節である
• 閉じ忘れは除外区間にしない: 閉じていないフェンス / コメントは除外区間にしない。閉じマーカー探索だけを打ち切り、開始行の本文は検査対象に残して後続の走査を続ける。除外範囲を文書末尾まで広げない。表セル・通常本文のプレースホルダーは検出対象のまま
• 記入雛形: 新規エントリの追加形式を示すブロックは、閉じたコードフェンス内または閉じた HTML コメント内に置く場合に限り残してよい
• 例示内の変数スロット: 表セルなどフェンスに入れられない位置の可変部分は具体例へ置換する（残さない）
• 未記入のテンプレート骨組み: 実体を書く。実体が無い項目は「該当なし（理由）」と明記する
• 規則説明のための引用: プレースホルダー自体を説明対象として引用する場合は、同一行内で対になった単一バックティックのインラインコードスパンで囲む

5. クロスリファレンスチェック

• MASTER.md からの索引リンクが実際のファイルを指しているか
• 相対パスが正しいか
• 初期セット外テンプレートへの参照は区別する: リンク切れのうち、同一相対パスのファイルが ${FF_DEV_TOOLKIT_ROOT}/docs-template/ に存在するもの（例: GETTING_STARTED*.md、05-operations/deployment/ 配下、08-knowledge/ 等）は「リンク切れ」ではなく「未導入テンプレートへの参照（必要時に ff-dev-toolkit プラグインの docs-template から追加コピー可）」として別枠で報告する。docs-template にも存在しないリンク先だけを真のリンク切れとして報告する

6. Frontmatter スキーマチェック

標準はすべての仕様文書に YAML Frontmatter を要求し、適合チェックリストにも Frontmatter の MUST 項目があります。存在する各コア文書の先頭 YAML Frontmatter を以下の観点で検証します（未作成の条件付き文書はスキップ = N/A。プロジェクトが追加した拡張文書も Frontmatter を持つ場合は同じ基準で検証する）:

• 必須6フィールドの充足: title / version / status / owner / created / updated の6フィールドが揃っているか。Frontmatter ブロック自体が無い場合、または欠落フィールドがある場合は ❌ とし、欠落しているフィールド名を列挙する
• version 形式: version が x.y.z 形式のセマンティックバージョンか（例: 1.2.0 は ✅。1.0 / 1 / v1.0.0 / 1.0.0.0 / 1.2.x は ❌）
• status 値域: status が draft / review / approved のいずれかか。本ツールキットのテンプレートは終端状態 deprecated も有効値として定義するため deprecated も許容する。それ以外の値（Draft など大文字化・タイプミス含む）は ❌
• changeImpact の記録と小文字: 文書が変更済みであることが明らかな場合（例: created と updated が異なる、更新履歴 / Changelog に初版以外のエントリがある等）は changeImpact が記録されているか確認する。changeImpact フィールドが存在する場合は、値が小文字（low / medium / high）であるか検証する。欠落（変更済みなのに未記録）・大文字（LOW / MEDIUM / HIGH）・Medium 等の混在はいずれも ❌。初版など変更済みと判断できない文書で changeImpact が存在しない場合は指摘しない

判定ルール:

• 各フィールドのプレースホルダー残存（owner の @your-github-handle、created / updated の YYYY-MM-DD 等）は §4 の内容チェックで扱う。本チェックはフィールドの存在・形式・値域に絞り、二重指摘しない
• docs/specs/ の 6 ステータスは別スキーマ: 仕様ファイル（docs/specs/）は Spec Kit 運用ガイドの Front Matter スキーマ（specId / owners / lastUpdated と、中間状態 implementing / done を含む 6 ステータス）を持つ。これはコア7文書・拡張文書の Frontmatter とは別のスキーマであり、本チェックの対象外。本節の 4 値（draft / review / approved / deprecated）へ implementing / done を混ぜない（docs-template/MASTER.md §Frontmatter の注記も同じ線引きを持つ。機械側の pin は tests/docs-template-frontmatter-selftest G18）
• Frontmatter を持たない補助ドキュメント（GETTING_STARTED*.md・SETUP_*.md 等）は本チェックの対象外。Frontmatter を持つ拡張文書は同じ基準で検証する
• Frontmatter スキーマ違反は ❌ として扱い、最終判定（達成 / 未達）に反映する。値の違反を正常扱いする silent failure を防ぐことが本チェックの目的

出力形式

検証結果を以下の形式で出力してください:

## ドキュメント検証結果

### コア文書の存在
必須3文書:
- ✅ MASTER.md — 存在 (xxx行)
- ✅ PROJECT.md — 存在 (xxx行)
- ❌ ARCHITECTURE.md — 未作成（必須）

条件付き文書:
- ✅ DOMAIN.md — 存在 (xxx行)
- ➖ PATTERNS.md — 未作成 → N/A（判断マトリクス上の必要性の兆候なし。必要になった時点で作成）
- ❌ TESTING.md — 未作成だがテストコードが存在（判断マトリクス上必要）→ 作成が必要
- ...

### 必須セクション（存在する文書のみ）
MASTER.md:
- ✅ プロジェクト概要
- ✅ 文書索引（「関連ドキュメント」が充足）
- ❌ ディレクトリ構造 — 見つかりません
- ❌ 重要な制約 — セクションは存在するが空（「該当なし」等の状態明記もなし）

DOMAIN.md:
- ✅ ビジネスルール
- ✅ 状態遷移（空だが「該当なし（状態を持たないドメイン）」と明記あり）
- ...

### MASTER.md 追加チェック（公式実装基準）
- ✅ プロジェクト識別情報
- ❌ 技術スタック要約 — 見つかりません
- ...

### 内容品質
- ⚠️ DOMAIN.md — プレースホルダー残存 (3箇所)
- ⚠️ PATTERNS.md — 内容が少ない (8行)
- ...

### Frontmatter スキーマ（存在する文書のみ）
- ✅ MASTER.md — 必須6フィールド充足 / version 1.4.0 / status draft / changeImpact medium
- ❌ PROJECT.md — 必須フィールド欠落（`status`, `owner`）
- ❌ ARCHITECTURE.md — version が SemVer 形式でない（`1.0`）
- ❌ DOMAIN.md — status が値域外（`Draft` — 有効値は draft / review / approved / deprecated）
- ❌ TESTING.md — 変更済みだが changeImpact 未記録（`created` と `updated` が異なる）
- ❌ DEPLOYMENT.md — changeImpact が大文字（`LOW` → `low`）
- ...

### クロスリファレンス
- ✅ 全リンク有効
- ❌ MASTER.md → docs/03-implementation/PATTERNS.md — リンク切れ
- ...

### サマリー
- 必須3文書: 2/3 ✅（ARCHITECTURE.md 未作成）
- 条件付き文書: 1/4 存在（2件 N/A、1件 不足）
- 必須セクション: 11/13 ✅（存在する MASTER 4 + PROJECT 5 + DOMAIN 4 を分母とする）
- Frontmatter: 1/4 ✅（存在する文書のうち PROJECT / ARCHITECTURE / DEPLOYMENT に違反）
- 全体スコア: 72%（例示値）— 改善が必要
- **判定: 未達**（❌ の項目が残っている）

### 推奨アクション
1. ARCHITECTURE.md を作成してください（`/init-docs` で初期化可能）
2. MASTER.md に「ディレクトリ構造」セクションを追加してください
3. MASTER.md の「重要な制約」を記入するか、「該当なし」等の状態を明記してください
4. PROJECT.md の Frontmatter に不足フィールド（`status`, `owner`）を追加してください
5. ARCHITECTURE.md の Frontmatter の `version` を SemVer 形式（`1.0.0`）に修正してください
6. ...

重要ルール

• 番号付きフォルダ名の揺れ（01-context vs 01-business）は許容する
• ファイル名の大文字小文字は区別しない
• docs/ 以外の場所（例: root直下のMASTER.md）にあるファイルも検出する
• N/A と判定した条件付き文書（DOMAIN・PATTERNS・TESTING・DEPLOYMENT）はスコアの分母に入れない（N/A は未達ではない）。ただし必要性の兆候があるのに未作成の文書は ❌（不足）として分母に入れる。必須セクションのスコアは存在する文書のみを分母とする
• 全体スコア = 充足項目数 ÷ 判定対象項目数（N/A は分母から除外）。スコアは参考値であり、最終判定は「❌ の項目が1つもないこと」（達成 / 未達）で行う
• 必須セクションは見出しの文字列一致ではなく内容の責務で判定し、充足の根拠（対応見出しと内容の要旨）を添える（同義見出し・番号prefix・見出しレベルの違いを許容）
• Frontmatter スキーマは存在する文書のみを検証する（未作成の条件付き文書は N/A）。必須6フィールド（title / version / status / owner / created / updated）の充足・version の SemVer 形式・status の値域（draft / review / approved / deprecated）・変更済み文書の changeImpact 記録と小文字（low / medium / high）を確認し、違反は ❌ として最終判定に反映する
• Frontmatter のフィールド値がプレースホルダー（@your-github-handle・YYYY-MM-DD）のまま残っている場合は §4 の内容チェックで報告し、Frontmatter スキーマチェックとは二重指摘しない
• プレースホルダー免除は閉じた区間のみ: 閉じたコードフェンス・閉じた HTML コメント・同一行内で対になった単一バックティックのインラインコードスパンの中は検査対象外。閉じ忘れは除外区間にしない（閉じマーカー探索だけを打ち切り、開始行の本文は残して走査を続ける）。表セル・通常本文は検出対象のまま。規則の正本は §4
• 検証結果に基づいた具体的な改善アクションを必ず提示する