# M6 — Cycle (Fertility) — Session Card

> **Planning artifact.** This card is opened by a future build session so it knows exactly what to build for module **M6 Cycle (Fertility)**. It contains no production code. It is faithful to `docs/plan/13-execution-modules-and-sessions.md` (the session framework), `03-protocol-engines.md §6` (the engine spec), `04-backend-togo.md` (backend conventions), `02-platform-divergences.md §2.1` (this module closes Divergence #1 on iOS), and `12-legacy-reference-map.md` (legacy precedents).

## 1. Purpose

The Cycle (Fertility) engine tracks user-logged menstrual cycles and offers predictions **only** once enough consistent data exists, and otherwise **fails safe to "no prediction."** It is a backend state machine in ToGO (the Single Source of Truth); every client — web, mcp, apple, android, desktop (there is **no chrome surface** for this module) — only renders the engine state the API returns and submits log intents. This module closes **platform Divergence #1** (Meds & Cycle Tracking, historically missing on iOS): in the greenfield build the 3-cycle prediction gate and irregularity fail-safe live once, server-side, so the iOS/Android/web screens are pure presentation against an already-live contract and can never re-derive the rule. Because cycle/fertility data is highly sensitive, cross-user isolation (404-not-403) and per-user SSE/event routing (no cross-user leakage) are hard requirements, not niceties — the legacy build had to fix an event broker that leaked across users, and this module must not reintroduce that class of bug.

## 2. Engine parameters relevant to this module

### Spec-fixed constants (from `03-protocol-engines.md §6.2` and shared context — do NOT invent others)

| Parameter | Value | Notes |
|---|---|---|
| Calibration requirement | **3 consecutive logged cycles** before **any** prediction is made | Hard gate. No prediction, ever, below this. |
| Irregularity rule | On irregularity the engine **fails safe: no prediction** | Predictions are **withdrawn**, never "widened." |
| Prediction sentinel | `unavailable` (+ reason code) | NOT NULL rule: an explicit sentinel value, **never SQL NULL**. |
| States | `Insufficient` / `Calibrated` / `Suspended` | Categorical only — the user never sees a confidence percentage (Core Opinion 1). |
| "Consecutive" | no unlogged cycle between logged ones | Engine never infers a skipped cycle happened. |

State transitions (`03 §6.3`): `Insufficient → Calibrated` on the 3rd consecutive cycle; `Calibrated → Suspended` when irregularity is detected; a logging gap resets the consecutive counter to `Insufficient`; `Suspended → Insufficient` on recalibration (a fresh 3-consecutive run — see PENDING items).

### Legacy precedent (PENDING RATIFICATION — precedents from `cycle.go`, NOT spec-fixed; carry as fail-safe categorical/temporal, no medical certainty)

These are the concrete numbers the legacy engine used. They are **candidate answers**, not authority — the greenfield spec (`03 §6.2`, and Open Question #6 in `03 §Open Questions`) leaves the quantitative definition of "irregularity" undefined. Use them as the default implementation to be ratified during the backend session, and encode whatever is ratified as literal constants inside the engine `core/` package.

| Precedent | Legacy value (`cycle.go`) |
|---|---|
| Minimum cycles for prediction | `MinCyclesForPrediction = 3` (matches the spec gate) |
| Irregularity threshold | `IrregularThresholdDays = 9`-day spread → refuse to predict |
| Averaging window | average of the **last 6 cycles** |
| Ovulation estimate | next cycle start **−14 days** |
| Fertile window | **−5 / +1 day** around the ovulation estimate |
| BBT confirmation | 3 readings **≥ +0.2 °C** over the prior 6-day mean |
| Pregnancy dating | **Naegele: +280 days** from cycle start |
| Safety data | `SafetyProvider` interface with `NoSafetyData{}` default — **no drug DB wired, by design** |

All predictions are behavioral-data extrapolations, explicitly labelled non-medical, and every AI-adjacent / fertility surface ends in **"Consult your doctor"** (Core Opinion 2). The engine never smooths, averages away, or best-guesses an irregular history.

### Data model (this module owns)

- Tables: **`cycles`** and **`cycle_days`** (per-user). Every column `NOT NULL` with a defined default; UUID ids; `timestamptz` timestamps (`04 §4/§6`).
- Endpoints (names from `03 §6.6`, under the `/api/v1/` prefix per `04 §API`): `POST /api/v1/engines/cycle/logs` (log a cycle event; accepts `Idempotency-Key`), `GET /api/v1/engines/cycle/state` (calibration state + prediction-or-`unavailable` + reason), `GET /api/v1/engines/cycle/history`.
- Engine output shape: `{ state, consecutive_cycles_logged, prediction: value|unavailable, reason }`.

## 3. Session table

One row per session. Surface order per `13 §3`: backend → web → mcp → (no chrome) → apple → android → desktop. **The backend session must land before any client session** (`13 §4`). Replace `<date>` (YYYY-MM-DD) and `NN` (per-cell counter) when the session actually runs.

| Session ID | Surface | Scope (what this one session builds) | Entry deps | Done criteria (template from `13 §5`) | Plan docs to read |
|---|---|---|---|---|---|
| `S-<date>-M6-backend-NN` | backend | The **cycle ToGO plugin**: pure `core/` state machine (Insufficient/Calibrated/Suspended, the 3-consecutive gate, irregularity → no-prediction fail-safe, `unavailable` sentinel + reason) + `plugin.go` registration; `cycles` + `cycle_days` expand-contract migration; the three endpoints; engine unit tests as executable spec; integration test on real Postgres. Ratify the PENDING legacy numbers (§2) and encode them literally in `core/`. Verify cross-user isolation (404-not-403) and that any SSE/event emitted for cycle carries **no cross-user leakage**. | M0.1–M0.4 (foundation backend: kernel, TOGO auth + isolation test, plugin framework, expand-contract + error-envelope harness); **M1 backend** as the reference-engine pattern to copy | **Backend-engine template:** plugin registered on the kernel; migration is expand-contract and every column `NOT NULL` with a default; endpoints return computed state; engine unit tests encode every spec/ratified constant literally and pass (no prediction until 3 consecutive cycles; fail-safe = no prediction on irregularity); integration test on real Postgres passes (idempotency replay; contradictory-edit → `Suspended`; cross-user isolation 404-not-403); **no protocol constant appears outside the engine's `core/` package** | `13` (§3–§6), `03 §6` (engine spec), `04` (§2 layout, §3 sqlc+Atlas, §4 NOT NULL rule, §5 expand-contract, §8 plugin/purity, §9 testing), `12 §2` (legacy `cycle.go` constants) |
| `S-<date>-M6-web-NN` | web | The **cycle screen** (`/engines/cycle`): renders server state — shows calibration progress / "needs 3 consecutive logged cycles" when `Insufficient` or `Suspended`, and shows a prediction **only** when the server state is `Calibrated`. Cycle-log entry control submits intents only. Both themes; Arabic RTL. | `S-<date>-M6-backend-NN`; M0.5–M0.7 (web shell, theme engine, i18n engine); **M1 web** as the reference card pattern | **Client-engine template:** renders the cycle endpoint state and submits log intents only; **thin-client/SSOT audit passes** — no gate/irregularity/prediction logic in client code, grep for the protocol constants finds nothing, prediction shown only when server says `Calibrated`; both themes render per the strict color spec; Arabic RTL mirrors correctly (incl. progress/calibration bars); strings are ICU, none concatenated; "Consult your doctor" deferral rendered verbatim | `13` (§5 client template, §6), `03 §6`, `05` (§3 routing `/engines/cycle`, §4 query keys, §5b RTL strategy, component inventory), `02 §2.1` (Divergence #1) |
| `S-<date>-M6-mcp-NN` | mcp | **Cycle status read-only** MCP tool(s): `cycle_status` → `GET /api/v1/engines/cycle/state`, returned verbatim. **No prediction tool beyond what the backend exposes** — the engine's fail-safe rules apply unchanged; no client-side inference. | `S-<date>-M6-backend-NN`; **M0.8** (MCP server + CLI skeleton) | **MCP template:** each tool calls the real API with personal-access-token auth, returns server state verbatim, holds no protocol logic and no AI keys; the excluded tools stay excluded (no cycle/fertility *prediction* tool beyond the backend `state`/`history` reads; the general `complete_break` exclusion still holds) | `13` (§5 MCP template, §6), `11` (§thin-layer rule, planned tools, deliberately-excluded tools incl. "no cycle/fertility prediction tool"), `03 §6` |
| `S-<date>-M6-apple-NN` | apple | Native Swift **Meds & Cycle screen** (iOS; + macOS/widget surfaces as they apply) rendering cycle engine state against the live API — **this session closes Divergence #1 on iOS.** No local re-implementation of the 3-cycle gate or irregularity rule. | `S-<date>-M6-backend-NN`; **M1 apple** (Apple project scaffold + reference engine pattern) | **Client-engine template:** renders the cycle endpoint state and submits log intents only; thin-client/SSOT audit passes (no gate/prediction/irregularity logic in Swift — grep finds no protocol constants; iOS never re-derives the rule); both themes per the strict color spec; Arabic RTL mirrors correctly; strings are ICU/String-Catalog, none concatenated; "Consult your doctor" deferral present | `13` (§5 client template, §6), `03 §6`, `07` (§principles, project layout, iOS app row — "Meds & Cycle tracking (closes Divergence #1)"), `02 §2.1` |
| `S-<date>-M6-android-NN` | android | Native Kotlin/Compose cycle screen (phone; + Wear/Glance as they apply) rendering cycle engine state; cycle-log intents only. | `S-<date>-M6-backend-NN`; **M1 android** (Android scaffold + reference engine pattern) | **Client-engine template:** renders the cycle endpoint state and submits log intents only; thin-client/SSOT audit passes (no protocol logic in Kotlin, grep finds no constants); both themes per the strict color spec; Arabic RTL mirrors correctly; strings are ICU, none concatenated; "Consult your doctor" deferral present | `13` (§5 client template, §6), `03 §6`, `08` (project layout, engine screen pattern, en/ar parity), `02 §2.1` |
| `S-<date>-M6-desktop-NN` | desktop | Electron cycle surface, **reusing the M6 web components** (`13 §3` step 7) — thin renderer of server cycle state. | `S-<date>-M6-backend-NN`; `S-<date>-M6-web-NN` (component reuse); **M1 desktop** (Electron scaffold pattern) | **Client-engine template:** renders the cycle endpoint state and submits log intents only; thin-client/SSOT audit passes (reused web components carry no protocol logic; PAT auth via safeStorage, no keys embedded); both themes per the strict color spec; Arabic RTL mirrors correctly; strings are ICU, none concatenated | `13` (§5 client template, §6), `03 §6`, `09` (Electron layout, web-component reuse), `05` (reused components) |

**Session count: 6** (backend, web, mcp, apple, android, desktop — no chrome).

## 4. Notes & gotchas

**Legacy precedents worth reusing**
- `internal/protocols/cycle.go` and its `*_test.go` are the **executable protocol specification** — validate the new `core/` engine against those cases first (`12 §2`). Constants: `MinCyclesForPrediction=3`, `IrregularThresholdDays=9`, last-6-cycle average, ovulation −14d, fertile window −5/+1d, BBT +0.2 °C ×3 over prior 6-day mean, Naegele +280d.
- The legacy `SafetyProvider` / `NoSafetyData{}` seam (no drug DB wired, by design) is the correct posture — keep the safety hook empty rather than inventing safety data.
- Legacy per-user CRUD already modeled `cycles` and `cycle_days` (and `pregnancies` with a partial-unique "one ongoing per user") — a schema precedent, but re-evaluate the legacy anti-patterns (text ids → use UUIDs; absent dates as empty text → use proper defaults; no FK to the auth users table; CSV-text fields).

**Liabilities to avoid**
- **#1 liability — duplicated protocol logic on a client.** The legacy iOS app re-implemented engines locally and never called the API; that is exactly the drift this module closes. Every client session's done-criteria include the thin-client/SSOT grep audit for precisely this reason.
- **Sensitive-data routing.** Fertility data is sensitive: the legacy fix replaced ToGO's event broker (which **leaked events across users**) with a per-user SSE hub carrying resource names only, no state (`12 §4`). Any cycle event/SSE emitted here must be per-user with **zero cross-user leakage**; foreign rows return **404 not 403**. Add an isolation assertion to the backend integration test.
- **Never emit a prediction outside `Calibrated`.** The prediction field must carry the `unavailable` sentinel (not SQL NULL) plus a reason in `Insufficient`/`Suspended`. Clients must show a prediction **only** when the server state is `Calibrated` — no client-side "we probably have enough data" heuristic.
- **No medical certainty.** Predictions are behavioral extrapolations, never fertility guarantees or contraceptive advice; all such copy defers to "Consult your doctor" (Core Opinion 2).

**PENDING DESIGN / PENDING RATIFICATION**
- **PENDING RATIFICATION:** the quantitative definition of "irregularity" is undefined in spec (`03 §6.2`, Open Question #6). Ratify the legacy 9-day-spread / last-6-average / BBT numbers (or a replacement) during the backend session and encode them literally in `core/`.
- **PENDING (spec open, `03 §6.7`):** whether recalibration after `Suspended` requires a fresh full 3-consecutive-cycle run (planning default: yes, fail-safe); and whether **backfilled** historical cycles count toward "consecutive" (planning default: stored but not counted — only forward-logged cycles calibrate).
- **PENDING PRODUCT/CLINICAL (`03 §7`):** whether an active contraceptive method (M7) should suspend cycle predictions — a product/clinical decision, not an engine guess. Coordinate at M7, do not hardcode an interaction now.
- **PENDING SCOPE:** pregnancy dating (Naegele +280d) and a `pregnancies` table — decide in the backend session whether it is in M6 scope or deferred; it is a legacy precedent, not a spec-fixed M6 deliverable.
- **PENDING DESIGN:** the calibration-progress UI (Insufficient state) and the cycle/prediction screen layouts across web/apple/android come from the separate design track (`02 §2.1`, `03 §6.3`).

## 5. Handoff reminder

At the end of **every** M6 session, per `13 §6`: write **one** `session-handoff` memory to the `healthdebug` brain (retain, then `memory/edit` to attach metadata — retain cannot set metadata) using the exact handoff content structure, with `source_ref: handoff/M6-cycle-fertility/<surface>/<n>` (unique per session; never reuse) and `metadata: {project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"M6", title:"Handoff <session-id>", next:"<module+surface>"}`. Then **update the single build-ledger memory** (`source_ref: build-ledger`, edited in place) so one recall shows the whole frontier and the recommended next session. Any architectural decision or new open question also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc.