A file-based governance layer for human–AI work where agents do not get to invent state.
Agents may propose state. Receipts establish it.
Status: v0.2.0, released 2026-07-16. The public tag v0.2.0 is the release record; v0.1.0 remains the record of the first cut.
Two versions, on purpose: the release version (0.2.0) names what ships from this repository — checker, lab, docs. The method version (0.1.0, unchanged since the first release) names the specification contract in SPEC.md that vaults declare conformance to via method_version. This release adds the Vault Lab; the method itself did not change.
Break it. Fix it. Try to beat it: run lab/start.sh — the Vault Lab, a five-case guided falsification run against the real checker.
BAION Vault Method (BVM) is a reference methodology for maintaining trustworthy project state when humans and AI agents work in the same file-based environment. It separates proposed work from accepted claims, requires addressable evidence before promotion, preserves corrections without erasing history, and ships an executable checker so structural conformance is a command rather than a feeling.
BVM is not a consciousness claim, an AI-safety certification, a substitute for domain expertise, or a universal knowledge-management standard. Method v0.1.0 is a bounded reference method with a bounded checker.
The fastest way to understand the method is to watch it fail. The
Vault Lab walks you through five small vaults that each
violate one MUST — you predict the diagnostic, watch the real checker
catch it, study the exact repair diff, and watch it pass. Four judgment
scenarios then cover what the checker cannot decide, and the
challenge invites you to construct a vault that
violates a SPEC.md MUST while bvm-lint --strict stays green — verified
catches are credited in the Hall of Catches.
lab/start.sh # guided run, 15-25 minutes
lab/start.sh --check # non-interactive fixture verificationAI collaborators can produce useful work quickly. Fluent output can also conceal:
- unsupported gap-filling;
- stale or contradictory project state;
- several reviewers sharing the same incomplete evidence window;
- a proxy, mock, summary, or remembered description substituted for the governed object;
- negative results from an unproven measurement path;
- aggregate claims where one unit was never checked;
- corrections that overwrite the very history needed to audit them.
A folder tree alone does not prevent those failures. BVM treats accepted state as something that must be established, not merely written.
- Unknown stays unknown. Missing evidence is not completed with plausible prose.
- The governed object outranks its description. Inspect or execute the canonical source, function, dataset, registry, or binary when the claim depends on it.
- A proxy does not inherit the governed object's claim. Substitutes are labeled and bounded.
- The primary enforcer differs from the writer. Self-reminders are a backup, not the canon gate.
- Receipts precede promotion. Evidence, review, candidate bytes, and the promotion decision remain addressable.
- Reviews bind exact bytes. A review of yesterday's draft does not approve today's edit.
- Promotion binds its receipts. Evidence and review records cannot change after promotion without invalidating current state.
- Negative results require a positive control. “Nothing happened” is uninterpretable until the path detects a known signal.
- Aggregate claims enumerate their units. Every declared unit maps to a passing unit receipt.
- Receipt control is explicit. Applicability, provenance, and declared supersession—not timestamp alone—determine which receipts remain controlling; unresolved applicable conflicts block canon.
- Corrections preserve history. Supersession and retraction retain the prior bytes and verify identity by hash.
The normative requirements are in SPEC.md.
WORKING versus CANON, promotion gates, and preserved history have precedents in research and data governance. BVM's sharper contribution is the AI collaboration contract around them:
- an agent may draft state but cannot establish it from recall;
- transcripts establish authorization history, not external factual truth;
- a canonical-object claim stops when the real object cannot be inspected or executed;
- multiple AI reviews sharing one evidence window do not become independent factual anchors;
- corrections preserve the failed claim and its hash;
- the repository includes machinery that rejects declared state when its receipts no longer match.
The method is accompanied by anonymized operating reports that preserve real catch-and-correction shapes alongside the fictional tutorial. They are not independent proof that the method generalizes or earns its overhead in every setting.
The checker requires Python 3.11 or newer and has no runtime dependencies outside the standard library.
python -m pip install -e .
bvm-lint examples/tutorial-vault --strict
./verify_repo.shExpected lint result:
PASS: structural conformance established for examples/tutorial-vault
A zero exit code means the checker found no structural violations. It does not prove that the underlying claim is true, safe, complete, or persuasive.
See QUICKSTART.md for the promotion sequence. A crucial detail is that the final candidate is frozen under RECEIPTS/candidates/; the review and promotion records must match the exact promoted bytes.
VAULT/
├── vault.toml
├── INDEX.json
├── INBOX/
├── WORKING/
├── CANON/
├── RECEIPTS/
│ ├── candidates/
│ ├── data/
│ ├── evidence/
│ ├── reviews/
│ └── promotions/
├── RETRACTIONS/
├── HANDOFFS/
└── ARCHIVE/
The directories are not the method by themselves. The method is the set of allowed transitions and the evidence required to cross them.
CAPTURE → WORKING → EVIDENCE + SEPARATE ENFORCEMENT → FROZEN CANDIDATE → CANON
↘ contradiction / failure ↘
RECONCILE SUPERSEDE / RETRACT
↓
ARCHIVE
- A normative core specification.
- A zero-dependency Python checker with stable diagnostic codes.
- Machine-readable schemas and starter templates.
- A runnable fictional tutorial vault.
- Four anonymized field reports derived from real operating catches.
- Tests for valid state and failure paths, pinned CI actions, link validation, and publication-boundary checks.
- A clear split between core requirements, recommended practices, and BAION-specific patterns.
bvm-lint checks declared structure, including:
- strict JSON metadata with duplicate-key and nonstandard-constant rejection;
- state/directory agreement, timestamps, unique identities, and safe vault-relative links;
- source, governed-object, review, candidate, promoted-artifact, retracted-artifact, and replacement hashes;
- exact agreement between an artifact's evidence/review set and its promotion receipt;
- SHA-256 binding of every evidence and review receipt used for promotion;
- SHA-256 binding of the current promotion receipt from
INDEX.json; - positive controls for declared negative results;
- authoritative-search receipts for declared negative-existence claims;
- per-unit receipts for declared aggregate claims;
- canonical-object execution requirements and proxy boundaries;
- SemVer-ordered, acyclic supersession with preserved predecessors;
- no orphaned archive artifacts;
- one indexed current canon artifact per lineage;
- required continuity sections in managed handoffs;
- unresolved pass/fail receipt conflicts for current canon.
The checker can only enforce requirements represented in declared metadata. It cannot infer that an author should have marked a claim as negative, aggregate, negative-existence, or canonical-object-dependent. That semantic declaration remains a review responsibility.
See the linter reference and conformance limits.
The field reports preserve four catch shapes:
- shared reviewers reached the same wrong conclusion from one partial source window;
- a budget-bound null result was promoted into “wall” language, then retracted across a preserved claim chain after a larger run produced a witness;
- a differential probe showed that a parsing defect had been attributed to the wrong implementation;
- a negative-existence claim persisted without querying the authority it named.
Private paths, identities, unpublished subject matter, and protected implementation details are removed. The gate, catch, correction, and enforcement lesson remain.
For a solo human working with one or more AI agents, begin with:
WORKING,CANON,RECEIPTS,RETRACTIONS,ARCHIVE, andINDEX.json;- at least one evidence receipt and one separate, exact-byte review for canon promotion;
- a frozen candidate, receipt-hash manifest, and exact-byte promotion receipt;
- a positive control for every declared negative result;
- a retraction record that preserves the prior artifact when a claim is withdrawn;
bvm-lint --strictin CI.
Add richer receipt types and handoff discipline when the work needs them. Complexity that is not enforced is ceremony.
This repository deliberately says reference methodology, not standard. Standards language would require broader adoption, independent implementations or conformance work, stable external governance, and evidence that the requirements generalize beyond the originating environment. Those conditions have not been earned yet.
This repository is fresh public authorship. It is not a sanitized dump of a private operating vault. Field reports preserve failure shapes while removing private paths, project identifiers, counterparties, unpublished subject matter, and protected material. See PUBLICATION_BOUNDARY.md.
A strong proposal identifies a concrete failure mode, names the enforcement site, includes a failing fixture, and adds a mechanical check when feasible. Read CONTRIBUTING.md and GOVERNANCE.md first.
Citation metadata is in CITATION.cff. All material included in this public repository is licensed under the MIT License. Private vault contents and other material not included here are outside this repository’s licensing and distribution boundary.