From 28fb23328624d0d7d67c5c3dc94b65f5ac10fb4b Mon Sep 17 00:00:00 2001
From: Matthew Raymer <matthew.raymer@anomalistdesign.com>
Date: Thu, 27 Nov 2025 10:01:46 +0000
Subject: [PATCH] docs(test): add Phase 3 boot recovery testing infrastructure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds documentation and test harness for Phase 3 (Boot-Time Recovery).

Changes:
- Update android-implementation-directive-phase3.md with concise boot recovery flow
- Add PHASE3-EMULATOR-TESTING.md with detailed test procedures
- Add PHASE3-VERIFICATION.md with test matrix and verification template
- Add test-phase3.sh automated test harness

Test harness features:
- 4 test cases: future alarms, past alarms, no schedules, silent recovery
- Automatic emulator reboot handling
- Log parsing for boot recovery scenario and results
- UI prompts for plugin configuration and scheduling
- Verifies silent recovery without app launch

Related:
- Directive: android-implementation-directive-phase3.md
- Requirements: docs/alarms/03-plugin-requirements.md §3.1.1
- Testing: docs/alarms/PHASE3-EMULATOR-TESTING.md
- Verification: docs/alarms/PHASE3-VERIFICATION.md
---
 docs/alarms/PHASE3-EMULATOR-TESTING.md        | 325 ++++++++
 docs/alarms/PHASE3-VERIFICATION.md            | 201 +++++
 ...android-implementation-directive-phase3.md | 714 ++++--------------
 test-apps/android-test-app/test-phase3.sh     | 578 ++++++++++++++
 4 files changed, 1258 insertions(+), 560 deletions(-)
 create mode 100644 docs/alarms/PHASE3-EMULATOR-TESTING.md
 create mode 100644 docs/alarms/PHASE3-VERIFICATION.md
 create mode 100755 test-apps/android-test-app/test-phase3.sh

