wiki-stage-commit

Wiki ステージコミット — ステージ済み書き込みの昇格

LLM が作成し、公開中の Wiki に反映する前に人間の承認を待っている _staging/ 内のページを確認します。このスキルは、Vault の設定で WIKI_STAGED_WRITES=true の場合にのみ役立ちます。

開始前に

1. 設定を解決する — llm-wiki/SKILL.md の Config Resolution Protocol に従います。これにより、OBSIDIAN_VAULT_PATH と WIKI_STAGED_WRITES が得られます。
2. WIKI_STAGED_WRITES が設定されていないか、false の場合は、ユーザーに「ステージ済み書き込みモードは有効になっていません。この機能を使うには、.env に WIKI_STAGED_WRITES=true を設定してください。」と伝えます。その後、停止します。
3. _staging/ ディレクトリの一覧を読み込みます。

呼び出し形式

/wiki-stage-commit               # interactive review: show each file and ask accept/reject
/wiki-stage-commit --all         # accept all staged files without per-file review
/wiki-stage-commit --reject-all  # reject all staged files (move to _raw/ for manual editing)
/wiki-stage-commit --list        # list staged files with summary, no changes

手順 1: ステージ済みファイルの一覧表示

一覧の取得は CLI が担当します。自分で _staging/ を glob しないでください。

obsidian-wiki staging list --json

各項目には次の情報が含まれます。

フィールド	意味
staged_path	ステージ済みファイルの Vault 相対パス
live_path	ファイルの反映先（.patch.md は名前の元になったページを対象とします）
kind	new、update、patch のいずれか
staged_revision	現在表示されているステージ済みファイルのコンテンツハッシュ
live_revision	公開中のページのコンテンツハッシュ。まだ存在しない場合は null
staged_mtime	ステージされた日時

ユーザーに表示するすべてのファイルについて、staged_revision と live_revision を保持してください。これらがあることで、手順 3 ではエージェントによる並行書き込みを黙って上書きせず、処理を拒否できます。

一覧を報告します。

Staged files: 4 new pages, 2 updates

New pages:
  _staging/concepts/attention-mechanism.md        (staged 2026-09-08)
  _staging/entities/andrej-karpathy.md            (staged 2026-09-08)

Updates:
  _staging/concepts/transformer-architecture.md   (target: concepts/transformer-architecture.md)

Patches:
  _staging/skills/prompt-engineering.patch.md     (target: skills/prompt-engineering.md)

一覧が空の場合は、「ステージ済みの項目はありません。すべての書き込みがコミット済みか、まだステージ済み書き込みが作成されていません。」と報告します。

手順 2: ファイルごとのレビュー（対話モード）

ステージ済みファイルごとに（新規ページを先に、その後に更新ページを）処理します。

新規ページの場合：

概要を表示します。

--- New page: concepts/attention-mechanism.md ---
Title:    Attention Mechanism
Tags:     #ml #architecture
Summary:  Core building block of transformers — computes weighted sum of values based on query-key similarity.
Tier:     supporting
Confidence: 0.72
Sources:  papers/attention.pdf

[Preview first 20 lines of body]
...

Accept [a], Reject [r], Skip [s], Preview full [p]?

パッチファイルの場合：

構造化された差分を表示します。

--- Update: concepts/transformer-architecture.md ---
Source: _staging/concepts/transformer-architecture.patch.md

Proposed additions (+):
+ Transformers outperform RNNs on tasks requiring long-range dependencies. ^[inferred]
+ New source: papers/survey-2026.pdf

Proposed deletions (-):
- The attention mechanism was first described in [Bahdanau 2015].  (to be replaced by updated claim)

⚠️  Conflict check: live_revision no longer matches what was staged against. Review carefully.

Accept [a], Reject [r], Skip [s], Preview full diff [p]?

