M7 — Contraceptive Security — Session Card

Planning artifact. A future build session opens this file to know exactly what to build for the Contraceptive Security module, in what order, with what entry dependencies and done criteria. No production code lives here. Read alongside docs/plan/13-execution-modules-and-sessions.md (the execution framework), docs/plan/03-protocol-engines.md §7 (the engine spec), and docs/plan/04-backend-togo.md (schema/migration/plugin rules).

Purpose

The Contraceptive Security engine tracks contraceptive-method adherence with per-method state machines, because a daily pill, a monthly injection, and a long-term implant have fundamentally different schedules and failure modes. Like every Health Debug engine it lives only in the ToGO backend (the Single Source of Truth); every client renders server state and submits log intents. The engine is strictly categorical — it branches on what the method is, never on hormone dosage or brand pharmacology — and it never states protection status ("you are/aren't protected"): every consequence-shaped question terminates in "Consult your doctor." This module ships on backend, web, mcp, apple, android, desktop — no chrome surface (a browser popup is the wrong place for contraceptive tracking; matches M6 Cycle).

Engine parameters (exact — from 03-protocol-engines.md §7 / shared context)

Parameter	Value	Notes
Differentiated method types	daily pills, monthly injections, implants	Closed enum: daily_pill | monthly_injection | implant. The engine's logic branches on the method type (categorical), never on dosage.
Per-type schedule / validity rules	UNDEFINED BY SPEC — OPEN QUESTION	Pill day-window/grace, injection due-date tolerance, implant validity duration + expiry-reminder lead time are not in the spec. Do not invent numbers. See Notes & gotchas / 03 §7.2, §11 Q7.
Cycle Engine (M6) interaction	UNDEFINED BY SPEC — OPEN QUESTION	Whether an active method suspends Cycle Engine predictions is not in the spec. Fail-safe posture suggests suspension, but this is a product/clinical decision, never an engine guess.
Guidance on any missed/overdue/expiring state	"Consult your doctor."	The engine reports the logging fact only. It never states protection status, never advises doubling/skipping. (Core Opinion 2.)
Fail-safe	Report unconfigured/ambiguous and ask the user	When due-date math is ambiguous (e.g. missing injection date) the engine never assumes protection continuity.

Note on "constants": unlike Hydration (250ml/5000ml/30s) or Caffeine (90min), M7 has no spec-fixed numeric protocol constant. The only fixed protocol facts are the three method-type enum values and the fail-safe/no-certainty posture. The per-type windows that would be the numeric constants are exactly the OPEN QUESTIONS above — so the SSOT/thin-client audit for M7 targets due-date math, protection-status logic, and local schedule computation, not literal magic numbers.

Proposed REST surface (names only — from 03 §7.6; reconcile against the frozen Phase 1 contract)

Endpoint	Purpose
POST /v1/engines/contraceptive/methods	Register a method (typed)
GET /v1/engines/contraceptive/state	Current per-method snapshot
POST /v1/engines/contraceptive/events	Log dose / injection / replacement
GET /v1/engines/contraceptive/history	Adherence-to-logging history

Session table

Surfaces are executed in the fixed order backend → web → mcp → apple → android → desktop (chrome omitted). The backend session MUST land before any client session. <date> = ISO build date; NN = zero-padded sequence — leave both as placeholders until the session runs.

