---
phase: 04-gps-power-optimization
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - lib/models/processed_gps_data.dart
  - lib/config/gps_constants.dart
  - lib/config/timing_constants.dart
  - lib/services/gps_data_manager.dart
  - lib/gps_service.dart
autonomous: true

must_haves:
  truths:
    - "GPS precision switches to HIGH when speed exceeds 12 km/h (3.33 m/s)"
    - "GPS precision switches to BALANCED when speed drops below 8 km/h (2.22 m/s)"
    - "Precision does NOT switch until first GPS fix is received"
    - "GPS stops after 7s grace period when app backgrounded without overlay"
    - "GPS continues running when app backgrounded with overlay visible"
    - "GPS restarts when app returns to foreground after being stopped"
    - "Wake lock enabled when GPS active AND (overlay visible OR app in foreground)"
    - "Wake lock disabled when GPS stops or app backgrounds without overlay"
    - "ProcessedGpsData carries timestamp for staleness detection"
  artifacts:
    - path: "lib/models/processed_gps_data.dart"
      provides: "ProcessedGpsData with timestamp field and copyWith support"
      contains: "DateTime timestamp"
    - path: "lib/config/gps_constants.dart"
      provides: "Precision switching threshold constants in m/s"
      contains: "PRECISION_UP_THRESHOLD_MPS"
    - path: "lib/config/timing_constants.dart"
      provides: "Background grace period duration constant"
      contains: "BACKGROUND_GRACE_PERIOD"
    - path: "lib/services/gps_data_manager.dart"
      provides: "Lifecycle-aware GPS engine with precision switching and wake lock"
      contains: "WidgetsBindingObserver"
    - path: "lib/gps_service.dart"
      provides: "Dynamic position stream accepting LocationAccuracy parameter"
      contains: "LocationAccuracy accuracy"
  key_links:
    - from: "lib/services/gps_data_manager.dart"
      to: "lib/gps_service.dart"
      via: "createPositionStream with dynamic accuracy"
      pattern: "GpsService\\.createPositionStream"
    - from: "lib/services/gps_data_manager.dart"
      to: "lib/providers/overlay_provider.dart"
      via: "overlay state check for background decisions"
      pattern: "_overlayProvider.*isOverlayActive"
    - from: "lib/services/gps_data_manager.dart"
      to: "wakelock_plus"
      via: "conditional wake lock based on tracking + visibility state"
      pattern: "WakelockPlus\\.(enable|disable)"
---

<objective>
Build the core GPS engine with speed-adaptive precision switching, lifecycle-aware background management, and conditional wake lock control.

Purpose: This is the engine layer -- all GPS intelligence lives in GpsDataManager. It reacts to speed changes (hysteresis switching), app lifecycle events (background/foreground), and overlay state to make autonomous decisions about GPS precision, tracking, and power usage. The UI layer (Plan 02) will consume this engine's outputs.

Output: A GpsDataManager that is lifecycle-aware, precision-adaptive, and power-conscious. ProcessedGpsData with timestamp for staleness. Dynamic GPS stream via GpsService.
</objective>

<execution_context>
@C:/Users/SKSup/.claude/get-shit-done/workflows/execute-plan.md
@C:/Users/SKSup/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-gps-power-optimization/04-CONTEXT.md
@.planning/phases/04-gps-power-optimization/04-RESEARCH.md

Source files to modify:
@lib/models/processed_gps_data.dart
@lib/config/gps_constants.dart
@lib/config/timing_constants.dart
@lib/services/gps_data_manager.dart
@lib/gps_service.dart

Reference files (read-only context):
@lib/providers/overlay_provider.dart
@lib/config/overlay_constants.dart
@lib/main.dart
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add timestamp to ProcessedGpsData and precision/lifecycle constants</name>
  <files>lib/models/processed_gps_data.dart, lib/config/gps_constants.dart, lib/config/timing_constants.dart, lib/gps_service.dart</files>
  <action>
