A provenance-complete knowledge base architecture for humans and AI agents.
This page is generated from the documents of the grounded-vault repository and reflects their state of 2026-08-10.
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.
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.
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 suiteThen follow SETUP.md, which lists the parameters an instance sets and carries a copy-paste prompt for the first agent session that fills them.
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.
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.
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.
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.
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.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.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.
A provenance-complete knowledge base architecture for humans and AI agents. A Promptotyping profile for evidence-grounded knowledge work.
This document describes the concept. The repository around it is the reference implementation of that concept.
Output generated by large 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. The reader either trusts the whole text or re-does the work. For knowledge work under evidence obligations this is disqualifying, whether the output is an institutional strategy, a funding proposal, a scholarly synthesis or a policy report.
The problem is structural. Trust in a statement requires a checkable path from the statement to its source material, and plain generated prose has no such path. Adding citations after the fact does not create one, because a citation asserts a connection without exposing it to inspection.
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. The three checking instances divide the work along that anchor. Validation decides whether an anchor resolves and whether its form conforms, machine review judges whether the resolved location actually supports the statement, and human verification alone establishes evidence. The knowledge base is built in layers. Source material enters at the bottom, statements condense upward through defined transformations, and each transformation preserves the anchor chain.
AI agents produce most of this structure. The architecture therefore never asserts that its content is true. What a finished vault delivers is a fully prepared audit object. Every assertion is anchored to its source passages, every anchor has passed deterministic validation and an adversarial machine check, and human expert review can proceed passage by passage instead of starting from zero. The value of the architecture is that it makes agent output auditable at low cost and makes the state of auditing explicit at every point.
The vault is dual-readable by design. A human reads it as a linked Markdown collection in Obsidian, following wikilinks from the output down to the supporting passages. An AI agent operates on the same files through an agent harness, steered by an imperative action layer that routes into the declarative rule documents.
The vocabulary is chosen to keep an epistemological distinction visible that generated knowledge tends to blur, the distinction between material and evidence.
Source. Any carrier of information that enters the vault, whether a document, a publication, a dataset or an image. A source is where information comes from. Nothing about being a source implies being checked or being true.
Source type. A class of sources defined by its representation inside the repository, which for archivable material is the Markdown representation, by its distillation operation, and by its grounding anchor, meaning the mechanism by which a statement binds to a location in the source. Section 5 defines the initial typology. Source types are configuration; a project activates the types it needs.
Distillate. The condensation of exactly one source into its core statements, each statement carrying a grounding anchor into that source. The core statements reproduce their source without merging it with other sources. What the source is worth stays out of them and goes into a separate optional appraisal section, which is the vault's own judgment, mints no anchors and can therefore never be grounded in. Production runs as a three-stage chain, LLM extraction with a canonical prompt, deterministic formatting, and a fidelity check against the source; every content document type carries a fixed frontmatter and section skeleton defined in the schema. The skeleton follows the general shape of a knowledge document (title, lead summary, key statements, open questions, related links) with one deliberate omission: the distillate has no synthesis section, because synthesis is promoted to its own document type, the assertion, where it becomes subject to grounding.
Assertion. An atomic, source-independent statement relevant to the output, held in one file, synthesized from the distillates of one or more sources. The term comes from historical work practice, where an assertion is the researcher's own source-supported statement, and it connects to the nanopublication community, whose core building block is an assertion together with its provenance. The assertion layer is where sources of different types converge. Digital prosopography models something structurally similar under the name factoid, a statement a source makes, recorded without asserting its truth; the concept applies here, the term does not travel well outside that field.
Grounding. The anchor relation between an assertion and its source locations. An assertion is grounded when it references the passages, quotations or computations that support it. Grounding is a structural property that an agent can produce. It says nothing about whether the statement is true.
Evidence. A grounding relation that has passed human expert verification. Evidence is relational; no document is evidence in itself, a source location becomes evidence with respect to a specific assertion, and only through verification. The word is deliberately reserved for this final state, which keeps it rare and expensive inside the architecture. A freshly generated vault contains grounding; evidence arises only through subsequent human review.
Provenance chain. The unbroken anchor path from a sentence in the output through the supporting assertions and their distillates to the source locations. Breaking it anywhere, for instance through an anchor that no longer resolves or a quotation that deviates from its source, is a defect that validation detects.
Audit trail. The principle that status fields record the outcomes of checks that actually ran. A status is never set because it seems appropriate. Every check writes its outcome and date to the document it checked, so reading a document reveals which checking instances have passed and when.
Validation, machine review, verification. The three checking instances, defined in section 6. In this architecture, validation is deterministic checking against formal rules, and verification is human expert judgment. Readers from software engineering should note that this assignment inverts the IEEE convention; the definitions here follow the epistemology of the domain, where establishing truth is a human act and establishing formal conformance is a mechanical one.
The vault is organized in ascending layers. Each layer is checkable on its own, so the vault can be handed over even when upper layers are incomplete.
| Layer | Content | Anchor it carries |
|---|---|---|
| Sources | Original material per source type | none; this is the ground |
| Markdown representation | Archived full texts, bibliographic records, datasets | stable anchors (block IDs, identifiers, file plus schema) |
| Distillates | One distillate per source | grounding anchors into that source |
| Assertions | Atomic statements plus topic maps (MOCs) and glossary | grounding anchors into distillates |
| Output | The final output of the vault, one or more documents such as a report, proposal, thesis or paper | footnote anchors into assertions, own conclusions marked as posits |
Two rules constrain the chain. Anchors are created only at the layer they belong to, so a distillate references existing block IDs and has no authority to mint new ones. And each layer references only the layer directly beneath it; the output binds to assertions, and every statement therefore passes through the synthesis and checking machinery before it can reach a source.
A conclusion that emerges during synthesis without source support does not enter an assertion. It enters the output as an explicitly marked posit, with its rationale and its open evidence question. The vault thereby shows exactly where it leaves its sources.
Contradictions between sources are preserved. Assertions that cannot be reconciled are marked as contested and linked to each other in both directions. A contradictory source situation is itself information for the output.
The initial typology covers three source types, with a fourth sketched. Each is defined by its representation in the repository, its distillation operation and its grounding anchor. The criterion that assigns a source to a type is whether its content may be stored in the vault, and the publication status of a source decides nothing by itself, so an open-access article that may be stored is treated as a document.
Every Markdown representation carries a compact metadata block in its frontmatter, with Dublin-Core-compatible field names (title, creator, date, type, identifier, license) plus the acquisition channel as a provenance note. Licensing and confidentiality are thereby metadata of the individual source; whether a full text may be archived, versioned or published is read off the license field instead of being wired into the architecture. For publications the bibliographic substance lives in the CSL JSON record, which the metadata block references instead of duplicating.
Documents. Sources whose full text may be stored in the vault and is therefore converted into a Markdown representation, typically material produced by or for the project owner, but equally any externally published text whose license permits storage.
Whether the originals and full texts may be versioned or published is read off the source's license and confidentiality metadata, independent of the mechanics.
Publications. Sources that are only cited, because their full text may not or cannot be stored, whether for licensing or practical reasons. What lies in the vault is the bibliographic record, and the anchor is the verbatim quotation. This is the fallback case; where a full text may be stored, the document type is preferred, because its anchors resolve inside the vault.
Data. Datasets such as CSV, spreadsheets or XML, whose anchor is a deterministic computation over the file.
This type strengthens checking, because validation can re-run the computation and compare exactly.
Images and other carriers (sketched). An anchor would be the image file plus a region or a documented description. The type is named as an extension point and left unelaborated.
The historical two-stream design this architecture generalizes from distinguished internal and external documents for reasons of confidentiality and copyright. Those reasons were project-specific. What generalizes is the anchor mechanics per type; confidentiality and licensing live in the per-source metadata block, and a project may run a single type or several.
Sources are versioned by replacement. A Markdown representation is converted once and never edited, so its anchors stay stable; a revised source enters as a new representation file with a date-suffixed slug, existing anchors keep resolving against the old file, and the old distillate is marked as superseded by the new one.
How a source enters the vault is a dimension orthogonal to its type. The type fixes the anchor mechanics; the channel describes the intake. The same publication type can be filled by handover from a project partner, by manual collection, by import from an existing reference library, or by agent-driven deep research. Channels are recorded as a provenance note on the source and change nothing else.
The elaborated reference channel is deep research for citable-only publications. A reusable prompt, parameterized with a topic from the project's controlled topic set, searches and prioritizes candidate publications, evaluates them at full text, counter-checks adversarially and synthesizes. Priority rules favor peer-reviewed and official sources; an explicit exclusion list names unreliable ones. Every located source is captured in a reference manager, Zotero in the reference implementation, and exported as a CSL JSON record into the vault; credentials and library identifiers stay outside the repository. Each source then receives an ordinary distillate with verbatim quotations as anchors.
Two rules keep the channel compatible with the architecture. First, the research report itself never becomes a source. A deep research run produces synthesized, agent-generated text; the sources are the located publications, and all anchors bind to those. If the report were treated as a source, generated text would enter the source layer and from then on count as source material. Second, the channel does not change the checking. The character-for-character quotation check runs regardless of how a source arrived, which is precisely what catches the typical weakness of automated research, fabricated or inexact citations. For a publication the check happens at intake, while the full text is at hand, and its date is recorded on the distillate, because the full text is not available to later validation runs.
Three instances check the vault, distinguished by who or what judges and with what reliability.
Validation is deterministic conformance checking of the vault against its own schema. A rule set defines what a well-formed artifact is, in machine-decidable terms, and a checker reports every violation with its location. The same input always yields the same verdict. Concretely it checks, per source type, that every core statement carries an anchor, that every block reference resolves to an existing passage, that every quotation whose source text lies in the vault matches it character for character and that every quotation to an external publication carries a recorded intake-time check, that every computation re-runs to the stated result, that every assertion is reachable from a topic map, and that frontmatter conforms to the document type schema. The mechanism is an ordinary one, the same principle as schema validation in XML workflows, constraint languages, automated tests or referential integrity in databases. Validation runs on every change and gates everything above it.
Machine review is adversarial checking by a language model. A reviewer model judges whether a source location actually supports the statement built on it, using a fixed verdict vocabulary (fully supports, partially supports, overreaches, contradicts, not in the text). Anti-anchoring is mandatory, meaning the reviewer sees only the source location and the statement, while the producing agent's reasoning stays hidden from it, so that it cannot be led. Machine review is probabilistic and is therefore its own instance. Classifying it as validation would blur the line between deterministic and judged, and classifying it as verification would claim human authority it does not have. Its role is to pre-filter for verification, so that human attention lands on the cases that survive an adversarial pass.
Verification is expert-in-the-loop review by humans. It alone establishes evidence in the sense of section 3. The final authority is the project's designated critical expert.
The architecture fixes a check contract per instance; the mechanism that fulfils it is a project choice. The contract names what the instance judges, the ceiling of its authority (the highest status it may set), the conditions it must observe (for machine review, anti-anchoring and the fixed verdict vocabulary, with only fully supports passing), and the obligation to record outcome and date on the checked document. Which validator implementation runs, which reviewer model judges and how pairs are extracted for it are instantiation decisions. The template ships a generic validator for the schema-level checks, pluggable checks per source type, and for machine review the contract with a reference prompt skeleton.
The audit trail records the progression. A grounding relation moves through the statuses grounded (structurally anchored, produced by the agent), validated (deterministic checks passed, machine review not refuted) and verified (expert review passed), with contested available where sources conflict. The overall state of a vault is readable as the distribution of its statements across these statuses. A freshly generated vault sits almost entirely at grounded and validated; the human work consists of lifting statements to verified. No instance ever sets a status above its own authority.
The vault separates meta-knowledge from content. A knowledge/ folder carries the documents that govern production. The template starts with a compact core of six, separated by what an agent loads together and by how fast content ages. index.md holds navigation, reading paths and the project's terminology. specification.md holds purpose, requirements and settled decisions. schema.md defines the rules of the vault, covering layers, folders, document types with their frontmatter, anchor mechanics per source type, the controlled topic set and the output's style sheet. operations.md defines the procedures, one section per chain, covering acquisition (including the deep research channel), intake, distillation, assertion building, chapter writing, query answering and checking. state.md gathers everything volatile in one place, the source inventory with processing status and the chapter register with writing status, so that the rule documents stay stable. journal.md holds the chronological decision history, append-only.
A split rule accompanies the core: a document is divided only when its sections develop divergent update rhythms or divergent readers. Grown instances may therefore carry more documents than the template ships.
The content folders carry what is produced. Governance and content never mix; decision provenance lives in the journal, content documents carry only current state.
This governance layer is Promptotyping. Promptotyping organizes the knowledge about a project so that an agent need not re-derive it each session; requirements, data, decisions and domain knowledge are written down and cross-referenced in a fixed document set. Grounded Vault inherits that layer unchanged and adds the answer to the follow-up question: how to organize the knowledge a project produces when every statement is under evidence obligation. Grounded Vault is therefore a Promptotyping profile, the profile for evidence-grounded knowledge work.
The same files serve two readers.
For humans, the vault is an Obsidian collection. A home page is the entry point, topic maps (MOCs) bundle the assertions per topic, wikilinks connect related knowledge instead of repeating it, and the provenance chain can be followed by clicking from an output footnote down to the supporting passage. The Markdown stays portable; beyond wikilinks and block references no plugin-specific syntax is used, so the vault remains readable outside Obsidian.
For agents, the entry point is an action layer (CLAUDE.md in the Claude Code harness, replaceable for other harnesses). It is imperative, kept short, and routes every task onto the declarative rule documents in knowledge/ instead of duplicating them. A session-start reading order and a task routing table stand at its top. The harness-specific part is an explicitly exchangeable block, so the architecture does not depend on one vendor's tooling.
Dual readability is also why schema discipline pays beyond checking. Consistent frontmatter per document type is exactly the data contract a presentation frontend would need. Frontends are out of scope for this architecture, and the option costs nothing to keep open.
The upper layer is the point of variation between projects. The reference case is a prose output, written as continuous text in one file per chapter, with every load-bearing sentence footnoted to its supporting assertions and every unsupported conclusion marked as a posit.
The footnote is a rendering, and the binding part is an anchor contract. Every load-bearing statement carries a machine-extractable inline marker that resolves to at least one assertion and distinguishes supported statements from posits; the document's frontmatter mirrors the set of referenced assertions as structured data; validation cross-checks text and frontmatter against each other. Footnotes are the reference notation for prose because they live in portable Markdown and stay readable for both humans and machines. An instantiation may substitute another notation as long as the contract holds; a pure structured-data sidecar would satisfy the machine and break human readability, which is why the default combines an inline marker with a structured mirror. Instantiations differ in the chapter register, the style sheet and the genre, whether the output is a strategy, a proposal, a report or a scholarly elaboration; the grounding and checking mechanics stay identical.
A code or data-analysis output is a named extension, deliberately not elaborated in the first version. Code carries no footnotes, so the anchoring would shift: specification and decision documents bind to assertions, and the code binds to the specification. Working that out is future work; forcing it into the prose model would dilute the provenance mechanics that are the architecture's value.
Proposed folder layout of the template, layer numbering kept because it makes the stratification visible in any file listing:
The numbered chain runs 00_sources → 10_markdown → 20_distillates → 30_assertions → 40_output. The unnumbered folders lie across the chain rather than inside it.
00_sources/ originals per source type, local only where confidentiality
requires; unchecked, because this layer holds the original
everything above it is checked against
10_markdown/ Markdown representations of full texts and datasets;
stable anchors live here
20_distillates/ one distillate per source, one subfolder per source type
30_assertions/ assertion atoms and topic maps (MOC-*)
40_output/ the final output, one file per chapter
glossary/ one term per file: definition, wikilink hub, tag keyword
references/ bibliographic records (CSL JSON)
knowledge/ governance layer (Promptotyping documents)
tools/ validation scripts, one script per task
HOME.md human entry point
CLAUDE.md agent action layer (exchangeable block)Folder names, the exact split of 10_markdown/, and the handling of the register of source identifiers are open design decisions of the template build.
A project instantiates the template by setting a small number of parameters. These are the purpose, which names the overall topic in its first sentence, the controlled topic set (which becomes the MOC set), the active source types, the output genre with its chapter register and style sheet, the working language of the content, the role that holds verification authority, and the mechanisms that fulfil the check contracts. Everything else, the layer model, the anchor mechanics per source type, the check contracts of the three instances, the status progression and the governance document set, is invariant. The instantiation mechanism is a template repository with placeholders plus the setup guide SETUP.md, which carries a prompt for the first agent session that fills them.
The architecture stands in recognizable traditions and gains its terminology from them. From historical source criticism it takes the relational concept of evidence and the primacy of the source location. From digital prosopography it takes the factoid insight that recorded statements and asserted facts must be kept apart. From historical work practice it takes the source-supported assertion, and from the nanopublications of the research data world the pairing of an assertion with its provenance. From scholarly digital editing it takes the practice of validating a document corpus against its own schema, the vault treats itself the way an edition treats its TEI files. From data management it takes provenance as a first-class, machine-traversable relation, as standardized in W3C PROV. The contribution of Grounded Vault is the combination: these instruments, arranged so that AI agents can produce the structure at scale while humans retain sole authority over what counts as evidence.
Navigation and terminology of the vault. Human readers start at HOME; agents start at CLAUDE.md, which routes onto these documents.
knowledge/specification for purpose and parameters, then knowledge/state for where work stands.knowledge/schema for what a well-formed artifact is, knowledge/operations for the chain that produces it.knowledge/journal, append-only, newest last.| Document | Holds | Changes |
|---|---|---|
knowledge/index | navigation, terminology | rarely |
knowledge/specification | purpose, parameters, settled decisions | on decisions |
knowledge/schema | layer model, document types, anchor mechanics, audit trail | rarely, by decision |
knowledge/operations | the chains: acquire, ingest, distill, assertions, chapters, query, check | rarely, by decision |
knowledge/state | source inventory, chapter register, everything volatile | constantly |
knowledge/journal | decision history | append-only |
A document is split only when its sections develop divergent update rhythms or divergent readers.
This document defines the rules of the vault. It sets out the layer model, the controlled vocabularies, the anchor mechanics per source type, the audit trail, and for every content document type the exact frontmatter and section skeleton. Every content file, whether produced by agent or human, derives from the rules set here. The procedures that produce and check these documents live in knowledge/operations; this document defines only what a well-formed artifact is.
| Layer | Folder | Content | Anchor it carries |
|---|---|---|---|
| Sources | 00_sources/ | originals, local only | none; this is the ground |
| Markdown representation | 10_markdown/ | archived full texts, datasets with schema | block IDs, file plus schema |
| Distillates | 20_distillates/ | one distillate per source | grounding anchors into its source, statement IDs |
| Assertions | 30_assertions/ | atomic cross-source statements, topic maps | grounding anchors into distillate statements |
| Output | 40_output/ | one file per chapter | footnote anchors into assertions, posits marked |
The source inventory in knowledge/state.md lists every Markdown representation and every distillate, and it is generated from the file state by python tools/inventory.py . --write rather than maintained by hand. The files are the one record of what the vault holds, so there is no second bookkeeping that could drift away from them.
The layers carry these definitions. A source is the original file exactly as it arrived, kept untouched so that every later form of its content can be checked against it. A Markdown representation is the uniform Markdown form of a source, produced once by converting the original and given block IDs so that later layers anchor into passages that never change afterwards. A distillate is the set of single statements extracted from one source, each anchored to the passage of the representation it was taken from. An assertion is a single source-supported statement synthesized from the distillates of a topic and grounded in at least one distillate statement. The output is the final output of the vault, one or more documents such as a report, proposal, thesis or paper; its document type is the chapter, and a chapter is an output text in which every load-bearing sentence carries a footnote to an assertion and every own conclusion is marked as a posit.
Two rules constrain the chain. Anchors are minted only at the layer they belong to; a Markdown representation mints block IDs, a distillate mints statement IDs, and no higher layer creates anchors into material below its direct predecessor. And each layer references only the layer directly beneath it; the output binds to assertions, assertions bind to distillate statements, distillates bind to the blocks of the Markdown representation.
The chain fastens onto one property of its subject matter. Whether a passage covers a statement is settled by a fast oracle, a resolver that answers in milliseconds whether the anchor exists and what stands at it. Qualities without such an oracle stay unrewarded wherever checking has to scale, which is why the maintainability of code goes unscored in machine learning and shows its cost only in weeks and months. Verification here is therefore fastened to the one relation that is cheap to test, and everything the relation cannot settle is handed to the instances defined in knowledge/operations.
type: representation | distillate | assertion | moc | glossary | chapter. The value representation is the machine-side short form for Markdown representation; the prose of this vault uses the full term.source-type: document | publication | datachannel: handover | collection | import | deep-researchstatus: grounded | validated | verified, plus contested (assertions only) and superseded (distillates only)topics: values must each name an existing topic map; the set of MOC-*.md files in 30_assertions/ is the controlled topic setA status records the outcome of checks that actually ran. Every check writes its date into the checked map of the document it checked:
status: validated
checked:
validation: 2026-07-11
machine-review: 2026-07-11The discipline is machine-enforced: validated requires checked.validation and checked.machine-review; verified additionally requires checked.verification. Every entry of the map carries an ISO date, because a record without one cannot be held against the content it judges. grounded is the entry status of every freshly produced document and requires no entry. A document's status is the minimum of the states of its anchors, judged against the anchors an assertion names in grounding and a chapter in its assertions mirror, so one unreviewed anchor keeps the whole document at grounded. contested and superseded lie beside the ladder and earn no rank, so a document resting on one of them stays at grounded as well. For publication distillates the intake-time quotation check is recorded as checked.quote, because the source text may be unavailable to later validation runs. No instance ever sets a status above its own authority; the contracts are defined in knowledge/operations.
Every Markdown representation carries a compact, Dublin-Core-compatible metadata block. Licensing and confidentiality are metadata of the individual source; nothing else in the architecture depends on them.
metadata:
title: "" # dc:title
creator: "" # dc:creator; role and institution, no third-party personal names
date: "" # dc:date of the source, ISO 8601
format: "" # dc:format of the original (pdf, pptx, csv, …)
identifier: "" # dc:identifier (DOI, URL, archival signature) where one exists
license: "" # dc:rights; SPDX identifier or short clause
confidential: false # true keeps original and full text localThe source type of a source follows from whether its content may be stored in the vault and from the anchor that storage decision permits.
A document is a source whose full text may be stored in the vault. It is converted into a Markdown representation and anchored by block reference into that representation. A publication is a source that is only cited. What lies in the vault is the bibliographic record, and the anchor is the verbatim quotation together with the identifier. A data source is a file whose anchor is a deterministic computation over that file. An aggregate or a statistical finding exists at no single passage, so the computation takes the place of one.
The criterion is storability, and the publication status of a source decides nothing by itself, so an open-access article that may be stored is treated as a document. Where a full text may be stored, document is preferred over publication, because its anchors resolve inside the vault.
references/ holds the bibliographic records of the citable-only sources as CSL JSON, exported from the reference manager. Each file is a JSON array of records, and each record carries an id alongside its bibliographic fields.
[
{
"id": "author2024keyword",
"type": "article-journal",
"title": "",
"author": [{ "family": "", "given": "" }],
"issued": { "date-parts": [[2024]] },
"container-title": "",
"URL": ""
}
]The reference field of a publication distillate names one such id, and validation raises E-ANCHOR when no record in references/ carries it. The folder is needed only while the source type publication is active.
Each type carries its frontmatter as a code block, followed by the section skeleton where one is fixed. Fields not marked optional are required. Wikilink values are quoted, block IDs unquoted, as Obsidian requires for YAML.
The uniform Markdown form of a source, produced once by converting the original and given block IDs so that later layers anchor into passages that never change afterwards. Exactly one per source, stored in 10_markdown/documents/. A revised source enters as a new file with a date-suffixed slug; existing anchors keep resolving against the old file.
---
type: representation
source-type: document
source: "[[00_sources/<filename>]]"
converter: "" # e.g. Docling, MarkItDown
channel: handover # handover | collection | import | deep-research
metadata: { … } # see Source metadata
created: 2026-01-01
updated: 2026-01-01
---The body is the converted full text under an H1 taken from the original. Every anchor-relevant paragraph ends with a block ID:
The board approves centrally operated services. ^a1b2Block IDs are short, stable, unique per file, and minted only here.
A dataset plus its schema description. The data file (CSV, XML, …) lives in 10_markdown/data/ next to a Markdown file of the same slug that carries the frontmatter and describes the schema.
---
type: representation
source-type: data
source: "[[00_sources/<filename>]]" # omit when the data file is the original
data: "[[10_markdown/data/<file.csv>]]"
channel: handover
metadata: { … }
created: 2026-01-01
updated: 2026-01-01
---The body describes columns, units, encodings and known limitations. The anchor of this type is a computation, defined in the distillate.
The set of single statements extracted from one source, each anchored to the passage of the representation it was taken from. One file per source in 20_distillates/<source-type>s/, same slug as its Markdown representation. The core statements reproduce their source without merging it with other sources; synthesis belongs to assertions, and judging the source belongs to the Appraisal section defined below.
---
type: distillate
source-type: document # document | publication | data
representation: "[[10_markdown/documents/<slug>]]" # document and data types
reference: "" # publication type: CSL JSON id from references/
topics: ["[[<Topic>]]"]
status: grounded # grounded | validated | verified | superseded
checked: {}
superseded-by: "" # optional, wikilink to the successor distillate
created: 2026-01-01
updated: 2026-01-01
---## Distillate: <source short title>
<Lead: one sentence naming the source and its contribution to the vault.>
### Core statements
- <statement> [[10_markdown/documents/<slug>#^a1b2]] ^s1
- <statement> [[10_markdown/documents/<slug>#^c3d4]] ^s2
### Terms
- **<term>**: <meaning as set by the source> [[10_markdown/documents/<slug>#^e5f6]]
### Open questions
- <unclarity of the source>
### Appraisal
<optional; what this source is worth, in prose>
### Related
- [[20_distillates/…]] / [[30_assertions/…]]Every core statement carries exactly one grounding anchor into its source and ends with a statement ID (^s1, ^s2, …), the anchor assertions bind to. The anchor form varies by source type:
checked.quote.- <statement in own words> ^s1
> "<verbatim quotation>" (<identifier>, p. <n>)tools/analysis/ and is deterministic.- <statement, e.g. an aggregate or finding> ^s1
- computation: `python tools/analysis/<script>.py` → `<stated result>`The script reads the data file of the Markdown representation, takes no arguments, and prints the stated result and nothing else to standard output. Validation re-runs it from the vault root and compares that output character for character with the stated result, so a formatting difference is a defect.
The Appraisal section is optional and holds the judgment of the source, covering the standing of its venue and its review, the strengths and limits of its method, its relevance to the output of this vault, and the position the vault takes towards it, as far as each applies to the source at hand. Saying what a source is worth is a different speech act from saying what it says, and the section separates the two so that a reader can tell evidence from opinion at a glance. The appraisal is the vault's own judgment and therefore a posit, so it carries no grounding obligation and no anchor of its own. It also mints no IDs, because every ID in a distillate is citable from the assertion layer; validation raises E-STATEMENT on an ID minted anywhere but in the core statements, which is what keeps an appraisal from ever becoming grounding. Where an appraisal shapes the output, it enters as a posit footnote there.
The Open questions section holds questions and no findings. A finding that could carry an assertion belongs in the core statements with an anchor and an ID of its own, and it is lifted there rather than cited from where it sits. The section mints no IDs for the same reason the appraisal mints none, and that is what makes it the one place in the chain where unanchored material may rest, including whatever a perspective pass produced before the sources were chosen.
A single source-supported statement synthesized from the distillates of a topic and grounded in at least one distillate statement. One file per assertion in 30_assertions/. This is the layer where source types converge.
---
type: assertion
topics: ["[[<Topic>]]"]
status: grounded # grounded | validated | verified | contested
checked: {}
grounding:
- "[[20_distillates/documents/<slug>#^s1]]"
- "[[20_distillates/publications/<slug>#^s2]]"
contested-with: [] # wikilinks; required on both sides when status is contested
created: 2026-01-01
updated: 2026-01-01
---## <The assertion as one sentence>
### Statement
<The assertion spelled out, one short paragraph.>
### Support
- [[20_distillates/documents/<slug>#^s1]] — <what this anchor contributes>
- [[20_distillates/publications/<slug>#^s2]] — <what this anchor contributes>
### Related
- [[30_assertions/…]]A conclusion without source support never becomes an assertion; it enters the output as a posit. Assertions that cannot be reconciled are both set to contested and linked to each other in contested-with.
Posit and assertion differ in kind and not in ripeness, and reading the posit as an unripe assertion is the common mistake. An assertion rests on sources and carries a status on the ladder, which records how far it has been checked. A posit rests on the author, and it carries no status because it makes no claim about a source that a check could test. A posit therefore never matures into an assertion. Where a source turns up later, a new assertion is written and the posit falls away. What it leaves behind is its open evidence question, which is a research task rather than a defect, and the posits count of a chapter measures how much of that text stands on the author alone.
A passage can support a statement whose subject is not the subject the assertion is about, and the coverage relation still holds. No check catches this on its own, because validation and machine review test exactly that relation. Two cases of such a displaced subject occur often enough to be named.
Self-report. Where a source speaks about itself, about its own priority, reach or achievement, its passage covers the claim and never the matter the claim is about. The distillate holds such a statement as what the source asserts. An assertion built from it either carries the speaker along, in the form that the source claims something, or it rests on a second and independent source.
State report. Where a source shows the matter in one state at one time, its passage covers that state and never the matter across time. A restored object witnesses the restoration, a dated inventory witnesses the day it was taken, a plan witnesses what was intended when it was written. The distillate holds such a statement together with the state and its date. An assertion built from it either names the state and its date, or it rests on a source that establishes the property for the span the assertion claims.
One file per topic of the controlled topic set, named MOC-<Topic>.md in 30_assertions/. The set of these files is the topic vocabulary.
---
type: moc
topic: "<Topic>"
created: 2026-01-01
updated: 2026-01-01
---## MOC: <Topic>
<Lead: one sentence on what this topic covers.>
- [[30_assertions/<slug>]] — <half-sentence of orientation>
### Open questions
- <question the vault cannot currently answer from its sources>The body lists every assertion of the topic as a wikilink with a half-sentence of orientation. Every assertion must be reachable from at least one topic map, and the validator raises E-ORPHAN on one that is not.
One term per file in glossary/, serving as definition, wikilink hub and tag keyword.
---
type: glossary
term: "<term>"
created: 2026-01-01
updated: 2026-01-01
---## <Term>
<Definition in one or two sentences.> [[10_markdown/documents/<slug>#^a1b2]]The body gives the definition in one or two sentences with a grounding anchor where the definition comes from a source. The glossary holds one document per central technical term of the content and is used as the need arises.
An output text in which every load-bearing sentence carries a footnote to an assertion and every own conclusion is marked as a posit. One file per chapter in 40_output/, continuous prose in the project's working language and style sheet. The type name chapter denotes the acceptance-capable unit of the output, one file that is checked and accepted on its own; in an article genre it corresponds to a section.
---
type: chapter
status: grounded # grounded | validated | verified
checked: {}
assertions: ["[[30_assertions/<slug>]]"] # structured mirror of exactly the Grounded-in assertions; posit-linked ones stay out
posits: 0 # count of posit footnotes
created: 2026-01-01
updated: 2026-01-01
---The anchor contract of the output: every load-bearing sentence carries a footnote marker; every footnote begins with one of two keywords and nothing else counts.
Water use fell by a third after metering was introduced.[^1] The board should
therefore extend metering to all sites.[^2]
[^1]: Grounded in [[30_assertions/metering-reduces-use]].
[^2]: Posit: follows from [^1] only if consumption patterns are comparable
across sites. Open evidence question: site-level baseline data.Validation cross-checks the footnotes against the assertions mirror and the posits count. Footnotes are the reference notation; an instantiation may substitute another notation as long as marker, keyword and mirror survive.
Where a chapter reports a matter the sources disagree on, it grounds in both sides of the contested pair. A chapter that names one assertion of such a pair and none of its counterparts presents the dispute as settled, and validation raises W-CONTESTED.
The six documents in knowledge/ carry the Promptotyping header (as at the top of this file) instead of a content type. They are meta-knowledge about the vault and are exempt from the content schema. A knowledge document is split only when its sections develop divergent update rhythms or divergent readers.
File names are speaking slugs, ASCII-lowercase with hyphens, derived from genre and subject (report-water-metering-2026-03). Markdown representation and distillate of the same source share the same slug. Date suffixes distinguish version rows.
This document defines the procedures of the vault, one section per chain. Every chain produces or checks artifacts defined in knowledge/schema and updates the registers in knowledge/state. Decisions made along the way go to knowledge/journal.
How a source enters the vault is orthogonal to its type; the channel is recorded in the channel field of the Markdown representation and changes nothing about checking.
00_sources/.references/, one file per batch of records.references/. The research report itself never becomes a source; all anchors bind to the located publications.Research the topic {topic from the controlled topic set} for the project {project}. Search broadly, then prioritize: peer-reviewed and official sources first; exclude: {project exclusion list}. Evaluate candidates at full text. Counter-check adversarially: for each candidate finding, search for sources that contradict it. Deliver a list of publications with full bibliographic data and, per publication, the two or three passages that matter for the topic, quoted verbatim. Do not deliver synthesis; the vault synthesizes.
Per source, produce the Markdown representation. The operation is the Markdown conversion, and it runs in two steps. The first step converts the original into structure-preserving Markdown, so that headings, lists, tables and paragraph boundaries survive as the original had them. The second step stamps a block ID onto every anchor-relevant paragraph. After the second step the file is never edited again, because every later layer anchors into these blocks and an edit would move them.
Which converter performs the first step is decided per source, along this list. The chosen converter is recorded in the converter field of the Markdown representation as before, so that a later run can be reproduced or repeated with a different tool.
10_markdown/documents/, note the converter in the frontmatter, set the H1 from the original, fill the metadata block.10_markdown/data/, write the schema description of the same slug, fill the metadata block.references/ is the root of this source type.Then run python tools/inventory.py . --write, which rewrites the source inventory in knowledge/state from the real file state.
One distillate per source, produced as a three-stage chain:
knowledge/schema.checked.quote.Extract the core statements of the source {source short title}, and of this source alone. Work only from the text given below. One statement per anchor. Each statement stands on its own, is understandable without its neighbours, and stays within the literal sense of the source. Do not evaluate, do not interpret, do not infer, and do not merge this source with any other; the vault synthesizes at a later layer. No statement without a nameable source location. Where you cannot name one, drop the statement. Deliver per statement the statement itself and its source location, in the form the source type requires: for a document the block it was taken from, for a publication the verbatim quotation with page, for data the computation that yields the stated result.
SOURCE: {Markdown representation, quotation set, or data schema description}
The chain iterates. A statement that fails the fidelity check is reformulated or discarded, and the check runs again, until every remaining statement passes.
Where the source is to be judged as well as reproduced, the appraisal is written after the chain has run, so that no evaluation can leak into the extraction the chain checks. It goes into the optional Appraisal section defined in knowledge/schema and stays outside the fidelity check, which has nothing to compare it against.
The distillate enters at status: grounded. Run python tools/inventory.py . --write again, so that the source inventory in knowledge/state carries the new file state.
Assertions are where the vault synthesizes, one file per assertion, and the work proceeds by topic in these steps.
grounding every statement ID that supports the assertion, one per supporting source, and say in the Support section what each anchor contributes.contested, and link them to each other in contested-with on both sides.Machine review then runs over every pair of assertion and supporting statement, under the contract below. A verdict below fully supports means the assertion is reformulated to the width its sources actually carry, or the grounding is corrected by dropping the anchor that does not carry it and naming one that does. Review repeats on the changed pair.
You are an adversarial reviewer. Below are a distillate statement and an assertion that claims to be supported by it. Your task is to refute the assertion. Judge only whether this statement supports this assertion; whether the assertion is true is out of scope. Answer with exactly one verdict: fully supports
| partially supports | overreaches | contradicts | not in the text. Then give one sentence of justification, and where the verdict is not fully supports, name the part of the assertion that the statement does not carry.
STATEMENT: {distillate statement, without its own grounding anchor} ASSERTION: {assertion as one sentence}
Write per chapter, in the working language and style sheet set in knowledge/specification. Every load-bearing sentence gets a footnote Grounded in [[assertion]]; every own conclusion gets a footnote Posit: <rationale>. Open evidence question: <question>. Mirror the referenced assertions and the posit count in the frontmatter. Update the chapter register in knowledge/state.
A chapter that reports the state of research across the sources of a topic is written with the same means and needs no type of its own. Enter through the topic map, and let the three parts fall on the mechanics that already carry them. What the sources agree on becomes sentences grounded in the assertions of the topic. What they disagree on becomes sentences grounded in both sides of a contested pair, which is why taking one side alone raises W-CONTESTED. The gap that the vault's own work closes carries no source and becomes a posit footnote with its open evidence question; the topic map's open questions are the register such a gap is read off. A synthesis chapter that later feeds another chapter stays an ordinary row in the chapter register.
To answer a question from the vault, enter through the topic maps, follow assertions to their distillate statements and, where exactness matters, down to the source passage. Quote assertions by wikilink so the answer stays anchored. Questions the vault cannot answer are recorded as open questions in the topic's map.
Three instances check the vault. The architecture fixes their contracts; the mechanism fulfilling each contract is an instantiation decision recorded in knowledge/specification.
knowledge/schema.checked.validation: <date> on every file that passes.python tools/validate.py . (checks frontmatter per type, anchor resolution, statement IDs, quotation identity where a source text is available, computation declarations, MOC reachability, bidirectional contested links, chapter mirror and footnote keywords, status discipline). Data anchors are re-run and compared by default; --no-computations switches that off for a fast run.python tools/validate.py . --chapter 40_output/<slug> judges one chapter and, transitively, the assertions, distillates and Markdown representations it grounds in, so that a chapter can be reported ready while other parts of the vault are still in progress. The scope walk follows only anchors pointing one layer down, so a neighbouring branch of the vault stays out of the verdict. The vault-level warnings stay out too, because they are decidable only over the whole vault, and the run names them in its closing lines. In this mode any warning inside the scope fails the run alongside an error, because the question the run answers is whether this chapter is ready for acceptance.E-ANCHOR fires when an anchor does not resolve, and it resolves the frontmatter targets representation, superseded-by and contested-with as well as the anchors in the body. E-LAYER fires when an anchor skips a layer instead of binding to the layer directly beneath its own. E-GROUNDING fires when a document that owes grounding carries an empty grounding. E-DUPLICATE fires when a block ID or a statement ID occurs more than once in one file. E-STATUS fires when a status lacks a check its rung requires or when an entry of checked records no date. E-LADDER fires when a document stands higher on the status ladder than an anchor it rests on, the rule that a status is the minimum of the states of its anchors. W-PLACEHOLDER fires while an unreplaced template placeholder in double braces remains anywhere in the vault. W-EMPTY fires while the production chain from 10_markdown to 40_output holds no document, so that no content check had a subject. W-STALE fires when a document's updated date is younger than the youngest of its checked dates, because then its checks are older than the content they judge; a document without any check date does not fire, since that is the state the status ladder starts from. W-DUPLICATE-GROUNDING fires when two assertions carry the same grounding set or one grounding set contains the other, the shape an accidentally duplicated assertion has. W-ALIAS fires when the alias of a chapter footnote wikilink differs from the H1 title of the assertion it points to, because a shortened alias can silently drop the clause that restricts the assertion.validated, never higher.checked.machine-review: <date>; verdicts below fully supports trigger rework and are noted in the journal when they reveal a systematic pattern.You are an adversarial reviewer. Below are a source passage and a statement that claims to be supported by it. Your task is to refute the statement. Judge only whether this passage supports this statement. Answer with exactly one verdict: fully supports | partially supports | overreaches | contradicts
| not in the text. Then give one sentence of justification.
PASSAGE: {source location, with its heading path} STATEMENT: {statement}
knowledge/specification.verified. Machine checks prepare, never replace it.checked.verification: <date> set by or on behalf of the verifying role.grounded → (validation and machine review passed) → validated → (expert passed) → verified. contested is set by assertion building or review when sources conflict, and resolved only by verification. A document's status is the minimum of its anchors' states.