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.

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-checkable anchor to the source material that supports it, from the finished deliverable 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.

Layers

30_deliverable/      synthesized output; every load-bearing sentence anchored to
                     claims, unsupported conclusions marked as posits
20_claims/           atomic cross-source statements; topic maps (MOCs) per topic
10_distillates/      one distillate per source, core statements anchored into it
00_representation/   stable source representations: full texts with block anchors,
                     data files with schema
_sources/ +          originals (local where confidentiality requires) and
references/          bibliographic records (CSL JSON)
knowledge/           governance layer (Promptotyping documents)

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.

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 quotation matches character for character, 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 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).

Dual readability

Humans read the vault in Obsidian, following wikilinks from a deliverable 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 (topic backbone, active source types, deliverable genre, language, verification role, check mechanisms).
3. Read examples/minimal/ for a complete worked instance; examples/broken/ shows the defect classes the validator catches.
4. 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; warnings say that a check found no subject, and the instance declares the ones it expects under expected-warnings in knowledge/specification.md.

Licence

Code is licensed under the MIT License (see LICENSE). Documentation and knowledge documents are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). Third-party research data is excluded from these terms; rights remain with their respective holders.