**ProcessedGpsData** (`lib/models/processed_gps_data.dart`):
- Add `final DateTime timestamp` field
- Add to constructor as required parameter
- Add to `copyWith()` method
- Update the `const` default in GpsDataManager to use a factory or remove const (DateTime.now() is not const-compatible). The default initialization in GpsDataManager will need to change from `const ProcessedGpsData(...)` to `ProcessedGpsData(... timestamp: DateTime.now())`.

**GpsConfig** (`lib/config/gps_constants.dart`):
- Add precision switching threshold constants (SCREAMING_SNAKE per project convention):
  - `PRECISION_UP_THRESHOLD_MPS = 3.33` (12 km/h, switch to high)
  - `PRECISION_DOWN_THRESHOLD_MPS = 2.22` (8 km/h, switch to balanced/medium)
  - `PRECISION_SWITCH_FIRST_FIX_DELAY = Duration(seconds: 5)` (minimum time before first precision switch)
- Keep existing constants unchanged

**TimingConfig** (`lib/config/timing_constants.dart`):
- Add `BACKGROUND_GRACE_PERIOD = Duration(seconds: 7)` for background GPS stop delay
- Update comment on existing `GPS_GRACE_PERIOD` (30s) to mark it as deprecated/unused (Phase 3 placeholder, replaced by BACKGROUND_GRACE_PERIOD). OR remove it if nothing references it besides OverlayProvider (which will be cleaned up in Plan 02).
- Check if `GPS_GRACE_PERIOD` is referenced anywhere. If only in OverlayProvider, leave it for now (Plan 02 will clean it up). If referenced elsewhere, leave both.

**GpsService** (`lib/gps_service.dart`):
- Change `positionStream` from a static getter with hardcoded `bestForNavigation` accuracy to a static method that accepts a `LocationAccuracy` parameter:
  ```dart
  static Stream<Position> createPositionStream({
    LocationAccuracy accuracy = LocationAccuracy.high,
  }) {
    return Geolocator.getPositionStream(
      locationSettings: LocationSettings(
        accuracy: accuracy,
        distanceFilter: 0,
      ),
    );
  }
  ```
- Keep the old `positionStream` getter as a deprecated wrapper calling `createPositionStream(accuracy: LocationAccuracy.bestForNavigation)` for backward compatibility during transition, OR remove it if GpsDataManager is the only consumer (check imports first).

Do NOT modify GpsDataManager in this task -- that is Task 2.
  </action>
  <verify>
Run `cd J:/dev/gps_speedo && flutter analyze` -- should pass with no new errors (existing SCREAMING_SNAKE info warnings are acceptable). Check that ProcessedGpsData, GpsConfig, TimingConfig, and GpsService all compile cleanly. The GpsDataManager will have a compile error on the `const ProcessedGpsData(...)` line due to the new required `timestamp` field -- that is expected and will be fixed in Task 2.
  </verify>
  <done>
ProcessedGpsData has timestamp field with copyWith support. GpsConfig has precision threshold constants in m/s. TimingConfig has BACKGROUND_GRACE_PERIOD (7s). GpsService has createPositionStream() accepting dynamic accuracy. Flutter analyze shows no new errors beyond the expected GpsDataManager compile issue.
  </done>
</task>

<task type="auto">
  <name>Task 2: Implement lifecycle-aware GPS engine with precision switching and wake lock</name>
  <files>lib/services/gps_data_manager.dart</files>
  <action>
**GpsDataManager** (`lib/services/gps_data_manager.dart`) -- This is the big task. Transform GpsDataManager into a lifecycle-aware, precision-adaptive GPS engine.

**Add WidgetsBindingObserver mixin:**
- Change class declaration to `class GpsDataManager extends ChangeNotifier with WidgetsBindingObserver`
- Import `package:flutter/widgets.dart` (for WidgetsBindingObserver and WidgetsBinding)
- Import `package:wakelock_plus/wakelock_plus.dart`
- Register observer in `initialize()`: `WidgetsBinding.instance.addObserver(this)`
- Remove observer in `dispose()` BEFORE `super.dispose()`: `WidgetsBinding.instance.removeObserver(this)`