Session ID	Surface	Scope (what this one session builds)	Entry deps	Done criteria (doc 13 §5)	Plan docs to read
S-<date>-M7-backend-NN	backend	The contraceptive ToGO plugin: pure core/ state machine with the three per-method sub-machines (DailyTrack / MonthlyTrack / LongTermTrack per 03 §7.3); plugin.go kernel registration (routes, config, hook subscriptions, migration manifest); expand-contract migration for method + event tables; the four endpoints returning computed per-method state; fail-safe unconfigured/ambiguous handling; engine unit tests encoding the categorical differentiation as executable spec; integration test against real Postgres. Rule sets are read through the Microkernel config/hook layer (future doctor "Medical Restrictions" overlay), never hardcoded. Per-type window rules and Cycle-suspension behavior land as explicitly-flagged sentinels/config, not invented numbers (see gotchas).	M0.1–M0.4 (kernel, TOGO auth, plugin framework, migration harness); coordinate with S-<date>-M6-backend (Cycle) — the "does an active method suspend Cycle predictions?" open question spans both engines, so M6 backend should exist first or the decision be recorded jointly	Backend-engine template: plugin registered on the kernel; migration is expand-contract and every column NOT NULL with a defined default (unconfigured/ambiguous modeled as a sentinel enum state, never SQL NULL); endpoints return computed state; engine unit tests encode the spec facts literally (daily pill vs monthly injection vs implant follow distinct machines; missed/overdue reports logging fact only; no protection-status output) and pass; integration test against real Postgres passes (idempotency replay on events, concurrent-log race); no protocol/schedule constant appears outside the engine's core/ package	13 (§3, §5, §6); 03 §7 + §0 + §9.2 + §10; 04 §4 (NOT NULL rule), §5 (expand-contract), §8 (plugin purity), §9 (testing)
S-<date>-M7-web-NN	web	Contraceptive tracking screen at /engines/contraceptive: register a typed method, log dose/injection/replacement events, and render the server's per-method snapshot + upcoming due items + missed/late history verbatim. All three method-type UIs render from server state; the screen computes no schedule and shows no protection verdict. Categorical method picker only.	M0.5–M0.7 (web shell, theme engine, i18n/RTL); S-<date>-M7-backend; M1 web as the reference-engine pattern to copy	Client-engine template: the screen renders /v1/engines/contraceptive/state (+ history) and submits register/log intents only; thin-client/SSOT audit passes — no due-date math, no schedule computation, no "protected/not protected" logic in client code (grep finds no per-type window logic); both dark-glow and light-flat themes render per the strict color spec; Arabic RTL mirrors correctly (incl. any progress/countdown for an expiring implant); all strings ICU, none concatenated; every AI-adjacent/consequence surface carries "Consult your doctor."	13 (§3, §5); 05 §1, §3.1 (/engines/contraceptive route), §3.2 (['engine','contraceptive'] query), §4 (theme), §5/§5b (i18n/RTL), §7 (Log Entry Controls); 03 §7
S-<date>-M7-mcp-NN	mcp	A read-only status tool (e.g. contraceptive_status) that calls GET /v1/engines/contraceptive/state and returns the server snapshot verbatim (per method: type, upcoming due, missed/late — no protection claim). Register the CLI equivalent (healthdebug contraceptive status). Logging/write tools are out of M7 mcp scope (brief = "status read").	M0.8 (MCP server + CLI skeleton); S-<date>-M7-backend	MCP template: the tool calls the real API with personal-access-token auth, returns server state verbatim, holds no protocol logic and no AI keys; it adds no interpretation and emits no medical-certainty text; deliberately-excluded surfaces stay excluded (no prediction/diagnosis passthrough). Whether MCP should also allow logging contraceptive events is flagged PENDING DESIGN, not built here	13 (§5); 11 (Architecture, Planned tools table, Core Opinions, "Tool list grows with the engines"); 03 §7
S-<date>-M7-apple-NN	apple	iOS Contraceptive Security screen (part of Divergence #1 "Meds & Cycle Tracking on iOS"): render the server's differentiation of daily pills / monthly injections / implants and log adherence events against it. Reminder scheduling fires at server-provided instants only. Privacy-discreet presentation (lock-screen / complication discretion) is a first-class concern here. No HealthKit cycle-tracking data is used as input or output.	S-<date>-M7-backend; M1 apple (workspace + HDAPIClient/HDDesignSystem/HDLocalization scaffold); logically grouped with S-<date>-M6-apple (Cycle) under Divergence #1	Client-engine template: iOS surface renders API state and logs intents only; SSOT audit — no regimen/schedule math on device (no per-type window constants embedded); both themes exact per §10.1 color spec (glow vs flat); full Arabic RTL mirroring incl. progress/ring direction; ICU strings, no concatenation; medical-certainty copy audit passes ("Consult your doctor.", no protection claims)	13 (§5); 07 §1, §3.1 (client/backend line), §4 (Contraceptive row), §10 (theming/RTL), §11 (Closing Divergence #1 — Meds & Cycle); 03 §7
S-<date>-M7-android-NN	android	Handheld Kotlin/Compose Contraceptive Security screen: collect method + log intents, render the server's regimen differentiation and history. Reminders fire at server-scheduled instants via core/notifications (Divergence #3 layer); channel taxonomy includes cycle/contraceptive reminders. Wear/Auto/Glance parity for this engine is not required (it is not a companion-surface engine like Hydration/Pomodoro) unless design says otherwise.	S-<date>-M7-backend; M1 android (core/network, core/model, core/designsystem, core/i18n scaffold); logically alongside S-<date>-M6-android (Cycle)	Client-engine template: the screen POSTs method/log intents and renders API state only; thin-client architecture test — core/model stays data-only, no engine outcome computed anywhere (no per-type window rules in Kotlin); both palettes exact per §7.1; full LayoutDirection.Rtl Arabic pass incl. mirrored progress; ICU/values-ar, no concatenation; behavioral-only copy, "Consult your doctor."	13 (§5); 08 §2 (thin-client matrix, Contraceptive row), §3 (layout), §7.1 (theme), §8 (notifications), §9 (RTL); 03 §7
S-<date>-M7-desktop-NN	desktop	Electron desktop Contraceptive Security view: reuse the shared packages/ui React components from the M7 web session inside the desktop shell; render server state, log via the same packages/api-client. No desktop-specific protocol logic; tray/quick-action involvement is optional and PENDING DESIGN (contraceptive logging may be intentionally kept to the full window for privacy).	S-<date>-M7-backend; S-<date>-M7-web (shared components + api-client hooks); M1 desktop (Electron shell scaffold, Phases 1–2 stable)	Client-engine template: renderer reuses shared components and renders API state only; SSOT conformance gate — no protocol/schedule constants in apps/desktop or packages/* (only server-provided display strings); both themes exact per §9 palette; Arabic RTL incl. mirrored progress across window/popover; ICU catalogs shared, no concatenation; AI/consequence copy defers to "Consult your doctor."	13 (§5); 09 §3 (architectural rules), §4 (code sharing with web), §9 (theme), §11 (i18n/RTL); 05 (shared component contracts); 03 §7

Notes & gotchas

• Reuse the reference-engine pattern. M1 (Hydration) is built end-to-end first as the reference; every M7 per-surface session should copy its established shape (plugin core/+plugin.go layout, web engine-card/route pattern, MCP tool wiring, native screen scaffold) so these sessions go faster. M6 (Cycle) is the closest sibling — same "not on chrome," same Divergence #1 grouping on Apple, same fail-safe/no-certainty posture — reuse its decisions where they transfer.
• No invented numbers — this is the headline liability. Per-type window/validity rules (pill day-window/grace, injection due tolerance, implant validity duration, expiry-reminder lead time) are PENDING DESIGN / OPEN QUESTION (03 §7.2, §11 Q7). The backend must model these as loaded config/sentinels behind the Microkernel config-hook layer (so a future doctor "Medical Restrictions" overlay can set them without an engine rewrite — 03 §10, 04 §8), not as constants baked into core/. If a session needs a concrete window to proceed, it stops and records the open question — it does not guess.
• Cycle interaction is cross-engine and clinical (PENDING DESIGN). "Does an active contraceptive method suspend Cycle Engine (M6) predictions?" is unresolved (03 §7.7, §11 Q7). Fail-safe posture suggests suspension, but it must be a product/clinical decision. Coordinate the M7 and M6 backend sessions; whichever lands second must reconcile the interaction and record the decision as a classified architecture-decision/open-question memory and (if it changes behavior) an edit to 03.
• Never emit protection status. On any missed/overdue/expiring state the engine reports only the logging fact; it must never render "you are protected / not protected," efficacy percentages, or dosing advice. Every such surface terminates in "Consult your doctor." (Core Opinion 2 — strict here.) Copy audits are a client-session done-criterion.
• Privacy/discretion is a real requirement, and PENDING DESIGN. Reminder surfaces and privacy presentation — lock-screen discretion, watch complications, whether contraceptive logging appears in tray/widgets at all — are PENDING DESIGN (03 §7.4). Treat contraceptive data as sensitive; default to discreet.
• Method switching / archival. Overlap semantics when switching method (pill → injection: archive old machine, instantiate new) are an open question (03 §7.7). Model archival explicitly; do not silently drop history.
• Schema discipline (backend). Every column NOT NULL with a defined default; the unconfigured/ambiguous fail-safe is a sentinel enum state, never SQL NULL; all changes strictly expand-contract with atlas migrate lint as the CI gate (04 §4, §5). Method type is a closed enum; events are append-only with an idempotency key (04 §7) so an AI/watch retry cannot double-log.
• MCP is read-only for M7. The brief scopes MCP to a status read. No log/write tool and no prediction/diagnosis passthrough. Keep the deliberately-excluded posture; revisit only if a later product decision opens it (PENDING DESIGN).
• No chrome cell exists for M7. Do not create one; the module grid intentionally has no chrome column here (matches M6).

Handoff reminder

At session end, follow the Brain Handoff Protocol (docs/plan/13-execution-modules-and-sessions.md §6): write one session-handoff memory to the healthdebug cabrain brain — retain the content in the §6 structure, then memory/edit to attach metadata — with a unique source_ref: handoff/M7-contraceptive-security/<surface>/<n> (never reuse a ref) and metadata {project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"M7", title:"Handoff <session-id>", tags:[...], 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 new architectural decision or open question (e.g. the Cycle-suspension resolution, a chosen per-type window rule) also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc.