Grounded Vault

A grounded vault est un entrepôt Markdown à trois couches dans lequel chaque affirmation compilée peut être retracée jusqu'à une source immuable et chaque page peut être vérifiée pour son obsolescence avec un simple git diff. Il ne nécessite qu'un repository git et rien d'autre. La convention provient du projet llm-wiki-loop, qui est une implémentation de référence plutôt qu'une dépendance ; ce skill enseigne le pattern afin qu'il fonctionne avec des fichiers simples et n'importe quel agent dans la session.

Quand l'utiliser

Un agent compile des notes, des articles, des transcriptions, des journaux ou du code en pages wiki sur lesquelles les sessions ultérieures s'appuient.
Une page cite des chiffres, des dates ou des citations, et un lecteur doit pouvoir vérifier chacun d'eux par rapport à sa source.
Les pages décrivent du code, et relire l'ensemble du codebase à chaque session pour vérifier si elles tiennent toujours est trop coûteux.
Les connaissances doivent être corrigées sans perdre l'historique : les pages obsolètes sont archivées, jamais supprimées.

L'état de la session, les files de tâches et la continuité de conversation sont un problème différent ; utilisez les plugins context-management ou conductor pour cela. Ce skill concerne la provenance et la dérive sur un entrepôt de connaissances durable.

Les trois couches

Couche	Contenu	Qui l'écrit	Règle
`raw/`	matériel source : notes, articles, transcriptions, journaux, données exportées	personnes et ingestion uniquement	immuable une fois ajouté ; les agents ne modifient jamais un fichier raw
`wiki/`	pages compilées construites à partir de `raw/` et du code	agents et personnes	chaque chiffre, date et citation renvoie à sa source
`archive/`	pages qui ont dérivé ou ont été remplacées	agents, lors du nettoyage	déplacées, jamais supprimées ; l'en-tête indique pourquoi

Deux fichiers se trouvent à la racine de l'entrepôt. index.md est la carte de chaque page actuelle. log.md est un enregistrement append-only de ce qui a changé et pourquoi. Les deux changent dans le même commit que la page qu'ils décrivent.

Contrat d'en-tête de page

Chaque page wiki/ commence par un bloc d'en-tête :

# 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: liste chaque source à partir de laquelle la page a été compilée. Les affirmations inline renvoient également à leur source spécifique : Les tokens expirent après 15 minutes ([raw/adr/0007-jwt.md](../raw/adr/0007-jwt.md)).
Fingerprint: est le hash court du commit par rapport auquel la page a été compilée.
Monitored: liste les chemins de code que la page décrit. Un changement dans l'un d'eux après le fingerprint signifie que la page peut être obsolète.
Status: est Current, Outdated (le code surveillé a progressé) ou Disputed (une source plus récente contredit la page).

Règle de justification

Une page compilée énonce uniquement ce qu'une source appuie, et chaque chiffre, date ou citation apparaît textuellement dans la source liée. Une synthèse dit que c'en est une et renvoie à ses entrées. Un écart dans les sources est écrit dans la page comme un écart plutôt que comblé par deviner.

Vérifiez-le mécaniquement : pour chaque affirmation liée, cherchez le chiffre exact ou la phrase citée dans le fichier raw lié. Une absence est une erreur de justification et bloque le commit. Le script dans references/details.md le fait pour un entrepôt entier.

Détection de dérive

Comparez le fingerprint avec l'arborescence actuelle au lieu de relire le code surveillé :

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

Une sortie vide signifie que la page décrit toujours le code par rapport auquel elle a été compilée. Toute sortie signifie recompiler : relire uniquement les fichiers modifiés, mettre à jour la page et estampiller le nouveau fingerprint. La vérification s'exécute en millisecondes et ne dépense aucun token de modèle.

Workflow

Ingérer. Mettez le nouveau matériel dans raw/ sous un nom de fichier daté ou sourcé. Ne réécrivez jamais un fichier raw existant ; ajoutez-en un nouveau à côté.
Compiler. Écrivez ou mettez à jour la page wiki/ avec le bloc d'en-tête, un lien source sur chaque affirmation, et le fingerprint du commit auquel le code a été lu.
Vérifier. Exécutez la vérification de justification et la vérification de dérive avant de committer. Corrigez les absences à la source ; ne faites pas fléchir une affirmation pour que la vérification réussisse.
Nettoyer les déchets. Quand une dérive ou une source contradictoire apparaît et que la page n'est pas recompilée maintenant, changez son statut, déplacez-la vers archive/, et enregistrez la raison :
```
> Status: Outdated
> Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01
```
Mettre à jour la carte. Chaque ajout, déplacement ou archivage met à jour index.md et ajoute une ligne à log.md dans le même commit.

Portail de commit

Exécutez les deux vérifications à partir d'un hook pre-commit ou d'une étape CI afin qu'une page ne puisse pas être fusionnée avec un chiffre invérifiable ou un fingerprint obsolète :

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

Aller plus loin

references/details.md couvre : le script de vérification de l'entrepôt, le regroupement de la vérification de dérive sur les pages, les modèles pour index.md et log.md, les fichiers surveillés renommés ou supprimés, les sources qui sont binaires ou vivantes à des URLs externes, et l'implémentation de référence.

grounded-vault