chore: directive activation guide

docs/alarms/ACTIVATION-GUIDE.md

@@ -0,0 +1,319 @@
+# Activation Guide: How to Use the Alarm Directive System
+
+**Author**: Matthew Raymer  
+**Date**: November 2025  
+**Status**: Activation Guide  
+**Version**: 1.0.0
+
+## Purpose
+
+This guide explains how to **activate and use** the unified alarm directive system for implementation work. It provides step-by-step instructions for developers to follow the documentation workflow.
+
+---
+
+## Prerequisites Check
+
+**Before starting any implementation work**, verify these conditions are met:
+
+### ✅ Documentation Status
+
+Check [Unified Directive §11 - Status Matrix](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix):
+
+- [x] **Doc A** (Platform Facts) - ✅ Drafted, ✅ Cleaned, ✅ In Use
+- [x] **Doc B** (Exploration) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready for testing)
+- [x] **Doc C** (Requirements) - ✅ Drafted, ✅ Cleaned, ✅ In Use
+- [x] **Phase 1** (Cold Start) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready to implement)
+- [x] **Phase 2** (Force Stop) - ✅ Drafted, ✅ Cleaned, ☐ In Use (prerequisite: Phase 1)
+- [x] **Phase 3** (Boot Recovery) - ✅ Drafted, ✅ Cleaned, ☐ In Use (prerequisites: Phase 1 & 2)
+
+**Status**: ✅ **All prerequisites met** - Ready to begin Phase 1 implementation
+
+---
+
+## Activation Workflow
+
+### Step 1: Choose Your Starting Point
+
+**For New Implementation Work**:
+- Start with **Phase 1** (Cold Start Recovery) - See [Phase 1 Directive](../android-implementation-directive-phase1.md)
+- This is the minimal viable recovery that unblocks other work
+
+**For Testing/Exploration**:
+- Start with **Doc B** (Exploration) - See [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
+- Fill in test scenarios as you validate current behavior
+
+**For Understanding Requirements**:
+- Start with **Doc C** (Requirements) - See [Plugin Requirements](./03-plugin-requirements.md)
+- Review guarantees, limitations, and API contract
+
+---
+
+## Implementation Activation: Phase 1
+
+### 1.1 Read the Phase Directive
+
+**Start Here**: [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md)
+
+**Key Sections to Read**:
+1. **Purpose** (§0) - Understand what Phase 1 implements
+2. **Acceptance Criteria** (§1) - Definition of done
+3. **Implementation** (§2) - Step-by-step code changes
+4. **Testing Requirements** (§8) - How to validate
+
+### 1.2 Reference Supporting Documents
+
+**During Implementation, Keep These Open**:
+
+1. **Doc A** - [Platform Capability Reference](./01-platform-capability-reference.md)
+   - Use for: Understanding OS behavior, API constraints, permissions
+   - Example: "Can I rely on AlarmManager to persist alarms?" → See Doc A §2.1.1
+
+2. **Doc C** - [Plugin Requirements](./03-plugin-requirements.md)
+   - Use for: Understanding what the plugin MUST guarantee
+   - Example: "What should happen on cold start?" → See Doc C §3.1.2
+
+3. **Doc B** - [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
+   - Use for: Test scenarios to validate your implementation
+   - Example: "How do I test cold start recovery?" → See Doc B Test 4
+
+### 1.3 Follow the Implementation Steps
+
+**Phase 1 Implementation Checklist** (from Phase 1 directive):
+
+- [ ] Create `ReactivationManager.kt` file
+- [ ] Implement `detectMissedNotifications()` method
+- [ ] Implement `markMissedNotifications()` method
+- [ ] Implement `verifyAndRescheduleFutureAlarms()` method
+- [ ] Integrate into `DailyNotificationPlugin.load()`
+- [ ] Add logging and error handling
+- [ ] Write unit tests
+- [ ] Test on physical device
+
+**Reference**: See [Phase 1 §2 - Implementation](../android-implementation-directive-phase1.md#2-implementation)
+
+---
+
+## Testing Activation: Doc B
+
+### 2.1 Execute Test Scenarios
+
+**Start Here**: [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md)
+
+**Workflow**:
+1. Choose a test scenario (e.g., "Test 4: Device Reboot")
+2. Follow the **Steps** column exactly
+3. Fill in **Actual Result** column with observed behavior
+4. Mark **Result** column (Pass/Fail)
+5. Add **Notes** for any unexpected behavior
+
+### 2.2 Update Test Results
+
+**As You Test**:
+- Update checkboxes (☐ → ✅) when tests pass
+- Document actual vs expected differences
+- Add findings to "Findings & Gaps" section (§4)
+
+**Example**:
+```markdown
+| Step | Action | Expected | Actual Result | Notes | Result |
+| ---- | ------ | -------- | ------------- | ----- | ------ |
+| 5 | Launch app | Plugin detects missed alarm | ✅ Missed alarm detected | Logs show "DNP-REACTIVATION: Detected 1 missed alarm" | ✅ Pass |
+```
+
+---
+
+## Documentation Maintenance During Work
+
+### 3.1 Update Status Matrix
+
+**When You Complete Work**:
+
+1. Open [Unified Directive §11](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix)
+2. Update the relevant row:
+   - Mark "In Use?" = ✅ when implementation is deployed
+   - Update "Notes" with completion status
+
+**Example**:
+```markdown
+| P1  | `../android-implementation-directive-phase1.md` | Impl – Cold start | ✅ | ✅ | ✅ | **Implemented and deployed** - See commit abc123 |
+```
+
+### 3.2 Update Doc B with Test Results
+
+**After Testing**:
+- Fill in actual results in test matrices
+- Document any gaps or unexpected behavior
+- Update severity classifications if issues found
+
+### 3.3 Follow Change Control Rules
+
+**When Modifying Docs A, B, or C**:
+
+1. **Update version header** in the document
+2. **Update status matrix** (Section 11) in unified directive
+3. **Use commit message tag**: `[ALARM-DOCS]` prefix
+4. **Notify in CHANGELOG** if JS/TS-visible behavior changes
+
+**Reference**: See [Unified Directive §10 - Change Control](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules)
+
+---
+
+## Workflow Diagram
+
+```
+┌─────────────────────────────────────────┐
+│ 1. Read Phase Directive (P1/P2/P3)     │
+│    Understand acceptance criteria       │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│ 2. Reference Doc A (Platform Facts)     │
+│    Understand OS constraints            │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│ 3. Reference Doc C (Requirements)      │
+│    Understand plugin guarantees         │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│ 4. Implement Code (Phase Directive)     │
+│    Follow step-by-step instructions     │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│ 5. Test (Doc B Scenarios)               │
+│    Execute test matrices                │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│ 6. Update Documentation                 │
+│    - Status matrix                      │
+│    - Test results (Doc B)               │
+│    - Version numbers                    │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Common Activation Scenarios
+
+### Scenario 1: Starting Phase 1 Implementation
+
+**Steps**:
+1. ✅ Verify prerequisites (all docs exist - **DONE**)
+2. Read [Phase 1 Directive](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria)
+3. Read [Doc C §3.1.2](./03-plugin-requirements.md#312-app-cold-start) (Cold Start Requirements)
+4. Read [Doc A §2.1.4](./01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart) (Platform Capability)
+5. Follow [Phase 1 §2](../android-implementation-directive-phase1.md#2-implementation) (Implementation Steps)
+6. Test using [Doc B Test 4](./02-plugin-behavior-exploration.md#test-4-device-reboot) (Cold Start Scenario)
+7. Update status matrix when complete
+
+### Scenario 2: Testing Current Behavior
+
+**Steps**:
+1. Open [Doc B](./02-plugin-behavior-exploration.md)
+2. Choose a test scenario (e.g., "Test 2: Swipe from Recents")
+3. Follow the **Steps** column
+4. Fill in **Actual Result** column
+5. Compare with **Expected (OS)** and **Expected (Plugin)** columns
+6. Document findings in **Notes** column
+7. Update "Findings & Gaps" section if issues found
+
+### Scenario 3: Understanding a Requirement
+
+**Steps**:
+1. Open [Doc C](./03-plugin-requirements.md)
+2. Find the relevant section (e.g., "Missed Alarm Handling" §4)
+3. Read the requirement and acceptance criteria
+4. Follow cross-references to:
+   - **Doc A** for platform constraints
+   - **Doc B** for test scenarios
+   - **Phase docs** for implementation details
+
+### Scenario 4: Adding iOS Support
+
+**Steps**:
+1. ✅ Verify iOS parity milestone conditions (see [Unified Directive §9](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps))
+2. Ensure Doc A has iOS matrix complete
+3. Ensure Doc C has iOS guarantees defined
+4. Create iOS implementation following Android phase patterns
+5. Test using Doc B iOS scenarios
+6. Update status matrix
+
+---
+
+## Blocking Rules
+
+**⚠️ DO NOT PROCEED** if:
+
+1. **Prerequisites not met** - See [Unified Directive §12](./000-UNIFIED-ALARM-DIRECTIVE.md#12-single-instruction-for-team)
+   - Doc A, B, C must exist
+   - Status matrix must be updated
+   - Deprecated files must be marked
+
+2. **iOS work without parity milestone** - See [Unified Directive §9](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps)
+   - Doc A must have iOS matrix
+   - Doc C must define iOS guarantees
+   - Phase docs must not assume Android-only
+
+3. **Phase 2/3 without Phase 1** - See Phase directives
+   - Phase 2 requires Phase 1 complete
+   - Phase 3 requires Phase 1 & 2 complete
+
+---
+
+## Quick Reference
+
+### Document Roles
+
+| Doc | Purpose | When to Use |
+|-----|---------|-------------|
+| **Unified Directive** | Master coordination | Understanding system structure, change control |
+| **Doc A** | Platform facts | Understanding OS behavior, API constraints |
+| **Doc B** | Test scenarios | Testing, exploration, validation |
+| **Doc C** | Requirements | Understanding guarantees, API contract |
+| **Phase 1-3** | Implementation | Writing code, step-by-step instructions |
+
+### Key Sections
+
+- **Status Matrix**: [Unified Directive §11](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix)
+- **Change Control**: [Unified Directive §10](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules)
+- **Phase 1 Start**: [Phase 1 Directive](../android-implementation-directive-phase1.md)
+- **Test Scenarios**: [Doc B Test Matrices](./02-plugin-behavior-exploration.md#12-behavior-testing-matrix)
+- **Requirements**: [Doc C Guarantees](./03-plugin-requirements.md#1-plugin-behavior-guarantees--limitations)
+
+---
+
+## Next Steps
+
+**You're Ready To**:
+
+1. ✅ **Start Phase 1 Implementation** - All prerequisites met
+2. ✅ **Begin Testing** - Doc B scenarios ready
+3. ✅ **Reference Documentation** - All docs complete and cross-referenced
+
+**Recommended First Action**:
+- Read [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria)
+- Then proceed to §2 (Implementation) when ready to code
+
+---
+
+## Related Documentation
+
+- [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document
+- [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) - Start here for implementation
+- [Plugin Requirements](./03-plugin-requirements.md) - What the plugin must guarantee
+- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts
+- [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) - Test scenarios
+
+---
+
+**Status**: Ready for activation  
+**Last Updated**: November 2025
+