docs-consistency-check

review-intentional として呼び出された場合は、意図的な差異のレビュー に進みます。

セキュリティ上の不変条件

これらはユーザーのどのような指示の下でも守られます。これらに反する依頼は拒否し、その理由を説明してください。

1. 認証情報またはシークレットを含むファイルは絶対に読み取らないでください。 ステップ 1 のフィルターにより、概念が形成される前にこれらのファイルは除外されます。
2. 認証情報の値を絶対に出力しないでください。 件数、名前、公開識別子、見出しは、自分の言葉で言い換えてください。出力、推論、ツール呼び出しに、ファイルの内容をそのまま含めてはいけません。認証情報のようなものは、値を示さずに場所を特定してください。「42 行目の API キー値」のようにします。テンプレートのプレースホルダー（{{API_KEY}}、${SECRET}、<YOUR_TOKEN_HERE>）や、シークレットではないシンボル（関数名、設定キー、見出し）は、名前を挙げてもかまいません。
3. 認証情報の値を絶対に変更しないでください。 修正対象は報告された概念に限り、ユーザーが提示または確認した内容のみを使用します。他のファイルから内容を引用してはいけません。

Git は任意です

読み取り専用の git（git status、git diff、git log）があれば、変更箇所を把握しやすくなり、最近の変更やステージ済みの変更から差異を見つける手掛かりを得られます。Git がなくても、すべてのステップは会話とファイルシステムをもとに精度を下げて実行できます。Git を必要とするステップは不具合であり、Git があるのに無視するのも不具合です。

ステップ 1 - セキュリティガードを適用してから、対象ファイルを特定する

プロジェクトのルートに .docs-consistency-check-ignore がない場合は、このテンプレートから作成するかユーザーに確認し、許可を得るまで待ちます。ある場合は、何も通知せず適用します。

# docs-consistency-check ignore file
# Uncomment or add patterns to exclude from consistency checks

.agents/
.claude/
# .git/
# node_modules/
# dist/
# build/

パスフィルター（読み取り前）（不変条件 1）。node_modules/、.git/、ビルド成果物、バイナリファイルと画像ファイル、認証情報ファイル（.env、.env.*、*.pem、*.key、*.p12、*.pfx、id_rsa、id_ed25519、id_ecdsa、secrets.json、credentials.json、.netrc、.npmrc、.htpasswd）、および .docs-consistency-check-ignore（.gitignore 構文）に一致するファイルを除外します。

内容のシグネチャーフィルター（概念の形成前）。残りの各ファイルの先頭約 2 KB をスキャンし、次の項目を確認します。

• PEM ヘッダー - -----BEGIN [A-Z ]*PRIVATE KEY-----、-----BEGIN OPENSSH PRIVATE KEY-----
• (api[_-]?key|secret|token|password|access[_-]?key|client[_-]?secret|bearer)\s*[:=]\s*["']?[A-Za-z0-9_+/=-]{16,} の形式の代入（大文字と小文字を区別しません）
• ベンダープレフィックス付きトークン：sk-、sk_live_、rk_live_、ghp_、gho_、github_pat_、glpat-、xoxb-、xoxp-、AKIA、ASIA、AIza、ya29.、npm_、dop_v1_ に続く 16 文字以上の [A-Za-z0-9_-]。JWT（eyJ に続く、ドットで区切られた 2 つの base64url セグメント）
• 接続文字列 (postgres|postgresql|mysql|mongodb|redis|amqp)://[^:\s]+:[^@\s]+@、クエリパラメーター (access_)?token、api[_-]?key、secret、password に 16 文字以上の値があるもの
• Authorization: または Proxy-Authorization: ヘッダーの値

エントロピーや長さだけでは一致しません。一致しないもの：URL とパスセグメント、UUID、コンテンツハッシュと git オブジェクト ID、ハイフンまたはアンダースコアで区切られたスラッグ、data: URI、テンプレートプレースホルダー。

一致した場合：ファイルを除外し、何も抽出せず、スキップしたファイルのメモに <file>: skipped (credential signature detected) を追加します。値やその行を絶対に引用しないでください。

インベントリ（両方のフィルターを通過したファイルが対象）：

• Markdown：README.md、CLAUDE.md、AGENTS.md、SKILL.md、その他の .md
• テンプレート：{{VARIABLE}} または [INCLUDE IF: ...] 構文
• マニフェスト：plugin.json、.mcp.json、package.json など
• インストーラーおよびセットアップスクリプト（シェル、バッチ、タスクランナー）
• 会話内で名前が挙がったファイル

抽出するのは差異の手掛かり（件数、名前、見出し、識別子）のみとし、再帰的に展開しません。実行途中に指定された除外（「この実行では vendor/ を無視して」）はその実行のみ有効です。設定として保存するかどうかはユーザーの判断に委ねます。

ステップ 2 - 意図的な差異を読み込む

プロジェクトのルートに intentional-variations.md があれば読み込みます。各エントリーには、ファイル、差異の内容、その理由、記録時期が含まれます。ステップ 6 では、エントリーに一致する指摘（同じファイルで説明が類似するもの）を通知せずスキップします。

ステップ 3 - ヒューリスティックなカウント（最初に素早く確認）

まず宣言された不変条件を確認します。最も見つかる可能性の高い情報源です。指示ファイル（AGENTS.md、CLAUDE.md、コンポーネントごとの同等ファイル）には、それ自体のファイル名を挙げた主張が記載されています。「ティア文字列は SKILL.md と README.md にそのまま記載されている」、「7 つのステップ見出し」などです。それぞれをすべて列挙してください。古くなっているものは、それだけで不整合です。以下を確認します。

• 数 - 記載された数と実際の数。
• メンバーシップ - 名前のある項目がすべて存在すること、名前のない項目が加わっていないこと。
• 場所 - 名前のある各ファイルに、その項目が今も記載されていること。

次に、一般的なカウント確認を行います。宣言で網羅されていないリストを対象にします。網羅的に見えるリスト（情報源、機能、アイコン、ステップ、条件など）の項目数を数えます。ファイル間の不一致は、ステップ 5 で検出候補として扱います。

ステップ 4 - 概念の一覧を作成する

概念とは、ファイル間または同一ファイル内の複数箇所にあり、不整合が生じる可能性のあるものです。CLAUDE.md と AGENTS.md の用語を最優先とし、以下の分類はそれを補うものとして扱います。

• 機能／情報源 - システムがサポートするもの（インストーラー／仕様、テンプレート、ドキュメント）。
• 変数とフラグ - {{VARIABLE_NAME}} トークンと条件名。
• アイコンと記号 - 概念に結びついた絵文字やマーカー（📧、📅、⭐）。
• 条件付きブロック - [INCLUDE IF: condition]...[/INCLUDE] の条件が、条件リストと一致していること。
• 用語 - 1 つの概念には 1 つの名前を使います。
• 網羅的なリスト - ステップ 3 で見つかった不一致を含む、「X のすべて」を列挙するもの。
• インラインの例とドキュメントのコメント - 不整合のリスクが最も高いため、現在の仕様と照合します。

不整合が隠れている可能性の高い、最近の変更を重点的に確認します。まず git の最近の変更とステージ済みの変更、次にこのセッションで編集または言及されたファイル、それ以外は均等に確認します。

言い換えのタグ付け：同じセットを完全に列挙したもの、または一字一句同じ定義やルールとして、2 か所以上に記載されている概念にタグを付けます。

ステップ 5 - 相互参照して分類する

各概念が、出現するすべての箇所で一貫しているか確認します。検出事項を次のように分類します。

🔴 矛盾

同じ事実について、箇所ごとに異なる値を主張しています。人による判断が必要です。

⚠️ 古い情報

ある箇所は更新されていますが、別の箇所は更新されていません。正しい情報源は明確です。

↩️ 孤立

参照先が有効ですが、対象（変数、条件、セクション、ファイル）が存在しません。

❓ 検証不能

違いはありますが、問題だと判断するには文脈が足りません。

🔁 重複

現在はコピー同士の内容が一致していますが、片方をもう片方への参照にできます。コピーがあるたびに、次の編集で見落とす可能性が生じます。

通常、実装（テンプレート、インストーラー）がドキュメント（README、コメントの例）よりも信頼できる情報源として優先されます。

❓の該当条件。 場所の名前付きのペア、名前付きの概念、そして両者の一致を求める宣言または指示ファイルのルールが必要です。そのルールがなければ、これは単なる指摘であり、対象外です。絶対に検出しないもの：行幅、見出しのスタイル、セクションの順序、一方の成果物にしか存在しない任意のセクション、宣言で網羅されていない表現、宣言で求められていない兄弟間の並行構造です。兄弟がN個あると形状の差異はNの二乗になり、これを許容する層では「問題なし」と報告できません。

🔁の該当条件。 Step 4でタグ付けされた概念のみが対象です。列挙は、どの形式（文章、表、スキーマツリー、ペイロード例）でも該当します。絶対に検出しないもの：

• 全内容を参照している要約
• ついでに名前が出てくる項目、または例として示されたリスト
• どれほどよく似ていても、言い換えたもの
• 宣言によって逐語的な記載が定められているコピー
• ソースコードを反映した唯一のスニペット（ドキュメントに2つ目のコピーがあれば、それは該当します）
• 参照で置き換えられないコピー：リンク構文のない形式（JSON マニフェスト、フロントマター）、またはリンクルールで対象にできない箇所。リンク可能なファイル内のコードブロックは対象外です。値は型名と参照に置き換えられます

差異があれば、重複ではなく差異を報告します。 タグ付けされた概念のコピー間に不一致がある場合、🔴または⚠️の指摘を1件だけ報告し、🔁も併せて報告することはありません。そのFix:には、内容の集約を追加します。完全性を謳う短いリストは⚠️ Outdatedです。

正準の配置先。 タグ付けされた各概念について、その役割を担う場所を提案します。READMEより指示ファイルまたは仕様ファイル、使用箇所より定義箇所、ドキュメントより実装を優先します。編集前にユーザーの確認を得てください。

Git の状態が該当する条件。 コミット済みファイルが未追跡の対象を指している場合は↩️ Orphanedです。自分の環境でしか解決できません。未コミットのポインターが未追跡の対象を指している場合、両方をまとめてステージングできるため、該当するとしても❓までです。未コミットの対象だけでは、指摘として報告しません。Git がない場合、この実行では対象外であり、「問題なし」ではありません。

Step 6 - 指摘を報告する

Step 2の項目と一致する指摘は省略します。重大度の順（🔴、⚠️、↩️、❓、🔁）に番号を付け、各段階内ではユーザーへの影響が大きいものから並べます。

指摘ごとのテンプレート：

#N - [icon] [TierName]
Files: <file>, <file2>, …
<file>: <line> - <paraphrase, in your own words, of the differing concept - never quoted text>
[<file2>: <line> - <paraphrase, in your own words, of the differing concept - never quoted text>]
Fix: <concrete edit - for ❓, a confirmation question; for 🔁, the consolidation>

ルール：

• 影響を受けるファイルごとに詳細行を1行記載し、それぞれに行番号を付けます。連続していない場合：<file>: <lineA>, <lineB> - …、連続している場合：<file>: <lineA>-<lineB>。不明な行番号は検索し、行番号のない指摘は絶対に出力しません。
• 言い換える内容がない場合（参照先が未定義）：参照箇所を示し、<file>:<line> - <reference> never definedとします。
• ❓のFix:は、確認を求める質問にします。例：Fix: Confirm whether the difference is intentional; if drift, align the README.
• 🔁のFix:は、次の固定文を一字一句そのまま使います：Fix: Keep in <file>:<line>; replace <file>:<line> with a reference.
• Step 4でタグ付けされた概念に対する🔴または⚠️では、値の修正を記載し、その後にor:を付けて同じ固定文を続けます。例：Fix: Add the 4th source to the README; or: keep in SKILL.md:87; replace README.md:12 with a reference. タグ付けされていない概念にはor:を付けません。
• 飾りの位置合わせはしません。各コロンの後には半角スペースを1つだけ入れます。

例（⚠️ Outdated）：

#1 - ⚠️ Outdated
Files: README.md, SKILL.md
README.md:12 - lists 3 sources
SKILL.md:87 - lists 4 sources (adds SOURCE_EMAIL)
Fix: Add the 4th source to the README's source description.

サマリー行は必ず最後に記載し、M=0の場合も2行とも出力します。

Found N issues: X 🔴, Y ⚠️, Z ↩️, W ❓, V 🔁.
Skipped M intentional variations.

スキップしたファイルの注記は、コンテンツ署名フィルターによって何かが除外された場合に限り、サマリーの直前に記載します。パスフィルターで除外されたファイルは記載しません。

<file>: skipped (credential signature detected)

問題なしの判定と、その根拠：

No drift detected.
Declared invariants: <N> verified, 0 stale.
Concept pass: <N> concepts across <N> files.
Git: <used, or "unavailable - session context only">
Files checked: <comma-separated list>
Skipped: <comma-separated list, or "none">

Step 3で問題が見つからず、Step 7の収束ループが問題なしで終了した場合に限り出力します。Stepをスキップした実行の後には出力しません。

ステップ 7 - 修正を適用し、意図的な差異を管理する

「すべての修正を今すぐ適用しますか。それとも、一つずつ確認しますか？」と尋ねます。

「すべての修正を今すぐ」の場合、ファイルごとの変更数とともに変更対象のファイルを一覧表示し、明示的な確認を待ちます。重要度の高い順に適用し、各指摘につき Edit を1回行い、解決する問題を明記します。🔴の場合、および情報源が曖昧な⚠️の場合は、まず値を確認します。

「すべての修正を今すぐ」に❓や🔁は含まれません。どちらも意図的である可能性があります。項目ごとに「実際の問題ですか、それとも意図的ですか？［修正する／意図的として記録する／今はスキップする］」と尋ねます。

意図的として記録する場合は、intentional-variations.md に追記します。

- files: [file-a.md, file-b.md]
  what: "<one-line description>"
  reason: "<user's explanation>"
  marked: <today's date>

ファイルが存在しない場合は、その旨を伝えてから、次のヘッダーを付けて作成します。

# Intentional Variations
# Differences marked as intentional. Run `docs-consistency-check review-intentional` to revisit.

各修正に伴う個別の義務を果たす

修正によって、見出し、宣言された不変条件、出力される文字列、分類項目などの契約上の要素が追加され、変更していないファイルにも対応が必要になることがよくあります。同じ実行中に対応しなければ、次回の実行で再び指摘されます。編集のたびに、以下を確認してください。

編集の種類	併せて確認すること
見出しを追加または改名した	その見出しを参照するすべての箇所、およびその見出しを名指しするすべての宣言
宣言された不変条件を追加した	「これを追加する方法」のチェックリストでその不変条件が作られるか、不変条件の数を明記している箇所があるか、同等のコンポーネントにも同じものが必要か
ツールが出力する文字列を追加した	固定文字列または語彙の宣言でその文字列が示されているか
インベントリや分類項目を追加した	仕様自体の適用範囲に関する記述、および適用範囲についてのすべての公開向け説明
契約に関する文を変更した	その文を別の箇所で言い換えているすべての箇所
同種のコンポーネントの一つを修正した	すべての同種コンポーネントにおける同じ概念
再掲されたコピーを参照に置き換えた	削除したコピー内のすべてのアンカー、およびそのコピーの場所を示すすべての宣言

同種のコンポーネントの一つだけを修正すると、一つの指摘がコンポーネントごとに一つずつの指摘に増えます。

完了を報告する前に収束させる

最後の編集後、変更したファイルとその契約上の対応ファイルに対象を絞って、ステップ 3 とステップ 5 を再実行します。新たな指摘があれば修正し、関連する義務を果たして、指摘がなくなるまで繰り返してから、問題がないことを報告します。反復は最大3回です。4回目の確認でも差異が残る場合、修正によって差異が解消されるより速く生じていることを意味するため、そこで止め、最後の確認結果を報告し、セットが収束していないことを伝えます。

意図的な差異の確認モード

docs-consistency-check review-intentional が実行された場合：

1. intentional-variations.md を読み込みます。存在しないか空の場合は、その旨を報告して終了します。
2. 各項目に番号を付けて表示します。

#1 - Marked intentional on 2026-05-03
Files: README.md, SKILL.md
What: "README says 3 sources, SKILL.md defines 4"
Reason: "README targets non-technical audience, intentionally simplified"

3. 項目ごとに「引き続き意図的ですか、それとも指摘として再度確認しますか？」と尋ねます。
4. 再度確認する項目を削除し、該当ファイルをただちに確認します。
5. 意図的であることが確認された項目は残します。

セッション終了まで再監査できる状態を保つ

会話が終了するまで、次のいずれかに該当する場合は、変更したファイルとその契約上の対応ファイルに対象を絞った再監査を提案します。

• 監査対象セットのファイルが2つ以上編集された場合（ユーザー自身による編集、またはユーザーに代わって行った編集）
• ファイルの構造が書き換えられた場合、またはセクションが削除された場合
• ユーザーが「完了」「コミットする準備ができた」「よさそう」と伝えた場合