# wiki/CLAUDE.md — LLM wiki レイヤー運用ガイド この vault は `claude-obsidian` の LLM wiki ワークフローを**新規ソースのみ・独立 wiki レイヤー共存**方針で導入している。`wiki/` 配下を操作する前に、このファイルと [`meta/conventions.md`](meta/conventions.md) を必ず読む。一般的なリポジトリ運用は vault ルートの [`AGENTS.md`](../AGENTS.md) を参照する。 ## VAULT 構造 既存(温存・wiki-ingest で書き換えない): - `papers/` — 論文ノート(`YYYY__SOURCE__Title.md`、事実上のソース DB) - `research/` — プロジェクト・時系列軸の研究ノート(aiops/tsifter/meltria/conferences 等) - `structures/` — MOC(`*.MOC.md`、人間がキュレートする索引。central entry: `structures/000 Index.md`) - `notes/` `floating/` `books/` `Clippings/` `00_inbox/` — その他既存ノート 新設(LLM wiki レイヤー): - `.raw/` — 新規ソースの**不変原本**(`papers/` `conferences/` `articles/` `images/`)。ingest は read-only で読む - `wiki/` — LLM 生成の横断知識 - `sources/` ソース要約(一望は [[sources.base]])、`entities/` 実体(一望は [[entities.base]])、`concepts/` 概念(一望は [[concepts.base]])、`questions/` query 回答、`asks/` 単一 source への軽い質問(1 論文 1 ノート、日付ごとに積み増し。§14)、`briefs/` 配布用紹介文(1 source = 1 ノート。§15)、`surveys/` 横断編纂、`meta/` 規約・lint・[[token-discipline]] - `index.md` カタログ / `hot.md` 直近コンテキスト(トークン上限の窓) / `log.md` 操作履歴(追記式・先頭追加) / `overview.md` - `.vault-meta/` — `mode.json`(generic) / `transport.json`(filesystem) / lock 等 - `scripts/` — `wiki-mode.py` `wiki-lock.sh` `detect-transport.sh`(plugin からのローカルコピー)、`fetch-paper-pdf.sh`(`wiki-ingest-paper` の PDF 取得ヘルパー)、`fetch-book.sh`(`wiki-ingest-book` / `wiki-ingest-thesis` の PDF 取得・章分割ヘルパー。後者は `--raw-root .raw/theses` で呼ぶ)、`wiki-resolve.py` / `wiki-excerpt.py` / `wiki-catalog.py` / `wiki-retrieve-refresh.py` / `wiki-concept-stats.py`(トークン規律。[[token-discipline]] 参照)、`contradiction-index.py`(矛盾 callout の索引・検索・片側検出。conventions §5)、`recompile-queue.py`(再編纂キュー。compile 負債の永続化と却下理由。conventions §8 更新ルール 6)、`claim-audit.py`(命題の再検証パケットと台帳。conventions §5)、`wiki-graph.py`(wikilink と共通出典のページグラフ。`retrieve.py` の第 3 路として BM25 の種から近傍ページを補い、`wiki-retrieve-refresh.py` が再構築する)、`wiki-clusters.py`(スキル世界のテーマ塊。`lookup` / `members` だけをスキルから呼ぶ。`.vault-meta/clusters.json` は Read しない)、`concept-candidates.py`(新設閾値に届かない concept 候補の台帳。ingest が `add`、`wiki-resolve.py` が `ledger:` ヒント、lint が到達を報告。conventions §12 ルール 5)、`paper-ids.py`(source の arXiv ID / DOI 索引。`fetch-paper-pdf.sh` が取得前に `check` して `existing_sources=` を返し、`backfill` が `arxiv_id:` / `doi:` を埋め、lint が重複論文を報告。conventions §3)、`entity-resolve.py`(同一人物・同一組織の別ページを strong / medium / weak の候補対として検出。読み取り専用。`plan` が統合の影響範囲、`decide` が判断の台帳。統合は wiki-refactor が人間承認で行う。conventions §12 ルール 6)、`wiki-profile.py`(人間所有の `research/curation/profile.md` を 25 行に要約して出す読み取り専用の要約器。ingest の concept 新設・保留判断(conventions §12 ルール 3)と wiki-query deep / wiki-survey の枠付けが読む。profile.md 自体の蒸留は paper-curation `--refresh-profile`)、`wiki-context-pack.py`(目標に対する引用付き・予算内・省略明示のコンテキスト束。`retrieve.py` の候補か `--pages` の指定を `wiki-excerpt.py` の抜粋で予算に詰め、入らないページは outline か「省略」として末尾に列挙する。subagent への引き継ぎと長い作業の再開に使う。読み取り専用)、`wiki-doctor.py`(機械状態の健全性検査。索引の鮮度、消えたページを指す chunk、残留ロック、address 計数器と重複、`.raw/.manifest.json` の整合、台帳 JSON、hot 窓、一時ファイルを OK / WARN / FAIL で出し、直すコマンドを添える。wiki-lint の最初に走らせる。読み取り専用) ## wiki 操作の鉄則 1. **wiki を操作する前に必ず [`meta/conventions.md`](meta/conventions.md) を読む**。frontmatter・命名・言語(日本語常体)・出典規約は既存 vault に合わせる(標準形式より conventions が優先)。 2. **スコープは新規ソースのみ**。既存 `papers/`・`research/` は ingest しない。今後 `.raw/` に投入する新規ソースだけを wiki 化する。 3. `.raw/` 配下のファイルは**不変**(`.raw/.manifest.json` のみ wiki-ingest が更新)。 4. `wiki/log.md` は**先頭に追記**、過去エントリは編集しない。 5. **既存 `papers/`・`research/`・`structures/`・`notes/` を wiki-ingest で書き換えない**。MOC への逆リンク追記は**人間承認時のみ** 1 件単位。 6. transport は filesystem 固定(`.vault-meta/transport.json` は `manual_override: true`)。`scripts/detect-transport.sh` のローカル版は GUI バイナリ誤検出を無効化済み。bare 実行や plugin 同梱 `scripts/` の直接実行はしない(VAULT_ROOT が plugin 側を指すため)。 7. **DragonScale address は導入済み**(`scripts/allocate-address.sh`、`.vault-meta/address-counter.txt` + `.address.lock`)。新規ページ(source/entity/concept)作成時は必ず `bash scripts/allocate-address.sh` を実行して `address: c-NNNNNN` を frontmatter に入れる。flock による atomic 採番なので並行 ingest(複数 subagent)から個別に呼んでも安全。既存ページ更新時は再採番しない。BM25 retrieve(`scripts/bm25-index.py` 等、`.vault-meta/bm25`)も導入済み。詳細は `claude-obsidian:wiki-retrieve` skill を参照。 8. **lock 有効**: `flock`(util-linux, keg-only)を導入済み。`scripts/wiki-lock.sh`(ローカルコピーは flock のパスを自動解決する)で per-file ロックが効くため、並行 ingest(複数セッション/サブエージェント)も安全。通常の wiki ページは書き込み前に `bash scripts/wiki-lock.sh acquire <path>`、書き込み後に `release <path>`。`wiki-catalog.py` は自己 lock するので、カタログコマンドを `wiki-lock.sh` で包まない。`index.md`・`hot.md`・`log.md`・各 `_index.md` は Read+Edit せず catalog スクリプトだけを使う。 9. **トークン規律**: `wiki/index.md`・各 `_index.md`・`wiki/log.md`・`wiki/hot.md` の全文を ingest / query の入力にしない。発見は `wiki-resolve.py`、本文は `wiki-excerpt.py`、カタログ更新は `wiki-catalog.py`、照会は `retrieve.py` を第一経路にする。詳細は [`meta/token-discipline.md`](meta/token-discipline.md)。 10. **テーマ塊**: id を wiki ページへ書かない。Gap Finder 報告の `#id` と `wiki-clusters.py` の id を突合しない。`.vault-meta/clusters.json` を Read しない。見るなら `wiki-clusters.py lookup` / `members`。 ## レイヤーと skill の役割分担 | やりたいこと | 使う skill | 出力先 | |---|---|---| | **新規論文の取り込み(PDF 原本ごと wiki 化)** | `wiki-ingest-paper` | `.raw/papers/*.pdf` + `wiki/{sources,entities,concepts}/` | | **博士論文・長編サーベイ(30p超・章構造)の章単位取り込み** | `wiki-ingest-thesis` | `.raw/theses/<slug>/` + `wiki/{sources,entities,concepts}/` | | **書籍(PDF/章別ウェブ)の章単位取り込み** | `wiki-ingest-book` | `.raw/books/<slug>/` + `wiki/{sources,entities,concepts}/` | | 新規会議トークの詳細メモ | `create-conference-note` | `research/conferences/`(2 層) | | 技術記事の詳細メモ | `create-tech-note` | `notes/`(従来どおり) | | **論文以外の複数ソース横断の定義・関係・矛盾の集約** | `wiki-ingest` / `autoresearch` | `wiki/{sources,entities,concepts}/` | | wiki への質問・引用付き回答 | `wiki-query` | 回答 + `wiki/questions/`(standard 以上は既定で保存。quick は保存しない) | | **既に ingest 済みの 1 source への軽い確認・深掘り質問** | `wiki-ask-source` | `wiki/asks/`(1 source = 1 ノート、日付ごとに Q&A を積み増し。source 側 frontmatter に `asks:` で相互リンク。conventions §14) | | **既に ingest 済みの 1 source の配布用紹介文(Slack 等)** | `wiki-brief-source` | `wiki/briefs/`(1 source = 1 ノート。source 側 frontmatter に `brief:` で相互リンク。conventions §15)。旧名 `summarize-paper-note` | | **1 つの命題の判定(支持 / 反対 / 機序 / メタ / 隣接で根拠を集め、supported / partially / contradicted / insufficient / mixed)** | `wiki-thesis` | `wiki/questions/`(`type: thesis`)+ 出自 concept の `## 未解決の問い` を閉じる | | **ギャップ(wiki-gap の real-gap)・閉じなかった命題(insufficient / mixed)・未解決の問いからの研究着想 1 本と新規性の照合** | `wiki-ideate` | 承認後に `research/ideas/<題>.md`(新規 1 枚)+ 出自 concept の受信箱に 1 行。wiki と arXiv / DBLP で近い仕事を novel / incremental / already-done に判定 | | **蓄積済み wiki の横断編纂(教科書・サーベイ・文献横断調査)** | `wiki-survey` | `wiki/surveys/`(長編 1 枚) | | wiki の健全性チェック | `wiki-lint` | `wiki/meta/lint-report-*.md` | > [!important] `create-paper-note` は使わない。論文は `papers/` に単一ソース詳細メモを作らず、`wiki-ingest-paper` で **PDF 原本を `.raw/papers/` に置きつつ wiki レイヤーに一本化**する(詳細メモは `wiki/sources/` の source ページ本文に含める)。既存 `papers/` ノートは温存し、wiki から一方向参照するのみ。 判断基準: **論文 = `wiki-ingest-paper`**、**博士・修士論文と 30 ページ超で章構造を持つサーベイ = `wiki-ingest-thesis`**、**書籍・書籍の章 = `wiki-ingest-book`**、**会議トーク・技術記事の単一ソース詳細メモ = `create-conference-note` / `create-tech-note`**、**論文以外の複数ソース横断 = `wiki-ingest`**。いずれも wiki から既存一次ノート/MOC へは一方向参照でつなぐ。 蓄積後の出力側の判断基準(**設問が何を求めているかで決める。出力の行数や文献本数で決めない**): **既読の 1 source について「ここが分からない」を確認する軽い質問 = `wiki-ask-source`**(`wiki/asks/`。§14)、**既読の 1 source を Slack 等へ貼る配布用紹介文 = `wiki-brief-source`**(`wiki/briefs/`。§15)、**単発の問いへの引用付き回答、単一ソースの深掘り解説、2 対象の差分 = `wiki-query`**、**真偽または成立条件を問う 1 つの主張の判定(「〜は本当か」「〜と言えるか」、concept の `## 未解決の問い` を閉じる)= `wiki-thesis`**、**設計空間の体系・文献母集団の地図・対象の像の横断構築を求める長編編纂(教科書・サーベイ・文献横断調査)= `wiki-survey`**、**完成した `wiki/surveys/` ページの外部公開用清書 = `wiki-publish`**。`wiki-survey` は母集団が薄いとき、`wiki-thesis` は命題に触れる source が 2 本未満のとき(insufficient)、`autoresearch` または `wiki-ingest-*` へ差し戻す(`wiki-query` へは戻さない)。 典型フロー(新規論文): 1. `wiki-ingest-paper` に arXiv URL / ID / PDF URL / ローカル PDF を渡す(例: `この論文を wiki に https://arxiv.org/abs/XXXX`)。 2. ヘルパー `scripts/fetch-paper-pdf.sh` が PDF 原本を `.raw/papers/<slug>.pdf` に配置し、`pdftotext` でテキスト抽出。 3. `wiki/sources/` に詳細メモ込みの source ページ、`wiki/entities/`・`wiki/concepts/` に横断集約を作り、関連 `structures/*.MOC.md` へ一方向リンク。 ## 概念ページ層(導入の主目的) 既存 vault に欠けていた「異常検知 / Fault Localization / 分散トレーシング / AIOps」等の **cross-project 概念集約**を `wiki/concepts/<原名>.md` で育てる。各 concept は (1) 定義、(2) 主題別の節(命題を単位に、根拠を入れ子で)、(3) `## 未解決の問い` と `## 未編纂の観察`(ingest の唯一の追記先。旧名 `## 横断的知見`)、(4) 関連 source/entity への wikilink と関連 `structures/*.MOC.md` への一方向参照、(5) 矛盾は contradiction callout を持つ。受信箱に溜まった観察を主題節へ畳む**再編纂**は `wiki-refactor`(`references/recompile.md`)の領分で、ingest は主題節を書き換えない(conventions §8)。 ## Git - `wiki/`・`scripts/`・`.vault-meta/{mode,transport}.json` は git 管理する。 - コミット規則(auto-commit の扱い、コミットメッセージ規約)はルートの [`CLAUDE.md`](../CLAUDE.md#コミット) に一元化した。area には `wiki` を使う。