Skip to content

feat: Watch app UI upgrade, engine fixes, and production readiness #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cortexark merged 4 commits into from
Mar 15, 2026
Merged

feat: Watch app UI upgrade, engine fixes, and production readiness #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
077d584
feat: premium Baymax character with 8 mood-specific animations
cortexark Mar 14, 2026
e772cc1
feat: watch complications, Siri shortcuts, buddy interactions, and UI…
cortexark Mar 14, 2026
b0697b3
fix: conflict guard between nudge systems + engine bug fixes
cortexark Mar 14, 2026
f3e2bd6
feat: watch UX redesign, engine bug fixes, production readiness tests
cortexark Mar 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
366 changes: 164 additions & 202 deletions PROJECT_CODE_REVIEW_2026-03-13.md
View file
Open in desktop

Large diffs are not rendered by default.

130 changes: 91 additions & 39 deletions apps/HeartCoach/BUGS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Thump Bug Tracker

> Auto-maintained during development sessions.
> Auto-maintained by Claude during development sessions.
> Status: `OPEN` | `FIXED` | `WONTFIX`
> Severity: `P0-CRASH` | `P1-BLOCKER` | `P2-MAJOR` | `P3-MINOR` | `P4-COSMETIC`

Expand Down Expand Up @@ -385,52 +385,104 @@
- **Description:** "patterns detected" sounds like a medical diagnosis.
- **Fix Applied:** Changed to "numbers look different from usual range".

### BUG-056: LocalStore assertionFailure crash in simulator/test environment
- **Status:** OPEN
- **File:** `Shared/Services/LocalStore.swift` line 304
- **Description:** `assertionFailure("CryptoService.encrypt() returned nil")` fires in DEBUG mode when CryptoService cannot access Keychain (simulator, unit test target). Crashes CustomerJourneyTests and any test that triggers encrypted save.
- **Root Cause:** CryptoService depends on Keychain, which is unavailable in some test contexts. No mock/stub injection point.
- **Fix Plan:** Create `CryptoServiceProtocol` and inject a mock for test targets. Or gate assertionFailure behind a `#if !targetEnvironment(simulator)` check.

### BUG-057: Swift compiler Signal 11 with nested structs in XCTestCase
- **Status:** WORKAROUND
- **File:** `Tests/ZoneEngineImprovementTests.swift`
- **Description:** Swift compiler crashes (Signal 11) when XCTestCase methods define local struct arrays containing `BiologicalSex` enum members. Reproducible in Xcode 16.
- **Workaround:** Use parallel arrays (`let ages = [...]`, `let sexes: [BiologicalSex] = [...]`) instead of struct arrays.
- **Root Cause:** Suspected Swift compiler type inference bug with nested generics + enums in test methods.

### BUG-058: Synthetic persona scores outside expected ranges
- **Status:** KNOWN
- **File:** `Tests/SyntheticPersonaProfiles.swift`
- **Description:** "Recovering from Illness" persona stress score sometimes outside [45-75] expected range. "Overtraining Syndrome" persona `consecutiveAlert` is nil. Both caused by synthetic data noise characteristics, not engine regressions.
- **Fix Plan:** Tune synthetic data generation seeds or widen expected ranges.
---

## P2 — Major Bugs (2026-03-14 Session)

### BUG-056: ReadinessEngine activity balance nil cascade for irregular wearers
- **Status:** FIXED (2026-03-14)
- **File:** `Shared/Engine/ReadinessEngine.swift`
- **Description:** `scoreActivityBalance` returned nil when yesterday's data was missing. Combined with the 2-pillar minimum gate, irregular watch wearers (no yesterday data + no HRV today) got no readiness score. This silently breaks the NudgeGenerator readiness gate.
- **Fix Applied:** Added today-only fallback scoring (35 for no activity, 55 for some, 75 for ideal). Conservative scores that don't over-promise.
- **Trade-off:** Activity pillar is less accurate without yesterday comparison, but "approximate readiness" beats "no readiness" for user engagement and safety (nudge gating still works).

### BUG-057: CoachingEngine zone analysis window off by 1 day
- **Status:** FIXED (2026-03-14)
- **File:** `Shared/Engine/CoachingEngine.swift`
- **Description:** `weeklyZoneSummary(history:)` called without `referenceDate`. Defaults to `history.last?.date`, which is 1 day behind `current.date`. Zone analysis evaluates the wrong 7-day window.
- **Fix Applied:** Pass `referenceDate: current.date` explicitly. Same class of bug as ENG-1 (HeartTrendEngine) and ZE-001 (HeartRateZoneEngine).

