grounded-vault

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grounded Vault

A grounded vault is a three-layer Markdown store in which every compiled claim can be traced back to an immutable source and every page can be checked for staleness with one

git diff

. It needs a git repository and nothing else. The convention comes from the

llm-wiki-loop

project, which is a reference implementation rather than a dependency; this skill teaches the pattern so it works with plain files and whatever agent is in the session.

Grounded Vault是一种三层Markdown存储结构，其中每个编译后的声明都可追溯到不可变来源，且每个页面只需通过一次

git diff

即可检查是否过期。它仅需一个Git仓库，无需其他依赖。该约定源自

llm-wiki-loop

项目，该项目是参考实现而非依赖项；本技能旨在传授该模式，使其可用于普通文件及会话中的任意Agent。

When to Use

适用场景

An agent compiles notes, papers, transcripts, logs, or code into wiki pages that later sessions rely on.
A page cites numbers, dates, or quotes, and a reader must be able to verify each one against its source.
Pages describe code, and rereading the codebase every session to check whether they still hold is too expensive.
Knowledge must be corrected without losing history: superseded pages are archived, never deleted.

Session state, task queues, and conversation continuity are a different problem; use the context-management or conductor plugins for those. This skill is about provenance and drift on a durable knowledge store.

Agent将笔记、论文、 transcripts、日志或代码编译为wiki页面，供后续会话使用。
页面引用数字、日期或引用内容，读者必须能够针对来源验证其中每一项。
页面描述代码，而每次会话都重新读取代码库以检查内容是否有效成本过高。
知识需要在不丢失历史的情况下进行修正：过时页面会被归档，而非删除。

会话状态、任务队列和对话连续性属于不同问题；可使用上下文管理或conductor插件处理这些场景。本技能聚焦于持久化知识库的溯源与漂移检测。

The three layers

三层结构

Layer	Contents	Who writes it	Rule
`raw/`	source material: notes, papers, transcripts, logs, exported data	people and ingestion only	immutable once added; agents never edit a raw file
`wiki/`	compiled pages built from `raw/` and from code	agents and people	every number, date, and quote links to its source
`archive/`	pages that drifted or were superseded	agents, during garbage collection	moved, never deleted; the header says why

Two files sit at the vault root.

index.md

is the map of every current page.

log.md

is an append-only record of what changed and why. Both change in the same commit as the page they describe.

层级	内容	编写者	规则
`raw/`	源材料：笔记、论文、 transcripts、日志、导出数据	仅人工和导入工具	一旦添加则不可变；Agent永远不会编辑原始文件
`wiki/`	基于 `raw/` 和代码编译生成的页面	Agent和人工	每个数字、日期和引用都需链接到其来源
`archive/`	已漂移或被取代的页面	Agent（垃圾回收时）	仅移动，不删除；页面头部需说明原因

存储库根目录下有两个文件：

index.md

是所有当前页面的映射；

log.md

是仅追加的变更记录及原因。两者会与所描述的页面在同一提交中更新。

Page header contract

页面头部约定

Every

wiki/

page opens with a header block:

markdown

undefined

每个

wiki/

页面都以头部块开头：

markdown

undefined

Authentication architecture

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


- `Raw:` lists every source the page was compiled from. Inline claims link to their specific source as well: `Tokens expire after 15 minutes ([raw/adr/0007-jwt.md](../raw/adr/0007-jwt.md)).`
- `Fingerprint:` is the short commit hash the page was compiled against.
- `Monitored:` lists the code paths the page describes. A change to any of them after the fingerprint means the page may be stale.
- `Status:` is `Current`, `Outdated` (monitored code moved on), or `Disputed` (a newer source contradicts the page).

Raw: raw/notes/auth-v1.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`（新来源与页面内容矛盾）。

Grounding rule

可信规则

A compiled page states only what a source supports, and every number, date, or quotation appears verbatim in the linked source. A synthesis says it is one and links its inputs. A gap in the sources is written into the page as a gap rather than filled by guessing.

Check it mechanically: for each linked claim, search the linked raw file for the exact figure or quoted phrase. A miss is a grounding error and blocks the commit. The script in

references/details.md

does this for a whole vault.

编译后的页面仅陈述来源所支持的内容，每个数字、日期或引用都需与链接来源中的内容完全一致。综合内容需明确说明并链接其输入来源。来源中的空白需如实写入页面，而非通过猜测填补。

可通过机械方式检查：针对每个链接的声明，在链接的原始文件中搜索确切数字或引用短语。未找到则视为可信错误，将阻止提交。

references/details.md

中的脚本可对整个存储库执行此检查。

Drift detection

漂移检测

Compare the fingerprint with the current tree instead of rereading monitored code:

bash

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

Empty output means the page still describes the code it was compiled against. Any output means recompile: reread only the changed files, update the page, and stamp the new fingerprint. The check runs in milliseconds and spends no model tokens.

无需重新读取监控代码，只需将指纹与当前代码树进行比较：

bash

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

输出为空意味着页面仍能准确描述其编译时对应的代码。任何输出都需重新编译：仅重新读取已变更的文件，更新页面，并标记新的指纹。该检查仅需数毫秒，且无需消耗模型令牌。

Workflow

工作流程

Ingest. Put new material in
```
raw/
```
under a dated or sourced filename. Never rewrite an existing raw file; add a new one beside it.
Compile. Write or update the
```
wiki/
```
page with the header block, a source link on every claim, and the fingerprint of the commit the code was read at.
Check. Run the grounding check and the drift check before committing. Fix misses at the source; do not weaken a claim to make the check pass.
Garbage collect. When drift or a contradicting source appears and the page is not recompiled now, change its status, move it to
```
archive/
```
, and record the reason:
markdown
```
> Status: Outdated
> Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01
```
Update the map. Every add, move, or archive updates
```
index.md
```
and appends one line to
```
log.md
```
in the same commit.

导入：将新材料放入
```
raw/
```
目录，命名需包含日期或来源信息。切勿重写现有原始文件；需在其旁添加新文件。
编译：编写或更新
```
wiki/
```
页面，包含头部块、每个声明的来源链接，以及读取代码时对应的提交指纹。
检查：提交前运行可信检查和漂移检查。需从源头修复未通过项；切勿为通过检查而弱化声明。
垃圾回收：当出现漂移或矛盾来源且当前不重新编译页面时，修改其状态，将其移至
```
archive/
```
目录，并记录原因：
markdown
```
> Status: Outdated
> Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01
```
更新映射：每次添加、移动或归档操作都需更新
```
index.md
```
，并在同一提交中向
```
log.md
```
追加一行记录。

Commit gate

提交校验

Run both checks from a pre-commit hook or a CI step so a page cannot land with an unverifiable number or a stale fingerprint:

bash

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

通过预提交钩子或CI步骤运行两项检查，确保页面不会存在无法验证的数字或过期指纹：

bash

python3 scripts/check_vault.py --strict   # 若存在可信错误或过期页面则返回1

Going deeper

深入了解

references/details.md

covers: the vault check script, batching the drift check across pages, templates for

index.md

and

log.md

, renamed or deleted monitored files, sources that are binary or live at external URLs, and the reference implementation.

references/details.md

涵盖以下内容：存储库检查脚本、跨页面批量漂移检查、

index.md

和

log.md

模板、已重命名或删除的监控文件、二进制来源或外部URL来源，以及参考实现。