llm-wiki-okf

name	llm-wiki-okf
description	docs/ 配下の OKF (Open Knowledge Format v0.2) 形式ナレッジベースを探索・構築・維持し、コードと同期させるプロシージャ

LLM-Wiki (OKF v0.2) 運用プロシージャ

0. ナレッジベースの初期化 (Init Protocol)

「ナレッジベースを初期化して」「Wikiをセットアップして」などの指示を受けた場合、または docs/ が存在しない場合：

1. リポジトリルートに docs/, docs/raw/, docs/architecture/, docs/domain/, docs/infrastructure/ ディレクトリを作成する。
2. スキル配下の templates/ から以下をコピーして配置する：
   • templates/README.md.template -> docs/README.md
   • templates/log.md.template -> docs/log.md
3. コピー完了後、docs/log.md の日付（YYYY-MM-DD）を本日の日付に置き換える。

1. 知識の参照 (Query Protocol)

ユーザーから実装・設計・調査の指示を受けたら、コードを変更する前に以下の順序でナレッジをロードします：

1. docs/README.md（または docs/index.md）を読み、該当するサブカテゴリを特定する。
2. 必要な概念ページ（例: docs/domain/payment.md）にアクセスし、仕様やデータ構造を理解する。
3. ナレッジに記載がない場合のみ docs/raw/ のソースを参照する。

2. ソース取り込みと計画見直し (Ingest Protocol)

docs/raw/ に新しい仕様書や改訂された実装計画が追加された場合：

1. 追加された raw ソースを解析し、抽出された概念ごとに 1トピック=1ファイル で概念ページを作成・更新する。
2. 概念ページの YAML フロントマターには以下を記述する（OKF v0.2 準拠）：
   • type: 概念の種別（必須。例: Concept, Architecture Decision, Data Model, Configuration など）
   • sources: 参照した出所情報のリスト（必須）。各エントリに resource（例: /docs/raw/xxx.md）を含める。本文で引用する場合は id を付与する。
   • status: ライフサイクル状態（draft | stable | deprecated。デフォルトは stable）
   • generated: { by: <actor>, at: <ISO8601> }（生成主体と日時）
     • Actor 命名規則: エージェントの場合は agent/<model-name>、人間の場合は human:<name>、自動処理の場合は process:<id>
   • title, description, tags（推奨）
3. 差分・矛盾検出 (Contradiction Check): 既存の概念ページと新しい raw ソースの間に仕様の矛盾がある場合、サイレントに上書きせず、人間に対して差分（diff）と変更箇所を明示して確認を取る。
4. docs/raw/ には、ユーザから新たな実装計画を示された場合にのみ追加し、それ以外の目的で追加・編集・削除をしない。

3. コード開発とナレッジ更新 (Update Protocol)

ソースコードの生成・修正が完了した際：

1. 実装によって確定した詳細（インターフェース、例外型、関連コンポーネント等）を、対応する概念ページ（docs/ 配下）に書き戻す。
2. 更新時は generated（または検証時は verified）を更新する。
3. 廃止された仕様には status: deprecated を設定し、代替先があれば superseded_by: <path> を付与する。
4. docs/log.md の最上部に、## YYYY-MM-DD 形式で変更内容の要約を追記する。エントリの先頭には * **Update**: ..., * **Creation**: ..., * **Deprecation**: ... などのプレフィックスを用いる。

4. ナレッジの静的検証 (Lint Protocol)

ドキュメントの更新後、または独立した要求時に以下をチェック・自動修復する：

1. 予約ファイル名の保護: README.md（または index.md）および log.md は予約ファイル名であり、個別の概念ページ名として使用されていないことを確認する。
2. リンク切れの防止: 存在しない Markdown ファイルへの参照（デッドリンク）を修正する。
3. 孤立ページの修正: どのページからも参照されていない概念ページがあれば、適切な README.md や関連概念ページからリンクを繋ぐ。
4. フロントマター検証: すべての概念ファイルに type および有効な YAML 構文が存在することを確認する。

5. ドキュメント記法・フォーマット規約

1. GitHubフレンドリーなインデックス（README.md）の扱い:
   • OKF仕様では index.md が標準ですが、GitHub上での閲覧性・レンダリング互換性を最優先するため、本リポジトリでは各ディレクトリのインデックスとして README.md を主軸（Primary）として運用します。
   • index.md が存在する場合は README.md への参照または同一内容として扱います。
2. Mermaid ダイアグラムの安全な記述 (パースエラー防止):
   • 日本語、半角空白、および記号（丸括弧 ()、角括弧 []、不等号 <>、コロン :、スラッシュ / 等）を含む場合、GitHub やパーサーの誤認を防ぐためノード名 ["..."] およびエッジラベル |"..."| は必ずダブルクォーテーションで囲む。
3. パスと環境情報の抽象化 (プライバシー・移植性ガードレール):
   • 特定の個人環境に依存した絶対パス（/home/username/...）や実ローカル IP（10.x.x.x）の記述は厳禁。常に相対パス（./docs/...）またはダミー値（/path/to/..., 192.168.1.100）を使用する。