### BUG-058: NudgeGenerator regression path returns moderate intensity
- **Status:** FIXED (2026-03-14)
- **File:** `Shared/Engine/NudgeGenerator.swift`
- **Description:** `regressionNudgeLibrary()` contained a `.moderate` category nudge. Regression = multi-day worsening trend → moderate intensity is clinically inappropriate. The readiness gate only caught cases where readiness was ALSO low, but regression can co-exist with "good" readiness.
- **Fix Applied:** (a) Replaced `.moderate` with `.walk` in regression library. (b) Added readiness gate to `selectRegressionNudge` for consistency with positive/default paths.

### BUG-059: NudgeGenerator low-data nudge uses wall-clock time
- **Status:** FIXED (2026-03-14, by linter)
- **File:** `Shared/Engine/NudgeGenerator.swift`
- **Description:** `selectLowDataNudge` used `Calendar.current.component(.hour, from: Date())` for rotation instead of `current.date`. Non-deterministic in tests. Same class as ENG-1 and ZE-001.
- **Fix Applied:** Now uses `current.date` via `ordinality(of:in:for:)`.

---

## P3 — Minor Bugs (2026-03-14 Session)

### BUG-060: LegalGateTests fail due to simulator state pollution
- **Status:** FIXED (2026-03-14)
- **File:** `Tests/LegalGateTests.swift`
- **Description:** `setUp()` used `removeObject(forKey:)` which doesn't reliably clear UserDefaults when the test host app has previously accepted legal terms on the simulator. 7 tests failed intermittently.
- **Fix Applied:** Use `set(false, forKey:)` + `synchronize()` instead of `removeObject`. Also fixed `testLegalAccepted_canBeReset` which used `removeObject` in the test body.

---

## Open — Not Fixed (2026-03-14 Session)

### BUG-061: HeartTrendEngine stress proxy diverges from real StressEngine
- **Status:** FIXED (2026-03-14)
- **Severity:** P2-MAJOR
- **File:** `Shared/Engine/HeartTrendEngine.swift`
- **Description:** ReadinessEngine was called with a heuristic stress score (70/50/25) derived from trend flags, not the real StressEngine output. This proxy diverged from the actual stress score, causing nudge intensity misalignment.
- **Fix Applied:** Added `stressScore: Double?` parameter to `assess()` with backward-compatible default of `nil`. When provided, real score is used directly. Falls back to heuristic proxy only when caller doesn't have a stress score.

### BUG-062: BioAgeEngine uses estimated height for BMI calculation
- **Status:** FIXED (2026-03-14)
- **Severity:** P3-MINOR
- **File:** `Shared/Engine/BioAgeEngine.swift`, `Shared/Models/HeartModels.swift`
- **Description:** Used sex-stratified average heights when actual height unavailable. A 188cm man got BMI inflated by ~15%.
- **Fix Applied:** Added `heightM: Double?` field to `HeartSnapshot` (clamped 0.5-2.5m). BioAgeEngine now uses actual height when available, falls back to estimated only when nil. HealthKit query for `HKQuantityType(.height)` still needed in HealthKitService.

### BUG-063: SmartNudgeScheduler assumes midnight-to-morning sleep
- **Status:** FIXED (2026-03-14)
- **Severity:** P2-MAJOR
- **File:** `Shared/Engine/SmartNudgeScheduler.swift`
- **Description:** Sleep pattern estimation clamped wake time to 5-12 range. Shift workers sleeping 2AM-10AM got wrong bedtime/wake estimates.
- **Fix Applied:** Widened wake range to 3-14 (was 5-12), bedtime floor to 18 (was 20). Long sleep (>9h) now shifts wake estimate later for shift workers. Full fix with actual HealthKit sleep timestamps still recommended for v2.

---

## Tracking Summary

| Severity | Total | Open | Fixed | Workaround |
|----------|-------|------|-------|------------|
| P0-CRASH | 1 | 0 | 1 | 0 |
| P1-BLOCKER | 8 | 0 | 8 | 0 |
| P2-MAJOR | 29 | 2 | 27 | 0 |
| P3-MINOR | 7 | 1 | 5 | 1 |
| P4-COSMETIC | 13 | 0 | 13 | 0 |
| **Total** | **58** | **3** | **54** | **1** |
| Severity | Total | Open | Fixed |
|----------|-------|------|-------|
| P0-CRASH | 1 | 0 | 1 |
| P1-BLOCKER | 8 | 0 | 8 |
| P2-MAJOR | 32 | 1 | 31 |
| P3-MINOR | 7 | 0 | 7 |
| P4-COSMETIC | 13 | 0 | 13 |
| **Total** | **63** | **1** | **62** |

