consistency-check

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,system_overrides

整合性チェック

すべての GDD とエンティティレジストリ（design/registry/entities.yaml）を比較し、ドキュメント間の不整合を検出します。grep を優先する方式を採用しています。レジストリを一度読み込み、登録済みの名前に言及している GDD のセクションのみを対象とします。競合の調査が必要な場合を除き、ドキュメント全体を読み込むことはありません。

このスキルは、書き込み時のセーフティネットです。 /design-system のセクション単位のチェックで見逃した可能性がある点や、/review-all-gdds の全体レビューでは検出が遅すぎる点を検出します。

実行するタイミング：

• 新しい GDD を書いた後、次のシステムに進む前
• /review-all-gdds の前（このスキルがクリーンなベースラインから開始できるようにします）
• /create-architecture の前（不整合は後続の ADR に悪影響を与えます）
• 必要に応じて：特定のエンティティをチェックするには /consistency-check entity:[name]

出力： 競合レポートと、任意のレジストリ修正

---

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います（collaborative は常に質問し、guided は主要な項目のみ、autonomous は記録して処理を続行します。automation_always_ask カテゴリでは常に質問します）。

workflow（.claude/docs/workflow-modes.md を参照）は、各 GDD に対してその実効ティアで適用されます。ブロックにその GDD のシステム（ファイル名の拡張子より前の部分）の system_overrides 行があればその値、なければプロジェクトの値を使用します。

• full — すべての GDD セクションとエンティティレジストリを完全に照合します。
• standard — 必須セクションのみを照合します。レポートの Scope 行にその旨を記載し、それらのセクション外で登録済みの名前について記載された値は、このティアでは未チェックとして一覧表示します（Phase 3 で適用します）。
• minimal — 意味のあるチェックはできません（チェック対象の GDD がないため）。

Phase 1: 引数の解析とレジストリの読み込み

モード：

• 引数なし / full — 登録済みのすべてのエントリを、すべての GDD と照合します
• since-last-review — 最後のレビュー報告以降に変更された GDD のみをチェックします
• entity:<name> — すべての GDD を対象に、指定したエンティティをチェックします
• item:<name> — すべての GDD を対象に、指定したアイテムをチェックします

レジストリを読み込みます：

Read path="design/registry/entities.yaml"

ファイルが存在しない、またはエントリがない場合：

"Entity registry is empty. Run /design-system to write GDDs — the registry is populated automatically after each GDD is completed. Nothing to check yet."

判定：NOT ASSESSED — entity registry empty。停止します。比較対象がなかったため、PASS とは判定できず、書き込みも行いません。

レジストリから次の 4 つのルックアップテーブルを作成します。

• entity_map: { name → { source, attributes, referenced_by } }
• item_map: { name → { source, value_gold, weight, ... } }
• formula_map: { name → { source, variables, output_range } }
• constant_map: { name → { source, value, unit } }

登録済みエントリの合計数を数えます。次を報告します。

Registry loaded: [N] entities, [N] items, [N] formulas, [N] constants
Scope: [full | since-last-review | entity:name]

entity:<name> または item:<name> の場合、レジストリにその名前のエントリがなければ、判定は NOT ASSESSED — <name> is not in the registry となります。最も近い登録済みの名前を一覧表示して停止します。未登録の名前をチェックしても比較対象はなく、それは PASS ではありません。

---

Phase 2: 対象範囲内の GDD を特定

Glob pattern="design/gdd/*.md"

design/gdd/ 内にあるものの、システム GDD ではないドキュメントは除外します。 game-concept.md、systems-index.md、game-pillars.md、gameplay-tags.md、 entity-registry.md、fixture-swap-ledger.md、sound-bible.md、および gdd-cross-review-*.md（/review-all-gdds がここに書き込むレポート）です。

since-last-review モードの場合：

git log --name-only --pretty=format: -- design/gdd/ | grep "\.md$" | sort -u

最新の design/gdd/gdd-cross-review-*.md ファイルの作成日以降に変更された GDD に絞ります。

