Verification

<TrackedFiles paths="crates/supersigil-verify/src/**/*.rs" />

Verification is what makes Supersigil more than documentation. It is a graph checker that catches broken references, uncovered criteria, missing tests, and stale specs — automatically, on every commit.

What Verify Does

supersigil verify builds the full document graph and checks everything: cross-document references, coverage, test mappings, staleness, and cycles. This is the CI command.

Hard Errors

These are structural integrity failures detected during parsing and graph construction. They are always fatal and cannot be suppressed, overridden, or draft-gated:

Error	Description
broken_ref	Referenced document or fragment does not exist
duplicate_id	Two or more documents share the same ID, or duplicate component IDs within a document
missing_required_attribute	Component missing a required attribute (e.g., <Criterion> without id)
xml_syntax_error	Malformed XML inside a supersigil-xml fence
dependency_cycle	Circular dependency in <Task> chains or <DependsOn> chains

Caution

Hard errors prevent the graph from being constructed at all. A broken reference means the graph is inconsistent. A duplicate ID means the graph is ambiguous. These are never acceptable, even in draft documents.

Configurable Rules

These rules have built-in default severities that can be overridden in supersigil.toml:

Rule	Default	Description
missing_verification_evidence	error	Criterion has no verification evidence (no VerifiedBy, no plugin evidence)
missing_test_files	error	<VerifiedBy strategy="file-glob"> paths resolve to no files
invalid_verified_by_placement	error	<VerifiedBy> placed outside a <Criterion>
zero_tag_matches	warning	<VerifiedBy strategy="tag"> tag found no matching tests
status_inconsistency	warning	Tasks doc has completed tasks but stale status, or sibling design/requirements doc not promoted after tasks doc reaches done
stale_tracked_files	warning	Tracked files changed since the specified git ref
empty_tracked_glob	warning	<TrackedFiles> glob matches no files
orphan_test_tag	warning	Test file has a supersigil: tag not referenced by any spec
invalid_id_pattern	warning	Document ID does not match the configured id_pattern regex
plugin_discovery_failure	warning	Ecosystem plugin discovery failed
plugin_discovery_warning	warning	Ecosystem plugin discovery produced a warning
sequential_id_order	warning	Sequentially-numbered component IDs appear out of numeric order in the source
sequential_id_gap	warning	A numbered component ID sequence has missing entries (e.g. task-1, task-3 with no task-2)
incomplete_decision	warning	<Decision> has no <Rationale> child
orphan_decision	warning	<Decision> has no outward refs and is not referenced
missing_decision_coverage	off	Design document has no <Decision> referencing it
invalid_rationale_placement	warning	<Rationale> placed outside a <Decision>
invalid_alternative_placement	warning	<Alternative> placed outside a <Decision>
duplicate_rationale	warning	<Decision> has more than one <Rationale> child
invalid_alternative_status	warning	<Alternative> status is not rejected, deferred, or superseded
isolated_document	off	Document has no edges to or from any other document
empty_project	warning	No documents found matching configured paths

Severity Levels

Rules produce findings at four severity levels:

Level	Meaning	Effect
error	Fails verification	Non-zero exit code (1)
warning	Reported but does not fail	Exit code 2 when warnings are the worst severity
info	Informational	No effect on exit code
off	Suppressed entirely	Finding not emitted

Configuring Rules

Override rule severity in supersigil.toml under the [verify.rules] section:

supersigil.toml

[verify.rules]
missing_verification_evidence = "warning"   # default: error
isolated_document = "warning"               # default: off
zero_tag_matches = "error"                  # default: warning

You can also set a global strictness level that applies to all rules not explicitly overridden:

supersigil.toml

[verify]
strictness = "error"   # Promotes all warnings to errors

Severity Precedence

When multiple settings apply, this 4-level precedence chain resolves the effective severity:

1. Draft gating (highest) — status: draft suppresses configurable rules to info
2. Per-rule override — Explicit rule setting in [verify.rules]
3. Global strictness — The [verify] strictness setting
4. Built-in default (lowest) — The hardcoded default for each rule

Draft Gating

Documents with status: draft get relaxed verification. All configurable rules are suppressed to info level — they are still computed but they do not fail the build.

---
supersigil:
  id: payments/req/refunds
  type: requirements
  status: draft
---

Caution

Hard errors are never suppressed by draft gating. A broken reference is a broken reference, draft or not. Only configurable rules are affected.

When you change status from draft to any other value, the full rule set applies. This allows iterative authoring without CI friction.

Evidence Sources

A criterion is covered when the graph can resolve at least one evidence source for it — explicit <VerifiedBy> mappings, ecosystem plugin discovery, or both. All sources are merged before coverage is evaluated. See Evidence Sources for the full details on each source type.

Exit Codes

Code	Meaning
0	Clean — no errors, no warnings
1	Errors found
2	Warnings only (no errors)

Output Formats

supersigil verify supports three output formats:

# Colored terminal output (default)
supersigil verify --format terminal

# Machine-readable JSON
supersigil verify --format json

# Markdown table (useful for CI comments)
supersigil verify --format markdown

The JSON format includes the full findings list, summary counts, and optional evidence summary.

Staleness Detection

When tracked files change, supersigil verify --since <ref> flags the associated specs as stale:

supersigil verify --since main

For a standalone staleness check without full verification, use the affected command:

supersigil affected --since main

auth/req/login (specs/auth/req/login.mdx)
  glob: src/auth/**/*.rs
  changed: src/auth/handler.rs

1 document affected

Additional flags control the git diff behavior:

Flag	Effect
--committed-only	Only consider committed changes (ignore staged/unstaged)
--merge-base	Use merge-base for the diff (useful for PR branches)

CI Integration

See the CI Verification guide for complete GitHub Actions examples and practical policy for integrating verification into pull requests.