docassert 0.1.0__py3-none-any.whl

docassert/__init__.py

@@ -0,0 +1,8 @@
+"""docassert — unit testing for business documents.
+
+Validate structured Markdown business documents against a configurable audit
+standard: deterministic structural checks that gate a merge, plus optional
+AI-graded semantic checks that advise.
+"""
+
+__version__ = "0.1.0"

docassert/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

docassert/_data/consistency.yaml

@@ -0,0 +1,51 @@
+# Cross-document traceability rules.
+#
+# The chain: BR (business req) ◀ PR (product req) ◀ FR/NFR (spec)
+#            PR ◀ AC (acceptance criterion) ◀ TC (test case)
+#
+# Broken references are ALWAYS blocking. The rules below (required links and
+# coverage) block only when the owning document is `status: approved`, so
+# work-in-progress is never punished.
+
+# Each downstream item prefix must declare at least one target via this
+# relation (else it's an orphan).
+required_links:
+  PR: traces        # a product requirement must trace to a business requirement
+  FR: traces        # a functional requirement must trace to a product requirement
+  NFR: traces       # a non-functional requirement must trace to a product requirement
+  US: traces        # a user story must trace to a product requirement
+  AC: verifies      # an acceptance criterion must verify a requirement
+  TC: tests         # a test case must test an acceptance criterion
+
+# Every parent item (by prefix) must be covered by >=1 child of `by_prefix`
+# linking to it via `relation`.
+coverage:
+  - parent: BR
+    relation: traces
+    by_prefix: PR
+    label: business requirement covered by a product requirement
+  - parent: PR
+    relation: verifies
+    by_prefix: AC
+    label: product requirement covered by an acceptance criterion
+  - parent: AC
+    relation: tests
+    by_prefix: TC
+    label: acceptance criterion covered by a test case
+
+# Advisory AI alignment: for each relation, judge whether the child genuinely
+# fulfils the parent it links to. Never blocks.
+alignment:
+  - relation: traces
+    prompt: >
+      Judge whether the CHILD requirement genuinely refines or implements the
+      PARENT requirement it traces to, rather than being merely topically
+      related. Penalise links that don't actually follow from the parent.
+  - relation: verifies
+    prompt: >
+      Judge whether the acceptance criterion actually verifies the requirement
+      it targets: testable, and covering the requirement's intent.
+  - relation: tests
+    prompt: >
+      Judge whether the test case actually exercises the acceptance criterion
+      it targets.

docassert/_data/criteria/adr.criteria.yaml

@@ -0,0 +1,36 @@
+# Audit criteria for the Architecture Decision Record (ADR) kind.
+#
+# Modeled as a decision log: one document holds many **ADR-###** decision items,
+# each optionally affecting a requirement. (Distinct from the portfolio-level
+# "Decision" concept.)
+kind: adr
+
+required_sections:
+  - Overview
+  - Decisions
+
+item_sections:
+  - section: Decisions
+    prefix: ADR
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/adr.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Every decision is a valid **ADR-###** item.
+  - id: adr-items-have-status
+    type: structural
+    blocking: true
+    description: Every decision declares a valid Status (proposed | accepted | superseded | deprecated | rejected).
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/benefits-realization.criteria.yaml

@@ -0,0 +1,30 @@
+# Audit criteria for the Benefits Realization kind.
+kind: benefits-realization
+
+required_sections:
+  - Overview
+  - Benefits
+  - Measurement
+  - Realized Value
+
+# Bullets in these sections must state a measurable threshold.
+measurable_sections:
+  - Benefits
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/benefits-realization.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: measurable-items
+    type: structural
+    blocking: true
+    description: Every benefit states a measurable target.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/brd.criteria.yaml

@@ -0,0 +1,30 @@
+# Audit criteria for the Business Requirements Document (BRD) kind.
+kind: brd
+
+required_sections:
+  - Purpose
+  - Business Requirements
+  - Out of Scope
+
+# Sections whose bullets are traceable items.
+item_sections:
+  - section: Business Requirements
+    prefix: BR
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/brd.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Every Business Requirement is a valid **BR-###** item.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/business-case.criteria.yaml

@@ -0,0 +1,23 @@
+# Audit criteria for the Business Case kind.
+kind: business-case
+
+required_sections:
+  - Problem Statement
+  - Options Considered
+  - Recommendation
+  - Costs
+  - Benefits
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/business-case.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/charter.criteria.yaml