--all フラグが設定されている場合は、確認を求めず、すべてのファイルを承認します。 --reject-all フラグが設定されている場合は、確認を求めず、すべてのファイルを却下します。 --list フラグが設定されている場合は、一覧を出力した後（手順 1）に停止します。

手順 3: 決定を適用する

移動処理は機械的なもので、CLI がアトミックに実行します。手順 1 で取得したリビジョンを渡すことで、古い情報に基づく決定は明示的に失敗します。

新規ページの承認

obsidian-wiki staging promote <staged_path> \
  --expect-staged <staged_revision> --expect-new

--expect-new は、一覧表示後に公開中のページが作成されていた場合、その処理を拒否します。先に誰かが作成したということです。

更新ページの承認

obsidian-wiki staging promote <staged_path> \
  --expect-staged <staged_revision> --expect-live <live_revision>

ファイルの却下

obsidian-wiki staging discard <staged_path>

ファイルは _raw/rejected-<category>-<page>.md に移動され、手動で編集できるようになります。同じページに対する過去の却下ファイルが上書きされることはありません。2 回目の却下ファイルには -2 が付加されます。

パッチの承認

promote は .patch.md ファイルを拒否します。人間が読める差分を、周辺のテキストが移動している可能性のあるページにマージするのは、単なる名前変更ではなく判断を伴うためです。次の手順で手動対応します。

1. 対象ページとパッチを読みます。
2. + の追加と - の削除をマージとして適用します。ページ全体を上書きしてはいけません。
3. 対象ページの updated フロントマターを更新します。
4. obsidian-wiki staging discard <patch staged_path> を実行して、パッチをキューから削除します。

CLI が競合を報告した場合

終了コード 9 と stderr の conflict: ... は、一覧表示後にステージ済みファイルまたは公開中のファイルが変更されたことを意味します。ファイルは移動されていません。最新のリビジョンを取得して何も考えずに再試行しないでください。staging list を再実行し、変更内容をユーザーに示して、再度確認を求めます。このチェックの目的は、承認された内容が、実際に反映される内容と異なっていることを検出することです。

index.md はページをステージした取り込み処理によって更新されるため、昇格処理では変更しません。log.md には、CLI が呼び出しごとに STAGE_COMMIT 行を 1 行書き込みます。

手順 4: 追跡ファイルを更新する

CLI 自身が log.md に STAGE_COMMIT 行を追記します。ステージ済みファイルをすべて処理した後、昇格したページが表示されるように、インデックスとホットキャッシュを同期します。

obsidian-wiki memory sync --takeaways "Committed N staged pages; rejected M."

（--verb は指定しません。ログ行はすでに staging promote によって書き込まれています。）index.md、log.md、hot.md を手動で編集してはいけません。このコマンドはロックを取得するため、並行して書き込むプロセスによって更新が失われることを防げます。

手順 5: 報告

Stage commit complete.

✅  Accepted (N):
  concepts/attention-mechanism.md     → now live
  entities/andrej-karpathy.md         → now live
  concepts/transformer-architecture.md → updated (patch applied)

❌  Rejected (M):
  skills/fine-tuning-llms.md          → moved to _raw/rejected-skills-fine-tuning-llms.md

⏭️  Skipped (K):
  references/attention-is-all-you-need.md → still in _staging/

Staging queue: K files remaining

注意事項

• ステージングされたファイルには公開済みページと同じページテンプレートが使われており、承認待ちの状態で、すぐに反映できます
• パッチファイルは人が読める差分形式です。+ で始まる行は追加、- で始まる行は削除です。staging promote では処理できないため、自分でマージしてください（手順 3）
• index.md と log.md は取り込み時に常にすぐ更新されます（リスクの低い追跡用ファイルです）。ステージングを経由するのはカテゴリーのページのみです
• 移動処理は obsidian_wiki/staging.py にあります。このスキルが担うのは判断であり、ファイルの処理ではありません
• _staging/ ディレクトリは Obsidian のグラフビューで追跡されません。ページが Wiki に表示されるのは、反映後のみです