スキャンする前に、対象範囲内の GDD の一覧を報告します。一覧が空の場合（システム GDD が存在しない場合、または since-last-review で変更されたものが見つからなかった場合）、判定は NOT ASSESSED — no GDDs in scope となります。どのフィルターで 0 件になったかを伝えて停止します。何もスキャンしなければ競合は見つかりませんが、それは PASS ではありません。

---

フェーズ 3：Grep 優先の競合スキャン

登録済みの各エントリーについて、対象範囲内のすべての GDD でエントリー名を grep します。 全文は読み込まず、一致した行とその直近の文脈（前後 3 行）のみを抽出します。

これが最適化の核です。10 個の GDD をそれぞれ 400 行読む（計 4,000 行）代わりに、 エンティティ名 50 個を 10 個の GDD で grep します（対象を絞った検索 50 回、 それぞれヒット時に約 10 行を返します）。

実効ティアが standard の GDD では、必須セクション内のヒットのみを比較します。 実効ティアは GDD ごとに決まります。system_overrides.<stem> は、その GDD に対してプロジェクトのティアをどちらの方向にも上書きします（full の行があれば、すべてのセクションが比較対象になります）。そのような GDD ごとに ^## を一度 grep して見出しと行番号を取得し、各名前のヒットをその直上にある最も近い見出しに記録します。Overview、Detailed Rules / Detailed Design、Formulas、Edge Cases、Dependencies、Acceptance Criteria の配下にあるヒットのみを比較します。また、project.yaml で workflow_overrides.tuning_knobs: true が設定されている場合は Tuning Knobs も比較対象になります（このフラグは一度だけ確認します。このセクションを追加する場合にのみ有効です）。それ以外のヒット（フラグがない場合の Tuning Knobs、Player Fantasy、その他のセクション）は検出項目にならず、記録もしません。値を示すものはそれぞれ、レポートの Not checked at this tier 行に記載します（名前、GDD、セクション）。

3a：エンティティのスキャン

entity_map 内の各エンティティについて：

Grep pattern="[entity_name]" glob="design/gdd/*.md" output_mode="content" -C 3

GDD でヒットした場合、エンティティ名の近くに記載されている値を抽出します。

• 数値属性（数量、コスト、期間、範囲、レート）
• カテゴリ属性（タイプ、ティア、カテゴリー）
• 派生値（合計、出力、結果）
• entity_map に登録されているその他の属性

抽出した値をレジストリエントリーと比較します。

競合の検出：

• レジストリに [entity_name].[attribute] = [value_A] と記載されている。GDD に [entity_name] has [value_B] と記載されている。→ 競合
• レジストリに [item_name].[attribute] = [value_A] と記載されている。GDD に [item_name] is [value_B] と記載されている。→ 競合
• GDD に [entity_name] の記載があるが、属性が指定されていない。→ 注記（競合ではなく、検証不能）

3b：アイテムのスキャン

item_map 内の各アイテムについて、すべての GDD でアイテム名を grep します。以下を抽出します。

• 売値／価値／ゴールド価値
• 重量
• スタックのルール（スタック可能／スタック不可）
• カテゴリー

レジストリエントリーの値と比較します。

3c：数式のスキャン

formula_map 内の各数式について、すべての GDD で数式名を grep します。以下を抽出します。

• 数式の近くに記載されている変数名
• 記載されている出力範囲または上限値

レジストリエントリーと比較します。

• 変数名が異なる → 競合
• 出力範囲の記載が異なる → 競合

3d：定数のスキャン

constant_map 内の各定数について、すべての GDD で定数名を grep します。以下を抽出します。

• 定数名の近くに記載されている数値

レジストリの値と比較します。

• 数値が異なる → 競合

---

フェーズ 4：詳細調査（競合のみ）

フェーズ 3 で見つかった競合ごとに、競合する GDD の該当セクション全体を対象に読み、正確なコンテキストを確認します。

Read path="design/gdd/[conflicting_gdd].md"

（ファイルが大きい場合は、Grep でより広いコンテキストを確認してもかまいません）

セクション単位で読みます。Grep ツール（パターン ^#、コンテンツモード）で競合するセクションの見出しを探し、offset と limit を指定してその範囲を Read します。

