67b3c45002
core/database holds the four entities from PRODUCT_PLAN.md §10 —
period_records, spotting_records, prediction_records, not_yet_observations —
with DAOs returning Flow, epoch-day/epoch-milli converters, and the schema
exported to core/database/schemas and committed.
Three constraints are structural rather than remembered:
- startDate is UNIQUE and inserts ABORT rather than REPLACE. REPLACE would
delete the original row with its createdAt and source; §14 says health
history is never modified silently.
- spotting has its own table, so no query for periods can reach it. §25: it
must never start or reset a cycle.
- a prediction snapshot can be scored but not rewritten — score() sets only
actualStartDate and absoluteErrorDays. A snapshot editable after the fact
can only ever report that the app was right, which would make §16's whole
accuracy feature a lie.
deleteEverything() is one transaction and the only bulk delete in the module: a
partial wipe leaves the cycle reconstructible from the tables the user asked to
be rid of.
14 tests, on the JVM under Robolectric — no emulator.
THE SCHEMA GUARD, AND WHY IT IS A SCRIPT
SchemaTest was written as a drift guard and proved not to be one. Room
regenerates the schema export during compilation, so adding a column to
PeriodRecordEntity without bumping VERSION leaves the suite green while the
committed schema quietly changes underneath it. That was not reasoned about, it
was run: the column was added, 1.json gained it, and every test passed. On a
device that is "Room cannot verify the data integrity" — a crash on update,
after shipping.
scripts/schema-guard.sh asks git instead, which Room cannot overwrite. Proved
both ways before being trusted: green on a clean tree, exit 1 on the injected
drift. It runs in pre-commit when an entity or the schema directory is staged,
and the hook treats its exit 2 as a refusal.
SchemaTest keeps its four tests and now documents what it does not catch.
Room's own MigrationTestHelper is not used: every constructor needs an
Instrumentation and schema assets, and AGP 9's library source-set DSL throws
DefaultAndroidLibrarySourceSet_Decorated cannot be cast to
AndroidLibrarySourceSet when you add an asset directory. Recorded so the next
person does not spend the afternoon on it.
Docs updated in this commit, as their triggers required: the migration table
now has its version 1 row and the trap that makes such tables go stale, TOOLS
explains the seventh script, and the hooks README lists the new guard.
closes #3
|
||
|---|---|---|
| .. | ||
| README.md | ||
README.md
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; then scripts/schema-guard.sh when a Room entity or the schema export 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.
The schema guard is here rather than in the suite for a reason worth knowing.
Room rewrites the schema export during compilation, so by the time any test
runs, both sides of any in-process comparison describe the changed entity and
agree. Only git can see that an already-committed schema file changed, and only
a hook can ask git before the commit exists. scripts/schema-guard.sh carries
the proof in its header — the check it replaced was watched staying green over
exactly the failure it claimed to catch.
It exits 2 for "nothing was checked", and the hook treats 2 as a refusal.
A missing schema directory is not a clean schema.
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.