wiki-lint

Lint — Wiki の健全性チェック

書式規約、フロントマター、リンクについては wiki/CONVENTIONS.md に従ってください。

言語

成果物はユーザーの言語で記述してください。文法と、必要な発音区別符号や文字体系固有の文字を正しく使用してください。ユーザーの言語が不明な場合は、出力を生成する前に確認してください。

プロジェクトルート

このスキルでは、エージェントの現在の作業ディレクトリではなく、プロジェクトルート（作業対象のリポジトリ）からの相対パスで成果物を作成します。

• プロジェクト内から実行する場合は、このスキルに記載された相対パスを使用してください。
• 別のディレクトリ（例：隣接するリポジトリ、またはプロジェクトが別の場所にある場合）から実行する場合は、すべての成果物パスの先頭に <project-root>/ を付けてください。
• プロジェクトルートが不明確な場合は、書き込みを行う前にハーネスの質問ツールでユーザーに確認してください。

プロンプト

プロジェクト全体の規約である CLAUDE.md / AGENTS.md の「Skill Prompting Conventions」に従ってください。以下の判断事項では、ハーネスの構造化質問ツール（Claude Code の AskUserQuestion、Codex の ask_user_question、OpenCode の question）を使用してください。

判断事項	構造化質問にする理由	推奨する選択肢
対象範囲（複数選択可）	チェック対象に影響するため	フロントマター · リンク · 差異 · 空のサブフォルダー · すべて
安全な問題の自動修正	元に戻すのが難しい編集のため	報告のみ · 自動修正 · 問題ごとに確認

自由形式のプロンプト（構造化ツールは使用しない）：

• カスタムルールの説明

一時停止なしモード：ユーザーがスキル実行中の確認を明示的に無効にしている場合は、すべての構造化プロンプトを「未解決の質問」（または同等の項目）に記載し、処理を止めずに続行してください。

クエリ言語の整合性

意味的な Lint チェックでは、Wiki の言語で検索してください。言語は .wiki-guardrails.yml の query_language または language から判定し、ガードレールがない場合は Wiki のフロントマターまたはインデックスから判定してください。正確な名称とコード識別子はそのまま保持してください。ユーザーへのレポートはユーザーの言語で記述してください。

検索 — 利用できる場合は QMD を優先

意味的なチェック（孤立ページ、クロスリファレンスの欠落、矛盾）には、QMD（ローカルのハイブリッド検索）を使用してください。リポジトリごとのセットアップは一度だけ必要です。docs/wiki/qmd-setup.md を参照してください。純粋に構造的なチェック（フロントマター、リンク切れ）には、grep/glob を使う方法でも問題ありません。こちらのほうが高速です。

• ページの意味的な近接項目（孤立ページの候補、矛盾の候補、クロスリファレンスの欠落）を探す場合は、mcp__qmd__query（MCP）または qmd query --json --files（CLI）を使用してください。
• QMD には、探している内容を説明する intent: 行を必ず渡してください。
• qmd embed / qmd update は自動実行しないでください。Wiki が変更され、インデックスが古くなっている場合は、Lint の最後にその必要性を指摘してください。

チェックリスト

各項目を順番に確認してください。ユーザーが特定の項目（例：「リンクだけ」）を指定した場合は、その部分に集中してください。

1. クロスリファレンス切れ

• 存在しないページを指す相対リンク [text](./path.md)。
• リンクを修正するか、不足しているページを作成してください。

2. 孤立ページ

• wiki/index.md からのリンクがない Wiki ページ（CONVENTIONS.md、index.md、log.md を除く）。
• 孤立ページの候補ごとに、どの既存ページからリンクすべきかを見つけるため、intent: page describing <topic of orphan> を指定して QMD クエリを実行してください。
• 有効な内容がある場合は、index.md に追加し、意味的に関連するページからもクロスリファレンスを追加してください。
• 関連性がない場合は、人間に削除を提案してください。

3. フロントマター

すべての Wiki ページに以下を含める必要があります。

フィールド	必須	検証
title	はい	存在し、空でないこと
audience	はい	次のいずれかであること：business、dev、ops、mixed
sources	はい	空でないリストであること
updated	はい	ISO 日付であること。90 日を超えている場合はフラグを立てる
tags	はい	空でないリストであること
status	はい	次のいずれかであること：draft、stable、stale

