validate-consistency

What it does

Universal document consistency auditor. Runs deterministic drift checks across docs, code, tests, and CI, resolves conflicts through a per-fact-class authority registry (sot-map.yaml), and produces reports that structurally separate deterministic findings from advisory LLM-judged findings.

How it works

• Announce audit (Step 0).
• Step 1: Load the Authority Registry from the provided path or default to ~/000-projects/intent-os/sot-map.yaml. Read and print:
  • Authority registry: [path]
  • Fact classes registered: [n] — [list of class names]
  • If missing/unparseable, bootstrap mode is activated where every fact class is unowned.
• Step 2: Inventory Documentation Artifacts by scanning for: README(README.), CLAUDE.md, CHANGELOG/CHANGES, 000-docs/**/.md, docs//*.md, planning//*.md, VERSION/version.txt, CI workflows, and package manifests. Print a summary of presence:
  • Documentation artifacts found: ...
• Step 3: Run Drift Checks. For each applicable check, determine lane (Deterministic or LLM-judged) and whether a registry row exists. Execute checks only if input files exist; skip otherwise. Checks include: 3.1 Index vs Filesystem, 3.2 Version String Consistency, 3.3 README Commands vs CI Workflows, 3.4 CLAUDE.md Doc Table vs Actual Docs, 3.5 Stale Phase/Status Language, 3.6 Capability Claims vs Code, 3.7 Cross-Doc Fact Comparison, 3.8 Broken Cross-References, 3.9 Planning-vs-Implementation State.
• Step 4: Compile Report in a strict markdown structure, separating Deterministic Findings from Advisory Findings, with sections for each category and subcategory, and sections for unowned fact classes and bootstrap registry drafts when needed. Each finding includes severity, fact class, authority value, drifted claim, location, and whether it is auto-fixable.
• Step 5: Summary prints a one-line statement of audit completion.

When to use it

Use when checking documentation accuracy before a release, after major refactors, or when onboarding to a new codebase. Also invoked automatically by /release Phase 1.6.

What it can touch

The toolset includes Read, Glob, Grep, Bash(echo:), Bash(git:), Bash(diff:*). The agent uses these to read files, glob directory trees, grep for patterns, echo outputs, compare diffs, and inspect git history as part of drift checks.

Caveats

Deterministic findings can block a release; advisory findings are informational. If no registry row exists for a fact class, findings are labeled as unowned and require human adjudication. bootstrap mode emits unowned fact-class findings with drafted registry rows for human input.