defect-to-guard

From one defect to a standing invariant

Ask the class question on every defect

On every defect you find or fix, ask: "could a GENERIC CI check have caught this whole CLASS without anticipating this specific error?" — and when the answer is yes, the output is a ## Proposed guards entry in the PR body, never a guard shipped in the same PR (root CLAUDE.md § Self-Critique and § Guard budget own that rule and the cost/benefit arithmetic the entry must show). The reflex:

1. Name the class the bug belongs to — a documented-but-unrouted subcommand, a parsed-but-undeclared flag, a referenced-but-undocumented env var, a feature whose lib code is written but never wired onto the live path, a portability divergence, a swallowed error.
2. Find whether a guard for that class already exists (cli-dispatch-sync, check-cli-flags-documented, check-env-documented, the layer-engagement self-test, check-exit-suppression) and, if so, why it didn't fire — a gap in the existing guard is itself the bug.
3. If none exists, prefer a check that iterates the SSOT and asserts the second copy, so it covers every future member for free and never names the instance (the anti-lockstep doctrine's forward form — a generic guard is an SSOT-completeness check, not a per-case assertion).
4. Pick the cheapest mechanism that can express the class, in this order: a type the compiler already tracks, then an AST rule, then a line or regex lint. The order tracks the false-positive rate. A type follows the value, so it never guesses at a shape; an AST rule sees structure, so it skips a match inside a string literal, a comment or a fixture; a text lint matches characters, so every legitimate use of those characters earns a disable comment, and each one hides the next real finding on its line. tsc --noEmit (pnpm check) covers the non-test *.mjs under scripts/, .claude/hooks/, .github/actions/, bin/lib/github-app/ and sbx-kit/, and nothing else there — tsconfig.json include names those globs and exclude drops **/*.test.mjs, so the Python and shell beside them get no type check at all. For a file it does cover, a provenance type needs no new machinery: brand the safe constructor's return value and make the dangerous sink accept only the brand. Reach for a line lint only when the class has no syntax to bind to — a banned word in prose, a path convention — and say in the proposal why. Show the mechanism, never just name it: the proposal carries the smallest snippet a reader can check — the signature that changes and the one line that now fails. "A provenance type" is a label; the three lines below are the thing, and a reviewer can judge them in ten seconds.