### Remaining Open (1)
- BUG-013: Accessibility labels missing across views (P2) — large effort, plan for next sprint

| Severity | Total | Open | Fixed |
|----------|-------|------|-------|
| P0-CRASH | 1 | 0 | 1 |
| P1-BLOCKER | 8 | 0 | 8 |
| P2-MAJOR | 28 | 1 | 27 |
| P3-MINOR | 5 | 0 | 5 |
| P4-COSMETIC | 13 | 0 | 13 |
| **Total** | **55** | **1** | **54** |

### Remaining Open (4)
### Remaining Open (1)
- BUG-013: Accessibility labels missing across views (P2) — large effort, plan for next sprint
- BUG-056: LocalStore assertionFailure crash in simulator/test env (P2) — needs CryptoService mock
- BUG-057: Swift compiler Signal 11 with nested structs (P3) — workaround in place
- BUG-058: Synthetic persona scores outside expected ranges (P3) — known, non-regression

### Test Results
- SPM build: Zero compilation errors
- XCTest: StressEngine 58/58, ZoneEngine 20/20, CorrelationEngine 10/10, StressModeConfidence 13/13
- Dataset validation: SWELL, PhysioNet, WESAD — all passing
- Time-series regression: 500+ fixture comparisons across 20 personas
- Signal 11 in SPM runner is a known toolchain issue, not a code bug
### Test Results (2026-03-14)
- Xcode build: ✅ iOS + Watch targets
- XCTest: **752 tests, 0 failures**
- Production readiness suite: 31 tests across 10 clinical personas × 8 engines
- Watch build: ✅ ThumpWatch scheme passes

---

*Last updated: 2026-03-13 — 54/58 bugs fixed, 3 open + 1 workaround. All P0 + P1 resolved. New bugs BUG-056/057/058 added from sprint. Stress engine, zone engine, and correlation engine improvements shipped with 88+ new tests.*
*Last updated: 2026-03-12 — 54/55 bugs fixed, 1 remaining (accessibility). All P0 + P1 resolved. Mock data replaced with real HealthKit queries. Medical language scrubbed. AI slop removed. Raw jargon humanized. Context-aware trend colors added. Watch shaming language softened. Plaintext PHI fallback removed. Force unwraps eliminated. E2E behavioral + UI coherence tests built.*
174 changes: 174 additions & 0 deletions apps/HeartCoach/ENGINE_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
# Thump Engine Reference

## All 10 Engines

| # | Engine | What It Does | Input | Output | Feeds Into |
|---|--------|-------------|-------|--------|------------|
| 1 | **HeartTrendEngine** | Master daily assessment — anomaly score, regression detection, stress pattern, week-over-week trend, coaching scenario | `[HeartSnapshot]` history + today's snapshot | `HeartAssessment` (status, confidence, anomaly, stressFlag, regressionFlag, cardioScore, nudges, WoW trend, scenario) | Dashboard, Watch, Notifications, all other engines |
| 2 | **StressEngine** | HRV-based stress score 0-100 — RHR deviation (50%), HRV Z-score (30%), CV (20%), sigmoid-calibrated | Today snapshot + 14-day history | `StressResult` (score, level: relaxed/balanced/elevated), hourly estimates, trend direction | Stress screen heatmap, ReadinessEngine, BuddyRecommendationEngine, SmartNudgeScheduler |
| 3 | **ReadinessEngine** | 5-pillar readiness score 0-100 — Sleep (25%), Recovery (25%), Stress (20%), Activity (15%), HRV trend (15%) | Today snapshot + stress score + history | `ReadinessResult` (score, level: primed/ready/moderate/recovering, pillar breakdown) | NudgeGenerator gate, Dashboard readiness card, conflict guard, Watch complication |
| 4 | **NudgeGenerator** | Picks daily coaching nudge from 6-priority waterfall — stress > regression > low data > negative feedback > improving > default | Confidence, anomaly, regression, stress, feedback, readiness, snapshot | `DailyNudge` (category, title, description, duration, icon) x 1-3 | Dashboard nudge card, Watch hero/walk screen, NotificationService, complications |
| 5 | **SmartNudgeScheduler** | Time-aware real-time actions — learns sleep patterns, detects late wake, suggests journal/breathe/bedtime/activity | Stress points, trend direction, sleep patterns, current hour, readiness gate | `SmartNudgeAction` (journal, breathe, checkin, bedtime, activity, rest, standard) | Stress screen action buttons, Watch breathe prompt, notification timing |
| 6 | **BioAgeEngine** | Fitness age estimate — compares RHR/HRV/VO2/sleep/activity/BMI against age-stratified population norms | Today snapshot + chronological age + sex | `BioAgeResult` (bioAge, offset years, category: excellent-needsWork, per-metric breakdown) | Dashboard bio age card |
| 7 | **CoachingEngine** | Weekly coaching report — per-metric narrative insights, 4-week projections, weekly progress score | Today snapshot + history + streak days | `CoachingReport` (hero message, metric insights, RHR/HRV projections, progress score 0-100) | Dashboard coaching section |
| 8 | **HeartRateZoneEngine** | Karvonen HR zones + zone analysis — computes 5 zones, daily targets by fitness level, AHA completion, 80/20 rule | Age, resting HR, sex, zone minutes | `[HeartRateZone]`, `ZoneAnalysis` (per-zone completion, recommendation), `WeeklyZoneSummary` (AHA%) | Dashboard zone chart, NudgeGenerator secondary nudges, CoachingEngine |
| 9 | **CorrelationEngine** | Pearson correlations — steps-RHR, walking-HRV, activity-recovery, sleep-RHR, sleep-HRV | 7+ day history | `[CorrelationResult]` (r value, confidence, plain-language interpretation) | Dashboard insight cards (gated behind subscription) |
| 10 | **BuddyRecommendationEngine** | Synthesis layer — aggregates all engine outputs into 1-4 prioritized, deduplicated action cards | Assessment + stress + readiness + snapshot + history | `[BuddyRecommendation]` (priority: critical-low, category, title, message, source) | Dashboard buddy recommendations section |

