wiki-init

Wiki 初期化

ユーザー指定のパスに、LLM が管理する新しい Wiki を作成します。

事前確認

近くに既存の SCHEMA.md がないか確認します。存在する場合は、ユーザーに再初期化するか、既存の Wiki をそのまま使用するか尋ねます。

手順

1. 設定を収集する（一度に質問は 1 つ）

次の質問をします。

1. Wiki はどこに作成しますか？（絶対パス。例：~/wikis/ml-research）

2. ドメイン／目的は何ですか？（1 文）

3. どのような種類のソースを追加しますか？（論文、URL、コードファイル、トランスクリプトなど）

4. index.md でどのカテゴリを使用しますか？

   • 研究のデフォルト：Sources | Entities | Concepts | Analyses
   • コードベースのデフォルト：Modules | APIs | Decisions | Flows — コードベースに関する詳しいガイダンスは、このスキルのディレクトリにある codebase.md を参照してください
   • または、独自のカテゴリを指定します

5. 主にどの方法でこの Wiki を閲覧しますか？

   1. Obsidian（または [[wiki-link]] 対応ビューアー）— [[slug]] 構文を使用します
   2. GitHub／VS Code プレビュー／静的サイトジェネレーター／プレーン Markdown — [[slug](pages/slug.md)] 構文を使用します

   選択した方式は SCHEMA.md の link_style: obsidian または link_style: markdown として記録され、ほかのすべての Wiki スキルで適用されます。

2. ディレクトリ構造を作成する

