From 43a2a5e6e20bce3392f2b959425942e5e3930f09 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 10 Jun 2026 01:38:27 -0500 Subject: docs(verification): flag that enumerated lint/test gates skip new files A green check only covers the files the gate actually ran on. When a lint, test, or format gate uses a hand-maintained file list instead of a glob, a newly-added file is silently skipped and the gate still reports clean. Added a subsection naming the failure mode (a Makefile path list, a pre-commit files: regex, a CI matrix, a coverage include list) and the check it calls for: when you add a file, confirm each gate discovers it before trusting the green. --- claude-rules/verification.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/claude-rules/verification.md b/claude-rules/verification.md index 617c02c..0b0fda4 100644 --- a/claude-rules/verification.md +++ b/claude-rules/verification.md @@ -31,6 +31,14 @@ If you find yourself using these words, you haven't verified: Replace beliefs with evidence. Run the command. +## A Passing Gate Can Skip Your New File + +A green check only counts for the files the check actually ran on. When a lint, test, or format gate runs against an explicit, hand-maintained file list rather than a glob or auto-discovery, a newly-added file is silently skipped until someone adds its path by hand. The gate reports clean while never looking at the new file — a false pass that reads exactly like a real one. + +The failure mode isn't tool-specific. It fires anywhere a quality gate enumerates files instead of discovering them: a Makefile lint target listing paths, a pre-commit `files:` regex that doesn't match a new extension, a CI matrix with hardcoded paths, a coverage config with an explicit include list. + +So when you add a file, confirm the gates see it. Check whether each lint/test/format gate discovers files automatically or enumerates them, and if it enumerates, add the new path before trusting the green check. "Linter is clean" means nothing for a file the linter never ran on. + ## When You Cannot Verify Sometimes the verification command cannot run: the tool is absent, there is no network, a sandbox blocks it, or the environment is missing a dependency. A check that did not run must never be reported as a pass. "Unable to verify" is an honest, required outcome — not silence, and not an optimistic "should work." -- cgit v1.2.3