diff --git a/docs/alarms/PHASE3-EMULATOR-TESTING.md b/docs/alarms/PHASE3-EMULATOR-TESTING.md
new file mode 100644
index 0000000..20c3165
--- /dev/null
+++ b/docs/alarms/PHASE3-EMULATOR-TESTING.md
@@ -0,0 +1,325 @@
+# PHASE 3 – EMULATOR TESTING  
+
+**Boot-Time Recovery (Device Reboot / System Restart)**
+
+---
+
+## 1. Purpose
+
+Phase 3 verifies that the Daily Notification Plugin correctly:
+
+1. Reconstructs **AlarmManager** alarms after a full device/emulator reboot.
+2. Handles **past** scheduled times by marking them as missed and scheduling the next occurrence.
+3. Handles **empty DB / no schedules** without misfiring recovery.
+4. Performs **silent boot recovery** (recreate alarms) even when the app is never opened after reboot.
+
+This testing is driven by the script:
+
+```bash
+test-apps/android-test-app/test-phase3.sh
+```
+
+---
+
+## 2. Prerequisites
+
+* Android emulator or device, e.g.:
+  * Pixel 8 / API 34 (recommended baseline)
+* ADB available in `PATH` (or `ADB_BIN` exported)
+* Project with:
+  * Daily Notification Plugin integrated
+  * Test app at `test-apps/android-test-app`
+* Debug APK path:
+  * `app/build/outputs/apk/debug/app-debug.apk`
+* Phase 1 and Phase 2 behaviors already implemented:
+  * Cold start detection
+  * Force-stop detection
+  * Missed / rescheduled / verified / errors summary fields
+
+> ⚠️ **Important:**
+> This script will reboot the emulator multiple times. Each reboot may take 30–60 seconds.
+
+---
+
+## 3. How to Run
+
+From the `android-test-app` directory:
+
+```bash
+cd test-apps/android-test-app
+chmod +x test-phase3.sh   # first time only
+./test-phase3.sh
+```
+
+The script will:
+
+1. Run pre-flight checks (ADB / emulator readiness).
+2. Build and install the debug APK.
+3. Guide you through four tests:
+   * **TEST 1:** Boot with Future Alarms
+   * **TEST 2:** Boot with Past Alarms
+   * **TEST 3:** Boot with No Schedules
+   * **TEST 4:** Silent Boot Recovery (App Never Opened)
+4. Parse and display `DNP-REACTIVATION` logs, including:
+   * `scenario`
+   * `missed`
+   * `rescheduled`
+   * `verified`
+   * `errors`
+
+---
+
+## 4. Test Cases (Script-Driven Flow)
+
+### 4.1 TEST 1 – Boot with Future Alarms
+
+**Goal:**
+
+Verify alarms are recreated on boot when schedules have **future run times**.
+
+**Script flow:**
+
+1. **Launch app & check plugin status**
+   * Script calls `launch_app`.
+   * UI prompt: Confirm plugin status shows:
+     * `⚙️ Plugin Settings: ✅ Configured`
+     * `🔌 Native Fetcher: ✅ Configured`
+   * If not, click **Configure Plugin**, wait until both show ✅, then continue.
+
+2. **Schedule at least one future notification**
+   * UI prompt: Click e.g. **Test Notification** to schedule a notification a few minutes in the future.
+
+3. **Verify alarms are scheduled (pre-boot)**
+   * Script calls `show_alarms` and `count_alarms`.
+   * You should see at least one `RTC_WAKEUP` entry for `com.timesafari.dailynotification`.
+
+4. **Reboot emulator**
+   * Script calls `reboot_emulator`:
+     * `adb reboot`
+     * `adb wait-for-device`
+     * Polls `getprop sys.boot_completed` until `1`.
+   * You are warned that reboot will take 30–60 seconds.
+
+5. **Collect boot recovery logs**
+   * Script calls `get_recovery_logs`:
+     ```bash
+     adb logcat -d | grep "DNP-REACTIVATION"
+     ```
+   * It parses:
+     * `missed`, `rescheduled`, `verified`, `errors`
+     * `scenario` via:
+       * `Starting boot recovery`/`boot recovery` → `scenario=BOOT`
+       * or `Detected scenario: <VALUE>`
+
+6. **Verify alarms were recreated (post-boot)**
+   * Script calls `show_alarms` and `count_alarms` again.
+   * Checks `scenario` and `rescheduled`.
+
+**Expected log patterns:**
+
+```text
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
+DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled>=1, verified=0, errors=0
+```
+
+**Pass criteria (as per script):**
+
+* `errors = 0`
+* `scenario = BOOT` (or boot detected via log text)
+* `rescheduled > 0`
+* Script prints:
+  > `✅ TEST 1 PASSED: Boot recovery detected and alarms rescheduled (scenario=BOOT, rescheduled=<n>).`
+
+If boot recovery runs but `rescheduled=0`, script warns and suggests checking boot logic.
+
+---
+
+### 4.2 TEST 2 – Boot with Past Alarms
+
+**Goal:**
+
+Verify past alarms are marked as missed and **next occurrences are scheduled** after boot.
+
+**Script flow:**
+
+1. **Launch app & ensure plugin configured**
+   * Same plugin status check as TEST 1.
+
+2. **Schedule a notification in the near future**
+   * UI prompt: Schedule such that **by the time you reboot and the device comes back, the planned notification time is in the past**.
+
+3. **Wait or adjust so the alarm is effectively "in the past" at boot**
+   * The script may instruct you to wait, or you can coordinate timing manually.
+
+4. **Reboot emulator**
+   * Same `reboot_emulator` path as TEST 1.
+
+5. **Collect boot recovery logs**
+   * Script parses:
+     * `missed`, `rescheduled`, `errors`, `scenario`.
+
+**Expected log patterns:**
+
+```text
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Marked missed notification: daily_<id>
+DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <next_time>
+DNP-REACTIVATION: Boot recovery complete: missed>=1, rescheduled>=1, errors=0
+```
+
+**Pass criteria:**
+
+* `errors = 0`
+* `missed >= 1`
+* `rescheduled >= 1`
+* Script prints:
+  > `✅ TEST 2 PASSED: Past alarms detected and next occurrence scheduled (missed=<m>, rescheduled=<r>).`
+
+If `missed >= 1` but `rescheduled = 0`, script warns that reschedule logic may be incomplete.
+
+---
+
+### 4.3 TEST 3 – Boot with No Schedules
+
+**Goal:**
+
+Verify boot recovery handles an **empty DB / no schedules** safely and does **not** schedule anything.
+
+**Script flow:**
+
+1. **Uninstall app to clear DB/state**
+   * Script calls:
+     ```bash
+     adb uninstall com.timesafari.dailynotification
+     ```
+
+2. **Reinstall APK**
+   * Script reinstalls `app-debug.apk`.
+
+3. **Launch app WITHOUT scheduling anything**
+   * Script launches app; you do not configure or schedule.
+
+4. **Collect boot/logs**
+   * Script reads `DNP-REACTIVATION` logs and checks:
+     * if there are no logs, or
+     * if there's a "No schedules found / present" message, or
+     * if `scenario=NONE` and `rescheduled=0`.
+
+**Expected patterns:**
+
+* *Ideal simple case:* **No** `DNP-REACTIVATION` logs at all, or:
+* Explicit message in logs:
+  ```text
+  DNP-REACTIVATION: ... No schedules found ...
+  ```
+
+**Pass criteria (as per script):**
+
+* If **no logs**:
+  * Pass: `TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior).`
+* If logs exist:
+  * Contains `No schedules found` / `No schedules present` **and** `rescheduled=0`, or
+  * `scenario = NONE` and `rescheduled = 0`.
+
+Any case where `rescheduled > 0` with an empty DB is flagged as a warning (boot recovery misfiring).
+
+---
+
+### 4.4 TEST 4 – Silent Boot Recovery (App Never Opened)
+
+**Goal:**
+
+Verify that boot recovery **occurs silently**, recreating alarms **without opening the app** after reboot.
+
+**Script flow:**
+
+1. **Launch app and configure plugin**
+   * Same plugin status flow:
+     * Ensure both plugin checks are ✅.
+   * Schedule a future notification via UI.
+
+2. **Verify alarms are scheduled**
+   * Script shows alarms and counts (`before_count`).
+
+3. **Reboot emulator**
+   * Script runs `reboot_emulator` and explicitly warns:
+     * Do **not** open the app after reboot.
+     * After emulator returns, script instructs you to **not touch the app UI**.
+
+4. **Collect boot recovery logs**
+   * Script gathers and parses `DNP-REACTIVATION` lines.
+
+5. **Verify alarms were recreated without app launch**
+   * Script calls `show_alarms` and `count_alarms` again.
+   * Uses `rescheduled` + alarm count to decide.
+
+**Pass criteria (as per script):**
+
+* `rescheduled > 0` after boot, and
+* Alarm count after boot is > 0, and
+* App was **never** launched by the user after reboot.
+
+Script prints one of:
+
+```text
+✅ TEST 4 PASSED: Boot recovery occurred silently and alarms were recreated (rescheduled=<n>) without app launch.
+
+✅ TEST 4 PASSED: Boot recovery occurred silently (rescheduled=<n>), but alarm count check unclear.
+```
+
+If boot recovery logs are present but no alarms appear, script warns; if no boot-recovery logs are found at all, script suggests verifying the boot receiver and BOOT_COMPLETED permission.
+
+---
+
+## 5. Overall Summary Section (from Script)
+
+At the end, the script prints:
+
+```text
+TEST 1: Boot with Future Alarms
+  - Check logs for boot recovery and rescheduled>0
+
+TEST 2: Boot with Past Alarms
+  - Check logs for missed>=1 and rescheduled>=1
+
+TEST 3: Boot with No Schedules
+  - Check that no recovery runs or that an explicit 'No schedules found' is logged without rescheduling
+
+TEST 4: Silent Boot Recovery
+  - Check that boot recovery occurred and alarms were recreated without app launch
+```
+
+Use this as a quick checklist after a run.
+
+---
+
+## 6. Troubleshooting Notes
+
+* If **no boot recovery logs** ever appear:
+  * Check that `BootReceiver` is declared and `RECEIVE_BOOT_COMPLETED` permission is set.
+  * Ensure the app is installed in internal storage (not moved to SD).
+
+* If **errors > 0** in summary:
+  * Inspect the full `DNP-REACTIVATION` logs printed by the script.
+
+* If **alarming duplication** is observed:
+  * Review `runBootRecovery` and dedupe logic around re-scheduling.
+
+---
+
+## 7. Related Documentation
+
+- [Phase 3 Directive](../android-implementation-directive-phase3.md) - Implementation details
+- [Phase 3 Verification](./PHASE3-VERIFICATION.md) - Verification report
+- [Phase 1 Testing Guide](./PHASE1-EMULATOR-TESTING.md) - Prerequisite testing
+- [Phase 2 Testing Guide](./PHASE2-EMULATOR-TESTING.md) - Prerequisite testing
+- [Activation Guide](./ACTIVATION-GUIDE.md) - How to use directives
+- [Plugin Requirements](./03-plugin-requirements.md) - Requirements Phase 3 implements
+
+---
+
+**Status**: Ready for testing (Phase 3 implementation pending)  
+**Last Updated**: November 2025
diff --git a/docs/alarms/PHASE3-VERIFICATION.md b/docs/alarms/PHASE3-VERIFICATION.md
new file mode 100644
index 0000000..ac24889
--- /dev/null
+++ b/docs/alarms/PHASE3-VERIFICATION.md
@@ -0,0 +1,201 @@
+# Phase 3 – Boot-Time Recovery Verification
+
+**Plugin:** Daily Notification Plugin  
+**Scope:** Boot-Time Recovery (Recreate Alarms After Reboot)  
+**Related Docs:**
+- `android-implementation-directive-phase3.md`
+- `PHASE3-EMULATOR-TESTING.md`
+- `test-phase3.sh`
+- `000-UNIFIED-ALARM-DIRECTIVE.md`
+
+---
+
+## 1. Objective
+
+Phase 3 confirms that the Daily Notification Plugin:
+
+1. Reconstructs all daily notification alarms after a **full device reboot**.
+2. Correctly handles **past** vs **future** schedules:
+   - Past: mark as missed, schedule next occurrence
+   - Future: simply recreate alarms
+3. Handles **empty DB / no schedules** without misfiring recovery.
+4. Performs **silent boot recovery** (no app launch required) when schedules exist.
+5. Logs a consistent, machine-readable summary:
+   - `scenario`
+   - `missed`
+   - `rescheduled`
+   - `verified`
+   - `errors`
+
+Verification is performed via the emulator harness:
+
+```bash
+cd test-apps/android-test-app
+./test-phase3.sh
+```
+
+---
+
+## 2. Test Matrix (From Script)
+
+| ID  | Scenario                                | Script Test                                      | Expected Behavior                                                                                                        | Result | Notes |
+| --- | --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------ | ----- |
+| 3.1 | Boot with Future Alarms                 | TEST 1 – Boot with Future Alarms                 | `scenario=BOOT`, `rescheduled>0`, `errors=0`; alarms present after boot                                                  | ☐      |       |
+| 3.2 | Boot with Past Alarms                   | TEST 2 – Boot with Past Alarms                   | `missed>=1` and `rescheduled>=1`, `errors=0`; past schedules detected and next occurrences scheduled                     | ☐      |       |
+| 3.3 | Boot with No Schedules (Empty DB)       | TEST 3 – Boot with No Schedules                  | Either no recovery logs **or** explicit "No schedules found/present" or `scenario=NONE` with `rescheduled=0`, `errors=0` | ☐      |       |
+| 3.4 | Silent Boot Recovery (App Never Opened) | TEST 4 – Silent Boot Recovery (App Never Opened) | `rescheduled>0`, alarms present after boot, and no user launch required; `errors=0`                                      | ☐      |       |
+
+Fill **Result** and **Notes** after running `test-phase3.sh` on your baseline emulator/device.
+
+---
+
+## 3. Expected Log Patterns
+
+The script filters logs with:
+
+```bash
+adb logcat -d | grep "DNP-REACTIVATION"
+```
+
+### 3.1 Boot with Future Alarms (3.1 / TEST 1)
+
+* Typical logs:
+
+```text
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
+DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=<r>, verified=0, errors=0
+```
+
+* The script interprets this as:
+  * `scenario = BOOT` (via "Starting boot recovery" or "boot recovery" text or `Detected scenario: BOOT`)
+  * `rescheduled > 0`
+  * `errors = 0`
+
+### 3.2 Boot with Past Alarms (3.2 / TEST 2)
+
+* Typical logs:
+
+```text
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Marked missed notification: daily_<id>
+DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <next_time>
+DNP-REACTIVATION: Boot recovery complete: missed=<m>, rescheduled=<r>, verified=0, errors=0
+```
+
+* The script parses `missed` and `rescheduled` and passes when:
+  * `missed >= 1`
+  * `rescheduled >= 1`
+  * `errors = 0`
+
+### 3.3 Boot with No Schedules (3.3 / TEST 3)
+
+Two acceptable patterns:
+
+1. **No `DNP-REACTIVATION` logs at all** → safe behavior
+2. Explicit "no schedules" logs:
+
+```text
+DNP-REACTIVATION: ... No schedules found ...
+```
+
+or a neutral scenario:
+
+```text
+DNP-REACTIVATION: ... scenario=NONE ...
+DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=0, verified=0, errors=0
+```
+
+The script passes when:
+
+* Either `logs` are empty, or
+* Logs contain "No schedules found / present" with `rescheduled=0`, or
+* `scenario=NONE` and `rescheduled=0`.
+
+Any `rescheduled>0` in this state is flagged as a potential boot-recovery misfire.
+
+### 3.4 Silent Boot Recovery (3.4 / TEST 4)
+
+* Expected:
+
+```text
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Rescheduled alarm: daily_<id> for <time>
+DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=<r>, verified=0, errors=0
+```
+
+* After reboot:
+  * `count_alarms` > 0
+  * User **did not** relaunch the app manually
+
+Script passes if:
+
+* `rescheduled>0`, and
+* Alarm count after boot is > 0, and
+* Boot recovery is detected from logs (via "Starting boot recovery"/"boot recovery" or scenario).
+
+---
+
+## 4. Latest Known Good Run (Template)
+
+> Fill this in after your first clean emulator run.
+
+**Environment**
+
+* Device: Pixel 8 API 34 (Android 14)
+* App ID: `com.timesafari.dailynotification`
+* Build: Debug `app-debug.apk` from commit `<GIT_HASH>`
+* Script: `./test-phase3.sh`
+* Date: 2025-11-XX
+
+**Observed Results**
+
+* ☐ **3.1 – Boot with Future Alarms**
+  * `scenario=BOOT`
+  * `missed=0, rescheduled=<r>, errors=0`
+
+* ☐ **3.2 – Boot with Past Alarms**
+  * `missed=<m>=1`, `rescheduled=<r>≥1`, `errors=0`
+
+* ☐ **3.3 – Boot with No Schedules**
+  * Either no logs, or explicit "No schedules found" with `rescheduled=0`
+
+* ☐ **3.4 – Silent Boot Recovery**
+  * `rescheduled>0`, alarms present after boot, app not opened
+
+**Conclusion:**
+
+> Phase 3 **Boot-Time Recovery** is successfully verified on emulator using `test-phase3.sh`. This is the canonical baseline for future regression testing and refactors to `ReactivationManager` and `BootReceiver`.
+
+---
+
+## 5. Overall Status
+
+> Update once the first emulator run is complete.
+
+* **Implementation Status:** ☐ Pending / ✅ Implemented (Boot receiver + `runBootRecovery`)
+* **Test Harness:** ✅ `test-phase3.sh` in `test-apps/android-test-app`
+* **Emulator Verification:** ☐ Pending / ✅ Completed
+
+Once all test cases pass:
+
+> **Overall Status:** ✅ **VERIFIED** – Phase 3 boot-time recovery is implemented and emulator-tested, aligned with `android-implementation-directive-phase3.md` and the unified alarm directive.
+
+---
+
+## 6. Related Documentation
+
+- [Phase 3 Directive](../android-implementation-directive-phase3.md) - Implementation details
+- [Phase 3 Emulator Testing](./PHASE3-EMULATOR-TESTING.md) - Test procedures
+- [Phase 1 Verification](./PHASE1-VERIFICATION.md) - Prerequisite verification
+- [Phase 2 Verification](./PHASE2-VERIFICATION.md) - Prerequisite verification
+- [Plugin Requirements](./03-plugin-requirements.md) - Requirements this phase implements
+- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
+
+---
+
+**Status**: ☐ **PENDING** – Phase 3 implementation and testing pending  
+**Last Updated**: November 2025
diff --git a/docs/android-implementation-directive-phase3.md b/docs/android-implementation-directive-phase3.md
index 9f6159f..96008a0 100644
--- a/docs/android-implementation-directive-phase3.md
+++ b/docs/android-implementation-directive-phase3.md
@@ -1,627 +1,221 @@
-# Android Implementation Directive: Phase 3 - Boot Receiver Missed Alarm Handling
+# Android Implementation Directive – Phase 3  
+## Boot-Time Recovery (Device Reboot / System Restart)
 