全体のコンテキストを踏まえて競合を確認します。次の点を判断してください。

1. どの GDD が正しいか？ レジストリの source: フィールドを確認します。source GDD が正式な所有元です。これに矛盾する他の GDD を更新する必要があります。
2. レジストリ自体が古くなっていないか？ source GDD がレジストリのエントリー作成後に更新されている場合（git log で確認）、レジストリが古くなっている可能性があります。
3. これは実際の設計変更か？ 競合が意図的な設計上の判断を表す場合、解決手順は次のとおりです。source GDD を更新し、レジストリを更新してから、他のすべての GDD を修正します。

競合ごとに、次のように分類します。

• 🔴 CONFLICT — 複数の GDD で、同じ名前付きエンティティ／項目／式／定数の値が異なります。アーキテクチャの着手前に解決する必要があります。
• ⚠️ STALE REGISTRY — source GDD の値が変更されていますが、レジストリが更新されていません。レジストリの更新が必要です。他の GDD はすでに正しい可能性があります。
• ℹ️ UNVERIFIABLE — エンティティへの言及はありますが、比較可能な属性が記載されていません。競合ではなく、参照があることを記録するだけです。

---

フェーズ 5：レポートの出力

## Consistency Check Report
Date: [date]
Registry entries checked: [N entities, N items, N formulas, N constants]
GDDs scanned: [N] ([list names])
Scope: [all GDD sections | required sections only — workflow: standard | per GDD — name each GDD whose effective tier differs, and its tier]
Not checked at this tier: [each value stated outside the required sections (name, GDD, section) — or "none"; omit when every GDD is at `full`]

---

### Conflicts Found (must resolve before architecture)

🔴 [Entity/Item/Formula/Constant Name]
   Registry (source: [gdd]): [attribute] = [value]
   Conflict in [other_gdd].md: [attribute] = [different_value]
   → Resolution needed: [which doc to change and to what]

---

### Stale Registry Entries (registry behind the GDD)

⚠️ [Entry Name]
   Registry says: [value] (written [date])
   Source GDD now says: [new value]
   → Update registry entry to match source GDD, then check referenced_by docs.

---

### Unverifiable References (no conflict, informational)

ℹ️ [gdd].md mentions [entity_name] but states no comparable attributes.
   No conflict detected. No action required.

---

### Clean Entries (no issues found)

✅ [N] registry entries verified across all GDDs with no conflicts.

---

Verdict: PASS | CONFLICTS FOUND | NOT ASSESSED

判定：

• CONFLICTS FOUND — 1 件以上の競合が検出されました。解決手順を列挙します。
• NOT ASSESSED — 比較が行われていません。エンティティレジストリが空であるか、名前付きエンティティがレジストリにない（フェーズ 1）、または対象となる GDD がない（フェーズ 2）ためです。どちらに該当するかを明記してください。
• PASS — 競合はありません。少なくとも 1 つの GDD を対象に、確認したすべての値についてレジストリと GDD の内容が一致しています。

---

フェーズ 6：レジストリの修正

書き込む前に再読してください。 フェーズ 1 ではスキャン前にレジストリを読み取っていますが、その後、別のスキルやセッションによって変更されている可能性があります。編集する前に、現在の design/registry/entities.yaml を読み、該当セクション内のエントリーを見つけてください。編集の基準には、フェーズ 1 で見た内容ではなく、必ず現在のエントリーのテキストを使用します。新しいエントリーは、該当セクションの最後の既存エントリーの後に追加します。

古くなったレジストリエントリーが見つかった場合は、次のように確認します。

「古くなった [N] 件のエントリーを修正するため、design/registry/entities.yaml を更新してもよいですか？」

古くなったエントリーごとに、次の操作を行います。

• value／属性フィールドを更新する
• revised: を今日の日付に設定する
• 古い値を示す YAML コメントを追加する：# was: [old_value] before [date]

レジストリにない新しいエントリーが GDD で見つかった場合は、次のように確認します。

「レジストリにまだ登録されていない、GDD で言及されたエンティティ／項目が [N] 件見つかりました。 design/registry/entities.yaml に追加してもよいですか？」

