Command line#

Find the next review#

Start with the file or directory you are working on:

$ snob pending src/routes/admin.ts
$ snob pending src/routes/

pending lists the unsatisfied rules for those paths. Read each rule's description and review guidance to see what the review needs to establish. It also shows the policy file, the current state and the subject the claim must name. If a claim is stale, its reasons identify what no longer matches.

Leave out the paths to see the whole worklist. Add --all to include satisfied rules. Path selection filters the report you see; snob still evaluates the project and runs configured providers.

After reviewing, record a claim with the current subject and put its reference in the file's review file. There is no command to create claims yet; local claim files shows the format. Then check the project:

$ snob check

check lists each file that still needs attention and exits 1 when a must rule fails. Unsatisfied should rules warn; --deny-warnings makes those warnings fail the check too. consider rules are guidance and never require a claim. The outcome reference covers every state.

Use incremental adoption for existing review debt, and trusted revision checks in CI.

Commands and flags#

Command	Does	Exit
`snob init [--dry-run]`	Creates `snob.toml` and the policy and review directories if missing, then adds a `"changeme"` entry for every `must` or `should` rule a file's review file lacks. Keeps existing entries and comments and never writes a real reference.	0
`snob check [--deny-warnings]`	Evaluates every policy and lists each file that needs attention, so new files cannot hide in totals.	0 pass, 1 fail
`snob pending [PATH...] [--all]`	The review worklist: each unsatisfied rule with its description, review guidance and the subject a claim must name. `PATH` is a file or directory prefix; `--all` adds satisfied rules.	0

Every command takes --root DIR and --format human|json. check and pending also take:

--trusted-rev REV: judge the checkout against a revision the change cannot edit, usually the target branch. Its snob.toml is the configuration, its rules keep applying, and files it has that are gone need deletion reviews (freshness.md);
--config PATH: read snob.toml from a file instead. Policies still come from the checkout. This flag and --trusted-rev cannot be combined;
--strict: ignore [ratchet], so every obligation needs a claim.

check and pending run configured provider commands to fetch claims.

Invalid configuration, policy or review files, and any other error that stops snob from producing a report, exit 2 with messages on stderr. Reports go to stdout.

Outcomes#

Each rule on each file has a state, and its level decides the outcome:

State	Meaning	`must`	`should`	`consider`
`satisfied`	satisfied claim bound to the current subject	pass	pass	info
`missing`	no entry, or no review file	fail	warn	info
`unclaimed`	entry is `"changeme"`	fail	warn	info
`invalid_reference`	not `provider:id`	fail	warn	info
`unavailable`	unknown prefix, claim not found, provider failure, timeout or malformed claim (`kind`: `not_found`, `unavailable` or `protocol`)	fail	warn	info
`rejected`, `pending`, `revoked`	the claim's own status	fail	warn	info
`stale`	satisfied, but about a different subject (`reasons` lists each difference)	fail	warn	info

--deny-warnings turns warnings into failures. Under [ratchet], an unsatisfied must or should obligation identical to one at the adoption commit is exempt, which passes. consider rules are always info.

Human output#

check lists warnings and failures by file, then files covered only by coverage policies, then a summary:

12 files (2 without a review file), 30 rules: 25 passed, 1 exempt, 1 warned, 3 failed
2 suggestions to consider (guidance only; see `snob pending`)
snob check: FAILED

"Rules" counts must and should results only. "Without a review file" counts files that have no review file and at least one warning or failure. pending also lists consider rules, as INFO.

JSON output#

check --format json and pending --format json print a report with "schema": "snob.report.v3". For the same inputs the output is identical: files are sorted by path, rules follow policy path order and then declaration order, and there are no timestamps. Each rule result includes expected_subject, the subject a new claim has to name. init --format json prints the files it created and the entries it added.

With --trusted-rev, the report has trusted (rev and commit), each rule result has origin (both, trusted or checkout), and a deleted file has "deleted": true. Human output marks deleted files and rules that only one side defines. claim_refs lists every reference written for a rule, and claim_ref is the one that decided its state.