This repository contains the implementation and demonstration of a typed simplicial complex framework for document verification, validation, and assurance of AI Generated Content with explicit human accountability.
Element Counts: 56 vertices | 148 edges | 65 faces | χ = -27
The paper "Test-Driven Document Development: Simplicial Complexes for Verification, Validation, and Assurance with Human Accountability" demonstrates a framework where:
- Documents are vertices (0-simplices) in a typed complex
- Verification, validation, and coupling are edges (1-simplices) connecting documents
- Assurance triangles are faces (2-simplices) representing complete quality attestation
- Human accountability is structurally required for validation judgments
The paper is its own proof. The file doc-incose-paper-2026.md exists as a vertex in an assurance complex, verified against its specification, validated against its guidance, with all checks passing.
This repository is designed for two complementary workflows:
Best for: Building, verifying, and analyzing the knowledge complex
- Run verification scripts directly from terminal
- Edit documents with full IDE features
- Use Claude Code for AI-assisted document development
- Git integration for version control and accountability
Key commands:
python scripts/verify_template_based.py <file> --templates templates
python scripts/audit_assurance_chart.py charts/<chart>/<chart>.md
python scripts/build_cache.py
Best for: Exploring relationships and understanding structure
- Wiki-style
[[wikilinks]]for seamless navigation - Graph view visualizes document relationships
- Backlinks show what references each document
- Local-first, works offline
To use: Open this repository as an Obsidian vault. See [[QUICKSTART]] for a 5-minute guide.
# Setup
git clone https://github.com/BlockScience/assurances-audits-accountability
cd assurances-audits-accountability
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
# Verify the paper
python scripts/verify_template_based.py 00_vertices/doc-incose-paper-2026.md --templates templates
# Run the assurance audit
python scripts/audit_assurance_chart.py charts/incose-paper-assurance/incose-paper-assurance.md
# Run all tests
python -m pytest tests/ -vExpected output:
Result: ✓ PASS
Checks: 6/6 passed
Status: PASS
Invariant: F = V - 1: 7 = 8 - 1 ✓
Coverage: 100.0% (7/7 targets assured)
assurances-audits-accountability/
├── 00_vertices/ # Document vertices (56 files)
│ ├── doc-incose-paper-2026.md # THE PAPER (also a vertex)
│ ├── spec-for-*.md # Specifications (27 files)
│ ├── guidance-for-*.md # Guidance documents (22 files)
│ └── doc-*.md # Content documents (5 files)
├── 01_edges/ # Relationship edges (148 files)
│ ├── verification-*.md # Verification edges
│ ├── validation-*.md # Validation edges (with approvers)
│ ├── coupling-*.md # Spec-guidance coupling
│ └── signs-*.md, qualifies-*.md # Signature infrastructure
├── 02_faces/ # Faces (65 files)
│ ├── assurance-*.md # Assurance triangles
│ ├── signature-*.md # Signature triangles
│ └── b2-*.md # Boundary faces
├── charts/ # Composed subcomplexes
│ ├── incose-paper-assurance/ # THE AUDIT CHART
│ ├── boundary-complex/ # Foundational structure
│ └── test-tetrahedron/ # Test fixture
├── docs/ # Documentation
│ ├── concepts/ # Core concepts explained
│ └── images/ # Screen captures for documentation
├── figures/ # Paper figures
├── scripts/ # CLI tools
├── templates/ # Type definitions
└── tests/ # Test suite
Central hub: [[NAVIGATION]] — Start here for exploring the knowledge complex
| Directory | Obsidian | GitHub/VS Code | Contents |
|---|---|---|---|
| Vertices | [[00_vertices/README]] | 00_vertices/ | 56 document vertices |
| Edges | [[01_edges/README]] | 01_edges/ | 148 relationship edges |
| Faces | [[02_faces/README]] | 02_faces/ | 65 triangular faces |
| Charts | [[charts/README]] | charts/ | Composed subcomplexes |
| Docs | [[docs/README]] | docs/ | Concepts & use cases |
| Templates | [[templates/README]] | templates/ | Type definitions |
Every assured document requires three edges forming a closed triangle:
- Verification edge → document passes structural checks against spec
- Coupling edge → spec is linked to corresponding guidance
- Validation edge → document assessed against guidance (requires human approver)
In any valid assurance audit chart:
- Every vertex (except root) must have exactly one assurance face
- Every face assures exactly one vertex
- V - F = 1 where root provides assurance but doesn't need it
Self-referential foundations (spec-for-spec, guidance-for-guidance) are resolved through a root vertex that anchors boundary faces, enabling computational topology methods without paradox.
The paper references three figures generated from this repository:
| Figure | Description | Source |
|---|---|---|
| Figure 1 | Assurance Triangle | figures/figure1-final.png |
| Figure 2 | Boundary Complex | figures/figure3-final.png |
| Figure 3 | Audit Chart | figures/figure2-final.png |
| Script | Purpose |
|---|---|
verify_template_based.py |
Verify document against its type template |
audit_assurance_chart.py |
Check assurance coverage and V-F=1 invariant |
topology.py |
Compute Euler characteristic |
visualize_chart.py |
Generate interactive visualization |
visualize_assured_signed.py |
Enhanced 3D visualization with layered architecture |
build_cache.py |
Build element cache and validate all documents |
This repository IS the evidence for the paper's claims:
- The paper exists as [[doc-incose-paper-2026]] (GitHub)
- Verification passes against [[spec-for-incose-paper]] (GitHub)
- Validation recorded in [[validation-incose-paper-2026:guidance-incose-paper]] (GitHub)
- Assurance face closed in [[assurance-incose-paper-2026-base]] (GitHub)
- Audit passes with 100% coverage and V-F=1 verified
The existence of this repository with passing audits proves the framework works.
- Python 3.12+
- uv (recommended) or pip
Copyright (c) 2025 Michael Zargham / Block Science. All rights reserved.
This repository is currently proprietary and not open source. No license is granted for use, modification, or distribution without explicit written permission.
We are actively researching the right balance between open source availability and commercial sustainability for this technology. If you are interested in using this framework, please reach out to us at info@block.science.
This repository and its contents may not be used for training machine learning models, large language models, or any AI/ML systems without explicit written permission. Automated scraping or crawling for AI training purposes is prohibited.
See LICENSE for full terms.
This repository was developed with assistance from Claude (Opus 4.5). All framework architecture, validation methodology, and approval decisions are original author work. The author maintains full responsibility for all content and attestations.