Grounded Vault

Start

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, and what changed for existing instances is in CHANGELOG.md.

The instance under paper/ applies the architecture to its own internal method manuscript.

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, and 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 --locked
uv run ruff check . && uv run ruff format --check .
uv run python tools/validate.py .
uv run python tools/validate.py paper
uv run python tools/validate.py examples/prov-entity --chapter 40_output/01-entity-definition
uv run python -m pytest tests

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.

The empty template deliberately reports placeholder, empty-chain and missing-output warnings. The public worked example follows a selected W3C PROV-DM excerpt through every content layer and gives the commands for source inventory, chapter validation and independent machine review. Its source is present locally and retains the W3C document terms. The synthetic fixtures in tests/fixtures/ test the schema with fictional material.

Layers

The numbered chain runs 00_sources → 10_markdown → 20_distillates → 30_assertions → 40_output, and each layer is checkable on its own. The rules that bind the layers to each other are set out in knowledge/schema.md § Layer model.

The three source types document, publication and data, and the criterion that assigns a source to one of them, are set out in knowledge/schema.md § Source types.

Repository layout

The five numbered folders form the production chain, each one holding the layer that the folder name announces. What each layer and its parts are is defined once in knowledge/index.md § Terminology.

• 00_sources/ holds the sources, the originals as they arrived. Whether an original is committed is set out in knowledge/operations.md § Acquire.
• 10_markdown/ holds the Markdown representations, the full texts in documents/ and the datasets plus their schema description in data/. An optional manifest.json at the vault root records their digests, so that the rule that a representation is never edited after ingest is checked, as knowledge/schema.md § Source manifest sets out.
• 20_distillates/ holds the distillates, one per source, in one subfolder per source type.
• 30_assertions/ holds the assertions, one file each, together with one topic map (MOC-*.md) per topic of the controlled topic set.
• 40_output/ holds the output, one or more documents such as a report, proposal, thesis or paper, kept as one file per chapter.

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

• knowledge/ is the governance layer, six project knowledge documents in the Promptotyping sense, holding terminology, parameters, schema, procedures, volatile state and the decision history. The two instances nested in this repository carry their own copies of the three invariant documents, and tests/test_instances.py holds every copy equal to the root apart from its frontmatter values.
• 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 machine review tool review.py, the project page generator build_docs.py and sync_instances.py, which refreshes the knowledge copies of the nested instances from the root when tests/test_instances.py reports drift. An instance with data sources adds tools/analysis/, the one folder from which data anchors re-run their deterministic scripts, one script per task.
• tests/ holds the pytest suite of all tools, with the fixture vaults the validator tests run 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, the template's decision record decisions.md, the generated project page index.html and a dated field report from an instance, all addressed to the template rather than to any instance, so an instance may delete the folder.
• .github/ holds the CI workflow checks.yml, which runs the Quickstart commands above 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, knowledge/index.md, knowledge/schema.md and knowledge/operations.md by uv run python tools/build_docs.py --date <date> and is never edited by hand.

Checking

Three instances check the vault, with strictly separated authority. Validation (tools/validate.py) judges resolvability and form, machine review by a language model judges whether a source location supports the statement built on it, and human verification alone establishes evidence. A status is only ever set by a check that actually ran, and a document never stands higher than the anchors it rests on. The terms are defined in knowledge/index.md § Terminology. The contracts, the finding codes, the chapter scope and the status discipline are set out in knowledge/operations.md § Check.

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, and 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 uv run python tools/validate.py . on every change, and uv run python -m pytest tests when you touch the tools. How errors and warnings count is set out in knowledge/operations.md § Check.

Licence

Code in tools/, tests/ and executable examples is licensed under MIT. Authored documentation and teaching material are licensed under CC BY 4.0. Third-party research data retains its own terms, and rights remain with its respective holders.

Concept

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

The repository is the reference implementation of this concept.

The architecture applied to itself is the method manuscript in paper/40_output/grounded-vault-method.md.

1. Problem

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.

2. Core idea

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 chain fastens onto one property of its subject matter. Whether a statement has a source location at all, and what stands there, is settled by a fast oracle, a resolver that answers in milliseconds whether the anchor exists. 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. Checking here is therefore fastened to the one relation that is cheap to test, resolvability, and whether the resolved location supports the statement is handed to the judging instances defined in section 6.

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.

3. Terminology

The vocabulary is chosen to keep an epistemological distinction visible that generated knowledge tends to blur, the distinction between material and evidence. Every term is defined once, in the terminology section of the index document in knowledge/, and this paper uses the terms in that sense without defining them again. Three choices behind that vocabulary need their reasons stated here.