**Add overlay provider reference:**
- Add field: `OverlayProvider? _overlayProvider;`
- Add setter method: `void setOverlayProvider(OverlayProvider provider)` -- called from main.dart or SpeedometerScreen after providers are wired
- Import OverlayProvider

**Add state tracking fields:**
- `LocationAccuracy _currentAccuracy = LocationAccuracy.high;`
- `bool _hasFirstFix = false;`
- `DateTime? _firstFixTime;` (to gate precision switching for 5s after first fix)
- `bool _isAppInForeground = true;`
- `bool _isGpsActive = false;`
- `Timer? _backgroundGracePeriodTimer;`

**Fix default ProcessedGpsData initialization:**
- Change `_currentData` from `const ProcessedGpsData(...)` to non-const with `timestamp: DateTime.now()`

**Update `initialize()`:**
- After getting initial position, set `_hasFirstFix = true` and `_firstFixTime = DateTime.now()`
- Replace `GpsService.positionStream.listen(...)` with `GpsService.createPositionStream(accuracy: _currentAccuracy).listen(...)`
- Set `_isGpsActive = true` after successful subscription
- Call `_updateWakeLock()` after GPS starts

**Update `_onPositionUpdate(Position position)`:**
- Add `timestamp: DateTime.now()` to the `ProcessedGpsData(...)` constructor call
- After processing position data, add precision switching check:
  ```dart
  if (_hasFirstFix && _firstFixTime != null) {
    final timeSinceFirstFix = DateTime.now().difference(_firstFixTime!);
    if (timeSinceFirstFix >= GpsConfig.PRECISION_SWITCH_FIRST_FIX_DELAY) {
      _checkPrecisionSwitch(position.speed);
    }
  }
  ```

**Add precision switching methods:**
- `_checkPrecisionSwitch(double speedMps)`:
  - If currently HIGH and speed < PRECISION_DOWN_THRESHOLD_MPS: switch to medium
  - If currently MEDIUM and speed > PRECISION_UP_THRESHOLD_MPS: switch to high
  - Per user decision: "favor accuracy over battery" -- when in doubt, stay high
  - Log precision change at debug level only (user decision: invisible to user)
- `_switchPrecision(LocationAccuracy newAccuracy)`:
  - Set `_currentAccuracy = newAccuracy`
  - Cancel existing `_gpsSubscription`
  - Create new subscription via `GpsService.createPositionStream(accuracy: newAccuracy).listen(...)`
  - Log: `Logger.debug('Precision switched to $newAccuracy at ${(speedMps * 3.6).toStringAsFixed(1)} km/h', 'GpsDataManager')`

**Implement lifecycle handlers:**
- Override `didChangeAppLifecycleState(AppLifecycleState state)`:
  - On `AppLifecycleState.paused`:
    - Set `_isAppInForeground = false`
    - Check `_overlayProvider?.isOverlayActive ?? false`
    - If overlay active: log "maintaining full GPS", do nothing to GPS
    - If overlay NOT active: start grace period timer (7s BACKGROUND_GRACE_PERIOD)
    - Call `_updateWakeLock()`
  - On `AppLifecycleState.resumed`:
    - Set `_isAppInForeground = true`
    - Cancel grace period timer if running
    - If GPS was stopped (`_gpsSubscription == null` and `_isInitialized`): restart GPS via `_restartGps()`
    - Call `_updateWakeLock()`
- Grace period timer callback: `_onGracePeriodExpired()`:
  - IMPORTANT: Check overlay state again at expiry (not at start) to handle race condition where overlay activated during grace period
  - If overlay is now active: log "overlay became active during grace, keeping GPS", cancel and return
  - Otherwise: call `_stopGps()`

**Add GPS stop/restart methods:**
- `_stopGps()`:
  - Cancel `_gpsSubscription`, set to null
  - Set `_isGpsActive = false`
  - Do NOT clear `_currentData` -- keep last known data (user decision: show last known speed as stale)
  - Cancel `_staleDataTimer`
  - Call `_updateWakeLock()`
  - Log: `Logger.info('GPS stopped (backgrounded without overlay)', 'GpsDataManager')`
- `_restartGps()`:
  - Log: `Logger.info('Restarting GPS (app foregrounded)', 'GpsDataManager')`
  - Create new subscription via `GpsService.createPositionStream(accuracy: _currentAccuracy).listen(...)`
  - Set `_isGpsActive = true`
  - Call `_updateWakeLock()`
  - Do NOT update timestamp on old data -- let staleness show naturally per user decision ("show last known speed until fresh data arrives")

**Add wake lock management:**
- `_updateWakeLock()`:
  - `final overlayActive = _overlayProvider?.isOverlayActive ?? false;`
  - `final shouldKeepAwake = _isGpsActive && (overlayActive || _isAppInForeground);`
  - If shouldKeepAwake: `WakelockPlus.enable()`
  - Else: `WakelockPlus.disable()`
  - Log at debug level with state breakdown

**Update `dispose()`:**
- Add BEFORE existing cleanup: `WidgetsBinding.instance.removeObserver(this);`
- Add: `_backgroundGracePeriodTimer?.cancel();`
- Add: `WakelockPlus.disable();` as safety net
- Keep all existing cleanup (subscription, stale timer, data controller)

**Important constraints:**
- Do NOT remove or change the existing `_staleDataTimer` / `_scheduleStaleDataTimer()` / `_handleStaleDataTimeout()` logic -- it still serves a purpose for hard stale detection
- Do NOT change `_updateData()` method signature or behavior
- Do NOT change `getFormattedSpeed()` method
- The broadcast stream and notifyListeners pattern stays exactly the same
  </action>
  <verify>
Run `cd J:/dev/gps_speedo && flutter analyze` -- should pass with no new errors (SCREAMING_SNAKE info warnings acceptable). Verify GpsDataManager compiles with all new fields, methods, and the WidgetsBindingObserver mixin. Check that dispose() removes the observer before super.dispose(). Check that all timer fields are canceled in dispose().
  </verify>
  <done>
GpsDataManager is lifecycle-aware with WidgetsBindingObserver. Precision switches at hysteresis boundaries (8/12 km/h) with first-fix gate. Background grace period (7s) stops GPS when overlay not visible. GPS restarts on foreground resume. Wake lock is contextual (GPS active + visible). All timers canceled in dispose(). ProcessedGpsData carries timestamp. Flutter analyze passes.
  </done>
</task>

</tasks>

<verification>
1. `cd J:/dev/gps_speedo && flutter analyze` passes with no new errors
2. GpsDataManager has WidgetsBindingObserver mixin with proper registration/removal
3. ProcessedGpsData has `timestamp` field with `copyWith` support
4. GpsConfig has `PRECISION_UP_THRESHOLD_MPS` (3.33) and `PRECISION_DOWN_THRESHOLD_MPS` (2.22)
5. TimingConfig has `BACKGROUND_GRACE_PERIOD` (7s)
6. GpsService has `createPositionStream()` accepting dynamic accuracy
7. Precision switching is gated by `_hasFirstFix` and 5s delay
8. Grace period checks overlay state at expiry (not start)
9. Wake lock updates on GPS start/stop, lifecycle change
10. All new timers canceled in dispose()
</verification>

<success_criteria>
- Flutter analyze passes with no new errors
- GpsDataManager implements full lifecycle awareness (background/foreground detection)
- Precision switching works with hysteresis (8/12 km/h) and first-fix safety gate
- Background GPS stops after 7s grace period (no overlay) or continues (overlay visible)
- Wake lock is contextual: active when GPS tracking AND (overlay OR foreground)
- All ProcessedGpsData instances carry timestamps
- No regressions in existing GPS data flow (broadcast stream, notifyListeners)
</success_criteria>

<output>
After completion, create `.planning/phases/04-gps-power-optimization/04-01-SUMMARY.md`
</output>