Design notes#

Decisions#

Strict TOML catches mistakes in files people and agents edit by hand. Unknown fields are errors, so a misspelt setting cannot silently do nothing.

Policy text lives in one place. Review files map rule ids to references, which avoids per-file copies of policy text. An id names the rule; its fingerprint identifies its definition. Renaming an id creates a rule, while rewording changes the fingerprint and makes existing claims stale. The configuration guide defines the fingerprint's inputs.

Providers retrieve stored claims. Keeping subject comparison in snob gives local files and external systems the same freshness rules. Provider integration is documented in claims and providers.

Evaluation is synchronous, with no async runtime or network access in snob itself. Sorted traversal and reports without timestamps make output deterministic.

Limitations#

Subjects cover whole files. Context uses declared globs, with no per-file templates such as {dir}/**; see context configuration.
The CLI has no command to draft or request a claim. The local review sequence explains the manual process.
Checking against the checkout alone permits rule weakening and drops deleted-file obligations. Use the trusted revision workflow in CI.
Raw-byte hashing makes line-ending conversions matter; see subjects. Candidate paths must be valid UTF-8, as described under file selection.
Command-provider tests and process-group cleanup are Unix-only.

Open: finer-than-file subjects#

Finer subjects are not implemented, and no approach has been chosen. The open questions are:

Which units need coverage? Today a unit is a file matched by match. Finer units (exports, symbols, routes) would most likely come from an external, language-aware extractor rather than parsing built into snob.
What does a claim bind to? File subjects would keep their shape; finer units need their own stable names and content identity.
What else makes a review stale? Today supporting files are declared through context.

Whatever is chosen, new units should show up individually as missing obligations, the way new files do now.