A source is where information comes from, and nothing about being a source implies being checked or being true. Grounding names the structural relation an agent can produce, a resolvable anchor from a statement to what it rests on, and evidence names the same relation after a human expert has judged that it holds. The word evidence is reserved for that final state so that it stays rare and expensive inside the architecture, and a freshly generated vault contains grounding only.

The term assertion 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. It was preferred over claim, which in the attribution literature names the unit under test without saying whether it rests on anything.

The three checking instances are named validation, machine review and verification. 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 follow the epistemology of the domain, where establishing truth is a human act and establishing formal conformance is a mechanical one.

4. Layer model

The vault is organized in ascending layers, sources, Markdown representations, distillates, assertions and output, each with the anchor form the schema fixes for it. Each layer is checkable on its own, so the vault can be handed over even when upper layers are incomplete, and the numbered folder names keep the stratification visible in any file listing.

Two rules constrain the chain, and both exist for the same reason. IDs are minted only at the layer they belong to, and each layer anchors only into the layer directly beneath it. Together they force every statement through the synthesis and checking machinery before it can reach a source, so that no output sentence can quote a passage the distillate layer has not reproduced and no assertion can rest on a passage no statement has been checked against.

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. Posit and assertion differ in kind and not in ripeness. An assertion rests on sources and carries a status that records how far it has been checked, while a posit rests on the author and carries no status, because it makes no claim about a source that a check could test. A posit therefore never matures into an assertion. What it leaves behind is its open evidence question, a research task rather than a defect, and the posit count of a chapter measures how much of the text stands on the author alone.

Contradictions between sources are preserved. Assertions that cannot be reconciled are marked as contested and linked to each other, and a chapter that reports the matter grounds in both sides. A contradictory source situation is itself information for the output, and only human verification settles it.

5. Source types

The initial typology covers three source types, document, publication and data, with a fourth sketched. 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. The reason is that the anchor form follows from what the vault can hold. Where a full text may be stored, the anchor is a block reference into it, which resolves inside the vault and can be re-read at any time. Where only a bibliographic record may be stored, the anchor is a verbatim quotation, which the vault cannot re-check later, so the quotation check happens once at intake and is recorded with the text version it ran on. Where the source is a dataset, a statement like an aggregate exists at no passage, so the anchor is a deterministic computation that validation can re-run and compare exactly. The document type is therefore preferred wherever storage is permitted, and the publication type is the fallback.

Licensing and confidentiality are metadata of the individual source, recorded in a Dublin-Core-compatible block on its Markdown representation. Whether a full text may be archived, versioned or published is read off these fields instead of being wired into the architecture. 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, and a project may run a single type or several.

Images and other carriers are only sketched. An image whose text can be recognized enters as a document through an OCR converter. An image whose content is not text would need an anchor of its own, the image file plus a region or a documented description, and that type is named as an extension point and left unelaborated.

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 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. A manifest of digests makes the immutability checkable.

Acquisition channels

How a source enters the vault is a dimension orthogonal to its type. The type fixes the anchor mechanics, and the channel describes the intake. A document can arrive by handover from a project partner, by manual collection, by import or by agent-driven deep research. A publication, which has no original in the vault, arrives by import from a reference library or by deep research. The channel is recorded in the channel field of the Markdown representation, or of the distillate for a publication, and changes 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 and counter-checks each finding adversarially. It delivers the located publications with their relevant passages quoted verbatim and leaves synthesis to the vault. Priority rules favor peer-reviewed and official sources, and 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.

6. Checking instances and the audit trail

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 that every core statement carries an anchor of the form its source type requires, that every anchor resolves one layer down and skips none, that every computation re-runs to the stated result, that every assertion is reachable from a topic map, that frontmatter conforms to the document type schema, that no status stands above the checks recorded for it or above the status of its anchors, and that a chapter's footnotes and its structured mirror agree. The complete list of finding codes is in the operations document. 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 verification role named in the project's specification.

The architecture fixes a check contract per instance, and 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 the validator tools/validate.py, which covers the schema-level checks together with the anchor checks per source type, and for machine review the contract with its reference prompt skeletons and the pairing tool tools/review.py.

The audit trail records the progression. A document moves through the statuses grounded (structurally anchored, produced by the agent), validated (deterministic checks passed and machine review returned fully supports for every pair, or for a chapter, deterministic checks passed and every cited assertion validated) and verified (expert review passed), with contested beside the ladder for assertions whose sources conflict and superseded for distillates a revised source has replaced. The overall state of a vault is readable as the distribution of its documents across these statuses. A freshly generated vault sits almost entirely at grounded and validated, and the human work consists of lifting statements to verified. No instance ever sets a status above its own authority.

7. Governance layer and Promptotyping

