null
/
Privacy-Period-Tracker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Privacy-Period-Tracker/docs/TOOLS.md

102 lines
4.7 KiB
Markdown
Raw Normal View History

chore: adopt the project template and add the Kotlin/Compose skeleton Period was a bare directory holding one 2,527-line specification, with no git repository, no tracker and no documentation convention. This is the adoption from Projects/Template/START-HERE-New-Project.md, plus a project that compiles so the hooks and future guards have something real to run against. Documents. scaffold.sh created 19 paths, 0 skipped. The specification moved to docs/planning/PRODUCT_PLAN.md unchanged in substance, with a status header; the capitalised Docs/ is gone. Every scaffolded document was filled in for Period. docs/OPERATIONS.md deleted — an offline app is not a deployed service. DOC_TRUST_MAP.md written last, describing what is actually here, including what this project deliberately does not have. Code. Four Gradle modules. domain/cycle and domain/prediction are kotlin("jvm") and cannot see the Android SDK, so the engine is testable without an emulator — 17 tests pass, 12 of them the acceptance cases from PRODUCT_PLAN.md §51. BaselinePredictionEngine is a robust-median prototype and explicitly not the product; it exists so Batch 02's replacement can be shown to be better rather than merely different. Versions verified against their official sources today rather than inherited from the specification's own numbers, which that document asks for: Kotlin 2.4.10, AGP 9.3.1, Gradle 9.7.0, Compose BOM 2026.08.00, Room 2.8.4, Hilt 2.60.1. AGP 9 ships Kotlin built in, so org.jetbrains.kotlin.android is no longer applied. compileSdk is 37 because current AndroidX requires it; targetSdk stays 36, Play's floor from 2026-08-31, and the difference is deliberate. Six scripts taken into scripts/; the rest declined and named in docs/TOOLS.md. Three hooks in .githooks/, with pre-commit adapted to Gradle. closes #1 closes #2
2026-08-18 02:16:47 -05:00
# Tools — where the scripts are, and which ones can stop you
```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: scripts/**, .githooks/**
Review trigger: Any script added to, removed from or repurposed in scripts/; any
change to which of them gates a commit or a release
```
> A signpost, deliberately. Every project that adopts this template has a
> `docs/TOOLS.md`, so "read `docs/TOOLS.md` first" is an instruction that works
> without knowing anything about the project — which is the whole reason this
> file exists at a fixed path.
## The list is not here
**[`architecture/README.md`](architecture/README.md)** holds the table of what
this project has and what each script is. That is the one copy.
A second table here would be two records of one fact, and the other one would
never hear that a script was renamed. So this file answers the questions that
table does not, and points at it for everything else.
feat: Room database for cycle history, and the schema guard that actually works 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
2026-08-18 02:32:07 -05:00
## Period has seven of them, and that is deliberate
chore: adopt the project template and add the Kotlin/Compose skeleton Period was a bare directory holding one 2,527-line specification, with no git repository, no tracker and no documentation convention. This is the adoption from Projects/Template/START-HERE-New-Project.md, plus a project that compiles so the hooks and future guards have something real to run against. Documents. scaffold.sh created 19 paths, 0 skipped. The specification moved to docs/planning/PRODUCT_PLAN.md unchanged in substance, with a status header; the capitalised Docs/ is gone. Every scaffolded document was filled in for Period. docs/OPERATIONS.md deleted — an offline app is not a deployed service. DOC_TRUST_MAP.md written last, describing what is actually here, including what this project deliberately does not have. Code. Four Gradle modules. domain/cycle and domain/prediction are kotlin("jvm") and cannot see the Android SDK, so the engine is testable without an emulator — 17 tests pass, 12 of them the acceptance cases from PRODUCT_PLAN.md §51. BaselinePredictionEngine is a robust-median prototype and explicitly not the product; it exists so Batch 02's replacement can be shown to be better rather than merely different. Versions verified against their official sources today rather than inherited from the specification's own numbers, which that document asks for: Kotlin 2.4.10, AGP 9.3.1, Gradle 9.7.0, Compose BOM 2026.08.00, Room 2.8.4, Hilt 2.60.1. AGP 9 ships Kotlin built in, so org.jetbrains.kotlin.android is no longer applied. compileSdk is 37 because current AndroidX requires it; targetSdk stays 36, Play's floor from 2026-08-31, and the difference is deliberate. Six scripts taken into scripts/; the rest declined and named in docs/TOOLS.md. Three hooks in .githooks/, with pre-commit adapted to Gradle. closes #1 closes #2
2026-08-18 02:16:47 -05:00
The template this repository adopted ships around twenty scripts. Period took
feat: Room database for cycle history, and the schema guard that actually works 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
2026-08-18 02:32:07 -05:00
six of them and wrote one of its own. `scaffold.sh` copies none of them on purpose — *"an unconfigured
chore: adopt the project template and add the Kotlin/Compose skeleton Period was a bare directory holding one 2,527-line specification, with no git repository, no tracker and no documentation convention. This is the adoption from Projects/Template/START-HERE-New-Project.md, plus a project that compiles so the hooks and future guards have something real to run against. Documents. scaffold.sh created 19 paths, 0 skipped. The specification moved to docs/planning/PRODUCT_PLAN.md unchanged in substance, with a status header; the capitalised Docs/ is gone. Every scaffolded document was filled in for Period. docs/OPERATIONS.md deleted — an offline app is not a deployed service. DOC_TRUST_MAP.md written last, describing what is actually here, including what this project deliberately does not have. Code. Four Gradle modules. domain/cycle and domain/prediction are kotlin("jvm") and cannot see the Android SDK, so the engine is testable without an emulator — 17 tests pass, 12 of them the acceptance cases from PRODUCT_PLAN.md §51. BaselinePredictionEngine is a robust-median prototype and explicitly not the product; it exists so Batch 02's replacement can be shown to be better rather than merely different. Versions verified against their official sources today rather than inherited from the specification's own numbers, which that document asks for: Kotlin 2.4.10, AGP 9.3.1, Gradle 9.7.0, Compose BOM 2026.08.00, Room 2.8.4, Hilt 2.60.1. AGP 9 ships Kotlin built in, so org.jetbrains.kotlin.android is no longer applied. compileSdk is 37 because current AndroidX requires it; targetSdk stays 36, Play's floor from 2026-08-31, and the difference is deliberate. Six scripts taken into scripts/; the rest declined and named in docs/TOOLS.md. Three hooks in .githooks/, with pre-commit adapted to Gradle. closes #1 closes #2
2026-08-18 02:16:47 -05:00
`release.sh` landing in every new repository is a loaded gun, not a head
start"* — so each one is taken having been read and configured.
**The ones not taken were not forgotten.** `release.sh`, `deploy.py`,
`backup.sh`, `restore-check.sh`, `preflight.sh`, `healthcheck.sh`, `migrate.sh`,
`status.sh`, `dev.sh`, `audit-gate.mjs`, `release-notes.mjs`, `duplication.py`
and `dead-code.py` all assume a deployed Node or Postgres service with an npm
dependency tree and a URL. Period is an Android app that ships through Google
Play and has no server at all. A release here is an AAB and a Play Console
submission, so [`security/SECURITY_CHECKLIST.md`](security/SECURITY_CHECKLIST.md)
carries what `release.sh` would have gated.
Two were deferred rather than declined:
- **`verify.sh`** — worth having once there is a real check suite to aggregate.
Today `./gradlew check` is the whole answer and wrapping it would add a layer
that could only be wrong.
- **`check-env.sh`** — its SPEC ships empty and exits `2` until it has entries,
and Period has no environment variables yet. It gets taken with the first
signing or Play credential, which is exactly the moment it becomes worth
running.
feat: Room database for cycle history, and the schema guard that actually works 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
2026-08-18 02:32:07 -05:00
**The seventh is `schema-guard.sh`, and it is this project's own.** It clears
the bar in *Adding one* below the hard way: it exists because the check it
replaces was proved green over exactly the failure it claimed to catch. Its
header carries that proof.
chore: adopt the project template and add the Kotlin/Compose skeleton Period was a bare directory holding one 2,527-line specification, with no git repository, no tracker and no documentation convention. This is the adoption from Projects/Template/START-HERE-New-Project.md, plus a project that compiles so the hooks and future guards have something real to run against. Documents. scaffold.sh created 19 paths, 0 skipped. The specification moved to docs/planning/PRODUCT_PLAN.md unchanged in substance, with a status header; the capitalised Docs/ is gone. Every scaffolded document was filled in for Period. docs/OPERATIONS.md deleted — an offline app is not a deployed service. DOC_TRUST_MAP.md written last, describing what is actually here, including what this project deliberately does not have. Code. Four Gradle modules. domain/cycle and domain/prediction are kotlin("jvm") and cannot see the Android SDK, so the engine is testable without an emulator — 17 tests pass, 12 of them the acceptance cases from PRODUCT_PLAN.md §51. BaselinePredictionEngine is a robust-median prototype and explicitly not the product; it exists so Batch 02's replacement can be shown to be better rather than merely different. Versions verified against their official sources today rather than inherited from the specification's own numbers, which that document asks for: Kotlin 2.4.10, AGP 9.3.1, Gradle 9.7.0, Compose BOM 2026.08.00, Room 2.8.4, Hilt 2.60.1. AGP 9 ships Kotlin built in, so org.jetbrains.kotlin.android is no longer applied. compileSdk is 37 because current AndroidX requires it; targetSdk stays 36, Play's floor from 2026-08-31, and the difference is deliberate. Six scripts taken into scripts/; the rest declined and named in docs/TOOLS.md. Three hooks in .githooks/, with pre-commit adapted to Gradle. closes #1 closes #2
2026-08-18 02:16:47 -05:00
If this project later grows a script the template already has, take that one
rather than writing a new one — the arguments in its header are the part that
took the longest.
## Which ones can stop you
Not in a table, because the honest answer lives in each script's own header and
would go stale here. The rule that matters:
**Exit code `2` is never a pass.** These scripts distinguish "the check ran and
found nothing" from "the check did not run", because those look identical from
the outside and only one of them is evidence. A hook or a CI step that treats a
`2` as success has quietly turned the check off. Each script states its codes at
the top; read them there.
The hooks are the other place work gets stopped:
[`architecture/githooks/README.md`](architecture/githooks/README.md) has the one
install command and the table of what each hook runs. Note that **`post-commit`
pushes**, and that `pre-commit` here runs Gradle rather than the template's
TypeScript typecheck.
## Where to start in a fresh clone
1. `git config core.hooksPath .githooks` — per clone, every time, and an
uninstalled hook fails silently.
2. `bash scripts/secrets.sh --tracked` — the one-time audit of what is already
committed. The staged-diff mode is for the hook; this mode is for the day you
clone.
3. `./gradlew test` — the prediction acceptance tests run on the JVM, so this
needs no emulator and should be fast.
4. [`architecture/GUARDS.md`](architecture/GUARDS.md) — how to write a check that
can actually fail, before you write one. `scripts/prove-guard.sh` performs its
first rule.
## Adding one
Put it in `scripts/`, give it a header saying what it does and **which incident
motivated it**, state its exit codes, and add a row to
[`architecture/README.md`](architecture/README.md)'s table — this file's
`Review trigger` fires on exactly that.
The bar, from the scripts that are already here: **done by hand three times, or
once with a consequence.** A script written before either of those has no
failure to describe in its header, which is the part that stops the next person
deleting it.