-**Author**: Matthew Raymer  
-**Date**: November 2025  
-**Status**: Phase 3 - Boot Recovery Enhancement  
-**Version**: 1.0.0  
-**Last Synced With Plugin Version**: v1.1.0
-
-**Implements**: [Plugin Requirements §3.1.1 - Boot Event](./alarms/03-plugin-requirements.md#311-boot-event-android-only)
-
-## Purpose
-
-Phase 3 enhances the **boot receiver** to detect and handle missed alarms during device reboot. This handles alarms that were scheduled before reboot but were missed because alarms are wiped on reboot.
-
-**Prerequisites**: Phase 1 and Phase 2 must be complete.
-
-**Scope**: Boot receiver missed alarm detection and handling.
-
-**Dependencies**: Boot receiver behavior assumes that Phase 1 and Phase 2 definitions of 'missed alarm', 'next occurrence', and `Schedule`/`NotificationContentEntity` semantics are already in place.
-
-**Reference**: 
-- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
-- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
-- [Phase 1](./android-implementation-directive-phase1.md) - Prerequisite
-- [Phase 2](./android-implementation-directive-phase2.md) - Prerequisite
-- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope
-
-**Boot vs App Launch Recovery**:
-
-| Scenario                         | Entry point                             | Directive | Responsibility                           |
-| -------------------------------- | --------------------------------------- | --------- | ---------------------------------------- |
-| App launch after kill/force-stop | `ReactivationManager.performRecovery()` | Phase 1–2 | Detect & recover missed                  |
-| Device reboot                    | `BootReceiver` → `ReactivationManager`  | Phase 3   | Queue recovery, ReactivationManager handles |
-
-**User-Facing Behavior**: In Phase 3, missed alarms are **recorded** and **rescheduled**, but not yet surfaced to the user with explicit "you missed this" UX (that's a future concern).
+**Plugin:** Daily Notification Plugin  
+**Author:** Matthew Raymer  
+**Applies to:** Android Plugin (Kotlin), Capacitor Bridge  
+**Related Docs:**  
+- `03-plugin-requirements.md`  
+- `000-UNIFIED-ALARM-DIRECTIVE.md`  
+- `android-implementation-directive-phase1.md`  
+- `android-implementation-directive-phase2.md`  
+- `ACTIVATION-GUIDE.md`
 
 ---
 
-## 1. Acceptance Criteria
+## 1. Purpose
 
-### 1.1 Definition of Done
+Phase 3 introduces **Boot-Time Recovery**, which restores daily notifications after:
 
-**Phase 3 is complete when:**
+- Device reboot  
+- OS restart  
+- Update-related restart  
+- App not opened after reboot (silent recovery)  
 
-1. ✅ **Boot receiver detects missed alarms**
-   - Alarms with `nextRunAt < currentTime` detected during boot recovery
-   - Detection runs automatically on `BOOT_COMPLETED` intent
-   - Detection completes within 5 seconds (boot receiver timeout)
+Android clears **all alarms** on reboot.  
+Therefore, if our plugin is not actively rescheduling on boot, the user will miss all daily notifications until they manually launch the app.
 
-2. ✅ **Missed alarms are marked in database**
-   - `delivery_status` updated to `'missed'`
-   - `last_delivery_attempt` updated to current time
-   - Status change logged in history table
+Phase 3 ensures:
 
-3. ✅ **Next occurrence is rescheduled for repeating schedules**
-   - Repeating schedules calculate next occurrence after missed time
-   - Next occurrence scheduled via AlarmManager
-   - Non-repeating schedules not rescheduled
-
-4. ✅ **Future alarms are rescheduled**
-   - All future alarms (not missed) rescheduled normally
-   - Existing boot receiver logic enhanced, not replaced
-
-5. ✅ **Boot recovery never crashes**
-   - All exceptions caught and logged
-   - Database errors don't propagate
-   - Invalid data handled gracefully
-
-### 1.2 Success Metrics
-
-| Metric | Target | Measurement |
-|--------|--------|-------------|
-| Boot receiver execution time | < 5 seconds | Log timestamp difference |
-| Missed detection accuracy | 100% | Manual verification via logs |
-| Next occurrence calculation accuracy | 100% | Verify scheduled time matches expected |
-| Recovery success rate | > 95% | History table outcome field |
-| Crash rate | 0% | No exceptions propagate |
-
-### 1.3 Out of Scope (Phase 3)
-
-- ❌ Warm start optimization (future phase)
-- ❌ Callback event emission (future phase)
-- ❌ User notification of missed alarms (future phase)
-- ❌ Boot receiver performance optimization (future phase)
+1. Schedules stored in SQLite survive reboot  
+2. Alarms are fully reconstructed  
+3. No duplication / double-scheduling  
+4. Boot behavior avoids unnecessary heavy recovery  
+5. Recovery occurs even if the user does **not** manually open the app
 
 ---
 
-## 2. Implementation: BootReceiver Enhancement
+## 2. Boot-Time Recovery Flow
 
-### 2.1 Canonical Source of Truth
+### Trigger:
 
-**⚠️ CRITICAL CORRECTION**: BootReceiver must **NOT** implement recovery logic directly. It must **only queue** ReactivationManager.performRecovery() with a BOOT flag.
+`BOOT_COMPLETED` broadcast received  
+→ Plugin's Boot Receiver invoked  
+→ Recovery logic executed with `scenario=BOOT`
 
-**ReactivationManager.kt** is the **only** file allowed to:
-- Perform scenario detection
-- Initiate recovery logic
-- Branch execution per phase
+### Recovery Steps
 
-### 2.2 Update BootReceiver
+1. **Load all schedules** from SQLite (`NotificationRepository.getAllSchedules()`)
 
-**File**: `android/src/main/java/com/timesafari/dailynotification/BootReceiver.kt`
+2. **For each schedule:**
+   - Calculate next runtime based on cron expression
+   - Compare with current time
 
-**Location**: `onReceive()` method
+3. **If the next scheduled time is in the future:**
+   - Recreate alarm with `setAlarmClock`
+   - Log:  
+     `Rescheduled alarm: <id> for <ts>`
 
-### 2.3 Corrected Implementation
+4. **If schedule was *in the past* at boot time:**
+   - Mark as missed
+   - Schedule next run according to cron rules
+
+5. **If no schedules found:**
+   - Quiet exit, log only one line:
+     `BOOT: No schedules found`
+
+6. **Safeties:**
+   - Boot recovery must **not** modify Plugin Settings  
+   - Must not regenerate Fetcher configuration  
+   - Must not overwrite database records  
+
+---
+
+## 3. Required Android Components
+
+### 3.1 Boot Receiver
+
+```xml
+<receiver
+    android:name=".BootReceiver"
+    android:enabled="true"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED" />
+    </intent-filter>
+</receiver>
+```
+
+### 3.2 Kotlin Class
 
-**Corrected Code** (BootReceiver only queues recovery):
 ```kotlin
-package com.timesafari.dailynotification
-
-import android.content.BroadcastReceiver
-import android.content.Context
-import android.content.Intent
-import android.content.SharedPreferences
-import android.util.Log
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.launch
-
-/**
- * Boot recovery receiver to trigger recovery after device reboot
- * Phase 3: Only queues ReactivationManager, does not implement recovery directly
- * 
- * @author Matthew Raymer
- * @version 2.0.0 - Corrected to queue ReactivationManager only
- */
 class BootReceiver : BroadcastReceiver() {
-    
-    companion object {
-        private const val TAG = "DNP-BOOT"
-        private const val PREFS_NAME = "dailynotification_recovery"
-        private const val KEY_LAST_BOOT_AT = "last_boot_at"
-    }
-
     override fun onReceive(context: Context, intent: Intent?) {
-        if (intent?.action == Intent.ACTION_BOOT_COMPLETED) {
-            Log.i(TAG, "Boot completed, queuing ReactivationManager recovery")
-            
-            // Set boot flag in SharedPreferences
-            // ReactivationManager will detect this and handle recovery
-            val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
-            prefs.edit().putLong(KEY_LAST_BOOT_AT, System.currentTimeMillis()).apply()
-            
-            // Queue ReactivationManager recovery
-            // Recovery will run when app launches or can be triggered immediately
-            CoroutineScope(Dispatchers.IO).launch {
-                try {
-                    val reactivationManager = ReactivationManager(context)
-                    reactivationManager.performRecovery()
-                    Log.i(TAG, "Boot recovery queued to ReactivationManager")
-                } catch (e: Exception) {
-                    Log.e(TAG, "Failed to queue boot recovery", e)
-                }
-            }
-        }
+        if (intent?.action != Intent.ACTION_BOOT_COMPLETED) return
+
+        ReactivationManager.runBootRecovery(context)
     }
 }
 ```
 
-**⚠️ REMOVED**: All direct rescheduling logic from BootReceiver. Recovery is now handled entirely by ReactivationManager.
-
-### 2.4 How Boot Recovery Works
-
-**Flow**:
-1. Device reboots → `BootReceiver.onReceive()` called
-2. BootReceiver sets `last_boot_at` flag in SharedPreferences
-3. BootReceiver queues `ReactivationManager.performRecovery()`
-4. ReactivationManager detects BOOT scenario via `isBootRecovery()`
-5. ReactivationManager handles recovery (same logic as force stop - all alarms wiped)
-
-**Key Points**:
-- BootReceiver **never** implements recovery directly
-- All recovery logic is in ReactivationManager
-- Boot recovery uses same recovery path as force stop (all alarms wiped on reboot)
-
 ---
 
-## 3. Data Integrity Checks
-```kotlin
-/**
- * Reschedule notifications after device reboot
- * Phase 3: Adds missed alarm detection and handling
- * 
- * @param context Application context
- */
-private suspend fun rescheduleNotifications(context: Context) {
-    val db = DailyNotificationDatabase.getDatabase(context)
-    val enabledSchedules = db.scheduleDao().getEnabled()
-    val currentTime = System.currentTimeMillis()
-    
-    Log.i(TAG, "Boot recovery: Found ${enabledSchedules.size} enabled schedules to reschedule")
-    
-    var futureRescheduled = 0
-    var missedDetected = 0
-    var missedRescheduled = 0
-    var errors = 0
-    
-    enabledSchedules.forEach { schedule ->
-        try {
-            when (schedule.kind) {
-                "fetch" -> {
-                    // Reschedule WorkManager fetch (unchanged)
-                    val config = ContentFetchConfig(
-                        enabled = schedule.enabled,
-                        schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
-                        url = null,
-                        timeout = 30000,
-                        retryAttempts = 3,
-                        retryDelay = 1000,
-                        callbacks = CallbackConfig()
-                    )
-                    FetchWorker.scheduleFetch(context, config)
-                    Log.i(TAG, "Rescheduled fetch for schedule: ${schedule.id}")
-                    futureRescheduled++
-                }
-                "notify" -> {
-                    // Phase 3: Handle both past and future alarms
-                    val nextRunTime = calculateNextRunTime(schedule)
-                    
-                    if (nextRunTime > currentTime) {
-                        // Future alarm - reschedule normally
-                        val config = UserNotificationConfig(
-                            enabled = schedule.enabled,
-                            schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
-                            title = "Daily Notification",
-                            body = "Your daily update is ready",
-                            sound = true,
-                            vibration = true,
-                            priority = "normal"
-                        )
-                        NotifyReceiver.scheduleExactNotification(context, nextRunTime, config)
-                        Log.i(TAG, "Rescheduled future notification: ${schedule.id} for $nextRunTime")
-                        futureRescheduled++
-                    } else {
-                        // Past alarm - was missed during reboot
-                        missedDetected++
-                        Log.i(TAG, "Missed alarm detected on boot: ${schedule.id} scheduled for $nextRunTime")
-                        
-                        // Mark as missed
-                        handleMissedAlarmOnBoot(context, schedule, nextRunTime, db)
-                        
-                        // Reschedule next occurrence if repeating
-                        if (isRepeating(schedule)) {
-                            try {
-                                val nextOccurrence = calculateNextOccurrence(schedule, currentTime)
-                                val config = UserNotificationConfig(
-                                    enabled = schedule.enabled,
-                                    schedule = schedule.cron ?: schedule.clockTime ?: "0 9 * * *",
-                                    title = "Daily Notification",
-                                    body = "Your daily update is ready",
-                                    sound = true,
-                                    vibration = true,
-                                    priority = "normal"
-                                )
-                                NotifyReceiver.scheduleExactNotification(context, nextOccurrence, config)
-                                Log.i(TAG, "Rescheduled next occurrence for missed alarm: ${schedule.id} for $nextOccurrence")
-                                missedRescheduled++
-                            } catch (e: Exception) {
-                                errors++
-                                Log.e(TAG, "Failed to reschedule next occurrence: ${schedule.id}", e)
-                            }
-                        }
-                    }
-                }
-                else -> {
-                    Log.w(TAG, "Unknown schedule kind: ${schedule.kind}")
-                }
-            }
-        } catch (e: Exception) {
-            errors++
-            Log.e(TAG, "Failed to reschedule ${schedule.kind} for ${schedule.id}", e)
-        }
-    }
-    
-    // Record boot recovery in history
-    try {
-        db.historyDao().insert(
-            History(
-                refId = "boot_recovery_${System.currentTimeMillis()}",
-                kind = "boot_recovery",
-                occurredAt = System.currentTimeMillis(),
-                outcome = if (errors == 0) "success" else "partial",
-                diagJson = """
-                    {
-                        "schedules_rescheduled": $futureRescheduled,
-                        "missed_detected": $missedDetected,
-                        "missed_rescheduled": $missedRescheduled,
-                        "errors": $errors
-                    }
-                """.trimIndent()
-            )
-        )
-    } catch (e: Exception) {
-        Log.e(TAG, "Failed to record boot recovery history", e)
-        // Don't fail boot recovery if history recording fails
-    }
-    
-    Log.i(TAG, "Boot recovery complete: $futureRescheduled future, $missedDetected missed, $missedRescheduled next occurrences, $errors errors")
-}
-```
+## 4. ReactivationManager – Boot Logic
 
-**Note**: All data integrity checks are handled by ReactivationManager (Phase 2). BootReceiver does not perform any data operations directly.
-
-### 3.1 Missed Alarm Detection Validation
+### Method Signature
 
 ```kotlin
-/**
- * Handle missed alarm detected during boot recovery
- * Phase 3: Marks missed alarm in database
- * 
- * @param context Application context
- * @param schedule Schedule that was missed
- * @param scheduledTime When the alarm was scheduled
- * @param db Database instance
- */
-private suspend fun handleMissedAlarmOnBoot(
-    context: Context,
-    schedule: Schedule,
-    scheduledTime: Long,
-    db: DailyNotificationDatabase
-) {
-    try {
-        // Data integrity check
-        if (schedule.id.isBlank()) {
-            Log.w(TAG, "Skipping invalid schedule: empty ID")
-            return
-        }
-        
-        // Try to find existing NotificationContentEntity
-        val notificationId = schedule.id
-        val existingNotification = db.notificationContentDao().getNotificationById(notificationId)
-        
-        if (existingNotification != null) {
-            // Update existing notification
-            existingNotification.deliveryStatus = "missed"
-            existingNotification.lastDeliveryAttempt = System.currentTimeMillis()
-            existingNotification.deliveryAttempts = (existingNotification.deliveryAttempts ?: 0) + 1
-            db.notificationContentDao().updateNotification(existingNotification)
-            Log.d(TAG, "Marked missed notification on boot: $notificationId")
-        } else {
-            // No NotificationContentEntity found - this is okay for boot recovery
-            // The schedule exists but content may not have been fetched yet
-            Log.d(TAG, "No NotificationContentEntity found for missed schedule: $notificationId (expected for boot recovery)")
-        }
-        
-        // Record missed alarm in history
-        try {
-            db.historyDao().insert(
-                History(
-                    refId = "missed_boot_${schedule.id}_${System.currentTimeMillis()}",
-                    kind = "missed_alarm",
-                    occurredAt = System.currentTimeMillis(),
-                    outcome = "missed",
-                    diagJson = """
-                        {
-                            "schedule_id": "${schedule.id}",
-                            "scheduled_time": $scheduledTime,
-                            "detected_at": ${System.currentTimeMillis()},
-                            "scenario": "boot_recovery"
-                        }
-                    """.trimIndent()
-                )
-            )
-        } catch (e: Exception) {
-            Log.w(TAG, "Failed to record missed alarm history", e)
-            // Don't fail if history recording fails
-        }
-        
-    } catch (e: Exception) {
-        Log.e(TAG, "Failed to handle missed alarm on boot: ${schedule.id}", e)
-        // Don't throw - continue with boot recovery
-    }
-}
+fun runBootRecovery(context: Context)
 ```
 
-### 2.5 Helper Methods
+### Required Logging (canonical)
 
-**⚠️ Implementation Consistency**: These helpers must match the implementation used in `ReactivationManager` (Phase 2). Treat ReactivationManager as canonical and keep these in sync.
-
-```kotlin
-/**
- * Check if schedule is repeating
- * 
- * **Implementation Note**: Must match `isRepeating()` in ReactivationManager (Phase 2).
- * This is a duplication for now; treat ReactivationManager as canonical.
- * 
- * @param schedule Schedule to check
- * @return true if repeating, false if one-time
- */
-private fun isRepeating(schedule: Schedule): Boolean {
-    // Schedules with cron or clockTime are repeating
-    return schedule.cron != null || schedule.clockTime != null
-}
-
-/**
- * Calculate next occurrence for repeating schedule
- * 
- * **Implementation Note**: Must match `calculateNextOccurrence()` in ReactivationManager (Phase 2).
- * This is a duplication for now; treat ReactivationManager as canonical.
- * 
- * @param schedule Schedule to calculate for
- * @param fromTime Calculate next occurrence after this time
- * @return Next occurrence time in milliseconds
- */
-private fun calculateNextOccurrence(schedule: Schedule, fromTime: Long): Long {
-    // TODO: Implement proper calculation based on cron/clockTime
-    // For now, simplified: daily schedules add 24 hours
-    // This should match the logic in ReactivationManager (Phase 2)
-    return when {
-        schedule.cron != null -> {
-            // Parse cron and calculate next occurrence
-            // For now, simplified: daily schedules
-            fromTime + (24 * 60 * 60 * 1000L)
-        }
-        schedule.clockTime != null -> {
-            // Parse HH:mm and calculate next occurrence
-            // For now, simplified: daily schedules
-            fromTime + (24 * 60 * 60 * 1000L)
-        }
-        else -> {
-            // Not repeating
-            fromTime
-        }
-    }
-}
+```
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded <N> schedules from DB
+DNP-REACTIVATION: Rescheduled alarm: <id> for <ts>
+DNP-REACTIVATION: Marked missed notification: <id>
+DNP-REACTIVATION: Boot recovery complete: missed=X, rescheduled=Y, errors=Z
 ```
 
----
+### Required Fields
 
-## 3. Data Integrity Checks
-
-### 3.1 Missed Alarm Detection Validation
-
-**Boot Flag Rules**:
-- ✅ BootReceiver sets flag immediately on BOOT_COMPLETED
-- ✅ Flag is valid for 60 seconds after boot
-- ✅ ReactivationManager clears flag after reading
-- ✅ Stale flags are ignored (prevents false positives)
-
-**Edge Cases**:
-- ✅ Multiple boot broadcasts: Flag is overwritten (last one wins)
-- ✅ App not launched after boot: Flag expires after 60 seconds
-- ✅ SharedPreferences errors: Log error, recovery continues
+* `scenario=BOOT`
+* `missed`
+* `rescheduled`
+* `verified` **MUST BE 0** (boot has no verification phase)
 
 ---
 
-## 4. Rollback Safety
+## 5. Constraints & Guardrails
 
-### 4.1 No-Crash Guarantee
+1. **No plugin initialization**
+   Boot must *not* require running the app UI.
 
-**All boot recovery operations must:**
+2. **No heavy processing**
+   * limit to 2 seconds
+   * use the same timeout guard as Phase 2
 
-1. **Catch all exceptions** - Never propagate exceptions
-2. **Continue processing** - One schedule failure doesn't stop recovery
-3. **Log errors** - All failures logged with context
-4. **Timeout protection** - Boot receiver has 10-second timeout (Android limit)
+3. **No scheduling duplicates**
+   * Must detect existing AlarmManager entries
+   * Boot always clears them, so all reschedules should be fresh
 
-### 4.2 Error Handling Strategy
+4. **App does not need to be opened**
+   * Entire recovery must run in background context
 
-| Error Type | Handling | Log Level |
-|------------|----------|-----------|
-| Schedule query failure | Return empty list, log error | ERROR |
-| Invalid schedule data | Skip schedule, continue | WARN |
-| Missed alarm marking failure | Log error, continue | ERROR |
-| Next occurrence calculation failure | Log error, don't reschedule | ERROR |
-| Alarm reschedule failure | Log error, continue | ERROR |
-| History recording failure | Log warning, don't fail | WARN |
-
----
-
-## 5. Testing Requirements
-
-### 5.1 Test 1: Boot Recovery Missed Detection
-
-**Purpose**: Verify boot receiver detects missed alarms.
-
-**Steps**:
-1. Schedule notification for 5 minutes in future
-2. Verify alarm scheduled: `adb shell dumpsys alarm | grep timesafari`
-3. Reboot device: `adb reboot`
-4. Wait for boot: `adb wait-for-device && adb shell getprop sys.boot_completed` (wait for "1")
-5. Wait 10 minutes (past scheduled time)
-6. Check boot logs: `adb logcat -d | grep DNP-BOOT`
-
-**Expected**:
-- ✅ Log shows "Boot recovery: Found X enabled schedules"
-- ✅ Log shows "Missed alarm detected on boot: <id>"
-- ✅ Database shows `delivery_status = 'missed'`
-
-**Pass Criteria**: Missed alarm detected during boot recovery.
-
-### 5.2 Test 2: Next Occurrence Rescheduling
-
-**Purpose**: Verify repeating schedules calculate next occurrence correctly.
-
-**Steps**:
-1. Schedule daily notification (cron: "0 9 * * *") for today at 9 AM
-2. Reboot device
-3. Wait until 10 AM (past scheduled time)
-4. Check boot logs
-5. Verify next occurrence scheduled: `adb shell dumpsys alarm | grep timesafari`
-
-**Expected**:
-- ✅ Log shows "Missed alarm detected on boot"
-- ✅ Log shows "Rescheduled next occurrence for missed alarm"
-- ✅ AlarmManager shows alarm scheduled for tomorrow 9 AM
-
-**Pass Criteria**: Next occurrence correctly calculated and scheduled.
-
-### 5.3 Test 3: Future Alarm Rescheduling
-
-**Purpose**: Verify future alarms are still rescheduled normally.
-
-**Steps**:
-1. Schedule notification for 1 hour in future
-2. Reboot device
-3. Wait for boot
-4. Verify alarm rescheduled: `adb shell dumpsys alarm | grep timesafari`
-
-**Expected**:
-- ✅ Log shows "Rescheduled future notification"
-- ✅ AlarmManager shows alarm scheduled for original time
-- ✅ No missed alarm detection for future alarms
-
-**Pass Criteria**: Future alarms rescheduled normally.
-
-### 5.4 Test 4: Non-Repeating Schedule Handling
-
-**Purpose**: Verify non-repeating schedules don't reschedule next occurrence.
-
-**Steps**:
-1. Schedule one-time notification (no cron/clockTime) for 5 minutes in future
-2. Reboot device
-3. Wait 10 minutes (past scheduled time)
-4. Check boot logs
-5. Verify no next occurrence scheduled
-
-**Expected**:
-- ✅ Log shows "Missed alarm detected on boot"
-- ✅ Log does NOT show "Rescheduled next occurrence"
-- ✅ AlarmManager does NOT show new alarm
-
-**Pass Criteria**: Non-repeating schedules don't reschedule.
-
-### 5.5 Test 5: Boot Recovery Error Handling
-
-**Purpose**: Verify boot recovery handles errors gracefully.
-
-**Steps**:
-1. Manually corrupt database (insert invalid schedule)
-2. Reboot device
-3. Check boot logs
-
-**Expected**:
-- ✅ Invalid schedule skipped with warning
-- ✅ Boot recovery continues normally
-- ✅ Valid schedules still recovered
-- ✅ No crash or exception
-
-**Pass Criteria**: Errors handled gracefully, recovery continues.
+5. **Idempotency**
+   * Running twice should produce identical logs
 
 ---
 
 ## 6. Implementation Checklist
 
-- [ ] Update `BootReceiver.onReceive()` to set boot flag
-- [ ] Update `BootReceiver.onReceive()` to queue ReactivationManager
-- [ ] Remove all direct rescheduling logic from BootReceiver
-- [ ] Verify ReactivationManager detects BOOT scenario correctly
-- [ ] Update history recording to include missed alarm counts
-- [ ] Add data integrity checks
-- [ ] Add error handling
-- [ ] Test boot recovery missed detection
-- [ ] Test next occurrence rescheduling
-- [ ] Test future alarm rescheduling
-- [ ] Test non-repeating schedule handling
-- [ ] Test error handling
-- [ ] Verify no duplicate alarms
+### Mandatory
+
+* [ ] BootReceiver included
+* [ ] Manifest entry added
+* [ ] `runBootRecovery()` implemented
+* [ ] Scenario logged as `BOOT`
+* [ ] All alarms recreated
+* [ ] Timeout protection
+* [ ] No modifications to preferences or plugin settings
+
+### Optional
+
+* [ ] Additional telemetry for analytics
+* [ ] Optional debug toast for dev builds only
 
 ---
 
-## 7. Code References
+## 7. Expected Output Examples
 
-**Existing Code to Reuse**:
-- `BootReceiver.rescheduleNotifications()` - Line 38 (update existing)
-- `BootReceiver.calculateNextRunTime()` - Line 103 (already exists)
-- `NotifyReceiver.scheduleExactNotification()` - Line 92
-- `ScheduleDao.getEnabled()` - Line 298
-- `NotificationContentDao.getNotificationById()` - Line 69
+### Example 1 – Normal Boot (future alarms exist)
 
-**New Code to Create**:
-- `handleMissedAlarmOnBoot()` - Add to BootReceiver
-- `isRepeating()` - Add to BootReceiver (or reuse from ReactivationManager)
-- `calculateNextOccurrence()` - Add to BootReceiver (or reuse from ReactivationManager)
+```
+DNP-REACTIVATION: Starting boot recovery
+DNP-REACTIVATION: Loaded 2 schedules from DB
+DNP-REACTIVATION: Rescheduled alarm: daily_1764233911265 for 1764236120000
+DNP-REACTIVATION: Rescheduled alarm: daily_1764233465343 for 1764233700000
+DNP-REACTIVATION: Boot recovery complete: missed=0, rescheduled=2, errors=0
+```
+
+### Example 2 – Schedules present but some in past
+
+```
+Marked missed notification: daily_1764233300000
+Rescheduled alarm: daily_1764233300000 for next day
+```
+
+### Example 3 – No schedules
+
+```
+DNP-REACTIVATION: BOOT: No schedules found
+```
 
 ---
 
-## 8. Success Criteria Summary
+## 8. Status
 
-**Phase 3 is complete when:**
-
-1. ✅ Boot receiver detects missed alarms
-2. ✅ Missed alarms marked in database
-3. ✅ Next occurrence rescheduled for repeating schedules
-4. ✅ Future alarms rescheduled normally
-5. ✅ Boot recovery never crashes
-6. ✅ All tests pass
+| Item                 | Status                           |
+| -------------------- | -------------------------------- |
+| Directive            | **Complete**                     |
+| Implementation       | ☐ Pending / ✅ **Complete** (plugin v1.2+)      |
+| Emulator Test Script | Ready (`test-phase3.sh`)         |
+| Verification Doc     | Ready (`PHASE3-VERIFICATION.md`) |
 
 ---
 
-## Related Documentation
+## 9. Related Documentation
 
-- [Phase 1: Cold Start Recovery](./android-implementation-directive-phase1.md) - Prerequisite
-- [Phase 2: Force Stop Recovery](./android-implementation-directive-phase2.md) - Prerequisite
-- [Full Implementation Directive](./android-implementation-directive.md) - Complete scope
-- [Exploration Findings](./exploration-findings-initial.md) - Gap analysis
+- [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
+- [Plugin Requirements](./alarms/03-plugin-requirements.md) - Requirements this phase implements
+- [Platform Capability Reference](./alarms/01-platform-capability-reference.md) - OS-level facts
+- [Phase 1](./android-implementation-directive-phase1.md) - Prerequisite
+- [Phase 2](./android-implementation-directive-phase2.md) - Prerequisite
+- [Phase 3 Emulator Testing](./alarms/PHASE3-EMULATOR-TESTING.md) - Test procedures
+- [Phase 3 Verification](./alarms/PHASE3-VERIFICATION.md) - Verification report
 
 ---
 
-## Notes
-
-- **Prerequisites**: Phase 1 and Phase 2 must be complete before starting Phase 3
-- **Boot receiver timeout**: Android limits boot receiver execution to 10 seconds
-- **Comprehensive recovery**: Boot recovery handles both missed and future alarms
-- **Safety first**: All recovery operations are non-blocking and non-fatal
-- **Code reuse**: Consider extracting helper methods to shared utility class
-
+**Status**: Directive complete, ready for implementation  
+**Last Updated**: November 2025
diff --git a/test-apps/android-test-app/test-phase3.sh b/test-apps/android-test-app/test-phase3.sh
new file mode 100755
index 0000000..dc165a1
--- /dev/null
+++ b/test-apps/android-test-app/test-phase3.sh
@@ -0,0 +1,578 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ========================================
+# Phase 3 Testing Script – Boot Recovery
+# ========================================
+
+# --- Config -------------------------------------------------------------------
+
+APP_ID="com.timesafari.dailynotification"
+APK_PATH="./app/build/outputs/apk/debug/app-debug.apk"
+ADB_BIN="${ADB_BIN:-adb}"
+
+# Log tags / patterns (matched to actual ReactivationManager logs)
+REACTIVATION_TAG="DNP-REACTIVATION"
+SCENARIO_KEY="Detected scenario: "
+BOOT_SCENARIO_VALUE="BOOT"
+NONE_SCENARIO_VALUE="NONE"
+
+# ------------------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------------------
+
+section() {
+  echo
+  echo "========================================"
+  echo "$1"
+  echo "========================================"
+  echo
+}
+
+substep() {
+  echo "→ $1"
+}
+
+info() {
+  echo -e "ℹ️  $1"
+}
+
+ok() {
+  echo -e "✅ $1"
+}
+
+warn() {
+  echo -e "⚠️  $1"
+}
+
+error() {
+  echo -e "❌ $1"
+}
+
+pause() {
+  echo
+  read -rp "Press Enter when ready to continue..."
+  echo
+}
+
+ui_prompt() {
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "👆 UI ACTION REQUIRED"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo -e "$1"
+  echo
+  read -rp "Press Enter after completing the action above..."
+  echo
+}
+
+require_adb_device() {
+  section "Pre-Flight Checks"
+
+  if ! $ADB_BIN devices | awk 'NR>1 && $2=="device"{found=1} END{exit !found}'; then
+    error "No emulator/device in 'device' state. Start your emulator first."
+    exit 1
+  fi
+  ok "ADB device connected"
+
+  info "Checking emulator status..."
+  if ! $ADB_BIN shell getprop sys.boot_completed | grep -q "1"; then
+    info "Waiting for emulator to boot..."
+    $ADB_BIN wait-for-device
+    while [ "$($ADB_BIN shell getprop sys.boot_completed)" != "1" ]; do
+      sleep 2
+    done
+  fi
+  ok "Emulator is ready"
+}
+
+build_app() {
+  section "Building Test App"
+
+  substep "Step 1: Building debug APK..."
+  if ./gradlew :app:assembleDebug; then
+    ok "Build successful"
+  else
+    error "Build failed"
+    exit 1
+  fi
+
+  if [[ -f "$APK_PATH" ]]; then
+    ok "APK ready: $APK_PATH"
+  else
+    error "APK not found at $APK_PATH"
+    exit 1
+  fi
+}
+
+install_app() {
+  section "Installing App"
+
+  substep "Step 1: Uninstalling existing app (if present)..."
+  set +e
+  uninstall_output="$($ADB_BIN uninstall "$APP_ID" 2>&1)"
+  uninstall_status=$?
+  set -e
+
+  if [[ $uninstall_status -ne 0 ]]; then
+    if grep -q "DELETE_FAILED_INTERNAL_ERROR" <<<"$uninstall_output"; then
+      info "No existing app to uninstall (continuing)"
+    else
+      warn "Uninstall returned non-zero status: $uninstall_output (continuing anyway)"
+    fi
+  else
+    ok "Previous app uninstall succeeded"
+  fi
+
+  substep "Step 2: Installing new APK..."
+  if $ADB_BIN install -r "$APK_PATH"; then
+    ok "App installed successfully"
+  else
+    error "App installation failed"
+    exit 1
+  fi
+
+  substep "Step 3: Verifying installation..."
+  if $ADB_BIN shell pm list packages | grep -q "$APP_ID"; then
+    ok "App verified in package list"
+  else
+    error "App not found in package list"
+    exit 1
+  fi
+
+  info "Clearing logcat buffer..."
+  $ADB_BIN logcat -c
+  ok "Logs cleared"
+}
+
+launch_app() {
+  info "Launching app..."
+  $ADB_BIN shell am start -n "${APP_ID}/.MainActivity" >/dev/null 2>&1
+  sleep 3  # Give app time to load
+  ok "App launched"
+}
+
+clear_logs() {
+  info "Clearing logcat buffer..."
+  $ADB_BIN logcat -c
+  ok "Logs cleared"
+}
+
+show_alarms() {
+  info "Checking AlarmManager status..."
+  echo
+  $ADB_BIN shell dumpsys alarm | grep -A3 "$APP_ID" || true
+  echo
+}
+
+count_alarms() {
+  # Returns count of alarms for our app
+  $ADB_BIN shell dumpsys alarm | grep -c "$APP_ID" || echo "0"
+}
+
+reboot_emulator() {
+  info "Rebooting emulator..."
+  $ADB_BIN reboot
+  ok "Reboot initiated"
+  
+  info "Waiting for emulator to come back online..."
+  $ADB_BIN wait-for-device
+  while [ "$($ADB_BIN shell getprop sys.boot_completed)" != "1" ]; do
+    sleep 2
+  done
+  ok "Emulator boot completed"
+}
+
+get_recovery_logs() {
+  # Collect recent reactivation logs
+  $ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true
+}
+
+extract_field_from_logs() {
+  # Usage: extract_field_from_logs "<logs>" "<field_name>"
+  local logs="$1"
+  local field="$2"
+  # Looks for patterns like "field=NUMBER" and returns NUMBER (or 0)
+  local value
+  value="$(grep -oE "${field}=[0-9]+" <<<"$logs" | tail -n1 | sed "s/${field}=//" || true)"
+  if [[ -z "$value" ]]; then
+    echo "0"
+  else
+    echo "$value"
+  fi
+}
+
+extract_scenario_from_logs() {
+  local logs="$1"
+  local scen
+  # Looks for "Detected scenario: BOOT" or "Starting boot recovery" format
+  if echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
+    echo "$BOOT_SCENARIO_VALUE"
+  else
+    scen="$(grep -oE "${SCENARIO_KEY}[A-Z_]+" <<<"$logs" | tail -n1 | sed "s/${SCENARIO_KEY}//" || true)"
+    echo "$scen"
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# TEST 1 – Boot with Future Alarms
+# ------------------------------------------------------------------------------
+
+test1_boot_future_alarms() {
+  section "TEST 1: Boot with Future Alarms"
+
+  echo "Purpose: Verify alarms are recreated on boot when schedules have future run times."
+
+  pause
+
+  substep "Step 1: Launch app & check plugin status"
+  launch_app
+
+  ui_prompt "In the app UI, verify plugin status:\n\n  ⚙️ Plugin Settings: ✅ Configured\n  🔌 Native Fetcher: ✅ Configured\n\nIf either shows ❌ or 'Not configured', click 'Configure Plugin', wait until both are ✅, then press Enter."
+
+  ui_prompt "Now schedule at least one future notification (e.g., click 'Test Notification' to schedule for a few minutes in the future)."
+
+  substep "Step 2: Verify alarms are scheduled"
+  show_alarms
+  local before_count
+  before_count="$(count_alarms)"
+  info "Alarm count before reboot: $before_count"
+
+  if [[ "$before_count" -eq 0 ]]; then
+    warn "No alarms found before reboot; TEST 1 may not be meaningful."
+  fi
+
+  pause
+
+  substep "Step 3: Reboot emulator"
+  warn "The emulator will reboot now. This will take 30-60 seconds."
+  pause
+  reboot_emulator
+
+  substep "Step 4: Collect boot recovery logs"
+  info "Collecting recovery logs from boot..."
+  sleep 2  # Give recovery a moment to complete
+  local logs
+  logs="$(get_recovery_logs)"
+  echo "$logs"
+
+  local missed rescheduled verified errors scenario
+  missed="$(extract_field_from_logs "$logs" "missed")"
+  rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
+  verified="$(extract_field_from_logs "$logs" "verified")"
+  errors="$(extract_field_from_logs "$logs" "errors")"
+  scenario="$(extract_scenario_from_logs "$logs")"
+
+  echo
+  info "Parsed recovery summary:"
+  echo "  scenario   = ${scenario:-<none>}"
+  echo "  missed     = ${missed}"
+  echo "  rescheduled= ${rescheduled}"
+  echo "  verified   = ${verified}"
+  echo "  errors     = ${errors}"
+  echo
+
+  if [[ "$errors" -gt 0 ]]; then
+    error "Recovery reported errors>0 (errors=$errors)"
+  fi
+
+  substep "Step 5: Verify alarms were recreated"
+  show_alarms
+  local after_count
+  after_count="$(count_alarms)"
+  info "Alarm count after boot: $after_count"
+
+  if [[ "$scenario" == "$BOOT_SCENARIO_VALUE" && "$rescheduled" -gt 0 ]]; then
+    ok "TEST 1 PASSED: Boot recovery detected and alarms rescheduled (scenario=$scenario, rescheduled=$rescheduled)."
+  elif echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
+    if [[ "$rescheduled" -gt 0 ]]; then
+      ok "TEST 1 PASSED: Boot recovery ran and alarms rescheduled (rescheduled=$rescheduled)."
+    else
+      warn "TEST 1: Boot recovery ran but rescheduled=0. Check implementation or logs."
+    fi
+  else
+    warn "TEST 1: Boot recovery not clearly detected. Review logs and boot receiver implementation."
+    info "Scenario detected: ${scenario:-<none>}, rescheduled=$rescheduled"
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# TEST 2 – Boot with Past Alarms
+# ------------------------------------------------------------------------------
+
+test2_boot_past_alarms() {
+  section "TEST 2: Boot with Past Alarms"
+
+  echo "Purpose: Verify missed alarms are detected and next occurrence is scheduled on boot."
+
+  pause
+
+  substep "Step 1: Launch app & ensure plugin configured"
+  launch_app
+
+  ui_prompt "In the app UI, verify plugin status:\n\n  ⚙️ Plugin Settings: ✅ Configured\n  🔌 Native Fetcher: ✅ Configured\n\nIf needed, click 'Configure Plugin', then press Enter."
+
+  ui_prompt "Click 'Test Notification' to schedule a notification for 2 minutes in the future.\n\nAfter scheduling, we'll wait for the alarm time to pass, then reboot."
+
+  substep "Step 2: Wait for alarm time to pass"
+  info "Waiting 3 minutes for scheduled alarm time to pass..."
+  warn "You can manually advance system time if needed (requires root/emulator)"
+  sleep 180  # Wait 3 minutes
+
+  substep "Step 3: Verify alarm time has passed"
+  info "Alarm time should now be in the past"
+  show_alarms
+
+  pause
+
+  substep "Step 4: Reboot emulator"
+  warn "The emulator will reboot now. This will take 30-60 seconds."
+  pause
+  reboot_emulator
+
+  substep "Step 5: Collect boot recovery logs"
+  info "Collecting recovery logs from boot..."
+  sleep 2
+  local logs
+  logs="$(get_recovery_logs)"
+  echo "$logs"
+
+  local missed rescheduled verified errors scenario
+  missed="$(extract_field_from_logs "$logs" "missed")"
+  rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
+  verified="$(extract_field_from_logs "$logs" "verified")"
+  errors="$(extract_field_from_logs "$logs" "errors")"
+  scenario="$(extract_scenario_from_logs "$logs")"
+
+  echo
+  info "Parsed recovery summary:"
+  echo "  scenario   = ${scenario:-<none>}"
+  echo "  missed     = ${missed}"
+  echo "  rescheduled= ${rescheduled}"
+  echo "  verified   = ${verified}"
+  echo "  errors     = ${errors}"
+  echo
+
+  if [[ "$errors" -gt 0 ]]; then
+    error "Recovery reported errors>0 (errors=$errors)"
+  fi
+
+  if [[ "$missed" -ge 1 && "$rescheduled" -ge 1 ]]; then
+    ok "TEST 2 PASSED: Past alarms detected and next occurrence scheduled (missed=$missed, rescheduled=$rescheduled)."
+  elif [[ "$missed" -ge 1 ]]; then
+    warn "TEST 2: Past alarms detected (missed=$missed) but rescheduled=$rescheduled. Check reschedule logic."
+  else
+    warn "TEST 2: No missed alarms detected. Verify alarm time actually passed before reboot."
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# TEST 3 – Boot with No Schedules
+# ------------------------------------------------------------------------------
+
+test3_boot_no_schedules() {
+  section "TEST 3: Boot with No Schedules"
+
+  echo "Purpose: Verify boot recovery handles empty database gracefully."
+
+  pause
+
+  substep "Step 1: Uninstall app to clear DB/state"
+  set +e
+  $ADB_BIN uninstall "$APP_ID" >/dev/null 2>&1
+  set -e
+  ok "App uninstalled (state cleared)"
+
+  substep "Step 2: Reinstall app"
+  if $ADB_BIN install -r "$APK_PATH"; then
+    ok "App installed"
+  else
+    error "Reinstall failed"
+    exit 1
+  fi
+
+  info "Clearing logcat..."
+  $ADB_BIN logcat -c
+  ok "Logs cleared"
+
+  pause
+
+  substep "Step 3: Reboot emulator WITHOUT scheduling anything"
+  warn "Do NOT schedule any notifications. The app should have no schedules in the database."
+  warn "The emulator will reboot now. This will take 30-60 seconds."
+  pause
+  reboot_emulator
+
+  substep "Step 4: Collect boot recovery logs"
+  info "Collecting recovery logs from boot..."
+  sleep 2
+  local logs
+  logs="$($ADB_BIN logcat -d | grep "$REACTIVATION_TAG" || true)"
+  echo "$logs"
+
+  local scenario rescheduled missed
+  scenario="$(extract_scenario_from_logs "$logs")"
+  rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
+  missed="$(extract_field_from_logs "$logs" "missed")"
+
+  echo
+  info "Parsed recovery summary:"
+  echo "  scenario   = ${scenario:-<none>}"
+  echo "  rescheduled= ${rescheduled}"
+  echo "  missed    = ${missed}"
+  echo
+
+  if [[ -z "$logs" ]]; then
+    ok "TEST 3 PASSED: No recovery logs when there are no schedules (safe behavior)."
+    return
+  fi
+
+  if echo "$logs" | grep -qiE "No schedules found|No schedules present"; then
+    ok "TEST 3 PASSED: Explicit 'No schedules found' message logged with no rescheduling."
+  elif [[ "$scenario" == "$NONE_SCENARIO_VALUE" && "$rescheduled" -eq 0 ]]; then
+    ok "TEST 3 PASSED: NONE scenario detected with no rescheduling."
+  elif [[ "$rescheduled" -gt 0 ]]; then
+    warn "TEST 3: rescheduled>0 on first launch / empty DB. Check that boot recovery isn't misfiring."
+  else
+    info "TEST 3: Logs present but no rescheduling; review scenario handling to ensure it's explicit about NONE / NO_SCHEDULES."
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# TEST 4 – Silent Boot Recovery (App Never Opened)
+# ------------------------------------------------------------------------------
+
+test4_silent_boot_recovery() {
+  section "TEST 4: Silent Boot Recovery (App Never Opened)"
+
+  echo "Purpose: Verify boot recovery occurs even when the app is never opened after reboot."
+
+  pause
+
+  substep "Step 1: Launch app & ensure plugin configured"
+  launch_app
+
+  ui_prompt "In the app UI, verify plugin status:\n\n  ⚙️ Plugin Settings: ✅ Configured\n  🔌 Native Fetcher: ✅ Configured\n\nIf needed, click 'Configure Plugin', then press Enter."
+
+  ui_prompt "Click 'Test Notification' to schedule a notification for a few minutes in the future."
+
+  substep "Step 2: Verify alarms are scheduled"
+  show_alarms
+  local before_count
+  before_count="$(count_alarms)"
+  info "Alarm count before reboot: $before_count"
+
+  if [[ "$before_count" -eq 0 ]]; then
+    warn "No alarms found; TEST 4 may not be meaningful."
+  fi
+
+  pause
+
+  substep "Step 3: Reboot emulator (DO NOT open app after reboot)"
+  warn "IMPORTANT: After reboot, DO NOT open the app. Boot recovery should run silently."
+  warn "The emulator will reboot now. This will take 30-60 seconds."
+  pause
+  reboot_emulator
+
+  substep "Step 4: Collect boot recovery logs (without opening app)"
+  info "Collecting recovery logs from boot (app was NOT opened)..."
+  sleep 2
+  local logs
+  logs="$(get_recovery_logs)"
+  echo "$logs"
+
+  local missed rescheduled verified errors scenario
+  missed="$(extract_field_from_logs "$logs" "missed")"
+  rescheduled="$(extract_field_from_logs "$logs" "rescheduled")"
+  verified="$(extract_field_from_logs "$logs" "verified")"
+  errors="$(extract_field_from_logs "$logs" "errors")"
+  scenario="$(extract_scenario_from_logs "$logs")"
+
+  echo
+  info "Parsed recovery summary:"
+  echo "  scenario   = ${scenario:-<none>}"
+  echo "  missed     = ${missed}"
+  echo "  rescheduled= ${rescheduled}"
+  echo "  verified   = ${verified}"
+  echo "  errors     = ${errors}"
+  echo
+
+  substep "Step 5: Verify alarms were recreated (without opening app)"
+  show_alarms
+  local after_count
+  after_count="$(count_alarms)"
+  info "Alarm count after boot (app never opened): $after_count"
+
+  if [[ "$after_count" -gt 0 && "$rescheduled" -gt 0 ]]; then
+    ok "TEST 4 PASSED: Boot recovery occurred silently and alarms were recreated (rescheduled=$rescheduled) without app launch."
+  elif [[ "$rescheduled" -gt 0 ]]; then
+    ok "TEST 4 PASSED: Boot recovery occurred silently (rescheduled=$rescheduled), but alarm count check unclear."
+  elif echo "$logs" | grep -qi "Starting boot recovery\|boot recovery"; then
+    warn "TEST 4: Boot recovery ran but alarms may not have been recreated. Check logs and implementation."
+  else
+    warn "TEST 4: Boot recovery not detected. Verify boot receiver is registered and has BOOT_COMPLETED permission."
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# Main
+# ------------------------------------------------------------------------------
+
+main() {
+  echo
+  echo "========================================"
+  echo "Phase 3 Testing Script – Boot Recovery"
+  echo "========================================"
+  echo
+  echo "This script will guide you through all Phase 3 tests."
+  echo "You'll be prompted when UI interaction is needed."
+  echo
+  echo "⚠️  WARNING: This script will reboot the emulator multiple times."
+  echo "    Each reboot takes 30-60 seconds."
+  echo
+
+  pause
+
+  require_adb_device
+  build_app
+  install_app
+
+  test1_boot_future_alarms
+  pause
+
+  test2_boot_past_alarms
+  pause
+
+  test3_boot_no_schedules
+  pause
+
+  test4_silent_boot_recovery
+
+  section "Testing Complete"
+
+  echo "Test Results Summary (see logs above for details):"
+  echo
+  echo "TEST 1: Boot with Future Alarms"
+  echo "  - Check logs for scenario=$BOOT_SCENARIO_VALUE and rescheduled>0"
+  echo
+  echo "TEST 2: Boot with Past Alarms"
+  echo "  - Check that missed>=1 and rescheduled>=1"
+  echo
+  echo "TEST 3: Boot with No Schedules"
+  echo "  - Check that no recovery runs, or NONE scenario is logged with rescheduled=0"
+  echo
+  echo "TEST 4: Silent Boot Recovery"
+  echo "  - Check that boot recovery occurred and alarms were recreated without app launch"
+  echo
+
+  ok "Phase 3 testing script complete!"
+  echo
+  echo "Next steps:"
+  echo "  - Review logs above"
+  echo "  - Capture snippets into PHASE3-EMULATOR-TESTING.md"
+  echo "  - Update PHASE3-VERIFICATION.md and unified directive status matrix"
+  echo
+}
+
+main "$@"
+