3.9 KiB
Git hooks
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: .githooks/ — what runs before and after a commit
Review trigger: A new guard the repository wants run before a commit; any change
to what a commit message must contain; any change to which
Gradle tasks pre-commit runs
Three hooks, and the reason they live in the repository rather than in
.git/hooks: that directory is not versioned, so a hook living there protects
exactly one clone on exactly one machine.
The hooks are in .githooks/, and only there
The template this repository adopted keeps a master copy under
docs/architecture/githooks/ and installs copies into .githooks/. Period
does not, deliberately: pre-commit here is adapted for Gradle rather than
npm, so a second copy would be a second version of a file somebody edits once
and forgets — the exact failure ../../DOC_TRUST_MAP.md exists to prevent.
So .githooks/ holds the hooks and this document
describes them. One copy of the code, one copy of the explanation.
Install
git config core.hooksPath .githooks
That is the whole setup, and it is per clone — every checkout runs it once, including a fresh clone on the same machine. An uninstalled hook fails silently, which is the same class of problem the hooks exist to prevent.
What each one does
| Hook | Guard |
|---|---|
pre-commit |
the staged-diff secret scan, then :domain:cycle:test and :domain:prediction:test when .kt/.kts or a build file is staged |
commit-msg |
refuses a message with no conventional type — the closed vocabulary is in the hook's own header |
post-commit |
pushes to origin, so a guarded commit does not sit unpushed |
Two things worth knowing before you rely on them
pre-commit does not compile the Android modules. It runs the two pure-JVM
suites, which need no SDK and take about a second. Compiling :app needs the
Android SDK and half a minute, and a hook people reach for --no-verify to
avoid is worse than one that checks less. ./gradlew assembleRelease belongs to
../../security/SECURITY_CHECKLIST.md,
which is where it is.
The suite it does run is not an arbitrary subset: it is the prediction
acceptance cases from
../../planning/PRODUCT_PLAN.md §51, which
guard the one claim this product is built on.
post-commit pushes. That is the intent — the commit that first added a
pre-commit hook to the project this came from sat unpushed for a day, guarded
and invisible — but it is a surprise if you were not expecting it. It never
forces, stays out of the way mid-rebase, and SKIP_PUSH=1 opts out loudly.
It has a second consequence worth knowing about: the push is what the Command
Center reads, so whatever documentation was not in that commit is now behind
the code by one push. That is the mechanical reason
../../WORK_CYCLE.md asks for doc edits in the same
commit as the change rather than in a tidy-up afterwards — with this hook
installed, "I will document it next commit" means the site has already published
the version without it.
Escape hatches, and why they are loud
SKIP_GUARDS=1 git commit ... # skips the scan and the tests, and says so
SKIP_PUSH=1 git commit ... # commits without publishing, and says so
git commit --no-verify ... # skips the hooks entirely, silently
Prefer the first two. They leave a line in the terminal saying the guard did not run, which is the difference between a deliberate exception and a habit.
Why a hook and not CI
Both, eventually. These are the guards that must run before the artifact exists: a check that fires after a push, or after a Play upload, catches the problem once it is already somewhere it cannot be taken back from. CI is the second opinion; this is the one that runs first.