型付きページの例外（kind: decision / kind: rule）： ADR とルールはこの一般的な表ではなく、型付きスキーマ（wiki/_schemas/typed-schema.yaml）に従います。status には型付きの列挙値（decision の場合は proposed | accepted | superseded | deprecated、rule の場合は active | deprecated）を使用し、フロントマターは wiki-policy-check（validate-schema モード）によって検証されます。ページに kind: decision または kind: rule がある場合、その status に対して draft|stable|stale を基準にフラグを立てないでください。また、一般的な表の要件をそのページに対するブロッカーとして扱わず、型付きスキーマに従ってください。型付きページの sources / updated は引き続き歓迎され、現在は型付きスキーマ ≥ v1.1.0 で許可されています。

4. raw/ ↔ wiki/sources/ の整合性

raw/index.md と wiki/sources/ を相互参照します。

• 要約のないソース — raw/index.md では取り込み済みとして参照されているものの、<slug>.md が存在しません。
• ソースのない要約 — sources: が存在しないファイルを指している wiki/sources/<slug>.md。

5. 対象読者の境界チェック

• wiki/apps/ 内のページにビジネスルール（価格設定、ポリシー、カスタマージャーニー、収益化）を含めないでください。含まれている場合は、そのルールを wiki/business/ に移し、apps/ のページには相互参照のみを残してください。
• Wiki コレクションに対して、apps/ にパスを限定した intent: business rule (pricing/policy/monetization/cancellation) のような QMD クエリを実行し、Wiki 内の混入を確認します。
• プロジェクトが兄弟ディレクトリとして保持し、技術的なルールのみを含めるという規約を定めている製品／コードリポジトリは、QMD にインデックス化せず、grep / Read を使って監査してください。これらのリポジトリをインデックス化すると、エージェントが製品リポジトリ内の文章を正式な情報源として扱うようになり、「Wiki が正規の情報源」という境界が曖昧になります。見つかったビジネスルールに関する記述は、wiki/business/ への移行候補として提示してください。

6. 相互参照の不足

• 実質的な内容を含む各 Wiki ページについて、タイトル／トピックで QMD クエリを実行し、上位 5～10 件の結果を確認します。意味的に関連するページ同士がリンクされていない場合は、フラグを立ててください。
• 人間に提案してください（ノイズが生じる可能性があるため、自動では修正しないでください）。

7. 矛盾

• 複数のページに記載されている各トピックについて、正規の記述を使った Hyde 形式のクエリ（例：hyde: The cancellation policy is X hours with Y consequence）で QMD を実行し、上位の結果を比較します。
• ページ間に矛盾がある場合は、そのページに注記を付けてフラグを立ててください。

8. 古くなったステータス

• stable にできる（内容が完成し、検証済みの）draft。
• updated が 90 日を超えている stable → stale への変更を検討します。

9. index.md の統計情報

• ページ数は実際の数と一致していますか？
• ページの説明は最新ですか？

10. QMD インデックスの健全性（QMD が設定されている場合のみ）

• mcp__qmd__status（または qmd status）を呼び出します。
• needsEmbedding > 0 の場合 → 担当者に qmd embed の実行を伝えます。
• wiki/ のファイル数と Wiki コレクションの totalDocuments が大きく異なる場合 → 担当者に qmd update の実行を伝えます。

動作

• 簡単な修正（フロントマター、リンク、updated）→ 自動で修正します。
• コンテンツの変更 → まず人間に確認します。
• 人間への回答：対応が必要な内容を中心にします。
  1. 人間の判断が必要な未対応項目
  2. 改善の機会
  3. 数値の要約（問題の総数／自動修正の数）
  4. 担当者が実行する必要のある QMD の再インデックス化コマンド（該当する場合）
• すべての自動修正を回答に列挙しないでください — 詳細は log.md に記載します。

ログ記録

wiki/log.md を更新します（ヘッダーの直後、先頭に挿入）：

## [YYYY-MM-DD] lint | health check

### Automatic fixes
- ...

### Pending (human decision)
- ...

### Suggestions
- ...

### QMD reindex needed
- qmd update / qmd embed (only if applicable)

型付きスキーマ検証（オプトイン）

Wiki の対象が型付きスキーマパターン（中央の wiki/_schemas/typed-schema.yaml に照らして検証される ADR、ルール、イベント）に従っている場合、wiki-policy-check スキルを validate-schema モードで呼び出すことで、リンターにスキーマチェックを任意で含めることができます。

モード

Wiki の .wiki-guardrails.yml から lint.includeSchema を読み取ります。

モード	動作	使用するタイミング
off（デフォルト）	スキーマ検証を完全にスキップします。オーバーヘッドはゼロです。レポートにも記載しません。	型付きスキーマを使用しない Wiki。パターンを使用していないプロジェクトでのリグレッションを避けるための、安全なグローバルデフォルトです。
warning	validate-schema を実行し、スキーマ警告を構造化フィールドとして報告します。ブロックしません（スキーマに問題があっても LINT_RESULT: PASS になります）。	初期展開時。ETL やブロックインジェストを中断せずに、ドリフトを検出できます。
block	validate-schema を実行し、スキーマエラー、重複 ID、または孤立した参照がある場合はリンターを失敗させます（LINT_RESULT: FAIL）。	warning モードが1～2スプリント安定して稼働し、プロジェクトの80%以上に有効な ADR／ルールが1つ以上あるようになった後です。下記の昇格基準を参照してください。

有効化

1. <wiki-path>/_schemas/typed-schema.yaml が存在するか確認します。
2. .wiki-guardrails.yml → lint.includeSchema を読み取ります（設定がない場合のデフォルトは off です）。
3. モードが off でない場合、以下を呼び出します。

   bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts \
     --wiki-path <wiki-path> \
     --format json
   

4. JSON 出力を解析します。
   • summary.invalid + summary.duplicate_ids + summary.orphan_refs → スキーマの問題の合計数。
   • 各 validations.decisions[i].errors、validations.rules[i].errors、validations.events[i].errors → 個別の問題。

リンターレポートへの統合

リンターレポートに以下を追加します（自動実行の場合は wiki/log.md、それ以外の場合は会話の応答に記載します）。

## [YYYY-MM-DD] lint | health check

### Schema validation (mode: warning|block)
- schema-warnings: <N>   (or schema-errors if mode=block)
- valid: <ADRs>+<Rules>+<events>
- invalid: <N> (with file+field+message details for each)
- duplicate_ids: <N>
- orphan_refs: <N>

### Automatic fixes
- ...

モードが off の場合、このセクション全体を省略します。

昇格基準（warning → block）

以下のすべてを満たした場合、Wiki を warning から block に昇格させます。

1. Wiki 内の3つ以上のプロジェクトに、有効な ADR またはルールが1つ以上ある（パターンが定着したことを示します）。
2. warning モードで2スプリント連続しており、遡及的に確認してもブロック対象となるスキーマエラーがゼロである（スキーマが実データに適合していることを示します）。
3. オーナーが明示的に確認している（昇格を了承する1行の PR コメントまたはコミットメッセージ）。

昇格について Wiki の wiki/log.md に記録し、昇格にあたってスキーマ制約を緩和した場合（まれです）は、スキーマの version フィールドを更新します。

適用範囲

• これはグローバルではなく、Wiki ごとのオプトインです（.wiki-guardrails.yml を使用）。型付きスキーマパターンを使用しない Wiki では、動作に変更はありません。
• スキル wiki-policy-check --mode validate-schema が、有効な内容を定める正式な情報源です。このスキル（wiki-lint）は呼び出しを調整し、出力を統合するだけです。
• block モードをグローバルデフォルトにしてはいけません。typed-schema.yaml のない Wiki でエラーが発生します。

参照

• wiki-policy-check §モード 2 — スクリプト駆動のバリデーター（Epic #4 Story 02、wiki-service で実施）。
• ADR-0009 typed-schema（knowledge-center リポジトリなし）— スキーマ仕様と13件の確定済み決定事項。
• Epic #4 Story 05（wiki-lint-integration-gradual）— この統合。