How snob checks itself#

This repository is checked by snob, and it adopted snob the way an existing codebase would: it pinned the code as it was, and from then on every change needs its reviews. That is not a certification of the code. Most of it was written before the rules and has not been reviewed against them.

1. Baseline what already exists#

The policies in snob/policies/ were committed with a review file for every matching file, each entry still "changeme". The commit that added them is pinned in snob.toml:

# snob.toml
[ratchet]
since = "0123456789abcdef0123456789abcdef01234567"   # the adoption commit, in full

Every obligation that existed unchanged at that commit now passes as exempt. That is the inherited debt: snob pending lists it as EXEMPT, and it can be paid off one review at a time.

Pinning the commit edited snob.toml, and the coverage policy covers every file, so the first post-baseline review is snob.toml's own: a reviewer, person or agent, reads the change and records the claim. The gate never writes semantic claims.

2. Every change needs its reviews#

A file edited after the baseline, a new file, or a reworded rule loses its exemption. A few of the rules that then apply:

snob pending <file> prints a file's checklist and the subject a claim must name. The reviewer records a local: claim in snob/claims/ and points the review file at it. The full list of policies is in the reference below.

3. Automated checks leave receipts, not judgments#

Some rules only ask whether a check ran and passed. scripts/gate.sh records those itself, as auto-* claims, after every step of a stage passed:

A receipt is bound to the inputs of its check (sources, lockfiles, toolchain files, the gate script), so changing any of them needs a new run. Semantic rules are never bound to a receipt: tests/dogfood.rs fails if a review file points one at an auto-* claim. Receipts are gitignored; CI produces its own.

4. Pull requests are judged by the target branch#

CI checks out full history and runs, for a pull request,

$ scripts/gate.sh all --trusted-rev "origin/$GITHUB_BASE_REF"

so the target branch's snob.toml, policies and ratchet pin apply. A pull request cannot move its own baseline or weaken a rule it is judged by. Other branches and tags are judged by the default branch; the default branch is checked as committed, so it must only change through reviewed pull requests.

Reference#

The gate#

$ scripts/gate.sh                     # stable, msrv, site, then snob check
$ scripts/gate.sh all --trusted-rev REV   # the same, judged by REV's configuration
$ scripts/gate.sh stable              # pinned toolchain: fmt, clippy -D warnings, test, doc -D warnings
$ scripts/gate.sh msrv                # cargo +<rust-version> test --locked
$ scripts/gate.sh site                # docs site: npm ci --ignore-scripts, npm run build

Each stage deletes its old receipt, notes the subject snob expects, runs, and writes snob/claims/auto-gate.claim.toml, auto-msrv.claim.toml or auto-site.claim.toml only if every step passed (the script stops at the first failure) and the subject did not change meanwhile. Receipts are written by examples/record_claim.rs with snob's own TOML serializer; each says it is automated and records the tool versions. The gate refuses to run if rustc is not the pinned toolchain or the declared minimum, or if node is not the exact version in docs-site/.node-version.

The site stage needs that Node version with its bundled npm, and network access for npm ci. Its receipt is bound to the lockfile, Node pin, TypeScript and Vite config, site source and assets, and the README and docs the site imports. The docs-site/package.json review file references it as local:auto-site.

Trusted runner. The gate refuses to run with variables set that change what cargo, rustc, rustdoc, Clippy, node or npm do (RUSTFLAGS, RUSTDOCFLAGS, RUSTC*, RUSTDOC, RUSTUP_TOOLCHAIN, CLIPPY_*, CARGO_* other than CARGO_HOME, CARGO_TARGET_DIR, CARGO_TERM_*, CARGO_INCREMENTAL, CARGO_NET_* and CARGO_HTTP_*, NPM_CONFIG_*, npm_config_*, NODE_OPTIONS and NODE_PATH), or with a Cargo config file outside the repository. npm runs with no user or global configuration, so only the repository decides its registry and settings, and with install scripts disabled. Beyond that the machine is trusted: the gate cannot detect modified tool binaries, a dishonest runner or edits made after it finishes. An auto-* receipt means "this machine ran the gate", nothing more.

Tooling configuration#

rust-quality on Cargo.toml keeps reviews of configuration apart from receipts of runs, so each goes stale for its own reasons:

• toolchain-and-lints (review): unsafe_code forbidden; Clippy all and pedantic plus chosen restriction lints, never the restriction or nursery groups; rustdoc link lints; rust-version; rust-toolchain.toml pins an exact release; rustfmt defaults; no Cargo config adding flags or aliases.
• gate-config (review): scripts/gate.sh runs every check with failures fatal, verifies toolchains, refuses untrusted overrides and binds receipts correctly; CI runs it on an approved Blacksmith runner.
• gate-passed and msrv-passed: the receipts above.

Editing Cargo.toml invalidates all four. Editing rust-toolchain.toml invalidates the toolchain review and the stable run. Code edits invalidate only the runs. Disabling a gate step invalidates the gate review and both runs. tests/dogfood.rs has a test for each case.

Lint exceptions in code are code. tests/dogfood.rs scans every .rs file and rejects an exception that targets a lint group or a guard lint, applies to a whole module (one listed dead_code exception for shared test helpers aside), is conditional (cfg_attr) or has no reason. The same file has tripwires for the lint table, the toolchain pin, the gate's commands and failure handling, CI's trusted base, the release workflow and the CI runner labels. They catch obvious weakening and do not replace the reviews.

Policies#

coverage/policy-coverage asks of each file whether the right policies cover it; policies/coverage-intent asks of each policy whether it matches the right files. Adding a file does not re-open every policy's review: the new file's own coverage review asks the question.