grounded-vault

Grounded Vault

グラウンデッド・ボールトは 3 層の Markdown ストアであり、コンパイルされたすべての主張を不変のソースまでたどることができ、すべてのページが古くなっていないかを 1 回の git diff で確認できます。必要なのは git リポジトリだけで、それ以外は何も要りません。この規約は llm-wiki-loop プロジェクトに由来しますが、それは依存関係ではなくリファレンス実装です。このスキルはパターンを教えるものであり、プレーンなファイルと、そのセッションにいる任意のエージェントで動作します。

使用する場面

• エージェントがノート、論文、文字起こし、ログ、コードを wiki ページにコンパイルし、後のセッションがそれを頼りにする場合。
• ページが数値、日付、引用を引用しており、読み手がそれぞれをソースと照合して検証できなければならない場合。
• ページがコードを説明しており、それが今も成り立つかを確認するために毎セッションでコードベースを読み直すのはコストが高すぎる場合。
• 履歴を失わずにナレッジを修正しなければならない場合。置き換えられたページはアーカイブされ、決して削除されません。

セッション状態、タスクキュー、会話の継続性は別の問題です。それらにはコンテキスト管理または conductor プラグインを使用してください。このスキルは、永続的なナレッジストアにおける来歴とドリフトに関するものです。

3 つの層

層	内容	書き手	ルール
raw/	ソース素材: ノート、論文、文字起こし、ログ、エクスポートされたデータ	人と取り込みのみ	追加後は不変。エージェントは raw ファイルを決して編集しない
wiki/	raw/ とコードから構築されたコンパイル済みページ	エージェントと人	すべての数値、日付、引用がそのソースにリンクする
archive/	ドリフトした、または置き換えられたページ	エージェント、ガベージコレクション時	移動され、決して削除されない。ヘッダーに理由が記される

2 つのファイルがボールトのルートに置かれます。index.md は現在のすべてのページの地図です。log.md は何がなぜ変更されたかの追記専用の記録です。どちらも、それが記述するページと同じコミットで変更されます。

ページヘッダーの契約

すべての wiki/ ページはヘッダーブロックで始まります:

# Authentication architecture

> Raw: [raw/notes/auth-v1.md](../raw/notes/auth-v1.md), [raw/adr/0007-jwt.md](../raw/adr/0007-jwt.md)
> Fingerprint: git:5b237fa
> Monitored: src/auth/jwt.ts, src/auth/session.ts, package.json
> Status: Current

• Raw: はそのページのコンパイル元となったすべてのソースを列挙します。インラインの主張も、その特定のソースにリンクします: Tokens expire after 15 minutes ([raw/adr/0007-jwt.md](../raw/adr/0007-jwt.md)).
• Fingerprint: はそのページがコンパイルされた対象の短いコミットハッシュです。
• Monitored: はそのページが記述するコードパスを列挙します。フィンガープリント以降にそれらのいずれかが変更されると、そのページは古くなっている可能性があります。
• Status: は Current、Outdated(監視対象のコードが先に進んだ)、または Disputed(より新しいソースがそのページと矛盾する)です。

グラウンディングのルール

コンパイルされたページは、ソースが裏付けることだけを述べ、すべての数値、日付、引用はリンクされたソースにそのままの形で現れます。統合である場合はその旨を述べ、その入力をリンクします。ソースの欠落は、推測で埋めるのではなく、欠落としてそのページに書き込まれます。

機械的に確認してください: リンクされた各主張について、リンクされた raw ファイルで正確な数値または引用句を検索します。見つからなければグラウンディングエラーであり、コミットをブロックします。references/details.md のスクリプトはこれをボールト全体に対して行います。

ドリフト検出

監視対象のコードを読み直す代わりに、フィンガープリントを現在のツリーと比較します:

git diff --stat 5b237fa..HEAD -- src/auth/jwt.ts src/auth/session.ts package.json

出力が空であれば、そのページはコンパイル対象のコードをいまだに記述しています。何らかの出力があれば再コンパイルします: 変更されたファイルだけを読み直し、ページを更新し、新しいフィンガープリントを刻印します。このチェックはミリ秒で実行され、モデルのトークンを消費しません。

ワークフロー

1. 取り込み。 新しい資料は raw/ に日付または出典を含むファイル名で配置します。既存の raw ファイルを書き換えず、その隣に新しいファイルを追加します。

2. コンパイル。 ヘッダーブロック、すべての主張に対する出典リンク、コードを読んだコミットのフィンガープリントを含めて wiki/ ページを作成または更新します。

3. チェック。 コミットする前に、グラウンディングチェックとドリフトチェックを実行します。不整合はソース側で修正し、チェックを通すために主張を弱めてはいけません。

4. ガベージコレクト。 ドリフトや矛盾する出典が現れ、そのページを今すぐ再コンパイルしない場合は、ステータスを変更し、archive/ に移動して、理由を記録します：

   > Status: Outdated
   > Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01
   

5. マップを更新。 追加、移動、アーカイブのたびに、同じコミットで index.md を更新し、log.md に 1 行追加します。

コミットゲート

検証できない数値や古いフィンガープリントを含むページがコミットされないよう、pre-commit フックまたは CI ステップから両方のチェックを実行します：

python3 scripts/check_vault.py --strict   # exits 1 on any grounding miss or drifted page

さらに詳しく

references/details.md では、vault チェックスクリプト、ページ間でのドリフトチェックのバッチ処理、index.md と log.md のテンプレート、名前変更または削除された監視対象ファイル、バイナリまたは外部 URL にある出典、リファレンス実装について扱っています。