Wellness (PPP Pulse)
Algorithm walkthrough → Wellness algorithm: readiness, sleep & workload. The companion page explains exactly how the PPP Pulse readiness score, the sleep recommendation (the source Target Sleep Load model —
hours = max(7, 7 + 3.5 × (1 − e^(−5 × Sₜ))), #7670, envelope re-anchored on #8933 — floor 7 h, ceiling 10.5 h per #8359; supersedes the #8208 6 h floor), and the workload recommendation are calculated, with an interactiveSleepExplorercomparing the live source model against the former readiness-only formula.
Open Questions
Questions for Matt still open. Rows M5 to OQ-READINESS-EMPTY predate the 2026-10-03 Task 10 refresh (#11206). The five rows from OQ-EVENING-PROMPT-TIME down were added by that refresh, built from a dated ledger of everything Matt has said. Earlier answers are resolved per his 3 May 2026 Notion comment. Tracked on audit docs/features/.drift-audits/wellness.md.
| # | Question | Ref | Status |
|---|---|---|---|
| M5 | Supportive alerts — specific trigger for notifying Clinical Supervisor (WHO-5 threshold, Pulse drop, sustain). | Notion brief Q1 | ⏸ Deferred post-MVP per Matt 2026-05-03: "This needs more work defer for later decision". |
| M8 | Revisit Pulse opt-out after first user-testing round — surface genuine edge-case demand (e.g. users who physically cannot wear a wearable) before introducing a toggle. | #5941 | ⏸ Deferred to post-user-testing review (decision 12 May 2026; non-dismissable in v1). |
| OQ-SLEEP-MAP | The source sleep model takes three 0–1 inputs (Workload-load, DaytimeRecovery, MorningReadiness), but the live scorer exposes 17 individual sub-scores, not those three groups. The cell-level mapping is not specified. | #8208, #8461 | ⏳ Narrowed 2026-10-03 (Task 10 refresh). The active recovery half is answered, not open. Matt said on #8461 (2026-06-17, 06-21, 06-22) and on the 2026-07-01 call that active recovery (stretching, ice bath, massage, sauna, compression boots) and meditation (incl. yoga and breathwork) reduce sleep need, detected from wearable-logged activities, and that light exercise is not active recovery. The shipped exclusion of activeRecovery from the recovery group rests on the superseded 2026-06-03 #8089 reading, so it is now drift: see wellness.sleep.active-recovery-reduces-sleep-need (#12747). Still open: curve fidelity, i.e. whether the live curves must match the spreadsheet cell for cell. Rob proposed "accept small divergence" on 2026-06-22. On 2026-06-30 and 2026-07-01 Matt said he cannot choose until he sees the side-by-side numbers, so engineering owes that table on #8461.† † |
| OQ-WORKLOAD-SEVERE | Matt's note describes a severe "Poor readiness — Prioritise recovery today" band below Low, with a proposed < 40 boundary. The exact threshold was parked for post-user-testing on the 2026-05-26 call. | #6161 | ⏳ Shipped with three active bands (High ≥75 / Moderate 50–74 / Low under 50); the Poor band is defined but dormant (low threshold held at 0). Activating it is a one-line low: 0.4 change once Matt confirms the boundary. |
| OQ-READINESS-EMPTY | A newly-connected user (data flowing) with no genuinely-computed readiness score yet — before their first questionnaire + sync cycle — was shown an alarming red 0 / 100 / Low Readiness. What should the not-yet-computed state look like? | #9315 | ⏳ Engineering DEFAULT pending Matt's UX sign-off (for-discussion). Shipped a neutral, friendly onboarding prompt ("Your readiness score builds from your connected health data, such as sleep, heart rate and activity, once it has synced. It does not come from the questionnaire." — #12798; the card does not fill from the questionnaire, so the copy must not promise it) for the not-yet-computed case (score null, or 0 with no contributing metricsUsed); a genuinely-computed low score (metricsUsed > 0) still renders the real low score in red. Awaiting Matt's confirmation of the copy/treatment. |
| OQ-EVENING-PROMPT-TIME | When should the evening sleep-recommendation prompt fire? The shipped rule (from #6430, 2026-05-20) fires off-shift after 14 h awake. Matt's later statements point to a clock time instead. On 2026-05-26 he said "14 hours … potentially miss the mark". On 2026-07-29 he said "I think we decided that would be at 6:00 or 7:00 p.m.". He also raised early finishes and non-work days ("maybe an appropriate time in this instance is 6pm", #6449, 2026-05-20). Should the prompt be a fixed ~18:00–19:00 slot, the 14 h-awake rule, or 14 h-awake with an 18:00 floor for days off? | #6449, #6430, #11206 | ✅ Decided 2026-10-05 (Rob, Task 10 fix lane): build the evening prompt at the ~18:00 slot, off shift and outside the geofence, one prompt per day. The 14 h-awake rule no longer gates firing. Matt has not re-confirmed the exact clock time, so 18:00 is the engineering default (the bedtime-derived ceiling still fires later if the doctor was on shift at 18:00).† † |
| OQ-READINESS-BANDS | On the 2026-05-26 call Matt described the readiness brackets as four: "above 75 and then 75 to 60, 60 to 50 and then below 50", with a lower bracket at 40 "for consideration later". The shipped bands are three (High ≥75 / Moderate 50–74 / Low <50), and the 40 boundary is parked (OQ-WORKLOAD-SEVERE). Before that, on 2026-05-19 (#6161), he had asked for 75+ / 55–74 / 40–54 / <40 with new copy. He then asked to discuss on a call (2026-05-20), so the 26 May version is the newest. Should the 50–74 band split at 60? | #6161 | ❓ Open — added 2026-10-03. The two statements conflict, so this is not an AC change. The 2026-05-19 four-band table with new copy is superseded by the 2026-05-26 call ("go with the first things first").† |
| OQ-TIMESHEET-WEIGHT | Completed timesheet hours now flow into the evening recovery calculation and the next morning's readiness (wellness.readiness.completed-timesheet-hours). Matt has not said how much prior-day hours should weigh in readiness, or whether the evening prompt should mention them. | #11143 | ✅ Resolved 2026-10-04 — applied Matt's existing time-at-work curve and weights.timeAtWork to the prior day's completed hours (Matt on #8461, 2026-06-13: readiness is computed from previous-day factors; Rob on #11143, 2026-07-29: hours feed same-evening recovery and the NEXT morning's readiness, one shared ~18:00–19:00 prompt, never a recalc of a locked score). No new constants and no separate hours notification. |
| OQ-COACHING-REFINE | Task 10's brief ends with "Coaching prompts review of PPP pulse and workload recommendation ?refine of adapt". Does Matt want the approved Moreton Blue prompts (2026-05-13) reworded, or made adaptive (e.g. reflecting a multi-week trend)? | #11206 | ❓ Open — added 2026-10-03. Matt framed this as a question, so no AC was inferred. To answer at the Task 10 walkthrough review. |
| OQ-ALGO-VALIDATION | Matt asked on 2026-09-21 (#12411) for the wellness algorithm's inputs, hierarchy and message accuracy to be validated, and asked whether there is a best-practice method. The Pearson-r-vs-WHO-5 method below was drafted in May for Phase 1 (Matt's own data). Is it the method he wants, or does he want a wider clinical validation design? | #12411 | ❓ Open — added 2026-10-03. Engineering owes Matt a methodology proposal on #12411. Tracked as wellness.algorithm.validated. |
Closed Questions (7) — click to expand
| # | Question | Matt's answer (verbatim) | Resolution |
|---|---|---|---|
| OQ-SLEEP-FLOOR | The source formula's 7.5 h floor made the Normal band (cut-off < 6.5 computed h) mathematically unreachable — the model never recommended under 7.5 h. Retire the band or lower the floor? | — | ✅ Floor set to 7 h. Decision 2026-06-20 (#8933, Matt UAT direction "never recommend below 7 h"): floor raised 6 → 7 h and the envelope re-anchored (floor 7, base 7, ceiling 10.5 h) so all four bands stay reachable — Normal's cut-off (8 h) sits strictly above the 7 h floor, so a Target Sleep Load of 0 recommends 7 h and lands Normal. Supersedes the 2026-06-10 #8208 lower-to-6 h decision (which itself superseded the 2026-05-27 "floor stands as-is" call and the original 7.5 h floor). The #8208 reachability fix is preserved at the 7 h floor. |
| M1 | Manual data entry — keep removed? | "Yes. Data is automatically drawn down from data sources" | ✅ Confirmed kept removed;as expected behaviour. |
| M2 | Sleep wake target derivation? | "Unsure what is meant here; User wakes up when they wake up; Sleep recommendation based on workload of the day and previous recovery as set out by the algorithm" | ✅ Reframed — drop wake-target field entirely. Sleep recommendation is computed from workload + previous recovery via the algorithm; no user-supplied wake target needed. #4872 to be re-scoped or closed. |
| M3 | Debug Portal custom baselines — engineering proposal: keep dev-only test fixture used by the Frasers QA team to drive deterministic readiness/sleep scenarios; never flows to backend scoring; UI shows a "dev override active" badge whenever a non-default baseline is in effect; production users always see canonical scores. | — | ✅ Engineering decision — Debug Portal is a QA tool, no user-facing impact, no Matt sign-off required. (#4868) |
| M4 | Coaching-prompt tone — style guide? | "please send me the style guide you refer. Ill prescribe coaching prompts once cuts out and baseline from moreton blue work provided. Agree never lecture." | 🔧 Engineering action — drafted at wellness/coaching-style-guide.md; shared with Matt for prompt prescription once Moreton Blue baselines are provided. |
| M6 | Integrations v1 priority? | "WHOOP→ Apple Health Kit →Samsung/Google/Android → Garmin → Aura" | ✅ Order locked — WHOOP → Apple HealthKit → Samsung Health/Google Health/Android Health → Garmin → Aura. (Engineering had proposed Garmin third; Matt's order moves Samsung/Google/Android ahead of Garmin.) |
| M7 | PPP Pulse algorithm — acceptance criteria for "further testing"? | "Further testing will first include me using the app in functionality connecting to my whoop and Apple Health; then we can determine further user testing. Keen to understand methology for correlation coefficient" | ✅ Phased — Phase 1: Matt self-tests via WHOOP + Apple Health to validate end-to-end correlation. Phase 2: expanded user testing scope TBD post-Phase 1. Methodology note added below. |
Correlation coefficient methodology (Matt M7 follow-up)
PPP Pulse algorithm output is correlated against the WHO-5 weekly questionnaire score using Pearson's r. WHO-5 is a validated wellness instrument; for a wearable-derived composite to be considered a useful proxy we expect r > 0.5 sustained across ≥ 4 consecutive weekly cycles (typical threshold for validated wellness instruments). Phase 1 will run this against Matt's own dataset only; Phase 2 expands the cohort once Phase 1 r-values clear the threshold.
Feature Overview
Wellness tracks doctors' physical and mental wellbeing by integrating wearable data (WHOOP, Garmin, Apple Health, Health Connect) and correlating it with their work schedule. The goal is early detection of burnout and fatigue — surfacing actionable guidance to the doctor before it becomes a crisis.
PPP's wellness philosophy: data hierarchy means wearable data takes precedence over manual entry over phone-derived data. Manual entry should be a last resort, not the default.
Original Vision
Data Sources (priority order)
V1 priority order (locked per Matt 2026-05-03 — see Integrations):
- WHOOP — primary integration (API, HRV, recovery score, sleep)
- Apple HealthKit (iOS) — second priority
- Samsung Health / Google Health / Android Health — phone fallback (parallel)
- Garmin — integration planned
- Aura
- Manual entry — removed per Matt 2026-05-03 (data drawn automatically from sources)
Key Metrics
- Readiness / Recovery score — overall daily readiness (0–100)
- HRV (Heart Rate Variability) — average HRV vs personal baseline (not "HRV deviation" — that terminology was wrong and corrected in #3588)
- Sleep — duration and quality
- Strain / Workload — activity load
- PPP Pulse — PPP's own composite score combining multiple metrics
Dashboard Display
- Readiness score prominently displayed
- HRV: "above/below personal average" context (#3645)
- Pulse chart showing trends over time
- Sleep guidance card
- Workload guidance card
- When no source connected: show "connect your data" prompt, not zeros or static values
Onboarding Integration
- "Connect your data" prompt surfaces during onboarding for all wearable providers (#3646)
- Guidance on which devices are supported
Matt's 17 Apr 2026 Notion Brief — Requirements Update
Source: PPP Pulse — Wellness Notion brief.
Framing
- Market gap: current wearables don't reflect what surgeons actually need for rest (per Matt's experience).
- Regulatory anchor: ISO 45001 requires industry to address Psychosocial OHS.
- Evidence of need: Queensland Health Nov 2025 survey — 49% of junior doctors at risk of burnout.
Purpose
Industry-specific tool to raise self-awareness and support meaningful behaviour change — not a generic wellness app.
Functions
- Weekly Wellness Questionnaire (WHO-5 instrument) — WHO-validated, weekly cadence with reminders.
- PPP Pulse proprietary algorithm — built; needs further testing.
- Reminders and coaching prompts — around capacity and need for rest. Tone matters: acknowledge that doctors have roles and responsibilities; sometimes they work at increased capacity for a period and rest later. Comms must reflect this, not lecture.
- Mapped insights — correlate weekly wellness questionnaire results with PPP Pulse algorithm output.
Integrations
V1 priority order (locked per Matt 2026-05-03):
- WHOOP
- Apple HealthKit
- Samsung Health / Google Health / Android Health (parallel — same OS-level data store)
- Garmin
- Aura
PPP Pulse Score Brackets & Coaching Prompts
Status: Wording is final (Moreton Blue, confirmed 2026-05-13). The strings in
api/backend-ppp/src/services/wellnessService/readiness/scoring/scoreService.ts(DEFAULT_GUIDANCE_CONFIG) are canonical. No emojis — per Matt, emojis read as AI-generated and undermine the clinical positioning.
v1 dismissibility (12 May 2026, #5941): PPP Pulse is non-dismissable in v1 — revisit post user-testing. There is no user-facing toggle to disable PPP Pulse, and no backend flag for per-user Pulse opt-out. PPP Pulse is a core USP; an opt-out path is deferred until first-round user testing surfaces genuine edge-case demand (e.g. users who physically cannot wear a wearable).
- ✅
wellness.coaching-prompts.matt-approved— coaching prompt copy approved by Matt on 2026-05-13. Moreton Blue strings inDEFAULT_GUIDANCE_CONFIGare canonical for Workload Recommendation, Sleep Recommendation, and all wellness nudge notifications. (supersedes the earlier #5982 gate)
Readiness Score (displayed 0–100)
The Readiness Score card classifies the score with the same bands the Workload Recommendation uses — they are one shared source of truth (READINESS_BAND_THRESHOLDS in packages-shared/ppp/src/constants/wellness.ts), so a given score can never read as one band on the Readiness card and a different band on the Workload card.† Before #8637 this card carried its own High ≥ 85 / Moderate ≥ 70 / Low ≥ 50 / Poor < 50 ladder, which contradicted the Workload bands below. The High band sits at 75 for the same reason it does for Workload (the live algorithm rarely scores into the 90s, so 85 made High unreachable — Matt 2026-05-13, #6161), which also resolves the standing "an 81 should read green" mismatch (#8199). The severe Poor band is parked pending Matt's < 40 boundary (OQ-WORKLOAD-SEVERE, #6161) — everything below 50 reads Low today. (#8637)
| Band | Score | Label |
|---|---|---|
| High | ≥ 75 | High readiness |
| Moderate | 50–74 | Moderate readiness |
| Low | < 50 | Low readiness |
| Poor | (parked, < 40 TBD) | Poor readiness — dormant until Matt confirms the boundary (#6161) |
Sleep Recommendation
Recommended sleep hours follow the source spreadsheet's three-input Target Sleep Load model ("Wellness Algorithm Comm.xlsx", cells E30–E34) — the design of record. The recommendation responds to the day's workload and daytime recovery, not the readiness score alone.† † † (#7670, reverts the readiness-only drift flagged on #6161)
Sₜ = max(0, Workload × (1 − DaytimeRecovery) × (MorningReadiness < 0.5 ? 1.2 : 1))
hours = max(7, 7 + 3.5 × (1 − e^(−5 × Sₜ)))Amplifier recalibration (#8435): the morning-readiness amplifier was retuned from trigger < 0.7 / factor ×1.5 to trigger < 0.5 / factor ×1.2. The live algorithm rarely scores into the 0.7s on a normal workload, so the old 0.7 trigger fired the ×1.5 amplifier on virtually every working day, over-inflating the Target Sleep Load and tipping average days into Enhanced/Maximise. The new trigger reserves the amplifier for genuinely low-readiness days and the gentler ×1.2 factor flattens the curve so an average day lands Moderate, not Enhanced. The 0.5 / 1.2 values are an engineering proposal adopted per user direction and should be re-validated against Matt's spreadsheet.† (#8435)
The curve shape is the spreadsheet's; the envelope was re-anchored on 2026-06-20 to 7–10.5 h (floor 7, base 7, ceiling 10.5 — the ceiling sits half an hour above the Maximise cut-off so the 10 h+ band stays reachable, #8359) so the model never recommends below 7 h while keeping all four bands reachable (Normal's cut-off of 8 h is strictly above the 7 h floor) — see the Closed Question OQ-SLEEP-FLOOR. Supersedes the 2026-06-10 #8208 6 h floor per Matt's UAT direction.† (#8933, supersedes #8208)
Band labels. The Cut-off is the internal computed-hours threshold that selects the band — since #8359 (option A, Matt 2026-06-09) it is derived from the Range via the shared SLEEP_BAND_CUTOFFS constant, so a computed value always lands in the band whose range contains it.† The Range is Matt's locked display range (2026-05-27, "lock that in"), held in the shared SLEEP_BAND_RANGES source of truth and shown both in the prompt text and as the card headline.† † (#7670)
| Band | Cut-off (computed hours) | Range | Prompt (canonical, verbatim) |
|---|---|---|---|
| Normal | < 8 | 7-8 | Normal recovery: aim for 7-8 hrs |
| Moderate | < 9 | 8-9 | Moderate recovery: aim for 8-9 hrs |
| Enhanced | < 10 | 9-10 | Enhanced recovery: aim for 9-10 hrs |
| Maximise | ≥ 10 | 10+ | Maximise recovery: target 10+ hrs sleep |
The Normal range floor was raised "6-8" → "7-8" on #8933 so the displayed range matches the model's raised computed floor: the Target Sleep Load model now floors at 7.0 h (SLEEP_MIN_HOURS, scoreService.ts), so a well-recovered day recommends 7 h, and the card reads "aim for 7-8 hrs". The cut-off is unchanged (the band's upper bound, 8 h, still selects Normal, so the band stays reachable above the 7 h floor). Supersedes the #8656 "6-8" copy that matched the old 6 h floor.† (#8933, supersedes #8656)
The Sleep Guidance card headline shows the band range (e.g. "8-9 h"), not a single number — Matt confirmed this display on 2026-06-03 ("it should be B").† † (#7670)
Note: the original 7.5 h floor made the Normal band (cut-off < 6.5 h) mathematically unreachable. The floor was lowered to 6 h on 2026-06-10 (#8208), then raised to 7 h on 2026-06-20 (#8933, Matt UAT "never recommend below 7 h"); the envelope was re-anchored (floor 7, base 7, ceiling 10.5) so all four bands stay reachable — Normal's cut-off (8 h) is strictly above the 7 h floor, so a light, well-recovered day reads Normal at exactly 7 h. See OQ-SLEEP-MAP (still open, tracked on #8461) for the live-sub-score → model-input mapping.
Missing-data semantics (#8458): the DaytimeRecovery input averages only the recovery components that have data for the day; a fully absent recovery group reads as neutral (0.5) — unknown recovery is not zero recovery. Workload components keep fail-soft absence semantics (zero input already scores as no observed load). Before this, any day without wearable data collapsed DaytimeRecovery to 0 and read Enhanced/Maximise — the "average day reads high" symptom on #8435.† (#8458)
Overall-score presence-gating (#8435): the overall readiness score itself is renormalised over the components that have data for the day —
Σ(weight · sub-score | present) / Σ(weight | present)— instead of letting absent components fold in their zero-input default sub-score. Absent components are not observations: the penalty sub-scores (timeOnPhone, trainingStrain, stressTime, restingHr, respiratoryRate, coreTemperature) score 1.0 at zero input and the recovery sub-scores (sleep, hrv, spo2, meditation, activeRecovery, hrvDeviation) score 0 at zero input, so a sparse-data day was scored on defaults rather than on what was measured. When every component is present — a full wearable + timesheet + logbook day, as the pinned integrity-test datasets are — the present-weight sum is 1.0, so the renormalised score equals the legacy weighted sum exactly and historical full-data scores are unchanged. This is the companion fix on the overall-score side to the #8458 DaytimeRecovery presence-gating above. Engineering approach adopted per user direction — re-validate against Matt's spreadsheet.† † (#8435)
Workload Recommendation
The Workload card fires in the morning and reads only the readiness score — the single 0–100 number already shown on the Pulse widget. No other inputs. The score lands the doctor in one of three bands, and each band shows a fixed prompt and a traffic-light colour (green / amber / red). The thresholds below are on the internal 0–1 scale; the doctor sees the 0–100 equivalent (e.g. 0.75 → 75).† † (#6161)
| Band | Readiness score | Light | Prompt (canonical, verbatim) |
|---|---|---|---|
| High | ≥ 75 (0.75) | 🟢 green | High readiness — OK to proceed with full workload |
| Moderate | 50–74 | 🟡 amber | Moderate readiness — Consider moderating intensity and complex demands |
| Low | < 50 | 🔴 red | Low readiness — Consider reducing demanding tasks and plan more rest |
Why the top band moved from 85 to 75 (Matt, 2026-05-13): the live algorithm rarely produces scores in the 90s, so an 85 cut-off made "high readiness" hard to attain and less reflective of a doctor's actual state. Dropping it to 75 makes the High band realistically reachable.
Severe "Poor" band — parked. Matt's note also describes a fourth, more severe state below the Low band ("Poor readiness — Prioritise recovery today"). The exact boundary for it (proposed < 40) is parked for post-user-testing (agreed on the 2026-05-26 call), so it is not yet active: today everything below 50 shows the single Low prompt. The Poor copy and level are already defined in code so that activating the severe band later is a one-line threshold change. Tracked as OQ-WORKLOAD-SEVERE.
Visual treatment of the traffic light: shipped as a left-edge stripe on the readiness, workload and sleep cards (#8199, PR #8493) — the recommended treatment from Matt's 03-Jun colour-coding direction, swappable to dot/chip in minutes if he prefers at the Tuesday walkthrough. No emoji; text band labels remain alongside colour.
Supportive alerts
- Optional: notify Clinical Supervisor to check in with user when a trigger is satisfied.
- Trigger criteria — TBD (Matt).
Reference
Algorithm spreadsheet outlines information hierarchy for each input — referenced in gdrive-sources of this spec.
Draw schedule (engineering-led, 5 May)
Pulse, Workload Recommendation, and Sleep Recommendation re-compute on a fixed daily cadence per user. Resolves the open ask in #5563.
| Trigger | When | Recomputes |
|---|---|---|
| Morning draw | 06:00 user-local OR first foreground app event after 06:00, whichever is earlier | Pulse, Workload Recommendation, Sleep target |
| Evening draw | Shift-agnostic (12 May 2026, #5940; thresholds set 20 May 2026, #6788): fires when the user is outside a hospital geofence, not on an active shift, AND the 18:00 user-local slot has been reached (Rob 5 Oct 2026, from Matt 29 Jul on #11148; this replaced the ≥ 14 h-awake rule, and an hourly tick retries until the prompt is sent). Latest-prompt fallback is bedtime-derived: wake_target − recommended_sleep_hours (no clock-time ceiling). Supersedes the prior fixed 18:00 → 21:00 push rule and the earlier 21:00 clock fallback. | Sleep Recommendation only (using today's strain) |
| Manual refresh | "Refresh now" button on the wellness widget — rate-limited 1× per 5 min per user (the button was added in #4859; the limit itself was built in Task 10 wave 2, #12970: a manual refresh sends manualRefresh: true and a second press within 5 minutes returns "You can refresh once every 5 minutes"); covers ad-hoc force-recompute | All three |
The evening draw no longer uses a fixed 18:00 local trigger. Instead it is shift-agnostic: the notification fires when the user has left the hospital geofence and has been awake long enough that a sleep recommendation is meaningful. Implementation: eveningDrawTriggerService reads the latest geo_fence_events row to determine inside/outside-geofence state; "awake duration" derived from estimated sleep offset or last morning-draw timestamp.
Geofence success criterion — updated 2026-07-10 (#9257, supersedes the 2026-06-24 #9547 correction): Once the mobile client is wired (Option (b), decided on the #9257 thread 2026-07-08/09) to POST enter/exit to
geoFenceEventService.recordEntry/logExiton the background geofence handler,geo_fence_eventslegitimately accumulates rows from the mobile path (matching the pre-existing web Smart-GeoTag path). The "0 rows expected... independent of #9257" framing is now stale —timesheets.source='geofence'remains the operational trigger signal, butgeo_fence_eventsbecomes the intended dwell/audit analytics trail for both platforms, not a path expected to stay empty.
Thresholds set (2026-05-20, #6788): Matt's sign-off on #6430 confirmed: awake threshold N = 14 h; clock-time ceiling removed and replaced with a bedtime-derived ceiling (latest_prompt_time = wake_target − recommended_sleep_hours). The bedtime ceiling reuses calculateSleepTimingGuidance so the ceiling adapts per-user and per-day rather than firing at a fixed clock hour. Wearable-driven wake_target plumbing follows in a later ticket; for now the evaluator falls back to 06:30. See docs/site/research/wellness-evening-pulse-timing.md for the evidence base.
Rebrand (engineering-led, 5 May)
User-facing strings rebrand WHO-5 → "Weekly Wellness Questionnaire" across the app. Internal constants, schema column names, and clinical/compliance documentation retain WHO-5 so the validated-instrument provenance is preserved. One-shot string sweep in instances/ppp/src/modules/WellnessScore/** plus reminder/notification copy.
Integrations list (engineering-led, 5 May)
Per Matt's brief: WHOOP, Garmin, Apple Health, Samsung Health, Google Health, Aura.
- Garmin — Developer Program is currently paused (Apr 2026, no published ETA). Existing code is mothballed; UI surfaces a "Garmin connection paused — sign up for the waitlist" tile rather than a connect button. Re-enable when Garmin re-opens the program.
- Aura (Oura Ring) — ✅ shipped: full OAuth connect/callback/disconnect plus provider client/mapper/sync (
ouraOAuth.ts,providers/oura/,OuraCallbackContainer.tsx). "Aura" is Matt's spelling of the Oura Ring. - Samsung Health — not yet started; tracked under
wearables-roadmapfollow-up. v1 priority order remains WHOOP → Apple HealthKit → others (Q M6).
Acceptance Criteria
Data Sources & Hierarchy
- ✅ WHOOP pulls live HRV, recovery, sleep, strain (#4646) — ⚠️ Bug (Apr 2026): wearables data pipeline was not delivering data; flagged for testing green-light † †
- ⏳ Production WHOOP OAuth app registered before prod deploy (#4700)
- ✅ Garmin Health API credentials obtained and configured (#4677)
- ⏳ Garmin body-composition mapper extracts weight and BMI (#4651, blocked on #4646)
- ✅ Apple HealthKit verified end-to-end on Matt's device (#4646)
- ✅ Apple Health 24-hour polling deployed to wellness ingest endpoint (#4826)
- ✅ Google Fit removed from Connect Your Data; Health Connect added as device source (#7929) † †
- ✅
wellness.data.health-connect-connection-contract— the connection-management procedures (getStatus/connect/disconnect) accepthealth_connect, matching whatgetAvailableSourcesadvertises, so the advertised device source no longer returns a validation error (#8029) † - ✅ Aura / Oura Ring OAuth connection ("Aura" is Matt's spelling of the Oura Ring) — full OAuth connect, callback, disconnect, and connection-info flow plus provider client/mapper/sync. † † † †
- ✅
wellness.data.fitbit-removed— Fitbit is fully removed as a supported integration (Fitbit Web API retiring in favour of Google Health Connect). Phase 1 (#8667) removed it from the connectable surface (data-integrations list, available-sources API, connect UI). Phase 2 (#8690) purged the dormant backend stack: the Fitbit provider module (client/mapper/syncService/types), the Fitbit OAuth service + router, the Fitbit adapter and its registrations,constants/fitbit.ts, the Fitbit branches in the scheduler/sync/provider-priority/metric-type/scoring configs, the frontend Fitbit callback components + route, the Fitbit doc references, and the unused Fitbit env keys — together with all their tests. TheFITBITenum value (inDATA_SOURCES) and its entry in thedataSourcesrouterDataSourceSchemaare retained so a user with a pre-existing historical Fitbit connection can still see it as connected and disconnect it via the generic disconnect path (no Fitbit-specific OAuth revoke remains). Supersedes #4865. (#8667, #8690) † † - ✅
wellness.data.sources-panel-cleanup— the data-sources panel shows each phone health source exactly once (the duplicate "Health Monitoring" device card was removed), co-locates the device-permissions guidance inside the Phone Health Data panel rather than a separate block, and no longer labels phone sources "Coming Soon" on desktop — instead explaining the connection must be completed in the PPP mobile app. (#8667) † - ✅ Android Health tab shows connection UI, not "Not implemented" (#4890)
- ✅
wellness.data.connection-status-refetch-on-focus— data-source connection status refetches on page/app focus so the native app matches web (#8334) † - ✅
wellness.data.truthful-connection-state— a wearable source reports connected only when valid OAuth tokens exist; a granted-but-token-less state (provider authorised, no tokens persisted) renders as needs-reconnect, never as connected. Sync failures surface to the user instead of being silently skipped, and the WHOOP OAuth callback persists tokens so the user lands in a genuinely connected state rather than bouncing back token-less. The same post-write read-back verification now guards all three OAuth providers — WHOOP, Oura, and GarminhandleCallbackre-load the tokens after storing them and surface anINTERNAL_SERVER_ERROR(never a false "connected") if the write silently no-op'd, closing the badge-says-connected-but-no-tokens failure class on every provider. A successful reconnect also clears any stalelastSyncStatus/lastErrorleft over from before the reconnect —evaluateConnectionTruthpins ANY errored connection to needs-reconnect regardless of token freshness, so without the reset a genuinely-reconnected source stayed stuck reporting "Reconnect needed" forever (the card only offers Reconnect, not Sync Now, in that state, so the user could never escape the loop).storeTokenson all three providers now resets both fields on every successful token write, and the OAuth callback additionally kicks a fire-and-forget backfill sync (a sync failure logs a warning and does not fail the callback — the connection is legitimately established and the scheduled poll retries) so data reappears immediately instead of waiting for the next scheduled poll. (#8632, #8634, #8874, #10196) † † † † - ✅ Manual entry removed from Sync Data and Debug Portal
- ✅ No source connected shows prompt, not zeros
- ✅ Data hierarchy enforced end-to-end: wearable > phone > manual
- ✅ Dashboard waits for
getConnectedbefore rendering empty state - ✅
wellness.data.missing-not-zero— an absent biometric reading is treated as missing, never as a measured0. The readiness calculator'sgetMetric()returnsnull(was0) when no record exists for a metric, so a genuinely measured0and an absent reading are distinguishable; the biometricScoreInputsfields (hrvMs,restingHrBpm,respiratoryRate,coreTempDeltaC,spo2Percent,hrvDeviationMs) are typednumber | null. The display layer reads the realnull— an absent HRV renders--(viaRecoveryGaugeCard) instead of a fake0 ms— while the scoring formulas coercenull → 0at the formula boundary, so the computed readiness score is byte-identical to the prior absent-as-0behaviour (presence-gating #8435/#8458 already excludes absent components from the score). Closes the "HRV0 ms/ Resting HR blank" symptom family with #10149. BDD regression scenario:@regression @issue-10182inwellness-core.feature. † (#10182) - ✅
wellness.data.source-aware-provenance-badge— the recovery dark-panel badge names the source that actually produced the metric — "from WHOOP" / "from Apple Health" / "from your phone" — instead of the former hardcoded "WHOOP Connected", which always claimed WHOOP regardless of the real winning source. Named wearables (WHOOP / Garmin / Oura) are surfaced by name; phone stores (Apple Health / Health Connect / Samsung Health) collapse to a single friendly "from your phone"; an unknown/omitted source also reads "from your phone" (never a false WHOOP claim). The recovery-panel prop bag is renamed from the WHOOP-specificwhoopDatato the source-neutralrecoveryData, threading the winning source (fromresolveSource) through to the badge. This is the engineering-only slice of #10182 — the multi-source "peek" / side-by-side value display and thegarmin-above-apple_healthordering stayfor-discussion/ Matt-gated and are not built here;resolveSourceselection is unchanged. BDD smoke scenario:@smoke @issue-10182inwellness-core.feature. † (#10182) - ✅
wellness.data.recovery-panel-wired-to-production— the Row 2 recovery dark-panel (RecoveryGaugeCard/DayStrainCard/SleepStagesCard) and the source-aware provenance badge are now populated from real backend data in the live app, not only in Storybook. The production container (WellnessScore/index.tsx) fetches a per-day recovery payload via a newgetRecoveryPanelread (getRecoveryPanelForDate, which reusesgetMetricsForDate— already deduplicated to the per-metricresolveSourcewinner) and passes it as therecoveryDataprop bag. This closes the implementation gap the #10182 provenance-badge andmissing-not-zeroACs anticipated: those fixes were correct but invisible becauserecoveryDatawasundefinedin production, soDashboardViewskipped the whole{recoveryData && (...)}block. Absent biometrics thread through asnullend-to-end (missing ≠ zero — theRecoveryGaugeCard-- msdisplay is exercised with live data), and the HRV winner drives the badgesource. Panel fields with no backing metric (recovery %, day strain, calories, WHO-5 wellbeing) staynullrather than a fabricated0; the sleep-stage breakdown is left unpopulated because the backend measures only deep/REM minutes, not the full Awake/Light split the stacked bar needs. Out of scope, stillfor-discussion/ Matt-gated (from #10182): the multi-source "peek" / side-by-side value display and thegarmin-above-apple_healthordering. BDD smoke scenario:@smoke @issue-10335inwellness-core.feature. (#10335) Correction (2026-08-12, #11486): the "staysnullrather than a fabricated0" guarantee held in the payload but NOT on screen for day strain.DayStrainCardcoercedstrainScore ?? 0beforetoFixed(1), so an absent reading rendered as a confident0.0 / 21— a measured value the user never recorded — while the card's own Avg/Max HR rows correctly rendered--, which is why the symptom was reported as "0.0 with--HR". The headline number now renders--when the reading is absent, matching the sibling rows and restoringwellness.data.missing-not-zero. The 14-bar strain chart carried the same defect via a hardcodedDEFAULT_STRAIN_HISTORYdemo array — the identical trap #10236 removed fromSleepStagesCard'sDEFAULT_STAGES— and since the container passesstrainHistory: [], every real user saw 14 bars of invented strain presented as their own fortnight; the chart is now omitted entirely when there is no real history. Note the underlying data gap is unchanged and is NOT a display bug:whoopMapperreadsstrain/average_heart_rate/max_heart_ratefrom the WHOOP API but persists none of them (the LIVE mapper —readiness/providers/whoop/whoopMapper.ts, reached viawhoopAdapter→whoopSyncService.mapAllWhoopData— emits onlyhrv,resting_hr,spo2,core_temperature,sleep_duration,deep_sleep,rem_sleep,respiratory_rate,active_recovery_minutesand the per-sessiontraining_minutes_session_N/training_intensity_session_N, and contains zero references toaverage_heart_rateormax_heart_rate; day strain is a CYCLE-level field and the live sync never fetches cycles at all —whoopClient.getAllCyclesexists and is tested but has no production caller. Note there is a second, ORPHANEDwhoopMapper.tsunderreadiness/adapters/providers/which is imported only by its own tests (#11499); it implementshrv_deviation,meditation_timeandstress_period_*that the live one lacks, so reading it gives a materially different — and wrong — picture of what PPP actually persists).RecoveryPanelResulthas no strain/HR/calorie fields, so the panel is honestly empty rather than wrongly zero. Persisting those metrics end-to-end is a separate feature gap. Closed for strain and heart rate (2026-08-15, #11502):whoopSyncServicenow callsclient.getAllCyclesat BOTH sync call sites,whoopMappergainedmapCycleMetrics(withmapAllWhoopDatataking cycles as a 4th argument),day_strain/avg_hr/max_hrare registered metric types,RecoveryPanelResultexposesstrainScore/avgHrBpm/maxHrBpm, and the container reads those real fields instead of hard-codednulls. Day strain is stored raw on WHOOP's 0-21 scale — deliberately distinct from the per-workout strain thatmapWorkoutMetricsnormalises to a 0-2 training intensity. Cycles are attributed to a calendar day by their START time, because a cycle runs from waking past midnight and itsendisnullwhile still in progress, so attributing byendwould both shift the day's strain forward and drop the current day entirely. Themissing != zeroguarantee is preserved at the mapper: WHOOP reports0rather thannullfor an unrecorded heart rate and 0 bpm is not physiologically possible, so those are omitted (card renders-- bpm), while a genuine0day strain IS a real measurement (a fully rested day) and is emitted. All three are also registered inPROVIDER_PRIORITYas single-entry[whoop]lists — explicit rather than omitted, becauseresolveSourcefalls through toavailableSources[0]for any metric with no priority entry, which would make the winning source undefined the moment a second provider started emitting them. Closed for recovery percent and calories (6 Oct 2026, Task 10 wave 2, #12969):mapRecoveryMetricsnow emits WHOOP's ownrecovery_score(0-100 percent; omitted while the user is still calibrating) andmapCycleMetricsemitscalories_burned(the cycle'skilojouleconverted to kcal; omitted when 0), both registered metric types with single-entry[whoop]priority lists;RecoveryPanelResultcarriesrecoveryPercent/caloriesBurnedand the container reads them instead of hard-codednulls. Provenance: when the day has no HRV reading the badge now takes the winning source of another panel metric instead of falling back to the phone label (#12971). Still open: sleep efficiency, WHO-5 wellbeing and the multi-daystrainHistoryseries remain unbacked — the recovery panel is a single-day payload, so the 14-bar chart stays omitted. The orphanedreadiness/adapters/providers/whoopMapper.tsis untouched and remains #11499's concern. † (#11486) - ✅
wellness.data.biometric-priority-tail—health_connectandsamsungare ranked at the tail of thehrv,hrv_deviation,deep_sleep,rem_sleepandrespiratory_rateper-metric priority lists (they were already on the sleep-duration / resting-hr / phone lists via #9023/#9638 but missing from these), so an Android phone-store biometric resolves to a defined rank —health_connectahead ofsamsung, both behind the wearables — rather than falling through toavailableSources[0]. Thegarmin-vs-apple_healthinversion on these lists is left untouched (Matt-gated);health_connectsimply lands after whichever of them sits last. † (#10182) - ✅
wellness.phone-derived-fallback— when no wearable is connected but a phone health source (Apple HealthKit, Samsung Health, Google Health) is available, Pulse score is derived from phone-sourced step count, activity minutes, and sleep data using a reduced-confidence algorithm. The score is rendered with a visual indicator ("Estimated from phone data" Chip on the Readiness Score card) to signal lower confidence vs a wearable-sourced score. The data hierarchy (wearable > phone > nothing) is enforced viaclassifyScoreSource— wearable wins on every read, so connecting a wearable immediately supersedes the phone-derived score without a backfill. (21 Apr 2026) - ✅
wellness.data.phone-fallback-insight— when a user has no wearable connected, the system still surfaces a wellness insight using phone-derived data (step count, activity minutes, sleep); fidelity is explicitly lower and communicated to the user. Implemented viaclassifyScoreSourceand the phone-fallback scoring profile (#5984): when no wearable source is present but Apple HealthKit / Health Connect / Samsung Health metrics are available, the Pulse score is computed from step count, active-minute, and sleep inputs using the reduced-confidence weight profile, and the Readiness Score card renders the "Estimated from phone data" Chip so the lower fidelity is explicitly communicated. (20 May 2026) † (#6427) - ✅
wellness.settings.in-app-config-screen— the mobile app provides an in-app settings screen allowing users to manage preferences such as location services and health monitoring permissions. Users who make a mistake during onboarding can reset their preferences without leaving the app. Implemented as/wellness/settingsroute (HealthSettings.tsx) with the Connected Data Sources and Location Services panels; "Check Sources" button on the wellness dashboard navigates here instead of the old/my-profile#wellness-data-sourcesdetour. Route gated byRequirePppAccess. Layout is action-first: the Connected Data Sources panel is surfaced at the top so connect/disconnect needs no scrolling. The standalone "Health Monitoring" device card was removed because it duplicated the Phone Health Data panel, and its device-permissions guidance is now co-located inside that panel (#8667); the full step-by-step permission walkthrough remains in the Data Integrations guide reached via a header help (?) link. † (#7024) - ✅
wellness.ui.header-help-icon-placement— the help (?) affordance on wellness page headers sits immediately beside the heading text, never floated to the far-right edge of the title row. Both the Wellness Dashboard and Health Monitoring Settings render the title + "?" throughPageHeader'shelpGuideSectionprop (a button sibling of the<h1>, so the heading accessible name stays clean) rather than in the far-rightactionsslot beside the date picker. Health Monitoring Settings originally hand-rolled that flex row inline — the same visual result, but a<HelpButton>glued straight after the titleTypography, which is exactly the placementdesign-system.page-header.help-first-in-actions(#9213) bans; it now delegates to the shared atom instead of re-implementing it (#11534). This brings both wellness headers onto the canonicalPageHeaderpattern established for the app title standard (#9887/#9213). BDD regression scenario:@regression @issue-10065inwellness-core.feature. † (#10065) - ✅
wellness.settings.data-sources-deep-link—/wellness/data-sourcesis a registered route alias that redirects to the canonical/wellness/settingssurface, so native-app deep links and onboarding checklist callers that targeted the former path no longer hit a 404. The onboarding step route was updated to point directly at/wellness/settings. (#9254) - ✅
wellness.data.apple-health-connect-deeplink— inside the native app, a phone-only (mobileOnly) data-source card offers a real Connect button that opens the native health connect screen. Previously the web Data Sources page rendered thesemobileOnlycards as hint text only ("Connect via the PPP mobile app"), so inside the native shell the user was stuck on "Not Connected" with no affordance to reach the native connect flow. The card now detects the native shell (isReactNativeWebView) and renders a semantic MUI Connect button whose click posts anavigateToTabsbridge message for the(tabs)/healthroute, which the WebView resolves to the platform-aware native Health connect screen (Apple Health on iOS; Health Connect / Samsung Health on Android). Unblocks #8977 by giving users a path to the Apple Health connect screen from the app. BDD regression scenario:@regression @issue-9284inwellness-data-sources.feature. ‡ (#9284) - ✅
wellness.data.phone-sources-device-aware— the Phone Health Data section of the Data Sources page is device-aware. Inside the native app it shows only the phone health source(s) that match the device's OS — Apple Health on iOS; Health Connect (plus Samsung Health, when its metadata is present) on Android — each with the in-app Connect button; the other platform's cards are hidden. On web (desktop or mobile browser, i.e. not the native shell) the three connectable phone cards — which cannot be connected from a browser — are replaced by a single concise message: phone health sources (Apple Health on iPhone, Health Connect or Samsung Health on Android) are set up in the PPP mobile app, so open PPP on your phone to connect. The OAuth "Wearables & Apps" section (WHOOP / Garmin / Oura) is unaffected — those connect via web OAuth on every platform. OS detection is best-effort fromnavigator.userAgent(iPhone|iPad|iPodfor iOS,Androidfor Android), SSR-safe, with an unrecognised user-agent falling back to showing all phone sources. The section is kept tidy and minimal-scroll: inside the app it reduces to the heading + the single device-matching card (rendered compact) with a clear Connect CTA and a one-line permissions help caption — the redundant "Get started with your phone" info Alert, the long intro paragraph, and the boxed device-permissions callout were removed (consolidated, not stacked). Change (2026-07-01, #9907, for-discussion): the panel is now wrapped in anAccordionthat defaults to collapsed (matching the profile page's folded-panel pattern), so the Connect action requires one tap to reveal rather than sitting above the fold as originally specified here — this reverses part of this AC's original tap-free intent and has not yet been confirmed with Matt; flagged for his review. BDD regression scenarios:@regression @issue-9284inwellness-data-sources.feature. ‡ (#9284) - ✅
wellness.data.smart-open-app-button— on mobile web (a phone browser, not the native shell) the Phone Health Data panel shows a smart "Open PPP app" button. Tapping it deep-links into the installed app viappp://wellness(the same scheme #9814 routes to the Wellness tab) and, if the OS does not foreground the app within ~1.5 s — detected by avisibilitychange/document.hiddenguard, which cancels the fallback when the page is backgrounded — falls back to the correct platform store: the Play Store by package on Android, and on iOS a directapps.apple.com/app/id<N>link once PPP has a public App Store id (an App Store search for the app while it is TestFlight-only, since there is no numeric id yet). Platform is detected fromnavigator.userAgentviagetMobilePlatform(iPhone|iPad|iPod→ iOS,Android→ Android). On desktop web the panel keeps its static "set up in the PPP mobile app" pointer with no button, since there is no app to deep-link into. Engineering default from Rob's ask — not yet Matt-confirmed. BDD:@smoke @issue-9907(desktop no-button branch) inwellness-data-sources.feature; the iOS/Android button branches are covered by theDataSourcesViewandopenMobileAppvitest suites (which mocknavigator.userAgent). † ‡ (#9907) - ✅
wellness.data.health-connect-ingest— Health Connect (react-native-health-connect) is the primary Android device-push path for non-Samsung devices (Pixel, OnePlus, Xiaomi, etc.). The mobile app reads sleep stages, heart rate, HRV, respiratory rate, SpO2, steps, active energy, and exercise sessions via the Health Connect SDK and pushes them tosyncDeviceHealthAndScorewithsource=health_connect. The backend route writeshealth_metricrows, auto-connects thehealth_connectdata source, and returns a wellness score. The metric key set is pinned by a golden-fixture contract test (see issue #9239 — the Health Connect backend contract). BDD smoke scenario:@smoke @issue-9023inwellness-sync.feature. † (#9023) - ✅
wellness.data.apple-health-connect-truthful— the iOS Apple Health connect flow reports success only if the user has granted data-sharing permissions, not on accept-disclosure alone.AppleHealthKit.initHealthKit()completes without error regardless of whether the user granted read categories (Apple deliberately withholds read-permission status for privacy); the app previously treated no-error as "connected" and pushed an empty payload. The fix infers the real connection state from whether syncs actually return samples: a payload is pushed tosyncAppleHealthAndScoreonly when at least one HealthKit metric is available, so 0-sample pushes that auto-connect the source with no data are prevented. This closes the root cause of #8977 (0apple_healthrows despite the ingest pipeline being proven correct in #9013/#9021). BDD regression scenario:@regression @issue-4678inwellness-sync.feature. † (#9022) - ⏳
wellness.data.device-push-connect-smoke— The on-device connect → permission → foreground-sync UX for both Apple Health (iOS) and Samsung Health / Health Connect (Android) is covered by Maestro smoke flows (mobile/ppp/.maestro/apple-health-connect.yamlandmobile/ppp/.maestro/samsung-health-connect.yaml), replacing the manual QA steps noted in #4678 for the consent screen, permission prompt, and sync trigger. The iOS simulator flow runs in the unattended CI batch and asserts: More menu → Health Data navigation → "Connect Apple Health" CTA → disclosure modal acceptance → HealthKit init → "Sync now" visible → sync trigger → truthful-empty post-trigger state (#9255). The Android flow covers Health Connect (primary path) and Samsung Health (Samsung-device path, pending SDK partner approval) and is tagged@manualuntil the emulator path is confirmed stable. Satisfiesmobile.health.apple-health-sim-e2e(the Apple Health simulator flow, authored once and shared with #9014 per the #9016 coordination directive) andmobile.health.android-health-device-smokeindocs/features/mobile.md.†‡ (#9016, #4678) - ✅
wellness.data.active-recovery-from-logged-activities— active recovery is detected from the activities a doctor logs on their wearable: stretching, ice bath, massage, sauna, compression boots. It is not inferred from light or low-strain exercise. Yoga and breathwork are logged as meditation. Built in #12747: the live WHOOP mapper (providers/whoop/whoopMapper.ts) now classifies by the wearable-loggedsport_name: sauna / ice bath / massage / stretching / compression →active_recovery_minutes; yoga / breathwork / meditation →meditation_time; neither is a training session, and low-strain workouts are no longer inferred as recovery. The same rule applies to every provider: Garmin classifies byactivityType(not average HR < 120), Oura exposes only intensity buckets and no recovery activity type so it maps nothing, and WHOOP counts an unscorable recovery session because its minutes come from start/end, not the score. Supersession: the 2026-06-03 #8089 comment ("light exercise doesn't reduce the need to sleep") was about light exercise and was misread as being about active recovery. Matt corrected this on #8461 (2026-06-17, 06-21, 06-22) and on the 2026-07-01 call.† † (#8461, #12747)
Sync Cadence & Refresh
- ✅ Pulse + Workload + Sleep recompute on the morning draw (06:00 local or first foreground after 06:00) (#6014)
- ✅ Morning and evening draws deployed as Azure Container App Jobs in UAT and prod (#6014). Updated 2026-08-27 (#11837): migrated onto the NAS-hosted API container's in-process node-cron scheduler (
registerScheduledJob, #11835/#11843), per ADR-0006 (#11819) — same hourly cadence, same per-user local-time / shift-aware gating insiderunMorningDraw/runEveningDraw, mechanism only changed. - ✅
wellness.evening-draw-shift-agnostic— Sleep Recommendation draw triggers when all three conditions are met: (1) user is outside a hospital geofence, (2) user is not on an active shift, AND (3) the 18:00 Europe/London slot has been reached (Rob 5 Oct 2026, from Matt 29 Jul on #11148; replaced the ≥ 14 h-awake rule set on #6430, 2026-05-20; Matt has not re-confirmed 18:00, OQ-EVENING-PROMPT-TIME). The hard fallback is bedtime-derived (latest_prompt_time = typical_wake_time − recommended_sleep_hours) rather than a fixed clock hour, so the prompt never fires mid-night-shift. Supersedes the prior fixed 18:00 → 21:00 push-if-geofenced rule and the earlier 21:00 clock-time ceiling. (#5940, #6788) † — implemented inapi/backend-ppp/src/services/wellnessService/readiness/eveningDrawTrigger/eveningDrawTriggerService.ts(pureevaluateEveningDrawTriggerenforces all three conditions; bedtime-derived ceiling viaisPastBedtimeCeiling). (#6429) Correction (2026-08-12, #11486): the bedtime-derived ceiling was present in the evaluator but UNREACHABLE end-to-end until now.evaluateEveningDrawTriggergates that entire branch onNumber.isFinite(input.readinessScore), and the only production caller (eveningDrawService) passed{ userId, now, awakeSince }— so the ceiling was dead code, and a user whose morning draw had not run today (noawakeSince) resolved toawake-threshold-not-metforever rather than falling back as documented. The service now forwardsreadinessScore(parsed from the numeric-string column;Number.isFinite('0.62')isfalse, so the raw value would silently re-disarm it) and the user's wake target, so the ceiling is anchored per-user rather than to the 06:30 default. Independently, thewellness-evening-drawContainer App Job cron still encoded the superseded design —0 17-21 * * *, justified in-file by "the 21:00 hard-ceiling fallback" that #6788 had already replaced. Against the 14 h rule that left a silent dead zone: a morning draw at 08:00 UTC or later crosses 14 h awake after the final 21:00 tick, so the prompt could never fire for that user (in UK summer, BST = UTC+1, a 09:00 local wake is 08:00 UTC). The cron is now hourly, mirroring the morning job; the per-user trigger still decides firing andcalculateAndSaveScoreis idempotent. † (#11486) - ✅
wellness.geofence.arrival-signal— a geofence arrival is confirmed by atimesheetsrow withsource='geofence';geo_fence_eventsaccumulates entry/exit rows from both the web Smart-GeoTag path and, since #9257, the mobilebackgroundLocationTaskHandlerpath, so it is now the real dwell/audit trail rather than a path expected to stay empty. TheeveningDrawTriggerServicereadsgeo_fence_eventsfor the inside/outside-geofence state evaluation — with mobile writing real rows, this resolution is no longer permanentlynull(0 mobile-written rows previously starved it, silently disabling the geofence leg of the evening-draw trigger).timesheets.source='geofence'remains the operational trigger signal for both platforms. (updated 2026-07-10, #9257 — supersedes the 2026-06-24 #9547 "0 rows expected" framing) † (#9257, #9547) - ✅
wellness.geofence.super-admin-audit-view— a read-only Super Admin screen (Geofence Audit, alongside the existing hospital geo review-queue, #10269, for UI consistency) lists geofence entry/exit events: user, hospital, event type, timestamp, dwell duration (computed by pairing an exit with its immediately-preceding entry for the same user+hospital), within-geofence status, and distance from the geofence centre. No raw coordinates are shown — none are stored: #10827 (DPIA-4, DPO data-minimisation decision 2026-07-24) replaced the #9257-era coordinates column with the derived verification result (within_geofence/distance_meters), sincegeo_fence_eventsno longer persists raw GPS on any path. No write/edit affordance — the underlyinggeo_fence_eventsrows are written exclusively bygeoFenceEventService(web Smart-GeoTag, mobilebackgroundLocationTaskHandler) andmanualEndShift. Purpose: compliance spot-checks and debugging shift-auto-detection issues. † (#9257, #10827) - ✅
wellness.readiness.completed-timesheet-hours— completed timesheet hours feed the doctor's same-evening recovery guidance and the NEXT morning's readiness input, never a recalculation of a score already locked for the day (#11143; the lock invariant is #11148). Only entries in thecompletestate or later count — adraft(Smart-GeoTag arrival placeholder or unfinished entry) contributes no hours (WELLNESS_COUNTED_TIMESHEET_STATUSES,timesheetAdapter.ts). Today's completed hours aretime_at_work(the timeAtWork component of the Target Sleep Load workload group, so the evening recompute already reads them); yesterday's are exposed as a separatetime_at_work_prior_daymetric andScoreInputs.priorDayTimeAtWorkHoursso they can never inflate today's component. The prior-day metric is registered inwellness-scoring-config.json(thewriteMetricsallowlist rejects unregistered types) and stamped inside the scored day's window (the worked day is carried invendorPayload.workedDayStart/End), because everyhealthMetricreader selects onstartTimewithin the scored day. Built (#11143): when today has no completed hours (the morning draw), the calculator scores yesterday's completed hours through the existingtimeAtWorkScorecurve andweights.timeAtWork(0.12); the component is present-gated on either metric and the Daily Inputs breakdown shows the prior-day row with its real contribution. Today's hours win when both exist (evening recompute), so the two are never double-counted. The evening notification slot shared with #11148's sleep recommendation is unchanged — one prompt, two inputs (Rob, #11143 2026-07-29). The requirement itself is Matt's own, re-cited to his primary statement on 2026-10-03 (Task 10 refresh).† † - ✅
wellness.notifications.shift-aware-prompt— the evening sleep recommendation notification fires based on off-shift status and awake duration (not a fixed clock time), accounting for varying work shifts among medical professionals. Fires from the 18:00 Europe/London slot (the earlier 14 h awake threshold was replaced, Rob 5 Oct 2026); the bedtime-derived ceiling (wake target − recommended sleep hours) can still fire earlier. † (#6430, #6788) - ✅ Scheduled poll runs every 24 hours per connected source — daily batch sync for all OAuth providers (Whoop, Oura, Garmin). Updated 2026-08-27 (#11837, part of the ADR-0006 NAS move, #11819): runs on the NAS-hosted API container's in-process node-cron scheduler (
registerScheduledJob, #11835/#11843) rather than as an Azure Container Apps Job — same0 20 * * *UTC cadence, same batch-sync + 24h-poll logic, mechanism only changed. Morning and evening draws were migrated the same way in the same PR. † † - ✅ "Refresh now" button on wellness dashboard triggers on-demand sync
- Rate-limited once per 5 minutes per user
- Loading state with success/failure toast
- Works on web and mobile
- ✅ Auto-sync failures surface non-blocking toast; stale timestamp preserved (#4862)
- ✅ OAuth callback pages tolerate missing
window.openerwithout crashing (#4869) - ✅ OAuth callback completes the token exchange even without a popup opener (redirect-fallback / mobile path); connection state reflects without a manual refresh (#7353)
- ✅
wellness.data.oauth-returns-to-app— when WHOOP OAuth is initiated from the native app, the user is returned to the app after authorising rather than left in the external browser (Safari). The native-app context is signed into the OAuthstate; the callback echoes the verified flag and deep-links the user back via theppp://URL scheme, with the in-browser data-sources fallback intact for users without the app installed. (#8635) † - ✅
wellness.data.oauth-callback-authenticates-off-signed-state— the WHOOP/Oura/Garmin OAuth token-exchange callback authenticates off the cryptographically-signed credential, not the interactive PPP session, so the mobile callback succeeds when it completes in the external system browser (a separate cookie store from the WebView that carries no PPP session).handleCallbackis a public procedure: WHOOP/Oura derive the userId from the HMAC-signedstate(verified byparseState— signature + expiry/replay), and Garmin (OAuth 1.0a, no signed state) derives it from the unguessable, single-useoauth_tokenbound to a userId at the session-protectedgetAuthUrlstep. The signed credential is the sole trust anchor — a forged, tampered, or expiredstate/token is still rejected withBAD_REQUEST(no auth bypass), and the desktop popup flow is unchanged. (#8866) † - ✅
wellness.data.reconnect-ux— the data-sources reconnect flow keeps the user anchored to the device they acted on and returns them inside the wellness feature. Initiating a reconnect (isConnectingflips true on aneedsReconnectsource) scrolls that device card into view (scrollIntoView, centred) so the user is not stranded above the fold. On the WHOOP success path the callback now returns to the in-app Health Monitoring Settings screen/wellness/settings(which mounts the Connected Data Sources panel and refetches connection status on mount) rather than the old/my-profile#wellness-data-sourcesprofile detour — aligning withwellness.settings.in-app-config-screen(#7024). Because WHOOP auto-closes its popup and auto-navigates on success, the redundant manual "Return to Data Sources" button is dropped for WHOOP only (anautoReturnOnSuccessopt-in); Garmin and Oura keep the manual button since they do not auto-close their popups. Sub-item 4 ("WHOOP still not connecting / page not found") was a backend bug, not a WHOOP-dashboard config issue: the WHOOP v2 data API is served under the/developerpath segment, butWHOOP_OAUTH.API_BASE_URLlacked it, so the first data callGET /v2/user/profile/basic404'd; with no profile theexternalUserIdcould not resolve and a "connected" WHOOP source was left unusable. The base URL now carries/developerand the client preserves that segment when building every/v2URL (the OAuth/oauth/oauth2/...endpoints stay on the bare host). (#8930) † ‡ - ✅
wellness.data.reconnect-banner-scope— the page-level "needs reconnecting — your wellness data isn't syncing" banner on the Wellness dashboard fires only when the doctor has no healthy connected source (!hasConnectedSources). A single stale/expired provider (e.g. WHOOPneedsReconnect) alongside other wearables still syncing (Apple Health, Health Connect) does not raise the banner — that would overstate the problem ("your data isn't syncing" when it is) and nag doctors who never relied on that provider; the per-source "Reconnect" button on the Data Sources card carries the affordance instead. When the stale provider is the doctor's only would-be source, the banner still shows. Refineswellness.data.truthful-connection-state(#8632) and the #9182 mutual-exclusivity rule. † ‡ (#9215) - ✅
wellness.data.remove-stale-wearable— a wearable stuck inreconnect_needed(orerror) state can be removed, not only reconnected. PreviouslyDataSourceCardrendered the Disconnect button only in theisConnectedbranch; a broken-but-real connection row fell through to the Connect/Reconnect branch which offered only Reconnect, so a doctor who had stopped using the device (e.g. WHOOP) was trapped on a permanent "Reconnect needed" prompt and the page-levelreconnectSourcesbanner nagged forever. The card now also renders a secondary, destructive Remove button alongside Reconnect in thereconnect_needed/errorstates, reusing the sameonDisconnectpath the connected state uses (no duplicated handler — atomic design). Removing the source runs the existing disconnect mutation whoseonSuccessrefetchesgetAvailable; the cleared source loses itsneedsReconnect/connected/sync-metadata flags, so it drops out of thereconnectSourcesset derived inWellnessScore/index.tsxand theDashboardViewreconnect banner disappears. The Remove button is suppressed for a never-connected source (nothing to remove) and while a connect/reconnect is mid-flight, and its visible "Remove" label is its accessible name (#7773 — no divergingaria-label). On-device confirmation that disconnecting WHOOP clears the banner is a manual follow-up. (#9316) † ‡ BDD regression scenario:@regression @issue-9316inwellness-data-sources.feature. - ✅
wellness.data.source-allowlist-emitted-only— the per-metricsourcesenforcement allowlist inwellness-scoring-config.jsonadmits, for each metric, only the sources whose mapper actually emits that metric.sourcesis the enforcement boundary (metricTypes.validateHealthMetric,mobileIngestService.buildDeviceHealthRecords): a health metric tagged with a source not on that metric's allowlist is rejected, never scored. Previously every provider metric listed all six sources (whoop, oura, garmin, apple_health, health_connect, samsung), so a client could submit and have scored any metric tagged with any source — including one whose mapper never produces it (a latent data-integrity surface). Legitimate multi-source mappings are intentional and preserved —sleep_duration,deep_sleep,rem_sleep,resting_hr,spo2stay at all six (every mapper emits them), training minutes/intensity stay multi-source,hrv/respiratory_ratestay five-source,active_recovery_minutesstays four-source. The tightening removes only genuinely-wrong entries (e.g. phone-onlyscreen_time_*drop wearables;stress_period_2/3,hrv_deviation→whooponly;meditation_time→whoop, apple_health); a documentedcore_temperature→whoop, ouracarve-out is retained for the ranked-but-not-yet-mapped path. A both-directions invariant test (emitted ⇒ allowed, not-emitted ⇒ rejected) is asserted for every source, and both config copies (packages-shared/ppp/src/constants/+api/backend-ppp/__debug__/) are kept identical by the config-integrity contract. (#9042) † ‡ - ✅
wellness.data.webhook-payload-validated— inbound provider webhook PUSH bodies are validated against a Zod schema at the ingestion trust boundary before any user lookup or metric write. WHOOP and Garmin POST webhook events to PPP's HTTP endpoints (Oura is poll-only and has no webhook handler); previously each handler cast the parsed JSON to a TypeScript interface via a hand-rolled type guard, so a provider renaming or dropping a field passed the cast and wrote silent garbage tohealth_metric. Each handler now Zod-parses the untrusted body (WhoopWebhookPayloadSchemarequires a finite numericuser_id;GarminWebhookSummaryItemSchemarequires a non-emptyuserAccessToken— the load-bearing identity fields used to resolve the PPP user — while passing per-push-type metric fields through to the mapper). A malformed or drifted body fails closed: it is logged at error level (a drifted webhook contract is an operational signal) and rejected, so nohealth_metricrow is written for that delivery; a valid body is processed as before. The sharedvalidateWebhookBodyhelper returns a structured result rather than throwing, preserving each handler's contract of always answering the provider with a single result (WHOOP/Garmin treat a non-2XX/hung connection as a delivery failure and retry). Extends the #9015 runtime-validation pattern (OAuth API-response + mobile device-push boundaries) to the webhook push boundary; sameproviderResponseValidation.tsmodule, with each payload type nowz.inferof its schema so the type and validator cannot drift. † ‡ (#9240, extends #9015/#9010)
Metrics Display
- ✅ Readiness score shown prominently — rendered as the lead
ReadinessScoreCardon the wellness dashboard. † - ✅
wellness.cards.traffic-light— the readiness, workload and sleep dashboard cards are colour-coded on one consistent traffic-light signal (green / amber / red) from a single sharedSEMANTIC_COLORS-backed helper, not per-card hardcoded hex (#7525). Rendered as a left-edge stripe on each card (PR #8493). Colour is always paired with the band/level text label, so it is never the sole signal. † ‡ (#8199) Open: Matt expected an 81 readiness to read green, which conflicts with the published High band (≥ 85) — readiness green threshold pending Matt's confirmation. - ✅
wellness.cards.guidance-fallback— an unrecognised guidance level shows the guidance advice itself, never a placeholder headline. † ‡ (#8217) - ✅
wellness.dashboard.mobile-single-heading— at phone width the dashboard header reads as one heading; the friendly date yields to the date picker. † ‡ (#8258) - ✅
wellness.dashboard.mobile-whoop-row-density— the Row 2 WHOOP-inspired card grid (Recovery, Day Strain, Sleep Stages, Wellbeing), shown only when a wearable is connected, tightens its grid spacing and per-card vertical padding at phone width, extending the #8932 mobile-compaction pattern (already applied to Row 1) to the four full-width stacked panels that follow it. Reduces the total scroll height of the mobile Wellness dashboard without changing card content or desktop layout. † ‡ (#9890) Partial fix — the issue's on-brand/native-feel ask is tracked separately in #10045 (for-discussion, pending Matt's sign-off), and visual before/after screenshots plus iOS/Android device verification were not performed for this change (disclosed environment constraint); #9890 stays open for that follow-up. - ✅
wellness.questionnaire.mobile-fit— at phone width the Weekly Wellness Questionnaire fits one fullScreen dialog (393×676) without vertical scroll: all five WHO-5 questions plus the Submit/Cancel actions are reachable without scrolling. The inter-question and per-field spacing tightens at xs and the in-title date field yields at xs in submit mode, so the submission defaults to today (the path virtually every user takes); the desktop rhythm is preserved at sm+ and every rating stays tappable. Read-only viewers keep the date visible so they can see which day they are reviewing. † ‡ (#8931) - ✅
wellness.breakdown.no-metrics-actionable— the daily-inputs readiness breakdown distinguishes two empty states. When no score exists for the date it shows the neutral "No wellness score calculated for this date" message (scores need sufficient metrics). When a score exists but zero contributing metrics came through — the silent signature of a data-flow gap (no wearable connected, or a connected source returned no samples for the day, see #8632 / #8634) — it shows an actionable prompt ("No contributing metrics synced for this date" / "Connect or sync a data source to see the breakdown behind your score") rather than the previous neutral "Detailed metric breakdown is not available" dead-end that masked the failure as expected behaviour. The original empty-state was engineering-added in PR #7667 (fix #7552) with no spec AC; this AC records the realigned, actionable behaviour. † ‡ (#8658) - ✅
wellness.dashboard.data-sources-settings-gated— the Daily Inputs panel (the transparency surface that lists which raw health metrics, and their source, fed the readiness score — seewellness.breakdown.no-metrics-actionableabove) is gated behind a Health Monitoring Settings → "Show data sources" toggle and is HIDDEN BY DEFAULT. Real users no longer see the raw scoring inputs on the default Wellness dashboard; the panel appears only when the user opts in. This changes the prior always-visible behaviour: exposing exactly which data points feed the score risks revealing proprietary scoring methodology to real users pre-launch (Matt flagged this in the 2026-07-14 Dev Session and parked the launch decision). The preference persists server-side per user (users.show_wellness_data_sources, nullable → default OFF), read/written via thewellness.readiness.scores.getShowDataSources/setShowDataSourcesprocedures, mirroring thepreferredWakeTimepreference pattern. Built as Option 1 ("move behind settings") of Matt's parked A/B/C decision under Rob's recorded assumption; both reversal directions stay cheap — flip the default to show-for-everyone (config change) or drop the panel + toggle entirely (small PR). BDD smoke scenario:@smoke @issue-10604inwellness-data-sources.feature. † ‡ (#10604) - ✅ HRV shown as "average HRV" above/below personal average (closes)
- ✅ Wellness chart shows Weekly Wellness Questionnaire score mapped over PPP Pulse; default view is latest 1 week (#7765, superseding the 2-week default from #5993) † †
- ✅ Pill switcher (1W / 2W / 1M / 3M / 6M) changes the chart time range (#5993, #7765) †
- ✅ Pulse chart legend is positioned in a dedicated band below the plot so it does not crowd the series (#7765, superseded by #7805) †
- ✅ Pulse chart legend sits top-right on desktop, never overlapping the x-axis; at phone width the in-chart legend yields to captions below the chart (#7805, mobile treatment superseded by #8257) † ‡
- ✅
wellness.pulse.mobile-adaptive— at phone width the Pulse plot fills the chart; series labels move to captions below it. † ‡ (#8257) - ✅
wellness.pulse.embedded-clickthrough— whenScoreHistoryChartis embedded in the dashboard PPP Pulse card (variant="embedded"), the card's whole-card navigation overlay disables pointer-events on the chart plot so a tap anywhere on the chart routes through to/wellness(the dashboard click-through, seedashboard.pulse-broad-panel); the chart's own interactive controls — the range pill switcher and theAdd check-inweekly-questionnaire button — re-assert pointer-events so they stay tappable above the overlay. Standalone usage on the Wellness page is unaffected. † ‡ (#8640) - ✅ Pulse header shows "PPP Pulse", "Readiness meter" and the range label inline on one row, wrapping on mobile (#7823) † ‡
- ✅ Chart shows 6-month average annotation for both series; if < 6 months of data exists, computes over available history with the windowed label (#5993)
- ✅
wellness.pulse.average-label-distinct— the readiness average annotation reads as an average over a window ("Avg readiness · 1-month (56)") so it is never mistaken for the headline Readiness score. Before #8655 the label read "PPP Pulse 1-month avg: 56", and when the windowed average happened to equal the current-day readiness score (both 56) it read as the same number printed twice. The label now leads with "Avg", names the series, and trails the value in parentheses, making it textually and visually distinct from the bare headline number. † † (#8655) - ✅ All user-facing "WHO-5" strings replaced with "Weekly Wellness Questionnaire"; internal constants and DB columns unchanged (#5994) †
- ✅ Sleep and workload guidance cards —
SleepGuidanceCardandWorkloadGuidanceCardrendered on the wellness dashboard. † † - ✅
wellness.readiness.shared-bands— the Readiness Score card and the Workload Recommendation classify a score with the same bands (High ≥ 75 / Moderate 50–74 / Low < 50), sourced from one sharedREADINESS_BAND_THRESHOLDSconstant. The frontend readiness traffic-light/label and the backend workload thresholds (WORKLOAD_THRESHOLDS_NORMALISED) both derive from it, so a given score can never read as one band on the Readiness card and a different band on the Workload card. Before #8637 the Readiness card carried its own High ≥ 85 / Moderate ≥ 70 ladder, which contradicted the Workload bands and the "an 81 should read green" expectation (#8199). † † (#8637, refs #8199/#6161) - ⏳
wellness.readiness.no-score-empty-state— Engineering DEFAULT pending Matt's UX sign-off (for-discussion, OQ-READINESS-EMPTY). When readiness has not genuinely been computed yet — a newly-connected user whose data is flowing but who has not completed their first Weekly Wellness Questionnaire and has not had a sync cycle, where the Readiness Score card'sscoreisnullor0with no contributing metrics (metricsUsed0/null) — the card renders a neutral, friendly onboarding prompt ("Your readiness score builds from your connected health data, such as sleep, heart rate and activity, once it has synced. It does not come from the questionnaire." — #12798; the card does not fill from the questionnaire, so the copy must not promise it) with non-red (neutral grey) styling instead of an alarming red0 / 100 / Low Readiness. A genuinely-computed low score (metricsUsed > 0, including a real computed0) still renders the real low score in red — only the never-computed case changes. The dashboard'sComplete Questionnaireaction is unchanged. Callers that omitmetricsUsedkeep the previous render (back-compat). † ‡ (#9315, refs #8199/#6161) - ⏳
wellness.sleep.no-wearable-placeholder— Sleep-first slice of Matt's no-data hierarchy decision (for-discussion, #10236). When a genuine no-wearable day flows to the dashboard Sleep Stages card — no real total sleep AND no real stage data — the card renders a calm Supportive Placeholder (a mutedBedtimeOutlinedicon + "Didn't wear your device today?") instead of falling through toDEFAULT_STAGES, which previously rendered a fabricated ~8 h of demo sleep that read as a real-but-bad night. Neutral wellness-palette styling, no alarm colour — matching how Whoop/Oura/Garmin present a no-data night. Caller-supplied stages (real data OR an explicit Storybook fixture) still render normally, so previews are unaffected. Matt's paired Weighted-Score decision (exclude missing metrics rather than drag the composite to 0) was found to be already satisfied by the presence-gated renormalisation incalculateOverallScore(#8435/#8458), which drops absent components; the partial-score transparency label ("N of M metrics") is deferred pending Matt's choice of an honest denominator. † ‡ (#10236, refs #9315/#8658/#8435) - ⏳
wellness.readiness.low-confidence-guard— Engineering-defined sane bound, for-discussion pending Matt's sign-off (extends the deferred "N of M metrics" question parked atwellness.sleep.no-wearable-placeholder/ #10236; decision questions posed on #10930). Confirmed live in UAT, timed to the minute: a 2-metricmobile_health_ingestpush at 2026-07-21T05:53:32Z (spo2 +active_recovery_minutes) recomputed and persisted the day's score viacalculateAndSaveScore(called unconditionally on every ingest) one minute before Matt's 06:54 BST "Low Readiness — Reduce Intensity" screenshot. Renormalising (#8435) over only 2 of 17 weighted components is high-variance, not systematically low — it can read confidently high OR low depending on which components happen to be present that moment (on other dates a 2-metric day scored 100, an 8-metric day scored 59), which is the actual mechanism behind the reported 75+ point swings recurring weekly. Becausewellness_score_dailyupserts one row per (user, date) with no intraday history, the same row was overwritten later that day by fuller pushes and the evening draw, settling much higher — so the swing is real but invisible to a same-day-later query. The displayed readiness integer itself is NOT bounded by this fix —metricsUsedaccumulates monotonically across a day'smobile_health_ingestpushes (each push only replaces the metric TYPES it carries, never removes previously-written ones), so a later, sparser push can never regress an existing score on that path; the swing is mitigated by disclosure, not by capping the number. Fix, three parts: (1)calculateAndSaveScorewill not let a recompute backed by fewer metric types thanMIN_METRICS_FOR_SCORING(a previously-defined-but-unwired constant) regress an existing same-day score backed by more — a defensive guard that matters for a full data-replacing resync (scores.syncAll, the "Refresh now" button and background auto-sync, opts out viaforceOverwritesince it just replaced the day's data and is authoritative by construction) rather than for the reported partial-ingest scenario itself; (2) theReadinessScoreCardrenders a "Limited data so far today" chip (reusing the existing Chip/InfoHintpattern from the phone-derived-fallback badge,wellness.phone-derived-fallback) whenever a genuinely-computed score (metricsUsed > 0, distinct from thewellness.readiness.no-score-empty-statenever-computed case) is backed by fewer thanMIN_METRICS_FOR_SCORINGmetrics, disclosing low confidence rather than presenting a sparse reading as a settled clinical read — this is the primary mitigation for the reported symptom; (3) theWorkloadGuidanceCard's band-derived recommendation (e.g. "Reduce Intensity", "Prioritize Recovery") — the part carrying actual clinical weight, not just the integer — is likewise suppressed in favour of a neutral "not enough data yet" state whenevermetricsUsed < MIN_METRICS_FOR_SCORING(including a genuine 0, unlike the readiness chip, since this card has no separate never-computed branch of its own), so a surgeon is never told to reduce intensity on the strength of two — or zero — metrics. Open questions for Matt, tracked on #10930: is 3-of-17 the right confidence floor forMIN_METRICS_FOR_SCORING, and should the readiness integer itself also be suppressed/greyed like the workload advice, or is the disclosure chip enough? † ‡ ‡ ‡ (#10930) - ✅
wellness.sleep.wake-target-shown— the dashboard Sleep Guidance card surfaces a wake-time row showing the wake target, from which the recommended bedtime is derived (bedtime = wake target − recommended sleep hours). Change (2026-07-10, #10183): the wake target is now the user's detected wake time — derived from the day's actual sleep data (the end of the final overnightsleep_durationsegment from the highest-priority connected source that persists a real session end, resolved via the shared provider-priority model, with the latest segment being the morning wake per #6784) — rather than a fixed 06:30 default. Only WHOOP and Oura currently write a true sleep-session end; Garmin and the phone sources (Apple Health / Health Connect / Samsung) currently persistsleep_durationwith a day-boundary end (endOfDay), which is not a wake, so they do not yet drive a detected wake and fall back to the default (a provider joins automatically once its mapper emits a real end). The day-boundary sentinel is additionally rejected by value — so even a malformed WHOOP/Oura session that fell back toendOfDaycannot fabricate a ~midnight wake. When no real-end sleep is available for the day the derivation yields nothing and the guidance falls back to the 06:30 default (wake stays missing, never fabricated — never a ~midnight sentinel). This is the reactive, cross-platform detected-wake path; the proactive AndroidgetNextAlarmClock()next-alarm signal is a separate optional Phase 2 (no equivalent on iOS). For-discussion (pending Matt): the fixed-default → device-detected shift touches a clause Matt has personally reversed twice (M2 dropped the field #8656; #8933 restored it at 06:30), so the behavioural change (what the row shows) is flagged for his confirmation; the row itself and the 06:30 fallback are unchanged. The backend derives and persists the wake target on the score (calculateSleepTimingGuidance, #6430); the card displays it. Supersedes the fixed-default part of the previouswellness.sleep.wake-target-shownrestoration (#8933). Change (2026-07-15, #10603) — REVERSES #10183's device-detected wake: the wake target is now the user's explicit set preference (users.preferred_wake_time, HH:MM 24h), captured during onboarding and editable in place by tapping the wake-time value on the Sleep Guidance widget — saving recomputes today's score so the recommended bedtime recalculates live. Apple restricts app access to the phone alarm's actual wake time on iOS, so the #10183 per-day detection was unreliable for most users. When the user has not set a preference yet, the widget shows a "Set your wake time" onboarding prompt and the guidance falls back to the default (06:30) — matching the pre-#10183 default-wake-target behaviour, never per-day sleep-segment detection (thedetectedWakeTargetmodule is removed from the score path). The score path reads the preference viagetUserWakeTarget(view-first: readsusersView, writesusers) at thecalculateAndSaveScorecall site. This is the fourth reversal on this clause (M2 → #8656 → #8933 → #10183 → #10603); confirmed via Rob's verbal relay of Matt's decision, recorded on the issue (governance-trace + sign-off comments) — no linked Notion/Slack artefact. † † † † (#10603, reverses #10183; #8933, supersedes #8656/M2, refs #4872, #6430, #6784) - ✅ Sleep recommendation derived from workload + previous recovery via the source spreadsheet's three-input Target Sleep Load model (not the readiness score alone). Reverts the readiness-only drift flagged on #6161 per Matt's 2026-05-27 instruction, corroborating the standing requirement from Matt 2026-05-03 (#4872) and transcript-2026-05-12 §SleepGuidance (#6434). Change (2026-07-15, #10603): the bedtime countdown now subtracts a fixed target — always the top of the band (8 h,
FIXED_SLEEP_TARGET_HOURS) — from the user's wake target, rather than the model's variablehoursoutput. The three-input Target Sleep Load model still runs and still drives the displayed band/message classification (labelSleepHours), so the range headline is unchanged; only the single hours value the countdown subtracts is now fixed. The wake target it counts back from is the user's set preference (seewellness.sleep.wake-target-shownabove, #10603) — no longer "no user-supplied wake target". Confirmed via Rob's relay of Matt's decision on #10603. † † † (#7670, #10603) - ✅
wellness.sleep.active-recovery-reduces-sleep-need— logged active recovery (seewellness.data.active-recovery-from-logged-activities) and meditation both reduce the evening sleep recommendation through the DaytimeRecovery input of the Target Sleep Load model, by the amount set in Matt's spreadsheet. Built in #12747:activeRecoveryis now inRECOVERY_GROUP_COMPONENTSinscoring/sleepLoadInputs.tsalongsidemeditation. CONTRADICT, shown explicitly. Superseded wording, kept for traceability: "activeRecoveryremoved from the recovery group per Matt's #8089 confirm — light exercise must not reduce the sleep need" (2026-06-03 reading). Replaced by Matt 2026-06-17 (#8461), "these should reduce sleep need by the referenced amount in the spreadsheet", reconfirmed on the 2026-07-01 call. This matches his original brief: the evening update "incorporates todays workload and any active rest" (Notion, 2026-05-12) and "go for some active rest or recovery like a sauna which may reduce the amount of recommended sleep" (#6449, 2026-05-20).† † † † (#8461, #12747) - ✅
wellness.sleep.range-headline— the Sleep Guidance card headline shows the recovery band range (e.g. "8-9 h"), not a single number; the ranges are Matt's locked values (Normal 7-8 / Moderate 8-9 / Enhanced 9-10 / Maximise 10+; the Normal floor raised 6-8 → 7-8 on #8933 to match the model's 7 h floor, reverting the #8656 6-8 copy) held in the sharedSLEEP_BAND_RANGESsource of truth, read by both the card headline and the backend guidance messages so the two can never drift. † † † (#7670, #8933) - ✅
wellness.sleep.floor-7h— the sleep recommendation never recommends below 7 hours. The source Target Sleep Load model floors at 7 h (SLEEP_MIN_HOURS = 7, the model's base and clamp floor) and the readiness-only fallback curve clamps to[7, 10]. The envelope is re-anchored so all four bands stay reachable at the 7 h floor: a light, well-recovered day (Target Sleep Load = 0) recommends exactly 7 h and lands in the Normal band, because the Normal cut-off (8 h) is strictly above the floor; Moderate (8-9), Enhanced (9-10) and Maximise (10+) fire as the load climbs toward the 10.5 h ceiling. Supersedes the OQ-SLEEP-FLOOR / #8208 decision (2026-06-10) that had lowered the floor 7.5 → 6 h — restored to 7 h per Matt's UAT direction 2026-06-20 (#8933) ("never recommend below 7 h"), keeping band reachability intact (the raised floor does not re-introduce the unreachable-Normal bug #8208 fixed, because Normal's cut-off still sits above the floor). † † (#8933, supersedes OQ-SLEEP-FLOOR/#8208) - ✅ Debug Portal custom baselines are dev-only; never flow to backend scoring; UI shows "dev override active" badge when non-default baseline is active (#4868)
- ✅
wellness.pulse.who5-overlay— the PPP Pulse widget is overlaid with the Weekly Wellness Questionnaire (WHO-5) trend for comparative analysis; users can see how their subjective wellbeing score tracks against their biometric readiness over time. Verified 2026-05-20:instances/ppp/src/modules/WellnessScore/Dashboard/components/ScoreHistoryChart.tsxrenders a MUILineChartwith two co-plotted series —SERIES_IDS.READINESS(PPP Pulse) andSERIES_IDS.QUESTIONNAIRE(Weekly Wellness Questionnaire / WHO-5) — pinned to the shared 0–100 y-axis so subjective wellbeing and biometric readiness track day-aligned across the 2W/1M/3M/6M window, with 6-month average reference lines for each series (#5993, #6432). † † - ✅
wellness.pulse.daily-chart— the PPP Pulse widget displays a daily mapping chart showing readiness score plotted against Weekly Wellness Questionnaire data; the chart emits exactly one slot per calendar day across the selected window (2W/1M/3M/6M) so readiness and WHO-5 stay day-aligned for correlation, with empty days kept as null so x-axis spacing remains even. † (#6432) - ✅
wellness.pulse.three-scores— the Pulse widget header shows three top-line scores: (1) readiness score (PPP Pulse), (2) workload recommendation derived from readiness, and (3) sleep guidance; the Weekly Wellness Questionnaire prompts weekly (not daily). † (#6433) - ✅
wellness.pulse.traffic-light-dots— the PPP Pulse readiness dots are colour-coded to the traffic-light scheme via a piecewise y-axiscolorMapkeyed off the shared readiness bands (red below 50, amber 50–74, green 75+ — theREADINESS_BAND_THRESHOLDSsource of truth since #8637), reusing the sharedwellnessTrafficLightSEMANTIC_COLORStokens so the chart never drifts from the cards or hardcodes hex. The Weekly Wellness Questionnaire series stays one flat colour on a colorMap-free axis; the two average reference series are dropped from the legend (already shown bottom-left as dashed-glyph annotations) and the average renders with no decimal places. † † (#8186, refs #8199/#6161/#7670) - ✅
wellness.pulse.prompt-replicates-readiness— the headline prompt on the PPP Pulse widget (on/wellnessand in the PPP Dashboard Pulse card) repeats the approved readiness/workload prompt for the day's band. It never shows its own motivational or app-engagement copy. Built in #12748:MotivationalMessage.tsxnow picks the prompt from the sharedREADINESS_BAND_THRESHOLDSandWORKLOAD_GUIDANCE_MESSAGES(the same copyDEFAULT_GUIDANCE_CONFIGuses); the 80 / 60 bands and all engagement copy are gone.† (#12748) - ✅
wellness.pulse.chart-failure-contained— a rendering failure inside thePulseLineChartplot (the MUI X Charts area/line series) is contained to the chart widget and never escalates to a full-route crash. Before this,/wellnessand the embedded main/ppp-dashboardlanding page both hard-crashed to the top-levelAppErrorBoundaryfallback for any account with real, populated wellness score data — reproduced ontest-full@ppp-test.comwith 30 real WHOOP-sourced days, reported errorMUI X: Could not find the series ref context...thrown fromAreaPlotinsidePulseLineChart.PulseLineChartis now wrapped in a localAppErrorBoundary(the repo's standard generic error-boundary component) insideScoreHistoryChart, with a minimal on-brand fallback (PulseChartErrorFallback, reusing existingSEMANTIC_COLORStokens — no new visual primitives) rendered in place of the plot only; the rest of the widget (header, range switcher, average annotations) survives. This does not claim to fix the underlying MUI X Charts trigger — see #11798 for the root-cause follow-up — only that a chart-internal failure can no longer take down the whole route. † ‡ (#11798) - ✅
wellness.pulse.sleep-guidance-recompute— sleep guidance is computed in the morning after the user wakes (morning draw) and recomputed in the evening incorporating the day's workload and activities (evening draw). † (#6434) [src:api/backend-ppp/src/services/wellnessService/readiness/draws/morningDrawService.ts:9,api/backend-ppp/src/services/wellnessService/readiness/draws/eveningDrawService.ts:1-26] - ✅
wellness.pulse.readiness-locked-after-morning— the readiness score (PPP Pulse) is computed in the morning and then locked for the day: every later same-day recompute preserves the readiness figure, its 0-100 display value, and themetricsUsedconfidence count, rather than moving the number the doctor already read and acted on. The lock is deliberately partial — the Sleep Recommendation and Workload Recommendation still refresh on the evening draw from the day's strain, which is the adaptive behaviour that must be kept (seewellness.pulse.sleep-guidance-recompute). Before this, the score moved on every path that touched the day's row: the hourly morning draw, the evening draw, eachmobile_health_ingestpush, andscores.getOnDemandon every dashboard mount — so simply reopening the app after the freshness window re-scored the day. A persistedwellness_score_daily.readiness_locked_atstamp arms the lock on the first same-day recompute at or after a dawn-hour floor, so an overnight partial ingest cannot pin the day before the night's sleep data lands, and a backfill of an earlier day cannot stamp a lock as though it were that day's morning draw; a lock stamp with no readiness value behind it is never honoured, so a day can never be pinned to "no score". Authoritative user-initiated callers (scores.calculate,scores.syncAndScore, and thescores.recalculaterange mutation — an explicit force-recompute or a full data-replacing resync) opt out viabypassReadinessLockand re-arm the lock with their fresh value, so the day settles again rather than staying free to drift. An unattended remediation job does not:recalculateScoreRangeonly defaults to opting out and the default is caller-overridable, sobackfillCorruptedScorespassesbypassReadinessLock: falseand repairs historical rows while leaving an already-locked current day untouched (#11510). Saving a new wake time deliberately does not bypass it: that changes the recommended bedtime, not the day's readiness. † (#11148) [src:api/backend-ppp/src/services/wellness/wellnessService/readiness/scoring/scoreService/scorePersistence.ts—calculateAndSaveScorepreserve branch,getScoreOnDemandlock guard,isMorningDrawRecomputeNeededgate,shouldArmReadinessLock] - ✅
wellness.pulse.intra-night-wake-recalibration— when an overnight sleep is split (the doctor wakes mid-night and falls back asleep), the readiness sleep input is the total time asleep across all segments, not just the longest. Each provider sleep segment is stored as its ownhealth_metricrow with a distinct(startTime, endTime)window and the scorer sumssleep_duration/deep_sleep/rem_sleepacross segments from the winning source. Works for Whoop and Oura today (both expose multi-segment sleep in their APIs); other providers exposing split-sleep data benefit automatically because the scorer change is provider-agnostic. † (#6784, refs #6430) [src:api/backend-ppp/src/services/wellnessService/readiness/providers/oura/ouraMapper.ts,whoop/whoopMapper.ts,aggregation/priorityResolver.ts,scoring/calculator.ts]
Wellness Questionnaire
- ✅ Weekly reminder scheduled for Weekly Wellness Questionnaire. It arrives as a push notification on Friday morning, and tapping it opens the questionnaire directly, the same way the timesheet prompt works. Built: the scheduled window is Friday 06:00–06:59 Europe/London (
notification/timeWindow.ts; moved from 06:30 to match Matt's "6am Friday" call on #7606, built in #12758) and the bell opens the questionnaire inline (wellness.notifications.bell-opens-inline). Fire times in each user's own timezone are tracked on the #11651 epic. The 2026-08-07 missed-Friday report (#11426) is closed.† - ✅
wellness.questionnaire.reminder-once-per-week— a doctor receives exactly one weekly questionnaire reminder per ISO week, regardless of how many generator paths run. Two independent generators write this reminder — the scheduled Container Apps Job (processWellnessNotifications) and the client-triggered app-load path (ppp.wellness.questionnaireNotification/questionnaireNotificationBatch) — and both fire inside the same Friday 06:30–06:59 London window. Each previously deduplicated on a metadata key the other never wrote (scheduledKeyvsdate), so both landed every week: UATnotificationsrows 1186 (04:30, sender null,{scheduledKey: "wellness:17:2026-W31"}) and 1207 (04:44, sender 17,{date, type}) for user 17 on 31 Jul 2026, with the same pair on 3 Jul (row 532). All paths now write and match on one week-scoped identitywellness:<userId>:<ISO-week-year>-W<week>(api/backend-ppp/src/services/wellness/wellnessService/notification/weekKey.ts), and every path emitsmetadata.dateso the existing partial unique indexnotifications_wellness_user_date_uidxcovers rows from either generator. The reminder is system-generated:senderIdis null on every path, never the recipient's own id. (#11311) [src:api/backend-ppp/src/services/wellness/wellnessService/notification/weekKey.ts,api/backend-ppp/src/services/wellness/wellnessService/notification/index.ts,api/backend-ppp/src/services/wellness/wellnessService/notification/batch.ts,api/backend-ppp/src/services/notifications/scheduledNotificationService/index.ts] - ✅ Weekly Wellness Questionnaire scored 0–100 canonical; chart Y-axis pinned to 0–100
- ✅ "Complete Questionnaire" button opens modal on first click (#4864)
- ✅ Weekly Wellness Questionnaire submission shows success toast and updates dashboard score
- ✅
wellness.questionnaire.submission-banding— on submit, the post-questionnaire dialog shows the standardised WHO-5 score (0–100) together with a wellbeing band label and a revised prompt copy confirmed by Matt (#8342 comments, 2026-06-17): Good wellbeing (score > 66) — "Your responses suggest good current wellbeing. Keep it up."; Moderate wellbeing (33–66) — "Your responses suggest moderate wellbeing. Consider small steps to support yourself this week."; Low wellbeing (< 33) — "Your responses suggest low wellbeing. Consider larger steps to support yourself this week and going forward." The copy carries no GP / colleague / supervisor referral advice — that clinical advice is deferred under the M5 Supportive Alerts decision (trigger criteria TBD). Thresholds use the canonical WHO-5 three-band split (Good >66 / Moderate 33–66 / Low<33) — corrected from the wrong 52/28 values in the original implementation (#8710). Constants areWELLBEING_GOOD_MIN_SCORE/WELLBEING_MODERATE_MIN_SCORE. PR #8694 had removed the label and advice entirely under #8342; #8710 restores the banding with the softer, referral-free copy. † (#8710, #8342) - ✅ Test/manual mode disabled in production
- ✅
Questionnaire.Integration.mdreflects live tRPC namespace and backend-complete status (#4874) - ✅
SCORE_FRESHNESS_HOURSconstant used in cache-validity check (#4873)
Data Privacy — individual scores never shared with employer
- ✅
wellness.privacy.no-enterprise-individual-share— individual PPP Pulse scores, readiness bands, sleep guidance, and workload recommendations are never shared directly with the employer or hospital enterprise. The enterprise receives only anonymised, k-anonymity-compliant cohort aggregates via the Organisational Dashboard (seeorganisational-dashboard.md). The purpose is doctor self-awareness and behaviour change; surfacing individual scores to employers would risk restricting a doctor's work and undermine the platform's trust proposition.† † † † (#7481, #7593) - ✅
wellness.privacy.three-prompts-not-shared— the system delivers a small, fixed set of supportive coaching prompts regarding capacity and rest (Matt's 12 May wording: "three"; delivery today (6 Oct 2026, Task 10 wave 2): one morning Workload Recommendation prompt and one evening Sleep Recommendation prompt each day, plus the weekly questionnaire reminder on Fridays, so two on most days and three on a Friday; whether Matt's "three" meant these three or the three guidance outputs is not confirmed); these prompts are designed to be non-restrictive in tone. Prompt content and delivery are never shared directly with the enterprise. † † † † (#6435)
Notifications & Deep Links
- ✅
wellness_remindernotification type registered on frontend with deep link - ✅ Burnout image on wellness dashboard is clickable
- ✅
wellness.prompts.morning-readiness-notification— the morning draw raises one in-app notification per user per day, "Your readiness today is N.<workload recommendation>", between 05:00 and 11:59 user-local, from the freshly computed score or, when the day was already scored (the doctor opened the app first), from the stored one. It is registered in the notification trigger registry (wellness_morning_prompt, migration 0268) so the super-admin console lists it, can switch it off or re-route it, and the recipient's wellness opt-out applies. It never recomputes a locked score. (Task 10 audit D2, #11206 item 3) - ✅
wellness.prompts.evening-sleep-notification— one evening sleep prompt per user per day, "Time to wind down: aim for N h of sleep tonight, in bed by HH:MM, up at HH:MM", raised by the evening draw when the 18:00 user-local slot is reached, the user is off shift and outside the hospital geofence (hourly retries; the bedtime-derived ceiling remains the later fallback). One prompt, two inputs: it already carries the day's completed timesheet hours (#11143), so there is no separate hours notification. Registered aswellness_evening_sleep_prompt(migration 0268). (Task 10 audit D1, #11148 Rob 29 Jul and 5 Oct) - ✅
wellness.wellbeing-tile.shared-bands— the Wellbeing tile on the readiness view shows the most recent submitted WHO-5 result and uses the same three bands as the questionnaire result (Good >66, Moderate 33–66, Low<33); it no longer ignores a submitted questionnaire or uses the old four labels. (Task 10 audit D4, #8342 Matt 17 Jun) - ✅
wellness.prompts-as-notifications— All PPP Pulse coaching prompts (morning Workload Recommendation, evening Sleep Recommendation, weekly Questionnaire reminder) are delivered as in-app notifications, not as action items or to-dos. Correction (5 Oct 2026, #11218 C2): the weekly wellness reminder and the questionnaire reminder are Platform Reminders (Rob, 4 Oct 2026): they land in the Action Items Platform Reminders tab, not the Notifications feed, and the notification console now says so. Whether they should also show in the bell is an open question for Matt (his 27 May call on #7606 said the bell). They carry no required-completion semantics and do not appear in the action-items list. Implemented viaPULSE_COACHING_PROMPT_TYPESininstances/ppp/src/constants/notification-types.ts— Pulse prompt types (wellness_questionnaire_reminder,wellness_reminder) are deliberately excluded fromALL_ACTION_NOTIF_TYPESso they only surface in the Action Items Platform Reminders tab, never in the to-do list or the bell feed. (#5942) † - ✅
wellness.notifications.bell-opens-inline— clicking the weekly wellness-questionnaire reminder in the notification bell opens the questionnaire inline as a modal in place (reusing the sameuseInlineQuestionnairemodal as the dashboard onboarding item, #7350) rather than navigating to/wellnessand forcing the doctor to hunt for the button. The/wellness?openQuestionnaire=1deep-link is retained only as a fallback for surfaces (the Notifications page / Unified Inbox feed) that don't expose the inline modal. Implemented ininstances/ppp/src/slots/CoreAppContainerNotificationMenu/CoreAppContainerNotificationMenu.tsx(renders the inline dialog and passesonOpenWellnessQuestionnaire) andinstances/ppp/src/hooks/useNotificationNavigation.ts(skips navigation when the inline opener reports it handled the click). (#7606) - ✅
wellness.questionnaire.back-exits-wellness— opening and closing the questionnaire dialog replaces the current history entry rather than pushing new ones, so after completing the questionnaire the device back button returns the doctor to the screen they were on before entering wellness (e.g. the PPP dashboard) instead of back into the completed questionnaire.useQueryParamdefaults toupdateType: 'pushIn', which left three entries on the stack for one visit (/wellness→/wellness?openQuestionnaire=1on open →/wellnesson close); back landed on the middle entry, whose param is read on mount to re-open the dialog, so back could never escape the questionnaire. Opening a dialog is a UI state change rather than a destination, soreplaceInis also the semantically correct write. The param is still read from the URL on mount, so the/wellness?openQuestionnaire=1notification deep-link (wellness.notifications.bell-opens-inline, #4864) is unaffected. † ‡ (#11425) - ✅
wellness.notifications.non-tickable— wellness prompts appear as non-actionable notifications only; they must not appear in the to-do or action-items list and carry no completion state. Implemented viaPULSE_COACHING_PROMPT_TYPES(deliberately excluded fromALL_ACTION_NOTIF_TYPESininstances/ppp/src/constants/notification-types.ts);instances/ppp/src/modules/Notifications/index.tsxfilters the Actions tab viaALL_ACTION_TYPES_SET, sowellness_questionnaire_reminderandwellness_remindernever render in the Actions/To-do tab and carry no completion state. Correction (5 Oct 2026, #11218 C2): they are Platform Reminders (PLATFORM_REMINDER_TYPES), so they render in the Platform Reminders tab, not the Notifications feed. † - ✅
wellness.no-user-toggle-v1— In v1 the user has no option to turn off wearable-based reminders from within the app. The feature is a core USP; toggling it off is deferred until user-testing feedback establishes genuine edge-case demand (e.g. users who physically cannot wear a wearable). Decision: 12 May 2026 call. (#5941) † - ✅
wellness.settings.no-toggle-yet— the PPP Pulse cannot be toggled off at this stage; the decision is deferred to post-user-testing. Verified 2026-05-20 by code search: no Pulse toggle/opt-out setting exists ininstances/ppp/src/modules/Wellness/orinstances/ppp/src/(grep forpulse.*(toggle|disable|opt.?out|hide|setting)→ 0 results). †
Scoring Configuration
- ✅
wellness.scoring.weights-admin-override— a Super Admin can review and edit the 17-component weight profile used by the wellness readiness score calculation, without a redeploy, via/admin/wellness-scoring-settings. Weights are validated as a whole set (exactly the 17 known component keys, each value in [0,1], sum to 1.00 ± epsilon) rather than per-key, since the weights are only meaningful together. Edits are stored in awellness_scoring_weights_overridesingle-row DB table (mirroring thetodoSnoozes/cpdReminderSettings"master settings table" precedent) and consulted bygetEffectiveWeights()at score-calc time; falls back to the staticSCORING_WEIGHTSdefault when no override row exists. Cached (24h TTL, invalidated on write) since it sits on the per-user score-calculation hot path; writes an audit_trail entry (before/after weights) since this is a single shared row affecting every user's score. Out of scope:formulaParams(tiers/thresholds/decay curves inwellness-scoring-config.json, hardcoded logic informulas.ts, not live-loaded — editing them here would not change actual scoring behaviour) andPHONE_FALLBACK_WEIGHTS(a mathematically-derived redistribution of the standard profile, not independently tunable). (#11770) † ‡ - ⏳
wellness.algorithm.validated— the wellness algorithm's inputs, data-source hierarchy and the accuracy of the messages it delivers are validated with a documented method, separately from the Task 10 lifecycle walkthrough. The method is not yet agreed (OQ-ALGO-VALIDATION). The May Phase 1 plan (Pearson r against the Weekly Wellness Questionnaire on Matt's own data, M7) is the starting point.† (#12411)
Status
| Sub-feature | Status | Notes |
|---|---|---|
| WHOOP integration (UAT) | ✅ Built | Prod creds pending (#4700) |
| WHOOP integration (prod) | ⏳ Blocked | #4700 — prod OAuth app needed |
| Garmin integration | 🔄 In progress | Code done; creds blocked (#4677, #4651) |
| Apple HealthKit | 🔄 In progress | Polling deploy pending (#4826) |
| Google Fit | ✅ Removed | Fully retired — frontend (#7929), backend stack + enum + data migration (#8006/#8007) |
| Health Connect | ✅ Built | On-device Android source via PPP mobile app (#7929) |
| Fitbit | ✅ Removed | Connectable surface removed (#8667); dormant provider stack fully purged, enum + disconnect path retained for historical connections (#8690) |
| Android Health screen | ⚠️ Bug | "Not implemented" placeholder (#4890) |
| Data hierarchy | ✅ Built | #3643 |
| No-source display | ✅ Built | #3642, #4866 |
| Manual entry removed | ✅ Built | #3647 (Matt Q_M1 re #4870) |
| HRV label corrected | ✅ Built | #3588 |
| HRV above/below personal avg | ✅ Built | #3645 |
| Refresh-now button | ✅ Built | #4859; error handling pending (#4862) |
| OAuth callback robustness | ⚠️ Bug | #4869 |
| Weekly questionnaire reminder | ✅ Built | #3716 |
| Weekly Wellness Questionnaire (0–100) | ✅ Built | #4861 |
| Questionnaire modal first-click | ⚠️ Bug | #4864 |
| Questionnaire submission feedback | ✅ Fixed | #4863 |
| Test/manual mode in prod | ✅ Fixed | #3714 |
wellness_reminder deep link | ✅ Built | #4976 |
| Burnout image clickable | ✅ Built | #5135 |
| Sleep wake target field | ✅ Reframed | Per Matt 2026-05-03: no wake target — algorithm-driven (#4872 to re-scope) |
| Debug Portal baselines → backend | ⏸ Awaiting Matt | Q_M3 / #4868 — engineering proposal pending confirmation |
SCORE_FRESHNESS_HOURS cache usage | ⚠️ Bug | #4873 |
| Questionnaire integration doc refresh | ⚠️ Bug | #4874 |
| Scoring weights Super Admin override | ✅ Built | #11770 — /admin/wellness-scoring-settings; wellness_scoring_weights_override table + getEffectiveWeights()/upsertWeights(); formulaParams/PHONE_FALLBACK_WEIGHTS out of scope |
| Active recovery classification + sleep effect | ⚠️ Drift | Matt 2026-06-17/21/22 (#8461) + 2026-07-01 call: logged stretching/ice bath/massage/sauna reduce sleep need; live mapper still uses strain < 7, sleep group excludes it — #12747 |
| Pulse widget motivational line | ⚠️ Drift | Matt 2026-07-14 call: should replicate readiness prompts, not "spend more time on PPP" — #12748 |
Open issues on label:feature:wellness — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-06 | WHOOP recovery percent and calories now back the Row 2 Recovery gauge and Day Strain card; "Refresh now" is limited to 1 per 5 minutes with a message; the provenance badge falls back to the winning source on a no-HRV day. Spec text corrected: evening prompt is the 18:00 slot (not 14 h awake), prompts-as-notifications names the Platform Reminders tab, the weekly reminder drift row in notifications.md is closed, morning and evening prompt types are listed, and the "three prompts" AC now describes the delivery model. | #0, #11206, #12969, #12970, #12971, #12972, #12973 | Task 10 reachability check (5 Oct 2026): the UI hard-coded recovery and calories to null because the mapper never emitted them (#12969); the 5-minute refresh limit was claimed built but no cooldown existed (#12970); badge said FROM YOUR PHONE for a WHOOP user (#12971). Spec ACs still described rules the code replaced (#12973). Rob closed #11499 on 27 Aug 2026, so hrv_deviation and stress_period_* are deliberately not ported. Open and not built here: #12798 readiness from questionnaire (Rob decision), the 18:00 time itself (Matt to confirm), coaching adapt or refine, per-user timezone (#11651). |
| 2026-10-05 | Adds the morning readiness prompt and the single evening sleep prompt as notifications (registered in the notification trigger registry, migration 0268), moves the evening trigger from "14 h awake" to the 18:00 user-local slot, makes the Wellbeing tile show the latest submitted questionnaire in the shared Good/Moderate/Low bands, and seeds per-band, fresh-account, timesheet and reminder demo data for the Task 10 video. | #0, #11206, #11148, #11143, #8342 | Rob's 5 Oct 2026 decisions on the Task 10 audit (D1 evening prompt, D2 morning prompt, D4 tile, D3/D5/D6/D7 seeds). Matt on #11148 (29 Jul) said the evening prompt would come through at 6:00 or 7:00 p.m., and Rob the same day said both #11148 and #11143 share one ~18:00-19:00 prompt. #11206 item 3 asks for "calculation and prompt" in the morning. The tile ignored a submitted questionnaire because its container hard-coded wellbeingScore: null, and used 72/50/28 bands instead of Matt's >66 / 33-66 / <33 (#8342, 17 Jun). Open and not built here - #12798 (readiness wearable-only vs questionnaire-fed) stays a Rob decision, and the 18:00 clock time itself has not been re-confirmed by Matt. |
| 2026-10-05 | Spec text corrected: the weekly wellness reminder and the questionnaire reminder are Platform Reminders, so they land in the Platform Reminders tab, not the Notifications feed. The notification console now shows the same. | #11218 | Rob decided on 4 Oct 2026 to keep Platform Reminders delivery; the spec and console said Notifications (audit C2). Whether the bell should also carry them is an open question for Matt. |
| 2026-10-04 | Flipped wellness.readiness.completed-timesheet-hours from partial to built. The morning readiness draw now scores yesterday's completed timesheet hours through the existing timeAtWork curve and weight (0.12) when today has no completed hours; today's hours still win in the evening recompute, so the two are never double-counted. The Daily Inputs breakdown shows the prior-day row with its real contribution. Resolved OQ-TIMESHEET-WEIGHT: no new constants and no separate hours notification. | #11143, #11206 | Matt on #8461 (2026-06-13): readiness is computed from previous-day factors, and work is one of them. Rob on #11143 (2026-07-29, reconfirmed 2026-09-24): hours feed same-evening recovery and the NEXT morning's readiness, never a recalc of a locked score, with one shared ~18:00-19:00 prompt. Matt's spreadsheet model already carries weights.timeAtWork 0.12 and the timeAtWorkScore tiers, so no weighting needed to be invented. |
| 2026-10-04 | The Readiness Score card's empty-state copy now reads "Your readiness score builds from your connected health data, such as sleep, heart rate and activity, once it has synced. It does not come from the questionnaire." (was "Complete your first questionnaire to see your readiness."). Scoring is unchanged. | #12798, #9315 | Rob chose the copy-only fix for #12798 (4 Oct 2026). A doctor who submitted the questionnaire still saw "Complete your first questionnaire" on the card, which read as a bug; the readiness score builds from synced health data, not from the questionnaire. |
| 2026-10-03 | Flipped wellness.data.active-recovery-from-logged-activities and wellness.sleep.active-recovery-reduces-sleep-need from drift to built. The live WHOOP mapper now classifies wearable-logged activities by sport name (sauna / ice bath / massage / stretching / compression boots → active_recovery_minutes; yoga / breathwork / meditation → meditation_time) instead of counting every strain < 7 workout as active recovery. activeRecovery joined meditation in RECOVERY_GROUP_COMPONENTS so both reduce the evening sleep recommendation via DaytimeRecovery. Review fixes: Garmin now classifies by activityType instead of average HR < 120, Oura maps no active recovery (no recovery activity type exposed), and WHOOP counts unscorable recovery sessions. | #12747, #8461, #8089, #11499 | Matt's #8461 statements (2026-06-17, 06-21, 06-22) and the 2026-07-01 call supersede the 2026-06-03 #8089 reading, which was about light exercise. The #9906 classification fix lived only in the orphaned mapper deleted by #11499, so it never reached the live path. The OQ-SLEEP-MAP curve-fidelity question stays open. |
| 2026-10-03 | Flipped wellness.pulse.prompt-replicates-readiness from drift to built. The Pulse headline prompt now shows the approved readiness prompt for the day's band (High >= 75 / Moderate 50-74 / Low < 50, from the shared READINESS_BAND_THRESHOLDS) using copy moved into the shared WORKLOAD_GUIDANCE_MESSAGES constant, which DEFAULT_GUIDANCE_CONFIG now also reads. Removed the private 80 / 60 bands and the 'Working like a Pro', 'More interactions' and 'Spend some more time on PPP' copy. | #12748, #11206 | Matt, 2026-07-14 call: the Pulse prompts should replicate the readiness prompts; a fatigued doctor must not be told to spend more time on the app. Conflicted with wellness.coaching-prompts.matt-approved and the never-lecture rule. |
| 2026-10-03 | Weekly wellness questionnaire reminder window moved from Friday 06:30-06:59 to Friday 06:00-06:59 Europe/London, and the dedicated London-anchored tick now fires on the hour (0 * * * *) so the reminder goes out at 6am. The week-scoped idempotency key is unchanged. Built in #12758. | #12758 | Matt on #7606 (2026-05-27): "CHANGE trigger for 6am Friday" — newest dated statement, superseding his own #3716 "Friday at 6:30am" brief. The code still used 06:30. |
| 2026-10-03 | Task 10 spec refresh (wellness lifecycle) against Matt's latest dated statements. Added ACs: active recovery from wearable-logged activities, with yoga/breathwork as meditation (drift #12747); active recovery and meditation reduce the evening sleep need (drift #12747, CONTRADICT of the #8089-based exclusion, superseded wording kept visible); Pulse widget prompt replicates the readiness prompts (drift #12748); algorithm validation (#12411, specified). Re-cited completed-timesheet-hours to Matt's 2026-07-28 WhatsApp. Weekly reminder AC now states Friday-morning push that opens the questionnaire (2026-07-14 call). Narrowed OQ-SLEEP-MAP to curve fidelity only. New Open Questions: OQ-EVENING-PROMPT-TIME, OQ-READINESS-BANDS, OQ-TIMESHEET-WEIGHT, OQ-COACHING-REFINE, OQ-ALGO-VALIDATION. status in-progress → partial-drift; notion-last-synced → 2026-05-12 (page last edit). | #11206, #8461, #8089, #12747, #12748, #11143, #12411, #6161, #6449 | Async Task spec refresh (#11206). Newest dated Matt statement wins. Active recovery: #8089 2026-06-03 (about light exercise, misread as active recovery) → #8461 2026-06-17/21/22 → 2026-07-01 call (stretching/ice bath/massage reduce sleep need; yoga/breathwork = meditation). The #9906 classification fix went only into the orphaned mapper, which #11499 deleted 2026-08-27 without porting, so the live path never got it. Workload/readiness bands: Notion 2026-05-12 (85/70/50) → 2026-05-13 (75) → #6161 2026-05-19 four-band table → 2026-05-26 call (75/60/50, 40 later; conflicting, so an Open Question). Evening prompt: Notion 18:00/21:00 → #6449/#6430 2026-05-20 14 h → 2026-05-26 "may miss the mark" → 2026-07-29 "I think … 6:00 or 7:00 p.m." (hedged, so an Open Question). Spec-only, no BDD: the scenario requirement is on each fix issue. |
| 2026-09-24 | Added AC wellness.readiness.completed-timesheet-hours — the wellness timesheet adapter counts only complete-or-later entries (drafts excluded) and exposes yesterday's completed hours as a separate time_at_work_prior_day metric / ScoreInputs.priorDayTimeAtWorkHours for the next morning's readiness. Plumbing only; the prior-day weighting is unspecified and left as an open question for Matt. | #12436, #11143 | #11143 was unblocked by #11139 (entry state model), #11103 and #11148 (morning-locked readiness). The spec gave no formula or thresholds for how completed hours weight into readiness, so no numbers were invented — the input is exposed and unweighted until Matt specifies it. The #11148 lock invariant is preserved: hours never recalculate a locked score. |
| 2026-08-27 | PulseLineChart render failures are now contained to the chart widget instead of crashing the whole /wellness and /ppp-dashboard route — a local AppErrorBoundary wraps the chart with a minimal PulseChartErrorFallback. | #11847, #11798 | /wellness and the embedded /ppp-dashboard landing page both hard-crashed to the top-level AppErrorBoundary for any account with real, populated wellness score data (MUI X 'Could not find the series ref context' thrown from AreaPlot inside PulseLineChart, #11798). The underlying MUI X Charts trigger was not root-caused this session, but the severity (a chart-internal failure taking down the entire route) is fixed regardless by containing the failure to the chart widget. |
| 2026-08-27 | Migrated the 3 wellness scheduled jobs (daily sync, morning draw, evening draw) off Azure Container Apps Jobs onto the NAS-hosted API container's in-process node-cron scheduler via registerScheduledJob (#11835/#11843). Cron cadences and UTC timezone are unchanged from the Azure Job definitions; per-user local-time / shift-aware gating is unchanged inside runMorningDraw/runEveningDraw/runScheduledWellnessSync. | #11846, #11837 | Part of the ADR-0006 NAS migration (#11365/#11819) — Azure Container Apps hosting was not financially sustainable, so backend compute (including scheduled jobs) moved to a self-hosted Synology NAS for both UAT and prod. |
| 2026-08-24 | New Super Admin page (WellnessScoringSettings, /admin/wellness-scoring-settings) reviews and edits the wellness readiness score's 17-component weight profile without a redeploy. Weights are validated as a whole set (exact key list, each value in [0,1], sum to 1.00) and stored in a new wellness_scoring_weights_override table, consulted by calculator.ts via getEffectiveWeights() in place of the static SCORING_WEIGHTS import. | #11781, #11770 | Scoring-algorithm admin UI (#11770), a Task 18 Admin Console sub-issue. formulaParams (tiers/thresholds/decay curves) and PHONE_FALLBACK_WEIGHTS are deliberately out of scope — see the PR description for why. |
| 2026-08-15 | wellness.data.recovery-panel-wired-to-production — WHOOP Day Strain and the whole-day average/max heart rate are now fetched, mapped, persisted and surfaced end-to-end. whoopSyncService calls client.getAllCycles at both sync call sites, whoopMapper gains mapCycleMetrics (mapAllWhoopData takes cycles as a 4th argument), day_strain / avg_hr / max_hr are registered metric types, RecoveryPanelResult exposes strainScore / avgHrBpm / maxHrBpm, and the container reads those real fields instead of hard-coded nulls. | #11577, #11502 | The #11486 AC recorded this as "a separate feature gap" and it is now closed for strain and heart rate. The pipeline was broken at every stage, so it was never a display bug: day strain is a CYCLE-level field and the live sync never fetched cycles at all (getAllCycles existed and was tested but had no production caller), the live mapper contained zero references to average_heart_rate / max_heart_rate, and no metric types were registered — so the container''s hard-coded nulls were honest but permanently empty. Day strain is stored raw on WHOOP''s 0-21 scale, deliberately distinct from the per-workout strain that mapWorkoutMetrics normalises to a 0-2 training intensity. Cycles are attributed to a calendar day by START time because a cycle runs from waking past midnight and its end is null while in progress, so attributing by end would both shift the day''s strain forward and drop the current day. missing != zero (#10182) is preserved at the mapper: WHOOP reports 0 rather than null for an unrecorded heart rate and 0 bpm is not physiologically possible, so those are omitted, while a genuine 0 day strain is a real measurement (a fully rested day) and is emitted. Calories, sleep efficiency, WHO-5 wellbeing and the multi-day strainHistory series remain unbacked; the orphaned readiness/adapters/providers/whoopMapper.ts is untouched and remains #11499''s concern. |
| 2026-08-12 | wellness.ui.header-help-icon-placement — Health Monitoring Settings now renders its title + contextual help through the shared PageHeader atom (helpGuideSection="data-integrations") instead of hand-rolling the flex row with an inline <HelpButton>. | #11539, #11534 | The hand-rolled row glued <HelpButton> directly after the title Typography, the exact anti-pattern banned by design-system.page-header.help-first-in-actions (#9213). A BDD sweep asserting that AC had never executed (its path literals went stale after the ADR-0003 bounded-context move); once re-pointed it caught this file. The AC text described the hand-rolled row as the implementation, so it is updated to describe delegation to the atom. |
| 2026-08-12 | Makes the bypassReadinessLock opt-out in recalculateScoreRange caller-supplied rather than hardcoded, so backfillCorruptedScores — an unattended remediation job — repairs historical rows without unlocking and re-arming today's already-locked readiness score. No change to wellness.pulse.readiness-locked-after-morning's stated behaviour for user-initiated recomputes. | #11525, #11510 | Follow-up from #11480's post-merge review. recalculateScoreRange (scorePersistence.ts:740) spread bypassReadinessLock: true on top of the caller's options, so no caller could opt out. The AC names recalculateScoreRange as an authoritative opt-out caller, but justifies that on 'an explicit force-recompute or a full data-replacing resync' — a user act. A backfill is not one, so a repair range that happened to include today would unlock and recompute the score the doctor already read that morning, which is exactly what the #11148 lock exists to prevent. The default is unchanged (scores.recalculate still bypasses); only the ordering changed, so options can now override it, and the backfill passes bypassReadinessLock: false. |
| 2026-08-12 | Fixes two unrelated defects. (1) The evening Sleep-Recommendation prompt now reliably fires — eveningDrawService passes readinessScore and the user's wake target into the trigger, arming the bedtime-derived ceiling that #6788 documented but that was dead code in production, and the wellness-evening-draw Container App Job cron widens from 0 17-21 * * * to hourly. (2) An absent Day Strain reading renders -- instead of a fabricated 0.0 / 21, and the 14-bar strain chart no longer falls back to a hardcoded demo array — restoring wellness.data.missing-not-zero (#10182) and the #10335 "day strain stays null, never a fabricated 0" clause. | #11504, #11486 | Both symptoms were reported together on #11486 but have entirely different root causes. (1) evaluateEveningDrawTrigger gates the whole bedtime-ceiling branch on Number.isFinite(input.readinessScore), and the only production caller passed { userId, now, awakeSince } — so the ceiling could never engage, even though the doc comments in both files describe it as the safety net for exactly the case where the morning draw has not run and awakeSince is null. Proved by executing the real evaluator with the production input shape: 22:00 with awakeSince: null returns awake-threshold-not-met; the identical instant with readinessScore returns bedtime-ceiling-reached. Independently, the job cron still encoded the superseded design — its own comment justified the 17-21 window by 'the 21:00 hard-ceiling fallback' that #6788 had already removed. Against the 14h awake rule that left a silent dead zone: a morning draw at 08:00 UTC or later crosses 14h after the final 21:00 tick, so the prompt could never fire for that user; in UK summer (BST) a 09:00 local wake is 08:00 UTC. (2) Day Strain is not a display bug — whoopMapper reads strain and average/max heart rate from the WHOOP API but persists neither (all 10 createMetric calls enumerated; no strain, HR or calories metric), RecoveryPanelResult has no such fields, and the container hardcodes them to null. The card then rendered strainScore ?? 0 as a confident '0.0' while its sibling HR rows correctly rendered '--' — the same missing data shown two different ways. Persisting the metrics end-to-end is a genuine feature gap tracked separately; this change stops the card fabricating a value the user never recorded. |
| 2026-08-12 | Adds AC wellness.questionnaire.back-exits-wellness — opening/closing the questionnaire dialog replaces the current history entry rather than pushing new ones, so back after completing the questionnaire reaches the screen before wellness was entered instead of re-entering the completed questionnaire. | #11481, #11425 | Matt (WhatsApp, 7 Aug 2026) reported that back after completing the questionnaire went back into the questionnaire. The cause is useQueryParam's default updateType: 'pushIn' (use-query-params/dist/options.js): opening pushed /wellness?openQuestionnaire=1 and closing pushed /wellness again, so one visit left three entries on the stack and back landed on the middle one — whose param WellnessScore/index.tsx reads on mount to re-open the dialog, making the questionnaire inescapable by back. replaceIn collapses those entries. Deep-linking is unaffected because the param is still read on mount, which is what makes the notification deep-link work (#4864). |
| 2026-08-12 | Adds AC wellness.pulse.readiness-locked-after-morning — the readiness score (PPP Pulse) is computed in the morning and then locked for the day. A persisted wellness_score_daily.readiness_locked_at stamp pins the readiness triple (score, 0-100 display, metrics_used) against every later same-day recompute, while the Sleep and Workload Recommendations keep refreshing on the evening draw. Enforced at all three seams a recompute reaches the row through — calculateAndSaveScore preserves the locked fields, getScoreOnDemand serves the stored row without recomputing, and isMorningDrawRecomputeNeeded stops the hourly tick. Authoritative callers (scores.calculate, scores.syncAndScore, recalculateScoreRange) opt out via bypassReadinessLock and re-arm the lock with their fresh value. | #11480, #11148 | The score moved on every path that touched the day's row — the hourly morning draw, the evening draw, each mobile_health_ingest push, and scores.getOnDemand, which the dashboard calls on every mount, so merely reopening the app after the freshness window re-scored the day. Matt (Dev Session 2026-07-29): "it is updating every time you open it. The readiness score should just be calculated in the morning and then locked. The real-time is for the adaptation on the daily activities to make a sleep recommendation." His 28 Jul screenshot captured the symptom: "Updated 19:30 — a new sleep segment arrived after this morning — the score has been recalculated". |
| 2026-08-01 | Adds AC wellness.questionnaire.reminder-once-per-week — the weekly questionnaire reminder resolves to exactly one notification per user per ISO week. The scheduled Container Apps Job and the client-triggered app-load path now write AND match one shared week-scoped key (wellness:<userId>:<ISO-week-year>-W<week>), and every path emits metadata.date so the partial unique index notifications_wellness_user_date_uidx covers rows from either generator. senderId is null on all paths. | #11316, #11311 | Both generators fire in the same Friday 06:30–06:59 London window but each deduplicated on a metadata key the other never wrote (scheduledKey vs date), so neither SELECT could see the other's row and doctors received the reminder twice every week — UAT notifications rows 1186/1207 for user 17 on 31 Jul 2026, 14 min apart, with the same pair on 3 Jul (row 532). |
| 2026-07-24 | The Super Admin Geofence Audit view (wellness.geofence.super-admin-audit-view) no longer lists raw coordinates — it shows the derived within-geofence status and distance from the geofence centre instead (dwell unchanged). Underlying cause is the DPIA-4 remediation, geo_fence_events drops latitude/longitude in favour of derived within_geofence/distance_meters, with existing stored coordinates backfilled then purged (including audit_log JSONB row-snapshot copies), so no path can display or persist a raw GPS fix. The #9257 audit-view smoke scenario and step were updated to the coordinate-free shape and co-tagged @issue-10827. | #10880, #10827 | DPO decision (Rob Duncan, DPO, 2026-07-24, DPIA-4 under #10827) — data minimisation, the system must match the published privacy notices, which state GPS coordinates are never stored server-side. Findings F1–F4 of the DPIA-4 draft (PR #10875) are remediated by PR #10880; F4 specifically resolved the admin view's coordinate granularity as "hospital + distance only". |
| 2026-07-16 | Gated the wellness dashboard Daily Inputs panel — the transparency surface that lists which raw health metrics (and their source) fed the readiness score — behind a Health Monitoring Settings → "Show data sources" toggle, hidden by default. Real users no longer see the raw scoring inputs on the default Wellness dashboard; the panel appears only when the user opts in. New AC wellness.dashboard.data-sources-settings-gated. The preference persists server-side per user (users.show_wellness_data_sources, nullable → default OFF), read/written via new wellness.readiness.scores.getShowDataSources / setShowDataSources procedures, mirroring the preferredWakeTime preference pattern. | #10604 | #10604 — Matt (Dev Session 2026-07-14, ~00:38:35–00:39:45) flagged that the daily-inputs panel revealing which raw data sources feed the wellness score is useful during testing but risks exposing proprietary scoring methodology to real users pre-launch; he parked the launch decision (A: hide behind settings / B: remove / C: leave visible) as an explicit "make a ticket and put on hold". Built as Option 1 (A) under Rob's recorded assumption (issue comment 4989896204, 2026-07-16) as the reversible middle path — both reversal directions stay cheap (flip the default to show-for-everyone, or drop the panel + toggle entirely). Matt's parked decision stays open; veto window remains open beyond merge. |
| 2026-07-15 | Reversed wellness.sleep.wake-target-shown from #10183's device-detected wake back to a user-set wake target (users.preferred_wake_time, HH:MM 24h), and made it inline-editable on the Sleep Guidance widget — tapping the wake-time value swaps it for a time field, and saving recomputes today's score so the recommended bedtime recalculates live. The user sets their regular wake time during onboarding; when unset, guidance falls back to the default (06:30), matching the pre-#10183 default-wake-target behaviour rather than per-day sleep-segment detection. The #10183 detectedWakeTarget module and its detected-wake derivation are removed from the score path. Separately, standardised the underlying sleep recommendation that drives the bedtime countdown on the top of the band (fixed 8 h, FIXED_SLEEP_TARGET_HOURS) while the band UI still displays the variable range — reversing the "computed and variable hours" countdown value from #7670/#8933; the band/message classification still varies with the day's Target Sleep Load. | #10691, #10603 | #10603 — Apple restricts app access to the phone alarm's actual wake time on iOS, so #10183's device-detected wake was often wrong ("It says 6:30 for me. I'm like, 'Oh, I'm not waking at 6:30.'" — Matt, Dev Session 2026-07-14). Both requirement changes (device-detected → user-set + inline-editable; computed variable band → fixed 8 h countdown target) confirmed by Rob's verbal relay of Matt's decision, recorded in the issue's governance-trace + sign-off comments (no linked Notion/Slack artefact; audit trail per repo citation convention). Fourth reversal on the wake-target clause (M2 → #8656 → #8933 → #10183 → this). |
| 2026-07-10 | Wire the Row-2 recovery panel (RecoveryGaugeCard / DayStrainCard / SleepStagesCard) and source-aware provenance badge into the production dashboard, driven by real backend data. | #10347, #10335 | The #10182 source-aware badge and missing≠zero fixes only rendered in Storybook — the production container never populated recoveryData. A new getRecoveryPanel read projects the day's health metrics onto the panel (HRV winner as source, absent biometrics as null), so the panel now renders in the live app. |
| 2026-07-10 | wellness.data.missing-not-zero + source-aware provenance badge + biometric priority-list gaps. (1) The readiness calculator distinguishes an absent reading from a genuine measured 0 — getMetric() returns null (was 0) when no record exists, so an absent HRV renders -- instead of a fake 0 ms; the score is byte-identical because the formulas coerce null → 0 at the boundary and presence-gating (#8435/#8458) already excludes absent components. (2) The recovery panel badge is source-aware — WhoopConnectedBadge names the winning source (from WHOOP / from your phone) instead of the hardcoded WHOOP Connected, and the whoopData prop bag is renamed to source-neutral recoveryData. (3) health_connect + samsung are ranked at the tail of the hrv / hrv_deviation / deep_sleep / rem_sleep / respiratory_rate priority lists so an Android phone-store biometric resolves to a defined rank instead of falling through to availableSources[0]. | #10334, #10182 | UAT (#10182) — Matt's HRV read 0 ms and Resting HR blank while steps/sleep/HR still flowed from the phone (absent readings leaked as fake 0s), the recovery panel always claimed WHOOP regardless of the real source, and several biometric priority lists were missing the Android phone-store tail. This is the engineering-only slice; the multi-source display-format choice and the garmin-vs-apple_health ordering stay for-discussion / Matt-gated and are not built here. |
| 2026-07-10 | Extended wellness.sleep.wake-target-shown — the Sleep Guidance card's wake target is now the user's detected wake time (end of the day's final overnight sleep_duration segment from the highest-priority connected source that persists a real session end, resolved via the shared provider-priority model, latest segment = morning wake per #6784) instead of a fixed 06:30 default. Only WHOOP and Oura currently write a real sleep-session end; Garmin and the phone sources (Apple Health/Health Connect/Samsung) persist a day-boundary end (endOfDay) that is not a wake, so they fall back to the default rather than surfacing a ~midnight sentinel — a provider joins automatically once its mapper emits a real end. When no real-end sleep is present for the day the derivation yields nothing and the guidance falls back to 06:30 (wake stays missing, never fabricated). This is the reactive cross-platform detected-wake path (Phase 1); proactive Android getNextAlarmClock() next-alarm is a separate optional Phase 2. Implements the long-standing TODO(#6430) wearable-sleep-end plumbing at the calculateAndSaveScore call site. | #10183 | #10183 — the wake target driving the bedtime recommendation was a hardcoded 06:30 that ignored the user's real sleep data even when a wearable was connected. FOR-DISCUSSION (pending Matt): the fixed-default → device-detected shift changes a clause Matt has personally reversed twice (M2 dropped the field #8656; #8933 restored it at 06:30), so the behavioural change is flagged for his confirmation; the wake-time row and the 06:30 fallback are unchanged. |
| 2026-07-10 | Added a device-free WHOOP testing path (Part B of #10197) so OAuth → webhook → sync can be exercised on UAT/dev without a wristband. New data_source_connection.source_origin column ('real' default / 'seed') is the seed-vs-real guardrail — the demo seeder and a new super-admin, non-prod wellness.readiness.whoopSandbox.provision endpoint tag connections 'seed' so seeded rows can never masquerade as a working real integration in diagnostics/health checks. A webhook replay harness (scripts/replayWhoopWebhook.ts + signWhoopWebhookPayload) signs the golden fixture with the real WHOOP v2 scheme and POSTs it to a local/tunnel/UAT endpoint through the genuine signature-verify path. "Sync Now" is now reachable as a diagnostic even for a source in error/reconnect-needed state, and the single-source sync logs its full result. | #10303, #10197, #10064 | A seeded WHOOP connection with placeholder tokens read as "connected" and masked that the real WHOOP sync had never run (#10064). Tagging seed origin makes demo data honest and unblocks device-free end-to-end testing. The real WHOOP developer-portal synthetic account (#10303 items 1-2) remains a manual external-ops task and is out of scope for this in-repo change. |
| 2026-07-10 | Wire mobile's backgroundLocationTaskHandler to geoFenceEvent.recordEntry/logExit so geo_fence_events becomes the real dwell/audit trail (matching the pre-existing web Smart-GeoTag path), unblocking the evening-draw geofence gate which was permanently starved with 0 mobile-written rows. Correct the now-stale "geo_fence_events=0 expected" framing in the Geofence success criterion note and the wellness.geofence.arrival-signal AC. Add wellness.geofence.super-admin-audit-view AC + a new read-only Super Admin Geofence Audit screen. Add @regression + @smoke BDD scenarios. | #9257 | Investigation found eveningDrawTriggerService.shouldFireEveningDraw already read geo_fence_events for its geofence-gate check, but with 0 mobile-written rows insideGeofence always resolved null — silently permanently disabling the geofence leg of the evening-draw trigger. #9797 had retired the geoFenceEvent tRPC router on the premise mobile never called it; #9257 reverses that premise (Rob-approved) by wiring the mobile write path instead of leaving it retired. |
| 2026-07-09 | Extended wellness.data.truthful-connection-state — a successful WHOOP/Garmin/Oura reconnect now clears the stale lastSyncStatus/lastError left over from before the reconnect (previously pinned a genuinely-reconnected source to "Reconnect needed" forever), and the OAuth callback kicks an immediate fire-and-forget backfill sync so data reappears without waiting for the next scheduled poll. | #10298, #10196 | UAT (#10196) — Matt's real WHOOP reconnected successfully (fresh valid tokens, profile fetched) but the Connected Data Sources card stayed stuck on "Reconnect needed" and the dashboard kept saying no wearable was connected, because storeTokens never reset the pre-reconnect sync error and no sync was triggered to repopulate it. |
| 2026-07-09 | Added AC wellness.sleep.no-wearable-placeholder — on a genuine no-wearable day (no real total sleep AND no real stage data) the Sleep Stages card shows a calm Supportive Placeholder (muted BedtimeOutlined icon + "Didn't wear your device today?") instead of falling through to DEFAULT_STAGES, which previously rendered a fabricated ~8h of demo sleep that read as a real-but-bad night. Neutral wellness-palette styling, no alarm colour. Caller-supplied stages (real data or Storybook fixture) still render normally. | #10271, #10236 | Matt (#10236, WhatsApp 2026-07-09) didn't wear his WHOOP overnight so every sleep metric read 0; the demo-data fallback then fabricated a full night that read as real. Matt approved a Supportive Placeholder reusing the neutral empty-state pattern. Sleep metrics first. His paired Weighted-Score exclusion was found already implemented (presence-gated renormalisation, #8435/#8458); the "N of M metrics" transparency label is deferred pending Matt's choice of an honest denominator. |
| 2026-07-08 | Fixed metricsUsed to count only components with real health_metric data for the day (via the existing presentComponents presence map from calculator.ts), instead of walking the full ScoreInputs object — which always included the static baselines sub-object (5 always-positive constants: restingHrBpm, respiratoryRate, coreTempC, spo2Percent, hrvDeviationMs), guaranteeing metricsUsed >= 5 even with zero real health_metric rows for the day. | #10198, #10149 | Matt's dashboard showed a computed red "0/100 Low Readiness" on 7 Jul (#10149) even though the #9315 empty-state guard was present and correct — the backend's metricsUsed signal the guard trusts was unreliable, not the guard itself. Confirmed live in UAT (wellness_score_daily) that 4 consecutive days with zero health_metric rows for a user still recorded metrics_used=5, exactly the baseline-field count. |
| 2026-07-06 | Added AC wellness.ui.header-help-icon-placement — the help (?) on wellness page headers now sits immediately beside the heading text, not floated to the far-right edge. Health Monitoring Settings groups title + "?" in one flex row (was a space-between Stack); the Wellness Dashboard renders it via PageHeader's helpGuideSection prop (was the far-right actions slot beside the date picker), matching the canonical PageHeader pattern (#9887/#9213). | #10081, #10065 | Matt (#10065) asked that all "?" icons sit on the right close to the heading, never wrapping or placed on the far right. Both wellness headers pushed it to the far-right edge, reading as detached from the heading it explains. |
| 2026-07-04 | The Wellness dashboard's Row 2 WHOOP-inspired card grid (Recovery, Day Strain, Sleep Stages, Wellbeing) now tightens its grid spacing and per-card vertical padding at phone width (grid spacing {xs:2, sm:3}, py {xs:2, sm:3} on WhoopDarkCard, py {xs:1, sm:2} on Phq9Card), mirroring the existing #8932 mobile-compaction pattern already applied to Row 1. | #10047, #9890 | Row 1's #8932 gap-tightening reached the outer row Box and the three recommendation tiles, but not the Row 2 WHOOP card grid — at phone width it kept the same 24px gap and vertical padding as desktop across 4 full-width stacked panels, adding avoidable height on top of Row 1 + the chart + Daily Inputs below. Reported (#9890) as the mobile Wellness screen reading as "too tall" and overflowing the native app's bottom nav. |
| 2026-07-03 | The wellness Sources/Settings screen's in-page "Back to Wellness" button is now suppressed inside the native app's WebView (isReactNativeWebView()), where the native floating back chevron is already the intended back affordance — it remains visible in a plain browser session. | #10000, #9902, #9817 | The in-page button was rendering simultaneously with the native app shell's own back control on the same screen, the root cause of the "stray/duplicate back-button-and-header" symptom originally reported against this screen in #9817. Brings HealthSettings.tsx in line with the native-shell-detection convention its sibling components (DataSourcesView, DataSourceCard) on the same screen already use. |
| 2026-07-01 | Add a smart "Open PPP app" button to the mobile-web Data Sources phone-sources panel — deep-links to ppp://wellness with an app-store fallback; desktop web keeps the static copy unchanged. | #9907 | The web Data Sources screen only showed static "open PPP on your phone" copy with no action. Detect iOS/Android via navigator.userAgent and give mobile-web visitors a one-tap deep-link into the app, falling back to the Play Store / App Store if it isn't installed (visibilitychange guard). |
| 2026-07-01 | The "what fed this score" metrics breakdown now determines a source's contribution from the presence of its metric row for the date being viewed, not from whether that source is currently connected. | #9910 | filteredMetrics filtered historical metrics by the live connectedSources set, so any source not connected right now (including the connected-but-tokenless zombie state fixed in #9879) had its historical metrics silently stripped from the breakdown for every past date — even dates where it genuinely fed the score. The score itself reads health_metric directly and was unaffected; only the breakdown display was wrong. |
| 2026-06-27 | Correct geofence success-criterion AC — geo_fence_events=0 is expected in App Insights path; real signal is timesheets.source='geofence' + App Insights geofence_* events. Add wellness.geofence.arrival-signal AC + @regression BDD scenario. | #9547 | 24 Jun live test confirmed geo_fence_events had 0 rows in the UAT success path. The spec incorrectly cited geo_fence_events as the check; the observable success signal is a timesheets row with source='geofence'. Independent of the #9257 retire-vs-wire decision. |
| 2026-06-26 | The Readiness Score card no longer shows an alarming red 0 / 100 / "Low Readiness" to a newly-connected user before any readiness has been genuinely computed. When the score is null, or 0 with no contributing metrics (metricsUsed 0/null), the card renders a neutral, friendly onboarding prompt ("Complete your first questionnaire to see your readiness.") with non-red styling. A genuinely-computed low score (metricsUsed > 0, including a real computed 0) still renders the real low score in red — only the never-computed case changes. metricsUsed is threaded from todayScore.metricsUsed in DashboardView; callers that omit it keep the previous render (back-compat). New AC wellness.readiness.no-score-empty-state; new Open Question OQ-READINESS-EMPTY. | #9364, #9315 | On-device QA (2026-06-25) found a user who had just connected Apple Health (steps/HR/sleep flowing) still saw Readiness 0 / Out of 100 / Low Readiness in alarming red before completing the Weekly Wellness Questionnaire. A red 0 reads as "you are unwell" when the score simply has not been computed yet (it needs the questionnaire + a sync cycle). Shipped as the safe, additive engineering DEFAULT pending Matt's UX sign-off (for-discussion) — the never-computed case is diverted to a neutral empty state while genuinely-computed low scores are untouched. |
| 2026-06-26 | A wearable stuck in 'reconnect needed' (or error) state can now be removed, not only reconnected. The Wellness Data Sources card (DataSourceCard) previously rendered the Disconnect button only in the connected branch, so a broken-but-real connection row offered only a Reconnect button — a doctor who had stopped using the device (e.g. WHOOP) was trapped on a permanent "Reconnect needed" prompt and the page-level reconnect banner nagged forever. The card now also shows a secondary, destructive Remove button alongside Reconnect in the reconnect_needed/error states, reusing the same onDisconnect path the connected state uses. Removing the source runs the existing disconnect mutation whose onSuccess refetches getAvailable, so the cleared source drops out of the dashboard reconnectSources set and the reconnect banner disappears. Remove is suppressed for a never-connected source and while a reconnect is mid-flight; its visible "Remove" label is its accessible name (#7773). | #9362, #9316 | On-device QA (2026-06-25, #9316) found a user who stopped using WHOOP could not remove it and was nagged forever by the page-level reconnect banner. New AC wellness.data.remove-stale-wearable. |
| 2026-06-25 | The Wellness Data Sources "Phone Health Data" section is now device-aware AND tidier. Inside the bundled mobile app a phone-only source (Apple Health on iOS, Health Connect / Samsung Health on Android) shows only the source matching the device's OS, each with a real Connect button that opens the native health connect screen via the navigateToTabs bridge. The section was trimmed for minimal scrolling — the redundant "Get started with your phone" info Alert, the long intro paragraph, and the boxed device-permissions callout were removed (the card is rendered compact with a one-line permissions help caption), so Connect sits above the fold. On web (desktop or mobile browser) the three non-connectable phone cards are replaced by a single "open the PPP app on your phone to connect" message. The OAuth Wearables & Apps section is unchanged. | #9289, #9284, #8977 | Follow-up to the merged #9285. The section showed all three phone platforms on every device — including dead, non-connectable cards on web where phone sources can only be set up in the app — and stacked three overlapping "set up in the app" explanations. Make it device-aware and consolidate the copy so each context shows only what is actionable with little or no scrolling (Rob UX direction). New AC wellness.data.phone-sources-device-aware (the deeplink AC from #9285 is expanded to note platform-awareness and the tidy layout). |
| 2026-06-25 | Inside the bundled mobile app, the Wellness Data Sources card for a phone-only source (Apple Health / Health Connect / Samsung) now offers a real Connect button that opens the native health connect screen via the navigateToTabs bridge. On web the card still shows hint text only. | #9285, #9284, #8977 | On the web Data Sources page the mobileOnly cards render hint text only, so inside the native app the user was stuck on "Not Connected" with no way to reach the native Apple Health connect screen — also blocking #8977. New AC wellness.data.apple-health-connect-deeplink. |
| 2026-06-24 | Inbound provider webhook PUSH bodies (WHOOP, Garmin) are now validated against a Zod schema at the ingestion trust boundary before any user lookup or metric write. A malformed or drifted body fails closed — logged at error level and rejected, so no health_metric row is written for that delivery — while a valid body is processed as before. Oura is poll-only and has no webhook handler, so only WHOOP/Garmin are affected. New AC wellness.data.webhook-payload-validated. | #9270, #9240 | Each webhook handler previously cast the parsed JSON to a TypeScript interface via a hand-rolled type guard with no runtime parse — the "TS interfaces, not Zod" gap the #9010 ingestion epic called out and #9015 left at the webhook boundary. A provider silently renaming or dropping a field would pass the cast, produce undefined/NaN in the mapping, and write silent garbage to health_metric. Extends the #9015 runtime-validation pattern (OAuth API-response + mobile device-push boundaries) to the webhook push boundary, with each payload type now inferred from its schema so the type and validator cannot drift. |
| 2026-06-24 | Add structured ingest logging to mobile health push path (Apple Health, Samsung Health, Health Connect) — entry log with metric count/types, completion log with metricsWritten + scoreSaved, and a distinct warn for empty payloads. | #9256, #9010 | UAT observability gap — a device push was invisible in logs, making it impossible to prove whether data landed without a live device. Epic #9010. |
| 2026-06-24 | Add spec ACs for Health Connect ingest pipeline (wellness.data.health-connect-ingest) and iOS Apple Health truthful connect (wellness.data.apple-health-connect-truthful) — closes SGD C3/C7 drift for #9023 and #9022. | #9248, #9242, #9023, #9022 | PR #9214 (Health Connect) and PR #9022 (iOS Apple Health false-success fix) both shipped code without corresponding spec ACs. Adding these ACs prevents sgd:sgd-align from flagging C3/C7 drift on the next audit. |
| 2026-06-24 | Reconnect banner and "no data source connected" empty state are now mutually exclusive — a never-connected doctor no longer sees both simultaneously. | #9208, #9182 | Root cause: reconnectSources was computed from getAvailable.needsReconnect alone, without requiring evidence of a real data_source_connection row. Fix gates reconnectSources on a real connection row (connected | lastSyncAt | lastSyncStatus | lastError) and uses showConnectInvitation = !hasConnectedSources && !hasReconnectSources in DashboardView so the two states are XOR at render time. |
| 2026-06-24 | The page-level "needs reconnecting — your wellness data isn't syncing" banner on the Wellness dashboard now fires only when the doctor has no healthy connected source. A single stale provider (e.g. WHOOP) alongside other syncing wearables no longer raises the banner; the per-source "Reconnect" button on the Data Sources card carries it instead. | #9205, #9215 | During the demo rehearsal the WHOOP reconnect banner showed for a doctor whose Apple Health + Health Connect were syncing fine, falsely claiming their wellness data wasn't syncing and nagging about a provider they didn't rely on. Follow-up to #9182. New AC wellness.data.reconnect-banner-scope. |
| 2026-06-24 | Add /wellness/data-sources redirect to /wellness/settings; update onboarding step route to the canonical surface so deep links no longer 404. | #9254 | The native-app deep link (ppp://wellness/data-sources) and onboarding checklist both targeted /wellness/data-sources, which had no registered route. Confirmed live with Matt on 2026-06-24 (WhatsApp). The canonical Data Sources surface is /wellness/settings (renders HealthSettings.tsx/DataSources). |
| 2026-06-21 | Added Health Connect as an Android wellness data source — a new syncHealthConnectAndScore device-push endpoint (routed through the same validated mobile ingest path as Apple Health and Samsung) plus an Android HealthScreen with Health Connect source selection and a HealthConnectConnect UI. | #9029, #9023 | Health Connect is Google's cross-vendor Android health store and the primary Android phone-health path for non-Samsung devices; doctors on Android without a Samsung device previously had no on-device wellness source. |
| 2026-06-20 | Compact mobile layout so ~3 recommendation tiles fit on a 393×676 iPhone — buttons, date picker, and card padding shrink at xs; desktop layout unchanged. | #8979, #8932 | UAT report #8932 — the header section (title + date picker + three action buttons) consumed too much vertical space on iPhone, hiding the readiness/workload/sleep guidance tiles below the fold. |
| 2026-06-20 | WHOOP v2 data API base URL now carries the /developer path segment so data calls stop returning HTTP 404. WHOOP_OAUTH.API_BASE_URL → https://api.prod.whoop.com/developer, and whoopClient builds request URLs by concatenating base+path instead of new URL(path, base) (which silently strips /developer for leading-slash paths). OAuth endpoints (/oauth/oauth2/...) stay on the bare host and are unaffected. | #8974, #8930 | UAT (#8930 sub-4 "WHOOP still not connecting / page not found") — confirmed via UAT Azure logs and a live probe: GET /v2/user/profile/basic resolved to the bare host and returned 404 ("default backend - 404"), so the externalUserId never resolved and a connected WHOOP source was marked unusable. Originally assumed to be a WHOOP developer-dashboard redirect-URI config fix; root cause was the missing /developer data-API base. Corrects the wellness.data.reconnect-ux source note accordingly. |
| 2026-06-20 | Weekly Wellness Questionnaire fits one mobile screen — tighten the inter-question and per-field Stack spacing at xs and hide the in-title date field at xs in submit mode (submission defaults to today), so the fullScreen mobile dialog (393×676) renders all five questions and the Submit/Cancel actions without vertical scroll. | #8972, #8931 | UAT (#8931) — the fullScreen mobile questionnaire overflowed the viewport (header ~140px + actions ~70px left ~466px for content needing ~560px), forcing the user to scroll down to reach Submit. Desktop rhythm preserved at sm+; ratings stay tappable; read-only viewers keep the date visible. |
| 2026-06-20 | Restored the wake-time row on the dashboard Sleep Guidance card (shows the default wake target 06:30, from which the derived bedtime is computed) and raised the sleep recommendation floor from 6 h to 7 h. SLEEP_MIN_HOURS is now 7 (the Target Sleep Load model's base/clamp floor and the readiness-only fallback's clamp floor); the envelope is re-anchored (floor 7, base 7, ceiling 10.5) so all four sleep bands stay reachable — a light, well-recovered day recommends exactly 7 h and lands Normal because the Normal cut-off (8 h) is strictly above the floor. The Normal band display range copy moves 6-8 → 7-8 to track the raised floor. New AC wellness.sleep.wake-target-shown supersedes wellness.sleep.no-wake-target; new AC wellness.sleep.floor-7h records the 7 h floor; wellness.sleep.range-headline and the OQ-SLEEP-FLOOR Closed Question are updated. | #8971, #8933 | Matt UAT direction 2026-06-20 (#8933), authorised by the product owner (Fraser) to be implemented the SGD-correct way (amend the spec + Change Log, never silently reverse). Both changes supersede recorded decisions: re-showing the wake-time row supersedes OQ M2 / #8656 ('the user wakes when they wake'); the 7 h floor supersedes OQ-SLEEP-FLOOR / #8208 (2026-06-10), which had lowered the floor 7.5 → 6 h specifically to make the Normal band reachable. The #8208 reachability fix is preserved at the 7 h floor — Normal's cut-off (8 h) still sits above the floor, so raising it does not re-introduce the unreachable-Normal bug #8208 fixed. A new test asserts all four bands remain reachable at the 7 h floor. |
| 2026-06-20 | Data-sources reconnect UX — scroll the reconnecting device card into view, return the WHOOP callback to /wellness/settings, and drop the redundant manual return button on the WHOOP auto-return path (Garmin/Oura keep it). | #8966, #8930 | UAT (#8930) — the reconnecting card could sit below the fold, the WHOOP callback dropped the user on the profile page outside the wellness feature, and the manual return button was redundant once WHOOP auto-closes its popup and auto-navigates. FE sub-items 1–3; sub-item 4 (WHOOP redirect-URI config) tracked separately. |
| 2026-06-19 | Oura and Garmin OAuth handleCallback now perform the same post-write read-back persistence verification WHOOP has had since #8634: after storeTokens they re-load the tokens and throw INTERNAL_SERVER_ERROR (never a false 'connected') if the write silently no-op'd. The read-back now guards all three OAuth providers. | #8887, #8874 | Surfaced during the #8866/#8871 review: Oura and Garmin shared the pre-#8634 gap, reporting success straight after storeTokens with no read-back, so a silently non-persisting write produced the same badge-says-connected-but-no-tokens failure class — every subsequent sync throws 'No tokens found'. Aligning the safety check across all three providers (now that they all run the signed-state callback) is a small, contained backend-only correctness fix. The signed-state / request-token auth path from #8866 is unchanged. |
| 2026-06-18 | WHOOP/Garmin/Oura OAuth token-exchange callback now authenticates off the cryptographically-signed credential (HMAC-signed state for WHOOP/Oura; userId-bound single-use request token for Garmin), not the interactive PPP session. handleCallback is a public procedure, so the mobile callback succeeds when it completes in the external system browser (no PPP session). A forged/tampered/expired credential is still rejected with BAD_REQUEST. | #8871, #8866 | On mobile the OAuth redirect completes in the external system browser (#8635), a separate cookie store from the WebView that carries no PPP session. handleCallback was a protectedProcedure, so the cross-browser hop failed UNAUTHORIZED and stranded the user on the callback error page with no tokens stored. The signed state already embeds the userId (the real CSRF/identity boundary), making the session requirement redundant and the cause of the failure. The #8634 read-back persistence verification and the #8635 deep-link return are preserved; the desktop popup flow is unchanged. |
| 2026-06-17 | Corrected WHO-5 banding thresholds from 52/28 to 66/33. Good wellbeing: score >66; Moderate: 33–66; Low: <33. Also corrected Low wellbeing copy to match Matt's exact wording ('and going forward'). | #8753, #8710 | Original 52/28 values were PPP's own adaptation. Matt explicitly confirmed the canonical three-band split on #8342 (comment 2026-06-17): 'Good Wellbeing >66 / Moderate Wellbeing 33-66 / Low Wellbeing <33'. The Low wellbeing copy was also corrected from '...this week.' to '...this week and going forward.' per Matt's exact wording on the same comment. |
| 2026-06-17 | Restored post-questionnaire wellbeing banding (Good / Moderate / Low wellbeing) with Matt's revised copy and removed the GP/colleague/supervisor referral advice line. The post-submit dialog again shows the WHO-5 score (0–100) plus a band label and a softer prompt copy. | #8710, #8342 | PR #8694 (fixing #8342) removed the category label and advice entirely (Option A). Matt's follow-up on #8342 (2026-06-17) confirmed the banding should be kept but with softer copy and no clinical referral advice — the GP/colleague/supervisor line stays deferred under M5 Supportive Alerts (not yet shipped). |
| 2026-06-16 | Full Fitbit removal — purged the dormant Fitbit provider stack: the backend provider module (client/mapper/syncService/types/index), the Fitbit OAuth service + tRPC router, the Fitbit adapter and its registrations, packages-shared constants/fitbit.ts, the Fitbit branches in the scheduler/sync/provider-priority/metric-type/scoring configs, the frontend Fitbit callback components + route, the Fitbit references in the Guide docs, and the unused Fitbit env keys — together with all their tests. Retained the FITBIT enum value and its dataSources router DataSourceSchema entry plus the generic disconnect path so a pre-existing historical Fitbit connection can still be seen as connected and disconnected (no Fitbit-specific OAuth revoke remains). The connect procedure schema (ConnectableDataSourceSchema) now explicitly excludes FITBIT so a new Fitbit connection cannot be created via the API. | #8697, #8690, #8667 | Follow-up to #8667/PR #8687, which removed Fitbit from the connectable surface but left the full backend/OAuth/callback/constants in place. Fitbit is no longer a supported integration (Fitbit Web API retiring in favour of Google Health Connect), so the remaining code was unmaintained dead weight that confused the surface area and carried test burden (#8690). |
| 2026-06-16 | Wellness data-sources panel cleanup — removed Fitbit from the connectable surface (enum + schema retained for historical connections), removed the duplicate "Health Monitoring" device card so each phone source appears once, co-located the device-permissions guidance inside the Phone Health Data panel, and replaced the misleading "Coming Soon" badge on mobile-only phone sources with copy explaining the connection completes in the PPP mobile app. | #8687, #8667, #8633 | Dev Session 2026-06-16 demo (#8667): Fitbit no longer exists as a supported integration, Apple Health appeared twice (top + as a "health monitoring device"), the device-permissions block was separated from the phone-health panel, and the desktop "Coming Soon" wording was confusing. Apple Health web copy also clarified as iOS-app-only (#8633). |
| 2026-06-16 | Post-questionnaire confirmation dialog keeps the WHO-5 score (0-100) plus a neutral submission-confirmation message and no longer shows a wellbeing category label ("Low / Moderate / Good wellbeing") or supportive/clinical advice copy ("reach out to a colleague, supervisor, or GP"). | #8685, #8342 | The category label, the 52/28 thresholds and the advice copy were engineering-added in PR #5379 while fixing the silent-close bug #4863 — never prescribed by Matt — and the advice pre-empted the deferred Supportive Alerts decision (M5, trigger criteria TBD). Decision captured Dev Session 2026-06-16: the post-questionnaire prompt is not in the feature spec; reword or remove. Score feedback is retained; supportive messaging returns once M5 is defined. Neutral confirmation wording is an engineering proposal pending Matt's sign-off. |
| 2026-06-16 | Updated the wellness.pulse.embedded-clickthrough AC to name the renamed "Add check-in" weekly-questionnaire button (was "+ Add"). | #8684, #8641 | PR #8684 renamed the PPP Pulse add button to "Add check-in"; the wellness spec AC still referenced the old "+ Add" label and would have drifted from the implementation. |
| 2026-06-16 | WHOOP OAuth returns the user to the native app after authorising instead of stranding them in the external browser (Safari). The native-app context is signed into the OAuth state, the callback echoes the verified flag, and the WHOOP callback page deep-links back via the ppp:// URL scheme, with the in-browser data-sources fallback intact for users without the app installed. | #8682, #8635 | UAT (Safari, /wellness/settings): after completing WHOOP auth the user stayed in the web/browser version rather than redirecting back to the app (#8635). WHOOP bounces out to the system browser for the redirect, so the callback had no opener/bridge to signal a return. |
| 2026-06-16 | Align readiness bands to one shared source of truth (High ≥75 / Moderate 50–74 / Low <50); lower Normal sleep copy "7-8"→"6-8" to match the 6h model floor and drop the wake-target row; reframe the PPP Pulse average label so it is distinct from the headline readiness score. | #8679, #8637, #8656, #8655 | The Readiness card and Workload card classified the same score into different bands (#8637); the Normal sleep copy contradicted the model floor and the wake-target field was dropped per spec M2 (#8656); the headline score and the 1-month average could read as a duplicate (#8655). |
| 2026-06-16 | Recalibrate the readiness curve — renormalise the overall score over present components, and retune the sleep-load amplifier (trigger 0.7→0.5, factor 1.5→1.2) so an average day reads Moderate not Enhanced. | #8678, #8435 | An average day read too high. Absent components folded their zero-input default sub-score into the overall score, and the morning-readiness amplifier fired on virtually every working day. Full-data days (all components present) are unchanged — present-weight sum is 1.0, so the renormalised score equals the legacy weighted sum and pinned integrity scores hold. Amplifier values and renormalisation are engineering proposals adopted per user direction; re-validate against Matt's spreadsheet. |
| 2026-06-16 | ScoreHistoryChart (the shared PPP Pulse chart) re-asserts pointer-events on its header "+ Add" button and range-pill switcher so they stay tappable when the chart is embedded under the dashboard Pulse card's navigation overlay. | #8673, #8640 | Supports the #8640 dashboard fix — the Pulse card now disables pointer-events on the embedded chart so taps route to /wellness; the chart's own interactive controls must opt back in. |
| 2026-06-16 | Truthful wearable connection state — a CONNECTED row with no stored OAuth tokens or an errored last sync now reports "Reconnect needed" instead of a false "Connected", surfaces an actionable reconnect banner, hardens WHOOP OAuth callback token persistence with read-back verification, and adds structured logging at the previously-silent sync-failure points. | #8662, #8632, #8634, #8633 | Live UAT demo showed WHOOP "Connected" while every sync threw "No WHOOP tokens found" and the dashboard silently rendered "contributing metrics not available" — connection state was decoupled from actual token presence (#8632/#8634); Apple Health web copy clarified as iOS-app-only (#8633). |
| 2026-06-10 | Added code-paths for fitbit.ts, garmin.ts, oura.ts, whoop.ts | #8606, #8485 | Wearable OAuth/provider config belongs to the wellness data-sources feature; drift gate now fires correctly when provider constants change, per #8485 |
| 2026-06-10 | The PPP Pulse chart is adaptive at phone width. The in-chart legend is hidden on mobile (the two series labels render as colour-glyphed captions below the chart, next to the average annotations) and the freed band returns to the plot - the chart grows to 230px at phone width so the visible plot roughly doubles. Desktop is unchanged. | #8504, #8257 | The chart was a fixed 200px at every viewport and the mobile legend band reserved 72px inside it, leaving about 110px of actual plot - the "squished" Pulse Matt reported on mobile (issue 8257). Each previous legend fix had been paid for out of the plot because the height never adapted. |
| 2026-06-10 | Three dashboard polish fixes. The "Guidance Available" placeholder headline is removed - when the guidance level is unrecognised, the guidance advice itself fills the workload card. The readiness, workload and sleep cards carry a traffic-light stripe down the left edge, coloured from the shared tokens, with text band labels retained so colour is never the sole signal. At phone width the wellness header collapses to a single heading - the friendly date line yields to the date picker and the header padding tightens. | #8493, #8217, #8199, #8258 | Matt's 03-Jun call feedback, implemented per the 10-Jun triage. "The guidance advice should be in the box where it says guidance available, and 'guidance available' shouldn't be there" (8217); the cards "should be colour-coded... consistent with the traffic-light system" (8199, stripe = recommended treatment, swappable on the walkthrough); and the mobile double-heading bug report (8258, whose text-behind-buttons half was already fixed by 8333). |
| 2026-06-10 | The sleep band dividing lines now match the displayed ranges - under 8 h reads Normal "7-8", under 9 h Moderate "8-9", under 10 h Enhanced "9-10", and 10 h+ Maximise "10+". The cut-offs are derived from the locked display ranges via a single shared constant (SLEEP_BAND_CUTOFFS from SLEEP_BAND_RANGES), so the computed hours and the range on the card can never disagree again. The source-model ceiling becomes a named 10.5 h constant (half an hour above the Maximise cut-off) so the 10 h+ band stays reachable. | #8486, #8359 | Matt confirmed option A on issue 8359 (2026-06-09) - line the band cut-offs up with his locked display ranges. The previous cut-offs (6.5/8/9.5) were old spreadsheet values that never matched the displayed ranges (7-8/8-9/9-10/10+), so a computed 7.6 h showed as "8-9 h". Per Rob's steer the fix is structural - one derived constant rather than two hand-maintained sets of numbers. |
| 2026-06-10 | Claimed packages-shared/ppp/src/constants/wellness.ts + wellness-scoring-config.json in code-paths | #8483, #8481 | cpd-home no longer claims the whole shared-constants dir; these two files hold spec-coded values (SLEEP_BAND_RANGES, scoring weights) the wellness ACs cite, so the drift gate must attribute them to wellness |
| 2026-06-10 | The sleep recommendation's DaytimeRecovery input now averages only the recovery components that have data for the day, and a fully absent recovery group reads as neutral (0.5) instead of zero. Workload components keep their fail-soft absence semantics. With the 6-10 h envelope, a sparse-data average 8 h day now reads Normal (7.86 h) and a sparse 10 h day reads Moderate (8.29 h), instead of everything reading Enhanced/Maximise. Full-data days are unchanged. Additionally, activeRecovery is removed from the sleep-load recovery group, so tracked light exercise (e.g. a post-work sauna or walk) no longer reduces the recommended sleep hours - it still counts toward the overall readiness score. | #8460, #8458, #8435, #8089 | Investigating Matt's "average ~10h day reads Maximise" observation (#8435) found that absent metrics were folded in as zero, and the recovery formulas score zero input as worst-case - so any day without wearable data collapsed DaytimeRecovery to 0 and maximally inflated the Target Sleep Load. The source spreadsheet never modelled missing data; unknown recovery is not zero recovery. The curve-recalibration decision itself stays with Matt on #8435. The activeRecovery change implements Matt's explicit 03-Jun confirm on issue 8089 (light exercise does not reduce the need for sleep - he flagged it as a likely drift, and the check confirmed it); the remaining input-mapping sign-off, including the meditation grouping, stays on issue 8461. |
| 2026-06-10 | The sleep-recommendation envelope was re-anchored from 7.5-10.5 h to 6-10 h (floor 6 h, base 6 h, amplitude 4; curve shape unchanged). The Normal band (cut-off under 6.5 computed hours) is now reachable, so a light, well-recovered day reads "Normal recovery, aim for 7-8 hrs" instead of being pushed up to Moderate. Band ranges and prompts are unchanged. OQ-SLEEP-FLOOR moved to Closed Questions. | #8452, #8208 | Publishing the sleep bands on issue 8208 surfaced that the source model's 7.5 h floor (locked 2026-05-27, "follow the spreadsheet") made the Normal band mathematically unreachable - one of the four locked bands could never appear. Decision on the 2026-06-10 session, "Normal has to be achievable" - the floor was lowered to the 6 h clinical minimum the model already defined as SLEEP_MIN_HOURS, so the app still never recommends an unhealthy amount of sleep. |
| 2026-06-09 | Wellness data-source connection status now refetches whenever the page or app regains focus (staleTime 0 + refetchOnWindowFocus on getAvailable and the OAuth getConnectionInfo queries), and the native WebView shell dispatches a focus event on app foreground so iOS WKWebView cannot suppress the refetch. | #8418, #8334 | A UAT tester saw a wearable showing connected in mobile Safari but disconnected in the app. UAT logs confirmed the same userId from both Safari and the app WKWebView, so the backend returned identical data and the split was a stale client cache — the connection queries cached for 5 minutes and the app never refetched on foreground. |
| 2026-06-09 | Wellness dashboard cadence caption no longer overlaps the action buttons on mobile. | #8390, #8333 | The "Weekly collection..." hint under Complete Questionnaire was absolutely positioned and overlapped the stacked Check Sources button at mobile width (393px); it now renders in normal flow at every viewport. |
| 2026-06-09 | PPP Pulse chart now colour-codes the readiness dots to the traffic-light scheme via a piecewise y-axis colorMap (red below 70, amber 70-84, green 85+) sourced from the shared wellnessTrafficLight SEMANTIC_COLORS tokens. The Weekly Wellness Questionnaire series renders in a single flat colour on a colorMap-free axis; the two average reference series were removed from the chart legend (they are already represented bottom-left as dashed-glyph annotations) and the average renders with no decimal places. | #8356, #8186 | On the 2026-06-03 Dev Session Matt flagged that the readiness/workload guidance and Pulse chart were not colour-coded to the traffic-light system and asked for the chart to be tidied. The readiness/workload bands follow the spec's published readiness band table; the "an 81 should read green" boundary tweak stays the open #8199 decision. |
| 2026-06-03 | Sleep Guidance card headline now shows the recovery band range (e.g. "8-9 h") instead of a single number, and the band ranges were realigned to Matt's locked values (Normal 7-8 / Moderate 8-9 / Enhanced 9-10 / Maximise 10+). Ranges live in a new shared SLEEP_BAND_RANGES source of truth read by both the frontend card headline and the backend guidance message strings. | #8302, #7670 | Matt confirmed the card should display the band range, not a single number, on 2026-06-03 ("it should be B"), and had locked the ranges on 2026-05-27 ("lock that in") — but neither had reached the code; the message strings still carried the older spreadsheet ranges (6-6.5 / 7-8 / 8.5-9.5 / 10+). The 7.5h floor, band thresholds, and sub-score input mapping remain open on #8208. |
| 2026-06-03 | Wellness dashboard readiness/workload/sleep cards now colour-code on one consistent traffic-light signal (green/amber/red) from a shared SEMANTIC_COLORS-backed helper (wellnessTrafficLight.ts), replacing three separate hardcoded-hex systems. Colour always paired with the text label. | #8225, #8199 | Matt's 2026-06-03 call feedback that the wellness panels "didn't look right" — the colour coding was inconsistent across cards and used hardcoded hex (#7525). Readiness green threshold (Matt's "81 should be green") kept open on #8199 pending his confirmation. |
| 2026-06-03 | Aligned the evening sleep-notification spec citation, BDD scenarios and eveningDrawService comments to the shift-aware bedtime-derived ceiling (#6788), retiring the stale fixed-21:00-ceiling references. Tagged the proving scenarios @issue-6430. | #8212, #6430 | sgd:gap on #6430 — the shift-aware trigger was already implemented (#6429/#6788) and confirmed by Matt's Notion page + the 2026-05-12 transcript, but the spec/BDD/comments still encoded the retired 21:00 clock ceiling (one stale scenario even asserted a non-existent "hard-ceiling-21-local" reason and "fires regardless of shift", which contradicts the on-active-shift guard). Drift cleanup, no behaviour change. |
| 2026-06-03 | Workload Recommendation rewired to three readiness tiers — top band 0.85→0.75, collapsed 4 active bands to 3 (High ≥75 / Moderate 50–74 / Low under 50) with Matt's verbatim copy; severe "Poor" band defined but dormant pending the parked under-40 boundary. Sleep "Maximize"→"Maximise" UK spelling fixed. | #8203, #6161 | Matt's 2026-05-13 Notion note (reaffirmed on the 2026-06-02 call) moved the high-readiness threshold to 75 because the live algorithm rarely scores into the 90s, making 85 hard to attain. The sleep Target Sleep Load model already shipped (#7670/#7674); the traffic-light visual is split to #8199. |
| 2026-06-02 | HEALTH_CONNECT added to the wellness DataSourceSchema enum so getStatus/connect/disconnect accept the advertised device source instead of returning a validation error. | #8063, #8029 | getAvailableSources advertised health_connect (#7929) but the connection-management z.enum omitted it, so status/connect/disconnect 400'd — an advertised-but-unconnectable source (latent contract gap, surfaced in #8023 review). |
| 2026-06-02 | Fully retired Google Fit — deleted the backend OAuth/provider stack, removed GOOGLE_FIT from the DATA_SOURCES enum, and migrated away dead connection rows. | #8023, #8006, #8007 | Google Fit's REST API is closed to new sign-ups and reaches end-of-service end of 2026, and the web app no longer surfaces it (#7929). Leaving a full OAuth + provider stack plus injected secrets as dead code was a maintenance and security-surface liability. |
| 2026-06-01 | Removed deprecated Google Fit from Connect Your Data; added Health Connect as an on-device Android source. | #8004, #7929 | Google Fit's REST API is closed to new sign-ups and reaches end-of-service end of 2026 with no direct replacement, so it should not be surfaced as connectable. Health Connect is its on-device Android replacement, connected via the PPP mobile app. |
| 2026-05-27 | The PPP Pulse chart legend is moved out of the bottom band (where it collided with the x-axis date labels) to the top-right of the plot on desktop, and stacks below the plot on mobile. Chart margins now adapt to the viewport so the legend never overlaps the plot or x-axis. | #7805 | In the 2026-05-27 demo run-through Rob found the bottom-band legend rendering over the x-axis tick labels, colliding with them and wasting vertical space. A top-right desktop legend with an adaptive mobile stack uses the space well and keeps the x-axis readable for the 28 May demo. |
| 2026-05-27 | PPP Pulse chart now defaults to a 1-week (1W) window on first load (a new 1W pill joins 2W/1M/3M/6M) and the legend is repositioned into a dedicated band below the plot so it no longer crowds the series. | #7765 | In the 2026-05-27 demo run-through Matt and Rob found the 2-week default visually busy; a 1-week default plus a clear-of-the-plot legend reads cleaner for the 28 May demo. Users can still switch to 2W/1M/3M/6M. |
| 2026-05-27 | Make the interactive wellness-algorithm docs charts zoomable/clickable by opting the shared LineChart.vue wrapper into the existing useDiagramZoom.ts zoom/pan/fullscreen toolbar (added the .zoomable class). All three chart components (LineChart, WellnessCurves, SleepExplorer) render via LineChart, so every chart on the algorithm page gains hover-to-reveal zoom controls plus Ctrl/Cmd-wheel zoom and drag-to-pan. Reuses the existing mechanism instead of duplicating zoom logic. | #7725, #7644 | Matt wanted to zoom in to inspect the formula curves on the wellness-algorithm docs page, but the charts rendered as plain inline SVG with no .zoomable class so the global diagram-zoom enhancer skipped them (27 May 2026 catchup transcript, ~00:07:48). |
| 2026-05-27 | Reverted the Sleep Recommendation to the source spreadsheet's three-input Target Sleep Load model ("Wellness Algorithm Comm.xlsx", E30–E34). Added calculateTargetSleepLoad + calculateSleepGuidanceFromLoad in scoreService.ts (7.5 h floor verbatim) and sleepLoadInputs.ts to map the live component breakdown onto the model's workload/daytimeRecovery/morningReadiness inputs; calculateAndSaveScore now uses the source model on the persisted-score path. Recommended sleep now responds to the day's workload and daytime recovery, not the readiness score alone. Flipped the AC marker ⏳→✅, added Open Questions OQ-SLEEP-MAP and OQ-SLEEP-FLOOR, and rebuilt the algorithm explainer's SleepExplorer into per-input panels. | #7674, #7670, #6161 | The live app had derived recommended sleep hours from the readiness score alone since the first commit — drift from the design of record flagged on #6161. Matt confirmed on 2026-05-27 that the spreadsheet model is correct and the readiness-only formula should be reverted, corroborating the standing requirement from Matt 2026-05-03 (#4872) and transcript-2026-05-12 §SleepGuidance (#6434). |
| 2026-05-27 | Clicking the weekly wellness-questionnaire reminder in the notification bell now opens the questionnaire inline as a modal in place, instead of navigating to /wellness. | #7606 | Reuse the inline questionnaire modal (#7350) from the bell so doctors complete the weekly questionnaire without hunting for the button on the Wellness page; the /wellness deep-link is kept as a fallback for surfaces that do not expose the inline modal. |
| 2026-05-26 | Enforced wellness.privacy.no-enterprise-individual-share at the org-dashboard API layer. Added wellness-privacy.guard.ts (assertNoIndividualWellnessShare + guardWellnessCohort, reusing the existing COHORT_THRESHOLD=5) and an invariant test proving no org-dashboard procedure can return individual-level wellness data (PPP Pulse, readiness band, sleep guidance, workload recommendation). Flipped the AC marker ⏳→✅. | #7508, #7481 | The constraint was previously satisfied only by absence of a wellness section in the org dashboard, with no guard or test preventing regression. Matt requires individual wellness data is never shared with the enterprise (transcript-2026-05-12 §DataSharing) to avoid employers restricting a doctor's work. |
| 2026-05-26 | Reconciled four wellness AC markers from ⏳ to ✅ that the #7315 spec-audit listed as deferred but which are already shipped — Aura/Oura Ring OAuth connection, the 24-hour scheduled poll per connected source, the prominent readiness score, and the sleep/workload guidance cards. Each marker now carries a src: citation to the implementing file(s), and the Aura line notes that "Aura" is Matt's spelling of the Oura Ring. | #7487, #7482, #7315 | Spec-audit decomposition (#7315) flagged these as unimplemented, but code review confirmed they are built and wired: ouraOAuth.ts + providers/oura/ + OuraCallbackContainer.tsx (OAuth), scheduledWellnessSyncService.ts + run-wellness-sync.ts (24h poll), and ReadinessScoreCard/SleepGuidanceCard/WorkloadGuidanceCard rendered in DashboardView.tsx (display). Doc-only marker sync; no production code change. Existing BDD scenarios already cover these ACs. |
| 2026-05-26 | Wearable OAuth callbacks now complete the token exchange on the redirect-fallback / mobile path (no popup opener) instead of silently discarding the auth code, and the connect screen refreshes connection state without a manual reload. | #7407, #7353, #7341 | Users completed WHOOP/wearable OAuth but the connect screen still showed "not connected" and a refresh didn't help (#7353, #7341). The window.opener === null guard added for #4869 over-broadly skipped the exchange. Now the no-popup fallback only shows on a genuine param-less direct visit; the exchange runs whenever OAuth params are present. Defect of immediate post-connect data pull remains tracked in #7315. |
| 2026-05-21 | AC wellness.settings.in-app-config-screen marked ✅ — /wellness/settings route implemented as HealthSettings.tsx with Health Monitoring, Location Services, and Connected Data Sources panels. Check Sources button on wellness dashboard now navigates to /wellness/settings instead of /my-profile#wellness-data-sources. | #7024 | AC was ⏳ Specified (#6428). Implementation closes the spec gap; traces to Dev Session 2026-04-14 §MobileAppSettings (~00:33:26). |
| 2026-05-20 | Mark wellness.data.phone-fallback-insight AC complete — phone-only users already receive a Pulse insight via the phone-fallback scoring profile and "Estimated from phone data" badge (delivered in #5984) | #TBD, #6427 | Verification of existing implementation; AC newly surfaced from Dev Session 2026-05-12 §DataInputHierarchy |
| 2026-05-20 | Verified wellness.prompts-as-notifications — Pulse coaching prompts (morning Workload Recommendation, evening Sleep Recommendation, weekly Questionnaire reminder) are delivered as in-app notifications only. | #6621, #6436 | Centralised PULSE_COACHING_PROMPT_TYPES in notification-types.ts excludes Pulse prompt types from ALL_ACTION_NOTIF_TYPES, ACTIONABLE_NOTIF_TYPES, and REMINDER_NOTIF_TYPES, so they surface in the Notifications feed only and never as Action Items or reminders. |
| 2026-05-20 | Documents AC wellness.settings.in-app-config-screen as a known gap. Audit of mobile/ppp/lib/modules/settings/screens/SettingsScreen.tsx confirms the mobile Settings tab currently surfaces clinical reference data (hospitals, specialities, procedures, etc.) but exposes no controls for location-services or health-monitoring permissions, so users who decline (or mis-tap) during onboarding still cannot reset preferences without leaving the app. AC remains ⏳ pending implementation; adds a @wip @known-issue-6428 BDD scenario in wellness-data-sources.feature to capture the expected behaviour for the future build. | #6428 | Closes Matt's 14 Apr Dev Session brief (§MobileAppSettings ~00:33:26) by surfacing the gap explicitly in the spec/changelog rather than silently leaving it as an SGD-gap-analysis bullet — keeps traceability when the build later flips the AC to ✅. |
| 2026-05-20 | Mark wellness.evening-draw-shift-agnostic AC complete — flipped ⏳ → ✅ with file:line citation | #0, #6429 | Pure evaluateEveningDrawTrigger in eveningDrawTriggerService.ts:106-165 enforces all three preconditions (outside geofence, not on shift, awake ≥ threshold) plus 21:00 local hard-ceiling fallback at line 121. Coordinated scheduler wiring lives in #6014. |
| 2026-05-20 | Flips AC wellness.pulse.who5-overlay to ✅ — verified the PPP Pulse widget's ScoreHistoryChart already co-plots the Weekly Wellness Questionnaire (WHO-5) series over the readiness (Pulse) series on a shared 0–100 y-axis across the 2W/1M/3M/6M window. Adds a @regression @smoke BDD scenario tagged @issue-6431 so the two co-plotted series stay rendered together. | #6431 | Closes Matt's 22 Apr Dev Session brief — "the PPP Pulse widget overlaid with the WHO Five weekly questionnaire for trend analysis" — and pins the two-series overlay against silent regression to a single-series chart. |
| 2026-05-20 | Verified wellness.no-user-toggle-v1 — confirmed no user-facing opt-out toggle for wearable-based reminders exists in instances/ppp/src/modules/Wellness/; flipped status ⏳ → ✅. | #TBD, #6438 | V1 deliberately omits a toggle; behaviour matches the 12 May 2026 decision (transcript §UserControl ~00:25:01). Spec unchanged. |
| 2026-05-20 | Verified wellness.pulse.three-scores AC — flipped to ✅ | #TBD, #6433 | Pulse dashboard already renders the three top-line score cards (ReadinessScoreCard, WorkloadGuidanceCard, SleepGuidanceCard) as Row 1 of instances/ppp/src/modules/WellnessScore/Dashboard/DashboardView.tsx, and the weekly questionnaire cadence is enforced. Added readiness-score data-testid and a @smoke @issue-6433 BDD scenario asserting the three header cards render. |
| 2026-05-20 | Evening Pulse trigger — awake threshold raised to 14 h; 21:00 clock-time ceiling replaced with a bedtime-derived ceiling (latest_prompt_time = wake_target − recommended_sleep_hours). | #6797, #6788, #6430 | The 21:00 fallback was firing for night-shift doctors mid-shift. Deriving the ceiling from each user's wake target and tonight's recommended sleep hours adapts the prompt to the doctor's actual sleep window. |
| 2026-05-20 | Intra-night wake recalibration — readiness sleep input now sums total time asleep across all overnight segments when the doctor wakes mid-night and falls back asleep, instead of using only the longest segment. | #6784, #6430 | Matt 2026-05-20 on #6430 — Whoop and Apple Watch already recalibrate when sleep is interrupted; PPP needs the same. The Oura and Whoop API mappers were picking a single 'main' sleep period and discarding split-sleep segments. The mappers now emit one health_metric row per overnight segment with distinct (startTime, endTime) windows; the priority resolver keeps every segment from the winning source; the scorer's transformMetricsToInputs sums sleep_duration / deep_sleep / rem_sleep across segments. No schema change — multi-row segments already storable. Non-additive metrics (HRV, resting HR, respiratory rate) keep the single-pick-per-source rule. |
| 2026-05-20 | Flips AC wellness.pulse.sleep-guidance-recompute to ✅ — sleep guidance is already computed by morningDrawService after the user wakes (via calculateAndSaveScore, which persists sleep target + bedtime + wake target alongside readiness and workload), then re-computed by eveningDrawService between 18:00–21:00 user-local using the day's strain, so the morning recommendation is overwritten with one informed by today's workload and activities. | #6434 | Closes Matt's 12 May Dev Session brief (§SleepGuidance ~00:33:30) — "sleep guidance recommendation will be computed in the morning after the user wakes and will be recomputed in the evening based on the day's activities". Verified at api/backend-ppp/src/services/wellnessService/readiness/draws/morningDrawService.ts:9 and eveningDrawService.ts:1-26. |
| 2026-05-20 | Flips AC wellness.privacy.three-prompts-not-shared to ✅ — the system already delivers exactly three supportive coaching prompts per day via the existing draw scheduler (morningDrawService.ts recomputes PPP Pulse / Workload Recommendation / Sleep target in one pass; eveningDrawService.ts refreshes Sleep Recommendation only, capped at 21:00 local), and prompt content is never shared with the enterprise (paired with wellness.privacy.no-enterprise-individual-share — Org Dashboard receives only k-anonymity cohort aggregates). Adds an @issue-6435 smoke BDD scenario to lock the three-prompt invariant. | #6435 | Closes Matt's 12 May Dev Session brief (§RecommendationsPolicy ~00:17:51) — "three supportive prompts/coaching reminders regarding capacity and rest; the information will not be shared directly with the enterprise" — pinning the count and the no-share guarantee against regression. |
| 2026-05-20 | Flips AC wellness.notifications.non-tickable to ✅ — wellness prompts (wellness_questionnaire_reminder, wellness_reminder) are already centralised in PULSE_COACHING_PROMPT_TYPES and deliberately excluded from ALL_ACTION_NOTIF_TYPES, so the Notifications module's ALL_ACTION_TYPES_SET filter keeps them out of the Actions / Action Items tab and they carry no completion state. Adds an @issue-6437 regression BDD scenario to lock the invariant. | #6437 | Closes Matt's 12 May Dev Session brief (§NotificationStructure ~00:40:21) — "these items should appear as non-tickable notifications, not action items or to-dos" — and pins the categorisation against silent regression. |
| 2026-05-20 | Verified wellness.settings.no-toggle-yet AC — flipped to ✅ | #TBD, #6439 | Code search confirms no PPP Pulse toggle/opt-out setting exists in instances/ppp/src/modules/Wellness/ or anywhere in instances/ppp/src/. v1 decision (12 May 2026) is implemented as the absence of a toggle, matching the spec. |
| 2026-05-19 | PPP Pulse widget daily-mapping chart is now backed by a pure buildDailyMappingSeries helper (one slot per calendar day across the 2W/1M/3M/6M window, with empty days kept as null so readiness and WHO-5 stay day-aligned for correlation); flips AC wellness.pulse.daily-chart to ✅ and adds vitest + BDD regression cover. | #6432 | Closes Matt's 12 May Dev Session brief — "the widget needs to display a daily mapping chart of the PPP Pulse and the Wellness Questionnaire" — and pins the per-day mapping invariant against silent regression to a sparse / week-bucketed series. |
| 2026-05-13 | Wire the Android variant of mobile/ppp/lib/modules/health/screens/HealthScreen/HealthScreen.tsx to the Samsung Health integration. Replaces the previous "Not implemented" developer placeholder with a real screen that renders the existing SamsungHealthConnect connection component, a manual "Sync now" action that calls syncOnForeground() from samsungHealthSync, and a graceful "coming soon" fallback for non-Samsung Android devices. Adds an @regression @issue-4890 BDD scenario in instances/ppp/e2e/bdd/features/wellness.feature pinning that an Android user opening the Health tab sees the Samsung Health connection control and never the "Not implemented" string. | #4890 | Android users were locked out of health data entirely — the Samsung Health reader, mapper, sync service, and connection component all already existed but were never mounted into the Android Health screen, so the only thing rendered was <Text>Not implemented</Text>. This PR closes the wire-up gap rather than introducing new health functionality. |
| 2026-05-13 | Land the shift-agnostic evening-draw trigger logic. New eveningDrawTriggerService exposes a pure evaluateEveningDrawTrigger evaluator that fires the Sleep-Recommendation draw when the user is (1) outside a hospital geofence, (2) not on an active shift (no timesheets row whose [startTime, endTime] window contains now), AND (3) awake for >= awakeThresholdHours (default 12h — Rob to finalise). 21:00 user-local remains a hard fallback ceiling that fires regardless of geofence/shift/awake state. A DB-backed shouldFireEveningDraw wrapper resolves geofence/active-shift state from geo_fence_events and timesheets for one-off use (admin trigger, debug portal). The trigger is inert until the scheduler/cron wiring lands in #6014. | #TBD, #5940 | The previous fixed 18:00 → 21:00 push-if-geofenced rule fired during active night shifts and never fired for day-shift users who finished before 18:00 but had no geofence event recorded. Matt agreed the 12 May call decision: evening draw must be shift-agnostic — triggered on time-awake + outside-shift status, with 21:00 as the hard ceiling so the draw is never silently missed. |
| 2026-05-13 | Lock in Moreton Blue wellness prompts as final copy; strip emojis from fixtures/spec/style-guide; correct workload to 4-band (85/70/50) matching backend. | #6120, #5995 | Matt confirmed 2026-05-13 that the Moreton Blue strings in DEFAULT_GUIDANCE_CONFIG are final and dislikes emojis in user-facing copy (reads as AI-generated). The post-hoc style guide and Storybook fixtures had drifted; this PR aligns them. |
| 2026-05-13 | Deploy the wellness morning and evening draw schedulers as Azure Container App Jobs in UAT (wellness-morning-draw-uat, wellness-evening-draw-uat). New morningDrawService.runMorningDraw and eveningDrawService.runEveningDraw orchestrators iterate every user with a CONNECTED data-source (OAuth or device) in batches of 50 and recompute the daily score row via calculateAndSaveScore. The morning draw recomputes Pulse, Workload Recommendation, and Sleep target. The evening draw recomputes the Sleep Recommendation only, gated by shouldFireEveningDraw (#5940) so users still inside a hospital geofence or on an active shift are deferred to the next hourly tick — the 21:00 user-local hard ceiling fires the recompute regardless. Cron in Pulumi: morning job 0 * * * * (hourly, idempotent — covers every user-local 06:00 across timezones), evening job 0 17-21 * * * (hourly between 17:00 and 21:00 UTC, covers the 18:00 → 21:00 user-local window). Two new entrypoint scripts (scripts/run-wellness-morning-draw.ts, scripts/run-wellness-evening-draw.ts) are compiled by tsup and invoked by the jobs via node build/scripts/.... | #6117, #6014 | The wellness draw schedule is defined in docs/features/wellness.md § Draw schedule but no scheduler jobs existed in Azure — Pulse / Workload / Sleep recommendations were only recomputed on user-triggered reads, so users without a foreground app event missed the daily refresh. The Sleep Recommendation also could not adapt to today's strain at end-of-day. This lands the global hourly scheduler so per-user recomputes fire deterministically. PROD deployment intentionally deferred: the ppp-uk-prod Pulumi stack has never been initialised (verified via pulumi stack ls --all), so a prod apply would +create every prod resource — out of scope for this PR. Follow-up to stand up the prod stack independently before the wellness draws can ship to production. |
| 2026-05-13 | Record that PPP Pulse is non-dismissable in v1 — no user toggle and no backend opt-out flag. Open Question M8 added to revisit Pulse opt-out after the first user-testing round. | #6115, #5941 | Explicit architectural decision from the 12 May 2026 catchup. PPP Pulse is a core USP; an opt-out path is deferred until user testing surfaces genuine edge-case demand (e.g. users who physically cannot wear a wearable). Recording the decision in-spec prevents a reflexive "add a disable toggle" PR later. |
| 2026-05-13 | Rebrand user-facing "WHO-5" strings to "Weekly Wellness Questionnaire". Updates the todo-list reminder description in api/backend-ppp/src/services/todoListService/index.ts from "Your weekly WHO-5 wellness questionnaire is ready to complete" to "Your Weekly Wellness Questionnaire is ready to complete". Adds a regression BDD scenario in instances/ppp/e2e/bdd/features/wellness.feature pinning the new copy. | #5994 | Matt's product decision — patients and clinicians should never see the internal clinical-instrument code "WHO-5" in the UI. Internal constants, schema column names, and clinical/compliance documentation retain WHO-5 to preserve the validated-instrument provenance. |
| 2026-05-13 | Categorise PPP Pulse coaching prompts as Notifications, not Action Items — exclude wellness_questionnaire_reminder and wellness_reminder from the Actions / To-Do aggregate so they surface only in the Notifications feed. | #5942 | Coaching prompts are advisory nudges with no required-completion state; surfacing them as action items created false work-queue load and conflicted with the wellness.prompts-as-notifications AC. |
| 2026-05-13 | Add phone-derived fallback wellness score with reduced-confidence indicator. When no wearable provider has contributed metrics for a day, the score is computed via the PHONE_FALLBACK_WEIGHTS profile (zeros out HRV / resting HR / respiratory rate / SpO2 / sleep quality; redistributes onto sleep duration, training strain, active recovery, screen time, and PPP timesheet components). Backend exposes a source: 'wearable' | 'phone' | 'manual' field on every score; frontend renders an "Estimated from phone data" Chip on the Readiness Score card whenever source === 'phone'. | #5984 | Acceptance criteria from the 21 Apr 2026 transcript (issue #5984) — phone-only doctors must still get a score, but it must visibly carry a lower-confidence indicator and never override a wearable-sourced score when both data classes are available on the same day. |
| 2026-05-13 | PPP Pulse chart gains a 2W / 1M / 3M / 6M pill range switcher (default 2W) and 6-month average reference annotations for both the Weekly Wellness Questionnaire and PPP Pulse series; falls back to "N-month avg" when less than 6 months of data exist. | #5993 | Implements Matt's 17 Apr 2026 Notion brief — "WHO-5 mapped over PPP Pulse; latest 2 weeks / ability to change range of view / text for average numbers 6 months". |
| 2026-05-12 | Deploy daily wellness-sync Container Apps Job (daily 20:00 UTC) to pull Whoop/Oura/Garmin/Fitbit/Google Fit for all connected users. Add scripts/run-wellness-sync.ts runner and Pulumi resource in infra-azure. Apple Health remains push-only via the mobile tRPC endpoint. | #6035, #4826 | The daily OAuth wearable data sync was running only as an in-process cron inside the always-on container app with no standalone deployed job. The Rob & Matt call (13 Apr 2026) flagged this as a core functionality gap — wearable data was not reliably syncing to PPP. |
| 2026-05-12 | Transcript audit 2026-05-12 — §DataSharing classified R (requirement); 1 new AC added (wellness.privacy.no-enterprise-individual-share); 1 @wip BDD scenario added. All other R/F passages CONFIRM (already captured in wellness.md, hr-passport.md, dashboard.md, and organisational-dashboard.md from prior sessions). | #~ | §DataSharing (~00:17:51) of the 2026-05-12 Dev Session transcript ("PPP Pulse wellness deep dive, HR Passport, demo date set") confirmed that individual PPP Pulse scores, readiness bands, sleep guidance, and workload recommendations must never be shared directly with the employer or hospital enterprise. Matt's stated rationale: sharing individual scores risks employers restricting a doctor's work and undermines the platform's trust proposition; only anonymised cohort aggregates flow to the Organisational Dashboard. The anonymisation principle was already captured in organisational-dashboard.md (line 25) but wellness.md lacked an explicit AC anchoring it from the doctor's perspective. All other 2026-05-12 R passages (PPP Pulse non-dismissable, shift-agnostic evening draw, prompts as notifications, HR Passport domains, dashboard hover-overs, welcome-back frequency) were already fully captured in the respective specs. |
| 2026-05-05 | Applied Matt's 3 May 2026 Notion answers — M1/M2/M6/M7 resolved, M5 deferred post-MVP, M3 re-asked with engineering proposal, M4 style guide drafted at wellness/coaching-style-guide.md. Integrations order locked WHOOP → Apple HealthKit → Samsung/Google/Android → Garmin → Aura. Sleep wake-target field dropped (algorithm-driven per Matt). Onboarding wearable step updated to match. | #4870, #4872, #4868 | Spec was blocked on 7 Matt questions; 5 are now resolved with Matt's verbatim wording and the remaining 2 have a clear path (M3 awaiting confirmation, M5 explicitly deferred). |
| 2026-05-05 | Engineering-led answers for draw schedule (06:00 + 18:00→21:00 if still on-site), Weekly Wellness Questionnaire rebrand sweep, integrations list with Garmin paused note. Manual refresh confirmed already built (#4859). | #5563 | Closes the engineering-answerable items in #5563. Algorithm spreadsheet content (Q M4–M7) and supportive-alert criteria (Q M5) remain Matt-blocked. |
| 2026-04-22 | Drift re-baseline — 13 ACs added, 4 reworded, frontmatter reformatted, 7 Matt questions hoisted | #5348, #4890, #4874, #4873, #4872, #4871, #4870, #4869, #4868, #4866, #4865, #4864, #4863, #4862, #4826, #4700, #4677, #4651, #4646, #4976, #5135 | Audit docs/features/.drift-audits/wellness.md. Spec was self-declared partial-drift; 18 open issues were unlinked; closed #4976, #5135, #4861 unrecorded. |
| 2026-04-22 | wellness_reminder notification type registered on frontend with deep link | #4976 | Backend scheduler was emitting notifications the frontend couldn't route. |
| 2026-04-22 | Burnout image on wellness dashboard made clickable | #5135 | UX polish — image invited click but had no handler. |
| 2026-04-21 | Triage sweep — 19 open issues mapped to this spec | #4976, #4890, #4874, #4873, #4872, #4871, #4870, #4869, #4868, #4866, #4865, #4864, #4863, #4862, #4826, #4700, #4677, #4651, #4646 | Unblocks drift detection on the features index. |
| Mar 2026 | HRV label corrected from 'HRV deviation' to 'average HRV' | #3588 | Wrong terminology |
| Mar 2026 | Stop displaying data when no source connected | #3642 | Showing zeros was misleading |
| Mar 2026 | Enforce data hierarchy end-to-end | #3643 | Manual values were overriding wearable data |
| Mar 2026 | Remove manual data entry (Sync Data / DebugPortal) | #3647 | Static/manual values undermine data integrity |
| Apr 2026 | Apple Health 24-hour polling infrastructure required to make the source actually deliver data | #4826 | Matt (call 13 Apr 2026, ~00:04:57): the app wasn't connecting to his Apple Health data — polling loop was missing |
| Apr 2026 | 'Refresh now' button wired into the wellness dashboard (carved out of #4837 as a dup of #4765) | #4859 | Matt asked what triggers the sync; #4765 added the button on Data Sources, #4859 surfaces it on the wellness dashboard itself |
| Apr 2026 | WHO-5 questionnaire score is canonically 0–100 (standardized); chart Y-axis pinned to 0–100 | #4861 | Backend returns (sum / 25) × 100 per the WHO-5 Well-being Index; stale integration doc claimed 0–5 which would plot off-chart |
Sources & Recordings
| Source | Notes |
|---|---|
| https://drive.google.com/file/d/1HDF4acVA0QKImQ29Wu0rp_kVIgb-VGFVg_XwcZnUV6E | Description pending SGD audit |
| https://docs.google.com/spreadsheets/d/1nUyRQDrDCttqWgdPHyU1lWC8qB2Bs1WN | Description pending SGD audit |
| https://drive.google.com/file/d/1IOSOdRLqAhBP3aRsAwOoee5bxId5lafv | Description pending SGD audit |