<wiki-root>/
├── SCHEMA.md         ← conventions + absolute path (how other skills find the wiki)
├── config/
│   └── link-style.md ← cross-reference emit/parse rules (copied from this skill)
├── .gitignore        ← local-only / generated artifacts (audit reports, index) excluded from version control
├── bin/                  ← helper scripts (copied verbatim from this skill's assets/bin/)
│   ├── generate-index.py  ← regenerates wiki/index.md from page frontmatter (stdlib only)
│   ├── render-log.py      ← renders the operation log from git history (stdlib only)
│   ├── check-contradictions.py ← pre-commit gate: blocks staged pages flagged as contradicting
│   ├── lint-mechanical.py ← deterministic lint checks; full mode (JSON for wiki-lint) + --staged gate
│   └── hooks/pre-commit   ← tracked git hook chaining both gates (wired via core.hooksPath)
├── raw/              ← immutable source documents (you add these, LLM never modifies)
├── wiki/
│   ├── index.md      ← GENERATED catalog (gitignored) — never hand-edit; run bin/generate-index.py
│   ├── log.md        ← operation log — ONLY for non-git wikis (git wikis use git history)
│   ├── overview.md   ← evolving synthesis of everything known
│   └── pages/        ← all wiki pages, flat, slug-named (NO subdirectories)
└── assets/           ← downloaded images, PDFs, attachments

重要： wiki/pages/ はフラットな構造です。すべてのページはここに <slug>.md として配置します。サブディレクトリは作成しません。スラッグは小文字を使用し、単語をハイフンで区切ります。

選択したリンクスタイルのルールファイルを Wiki にコピーします。

• ユーザーがオプション 1（Obsidian）を選んだ場合：このスキルの config/link-style-obsidian.md を <wiki-root>/config/link-style.md にコピーします。
• ユーザーがオプション 2（markdown）を選んだ場合：このスキルの config/link-style-markdown.md を <wiki-root>/config/link-style.md にコピーします。

コピーするファイルは選択した 1 つだけです。Wiki 内では link-style.md に名前を変更します。ほかのすべての Wiki スキルは <wiki-root>/config/link-style.md を読み込み、相互参照の出力と解析方法を確認します。

<wiki-root>/.gitignore に、生成ファイルやローカル専用の成果物（監査レポートと生成されたインデックス）が含まれていることを確認します。Wiki が Git リポジトリである場合、または後から Git リポジトリになる場合に、不要な成果物がバージョン管理に含まれないようにするためです。既存の .gitignore を上書きしないでください。再初期化する Wiki や、既存の Git リポジトリ内にある Wiki のルートには、すでに .gitignore がある場合があります。

• <wiki-root>/.gitignore が存在しない場合は、以下のブロックを追加して作成します。
• 存在するものの、除外する行のいずれかが欠けている場合は、不足している行を追加します。
• すでに両方の行が設定されている場合は、変更せずそのままにします。

# Audit reports are regenerated local-only artifacts (wiki-audit). The committed record
# of an audit is the `review:` frontmatter token on the audited page, not the report.
wiki/pages/audit-*.md
# index.md is generated from page frontmatter by bin/generate-index.py — a runtime
# artifact, regenerated on demand. The source of truth is each page's frontmatter.
wiki/index.md

これは wiki-audit が自己修復に使用するものと同じ、作成または追記する手順です（タスク 4）。

3. SCHEMA.md を記述する

# Wiki Schema

## Identity
- **Path:** <absolute path to wiki-root>
- **Domain:** <user's domain description>
- **Source types:** <list>
- **Created:** <YYYY-MM-DD>

## Page Frontmatter
Every wiki page must start with:
---
title: <page title>
category: <one of the Index Categories below>
summary: <one-line description — becomes this page's index entry>
tags: [tag1, tag2]
sources: [source-slug1]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

`category` and `summary` drive index generation (see **Index Generation** below);
`category` must match one of the wiki's Index Categories. `created` is set once when the
page is first written and never changes; `updated` bumps on every edit.

## Cross-References
- **link_style:** <obsidian | markdown — the user's choice from step 1, question 5>
- **link_style_rules:** config/link-style.md
- See `config/link-style.md` for the exact emit and parse rules. Every wiki skill
  reads that file to decide how to write new cross-references and how to scan
  existing ones.

## Concept Identity

The slug **is** the concept's identity — there is no separate id. A concept is the
page at `wiki/pages/<slug>.md`; everything that links to it uses `[[slug]]`. This only
works if the link graph is trustworthy, so two rules hold everywhere links are written:

1. **Links are verified, never invented.** Before writing any `[[slug]]`, the slug must
   resolve to an existing `wiki/pages/<slug>.md` **or** to a page being created in the
   same operation. List the existing page set first (`ls wiki/pages/`); never emit a
   link to a slug you have not confirmed. A `[[slug]]` that resolves to nothing is a
   hallucinated link — the failure this discipline exists to prevent.

2. **Homonyms get qualified slugs.** When a new concept collides with an existing slug
   for a *different* sense, qualify both with a discriminator rather than overloading
   one page:
   - `mercury-planet` / `mercury-element` / `mercury-mythology`
   - `transformer-ml` / `transformer-electrical`

   Pick the narrowest discriminator that disambiguates. `wiki-lint` warns when slugs
   sharing a base token look like an unintended collision.

Consolidating two pages that turn out to be the same concept (merge), or separating one
overloaded page into qualified pages (split), is the job of the `wiki-merge` skill.

## Citations

Cite every non-common-knowledge factual claim. "Common knowledge" = uncontroversial,
undergraduate-level facts in this wiki's domain. Granularity is paragraph or claim,
never per-sentence. If you cannot produce a citation in one of the forms below,
find one, weaken the claim, or drop it.

Format: Markdown footnotes. Two citation kinds, three valid targets.
The slug-target form below follows the `link_style` declared above; the examples
shown here use that style.

**Quote citation** (preferred):

モデルは8つのアテンションヘッドを使用します。[^1]

[^1]: [[attention-is-all-you-need]] §3.2.2 L142-143 — "We employ h = 8 parallel attention layers" [^1]: [[attention-is-all-you-need](pages/attention-is-all-you-need.md)] §3.2.2 L142-143 — "We employ h = 8 parallel attention layers" ```

Synthesis citation (when no single quote captures the claim):

このアーキテクチャは、アテンションを備えたエンコーダー・デコーダーを基本としています。[^2]

<if link_style: obsidian>
[^2]: [[attention-is-all-you-need]] §3.2-3.4 [synthesis] L138-202 — encoder, decoder, and
      attention sections together describe the full multi-head architecture
<if link_style: markdown>
[^2]: [[attention-is-all-you-need](pages/attention-is-all-you-need.md)] §3.2-3.4 [synthesis] L138-202 — encoder, decoder, and
      attention sections together describe the full multi-head architecture

L142-143 / L138-202 are line ranges in the raw source file. For a quote they mark the lines the quote is taken from; for a synthesis they mark the block being summarized.

Three rules for every footnote:

1. The cited target is one of three forms:

   • A slug reference to a source-type wiki page, written in the wiki's link_style (preferred for sources you've ingested via wiki-ingest)
   • raw/<file> or assets/<file> — a path to a local file (for drive-by citations where a synthesis page isn't worth creating)
   • <URL> — a live URL, tweet, or ephemeral source (no local copy required)

   Never cite entity, concept, or analysis pages — those are syntheses, not sources.

2. A locator is present. Always a semantic locator: §<section>, p.<n>, [HH:MM:SS] for transcripts, URL anchor for web, or (YYYY-MM-DD) for dated posts.

   Plus a line-range when the source is text-addressable. If the resolved raw file is markdown, plaintext, code, or cached HTML, append a line-range token after the semantic locator:

   • L<start>-<end> — a range, e.g. L142-145
   • L<n> — a single line, e.g. L142
   • L142-145,L201-203 — disjoint ranges

   The line range refers to lines in the raw source file resolved from the target ([[slug]] → its **Source:** raw path; or a direct raw/<file>/assets/<file>). raw/ is immutable, so these line numbers are stable references.

   A line-range is required for text-addressable sources and applies to BOTH citation kinds — a [synthesis] footnote marks the block it summarizes with L… just as a quote marks the lines it quotes. Exempt (semantic locator only, no L…): PDFs, transcripts, and live URLs with no local cached copy.

3. Either a verbatim quote, or the [synthesis] tag plus a description of what the cited range supports. No third option.

Drive-by citation examples:

[^3]: raw/scaling-laws.pdf p.7 — "loss scales as a power law in compute"
[^4]: https://twitter.com/user/status/123 (2026-04-15) — "<tweet text>"

Cross-Model Review

wiki-audit strong runs a second-opinion pass with a different-provider model and stamps the audited page with an optional review: frontmatter block:

review:
  model: codex          # gemini | claude-sonnet
  provider: openai      # google | anthropic
  date: YYYY-MM-DD
  status: clean         # or: disputed
  findings: 2           # present only when status: disputed

• status: clean — the reviewer surfaced no disagreement with the normal audit.
• status: disputed — the reviewer flagged overreach or a contradiction the normal audit missed; findings: carries the count. The detail lives in the (local-only) audit report.
• provider: anthropic (the claude-sonnet fallback) means no different-provider CLI was available, so the check is same-provider and weaker.

This block is optional and is added only by wiki-audit strong. Pages never need it to be valid.

Contradiction Check

wiki-ingest runs a cheap contradiction check on the pages each ingest touches, before it commits. It is a gate, not an annotation: every page that lands in git is clean.

• Scope — touched neighbors only. The check compares the pages an ingest wrote or edited against (a) themselves and (b) the pages that ingest already read (the entity / concept pages it updated and the neighbor pages from its backlink audit). It does NOT re-read the whole wiki — a conflict with a distant, untouched page is left to the periodic wiki-lint sweep.
• Blocking vs. soft. A blocking contradiction is a real factual conflict on the same entity under the same scope — incompatible dates, counts, names, or mutually-exclusive claims. A soft tension (differing emphasis, values within plausible version / measurement variance, claims that hold under different scope) is not a conflict.
• The transient blocker flag. When a blocking contradiction is found, a single line is written to the affected page's frontmatter and the ingest stops before committing:

  contradiction-check: failed — <one-line reason naming the counterpart [[slug]] or "internal">
  

  機械可読トークンは、文字列どおりの contradiction-check: failed です。これは矛盾が未解決の間だけ存在し、矛盾を解消するとこの行が削除されます。コミット済みのページにこのトークンが含まれることはありません。passed の記録も、重大度の履歴もありません。このフラグがないことだけが「問題なし」の状態です。
• 軽微な不整合は提示しますが、記録しません — 取り込みの概要に記載するため、必要に応じて対応できますが、保存もブロックもされません。

このフラグは、以下のコミット前ゲートがステージ済みファイルをスキャンする際にも使用します。

コミット前ゲート

Git wiki では、bin/hooks/pre-commit（wiki-init が git config core.hooksPath bin/hooks を介してインストール）が、コミットのたびにLLMを使わず、決定論的なゲートを2つ実行します。

1. bin/check-contradictions.py — wiki/pages/*.md のステージ済みコンテンツをフロントマターのみスキャンし、contradiction-check: failed フラグが残っているページがあればコミットをブロックします。これは wiki-ingest の手順7bにあるスキルレベルの保留措置を補完するものです。正常なwikiでは作動しません。矛盾を解消して contradiction-check: の行を削除し、再度ステージしてください。
2. bin/lint-mechanical.py --staged — ステージ済みのページをスキャンして構造上の問題を確認し、問題があればコミットをブロックします。対象は、必須のフロントマターの欠落、壊れた [[link]]、スラッグの衝突（単独のスラッグが修飾付きスラッグと競合する場合）です。ページを修正し、再度ステージしてください。

• 新規クローンの場合： core.hooksPath はリポジトリローカルの設定であり、クローンされません。クローン後に一度、git config core.hooksPath bin/hooks を再実行してください。
• 意図的なコミットで上書きするには、git commit --no-verify を実行してください。

操作ログとコミット規約

操作：init、ingest、query、update、lint、audit、merge、split

Git wiki — Git の履歴が操作ログです。 操作後、スキルはコミットメッセージを提案し、確認後にコミットします（スキルが自動的にコミットすることはありません）。 必要に応じて、python bin/render-log.py で人間向けのログを生成します。

提案される件名行は、リポジトリのコミット規約に従います。

1. まず既存の規約を検出します — 直近の git log と、.gitmessage、commitlint の設定、CONTRIBUTING.md を確認します。リポジトリにすでに件名のスタイルがある場合は、それに従います。

2. 見つからない場合は Conventional Commits を既定とし、操作に応じて種別を選びます。

   操作	種別
   init	chore
   ingest	docs
   update	docs
   query (saved)	docs
   lint	修正を適用した場合は fix、それ以外は chore
   audit	修正を適用した場合は fix、それ以外は chore
   merge / split	refactor

件名のスタイルにかかわらず、必ず Wiki-Op: トレーラーを追加します。これを render-log.py がキーとして使用し、ログと件名の規約を切り離します。 変更されたページはコミット差分から読み取るため、Pages: トレーラーは不要です。

docs: summarize Attention Is All You Need

Wiki-Op: ingest

非 Git wiki — wiki/log.md にフォールバックします。 操作ごとに次の形式でエントリーを追加します。 ## [YYYY-MM-DD] <operation> | <title>.

インデックスの生成

wiki/index.md は生成される Git の無視対象ファイルです。手動で編集しないでください。ページのフロントマターから bin/generate-index.py で再生成します。

• インデックスを読む前と、ページの追加、削除、名前変更、またはカテゴリー変更を行う操作の後に、python bin/generate-index.py（または python3）を実行します。
• 生成スクリプトは、以下のインデックスカテゴリーに記載された順序で、ページをフロントマターの category ごとに分類します。各カテゴリー内では、created の新しい順にページを列挙します。各エントリーは - [[slug]] — summary _(created)_ 形式です。
• ファイル名が audit-*.md に一致するページは除外されます（Git で無視されるローカル専用の成果物です）。認識されない、または未指定の category を持つページは、Uncategorized セクションに配置されます。

インデックスカテゴリー

<ユーザーが選択した分類体系に一致するよう、1 行に 1 つずつ記載します>

規約

• raw/ は不変です — スキルが変更することはありません
• 操作ログ：git wiki では各操作をコミットとして記録します（「操作ログとコミット規約」を参照）。また、bin/render-log.py で表示します。git を使わない wiki では log.md に追記します（追記専用で、書き換えることはありません）
• index.md は bin/generate-index.py によって生成され、gitignore の対象です — 手動で編集しないでください。ページのフロントマター（category、summary）を設定してから、代わりに再生成してください
• すべてのページは wiki/pages/ 直下に配置します — サブディレクトリは作成しません
• overview.md には、すべてのソースを横断した現在の統合内容を反映します
• 相互参照と引用のスラッグターゲットは config/link-style.md に従います — すべてのスキルは、リンクを書き込む前またはスキャンする前にこれを読みます
• 矛盾チェック：取り込み時に、変更対象ページ内のブロッキング矛盾を確認します。一時的な contradiction-check: failed フラグを設定し、コミット前に削除します — コミット済みのページには常に矛盾がありません（「矛盾チェック」を参照）
• pre-commit ゲート：git wiki では、git が bin/hooks/pre-commit を実行し（core.hooksPath 経由）、続けて bin/check-contradictions.py を実行します。このスクリプトは、フラグが残ったページをステージングするコミットをブロックします（「Pre-commit ゲート」を参照）。新たにクローンした後は git config core.hooksPath bin/hooks を再実行してください
• README の境界：wiki ページで README の内容を重複させてはいけません。構造上の手がかりを抽出し、運用に関する内容（セットアップ、コントリビューション、実行）については README へのリンクを貼ってください。README を取り込む際は、内容の不足も評価し、編集案を提示してください。

### 4. Install the `bin/` helper scripts and generate the index

The wiki ships four stdlib-only helper scripts (no dependencies) plus a tracked git hook.
They are **bundled with this skill** at `assets/bin/` — copy them verbatim into
`<wiki-root>/bin/` (do not retype or regenerate them). From this skill's directory:

```sh
mkdir -p <wiki-root>/bin/hooks
cp assets/bin/generate-index.py       <wiki-root>/bin/
cp assets/bin/render-log.py           <wiki-root>/bin/
cp assets/bin/check-contradictions.py <wiki-root>/bin/
cp assets/bin/lint-mechanical.py      <wiki-root>/bin/
cp assets/bin/hooks/pre-commit        <wiki-root>/bin/hooks/
chmod +x <wiki-root>/bin/*.py <wiki-root>/bin/hooks/pre-commit

それぞれの役割：

• bin/generate-index.py — wiki/index.md はページのフロントマターから生成され、手書きではありません。そのため、実態と食い違うことはありません。コピー後に一度実行し（python bin/generate-index.py）、有効な index.md を作成してください。
• bin/render-log.py — 必要に応じて git 履歴から操作ログを表示します（SCHEMA.md の操作ログとコミット規約を参照）。git を使わない wiki で実行しても問題ありません — ログが log.md にあることを報告するだけです。
• bin/check-contradictions.py — pre-commit ゲートです（SCHEMA.md のPre-commit ゲートおよび矛盾チェックのセクションを参照）。P8 の contradiction-check: failed フラグが残った wiki/pages/ 内のファイルをステージングするコミットをブロックします。決定論的に動作し、LLM は使用しません。git を使わない wiki で実行しても問題ありません — 何もしません。
• bin/lint-mechanical.py — 2 つのモードがある、決定論的なヘルスチェックです。フルモード（python bin/lint-mechanical.py）では、wiki-lint のフェーズ 1 用 JSON（リンク切れ、孤立ページ、フロントマターの欠落、スラッグの衝突、日付の古さ、概念の欠落）に加えて、矛盾チェック用のタグクラスタ一覧を出力します。ステージ済みモード（--staged）は 2 つ目の pre-commit ゲートです。ステージ済みページにフロントマターの欠落、リンク切れ、またはスラッグの衝突があるコミットをブロックします。LLM は使用しません。git 作業ツリー外では何もしません。
• bin/hooks/pre-commit — uv run（インタープリターが必ず利用可能になります）経由で両方のゲート（check-contradictions.py、続けて lint-mechanical.py --staged）を実行する、追跡対象の git フックです。手順 5 で設定します。

5. 操作ログを設定する

操作の記録方法は、wiki が git リポジトリかどうかによって異なります。まだ git リポジトリでない場合は、git init の実行を提案してください — git 履歴によるログのほうが適しています。

• git リポジトリ： git 履歴そのものが操作ログです（SCHEMA の操作ログとコミット規約を参照）。log.md は作成しないでください。まず pre-commit ゲート（矛盾フラグと構造上の妥当性）を導入します。フックを実行可能にし、git に追跡対象のフックディレクトリを指定します —

  chmod +x bin/hooks/pre-commit
  git config core.hooksPath bin/hooks
  

  フックは追跡対象（以下でコミットします）ですが、core.hooksPath はリポジトリローカルの設定であり、新たにクローンした後は引き継がれません — クローン後に git config の行を再実行するようユーザーに伝えてください。次に初回コミットを提案し、ユーザーの確認を得てから実行します。

  chore: initialize <domain> wiki
  
  Wiki-Op: init
  

• git リポジトリではない場合： 代替の操作ログとして wiki/log.md を作成します。

  # Wiki Log
  
  Append-only fallback log (this wiki is not a git repo). Format:
  `## [YYYY-MM-DD] <operation> | <title>` — recent: `grep "^## \[" log.md | tail -10`
  
  ---
  
  ## [<today>] init | <domain>
  

6. wiki/overview.md を作成する

---
title: Overview
tags: [overview, synthesis]
sources: []
updated: <today>
---

# <Domain> — Overview

> Evolving synthesis of everything in the wiki. Updated by wiki-ingest when sources shift the understanding.

## Current Understanding

*No sources ingested yet.*

## Open Questions

*Add questions here as they arise.*

## Key Entities / Concepts

*Populated as pages are created.*

7. 確認

ユーザーに以下を伝えてください。

• Wiki は <path> に初期化されました。
• リンク形式：<obsidian | markdown> — ルールについては config/link-style.md を参照してください。後で切り替える場合は、このスキルの config/ ディレクトリにある別の形式のファイルに置き換え、SCHEMA.md の link_style: を更新してください。既存のページは自動変換されません。
• ソースは手動で raw/ に追加するか、URL またはファイルパスを指定して wiki-ingest を直接実行してください。
• Wiki を健全な状態に保つため、定期的に wiki-lint を実行してください。
• git wiki では、各操作がコミットとして記録されます。操作ログは python bin/render-log.py で確認できます。
• SCHEMA.md は、他のすべてのスキルがこの Wiki を見つけるために使用します。移動または削除しないでください。