Verity — Multi-Language Spec-Drift Detector & Integrity Gate

"Code as Truth, Docs as Intent"
Verity is a deterministic, multi-language integrity gate that detects when documentation, task briefs, and architectural decision records (ADRs) drift from actual code implementations.

1. Why Verity

Narrative docs rot when they drift from code (spec drift). Verity binds specs to code via Git provenance (commit SHA) + normalized AST fingerprints immune to cosmetic formatting — deterministic, zero LLM cost.

2. Supported Languages

Scanners are immune to cosmetic reformatting. Two tiers:

Tier 1 — Battle-Tested

Full AST slicing; Verity dogfoods these on itself.

| Language / Framework | Extensions | Immunity | |---|---|---| | TypeScript / JavaScript | .ts, .tsx, .js, .jsx | Prettier, ESLint, Biome | | Vue SFC | .vue | Prettier, vue-format | | Astro | .astro | Prettier Astro plugin |

Tier 2 — Extended (partial-format guarantee)

Tokenizing scanners via the pluggable ParserDispatcher; partial-format guarantee only. Tier-2 parsers live alongside the Tier-1 core in src/core/parser/ (go.ts, jvm.ts, python.ts, …).

| Language | Extensions | Immunity | |---|---|---| | Rust | .rs | rustfmt | | Python | .py | black, ruff | | Go | .go | gofmt, goimports | | PHP | .php | PHP-CS-Fixer, Pint | | C# | .cs | dotnet-format | | Java | .java | google-java-format | | Kotlin | .kt | ktlint | | Ruby | .rb | rubocop | | Generic Fallback | * | General whitespace |

3. Installation

bun add -g @dimassetoid/verity   # or: npm install -g @dimassetoid/verity
bunx @dimassetoid/verity init --yes  # or run on-demand without installing

4. CLI Usage

| Command | Purpose | |---|---| | verity init [--yes] [--hook] [--mindset] [--skills] | Scaffold drift-core (docs/brief/ + INDEX.md, starter brief, pre-commit hook); --mindset/--skills are opt-in layer-2 adapters | | verity link <brief> <anchor...> [--inline] [--supersedes <old-brief>] | Seal AST fingerprints + Git HEAD SHA into brief frontmatter (or inline tag); --supersedes marks <old-brief> as Superseded | | verity unlink <brief> <anchor... \| --all> | Remove dead anchors when subjects are intentionally deleted | | verity check [--quick] [--sync-index] [--ci] [--affected f1,f2] [--force-fresh] [--unsealed] [--sarif [path]] [--hook] [--strict] | Audit drift; --quick cache-aware, --affected scoped, --force-fresh bypass cache, --unsealed lists anchorless Completed briefs, --sarif writes SARIF report, --ci fails on STALE/unsealed, --hook is pre-commit mode (staged-only, fails on STALE only) | | verity find [query] [--target f] [--category c] [--status s] [--month YM] [--limit n] | Fuzzy search briefs / reverse-lookup governing briefs for a file | | verity diff <code-file \| brief> [--baseline sha] | Semantic AST + git diff since baseline provenance | | verity preflight <brief> | Validity evidence for a brief (anchor health, rival overlaps, recent touches); human owns the go/no-go verdict | | verity serve | Run as MCP server over stdio, CLI-only (see §5) |

verity init --yes
verity link docs/brief/2026-09/feature/auth.md src/auth.ts#login src/components/Login.vue#submitForm
verity check --sync-index
verity check --unsealed

5. MCP Server

Verity runs as an MCP server over stdio JSON-RPC. Add to agent config (mcpServers):

{ "mcpServers": { "verity": { "command": "verity", "args": ["serve"] } } }

| Tool | Maps to | |---|---| | verity_check | check (OK/STALE as structured JSON) | | verity_link / verity_unlink | link / unlink | | verity_find / verity_diff | find / diff | | verity_preflight | preflight (validity evidence before implementing a brief) | | verity_sync_manifest | check --sync-index |

6. Pluggable Parsers

ParserDispatcher accepts custom CodeParser implementations at runtime — no core changes needed (see tests/dispatcher-pluggable.test.ts for a .sql example).

7. Testing

bun test         # full suite: parsers, dispatcher, CLI, MCP, drift detection
bun run build    # rebuild local dist/ (gitignored) for `node dist/verity.js` trials

8. License

MIT License © 2026 Dimas Seto