# History — Privacy: Period Tracker

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: the narrative of how this project got to where it is
Review trigger: A decision reversed, a direction abandoned, or a rewrite
```

## What this is for

The story, in prose: what was tried, what was abandoned, and why. A reader
arriving in six months wants to know which walls have already been walked into,
and that is not something a commit log tells them.

**This is a record of *then*, never a description of *now*.** That distinction is
what makes it safe to leave alone as the project changes — a history document
edited to stay current is not a history, it is a second and competing
description of the present.

If you find yourself updating a sentence here because the code changed, the
sentence belongs somewhere else.

## Where this project started

Period began as a single document. Before any repository existed there was one
2,500-line specification — product, privacy, prediction algorithm, screen copy,
monetization and compliance — written to be handed to a coding agent whole. It
is still here, unchanged in substance, as
[`../planning/PRODUCT_PLAN.md`](../planning/PRODUCT_PLAN.md).

That is worth recording because it explains the shape the first weeks of this
repository had: an unusually complete specification and, at the start, no code at
all. Most projects have the reverse problem.

## Decisions and their reasons

One entry per decision that would otherwise look arbitrary later. The reason
matters more than the decision: "we chose X" ages badly, "we chose X because Y
was true at the time" survives Y stopping being true.

| When | What was decided | Why, at the time |
| --- | --- | --- |
| 2026-08-18 | Kotlin and Jetpack Compose, not Java or XML | Android is Kotlin-first and Compose-first in Google's own current documentation; the alternative was legacy on arrival |
| 2026-08-18 | Room, not files or SharedPreferences, for cycle history | history is structured, must survive app updates, and needs migrations that can be tested — the other options make a migration a hand-written parser |
| 2026-08-18 | The prediction engine is a **pure Kotlin JVM module** | it is the product, so it needs the most tests; a module that cannot see the Android SDK gets tests that run in a second instead of tests that need an emulator |
| 2026-08-18 | A robust personalized statistical model for V1, not a learned model | it is explainable, offline, fast, deterministic and testable, and the product promise is *personal*, not *neural*. A local ML model is a post-V1 option and only if it demonstrably beats this |
| 2026-08-18 | WorkManager for reminders, and **no exact-alarm permission** | a period reminder does not need alarm-clock precision, and requesting that permission is a Play scrutiny cost with no user benefit |
| 2026-08-18 | Ads stay behind an abstraction in a module that cannot reach cycle data | the privacy promise is the product; a rule people remember is not a control, a compile error is |
| 2026-08-18 | One-time purchase to remove ads, not a subscription | it keeps prediction quality free for everyone and avoids an entire class of entitlement defect — nothing to claw back on cancellation |
| 2026-08-18 | Four Gradle modules at the skeleton, not the seventeen the specification sketches | a module created before it has contents is a place for things to be put by accident; the rest arrive with the batch that needs them |
| 2026-08-18 | Eight milestones opened at once, issues filed only under Batch 01 | the roadmap is genuinely known and worth being visible; the *work items* are not, and inventing them would make every tracker percentage permanently wrong |
| 2026-08-18 | OPERATIONS.md deleted rather than kept empty | this is an offline app, not a deployed service; an empty runbook reads as one nobody wrote |

## What was tried and dropped

This is the most useful section in the file and the one most often missing — an
approach abandoned for a good reason will be proposed again by somebody who does
not know it was tried, including you, in a year.

- **A Room schema-export comparison as the schema-drift guard.** `SchemaTest` was
  written believing it caught drift. Room regenerates the export during
  compilation, so both sides of every comparison agree by construction, and
  adding a column without bumping the version stayed green.
  `scripts/schema-guard.sh` asks git instead, which is the one party Room cannot
  overwrite.
- **`BaselinePredictionEngine` as the product engine.** A robust median over
  recent intervals, correct and not personal enough: PRODUCT_PLAN §11 names a
  plain average as an acceptable prototype and an unacceptable final engine.
  Replaced in Batch 02 by `PersonalPredictionEngine`, and kept as the control
  `EngineComparisonTest` scores the new engine against — which is what makes the
  replacement demonstrably better rather than merely different.
- **PRODUCT_PLAN §39's muted teal and sage palette.** Dropped for the owner's
  plum-and-rose brand guide, including a pink fertile window where §39 wanted
  teal. Safe to drop only because the calendar's states differ in shape rather
  than colour, which is what §43 actually requires.

The specification already carries a partial version of it: every `Avoid:` and
`Do not:` list in [`../planning/PRODUCT_PLAN.md`](../planning/PRODUCT_PLAN.md)
is a decision made in advance rather than a lesson learned. When one of them
turns out to be wrong, that reversal belongs here.

## What this file is not

- **Not the plan.** That is [`../planning/PROJECT_PLAN.md`](../planning/PROJECT_PLAN.md).
- **Not the work list.** Open work lives in the tracker as milestones and issues.
- **Not a changelog.** Dated entries go in [`DEVELOPMENT_LOG.md`](DEVELOPMENT_LOG.md).