The vault separates meta-knowledge from content. A knowledge/ folder carries the documents that govern production, six in the template, separated by what an agent loads together and by how fast content ages, and the index document among them lists what each holds. A split rule accompanies the core. A document is divided only when its sections develop divergent update rhythms or divergent readers, so grown instances may 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, and 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 and adds the answer to the follow-up question of 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 profile departs from the Promptotyping document convention in three points. The navigation document is index.md in lower case, following the naming rule that every file of the vault is an ASCII-lowercase slug. The vault keeps no separate handoff inbox, because open items stand in state.md under open work and decisions in the journal. Without an inbox the convention's integration entry types have nothing to record, so journal entries record decisions, rejected alternatives and calibration results of the checks instead.

8. Dual readability

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.

9. The output as parameter

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, and 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, with specification and decision documents binding to assertions and the code binding 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.

10. Repository topology

The folder layout of the template is listed in the README. The folder names keep the layer numbering, because it makes the stratification visible in any file listing.

11. Instantiation

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 and the status progression, is invariant, and the governance document set is the core an instance starts from and may grow by the split rule of section 7. 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.

12. Lineage

The architecture stands in recognizable traditions and gains its terminology from them. From historical source criticism it takes the relational concept of evidence, the primacy of the source location, and the rule that what a source states is kept apart from what is asserted as fact. 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 of these instruments, arranged so that AI agents can produce the structure at scale while humans retain sole authority over what counts as evidence.

Terminology

Human readers start at HOME, and agents start at CLAUDE.md, which routes onto these documents.

Reading paths

• To understand the project, read knowledge/specification for purpose and parameters, then knowledge/state for where work stands.
• To produce or check content, read knowledge/schema for what a well-formed artifact is and knowledge/operations for the chain that produces it.
• To understand a past decision, read knowledge/journal, which is append-only with the newest entry last.

The six project knowledge documents

A document is split only when its sections develop divergent update rhythms or divergent readers.

Terminology

Each term of the vault is defined here and nowhere else. knowledge/schema fixes the form of what these terms name, knowledge/operations the procedures that produce and check it, and both use the terms without defining them again. The word instance is used in two senses, the checking instance (validation, machine review, verification) and the vault instance created from the template, and each occurrence is qualified where the context does not settle it.

Documents and layers

Knowledge document

A bounded, maintained document that distills fuller material into what a task needs, readable for humans and agents alike, as Promptotyping defines it. The vault knows two kinds, the distillate and the project knowledge document, and the bare term is used only where both are meant.

Project knowledge document

One of the six documents in knowledge/, which describe the vault itself, its terms, parameters, schema, procedures, state and decisions. It rests on no source, carries no anchor and stands outside the content schema.

Source

The original material a statement chain rests on. For a document or a data file it is the original file exactly as it arrived, kept untouched in 00_sources/ or, for a data file that is itself the original, in 10_markdown/data/, so that every later form of its content can be checked against it. For a publication the original stays outside the vault, and the bibliographic record in references/ stands for it.

Source type

A class of sources, assigned by whether the content of a source may be stored in the vault, and defined by what then stands in the vault for it (a Markdown representation or a bibliographic record), by its distillation operation and by the form of its grounding anchor. The source types are document, publication and data, and the assignment criterion is set out in knowledge/schema § Source types.

Markdown representation

The uniform form of a source inside the vault, produced once and never edited afterwards. For a document it is the converted full text with a block ID on every anchor-relevant paragraph, so that later layers anchor into passages that never change. For a data file it is the file itself together with a Markdown description of its schema, and the anchor into it is a computation rather than a block.

Distillate

The source-bound knowledge document, one per source. It condenses what the source says into core statements, each anchored to the source location it was taken from, and holds the source's terms, open questions and optional appraisal beside them. Being bound to a source, it falls under the content schema and its checks.

Appraisal

The optional section of a distillate that holds the vault's judgment of the source, such as the standing of its venue, the limits of its method and its relevance. It is the vault's own judgment rather than a report of the source, mints no IDs and can therefore never serve as grounding. Where it shapes the output, it enters there as a posit.

Assertion

A single source-supported statement synthesized from the distillates of a topic and grounded in at least one distillate statement. Source-supported means that it rests on sources and never on the author alone. It does not mean that the assertion is bound to one source. A core statement reports what its one source says, while an assertion states the matter, so a further source can join its grounding without the assertion changing. One source is enough.

Topic map

The file MOC-<Topic>.md in 30_assertions/, one per topic, which registers the assertions of that topic, while distillates and assertions name their topics in their own topics field. The set of topic maps is the controlled topic set.

Output

The final product of the vault, one or more documents such as a report, proposal, thesis or paper, held as chapters.

Chapter

An output text in which every load-bearing sentence carries a footnote to an assertion and every own conclusion is marked as a posit. It is the unit of the output that is checked and accepted on its own.

Posit

A conclusion in the output without source support, explicitly marked with its rationale and open evidence question. It differs from an assertion in kind, not in ripeness, and never matures into one.

