Five disarming faults were measured silent at exit 0, indistinguishable from each
other and from a legitimate docs-only commit. All five now speak.
(b) A malformed declaration REFUSES rather than skips: no separator, empty pathspec,
empty command, or a pathspec git cannot resolve. The refusal names file, line number,
fault, the offending text, the expected form, and --no-verify — a gate that blocks
without saying why is replaced by habit within a week.
(e) instead of a flag, on the ruling's reasoning that a flag nobody sets is a
capability nobody has: the per-rule line prints in exactly the ambiguous case. A rule
ran, the existing lines already say so and nothing is added. No triggers file, this
block never runs, so no other repo gains noise. Rules declared and none matched is the
only case a reader cannot otherwise tell from a broken hook, so it is the only case
that gets a line. PRECOMMIT_VERBOSE adds per-rule detail for a suspect pathspec.
Two things the implementation found that the ruling did not specify. A triggers file
declaring no rules — comments-only or empty — left declared=0, so my first cut skipped
the report and those two rows stayed silent. That state is a disarmed hook wearing an
armed face: the file is present so the repo looks opted in, and every commit sails
through. It now reports rather than refuses, since refusing would block a legitimately
emptied file. And a rule that has never matched is honestly unknown, not passing and
not failing; the hook holds no history and does not imply one.
Matched-rule output is byte-identical to what REVIEWED-100's acceptance proved — the
split reproduces `IFS='|' read` exactly, including the retained leading space in the
display. One observable change: a docs-only commit still runs nothing but now says so.
Acceptance, all seven rows: control FIRED · typo REPORTED-no-match · no separator
REFUSED · empty command REFUSED · comments-only REPORTED-empty · empty file
REPORTED-empty · docs-only REPORTED-no-match. Red direction still refuses.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A35wiD55yRHj5U1ECZAX4t
core.hooksPath makes this hook global to every repo, which is why it is tracked
and travels — and why it must hold no repo knowledge. A repo opts in by
declaring `.precommit-triggers` at its root: staged pathspecs on the left, a
command on the right. If the staged diff touches a declared pathspec the command
runs, and a non-zero exit refuses the commit.
Three decisions worth stating rather than leaving to be rediscovered:
Path matching is delegated to `git diff --cached --name-only -- <pathspec>`
rather than reimplemented, so declarations use the pathspec syntax the repo's
users already know and globs behave as they do everywhere else in git.
The declaration file is read on fd 3, so a declared check that reads stdin
cannot swallow the remainder of the rules.
It is dependency-free by design — no yq, no python. A global convention that
needs a toolchain silently fails to travel to the next machine, and a check that
silently does not run is worse than no check, because its absence reads as a
pass. This is a deliberate departure from the YAML used by data that python
tools consume.
Scope: this is a tripwire, not an enforcement boundary. --no-verify steps over
it, and the message says so. It is worth having because the failure mode it
addresses is forgetting, not evading.
First consumer: studium-engine, where a corpus edit invalidates engine fixtures.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A35wiD55yRHj5U1ECZAX4t
On macOS /dev/tty always exists, so '[ -e /dev/tty ]' passed even in agent
harnesses/CI with no controlling terminal — the subsequent read then died
with ENXIO ('Device not configured') and blocked the commit instead of taking
the hook's own non-interactive branch. Probe with '( : < /dev/tty )' — the
exact operation that fails. Both prompt sites fixed; the deliberate asymmetry
preserved (debug keywords warn-and-proceed; secrets fail closed). Verified
both paths from a non-TTY context. Surfaced via the be a11y-gate commit
bypass logged in today's ledger.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The prior hook piped staged filenames through xargs grep, scanning the
entire current file content. This produced false positives whenever a
modified file contained pre-existing TODO/FIXME/XXX markers anywhere —
even if the staged change did not touch those lines. Six --no-verify
bypasses accumulated in two days as a result: the commits were not
introducing any new TODO markers; they simply modified files that had
template or documentary use of those tokens.
Fix:
- Collect added lines from the staged diff once (git diff --cached -U0,
filtered to lines starting with + and excluding +++ file headers)
- Scan that set for debugging-keyword and secret patterns
- Pre-existing content in modified files no longer triggers the hook
Also:
- Show the matched lines when warning (previously the hook said
"Found debugging keywords" without indicating which)
- Read from /dev/tty explicitly so interactive prompts work even when
stdin is closed by the commit driver
- Non-interactive contexts: proceed on TODO warnings (least invasive);
block on secret matches (most invasive); in both cases state clearly
what's happening
--no-verify is used on this commit only because the hook file itself
contains the literal scan patterns (TODO:, FIXME:, XXX:) inside its
grep regex. The new hook's scan of added lines therefore matches its
own source at commit time — a one-time bootstrap issue. This should be
the LAST --no-verify in this pattern. Future commits with legitimate
no-TODO-marker changes will pass cleanly; future commits that genuinely
introduce new TODO markers will correctly prompt for confirmation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
