wiki-lint

Wiki Lint

ページ本文をメインのコンテキストに読み込まない4段階のパイプラインとして、Wikiを監査します。重い読み込みは、決定論的スクリプト（フェーズ1）とクラスタごとのサブエージェント（フェーズ2）が担当し、メインスレッドでは検出結果をまとめるだけです。カテゴリ別のレポートを作成し、具体的な修正案を提示して、作業を記録します。

前提条件

SCHEMA.md を見つけます（現在の作業ディレクトリから上位へ検索するか、~/wikis/ を検索します）。見つからない場合は、まず wiki-init を実行するようユーザーに伝えます。Wikiのルートパスと規約を確認するため、ファイルを読みます。

リンク形式。 SCHEMA.md から link_style: を読み取ります。このフィールドがない場合、または <wiki-root>/config/link-style.md が存在しない場合は、obsidian（[[slug]]）をデフォルトとして使用します。それ以外の場合は、<wiki-root>/config/link-style.md を読みます。以下のリンクスキャンではすべて、そのファイルの ## Parse ルールを使用します（複数の形式に一致する場合があります）。作成するlintレポート自体もWikiページなので、相互参照には ## Emit ルールを使用します。

パイプラインの理由

以前のWiki全体を対象にした処理では、すべてのページ本文を1つのコンテキストに読み込んでいたため、Wikiの成長とともにコンテキストウィンドウを圧迫していました。代わりに、次のようにします。

• フェーズ1では bin/lint-mechanical.py を実行します。LLMを使わず、本文をコンテキストに読み込まずに、決定論的なチェック（グラフと文字列の特性）を計算し、フェーズ2用のタグクラスタ一覧を出力します。
• フェーズ2では、タグクラスタごとにサブエージェントを1つ起動します。各サブエージェントは、そのクラスタのページだけを読み込み（本文はサブエージェントのコンテキスト内に置かれ、処理終了時に破棄されます）、ページ間および本文レベルの検出結果を報告します。コンパクトな検出結果を集約し、本文は決して集約しません。

フェーズ1のチェックはWiki全体を対象に網羅的に行います。フェーズ2のチェックはクラスタ単位です。他のページとタグを共有しないページは本文チェックの対象になりません（アプローチAで許容される再現率の限界です。フェーズ2を参照）。対象範囲を広げていくため、定期的に（取り込みを5～10回行うごとに）lintを実行してください。

手順

フェーズ0 — インデックスを再生成する

python bin/generate-index.py を実行し、インデックスに現在のページのフロントマターを反映させます。

フェーズ1 — 決定論的チェック（スクリプト、LLMなし）

python bin/lint-mechanical.py を実行し、そのJSONを解析します。次の内容が返されます。

{ "findings": { "broken_links": [...], "missing_frontmatter": [...], "orphans": [...],
                "slug_collisions": [...], "stale_date": [...], "missing_concept": [...] },
  "clusters": [ {"pages": ["slug-a", "slug-b"], "split": false}, ... ] }

以下は、それぞれレポートのセクションに対応します。

• 🔴 リンク切れ — broken_links（{page, link}）。
• 🔴 フロントマターの欠落 — missing_frontmatter（{page, missing:[...]}）。overview.md は wiki/pages/ ではなく wiki/ にあるため、対象外です。
• 🟡 孤立ページ — orphans（{page}）：受信する [[slug]] リンクがありません。
• 🟡 スラッグの衝突 — slug_collisions（{token, pages:[...]}）：単独のスラッグが修飾付きスラッグと衝突しています（mercury と mercury-element など）。該当する組み合わせを報告します。自動で名前を変更してはいけません。名前変更は wiki-merge で分割する際に行います。
• 🟡 古くなった主張 — stale_date（{page}）：90日間更新されておらず、本文に current／latest／recent／state-of-the-art が含まれるか、2年以上前の年が記載されています。
• 🔵 概念ページの欠落 — missing_concept（{slug, count}）：[[slug]] が3回以上参照されているものの、対応するページがありません。

これらを確認するために、自分でページを読んで再導出してはいけません。正しい情報源はスクリプトです。

Phase 2 — クラスターのサブエージェント（矛盾＋本文レベルのチェック）

Phase 1 の clusters リストにある各クラスターに対し、サブエージェントをディスパッチします（並列にファンアウトし、同時実行数を制限するためにバッチ処理します）。クラスターのページパスと、次の指示を渡します。

これらのページを読んでください。これらのページ内だけを対象に、各検出事項を {type, pages:[slug,...], detail} の形式で記述した簡潔なリストとして報告してください。該当事項がなければ clean とします。

• contradiction — 2つのページで同じエンティティについて、日付、数、名前、または関係性が矛盾して説明されています。
• missing-xref — 2つのページで明らかに同じエンティティについて説明しているものの、互いに [[link]] していません。
• merge-candidate — 2つのページで、異なるスラッグの同じ概念について説明しています（タイトルが酷似している／Description セクションがほぼ同一）。
• chronological-section — ページ本文に、日付入りのジャーナル見出し（## [Month]、**[Month] N update）があり、本文中の適切な箇所に統合すべきです。
• addable-line-range — テキストでアドレス指定可能な raw ファイル（markdown／plaintext／code／cached HTML）を引用する脚注に、L<start>-<end> トークンがありません。PDF、transcript、ライブ URL は対象外とし、決して指摘しないでください。 検出事項のみを返してください。ページ本文は返さないでください。