Anchors and statements

Anchor

A machine-resolvable reference from a statement to the location it rests on, one layer down. The target of an anchor is an ID that the lower layer minted, a block ID in a Markdown representation or a statement ID in a distillate, or a whole assertion in the case of a chapter footnote. Minting therefore concerns IDs, and anchoring concerns the references that point at them. Each layer carries its own anchor form, a block reference, quotation or computation in the distillate, a grounding anchor into a distillate statement in the assertion, and a footnote anchor into an assertion in the chapter.

Block ID

The ID (^a1b2) minted once at ingest on a passage of a document representation, the target distillate anchors bind to.

Anchor-relevant paragraph

A paragraph of a document representation that carries a statement a distillate could reproduce, and therefore receives a block ID at ingest. Headings, captions, table cells, navigation text and boilerplate carry none. The share of these paragraphs that distillate statements anchor is the coverage, so stamping a block on text no statement could rest on lowers coverage without adding anything checkable.

Core statement

A statement in the Core statements section of a distillate that reproduces its source within the source's literal sense. The schema and the operations also call it a distillate statement when they look at it from the assertion layer. It carries exactly one grounding anchor, whose form follows the source type, a block reference for a document, a verbatim quotation for a publication and a declared computation for data. Only core statements can support an assertion.

Statement ID

The ID (^s1) that ends a core statement, minted only in a distillate, the target assertions bind to.

Grounding

The anchor relation between a statement and what it rests on one layer down, source locations for a core statement and distillate statements for an assertion. The anchors that carry it are grounding anchors. It is a structural property an agent can produce and says nothing about whether the statement is true.

Source identity

What makes two distillates distillates of the same source. For a document or a data source it is the Markdown representation they name, for a publication it is the bibliographic record together with the text version named in checked-against. Two distillates with the same source identity fail validation.

Load-bearing sentence

A sentence of a chapter whose claim the chapter would lose if the sentence were struck. Every such sentence carries a footnote to an assertion or, where no source supports it, a posit footnote. Sentences that only connect, announce or summarize what the footnoted sentences already carry are free of footnotes, and a paragraph without any footnote marker raises W-UNANCHORED.

Posit candidate

A conclusion noted during assertion building that no distillate statement carries, kept in the open questions of the topic map until a chapter either writes it as a posit or a later source lets an assertion carry it.

Displaced subject

The case in which a passage supports a statement while its subject is not the matter the assertion is about. Its two named cases are the self-report, in which a source speaks about itself, and the state report, in which a source shows its matter in one state at one time.

Provenance chain

The unbroken anchor path from an output sentence through assertions and distillates to source locations. A break anywhere is a defect. Validation detects an anchor that does not resolve, and the quotation check at intake detects a quotation that deviates from a source the vault does not hold.

Checking

Acquisition channel

The way a source entered the vault, one of handover, collection, import and deep-research. It changes nothing about how the source is checked.

Fidelity check

The last stage of distillation, which compares every core statement against its anchor. For a publication it includes the quotation check, which confirms each quotation character for character against the source text.

Coverage

The share of the blocks of a document representation that some distillate statement anchors. It asks whether the passages were used, the direction the anchor chain itself does not check.

Validation

Deterministic conformance checking of every file against the schema, by tools/validate.py in the reference implementation. It judges resolvability and form. Together with machine review it lifts a distillate or an assertion to validated, and it lifts a chapter there alone, once every assertion the chapter cites stands at validated.

Machine review

Adversarial checking by a language model under anti-anchoring, the condition that the reviewer sees only the pair and never the producing agent's reasoning. It judges per pair whether the lower element supports the upper one, with one verdict from a fixed vocabulary. Together with validation it lifts a distillate or an assertion to validated, never higher.

Pair

The unit machine review judges. A source pair is a source location (a block with its heading path, a quotation, or a computation with its result) and the core statement anchored to it. An assertion pair is a distillate statement and the assertion grounded in it, the assertion given as the prose of its Statement section. Nothing else enters a pair.

Verification

Human expert review by the verification role named in knowledge/specification. It alone establishes evidence and sets verified.

Evidence

A grounding relation that has passed verification. It is relational and deliberately rare. A fresh vault contains grounding, and evidence arises only through review. Where verification samples, only the sampled relations are evidence, and the document status verified records that the sampling rule in the journal was applied to it.

Status ladder

The sequence grounded → validated → verified, with contested for assertions whose sources conflict and superseded for replaced distillates beside the ladder. A document's status is the minimum of the states of its anchors. contested is set by assertion building or review when sources conflict, and only verification resolves it.

Audit trail

The principle that status fields record outcomes of checks that actually ran, each with its date on the checked document.

Processing status

