Grounded Vault

A provenance-complete knowledge base architecture for humans and AI agents. A Promptotyping profile for evidence-grounded knowledge work.

This repository is a template. Instantiate it for a project via SETUP.md; the full concept lives in docs/concept.md. What changed for existing instances is in CHANGELOG.md.

Why

Output generated by language models is unauditable in its raw form. A generated report may name its sources, yet its structure offers no way to check an individual statement against the passage that supposedly supports it. Grounded Vault is a repository architecture in which every substantive statement carries a machine-resolvable anchor to the source material that supports it, from the finished output down to the individual passage, dataset row or computation. AI agents produce this structure at scale; the architecture never asserts that its content is true. A finished vault is a fully prepared audit object in which human expert review can proceed passage by passage.

Quickstart

uv sync                        # or: pip install pyyaml pytest
python tools/validate.py .     # conformance check of the whole vault
python tools/validate.py . --chapter 40_output/01-findings   # one chapter and its chain
python -m pytest tests         # the validator's own test suite

Then follow SETUP.md, which lists the parameters an instance sets and carries a copy-paste prompt for the first agent session that fills them.

Layers

The numbered chain runs 00_sources → 10_markdown → 20_distillates → 30_assertions → 40_output, and the folders are described under Repository layout below. Each layer is checkable on its own. Anchors are minted only at the layer they belong to, and each layer references only the layer directly beneath it.

Which of the three source types a source belongs to follows from whether its content may be stored in the vault. A document may be stored in full and is converted into a Markdown representation with block anchors. A publication is only cited, so the vault holds its bibliographic record and the anchor is the verbatim quotation. A data source is anchored by a deterministic computation over the file. The publication status of a source decides nothing by itself, so a storable open-access article is treated as a document.

Repository layout

The five numbered folders form the production chain, each one holding the layer that the folder name announces.

• 00_sources/ holds the originals exactly as they arrived, kept untouched so that every later form of their content can be checked against them. By default the originals stay local and uncommitted, because third-party rights usually forbid redistribution, and an instance commits exactly those originals whose rights it holds.
• 10_markdown/ holds the uniform Markdown form of each source, produced once by converting the original and given block IDs so that later layers anchor into passages that never change afterwards, with the full texts in documents/ and the datasets plus their schema description in data/.
• 20_distillates/ holds one distillate per source, meaning the set of single statements extracted from that source, each anchored to the passage of the Markdown representation it was taken from and carrying its own statement ID.
• 30_assertions/ holds the atomic cross-source statements, each synthesized from the distillates of a topic and grounded in at least one distillate statement, together with one topic map (MOC-*.md) per topic of the controlled topic set.
• 40_output/ holds the final output of the vault, one or more documents such as a report, proposal, thesis or paper, kept as one file per chapter, in which every load-bearing sentence carries a footnote to an assertion and every own conclusion is marked as a posit.

The remaining folders lie across the chain rather than inside it.

• knowledge/ is the governance layer, six Promptotyping documents holding terminology, parameters, schema, procedures, volatile state and the decision history.
• references/ holds the bibliographic records of citable-only sources as CSL JSON, one array per file, and is needed only while the source type publication is active.
• glossary/ holds one file per central technical term of the content, serving as definition, wikilink hub and tag keyword, and is filled as the need arises.
• tools/ holds the validator validate.py, the source inventory generator inventory.py, the project page generator build_docs.py, and in tools/analysis/ the deterministic scripts that data anchors re-run, one script per task.
• tests/ holds the validator's own pytest suite, with the fixture vaults it runs against in tests/fixtures/, a minimal conformant vault and a deliberately broken one that carries one specimen per finding class. A coverage test holds every finding code the validator emits against those specimens, so a check added without one fails the suite.
• docs/ holds the concept paper and the generated project page index.html, both describing the architecture rather than any instance, so an instance may delete the folder.
• .github/ holds the CI workflow checks.yml, which runs the validator and the test suite on every push and pull request.
• .claude/ holds the harness-specific skills that the action layer CLAUDE.md routes into, exchangeable together with that file.

docs/index.html is generated from README.md, docs/concept.md and the knowledge documents by python tools/build_docs.py --date <date> and is never edited by hand.

Checking

Three instances check the vault, with strictly separated authority. Validation is deterministic conformance checking against the vault's own schema (tools/validate.py); every anchor resolves, every computation re-runs, every frontmatter conforms. Machine review is adversarial checking by a language model under anti-anchoring, judging with a fixed verdict vocabulary whether a source location actually supports the statement built on it. Verification is human expert review, alone authorized to establish evidence. The division of labour is that the validator judges resolvability and form, the machine review judges whether the location supports the statement, and human verification establishes evidence.

Chapters are written and accepted one at a time, so the validator also judges one at a time. --chapter 40_output/<slug> restricts the run to that chapter and the chain it hangs on, meaning the assertions it footnotes, the distillates grounding them and the Markdown representations beneath, and it reports in a closing line which vault-wide checks that scope leaves out.

Quotations from citable-only publications are checked character for character at intake time, while the full text is at hand, and the check is recorded with its date in checked.quote on the distillate. Later validation runs cannot repeat it, because the full text of such a source does not lie in the vault; they check that the record exists.

The architecture fixes a check contract per instance; the mechanism that fulfils it is a project choice. Statuses progress grounded → validated → verified (plus contested where sources conflict), and a status is only ever set by a check that actually ran, with outcome and date recorded on the document (audit trail). A document never stands higher than the anchors it rests on, so one unreviewed anchor holds the whole chain above it at grounded.

Dual readability

Humans read the vault in Obsidian, following wikilinks from an output footnote down to the supporting passage. Agents enter through CLAUDE.md, an imperative action layer that routes every task onto the declarative rule documents in knowledge/. The Markdown stays portable; beyond wikilinks and block references no plugin-specific syntax is used.

Getting started

1. Create a repository from this template.
2. Follow SETUP.md to set the project parameters (purpose, controlled topic set, active source types, output genre, language, verification role, check mechanisms, harness rules), or hand its first-session prompt to an agent.
3. Run python tools/validate.py . on every change, and python -m pytest tests when you touch the validator. A run without errors is not the whole criterion; every warning is a finding, whether it says that a check found no subject or names a defect the schema does not make an error. Over the whole vault warnings never fail the run, and in chapter mode a warning inside the scope does.

Licence

The whole repository is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0), see LICENSE. Third-party research data is excluded from these terms; rights remain with their respective holders.