veritas

veritas is a CLI-first adversarial verification harness for AI-written and AI-modified software.

It answers the question ordinary test runs often miss:

Would the current tests catch the kinds of subtle mistakes an AI coding agent is likely to make?

veritas maps changed code to verification targets, generates reviewable harnesses, runs scoped tests, fuzzing, mutation probes, and coverage collection under budgets, then writes CI-friendly reports and AI-ready feedback.

The default path is deterministic and does not call an LLM. An optional external planner hook can be enabled for AI-assisted planning while veritas still owns execution scope, budgets, and artifact writes.

Install

From crates.io, after release:

cargo install veritas-cli --locked

From the Git repository:

cargo install --git https://github.com/Jacobious52/veritas veritas-cli --locked

For local development:

git clone https://github.com/Jacobious52/veritas.git
cd veritas
cargo build --workspace
cargo run -p veritas-cli -- scan

Optional tools:

# Go verification
go version

# Rust coverage, only used when coverage_enabled = true
cargo install cargo-llvm-cov

Quick Start

Use veritas on a changed branch:

veritas review-ai
veritas verify --changed --profile ci
veritas report --format markdown

Verify a specific target:

veritas verify --lang rust --target src/lib.rs
veritas verify --lang go --target ./pkg/invoice

Explain and promote findings:

veritas explain <finding-id>
veritas promote-repro --dry-run
veritas accept-baseline --id <finding-id>
veritas cleanup

Documentation

• AI Agent Guide: copy-paste instructions and review loop for coding agents.
• Production Guide: large-repo Go/Rust operation, budgets, CI policy, and host safety.
• Architecture: workspace layout, plugin contract, artifacts, and planner model.
• Confidence Guide: fixture tiers, seeded examples, and external canaries.
• Releasing: crates.io publishing through GitHub Actions.

CLI Surface

veritas scan
veritas review-ai
veritas verify --changed
veritas verify --changed --profile ci
veritas verify --lang rust --target path/to/file.rs
veritas verify --lang go --target ./pkg/foo
veritas generate --kind property --target path
veritas generate --kind fuzz --target path
veritas run
veritas report --format markdown
veritas report --format sarif
veritas report --format junit
veritas explain <finding-id>
veritas promote-repro
veritas promote-repro --index 0
veritas accept-baseline --id <finding-id>
veritas accept-baseline --all
veritas cleanup
veritas cleanup --dry-run

Capabilities

Changed-target verification:

• reads git diffs, staged changes, and untracked files
• maps changed lines to discovered Rust/Go symbols when line ranges are available
• scopes package commands to changed packages and selected reverse dependencies where graph data exists
• writes AI review artifacts with change digests and verification guidance

Rust verification:

• detects packages and virtual workspaces through Cargo.toml
• discovers public free functions and public methods with Tree-sitter
• writes package-local proptest integration harnesses for supported public free functions
• runs cargo test --all-targets with configurable jobs, test threads, command timeouts, and optional systemd scope limits
• runs AST-scoped mutation probes and reports surviving mutants
• collects cargo llvm-cov --summary-only when enabled
• writes Rust symbol graph artifacts under .veritas/symbol_graph/

Go verification:

• detects one or more go.mod roots
• discovers exported functions and methods with Tree-sitter
• builds package graphs with go list -json ./...
• runs scoped go test commands for selected packages plus configurable reverse dependencies
• discovers handwritten and generated fuzz targets
• writes testing.F fuzz harnesses for exported free functions with supported Go fuzz parameter types
• runs relevant go test -run=^$ -fuzz=... targets within caps and timeouts
• applies build tags to Go list, test, fuzz, coverage, and mutation commands
• runs AST-scoped mutation probes for comparisons, nil/error branches, return defaults, and domain-labeled risk surfaces
• writes package graph, package-awareness, and symbol graph artifacts

Reports and artifacts:

• renders Markdown, JSON, SARIF 2.1.0, and compact JUnit XML
• saves the latest report to .veritas/report.json
• writes API signature baselines and accepted finding baselines
• writes coverage feedback, mutation feedback, repro notes, candidate verification patches, and promotion notes
• cleans generated artifacts with veritas cleanup

CI behavior:

• veritas verify --profile ci implies --changed
• CI profile disables full coverage, tightens package/fuzz/mutation/time caps, and enables policy-based failure on error severity by default
• policy filters can select severity, language, artifact kind, and target risk
• accepted finding IDs support new-findings-only CI behavior

Config

Create veritas.toml or .veritas.toml in the target repo:

[veritas]
budget_seconds = 120
write_generated_tests = true
fail_on_generated_test_failure = true
fail_on_findings = false

[planner]
mode = "deterministic"
# mode = "external_llm"
# command = "my-veritas-planner"
# fail_on_error = false

[policy]
fail_on_severity = "error"
fail_on_languages = []
fail_on_artifact_kinds = []
fail_on_target_risks = []

[plugins.rust]
property_framework = "proptest"
command_timeout_seconds = 120
coverage_enabled = false
coverage_timeout_seconds = 120
cargo_jobs = 1
test_threads = 1
systemd_scope = false
memory_max = "4G"
cpu_quota = "200%"

[plugins.go]
fuzz_seconds = 10
fuzz_existing = true
coverage_enabled = true
reverse_dependency_depth = 1
max_fuzz_targets = 20
command_timeout_seconds = 120
max_packages = 64
max_mutants = 8
build_tags = []

For shared machines, keep Rust coverage disabled unless needed and enable systemd scope limits:

[plugins.rust]
coverage_enabled = false
systemd_scope = true
cargo_jobs = 1
test_threads = 1
memory_max = "4G"
cpu_quota = "200%"

Development

Run the workspace checks:

cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Run fixture checks:

cargo run -p veritas-cli -- scan --root fixtures/sample-rust
cargo run -p veritas-cli -- verify --root fixtures/sample-rust --lang rust --target src/lib.rs
cargo run -p veritas-cli -- cleanup --root fixtures/sample-rust --dry-run
cargo run -p veritas-cli -- verify --root fixtures/rust-workspace --lang rust --target .
cargo run -p veritas-cli -- scan --root fixtures/sample-go
cargo run -p veritas-cli -- verify --root fixtures/sample-go --lang go --target .
cargo run -p veritas-cli -- verify --root fixtures/go-multimodule --lang go --target services/billing/pkg/invoice

Run the richer example beds:

cargo test --manifest-path examples/rust-invoice/Cargo.toml
cargo run -p veritas-cli -- verify --root examples/rust-invoice --lang rust --target src/lib.rs
(cd examples/go-invoice && go test ./...)
cargo run -p veritas-cli -- verify --root examples/go-invoice --lang go --target .

The example projects intentionally contain hidden assumptions while their handwritten tests pass, so they are useful for validating generated property/fuzz artifacts and report output.

Run external canary smoke checks when you want confidence against real pinned repositories:

./scripts/run-canaries.sh smoke