Two-Tier Law in a Commit Hook at KotaPortal
A commit-hook script keeps two tiers of law: broken test-marker claims block the commit, while risky surfaces like auth paths or destructive migrations only earn a logged warning.
TL;DR
The commit script has two tiers: a test marker like "characterization" hard-blocks the commit unless an exact comment line is present, while risky surfaces such as auth code, destructive migrations, or dangerouslySetInnerHTML only log a warning. Hard-blocking everything would kill velocity, and hooks can be bypassed with --no-verify. The goal is raising the cost of carelessness, not building a wall.
That night I nearly lost a commit to a single word: characterization. I ran the commit command against a test file that mentioned the word, and the terminal printed an error that killed the commit instantly. The message demanded one exact comment line, not good intentions.
My first assumption was wrong. I thought review_gate.sh worked as an absolute gatekeeper that would block every change containing risky keywords or incomplete comments. In reality the mechanism is not black and white. The script enforces two tiers of law: violations of marker language are punished, while risky code surfaces only light a warning lamp — a design that balances development speed against code safety.
Hard Block for Test Markers
The check_markers function scans staged files under the API and frontend test directories. If any added line mentions "characterization" (case-insensitive) but does not carry the exact literal // characterization: current behavior, owner decision pending, the commit is rejected. The change surface the script inspects is extracted with git diff --cached -U0 combined with a grep extraction pattern [2]. That pattern guarantees only added lines are evaluated, which makes the check pipeline deterministic, grounded in the grep exit status documented in the official manual [4][6]. Replacing free-text claims with one exact literal turns "characterization" into a machine-verifiable condition.
Soft Warning for Risky Surfaces
The warn_triggers function handles a different scenario: it never blocks a commit because it always returns zero. It checks two conditions. First, whether the review coverage trailer value is below the code+security level, with the values none, code-only, or code+security. Second, whether the staged change touches specific trigger surfaces: authentication paths, middleware, userauth, mediaadmin, shared storage, openapi.yaml, up to the frontend middleware. The script also detects destructive migrations containing the keywords drop, delete from, or rename, plus the use of dangerouslySetInnerHTML in the frontend — an inherently dangerous XSS surface [5].
When both conditions hold, the script appends a warning line to the WARN_LOG audit file with the timestamp, the coverage value, and the hits, then prints it to stderr. Secure code review must be woven into the software development lifecycle [3]. The warning line keeps risky changes from slipping through without an audit trail that must be cleared before the push.
Why the Two-Tier Approach Makes Sense
Hard-blocking every change that touches the authentication layer or the database migrations would paralyze the team's velocity. A commit hook can by design be bypassed with the --no-verify flag by a developer who intends to do so [1]. The real purpose of the tool is not to stop determined violators, but to raise the cost of carelessness.
Separating the veto-power check_markers from the advisory warn_triggers keeps the workflow smooth for routine changes, while critical-surface changes always leave documented evidence. The best automation tool is not a wall without a door; it is a clear signpost when a developer steps into an area that needs extra attention.