Personalized health snapshot: replace population ranges with personal baselines

Replace static age/sex population ranges with a three-layer personalized
scoring system for the health snapshot tab:

Layer 1 - Personal Baseline: P10/P50/P90 computed from each user's own
90-day data window (30-day minimum). Population ranges become background
context, not the primary scoring signal.

Layer 2 - Cycle-Aware Baselines: For women who opt in, separate follicular
and luteal baselines prevent false alarms when metrics naturally shift with
the menstrual cycle. In-context Cycle Insight Card (not onboarding) collects
cycle data after 30 days of data, when the user can see why it matters.

Layer 3 - Trend Direction: Cycle-aware trend computation compares like-to-
like phases (luteal vs luteal) to avoid false shifting signals at phase
transitions.

Key components:
- compute-baselines Edge Function with upsert-based persistence
- Direction-aware color logic (outside_good=green, outside_bad=amber, never red)
- Phase-specific personal bests (Luteal Personal Best)
- Population safety net when personal P50 is outside population range
- HeroSummary, WinsSection, ExpertContext, CycleInsightCard, CycleConfirmationPrompt
- Respiratory rate added as 7th metric (WHOOP/Oura)
- Privacy commitment: cycle data used only for range personalization

New files: 19 created, 15 modified
Tests: 2773 mobile (0 fail) + 53 Edge Function (0 fail)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: schwaaamp

docs/README.md

@@ -42,6 +42,7 @@ Active feature planning and architectural strategy documents.
 | [Insight Engine v3](./planning/insight-engine-v3.md) | Dynamic metric discovery, auto-blacklisting, intraday analyzers | 📋 Planning |
 | [Timezone Strategy](./planning/timezone-strategy.md) | Cross-system timezone normalization for all data sources | 📋 Planning (prerequisite for Insight v3) |
 | [Unified Experiment Analysis](./planning/unified-experiment-analysis.md) | Single analysis engine, diagnostics, admin dashboard | ✅ Complete |
+| [Personalized Health Snapshot](./planning/personalized-health-snapshot.md) | Replace population ranges with personal baselines, cycle-aware scoring, trend direction | 📋 Planning |
 
 ---
 

docs/planning/personalized-health-snapshot.md

@@ -0,0 +1,105 @@
+/**
+ * TDD tests for ExpertContext component.
+ *
+ * Validates the collapsible expert quote section that provides context
+ * on why personal ranges are used instead of population averages.
+ */
+
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react-native';
+
+// ---------- Mocks ----------
+
+jest.mock('@/components/useColors', () => ({
+  useColors: () => ({
+    background: '#FFFFFF',
+    cardBackground: '#FFFFFF',
+    text: '#000000',
+    textSecondary: '#757575',
+    primary: '#6B4EE6',
+    primaryUltraLight: '#F0ECFD',
+    outline: '#E0E0E0',
+  }),
+}));
+
+// Mock AsyncStorage — the global mock from jest.setup.js handles this,
+// but we need to control the return value for "seen" state.
+const mockAsyncStorage = require('@react-native-async-storage/async-storage');
+
+// Import after mocks
+const ExpertContext = require('@/components/Experiments/ExpertContext').default;
+
+// ---------- Tests ----------
+
+describe('ExpertContext', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Default: user has seen the section before (collapsed by default)
+    mockAsyncStorage.getItem.mockResolvedValue('true');
+  });
+
+  it('renders "Why personal ranges?" title after loading', async () => {
+    render(<ExpertContext />);
+    await waitFor(() => {
+      expect(screen.getByText('Why personal ranges?')).toBeTruthy();
+    });
+  });
+
+  it('contains Huberman quote text when expanded', async () => {
+    render(<ExpertContext />);
+    await waitFor(() => {
+      expect(screen.getByText('Why personal ranges?')).toBeTruthy();
+    });
+    // Expand the section
+    fireEvent.press(screen.getByText('Why personal ranges?'));
+    expect(
+      screen.getByText(/Individual trends matter more than absolute numbers/),
+    ).toBeTruthy();
+  });
+
+  it('contains Patrick quote text when expanded', async () => {
+    render(<ExpertContext />);
+    await waitFor(() => {
+      expect(screen.getByText('Why personal ranges?')).toBeTruthy();
+    });
+    fireEvent.press(screen.getByText('Why personal ranges?'));
+    expect(
+      screen.getByText(/relative changes over time with respect to your normal range/),
+    ).toBeTruthy();
+  });
+
+  it('contains Sims quote text when expanded', async () => {
+    render(<ExpertContext />);
+    await waitFor(() => {
+      expect(screen.getByText('Why personal ranges?')).toBeTruthy();
+    });
+    fireEvent.press(screen.getByText('Why personal ranges?'));
+    expect(
+      screen.getByText(/recovery metrics in the late luteal phase/),
+    ).toBeTruthy();
+  });
+
+  it('toggles expanded/collapsed on press', async () => {
+    render(<ExpertContext />);
+    await waitFor(() => {
+      expect(screen.getByText('Why personal ranges?')).toBeTruthy();
+    });
+    // Initially collapsed (user has seen before)
+    expect(screen.queryByText(/Individual trends matter/)).toBeNull();
+
+    // Expand
+    fireEvent.press(screen.getByText('Why personal ranges?'));
+    expect(screen.getByText(/Individual trends matter/)).toBeTruthy();
+
+    // Collapse
+    fireEvent.press(screen.getByText('Why personal ranges?'));
+    expect(screen.queryByText(/Individual trends matter/)).toBeNull();
+  });
+
+  it('renders nothing before AsyncStorage resolves', () => {
+    // Make AsyncStorage never resolve
+    mockAsyncStorage.getItem.mockReturnValue(new Promise(() => {}));
+    const { toJSON } = render(<ExpertContext />);
+    expect(toJSON()).toBeNull();
+  });
+});

