Validation & Inspection

These four commands are how you run Waypoint's coherence checks and explore the results. waypoint validate is the core daily command: it checks that every artifact passes its schema, that every cross-reference resolves, and that the artifact set is coherent with the code — and it emits a proof certificate (waypoint.proof.json) recording why the verdict holds. The other three read that certificate: verify audits a recorded result by hash, inspect opens it in an interactive TUI, and status gives a quick one-screen health check.

For the model behind the certificate — proof trees, primitives, tiers, and caching — see Validation in Concepts.

waypoint validate

Run structural, validation, and semantic checks over the project and emit a proof certificate.

waypoint validate [rule-name] [flags]

validate checks the project against three tiers:

• structural — artifact schema and graph checks (reference integrity, orphan detection, field invariants) and artifact↔code coherence (CLI-command coverage, API-endpoint coverage, import direction). No code is executed.
• behavioral — runs waypoint:generated test files via go test and records pass/fail as proof nodes.
• semantic — LLM-as-judge quality review (design coherence, DDD correctness, per-requirement acceptance).

It fails non-zero on any failure, which is what lets git hooks gate commits and pushes on it.

The optional rule-name positional argument restricts the run to a single named rule (pair it with --target to narrow to one artifact).

:::note v1 vs v2 As of Plan 039 the v2 proof-tree validator is the default. The legacy three-tier path is behind --v1 (deprecated; it prints a warning). The v2-relevant flags are --cache-stats, --dev, --no-cache, and --from-certificate. Remote validation is opt-in — it runs locally unless you pass --remote or --kinds, and on an HTTP 429 rate-limit it gracefully falls back to local checks. :::

Flags

Flag	Type	Default	Description
--tier	string	all	Categories to run: structural, validation, semantic, or all. Aliases: 1/schema → structural, 2/dag → structural+validation, 3/reviewer → semantic.
--target	string	""	Narrow validation to a specific artifact slug (use with a rule-name argument).
--staged	bool	false	Restrict semantic review to staged changes (used by the pre-commit hook).
--requirements-only	bool	false	Run only the per-requirement semantic evaluation.
--hook	string	""	Git-hook preset: pre-commit, pre-push, or commit-msg.
--json	bool	false	Emit structured JSON output.
--report	string	""	Write a structured JSON report to this file after the run.
--lint	string	""	Override lint config: off disables advisory checkers; c1,c2 disables specific ones. Overrides waypoint.json.
--verbose, -v	count	0	Increase detail: -v per-rule, -vv sub-checks, -vvv file paths.
--quiet, -q	bool	false	Suppress per-tier headers/timings (still prints the final summary and failures).
--engine	string	prolog	Reasoning engine: prolog (default, demand-driven proof tree) or gofunc (legacy).
--update-code-files	bool	true	Refresh manifest.CodeFiles (path → SHA-256 pins) before validation; needed for Prolog code-state tracking.
--cache-stats	bool	false	Emit a cache hit/miss + recompute summary at the end of the run.
--no-cache	bool	false	Skip certificate hydration: every primitive re-dispatches (audit / release-gate runs).
--from-certificate	string	""	Load this certificate path for hydration instead of the default waypoint.proof.json.
--dev	bool	false	Render the v2 proof tree in Dev mode (why / prevents / justification + primitive detail).
--v1	bool	false	Deprecated. Opt back into the legacy three-tier path. v2 is default.
--remote	bool	false	Force remote validation (hits the Waypoint service).
--local	bool	false	Force local validation (ignore saved credentials).
--kinds	string	""	Remote validation kinds, comma-separated (structural,deep,semantic, or all). Setting this forces remote.
--workflow	string	software	Workflow the (remote) validation runs against.
--scope	string	""	Optional path prefix to restrict the remote validation.

When to use: Every day, before committing or pushing, to confirm artifacts pass schema, cross-reference, and coherence checks (and optionally semantic review). Git hooks invoke it via --hook. It writes waypoint.proof.json plus the full certificate into .waypoint/certs/, which verify and inspect then consume.

# Full local validation
waypoint validate

# Just structural checks, with per-rule detail
waypoint validate --tier structural -v

# As a pre-commit gate over staged changes
waypoint validate --hook pre-commit --staged

# Machine-readable run that also writes a JSON report
waypoint validate --json --report /tmp/report.json

# Inspect cache hits/misses (see the cache model in Concepts → Validation)
waypoint validate --cache-stats

# Restrict to a single rule against one artifact
waypoint validate some-rule-name --target personas/alice

# Opt into remote validation
waypoint validate --remote --kinds all

waypoint verify

Verify a recorded proof certificate by its hash.

waypoint verify <hash> [flags]

verify re-checks a certificate produced by validate. The required <hash> matches the certificateHash field in waypoint.proof.json. Without --why it prints the tier summary; with --why <ruleID> it prints the full proof node — the evidence and the DependsOn chain — for that rule.

It reads the local proof store (.waypoint/certs/) first, then falls back to a summary-only reconstruction from waypoint.proof.json (in that fallback there are no nodes, so --why has nothing to show). The HMAC signature is checked only when WAYPOINT_PROOF_SIGNING_KEY is set.

Flags

Flag	Type	Default	Description
--why	string	""	Print the full proof node (evidence + DependsOn chain) for this ruleID.
--json	bool	false	Emit structured JSON output.

Exit codes: 0 valid; 1 tampered (signature mismatch) or invalid; 2 not found. Errors and usage are silenced so output stays clean for CI grepping.

When to use: To audit a recorded validation result, or to drill into why a specific rule passed or failed — including its dependency chain and any fix obligations.

waypoint verify 3f9a...c21
waypoint verify 3f9a...c21 --why requirement-coverage
waypoint verify 3f9a...c21 --json

waypoint inspect

Interactively explore a proof-tree certificate in a terminal UI.

waypoint inspect [flags]

inspect launches a TUI for browsing the proof tree from the last validate. The tree starts collapsed to its top-level sections; navigate with the arrow keys or hjkl, and toggle expansion with enter/space. Filter keys: f failed, p passed, v vacuous, r deferred, a all (reset). d toggles the detail panel and q quits.

It resolves the certificate from --cert if given, otherwise the waypoint.proof.json index in the current repo; if neither is present it tells you to run validate first.

Flags

Flag	Type	Default	Description
--cert	string	""	Path to a proof-certificate JSON file.

When to use: Visual triage of a large proof tree after validation — much faster than reading the raw JSON.

waypoint inspect
waypoint inspect --cert .waypoint/certs/3f9a...c21.proof.json

waypoint status

Print a one-screen summary of repo state and the last validation result.

waypoint status [flags]

status discovers the project from the current directory (walk-up to waypoint.json, like validate), lists the workflows, prints HEAD/branch, working-tree cleanliness and staged-change count, then runs the structural and validation tiers as a quiet background probe and prints per-tier pass/fail with up to five failing rule names per tier.

Flags

Flag	Type	Default	Description
--json	bool	false	Emit structured JSON (StatusReport: projectRoot, workflows, head, branch, clean, stagedChanges, passed, tiers, failures).

When to use: A quick health check of the repo plus whether validation currently passes, without the full validate output.

waypoint status
waypoint status --json