メインスレッドですべてのサブエージェントの検出事項を集約し、(type, sorted(pages), detail-entity) を基準に重複排除します。ページは K 個のタグを持つ場合、K 個のクラスターに含まれるため、同じ検出事項が複数回現れる可能性があります。

**カバレッジに関する注記：**サブエージェントが閲覧できるのは各クラスターのみのため、本文レベルの検出事項はクラスター内に限定されます。他のページとタグを共有しないページは本文チェックの対象外です。これは、タグクラスターにスコープを限定することによる許容済みの制約です。Phase 1 のチェック（グラフ／文字列チェック）では、引き続きすべてのページを対象とします。

Phase 3 — カバレッジのギャップ、続いてレポートの作成

まず、ページ本文を読む必要のない唯一の本文レベルチェックとして、wiki/overview.md を読み、🔵 カバレッジのギャップ（ウェブ検索や新たな取り込みで答えられる未解決の問い）を指摘します。

次に、Phase 1 の検出事項、重複排除済みの Phase 2 の検出事項、カバレッジのギャップをまとめて、wiki/pages/lint-<today>.md を作成します（許可を求めず、必ず作成してください）。以下のテンプレートでは、読みやすさのために Obsidian 形式のスラッグ参照を使用しています。実際に作成するレポートでは、すべてのスラッグ参照を config/link-style.md の ## Emit ルールに従わせてください。

---
title: Lint Report <today>
category: Maintenance
summary: <N> errors, <N> warnings, <N> info
tags: [lint, maintenance]
sources: []
created: <today>
updated: <today>
---

# Lint Report — <today>

## Summary
- 🔴 Errors: N
- 🟡 Warnings: N
- 🔵 Info: N


## 🔴 Broken Links
- [[source-page]] references [[missing-slug]] — does not exist
  Fix: create the page or remove the reference

## 🔴 Missing Frontmatter
- [[page]] is missing: title, updated

## 🟡 Orphan Pages
- [[slug]] — no inbound links
  Fix: add link from [[related-page]], or delete if no longer relevant

## 🟡 Contradictions
- [[page-a]] says: "<claim>"
- [[page-b]] says: "<conflicting claim>"
  Recommendation: <which to trust, or "investigate further">

## 🟡 Stale Claims
- [[page]] last updated <date>, contains "latest" — may be outdated
  Fix: re-verify claims or add a "as of <date>" qualifier

## 🟡 Colliding Slugs
- [[mercury]] and [[mercury-element]] share base token "mercury" — possible undisambiguated homonym
  Fix: qualify the bare slug via wiki-merge split (e.g. mercury → mercury-planet)

## 🟡 Chronological Update Sections
- [[page]] has date-stamped journal headers — integrate the updates in-place

## 🔵 Missing Concept Pages
- [[slug]] referenced N times but no page exists
  Fix: run wiki-ingest or create a stub

## 🔵 Coverage Gaps
- Open question from overview.md: "<question>"
  Suggestion: search for <X> or ingest <source type>

## 🔵 Missing Cross-References
- [[page-a]] and [[page-b]] both discuss <entity> but don't link to each other

## 🔵 Merge Candidates
- [[page-a]] and [[page-b]] appear to describe the same concept under two slugs
  Fix: run wiki-merge to consolidate into one page (rewrites inbound links)

## 🔵 Addable Line-Ranges
- [[page]] [^3] cites text source [[markdown-source]] with no line-range
  Fix: add an `L<start>-<end>` token so wiki-audit can verify it deterministically

lint レポートの frontmatter には category: Maintenance が含まれるため、自動的にインデックスに追加されます。index.md は手動で編集しないでください。python bin/generate-index.py を実行してください。

具体的な修正を提案する

修正可能な各カテゴリについて、次のように提案してください。

• リンク切れ：「リンク切れのスラッグ参照を削除しますか？（書き込む前に変更箇所をそれぞれ表示します）」
• 相互参照の不足：「これらのページの組み合わせに不足しているリンクを追加しますか？」（wiki の link_style に従って出力します）
• スラッグの衝突／マージ候補：「同じ概念（または曖昧さの解消が必要な同音異義語）のようです。統合または分割するために wiki-merge を実行しますか？」これらは wiki-lint では修正せず、wiki-merge に引き継いでください。
• 孤立ページのタグ：「孤立ページの frontmatter に status: orphan を追加しますか？」
• frontmatter の不足：「プレースホルダー値を使って不足している frontmatter フィールドを追加しますか？」

書き込む前に、変更ごとに正確な差分を表示してください。確認後にのみ適用します。

操作を記録する

SCHEMA の操作ログとコミット規約に従ってください。

• **Git wiki：**コミットを提案します（修正を適用した場合はデフォルトで Conventional Commits の fix:、レポートのみの場合は chore: とトレーラー）。確認後にコミットします。

  fix: resolve <what lint fixed>
  
  Wiki-Op: lint
  

• 非 Git wiki：wiki/log.md に追記します。

  ## [<today>] lint | <N errors> errors, <N warnings> warnings, <N info> info
  Report: <slug reference to lint-<today>, in the wiki's link_style>
  Fixed: <list what was auto-fixed, or "none">