chore: synch this plan

docs/android-implementation-directive.md

@@ -6,15 +6,29 @@
 
 ## Purpose
 
-This directive provides **step-by-step implementation guidance** for Android-specific gaps identified in the exploration:
+This directive provides **descriptive overview and integration guidance** for Android-specific gaps identified in the exploration:
 
 1. App Launch Recovery (cold/warm/force-stop)
 2. Missed Alarm Detection
 3. Force Stop Detection
 4. Boot Receiver Missed Alarm Handling
 
+**⚠️ CRITICAL**: This document is **descriptive and integrative**. The **normative implementation instructions** are in the Phase 1–3 directives below. **If any code or behavior in this file conflicts with a Phase directive, the Phase directive wins.**
+
 **Reference**: See [Exploration Findings](./exploration-findings-initial.md) for gap analysis.
 
+**⚠️ IMPORTANT**: For implementation, use the phase-specific directives (these are the canonical source of truth):
+
+- **[Phase 1: Cold Start Recovery](./android-implementation-directive-phase1.md)** - Minimal viable recovery
+  - Explicit acceptance criteria, rollback safety, data integrity checks
+  - **Start here** for fastest implementation
+  
+- **[Phase 2: Force Stop Detection & Recovery](./android-implementation-directive-phase2.md)** - Comprehensive force stop handling
+  - Prerequisite: Phase 1 complete
+  
+- **[Phase 3: Boot Receiver Missed Alarm Handling](./android-implementation-directive-phase3.md)** - Boot recovery enhancement
+  - Prerequisites: Phase 1 and Phase 2 complete
+
 ---
 
 ## 1. Implementation Overview
@@ -30,24 +44,40 @@ This directive provides **step-by-step implementation guidance** for Android-spe
 
 ### 1.2 Implementation Strategy
 
-**Phase 1**: Create `ReactivationManager` class
-- Centralizes all recovery logic
-- Handles cold/warm/force-stop scenarios
-- Detects missed alarms
-- Reschedules future alarms
+**Phase 1** – Cold start recovery only
+- Missed notification detection + future alarm verification
+- No force-stop detection, no boot handling
+- **See [Phase 1 directive](./android-implementation-directive-phase1.md) for implementation**
 
-**Phase 2**: Integrate into `DailyNotificationPlugin.load()`
-- Call recovery manager on app launch
-- Run asynchronously to avoid blocking
+**Phase 2** – Force stop detection & full recovery
+- Force stop detection via AlarmManager state comparison
+- Comprehensive recovery of all schedules (notify + fetch)
+- Past alarms marked as missed, future alarms rescheduled
+- **See [Phase 2 directive](./android-implementation-directive-phase2.md) for implementation**
 
-**Phase 3**: Enhance `BootReceiver`
-- Add missed alarm detection
-- Handle alarms that were scheduled before reboot
+**Phase 3** – Boot receiver missed alarm detection & rescheduling
+- Boot receiver detects missed alarms during device reboot
+- Next occurrence rescheduled for repeating schedules
+- **See [Phase 3 directive](./android-implementation-directive-phase3.md) for implementation**
 
 ---
 
 ## 2. Implementation: ReactivationManager
 
+**⚠️ Illustrative only** – See Phase 1 and Phase 2 directives for canonical implementation.
+
+**ReactivationManager Responsibilities by Phase**:
+
+| Phase | Responsibilities                                              |
+| ----- | ------------------------------------------------------------- |
+| 1     | Cold start only (missed detection + verify/reschedule future) |
+| 2     | Adds force stop detection & recovery                          |
+| 3     | Warm start optimizations (future)                             |
+
+**For implementation details, see:**
+- [Phase 1: ReactivationManager creation](./android-implementation-directive-phase1.md#2-implementation-reactivationmanager)
+- [Phase 2: Force stop detection](./android-implementation-directive-phase2.md#2-implementation-force-stop-detection)
+
 ### 2.1 Create New File
 
 **File**: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`
@@ -56,6 +86,8 @@ This directive provides **step-by-step implementation guidance** for Android-spe
 
 ### 2.2 Class Structure
 
+**⚠️ Illustrative only** – See Phase 1 for canonical implementation.
+
 ```kotlin
 package com.timesafari.dailynotification
 
@@ -113,6 +145,8 @@ class ReactivationManager(private val context: Context) {
 
 ### 2.3 Scenario Detection
 
+**⚠️ Illustrative only** – See Phase 2 for canonical scenario detection implementation.
+
 ```kotlin
 /**
  * Detect recovery scenario based on AlarmManager state vs database
@@ -176,6 +210,8 @@ enum class RecoveryScenario {
 
 ### 2.4 Force Stop Recovery
 
+**⚠️ Illustrative only** – See Phase 2 for canonical force stop recovery implementation.
+
 ```kotlin
 /**
  * Handle force stop recovery
@@ -234,6 +270,8 @@ private suspend fun handleForceStopRecovery() {
 
 ### 2.5 Cold Start Recovery
 
+**⚠️ Illustrative only** – See Phase 1 for canonical cold start recovery implementation.
+
 ```kotlin
 /**
  * Handle cold start recovery
@@ -571,6 +609,10 @@ override fun load() {
 
 ## 4. Enhancement: BootReceiver
 
+**⚠️ Illustrative only** – See Phase 3 directive for canonical boot receiver implementation.
+
+**For implementation details, see [Phase 3: Boot Receiver Enhancement](./android-implementation-directive-phase3.md#2-implementation-bootreceiver-enhancement)**
+
 ### 4.1 Update `rescheduleNotifications()` Method
 
 **File**: `android/src/main/java/com/timesafari/dailynotification/BootReceiver.kt`
@@ -705,6 +747,13 @@ private suspend fun handleMissedAlarmOnBoot(
 
 ## 5. Testing Requirements
 
+**⚠️ Illustrative only** – See Phase 1, Phase 2, and Phase 3 directives for canonical testing procedures.
+
+**For testing details, see:**
+- [Phase 1: Testing Requirements](./android-implementation-directive-phase1.md#8-testing-requirements)
+- [Phase 2: Testing Requirements](./android-implementation-directive-phase2.md#6-testing-requirements)
+- [Phase 3: Testing Requirements](./android-implementation-directive-phase3.md#5-testing-requirements)
+
 ### 5.1 Test Setup
 
 **Package Name**: `com.timesafari.dailynotification`