# M8 — Kinetic Pomodoro — Session Card

> Planning artifact. A future build session opens this to know exactly what its cell is, what must be done first, and when it is done. Read alongside `docs/plan/13-execution-modules-and-sessions.md` (the framework), `docs/plan/03-protocol-engines.md §8` (the engine spec), `docs/plan/04-backend-togo.md` (plugin / migration / test conventions), and the relevant platform PRD (05 web, 06 chrome, 07 apple, 08 android, 09 desktop, 11 mcp).

## 1. Purpose

Kinetic Pomodoro is a desk-work focus timer for the core audience (programmers/engineers) whose defining, non-negotiable rule is that **a break registers only when a wearable detects physical movement away from the screen** — sitting through the break with the timer running does not count, and the absence of motion data is *never* treated as movement (fail-safe: under-credit, never over-credit). As with every engine, the ToGO backend is the Single Source of Truth: the pomodoro plugin owns the work/break state machine and the verification decision; watchOS (CoreMotion) and WearOS clients are pure **sensor-collection layers** that push motion evidence; and every desk-side surface (web, chrome, apple menu-bar/overlay, android, desktop) only renders server state and reports evidence. Because the whole point of the module is wearable-validated breaks, the **watch and Wear motion sub-sessions are mandatory** — apple and android cannot be marked done without them.

## 2. Engine / feature parameters (exact — do not invent)

| Parameter | Value / status |
|---|---|
| Break validation | Break registers **only** if wearable motion data shows physical movement **away from the screen**. |
| No-evidence rule (fail-safe) | Absence of wearable data ⇒ `BreakNotRegistered` (unverified). Absence is **never** movement. All ambiguity resolves to "break not registered"; the engine under-credits. |
| Verification authority | The verification decision is made **only on the backend**. watchOS (CoreMotion) / WearOS sensors collect and push evidence; the watch/phone/extension/desktop never mark a break complete. |
| Break state (categorical) | A break is `Registered` or `Not Registered` — binary. No "70% of a break," no movement-quality score surfaced to the user. |
| Motion ingest | Evidence arrives via shared sensor ingest (`POST /v1/sensors/motion/batches`), consumed by the pomodoro engine. |
| Interval lengths | **PENDING RATIFICATION — not spec-fixed.** Legacy precedent (also PENDING ratification): 25 min work / 5 min short break / 15 min long break, long break every 4 cycles, daily target 8. These are config values read through the Microkernel config/hook layer, **never hardcoded** in `core/`. |
| Qualifying-motion threshold | The quantitative signature of "movement away from the workstation" (steps/distance/duration/sensor-fusion recipe) is **PENDING DESIGN — backend-owned**; clients must not embed it. |
| Late-sync re-evaluation | Retroactive `BreakNotRegistered → BreakRegistered` on late-arriving evidence is allowed in principle; the exact re-evaluation window is **PENDING DESIGN**. |
| No-wearable degraded mode | Whether an honor-system mode exists is **PENDING DESIGN**; spec default is breaks simply do not register without wearable evidence. |
| Opinion 1 (categorical, not quantitative) | Binary break outcome only; no motion arithmetic surfaced. |
| Opinion 2 (no invented medical certainty) | No musculoskeletal/cardiovascular claims. AI does behavioral pattern analysis of sitting/break patterns only and always defers to "Consult your doctor." |
| Colors — Dark | `#1A1A1A` bg · `#00FF33` neon-green glow for the active timer · `#00CCFF` cyan buttons · `#FF3333` red alerts (glow effects). |
| Colors — Light | `#FFFFFF` bg · `#20A060` teal · `#0070A0` deep cyan (flat). |
| i18n | ICU Message Format, en/ar catalogs, full Arabic RTL with mirrored progress/countdown; no string concatenation. |

## 3. Session table

One row per session. `<date>` = ISO date the session runs; `<NN>` = zero-padded sequence. Surface order follows doc 13 §3/§4: **backend → web → mcp → chrome → apple → android → desktop**. The two shaded sub-sessions (`apple-watch`, `android-wear`) are **mandatory** gates on their parent surface.

