Sleep Planner: local bedtime recommendation and sleep-need plan #758

Context

This is the implementation-plan issue for a WHOOP-like Sleep Planner in NOOP, based on the clean-room feature gap analysis. It should consolidate the user-facing planning behavior without replacing the existing sleep-debt and notification work.

Related / does not replace:

• Sleep planner similar to whoop #625
• Sleep Need bedtime notification parity #750
• Wave 0 scoring: wire computed-but-disconnected methodology into Rest + readiness #456
• Sleep debt: recency-weighted, capped, asymmetric ledger (stacked on #456) #464

Proposed scope

Build a fully local Sleep Planner that turns existing NOOP sleep analytics into an actionable bedtime plan:

• user selects target wake time, desired readiness level, and optional wind-down lead time;
• NOOP computes recommended bedtime from personal sleep need, recent sleep debt, recent sleep consistency, and recovery context already available on-device;
• Today and Sleep surfaces show the plan, not just past sleep metrics;
• optional local notification nudges the user before wind-down / bedtime;
• UI exposes calibration/confidence states when data is insufficient or the night was manually edited;
• calculations are implemented in pure analytics code with Swift/Kotlin parity tests.

Non-goals / safety constraints

• No WHOOP proprietary model, copied decompiled logic, assets, copy, or cloud calls.
• No server/account dependency.
• No medical sleep advice; present as a local planning estimate.
• Do not make sleep staging itself more aggressive just to satisfy the planner.

Acceptance criteria

• A Sleep Planner model exists in pure analytics code on Apple and Android.
• Given the same sleep summaries/settings, Swift and Kotlin return the same recommended bedtime, sleep-need delta, and explanatory drivers.
• The app has a visible planner surface on Today/Sleep or equivalent platform screens.
• Bedtime/wind-down notifications are opt-in, local-only, and degrade gracefully when permissions are denied.
• Empty/calibrating states explain what data is missing.
• Existing sleep-debt tests remain valid or are updated with explicit golden changes.

Verification

• Add package/JVM tests for planner math and edge cases: no data, one night, sleep debt cap, manual sleep edit, timezone/day-boundary behavior.
• App-target Swift changes must be compiled locally with xcodebuild; default CI does not compile app targets.
• Android changes must pass ./gradlew testFullDebugUnitTest and ./gradlew compileFullDebugKotlin.