kb-lint

kb-lint — バンドルのヘルスチェック

バンドルに蓄積するドリフト、つまり成長するナレッジベースに生じる劣化を検出し、蓄積しても信頼できる状態を保ちます。確認は2段階です。決定論的な適合性チェック（機械的、スクリプトによる）と、ドリフト監査（曖昧さを含む、判断が必要な作業）です。両方を実行し、指摘事項を重大度別に報告してください。fixを指定すると、安全に修正できる項目を修復します。

1. 適合性（決定論的）

バンドル全体の形式またはライフサイクルを移行する場合は、まず同じフロントマター対応チェッカーで有効なメタデータを一覧化します。

node "<skill-dir>/scripts/conformance.mjs" <bundle-dir> --inventory --json

この一覧化処理では、各コンセプトの先頭にあるYAMLフロントマターのみを解析し、本文中の# Citationsは別途報告します。observationsには、有効なトップレベルキーとステータス値ごとの件数および正確なパスが含まれます。legacy_citationsには、引用セクション、番号付き項目、個別に定義された脚注ソース、ソースレコードの合計、およびよくある引用形式の件数が含まれます。structured_sourcesには、ポストフライト対象のコンセプト、エントリ、およびresourceを持つエントリの件数が含まれます。観測項目がない場合、その値は0です。本文やコードフェンス内の例には無効なフィールド名やライフサイクル値が含まれる場合があるため、有効なメタデータの分類にリポジトリ全体のgrepを使用しないでください。件数に基づく計画を立てる前に、報告されたフロントマターのエラーをすべて解決してください。

同梱のチェッカーを対象バンドル（デフォルトはknowledge/）に対して実行します。これは依存関係のないNodeスクリプトです（node >=18）。<skill-dir>はこのスキルのディレクトリです。Claude Codeでは${CLAUDE_SKILL_DIR}を使い、それ以外の場合はホストがスキル用に公開するパスを使います。

node "<skill-dir>/scripts/conformance.mjs" <bundle-dir>

ハードなSPEC §11違反はERROR、任意のv0.2フィールドにおけるプロデューサープロファイルの不備、リンク切れ、ISO形式ではないログの日付、古い日付はwarnとして報告されます。任意のフィールド群に関する警告によって、バンドルが不適合になることはありません。リンク切れは§6.1で明示的に許容されています。

**完了基準：**チェッカーを実行し、報告されたすべてのERRORをレポートに記載します（fixモードの場合は修正します）。

2. ドリフト監査（判断）

チェッカーでは意味を判定できません。蓄積される成果物が劣化する原因をすべて監査してください。これこそ、リンターを実行する価値を生む地道な作業です。以下のチェックをすべて実施してください。

• 矛盾 — conflicts_with で相互にリンクされていない、相反する事実を主張する概念。
• 古くなった主張 — より新しいソースによって置き換えられているにもかかわらず、superseded_by が付与されていない記述。子概念より古い概要。
• 孤立した概念 — 被リンク数がゼロの概念（相互リンクがない概念）。index／log は対象外、概要も対象外です。
• 相互参照の不足 — 同じエンティティ／テーマに関する概念同士がリンクされていない状態。
• カバレッジの不足 — 複数の概念で繰り返し名前が挙がっているのに、独自の概念がないエンティティ。ソースやウェブ検索で補えるデータの不足。
• 出典情報の不足 — 外部の主張を含む概念に、OKF v0.2 の sources も、レガシー形式の # Citations／Reference の記載もない状態。
• v0.2 メタデータのドリフト — resource のない sources エントリー、対応する sources[].id がない脚注ラベル、不正な generated／verified の作成者または日付、無効なライフサイクル値、および必須のランタイムまたは計算コントラクトが不足している Attested Computations。
• リポジトリのドリフト — 更新が続くリポジトリのドキュメントについて、sources[].resource に記載されていないパス、文書化された動作をもはや裏付けていない証拠、または spec/repository_state.md の documented_revision 以降に概念へ影響する変更があったにもかかわらず、対応する更新がない状態。同ファイルに documented_worktree: true が残っている場合は、現在の作業ツリーと比較してください。リポジトリの証拠または Git 履歴を利用できない場合は、このチェックをスキップしてください。
• スキーマのドリフト — 使用されているのに spec/types.md にない型、概念をもはや適切に表していない文書化済みの型、表記／大文字小文字のバリエーション、または繰り返し現れる実質的に異なる複数のエンティティ種別を、1 つの過度に汎用的な型で隠している状態。未使用の文書化済みの型はエラーではなく Info として扱ってください。

完了条件： 上記のすべてのチェックをバンドル全体に対して実施し、サンプルではなく、検出事項をすべて記録していること。

3. レポート

検出事項をチェック項目ごとにまとめ、それぞれに以下のタグを付けてください。

• Error — §11 の準拠要件違反。修正されるまで、バンドルは準拠していません。
• Warning — 信頼性を損なうドリフト（矛盾、古くなった主張、孤立した概念、リンク切れ）。
• Info — 提案（カバレッジの不足、追加を検討すべき概念やソース）。

カバレッジの不足は、具体的な次のアクションに落とし込んでください。調査する質問、取り込むソース、またはkb-documentを通じて確認するリポジトリの証拠を提示します。日付入りの概要（件数と主な検出事項）を、追記のみの形式でバンドルの log.md に追記してください。

完了条件： 重大度ごとにまとめたレポートを提出し、log.md に概要を追記していること。

修正モード

fix を指定して実行された場合は、安全かつ明確なものだけを修正し、その後、修正済みの内容と人間の判断が必要な内容を再報告してください。

• 自動修正してよいもの： 古くなった概要（子概念から再生成）、不足している相互リンク、不正なログの日付、明らかなリンク先があるリンク切れ、ファイルとの不整合がある index エントリー。
• 自動修正してはならないもの： 主張の意味を変えるあらゆる変更。矛盾や古くなった主張は、ここでその場の編集によって意味を変えるのではなく、信頼モデルに従って取り込みを行い（置き換え／矛盾）、解決してください。型の改名、統合、分割、非推奨化、移行にもユーザーの確認が必要です。提案するスキーマ変更と影響を受ける概念を併せて報告してください。意味の更新が必要な、更新が続くリポジトリの動作については、kb-documentに振り分けてください。kb-document は、ソースの証拠とリビジョンログを用いて、信頼モデルにおける限定的なバージョン管理リポジトリの例外を適用します。

完了条件： 安全に修正できる問題をすべて修正し、意味に関わる問題には手を加えず、すべて明示していること。再報告では、両者を区別してください。