mobile/__tests__/components/ExpertContext.test.tsx

@@ -0,0 +1,161 @@
+/**
+ * TDD tests for HeroSummary component.
+ *
+ * Validates the dynamic hero sentence that summarizes the user's current
+ * health snapshot status using positive, personal language.
+ */
+
+import React from 'react';
+import { render, screen } from '@testing-library/react-native';
+import { MetricScore } from '@/utils/experiments/types';
+
+// ---------- Mocks ----------
+
+jest.mock('@/components/useColors', () => ({
+  useColors: () => ({
+    background: '#FFFFFF',
+    cardBackground: '#FFFFFF',
+    text: '#000000',
+    textSecondary: '#757575',
+    primary: '#6B4EE6',
+    primaryUltraLight: '#F0ECFD',
+    outline: '#E0E0E0',
+  }),
+}));
+
+// Import after mocks
+const HeroSummary = require('@/components/Experiments/HeroSummary').default;
+
+// ---------- Test data ----------
+
+const makeScore = (overrides: Partial<MetricScore> = {}): MetricScore => ({
+  metric_key: 'resting_hr',
+  metric_label: 'Resting Heart Rate',
+  current_value: 58,
+  optimal_min: 52,
+  optimal_max: 72,
+  gap_status: 'within_optimal',
+  improvement_potential: 0,
+  unit: 'bpm',
+  description: 'Reflects cardiovascular fitness.',
+  insight: 'Your resting heart rate of 58 bpm is within the optimal range.',
+  citation: 'Ostchega et al. 2011 (NHANES)',
+  is_personalized: true,
+  direction: 'lower_is_better',
+  personal_p10: 55,
+  personal_p50: 60,
+  personal_p90: 66,
+  personal_status: 'within',
+  cycle_phase: null,
+  phase_label: null,
+  trend_direction: 'stable',
+  trend_pct_change: null,
+  is_personal_best: false,
+  personal_best_label: null,
+  population_safety_flag: false,
+  ...overrides,
+});
+
+// ---------- Tests ----------
+
+describe('HeroSummary', () => {
+  it('renders count of metrics in personal range', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'within' }),
+      makeScore({ metric_key: 'hrv', metric_label: 'HRV', personal_status: 'within' }),
+      makeScore({ metric_key: 'sleep_duration', metric_label: 'Sleep Duration', personal_status: 'outside_good' }),
+      makeScore({ metric_key: 'steps', metric_label: 'Steps', personal_status: 'outside_bad' }),
+      makeScore({ metric_key: 'deep_sleep', metric_label: 'Deep Sleep', personal_status: 'within' }),
+      makeScore({ metric_key: 'rem_sleep', metric_label: 'REM Sleep', personal_status: 'within' }),
+      makeScore({ metric_key: 'resp_rate', metric_label: 'Respiratory Rate', personal_status: 'within' }),
+    ];
+    render(<HeroSummary scorecard={scorecard} />);
+    // 5 within + 1 outside_good = 6 in personal range, out of 7 total
+    expect(screen.getByText(/6 of 7 metrics are in your personal range/)).toBeTruthy();
+  });
+
+  it('uses dynamic metric count (not hardcoded)', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'within' }),
+      makeScore({ metric_key: 'hrv', metric_label: 'HRV', personal_status: 'within' }),
+      makeScore({ metric_key: 'steps', metric_label: 'Steps', personal_status: 'outside_bad' }),
+    ];
+    render(<HeroSummary scorecard={scorecard} />);
+    expect(screen.getByText(/2 of 3 metrics are in your personal range/)).toBeTruthy();
+  });
+
+  it('highlights improving metric in sentence', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'within' }),
+      makeScore({
+        metric_key: 'deep_sleep',
+        metric_label: 'Deep Sleep',
+        personal_status: 'within',
+        trend_direction: 'improving',
+      }),
+    ];
+    render(<HeroSummary scorecard={scorecard} />);
+    expect(screen.getByText(/Deep Sleep has been improving/)).toBeTruthy();
+  });
+
+  it('includes follicular phase context', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'within' }),
+    ];
+    render(
+      <HeroSummary
+        scorecard={scorecard}
+        cyclePhase={{ phase: 'follicular', dayOfCycle: 8 }}
+      />,
+    );
+    expect(
+      screen.getByText(/Follicular phase, Day 8/),
+    ).toBeTruthy();
+    expect(
+      screen.getByText(/your metrics are in their strongest window/),
+    ).toBeTruthy();
+  });
+
+  it('includes luteal phase context with positive framing', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'within' }),
+    ];
+    render(
+      <HeroSummary
+        scorecard={scorecard}
+        cyclePhase={{ phase: 'luteal', dayOfCycle: 21 }}
+      />,
+    );
+    expect(
+      screen.getByText(/Luteal phase, Day 21/),
+    ).toBeTruthy();
+    expect(
+      screen.getByText(/your body is doing exactly what it should right now/),
+    ).toBeTruthy();
+  });
+
+  it('handles zero metrics in range without deficit language', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: 'outside_bad' }),
+      makeScore({ metric_key: 'hrv', metric_label: 'HRV', personal_status: 'outside_bad' }),
+      makeScore({ metric_key: 'steps', metric_label: 'Steps', personal_status: 'outside_bad' }),
+    ];
+    render(<HeroSummary scorecard={scorecard} />);
+    // Should say "0 of 3" but never use words like "below", "declining", "suboptimal"
+    expect(screen.getByText(/0 of 3 metrics are in your personal range/)).toBeTruthy();
+    // Ensure no deficit language
+    const allText = screen.getByText(/0 of 3/).props.children;
+    const textStr = Array.isArray(allText) ? allText.join('') : String(allText);
+    expect(textStr).not.toMatch(/below|declining|suboptimal|bad|poor|worse/i);
+  });
+
+  it('renders legacy header when no personal baselines exist (all personal_status null)', () => {
+    const scorecard = [
+      makeScore({ metric_key: 'resting_hr', personal_status: null }),
+      makeScore({ metric_key: 'hrv', metric_label: 'HRV', personal_status: null }),
+      makeScore({ metric_key: 'steps', metric_label: 'Steps', personal_status: null }),
+    ];
+    render(<HeroSummary scorecard={scorecard} />);
+    expect(screen.getByText('Your Health Snapshot')).toBeTruthy();
+  });
+});