## Data Flow: HealthKit to Screens

```
HealthKit (RHR, HRV, Recovery, VO2, Steps, Walk, Sleep, Zones)
|
v
DashboardViewModel.refresh()
|
+-- HeartTrendEngine.assess()
| +-- ReadinessEngine (internal)
| +-- NudgeGenerator (internal)
| +-- HeartRateZoneEngine (secondary nudges)
|
+-- StressEngine.computeStress()
+-- ReadinessEngine.compute()
+-- BioAgeEngine.estimate()
+-- CoachingEngine.generateReport()
| +-- HeartRateZoneEngine.weeklyZoneSummary()
+-- HeartRateZoneEngine.analyzeZoneDistribution()
+-- CorrelationEngine.analyze()
+-- BuddyRecommendationEngine.recommend()
|
v
@Published properties on DashboardViewModel
|
+-- iOS Views (Dashboard, Readiness, Coaching, Zones, Insights)
+-- LocalStore.appendSnapshot() (persistence)
+-- NotificationService (alerts + nudge reminders)
+-- ConnectivityService.sendAssessment() --> Watch
|
v
WatchViewModel --> ThumpComplicationData --> Watch face widgets

StressViewModel (separate HealthKit fetch):
+-- StressEngine --> Stress screen heatmap + trend
+-- SmartNudgeScheduler --> Action buttons
+-- breathe prompt --> Watch
```

## Notification Pipeline

| Engine Output | Notification Type | Trigger | Delivery Time |
|---|---|---|---|
| HeartAssessment.status == .needsAttention | Anomaly Alert (immediate) | Status check after assess() | 1 second |
| NudgeGenerator -> .walk/.moderate | Walk notification | Daily after refresh | Morning (wake+2h, max noon) |
| NudgeGenerator -> .rest | Rest notification | Daily after refresh | Bedtime (learned pattern) |
| NudgeGenerator -> .breathe | Breathe notification | Daily after refresh | 3 PM |
| NudgeGenerator -> .hydrate | Hydrate notification | Daily after refresh | 11 AM |
| NudgeGenerator -> .celebrate/.seekGuidance | General notification | Daily after refresh | 6 PM |
| SmartNudgeScheduler -> .breatheOnWatch | Watch breathe prompt (WCSession) | Stress rising | Real-time |
| SmartNudgeScheduler -> .morningCheckIn | Watch check-in (WCSession) | Late wake detected | Before noon |

## Key Thresholds

### HeartTrendEngine
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Anomaly weights | RHR 25%, HRV 25%, Recovery1m 20%, Recovery2m 10%, VO2 20% | Composite score |
| needsAttention | anomaly >= 2.0 | Status escalation |
| Regression slope | -0.3 bpm/day over 7 days | Multi-day decline detection |
| Stress pattern | RHR Z>1.5 AND HRV Z<-1.5 AND Recovery Z<-1.5 | Simultaneous elevation |
| Confidence: high | 4+ metrics, 14+ history days | |
| Confidence: medium | 2+ metrics, 7+ history days | |