| Session ID | Surface | Scope (what this one session builds) | Entry deps | Done criteria (doc 13 §5) | Plan docs to read |
|---|---|---|---|---|---|
| S-`<date>`-M8-backend-`<NN>` | backend | Pomodoro engine as its own ToGO plugin: pure `core/` state machine (`Idle → Working → BreakPending → BreakVerifying → BreakRegistered / BreakNotRegistered → Working`), `plugin.go` kernel registration (routes, hook subscriptions, config for interval lengths, migration manifest), expand-contract migration for session + break-verification tables, endpoints `POST /v1/engines/pomodoro/sessions`, `POST /v1/engines/pomodoro/sessions/{id}/stop`, `GET /v1/engines/pomodoro/state`, `GET /v1/engines/pomodoro/history`, plus consumption of `POST /v1/sensors/motion/batches`. Break verification consumes motion evidence only; no evidence ⇒ `BreakNotRegistered`. Interval lengths read from config (PENDING ratification), not hardcoded. | M0.1–M0.4 (kernel boot, TOGO auth + user isolation, plugin framework, migration harness). Shared sensor/motion ingest boundary (`/v1/sensors/...`) — build here or depend on X3 sensors ingest; resolve before starting. | **Backend-engine template:** plugin registered on kernel; migration expand-contract, every column NOT NULL with a default; endpoints return computed state; unit tests encode the one spec-fixed rule literally (break registers only on wearable movement; absence ≠ movement) and the config-driven interval values as parameters; integration test vs. real Postgres passes (idempotency replay, no-evidence ⇒ not registered, late-sync re-evaluation, break-window race); **no protocol constant appears outside the engine's `core/` package** (and interval numbers live in config, not `core/`). | 03 §8, §9.3; 04 §2–§9; 13 §3, §5 |
| S-`<date>`-M8-web-`<NN>` | web | Pomodoro focus card on the web dashboard (`/engines/pomodoro`, query key `['engine','pomodoro','current']`): renders server state (work/break-pending/verifying/registered/not-registered + today's registered breaks); start/stop mutations; countdown animates toward the **server-provided deadline only** and re-syncs on server response. Displays break outcome; never claims a break "counts." | M0.5–M0.7 (web shell + auth, theme engine, i18n engine); M8 backend. | **Client-engine template:** renders `/state` and submits start/stop intents only; **thin-client/SSOT audit passes** (no timer/interval/verification logic in client — grep finds no protocol constants; countdown is display-only against the server deadline); both themes render per the strict color spec (neon-green glow timer in dark); Arabic RTL mirrors correctly incl. progress/countdown; all strings ICU, none concatenated. | 05 §1, §3 (query keys/endpoints), §5 (Pomodoro Card); 03 §8; 13 §5 |
| S-`<date>`-M8-mcp-`<NN>` | mcp | `pomodoro_status` tool: **read-only** current work/break snapshot from `GET /v1/engines/pomodoro/state` via personal-access-token auth. Verify the deliberately **excluded** `complete_break` tool stays excluded — an AI must not fake a break. | M0.8 (MCP server + CLI skeleton); M8 backend. | **MCP template:** the tool calls the real API with PAT auth, returns server state verbatim, holds no protocol logic and no AI keys; the excluded `complete_break` (and any break-marking tool) stays excluded; tool schema description states outputs are behavioral tracking, not medical advice. | 11 (tool table + exclusions); 03 §8; 13 §5 |
| S-`<date>`-M8-chrome-`<NN>` | chrome | **Active Pomodoro Guard** (MV3, content-script-free): background worker mirrors work/break state to the toolbar **badge** from the aggregate snapshot poll; during a server-declared forced break it intercepts continuous browser activity (via chosen activity signal — `chrome.idle` vs. tab events, permission tradeoff PENDING) and **reports that activity to `POST /pomodoro/events` as sensor evidence only**. Never marks a break complete. | Chrome extension shell (auth/background worker/snapshot poll from the chrome foundation / M1 chrome session); M8 backend; motion+activity ingest live. | **Client-engine template:** badge renders server snapshot state; activity is reported as evidence, never a completion verdict; **thin-client/SSOT audit passes** (no interval/verification logic; the extension "never decides a break was completed"); both themes per color spec (alert `#FF3333` family while user keeps browsing during a break); Arabic RTL; ICU strings, none concatenated; permission set stays minimal unless the activity-signal decision explicitly widens it. | 06 §5 (Active Pomodoro Guard), §2.4 (permissions), §3.2; 03 §8; 13 §5 |
| S-`<date>`-M8-apple-`<NN>` | apple | iOS focus-timer screen; **macOS Workstation Guard** optional full-screen break overlay (reflects backend break state; lifts on server verdict; dismiss semantics PENDING DESIGN); **macOS menu-bar timer** (`MenuBarExtra`) rendering state + countdown from server timestamps. Renders server state only. Marking this surface **done requires the `apple-watch` sub-session below.** | Apple app shell + `HDAPIClient` + auth (apple foundation / M1 apple); M8 backend. | **Client-engine template** + **M8 gate:** surfaces render `/state` and submit start/stop only; **thin-client/SSOT audit passes** (no interval/verification logic; overlay never validates the break — closing it does not register one); both themes per color spec (glow timer; Metal-glow escalation is PENDING DESIGN); Arabic RTL incl. mirrored progress; ICU strings. **Not done until `apple-watch` sub-session is done** (doc 13 §4). | 07 §6–§7 (watchOS, menu bar, Workstation Guard); 03 §8; 13 §4–§5 |
| S-`<date>`-M8-apple-watch-`<NN>` | apple (watchOS) | **MANDATORY sub-session.** watchOS CoreMotion movement-evidence session: during a backend-declared break window, sample accelerometer/gyroscope, package as an evidence payload, and push to the ToGO API (via paired iPhone or direct — transport decision at build). Watch renders backend-returned state and **never self-completes a break.** | S-`<date>`-M8-apple-`<NN>`; M8 backend; the qualifying-movement **evidence contract** (backend-owned, PENDING DESIGN — payload = raw vs. featurized). | **Client-engine template** (sensor-collection variant): watch pushes evidence only and renders both `BreakRegistered` / `BreakNotRegistered` outcomes from the server; **SSOT audit passes** (no threshold/verification logic on-device); recorded-CoreMotion-trace test (movement vs. stationary) replayed vs. a mock API proves it reports evidence, renders both outcomes, and **never self-completes**; haptics timing originates from the server schedule; Arabic RTL on watch surfaces. Completing this **unblocks marking `apple` done.** | 07 §6.1 (CoreMotion break validation), §11 (Pomodoro test), Open Q #4; 03 §8; 13 §4 |
| S-`<date>`-M8-android-`<NN>` | android | Android phone focus-timer screen; **Android Auto** constraint-awareness surface for pomodoro state (display/voice per Auto affordances, backend-served ICU strings). Renders server state only. Marking this surface **done requires the `android-wear` sub-session below.** | Android app shell + core modules + auth (android foundation / M1 android); M8 backend. | **Client-engine template** + **M8 gate:** phone/Auto render engine-status snapshot and submit start/stop only; **thin-client/SSOT audit passes** (no interval/verification logic); both themes per color spec (Glance/Tile glow approximation PENDING DESIGN); full `LayoutDirection.Rtl` incl. mirrored progress; ICU strings shared with web catalogs, none concatenated. **Not done until `android-wear` sub-session is done** (doc 13 §4). | 08 §5–§6 (WearOS, Auto), §9 (RTL); 03 §8; 13 §4–§5 |
| S-`<date>`-M8-android-wear-`<NN>` | android (Wear) | **MANDATORY sub-session.** WearOS sensor movement-evidence session: during a backend-declared break window, sample the watch's motion/step sensors, transmit evidence to `POST /v1/engines/pomodoro/movement` (or the shared motion ingest); sense only inside break windows (battery). Backend decides; the Wear client **never registers a break** and embeds no threshold. | S-`<date>`-M8-android-`<NN>`; M8 backend; the movement **evidence contract / Wear transport** (backend-owned + phone-relay-vs-direct, PENDING). | **Client-engine template** (sensor-collection variant): Wear pushes evidence only, renders `BreakRegistered` / `BreakNotRegistered` as received; **SSOT audit passes** (no threshold/verification logic — the "engine decides" rule holds); test proves evidence is sent only during backend break windows and both verdicts render as received; no-wearable path leaves the break unregistered; Arabic RTL on Tiles/Wear surfaces. Completing this **unblocks marking `android` done.** | 08 §5.2 (Kinetic Pomodoro movement detection), §11, Open Q #3–#4; 03 §8; 13 §4 |
| S-`<date>`-M8-desktop-`<NN>` | desktop | Electron surface: **Workstation Lock / Break Enforcer** optional always-on-top overlay (one per connected display) driven by server break state, with a dismiss escape hatch (friction PENDING DESIGN); **system-tray live pomodoro countdown** (ticks locally against server anchors, re-anchors on sync) + quick-action menu; **global hotkey** for start/quick-log wired to API. Reuses the web focus card; has **no movement-sensor role**. | Desktop Electron shell + tray + hotkey + vault infra (desktop foundation / M1 desktop); M8 backend; web pomodoro card (S-`<date>`-M8-web-`<NN>`). | **Client-engine template:** overlay/tray/hotkey render server break state and submit intents only; **thin-client/SSOT audit passes** (overlay never validates a break — closing it, mouse, or keypress does not register one; only the server, on wearable movement, registers; no protocol constants in client code); both themes per color spec (`#00FF33` glow active timer, `#FF3333` alerts); Arabic RTL incl. mirrored progress in overlay + popover; ICU strings shared with web catalogs. | 09 §5 (tray), §7 (Break Enforcer), §8 (hotkeys), §10 (i18n/RTL); 03 §8; 13 §5 |

## 4. Notes & gotchas

- **Only one rule is spec-fixed.** "A break registers only on wearable-detected movement away from the screen, and absence of data never counts" is the whole spec (03 §8.2). Everything quantitative — interval lengths, break lengths, the motion threshold, long-break cadence, daily target — is an **open question / PENDING DESIGN**. Encode only the fail-safe rule as an engine invariant.
- **Interval lengths are PENDING RATIFICATION, not spec constants.** The legacy 25 min work / 5 min short / 15 min long / long break every 4 cycles / daily target 8 is a *precedent to reuse pending ratification*, not a value to hardcode. Keep it in Microkernel config/hook layer so a future doctor "Medical Restrictions" overlay (03 §10) can alter break policy without an engine rewrite. Do **not** let interval numbers leak into `core/` or any client (they would fail the thin-client / SSOT grep audit).
- **The watch/Wear sub-sessions are gates, not extras.** apple and android are **not done** until `apple-watch` (CoreMotion) and `android-wear` (Wear sensors) are done (doc 13 §4, §5). The phone/menu-bar/overlay/extension/desktop must never fabricate a break; a break with no motion evidence is `BreakNotRegistered`.
- **Fail-safe direction is under-credit.** Late-syncing evidence may upgrade `NotRegistered → Registered`; borderline/at-desk motion should *not* credit. All ambiguity resolves to "not registered."
- **Chrome liability.** The extension is content-script-free — it **cannot draw in-page overlays** and must intercept forced breaks via extension-owned surfaces (badge/notifications/side panel). Its activity signal is **evidence only**; the activity-signal mechanism (`chrome.idle` vs. tab events) and its permission tradeoff are PENDING (06 §5.2, §12).
- **Desktop liability.** The Break Enforcer is a full-screen always-on-top *app window*, not an OS lock; it must offer a dismiss path and has no sensor role. Multi-monitor coverage is first-class; Wayland global-hotkey and Linux tray support are open questions (09 §6–§8).
- **PENDING DESIGN carried by this module:** timer/overlay visuals and glow radii/intensities; how an unregistered break is communicated without shaming; Workstation Guard dismissal semantics (apple + desktop); chrome interception aggressiveness; the backend qualifying-movement evidence contract and re-evaluation window; watch↔phone transport for evidence; no-wearable degraded mode.
- **Motion ingest ordering.** The engine depends on the shared `/v1/sensors/...` motion ingest boundary. Confirm whether it is built inside the M8 backend session or supplied by X3 (sensors/biometrics) before starting backend; the watch/Wear sub-sessions cannot report evidence until it exists.

## 5. Handoff reminder

At the end of every M8 session, per doc 13 §6: write **one `session-handoff` memory** to the cabrain `healthdebug` brain (retain, then `memory/edit` to attach metadata — retain cannot set metadata) using the exact handoff content structure, with `source_ref: handoff/M8-kinetic-pomodoro/<surface>/<n>` (unique per session — never reuse) and `metadata` `{project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"M8", 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. `<surface>` values for this module: `backend`, `web`, `mcp`, `chrome`, `apple`, `apple-watch`, `android`, `android-wear`, `desktop`.