docassert

Unit testing for business documents. Validate structured Markdown documents (charters, BRDs, PRDs, risk registers, …) against a configurable audit standard: deterministic structural checks that gate a merge, plus optional AI-graded semantic checks that advise. Requirements trace end to end, and project status is derived from the documents rather than self-reported.

docassert is the reference implementation of PMO as Code — a vendor-neutral standard for running a PMO from version-controlled, declarative files. It implements the PMO as Code specification v0.8 and passes its conformance suite (73 cases) in CI.

Install

pipx install docassert          # recommended — installs the CLI in its own isolated env
# or:
pip install docassert
# with the AI advisory extra:
pip install "docassert[ai]"

Quickstart

docassert new project --code AUR --name "Aurora"   # anchor a project (auto-numbered id)
docassert new charter --project PRJ-001-AUR        # scaffold a charter into it
docassert validate documents/**/*.md  # unit-test your documents
docassert consistency                 # cross-document traceability + profile completeness
docassert status --index              # derived RAG per project
docassert pages --out _site           # a portfolio dashboard + a page per project

Config resolves local override → packaged default: docassert ships sensible defaults, and your repo's own criteria/ (or schema/, profiles/, consistency.yaml) wins when present. docassert init copies the defaults in so you can customize them — including the doc-to-pmo Claude skill into .claude/skills/, so Claude Code in your repo knows how to convert existing Word/PDF documents into testable docassert documents (faithfully — gaps are flagged as TODOs, never invented). The skill's source is skills/doc-to-pmo/SKILL.md.

Commands

Every document-reading command accepts --documents-dir (default documents/). The full flag-by-flag reference, and the 1.x stability guarantees (binding since 1.0.0), live in STABILITY.md. AI alignment grades at most alignment_limit links per run (default 25; set it in consistency.yaml, 0 = no cap) so API cost stays bounded on large graphs.

Document kinds

Twenty-one kinds, each a templates/<kind>.template.md + schema/<kind>.schema.json

• criteria/<kind>.criteria.yaml trio: project, charter, business-case, brd, prd, frnfr, user-story, test-cases, adr, risk-register, raci-stakeholder, qa-test-plan, data-migration-plan, release-cutover-plan, rollback-plan, hypercare-plan, runbook, operations, status-report, post-implementation-review, benefits-realization. Adding a kind is adding a trio — no code for the common cases.

Two tiers of checks

• Structural — deterministic, blocking. Required fields and sections, measurable success criteria, risks with owner + mitigation, resolving references, unique ids. Plain Python, reliable enough to gate a merge. Within this tier, integrity checks (malformed items, bad types, duplicate ids) block at any status, while completeness checks relax to advisory on status: draft and gate once a document is proposed — WIP is never punished.
• Semantic — AI-graded, advisory. Scored via the Anthropic API and posted to the PR — never blocking. Set ANTHROPIC_API_KEY to enable; skipped otherwise.

Privacy

Structural checks run entirely locally — no document content leaves your machine or CI runner. Semantic checks are the one exception: when ANTHROPIC_API_KEY is set, the graded excerpts (section text, linked item text) are sent to the Anthropic API for scoring. Without the key, semantic checks are skipped and nothing is sent anywhere. Alignment grading is capped at alignment_limit links per run (default 25). If your documents are confidential, run without the key or review Anthropic's data-usage policies first.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .

This repo ships example documents/ (four sample projects) that the test suite validates against.

The reference deployment

pmo-as-code-pipeline is a living example — sample projects, the gate on every pull request, and a published dashboard at c4g-john.github.io/pmo-as-code-pipeline. The standard's site is c4g-john.github.io/pmo-as-code.

License

Apache-2.0 — see LICENSE and NOTICE. © 2026 C4G Enterprises Inc.