@@ -0,0 +1,73 @@
+# Audit criteria for the Charter document kind.
+#
+# This file is the configurable contract for what "passing" means. Edit it to
+# tune your organisation's standard without touching the validator code.
+#
+#   type:     structural  -> deterministic Python check (always reliable)
+#             semantic     -> AI-graded rubric check (Anthropic API)
+#   blocking: true         -> a failure fails CI and blocks the PR merge
+#             false        -> a failure is reported as advisory only
+#
+# Policy (confirmed): structural checks block; semantic checks advise.
+
+kind: charter
+
+required_sections:
+  - Objective
+  - Success Criteria
+  - Scope
+  - Milestones
+  - Risks
+  - Approval
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is present and valid against schema/charter.schema.json.
+
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+
+  - id: measurable-success-criteria
+    type: structural
+    blocking: true
+    description: Every Success Criteria bullet states a measurable threshold (number, %, currency, or date).
+
+  - id: risks-have-owner-and-mitigation
+    type: structural
+    blocking: true
+    description: Every Risks bullet names an Owner and a Mitigation.
+
+  - id: dates-consistent
+    type: structural
+    blocking: true
+    description: Dates parse and the target date is on or after the created date.
+
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.
+
+  - id: objective-is-specific
+    type: semantic
+    blocking: false
+    pass_threshold: 0.7
+    prompt: >
+      You are auditing a project charter's Objective section. Judge whether it
+      states a specific, outcome-oriented goal a reader could hold the team
+      accountable to — not a vague aspiration or a restatement of the project
+      name. Reward concrete outcomes and measurable intent; penalise generic
+      filler ("drive synergies", "enhance capabilities").
+
+  - id: success-criteria-verifiable
+    type: semantic
+    blocking: false
+    pass_threshold: 0.7
+    prompt: >
+      You are auditing a project charter's Success Criteria. Judge whether each
+      criterion could be objectively verified by an independent third party
+      after the fact — i.e. it names a metric and a threshold, not a feeling.
+      Penalise criteria that are subjective or unmeasurable.

docassert/_data/criteria/data-migration-plan.criteria.yaml

@@ -0,0 +1,28 @@
+# Audit criteria for the Data Migration Plan kind.
+kind: data-migration-plan
+
+required_sections:
+  - Scope
+  - Source Systems
+  - Field Mapping
+  - Validation
+  - Cutover
+  - Rollback
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/data-migration-plan.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: mapping-table
+    type: structural
+    blocking: true
+    description: The Field Mapping section contains a mapping table.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/frnfr.criteria.yaml

@@ -0,0 +1,31 @@
+# Audit criteria for the Functional / Non-Functional Requirements kind.
+kind: frnfr
+
+required_sections:
+  - Overview
+  - Functional Requirements
+  - Non-Functional Requirements
+
+item_sections:
+  - section: Functional Requirements
+    prefix: FR
+  - section: Non-Functional Requirements
+    prefix: NFR
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/frnfr.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Functional requirements are **FR-###**, non-functional are **NFR-###**.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/hypercare-plan.criteria.yaml

@@ -0,0 +1,27 @@
+# Audit criteria for the Hypercare Plan kind.
+kind: hypercare-plan
+
+required_sections:
+  - Overview
+  - Support Window
+  - Severity Levels
+  - Escalation
+  - Exit Criteria
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/hypercare-plan.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: measurable-exit-criteria
+    type: structural
+    blocking: true
+    description: Every hypercare exit criterion states a measurable threshold.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/post-implementation-review.criteria.yaml

@@ -0,0 +1,24 @@
+# Audit criteria for the Post-Implementation Review kind.
+kind: post-implementation-review
+
+required_sections:
+  - Summary
+  - Outcomes vs Objectives
+  - What Went Well
+  - What Could Improve
+  - Lessons Learned
+  - Follow-up Actions
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/post-implementation-review.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/prd.criteria.yaml

@@ -0,0 +1,31 @@
+# Audit criteria for the Product Requirements Document (PRD) kind.
+kind: prd
+
+required_sections:
+  - Overview
+  - Product Requirements
+  - Acceptance Criteria
+
+item_sections:
+  - section: Product Requirements
+    prefix: PR
+  - section: Acceptance Criteria
+    prefix: AC
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/prd.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Product Requirements are **PR-###** items; Acceptance Criteria are **AC-###** items.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/project.criteria.yaml

