daily-notification-plugin/docs/alarms/ACTIVATION-GUIDE.md

# 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 (drives emulator test harness)
- [x] **Doc C** (Requirements) - ✅ Drafted, ✅ Cleaned, ✅ In Use
- [x] **Phase 1** (Cold Start) - ✅ Drafted, ✅ Cleaned, ✅ In Use (implemented in plugin v1.1.0, emulator-verified via `test-phase1.sh`)
- [x] **Phase 2** (Force Stop) - ✅ Drafted, ✅ Implemented, ☐ Emulator-tested (`test-phase2.sh` + `PHASE2-EMULATOR-TESTING.md`)
- [x] **Phase 3** (Boot Recovery) - ✅ Drafted, ✅ Implemented, ☐ Emulator-tested (`test-phase3.sh` + `PHASE3-EMULATOR-TESTING.md`)

**Status**: ✅ **All prerequisites met** – Phase 1 implementation is complete and emulator-verified; Phase 2 and Phase 3 are implemented and ready for emulator testing; ready for broader device testing and rollout.

---

## 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