The column of the source inventory that records how far a source has travelled along the chain, new, ingested or distilled. It is derived from the file state and is distinct from the status ladder, which records checking.

Schema

The rules of the vault cover 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 them. The procedures that produce and check these documents live in knowledge/operations.

Layer model

The source inventory in knowledge/state.md lists every Markdown representation and every distillate, and it is generated from the file state by uv run python tools/inventory.py <vault root> --write rather than maintained by hand, so that no second bookkeeping can drift away from the files. For a document representation it also carries the coverage defined in knowledge/index § Terminology, and validation raises W-COVERAGE where coverage falls below the share an instance sets.

The terms for the layers and their parts are defined once in knowledge/index § Terminology. The schema fixes the form of what they name.

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. Each layer also anchors only into the layer directly beneath it, so the output binds to assertions, assertions bind to distillate statements, and distillates bind to the blocks of the Markdown representation. Links in the Related sections serve navigation and fall outside this rule.

Controlled vocabularies

• type takes one of the values representation, distillate, assertion, moc, glossary and chapter. The value representation is the machine-side short form for Markdown representation, and the prose of this vault uses the full term.
• source-type takes one of the values document, publication and data.
• channel takes one of the values handover, collection, import and deep-research.
• status takes one of the values grounded, validated and verified, plus contested (assertions only) and superseded (distillates only).
• Each value of topics must name an existing topic map, and the set of MOC-*.md files in 30_assertions/ is the controlled topic set. A topic map's file name is MOC- followed by its topic value with spaces replaced by hyphens, and an entry of topics names that topic value.

Audit trail

A status records the outcome of checks that actually ran. Every check leaves its date in the checked map of the document it checked, written by the tool where the tool books (machine review through judge --apply) and by the agent after a clean run where the tool only reports (validation), and for verification by or on behalf of the verifying role:

status: validated
checked:
  validation: 2026-07-11
  machine-review: 2026-07-11

The discipline is machine-enforced. For a distillate or an assertion, validated requires checked.validation and checked.machine-review. A chapter reaches validated with checked.validation alone, because machine review pairs the assertions it cites and not its sentences, and the minimum rule below keeps it at grounded until each of those assertions stands at validated. verified additionally requires checked.verification for every type. 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. No instance ever sets a status above its own authority, and the contracts that fix each authority are defined in knowledge/operations.

Source metadata

Every Markdown representation carries a compact, Dublin-Core-compatible metadata block. Licensing and confidentiality are metadata of the individual source, and 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 local

Source types

The 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.

Bibliographic records

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, with a single-record object accepted for an export of one record. Each record carries a nonempty string or integer id alongside its bibliographic fields. IDs are unique across the entire reference directory. Malformed records fail whole-vault validation even when unused, and a duplicate ID resolves to no record. In chapter scope only the records the scope cites are checked.

[
  {
    "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.

Source manifest

The rule that a Markdown representation is never edited after ingest becomes checkable through an optional file manifest.json at the vault root. It records, for every retained original in 00_sources/ and every Markdown representation, the vault-relative path with forward slashes and the SHA-256 digest of the file. The digest of a text file is taken over its content with CRLF line ends folded to LF, so that a checkout on Windows and one on Linux agree, and validation also accepts the digest of the raw bytes, which is what sha256sum prints and what a binary original has.

{
  "source_url": "",
  "source_status": "",
  "source_date": "",
  "source_scope": "",
  "source_license": "",
  "source_copyright": "",
  "authored_license": "",
  "files": [
    { "path": "00_sources/<slug>.<ext>", "sha256": "<64 hexadecimal digits>" },
    { "path": "10_markdown/documents/<slug>.md", "sha256": "<64 hexadecimal digits>" }
  ]
}

Only files carries rules. The keys beside it are optional free metadata about the source and the rights under which the vault holds it, and validation does not interpret them. A NOTICE file beside the manifest carries the rights notices that third-party terms require, and validation does not read it at all. The folder checks/ at the vault root holds the returned machine review batches as JSONL, one file per review run named by its date, as the record the machine review contract in knowledge/operations lets a batch retain.

A vault without a manifest has no defect. Once a manifest exists, every path it lists must exist and match its digest, and every Markdown representation must be listed. Validation raises E-MANIFEST for an entry that fails and W-MANIFEST for a representation the manifest leaves out.

Document types

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.

1. Markdown representation (source-type: document)

Exactly one per source, stored in 10_markdown/documents/. A revised source enters as a new file with a date-suffixed slug, and 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. ^a1b2

Block IDs are short, stable, unique per file, and minted only here.

2. Markdown representation (source-type: data)

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.

3. Distillate

One file per source in 20_distillates/<source-type>s/, same slug as its Markdown representation. For document and data sources this means one distillate per representation. For publications the identity combines the bibliographic reference and the named text version in checked-against, so explicitly different versions remain distinct. Duplicate identities fail validation. 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: {}
checked-against: ""          # publication type: the text version checked.quote ran on
channel: import              # publication type, optional: import | deep-research
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:

• For a document, the anchor is a block reference into the Markdown representation, as above.
• For a publication, the anchor is a verbatim quotation with citation instead of a block reference. The quotation must appear character for character in the source. The intake-time check is recorded as checked.quote, and checked-against names the text version that check ran on, such as a preprint version, a publisher PDF or a page revision with its date. A publication has no representation in the vault, so nothing else records which text the quotations follow, and a record that later points to another version ages the quotations without moving any date. Validation raises W-VERSION while the field is missing.

  - <statement in own words> ^s1
    > "<verbatim quotation>" (<identifier>, p. <n>)

  The quotation block opens with the verbatim text in quotation marks and closes with the identifier and locator in parentheses. It may run over several > lines, and validation reads it as one block against that form.

• For data, the anchor is a reproducible computation instead of a block reference, named on an indented line. The script lives in 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, with surrounding whitespace trimmed, character for character with the stated result, so any other 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.

4. Assertion

One file per assertion in 30_assertions/. This is the layer where source types converge. An assertion resting on a single source is allowed, and the displaced-subject cases below say when it has to name that source.

---
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 in the sense of knowledge/index § Terminology, and where a source turns up later, a new assertion is written and the posit falls away. Assertions that cannot be reconciled are both set to contested and linked to each other in contested-with.

A displaced subject in the sense of knowledge/index § Terminology, a passage that supports the statement while its subject is not the matter the assertion is about, escapes validation, and machine review separates it only because its contract in knowledge/operations § Check names the two cases. The rule for the assertion in each case is this.

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 drops the self-report anchor and rests on a second and independent source. Keeping the self-report anchor beside the independent one leaves a pair that machine review marks as overreaching, and the assertion then never reaches validated.

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 drops the state-report anchor and rests on a source that establishes the property for the span the assertion claims, for the same reason as above.

5. Topic map (MOC)

One file per topic of the controlled topic set, named MOC-<Topic>.md in 30_assertions/. The set of these files is the controlled topic set.

---
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.

6. Glossary entry

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.

7. Chapter

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
---

Under 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, and 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.

Project knowledge documents

The six project knowledge documents in knowledge/ carry the Promptotyping header, as at the top of this file, instead of a content type, and they are exempt from the content schema, as knowledge/index § Terminology sets out.

Naming

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.

Operations

Every chain of the vault produces or checks artifacts defined in knowledge/schema and updates the registers in knowledge/state. Decisions made along the way go to knowledge/journal.

Production order

The first production cycle runs vertically. One source is carried through every chain below, from acquisition to a written paragraph of a chapter, and validated after each step, before a second source is touched. The tempting order is the horizontal one, converting every original first and then writing every distillate, because each step feels cheaper when repeated. That order produces nothing checkable until the last layer is reached, and a defect in the anchor mechanics then sits in every file at once instead of in one. Agents left to themselves choose it, so the rule has to be explicit.

Acquire

How a source enters the vault is orthogonal to its type. The acquisition channel is recorded in the channel field of the Markdown representation, and for a publication, which has none, in the channel field of its distillate.

• For handover and collection, place the original in 00_sources/.
• For import, export records from the reference library as CSL JSON into references/, one file per batch of records.
• For deep-research, run the research prompt below. Capture every located publication in the reference manager and export it as CSL JSON into references/. The research report itself never becomes a source, and all anchors bind to the located publications.

Originals in 00_sources/ stay out of version control by default, because third-party rights usually forbid redistribution. An original whose rights the project holds is committed by force-adding it past .gitignore.

Deep research prompt skeleton

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.

Ingest

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, so that a later run can be reproduced or repeated with a different tool.

• Short, simply structured texts are converted by the agent itself, because a tool adds nothing where the structure is already flat.
• Standard office and PDF formats go through MarkItDown or pandoc.
• Complex layouts and scanned documents go through Docling, which works markedly faster when a GPU is available.
• Image sources that require OCR are a named extension point of this profile and are not yet worked out.
• For a document, run the Markdown conversion into 10_markdown/documents/, note the converter in the frontmatter, set the H1 from the original and fill the metadata block.
• For data, place the data file in 10_markdown/data/, write the schema description of the same slug and fill the metadata block.
• A publication gets no Markdown representation, because the CSL JSON record in references/ is the root of this source type.

Then run uv run python tools/inventory.py <vault root> --write, which rewrites the source inventory in knowledge/state from the real file state.

Supersede

A revised version of a source that already has a Markdown representation enters as a new source. Ingest it under the same slug with a date suffix, distill it, and set the old distillate to status: superseded with superseded-by naming the new distillate. The old representation and distillate stay in place, because existing anchors resolve against them, and an assertion that rests on a superseded statement is re-grounded in the successor where the successor still carries it, or stays at grounded by the minimum rule until it is. Record the supersession in knowledge/journal.

Distill

One distillate per source, produced as a three-stage chain:

1. In the extraction, an LLM draws the core statements from the source with the canonical prompt (one statement per anchor, no evaluation, no cross-source merging).
2. The formatting is a deterministic pass that enforces the section skeleton, statement IDs and anchor syntax from knowledge/schema.
3. The fidelity check compares each statement against its anchor. For publications, run the quotation check now, while the source text is at hand, record it as checked.quote and name the text version it ran on in checked-against.

Canonical extraction prompt skeleton

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.

Extraction is judged in both directions. The fidelity check asks whether every statement has its passage. The coverage figure in the source inventory asks whether the passages were used, and W-COVERAGE names a source whose blocks the distillate mostly leaves unanchored. Such a finding is answered by extending the distillate, or by a journal entry stating why the rest of the source is out of scope for this vault.

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 uv run python tools/inventory.py <vault root> --write again, so that the source inventory in knowledge/state carries the new file state.

Build assertions

Assertions are where the vault synthesizes, one file per assertion, and the work proceeds by topic in these steps.

1. Enter through the topic map of the topic and read every distillate whose topics names the topic, so that synthesis covers the sources the topic actually holds rather than the ones at hand.
2. Gather the distillate statements that concern the same matter, across sources and across source types. A group is the unit an assertion is written from.
3. Write one atomic assertion per group, carried jointly by the sources of that group. Atomic means one statement that cannot be split without losing its point.
4. List in grounding every statement ID that supports the assertion, and say in the Support section what each anchor contributes. Where several statements of one source support it, each gets its own entry, because machine review judges per pair.
5. Check each group for a displaced subject and apply the rule knowledge/schema § Assertion gives for the self-report and the state report.
6. Where a group holds statements that cannot be reconciled, write two assertions instead of one, set both to contested, and link them to each other in contested-with on both sides. Assertion building is the only step that sets contested. A machine review verdict of contradicts is a finding that sends the pair back to this step, and verification alone resolves a contested pair by recording which side holds, after which the other side is removed or rewritten.
7. A conclusion that no distillate statement carries is noted as a posit candidate under the open questions of the topic map and never becomes an assertion. The appraisal sections of the distillates are read at this step as posit candidates, never as support, because they hold the vault's judgment of a source rather than its content.
8. Enter every assertion in its topic map with a half-sentence of orientation, and record questions the sources leave open under the map's open questions.

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.

Assertion review prompt skeleton

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. If the statement reports what its source says about itself, or shows the matter in one dated state, the assertion is fully supported only if it keeps the speaker or the state with its date, and it overreaches otherwise. In either case add one line naming the displacement.

STATEMENT: {distillate statement, without its own grounding anchor} ASSERTION: {assertion as one sentence}

Write chapters

Write per chapter, in the working language and style sheet set in knowledge/specification. Every load-bearing sentence gets a footnote Grounded in [[assertion]], and 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.

Query

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.

Check

Three instances check the vault. The architecture fixes their contracts, and the mechanism fulfilling each contract is an instantiation decision recorded in knowledge/specification.

Validation contract

• Validation judges the formal conformance of every file against knowledge/schema.
• Its authority is to gate everything, so no other check runs on a file that fails validation. It sets no status by itself. It enforces the status discipline, and for a chapter, which machine review does not pair, its record is the one check the validated rung requires.
• It is deterministic, so the same input yields the same verdict, and it runs on every change.
• Its record is checked.validation: <date> on every file that passes. tools/validate.py reports and writes no file, so the agent sets the date after a clean run.
• Its reference mechanism is uv run python tools/validate.py <vault root>, with the finding codes listed in the table below. In every command of this document <vault root> is . for a stand-alone instance and the instance folder, such as paper, for an instance nested inside the template repository, run from the repository root. Data anchors are re-run by default, and the output of each computation is compared with its stated result after surrounding whitespace is trimmed. --no-computations switches the re-run off for a fast run. A computation script is executed only from tools/analysis/, because the validator executes whatever the vault names. --min-coverage sets the share of blocks below which a source counts as unexhausted. The default is half, and an instance that decides otherwise records its value in knowledge/specification and passes it in its harness rules.
• In chapter scope, uv run python tools/validate.py <vault root> --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.
• A run without errors is not by itself the success criterion. Every warning is printed, counted and to be acted on. A warning names either a check that found no subject or a defect the schema does not make an error, and both are the failure modes a silent green run hides. Over the whole vault a warning never changes the exit code, so that work in progress stays runnable. In chapter mode a warning fails the run, because there the run decides acceptance.
• W-UNANCHORED works at paragraph level and does not prove that every sentence is supported. An output paragraph with a footnote still needs inspection for claims that exceed the cited assertion.

The finding codes of the reference mechanism are these.

Bibliographic imports also fall under E-FRONTMATTER when their JSON, encoding or record identity is malformed. Bibliographic duplicate-ID and import-shape checks apply to whole-vault validation. Chapter validation checks whether the references its distillates use resolve, while unrelated imports stay outside that chapter's scope. Distillate source-identity checks use the selected scope.

Machine review contract

• Machine review judges per pair whether a source location actually supports the statement built on it, with the fixed verdict vocabulary fully supports, partially supports, overreaches, contradicts and not in the text. Only fully supports passes.
• Its authority is to lift a distillate or an assertion to validated together with validation, never higher.
• Anti-anchoring is a mandatory condition. The reviewer sees only the source location and the statement, and the producing agent's reasoning stays hidden. A reviewer from a different model family is recommended as a precaution against shared error patterns. Family choice alone does not establish independence, and the review record names the mechanism actually used.
• Its record is checked.machine-review: <date>. Verdicts below fully supports trigger rework and are noted in the journal when they reveal a systematic pattern.
• Its reference mechanism is uv run python tools/review.py with the subcommands stats, emit, judge and run. stats counts the pairs, emit writes one prompt per pair as a JSONL batch, and judge reads the verdicts back and, with --apply, books checked.machine-review on every document whose pairs all came back fully supports. Booking runs the validator with its computations first and books nothing on a document with validation errors. run judges each pair through the local claude -p command line and takes --apply as well, while emit and judge are the path for a separately instructed reviewer. Every subcommand narrows its selection with --scope (all, source or assertion pairs) and --path (a document path prefix), and judge and run accept --date to override the recorded review date.
• Reference prompt skeleton:

  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. If the passage speaks about its own source, or shows its matter in one dated state, the statement is fully supported only if it keeps the speaker or the state with its date, and it overreaches otherwise. In either case add one line naming the displacement.

  PASSAGE: {source location, with its heading path} STATEMENT: {statement}

• In pair cutting, a pair consists of the anchored location (for documents the block plus its heading path, for publications the quotation, for data the computation and its result) and the bare statement, in which a wikilink reads as its alias or its slug and the statement's own anchor link is dropped. Nothing else enters the pair.
• An assertion pair includes the full prose of its ## Statement section. The title is a fallback for an assertion without that section. A correct title cannot substitute for checking additional claims in its statement.
• Each emitted pair carries prompt_hash, the SHA-256 digest of the exact UTF-8 prompt. A returned JSONL record must carry its unchanged id and prompt_hash together with verdict or response. Only a clear first-line verdict from the fixed vocabulary is accepted. A defective record, meaning a missing or malformed digest, a duplicate identifier, a conflicting response, an unparseable verdict or an unknown pair, fails the whole batch, and nothing is booked until the batch is clean. A verdict whose prompt has changed since export leaves its document unbooked. Re-export and review changed pairs. An empty selection fails visibly.
• judge --apply records a machine-review date only. It never sets the document's status or records validation on behalf of the operator. Validation dates are recorded after actual clean runs, and each status transition follows the audit trail in knowledge/schema. Batch judgement records may additionally retain the reviewer mechanism, actual model where known, timestamp and rationale, and the returned batch is kept under checks/ as JSONL in one file per review run named by its date. These fields stay outside the adversarial prompt.
• Where the pair shows a displaced subject in the sense of knowledge/index § Terminology, the reviewer adds one line naming the displacement. The verdict stays fully supports when the statement reports a self-report as the source's own claim or names a state report with its date, and it is overreaches when the statement asserts the matter itself. The rule for the assertion in each case is in knowledge/schema § Assertion.
• The content binding implements a version-specific review record. It follows the distinction between fixed entities and revisions in W3C PROV-DM. Reviewing the complete statement addresses the distinction the ALCE benchmark (Automatic LLMs' Citation Evaluation) draws between citation recall, whether the cited passages support every claim in a statement, and citation precision, whether individual citations are relevant. ALCE motivates this distinction, but does not establish the accuracy of this tool's judgements. Neither source prescribes the particular hash or batch format used here.

Verification contract

• Verification judges by human expert judgment whether a grounding relation holds as evidence. The authority is the verification role named in knowledge/specification.
• It alone lifts to verified, and it alone resolves a contested pair, by recording in the journal which side holds. Machine checks prepare it and never replace it.
• It proceeds passage by passage on the prepared pairs and may sample where the machine review pass rate justifies it, with the sampling rule noted in the journal.
• Its record is checked.verification: <date>, set by or on behalf of the verifying role.