@@ -0,0 +1,32 @@
+# Audit criteria for the Project anchor kind.
+#
+# A `project.md` sits at the root of each documents/PRJ-NNN-CODE/ folder and
+# declares that project's canonical identity. The registry (projects.yaml) and
+# the per-project pages are derived from these anchors.
+
+kind: project
+
+required_sections:
+  - Overview
+  - Scope
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is present and valid against schema/project.schema.json.
+
+  - id: project-id-format
+    type: structural
+    blocking: true
+    description: The id is PRJ-NNN-CODE and its CODE tail equals the `code` field.
+
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The project id is unique across documents/.

docassert/_data/criteria/qa-test-plan.criteria.yaml

@@ -0,0 +1,27 @@
+# Audit criteria for the QA / Test Plan kind.
+kind: qa-test-plan
+
+required_sections:
+  - Scope
+  - Test Approach
+  - Environments
+  - Entry Criteria
+  - Exit Criteria
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/qa-test-plan.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: measurable-exit-criteria
+    type: structural
+    blocking: true
+    description: Every exit criterion states a measurable threshold.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/raci-stakeholder.criteria.yaml

@@ -0,0 +1,24 @@
+# Audit criteria for the RACI / Stakeholder Register kind.
+kind: raci-stakeholder
+
+required_sections:
+  - Stakeholders
+  - RACI Matrix
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/raci-stakeholder.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: raci-one-accountable
+    type: structural
+    blocking: true
+    description: Every activity in the RACI Matrix has exactly one Accountable (A) role.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/release-cutover-plan.criteria.yaml

@@ -0,0 +1,30 @@
+# Audit criteria for the Release / Cutover Plan kind.
+kind: release-cutover-plan
+
+required_sections:
+  - Overview
+  - Pre-Cutover Checklist
+  - Cutover Steps
+  - Verification
+  - Rollback Trigger
+
+steps_sections:
+  - Cutover Steps
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/release-cutover-plan.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: numbered-steps
+    type: structural
+    blocking: true
+    description: Cutover Steps is an ordered list of at least two numbered steps.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/risk-register.criteria.yaml

@@ -0,0 +1,32 @@
+# Audit criteria for the Risk Register kind.
+kind: risk-register
+
+required_sections:
+  - Overview
+  - Risks
+
+item_sections:
+  - section: Risks
+    prefix: RISK
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/risk-register.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Every risk is a valid **RISK-###** item.
+  - id: risk-items-complete
+    type: structural
+    blocking: true
+    description: Every risk states a Probability, Impact, Owner, and Response.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/rollback-plan.criteria.yaml

@@ -0,0 +1,29 @@
+# Audit criteria for the Rollback Plan kind.
+kind: rollback-plan
+
+required_sections:
+  - Overview
+  - Trigger Conditions
+  - Rollback Steps
+  - Verification
+
+steps_sections:
+  - Rollback Steps
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/rollback-plan.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: numbered-steps
+    type: structural
+    blocking: true
+    description: Rollback Steps is an ordered list of at least two numbered steps.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/runbook.criteria.yaml

@@ -0,0 +1,30 @@
+# Audit criteria for the Runbook kind.
+kind: runbook
+
+required_sections:
+  - Overview
+  - Prerequisites
+  - Procedures
+  - Monitoring
+  - Escalation
+
+steps_sections:
+  - Procedures
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/runbook.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: numbered-steps
+    type: structural
+    blocking: true
+    description: Procedures is an ordered list of at least two numbered steps.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/status-report.criteria.yaml

@@ -0,0 +1,26 @@
+# Audit criteria for the Status Report kind.
+kind: status-report
+
+required_sections:
+  - Summary
+  - Progress
+  - Risks & Issues
+  - Next Steps
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid (includes a period date and a green/amber/red rag).
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: references-risk
+    type: structural
+    blocking: true
+    description: The Risks & Issues section cites at least one RISK-### from the register.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.

docassert/_data/criteria/test-cases.criteria.yaml

@@ -0,0 +1,28 @@
+# Audit criteria for the Test Cases kind.
+kind: test-cases
+
+required_sections:
+  - Overview
+  - Test Cases
+
+item_sections:
+  - section: Test Cases
+    prefix: TC
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/test-cases.schema.json.
+  - id: required-sections
+    type: structural
+    blocking: true
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Every test case is a valid **TC-###** item that tests an acceptance criterion.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across documents/.