Use when designing, wiring, debugging, or being blocked by quality-gate infrastructure — git hooks, lint matrices, exception files, complexity gates, Stop hooks. Defines the three-tier latency topology, the vacuous-green problem (gates must prove they FIRED), exception-file hygiene, and gate failure UX. verification-ratchet defines WHAT the checks are; this skill defines how the machinery that runs them stays honest.
81%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Field origin: a 389-commit Rust workspace where every architectural rule acquired a mechanical gate — and where the three worst incidents were all the same incident: a green signal that proved nothing.
Green has a failure mode: the check that didn't run. Three independent field incidents, one rule:
--no-verify or a broken hook slipped through; check+tests stayed green
(they don't cover lints) while 20+ deny-level errors piled up across 9
crates.fail_on_skipped: an undefined step is a red
build, not a silent skip.The rule: every gate needs proof that it fired, not just absence of red. Consequences:
just verify: fmt-check + lint +
arch-lint + full tests + generated-docs build) run before declaring any
work done, "so drift cannot survive even a missing hook." Hooks are
convenience; the recipe is the contract.--no-verify. The sanctioned bypass exists but demands a paper
trail: "bypass with --no-verify and file a bead explaining why."verify_backlog_quality_gate.sh, across ~122 verify_<bead>.sh scripts).
"Fired" and "can fail" are different vacuities: a gate can run on every
commit and still be toothless if no input makes it red. Both must be
shown — that it ran, and that it bites.Gates are placed by cost, and the placement is documented in the hook header itself:
-D warnings,
complexity gate on staged files, direct dependency-rule checks
(cargo-metadata parsing — no compilation needed).just metrics,
just mutants), never in hooks.Advisory checks may ride in blocking hooks with || true — they print,
they never block, and the split (BLOCKING vs ADVISORY) is declared at the
top of the hook so nobody has to infer it.
Missing-tool policy: a hook check whose tool isn't installed skips silently — a contributor without the optional linter must not be unable to commit. The canonical aggregate gate and CI are where a missing tool is an error.
cargo metadata) — exact,
no build, no AST.use tokio but not tokio::fs::read(...) — fine for an advisory nudge,
dishonest as a blocker.Mechanical architecture checks verify structural consequences (dep
edges), never semantic premises (whether the label is true). A crate
can self-declare role = "domain", have zero deps, pass every gate — and
be an orchestrator. Two responses, use both:
Every project has one decision that is its reason for existing — the line
that, quietly reverted, deletes the point of the work. An amnesiac session
cannot be trusted to know which line that is, so name it mechanically: the
exact file:field (or symbol), the forbidden value, and a top-priority
gate that fails the build the moment it flips. Field incident: an agent
flipped concurrent_mode_default = false and reimplemented the serialized
locking the project existed to replace — an emergency session to revert
(frankensqlite AGENTS.md:263-285, since pinned as invariant INV-C1).
Cheapest insurance against the most expensive regression:
concurrent_mode_default == true; the domain crate stays
#![forbid(unsafe_code)]; whatever the actual point is).#[allow(lint, reason = "...")], never file-level blankets. The strict
config earns its keep — deny-level lints caught a real lock-contention
bug masked by a significant-Drop temporary.Every blocking failure prints: the rule in one sentence ("all arrows point inward"), the two legitimate fixes ("invert the dependency, or change the role"), and the sanctioned bypass with its paper-trail requirement. An agent hitting the gate cold must be able to act from the message alone — a bare exit 1 trains agents to bypass.
Negative tool decisions are recorded at the enforcement site: when a scanner is rejected from the hook, the hook comment names the rejection and the concrete false positives that earned it — so the next session doesn't re-add it, and the decision is re-litigatable on evidence.
A Stop hook that blocks turn-end on a broken build keeps the workspace always-buildable — and makes "hand the human a non-compiling hole" an illegal move. Two corollaries:
todo!() bodies
or stub types, never missing functions.igouss/gitweb-rs
9ef2429
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.