### StressEngine
| Threshold | Value | Purpose |
|-----------|-------|---------|
| RHR weight | 50% | Primary signal |
| HRV weight | 30% | Secondary signal |
| CV weight | 20% | Tertiary signal |
| Sigmoid | k=0.08, mid=50 | Score normalization |
| relaxed | score < 40 | |
| balanced | score 40-65 | |
| elevated | score > 65 | |
| Trend rising | slope > 0.5/day | |

### ReadinessEngine
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Sleep pillar | Gaussian optimal at 8h, sigma=1.5 | 25% weight |
| Recovery pillar | Linear 10-40 bpm drop | 25% weight |
| Stress pillar | 100 - stressScore | 20% weight |
| Activity pillar | Sweet spot 20-45 min/day | 15% weight |
| HRV trend pillar | Each 10% below avg = -20 | 15% weight |
| Primed | score 80-100 | |
| Ready | score 60-79 | |
| Moderate | score 40-59 | |
| Recovering | score 0-39 | |
| Consecutive alert | caps score at 50 | |

### NudgeGenerator
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Priority 1 | stress == true | Stress nudge |
| Priority 2 | regression == true | Regression nudge (readiness gated) |
| Priority 3 | confidence == .low | Low data nudge |
| Priority 4 | feedback == .negative | Adjusted nudge |
| Priority 5 | anomaly < 0.5 | Positive nudge (readiness gated) |
| Priority 6 | default | General nudge (readiness gated) |
| Sleep too short | < 6.5h | Secondary rest nudge |
| Sleep too long | > 9.5h | Secondary walk nudge |
| Low activity | < 10 min | Secondary walk nudge |

### SmartNudgeScheduler
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Journal stress | >= 65 | Trigger journal prompt |
| Late wake | > 1.5h past typical | Morning check-in |
| Bedtime window | hour-1 to hour | Wind-down nudge |
| Low activity | walk+workout < 10 min | Activity suggestion |
| Poor sleep | < 6.5h | Rest suggestion |
| Readiness gate | .recovering | Suppress activity |

### BioAgeEngine
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Max offset per metric | +/- 8 years | Clamp |
| Minimum total weight | 0.3 (2+ metrics) | Required data |
| Excellent | diff <= -5 years | Category |
| Good | diff -5 to -2 | Category |
| On Track | diff -2 to +2 | Category |
| Watchful | diff +2 to +5 | Category |
| Needs Work | diff > +5 | Category |

### HeartRateZoneEngine
| Threshold | Value | Purpose |
|-----------|-------|---------|
| Zone 1 (Recovery) | 50-60% HRR | Karvonen |
| Zone 2 (Fat Burn) | 60-70% HRR | Karvonen |
| Zone 3 (Aerobic) | 70-80% HRR | Karvonen |
| Zone 4 (Threshold) | 80-90% HRR | Karvonen |
| Zone 5 (Peak) | 90-100% HRR | Karvonen |
| Max HR floor | 150 bpm | Safety |
| AHA target | 150 min/week | Moderate + 2x vigorous |
| 80/20 sweet spot | hard ratio 0.15-0.25 | Optimal balance |

## File Paths

| File | Role |
|------|------|
| Shared/Engine/HeartTrendEngine.swift | Master assessment |
| Shared/Engine/StressEngine.swift | Stress scoring |
| Shared/Engine/ReadinessEngine.swift | 5-pillar readiness |
| Shared/Engine/NudgeGenerator.swift | Nudge content selection |
| Shared/Engine/SmartNudgeScheduler.swift | Time-aware nudge timing |
| Shared/Engine/BioAgeEngine.swift | Fitness age estimate |
| Shared/Engine/CoachingEngine.swift | Weekly coaching report |
| Shared/Engine/HeartRateZoneEngine.swift | HR zone computation |
| Shared/Engine/CorrelationEngine.swift | Pearson insight cards |
| Shared/Engine/BuddyRecommendationEngine.swift | Synthesis/priority layer |
| Shared/Models/HeartModels.swift | All shared data models |
| Shared/Services/ConfigService.swift | Global thresholds |
| iOS/ViewModels/DashboardViewModel.swift | Primary iOS orchestrator |
| iOS/ViewModels/StressViewModel.swift | Stress screen orchestrator |
| iOS/Services/NotificationService.swift | Push notification scheduling |
| iOS/Services/ConnectivityService.swift | Phone-Watch sync |
| Watch/ViewModels/WatchViewModel.swift | Watch state + complications |
Loading
Loading