blueprint-adr-validate

/blueprint:adr-validate

アーキテクチャ決定記録の関係性の整合性、参照の整合性、ドメインの競合を検証します。

使用方法：/blueprint:adr-validate [--report-only]

このスキルを使用する場面

次のような場合にこのスキルを使用します…	次のような場合は代替手段を使用します…
リリース前にADRの整合性を維持する	新しいADRを作成する（/blueprint:derive-plansを使用）
リファクタリングや変更後に監査する	ドキュメントを一度だけ簡単にレビューする
定期的なドキュメントレビューのプロセス	ADR全般を読む

コンテキスト

• ADRディレクトリ：!find . -path '*/docs/adrs' -maxdepth 2 -type d
• ADR数：!find . -path '*/docs/adrs/*' -name "*.md" -type f
• ドメインタグ付きADR：!find . -path '*/docs/adrs/*' -maxdepth 3 -name '*.md' -exec grep -l "^domain:" {} +
• フラグ：!echo "${1:---}"

パラメーター

$ARGUMENTSを解析します：

• --report-only：修正を促さずに検証レポートを出力します
  • デフォルト：修正オプションを提示する対話モード

実行

ADRの完全な検証および修正ワークフローを実行します：

ステップ1：すべてのADRを検出する

1. docs/adrs/にADRディレクトリがあることを確認します
2. 見つからない場合 → エラー：「docs/adrs/にADRが見つかりません」
3. すべてのADRファイルを解析します：ls docs/adrs/*.md
4. 各ADRのフロントマターから、number、id、created、modified、status、domain、supersedes、superseded-by、extends、relates-toを抽出します

ステップ2：参照の整合性を検証する

各ADRについて、次の項目を検証します：

1. supersedes参照：参照先が存在すること、参照先のstatusが「Superseded」であること、参照先に相互参照となるsuperseded-byがあることを確認します
2. extends参照：参照先が存在することを確認し、参照先が「Superseded」の場合は警告します
3. 関連参照：すべての参照先が存在することを確認し、一方向リンクの場合は警告します
4. 自己参照：ADRが自身を参照している場合はフラグを付けます
5. 循環チェーン：置き換えグラフ内の循環を検出します
6. ワークスペース間参照（v3.3.0以降、workspaces.roleを含むマニフェスト）： supersedes／extends／relatedフィールドで、次の参照形式を認識します：
   • ADR-NNN — 現在のワークスペース内を指します（従来の動作）。
   • <workspace-path>/ADR-NNN — 兄弟または子ワークスペースを指します。モノレポのルートから<workspace-path>/docs/adrs/を読み込んで解決します。 そのワークスペースがルートのworkspaces.childrenに記載されていない場合は警告します。
   • /ADR-NNN — モノレポのルートにあるADRセットを指します。子マニフェストの場合はマニフェストのworkspaces.root_relative_pathを使用し、ルートマニフェストの場合は現在のディレクトリを使用して解決します。 解決できないワークスペース間参照は、検証を妨げないようにエラーではなく警告として報告されます。

詳細なチェックについては、REFERENCE.mdを参照してください。

ステップ 2b：ADR 番号の衝突とインデックスのずれを検出する

ADR 番号はブランチ作成時に選ばれますが、確保されるのはマージ時です。そのため、進行中の ADR PR が同じ番号を選び、両方ともマージされる可能性があります（issue #1585 — FVH インフラストラクチャの #2015 の衝突では、2 つの ADR がどちらも 0038 を主張しました）。決定的な検査を実行します。

bash ${CLAUDE_SKILL_DIR}/scripts/check-adr-numbers.sh --project-dir "$(pwd)"

構造化された STATUS= / ISSUE_COUNT= の規約に従って出力し、次の 4 種類を報告します（REFERENCE.md を参照）。

• duplicate_adr_number（ERROR）— NNNN-title.md ファイル名または frontmatter の id: ADR-NNNN の指定により、2 つのファイルが同じ番号を主張しています。メッセージには出所（basename / frontmatter）が含まれるため、番号がファイル名にないファイルによる指定も判別できます。
• adr_number_collision（ERROR）— 作業ツリー内の ADR が、ベース ref（origin/main）にある別のファイルがすでに保持している番号を主張しています。これはマージ前の並行 PR によるケースで、2 つ目の PR がマージされる前に検出されます。
• adr_registry_mismatch（ERROR）— ファイルが ADR-NNNN を主張していますが、マニフェストの id_registry ではその番号が別のパスに割り当てられています。ID からパスへの対応を曖昧さなく解決する唯一の基準はレジストリです。2 つのファイルがどちらも ADR-0016 と記載していても、登録できるのは 1 つだけです。マニフェストまたは id_registry がない場合は通知されません。
• adr_missing_index_row（WARN）— ADR がディレクトリの README インデックスにありません（0038 の衝突が 1 週間気づかれなかった原因です）。再度警告を出すのではなく、ステップ 2c で修正してください。

複数の ADR ディレクトリ（issue #2129）：この検査ではディレクトリの集合をスキャンします。実際の ADR-0016 の衝突では、該当する ADR が docs/adrs/ と docs/blueprint/adrs/ にあり、単一ディレクトリのスキャンでは検出できません。優先順位は、繰り返し指定できる --adr-dir <dir>、それがなければ（issue #2128）共有の validation マニフェストブロックにある validation.adr_dirs（blueprint-plugin/scripts/get-validation-config.sh 経由で読み込みます。設定方法を別途追加しないでください）、それもなければ docs/adrs、次に docs/adr の順です。ADR_DIRS=（タブ区切り）と ADR_DIR_COUNT= を出力します。ADR_DIR=、ADR_COUNT=、INDEX= は引き続き #1585 の意味で使われます。

検出結果をステップ 4 のレポートに反映します。STATUS=ERROR はマージを妨げる衝突です。新しい方の ADR に次の空き番号を割り当て直し（ファイル名と frontmatter の id: の両方を更新）、インデックスを再生成してください（ステップ 2c）。

ステップ 2c：ADR インデックスを再生成する

adr_missing_index_row は修正できます。手動管理の表が古くなっているのが原因です。frontmatter から再構築します。

# CI / read-only gate: non-zero exit when the on-disk index is out of date
bash ${CLAUDE_SKILL_DIR}/scripts/generate-adr-index.sh --project-dir "$(pwd)" --check

# Repair: rewrite the table in every resolved ADR directory
bash ${CLAUDE_SKILL_DIR}/scripts/generate-adr-index.sh --project-dir "$(pwd)"

2 つのマーカーコメントの間のブロックだけを書き換えるため、その周囲の文章は保持されます。

| ADR | Title | Status |
| --- | ----- | ------ |
| [ADR-0016](0016-in-engine-ui.md) | In-engine UI | Accepted |

ディレクトリごとに 1 つのインデックスを生成します（--index-file でデフォルトの README.md を上書きできます）。対象はステップ 2b と同じディレクトリ集合で、番号の収集範囲も拡張されます。そのため、番号が frontmatter にしかない ADR にも行が追加されます。--check はディレクトリごとに次の状態を報告します。

状態	重大度	意味
in_sync	OK	ディスク上のブロックが生成されたブロックと一致しています
drifted	ERROR（終了コード 1）	再生成が必要です。インデックスが古くなっています
markers_absent	WARN（終了コード 0）	マーカーペアがまだありません。書き込み時に追加されます。意図的に差分として扱いません
index_absent	WARN（終了コード 0）	インデックスファイルがまだありません。書き込み時に作成されます
no_adrs	OK	ディレクトリに番号付き ADR がありません

書き込みモードでは written / unchanged / markers_inserted / index_created を報告します。手書きの表がすでにある README にマーカーを追加する場合は、その表を削除してください。生成されたブロックが正として扱われます。

ステップ 3：ドメインを分析する

1. ADR をドメインフィールドごとにグループ化する
2. 「Accepted」の ADR が複数あるドメインごとに、潜在的な競合フラグを付ける
3. タグのない ADR を一覧表示する（エラーではなく、推奨事項です）

ステップ 4：検証レポートを生成する

次の内容を示す包括的なレポートをまとめます。

• 概要：ADR の総数、ドメインタグ付け率、関係の件数、ステータスの内訳
• 参照の整合性：supersedes、extends、related の状態（✅/⚠️/❌）
• 検出されたエラー：壊れた参照、自己参照、循環
• 警告：古くなった拡張、一方向リンク
• ドメイン分析：競合とタグのない ADR

ステップ 5：--report-only フラグを処理する

--report-only フラグがある場合：

1. ステップ 4 の検証レポートを出力します
2. 修正を促すことなく終了します

ステップ 6：修正を促す（対話モードの場合）

AskUserQuestion を使用して、ユーザーに実行する操作を尋ねます：

• すべてを自動で修正する（ステータスを更新し、相互リンクを追加する）
• 問題を個別に確認する
• レポートを docs/adrs/validation-report.md にエクスポートする
• 今はスキップする

選択内容に応じて実行します（REFERENCE.md を参照）。

ステップ 7：タスクレジストリを更新する

docs/blueprint/manifest.json のタスクレジストリ項目を更新します：

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg result "${VALIDATION_RESULT:-success}" \
  --argjson processed "${ADRS_VALIDATED:-0}" \
  '.task_registry["adr-validate"].last_completed_at = $now |
   .task_registry["adr-validate"].last_result = $result |
   .task_registry["adr-validate"].stats.runs_total = ((.task_registry["adr-validate"].stats.runs_total // 0) + 1) |
   .task_registry["adr-validate"].stats.items_processed = $processed' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

VALIDATION_RESULT は "success"、"{N} warnings"、または "failed: {reason}" です。

ステップ 8：変更内容と概要を報告する

行った変更をすべて報告します：

• 更新した ADR（ステータスの変更、リンクの追加）
• 残っている問題の数
• 次のステップの推奨事項

エージェント向けの最適化

コンテキスト	コマンド
ADR ディレクトリを確認する	test -d docs/adrs && echo "YES" || echo "NO"
ADR の数を数える	ls docs/adrs/*.md 2>/dev/null | wc -l
フロントマターを抽出する	head -50 {file} | grep -m1 "^field:" | sed 's/^[^:]*:[[:space:]]*//'
ドメインで検索する	grep -l "^domain: {domain}" docs/adrs/*.md
循環を検出する	廃止グラフを作成してたどる
番号の衝突	bash ${CLAUDE_SKILL_DIR}/scripts/check-adr-numbers.sh --project-dir "$(pwd)"
2 つの ADR ディレクトリ	… /check-adr-numbers.sh --adr-dir docs/adrs --adr-dir docs/blueprint/adrs
インデックスのずれをチェック（CI）	bash ${CLAUDE_SKILL_DIR}/scripts/generate-adr-index.sh --check
インデックスを再生成する	bash ${CLAUDE_SKILL_DIR}/scripts/generate-adr-index.sh

---

検証ルール、修正手順、レポート形式の詳細については、REFERENCE.md を参照してください。