複数の GDD に記載されているエントリー（システム間で共通する事実）のみを追加してください。

レジストリエントリーを削除してはいけません。 エントリーがすべての GDD から削除されている場合は、status: deprecated に設定します。

書き込み後、bash .claude/scripts/registry.sh validate を実行し、この書き込みで追加または変更したエントリーに関するすべての行（DUPLICATE、STATUS、LAYOUT 行、またはそのエントリーが指定したパスに対する PATH_MISSING 行）を、判定前に修正してください。他のエントリーに関する行は、依頼なしに修正せず、ユーザーに知らせてください。スクリプトがない場合、または何も出力されない場合は、レジストリのチェックを実行できなかったことを伝え、ファイルのヘッダーに記載されたルールと照らし合わせて、書き込んだエントリーを再読してください。

書き込み後：判定：COMPLETE — 整合性チェックが完了しました。 未解決の競合が残っている場合：判定：BLOCKED — アーキテクチャの着手前に手動で解決する必要のある競合が [N] 件あります。

6b: リフレクションログへの追記

🔴 CONFLICT エントリーが見つかった場合（解決済みかどうかを問わず）、 「docs/consistency-failures.md に [N] 件のエントリーを追記してもよいですか（存在しない場合は作成します）？」と尋ねます。許可されたら各競合のエントリーを追記し、許可されなかったら、競合を記録しなかったことを伝えます。

### [YYYY-MM-DD] — /consistency-check — 🔴 CONFLICT
**Domain**: [system domain(s) involved]
**Documents involved**: [source GDD] vs [conflicting GDD]
**What happened**: [specific conflict — entity name, attribute, differing values]
**Resolution**: [how it was fixed, or "Unresolved — manual action needed"]
**Pattern**: [generalised lesson, e.g. "Item values defined in combat GDD were not
referenced in economy GDD before authoring — always check entities.yaml first"]

docs/consistency-failures.md が存在しない場合は、追記する前に次のヘッダーを付けて作成します。

# Consistency Failure Log




| Date | GDD A | GDD B | Conflict Type | Status |
|------|-------|-------|---------------|--------|

その後、新しい競合エントリーを追記します。独断で記録を省略してはいけません。ファイルがないことは、競合の履歴を失う理由にはなりません。記録しないのは、ユーザーが「いいえ」と答えた場合だけです。

---

フェーズ 7：セッション状態と終了

production/session-state/active.md に、次の内容を黙って追記します（ファイルが存在しない場合は作成します）。

フェーズ 6 で実際に追記する docs/consistency-failures.md を参照してください。 ブレッドクラムは、後続のセッションがたどるために残すポインターです。どのファイルにも書き込まれないファイル名を記すと、後続のセッションは見つかることのない競合履歴を探しに行くことになり、その間エラーも発生しません。ここにレポートのファイル名をでっち上げてはいけません。

その後、AskUserQuestion ウィジェットで終了します。

• プロンプト: 「整合性チェックが完了しました。競合が [N] 件見つかりました。次はどうしますか？」
• 選択肢:
  • [A] 最優先の競合を今すぐ修正する
  • [B] 最も競合が多い GDD に対して /design-review を実行する
  • [C] ここで終了する

協働モードとガイド付きモードでは、スキルの最後を通常のテキストで締めくくってはいけません。必ずこのウィジェットで終了します。自律モードでは、調査結果と推奨される次のステップを出力し、その後 log_decision で記録します（ウィジェットは使用しません）。

---

復旧／参考情報

• PASS の場合: 設計理論に基づく包括的なレビューには /review-all-gdds を、MVP の GDD がすべて完成している場合は /create-architecture を実行します。
• CONFLICTS FOUND の場合: 指摘された GDD を修正し、解決を確認するために /consistency-check を再実行します。
• STALE REGISTRY の場合: レジストリを更新し（フェーズ 6）、検証のために再実行します。
• 問題を早期に検出するため、アーキテクチャ作成時ではなく、新しい GDD を作成するたびに /consistency-check を実行してください。