trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

chore: synch this plan

Browse Source
This commit is contained in:
Matthew Raymer
2025-11-25 08:04:53 +00:00
parent 6aa9140f67
commit afbc98f7dc
5 changed files with 2629 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

483
docs/alarms/000-UNIFIED-ALARM-DIRECTIVE.md Normal file
View File

@@ -0,0 +1,483 @@
# 🔧 UNIFIED DIRECTIVE: Alarm / Schedule / Notification Documentation & Implementation Stack
**Author:** Matthew Raymer
**Status:** Active – Master Coordination Directive
**Scope:** Android & iOS, Capacitor plugin, alarms/schedules/notifications
**Version:** 1.0.0
**Last Updated:** November 2025
---
## 0. Purpose
Unify all existing alarm/notification documents into a **coherent, layered system** that:
1. **Eliminates duplication** (especially Android alarm behavior repeated across docs)
2. **Separates concerns** into:
* Platform facts
* Exploration/testing
* Plugin requirements
* Implementation directives (Phases 1–3)
3. **Provides iOS parity** to the existing Android-heavy material
4. **Maps OS-level capabilities → plugin guarantees → JS/TS API contract**
5. **Standardizes testing** into executable matrices for exploration and regression
6. **Connects exploration → design → implementation** and tracks status across that pipeline
**This directive is the top of the stack.** If any lower-level document conflicts with this one, **this directive wins** unless explicitly noted.
**⚠️ ENFORCEMENT RULE**: No new alarm-related documentation may be created outside Documents A, B, C, or P1–P3. All future changes must modify these documents, not create additional standalone files.
---
## 1. Inputs (Existing Documents)
### 1.1 Platform & Reference Layer
* `platform-capability-reference.md` – OS-level facts (Android & iOS)
* `android-alarm-persistence-directive.md` – Android abilities & limitations, engineering-grade
### 1.2 Exploration & Findings
* `plugin-behavior-exploration-template.md` – Structured template for exploring behavior
* `explore-alarm-behavior-directive.md` – Exploration directive for behavior & persistence
* `exploration-findings-initial.md` – Initial code-level discovery
### 1.3 Requirements & Implementation
* `plugin-requirements-implementation.md` – Plugin behavior rules & guarantees
* `android-implementation-directive.md` – Umbrella Android implementation overview (app launch recovery, missed alarms, force stop, boot)
* Phase directives (normative):
* `android-implementation-directive-phase1.md` – Cold start recovery (minimal viable)
* `android-implementation-directive-phase2.md` – Force stop detection & recovery
* `android-implementation-directive-phase3.md` – Boot receiver missed alarm handling
### 1.4 Improvement Directive
* `improve-alarm-directives.md` – Current plan for structural and content improvements across the stack
---
## 2. Target Structure (What We're Building)
We standardize around **three primary doc roles**, plus implementation phases:
### A. **Platform Reference (Document A)**
**Goal:** Single, stable, normative OS facts.
* Merge:
* Android section from `android-alarm-persistence-directive.md`
* Android & iOS matrices from `platform-capability-reference.md`
* Content rules:
* NO plugin-specific rules
* Just: "what Android/iOS can and cannot do"
* Use matrices & short prose only
* Label each item as:
* **OS-guaranteed**, **Plugin-required**, or **Forbidden** (where relevant)
* Output path (recommended):
`docs/alarms/01-platform-capability-reference.md`
### B. **Plugin Behavior Exploration (Document B)**
**Goal:** Executable exploration & testing spec.
* Baseline: `plugin-behavior-exploration-template.md` + `explore-alarm-behavior-directive.md`
* Remove duplicated platform explanations (refer to Document A instead)
* For each scenario (swipe, reboot, force stop, etc.):
* Link to source files & functions (line or section refs)
* Provide **Expected (OS)** & **Expected (Plugin)** from Docs A + C
* Add columns for **Actual Result** and **Notes** (checkbox matrix)
* Output path:
`docs/alarms/02-plugin-behavior-exploration.md`
### C. **Plugin Requirements & Implementation Rules (Document C)**
**Goal:** What the plugin MUST guarantee & how.
* Baseline: `plugin-requirements-implementation.md` + `improve-alarm-directives.md`
* Must include:
1. **Plugin Behavior Guarantees & Limitations** by platform (table)
2. **Persistence Requirements** (fields, storage, validation, failure modes)
3. **Recovery Requirements**:
* Boot (Android)
* Cold start
* Warm start
* Force stop (Android)
* User-tap recovery
4. **Missed alarm handling contract** (definition, triggers, required actions)
5. **JS/TS API Contract**:
* What JS devs can rely on
* Platform caveats (e.g., Force Stop, iOS background limits)
6. **Unsupported features / limitations** clearly called out
* Output path:
`docs/alarms/03-plugin-requirements.md`
### D. **Implementation Directives (Phase 1–3)**
Already exist; this directive standardizes their role:
* **Phase docs are normative for code.**
If they conflict with Document C, update the phase docs and then C.
**⚠️ STRUCTURE FREEZE**: The structure defined in this directive is FINAL. No new document categories may be introduced without updating this master directive first.
---
## 3. Ownership, Versioning & Status
### 3.1 Ownership
**Assignable Ownership** (replace abstract roles with concrete owners):
| Layer | Owner | Responsibility |
| ---------------------- | ------------------- | ------------------------------------------------- |
| Doc A – Platform Facts | Engineering Lead | Long-lived reference, rare changes |
| Doc B – Exploration | QA / Testing Lead | Living document, updated with test results |
| Doc C – Requirements | Plugin Architect | Versioned with plugin, defines guarantees |
| Phases P1–P3 | Implementation Lead | Normative code specs, tied to Doc C requirements |
**Note**: If owners are not yet assigned, use role names above as placeholders until assignment.
### 3.2 Versioning Rules
* Any change that alters **JS/TS-visible behavior** → bump plugin **MINOR** at least
* Any change that breaks prior guarantees or adds new required migration → **MAJOR bump**
* Each doc should include:
* `Version: x.y.z`
* `Last Synced With Plugin Version: vX.Y.Z`
### 3.3 Status Matrix
Add this table to the end of *this* directive and keep it updated:
| Doc | Path | Role | Drafted? | Cleaned? | In Use? |
| --- | ------------------------------------- | ----------------- | -------- | -------- | ------- |
| A | `01-platform-capability-reference.md` | Platform facts | ☐ | ☐ | ☐ |
| B | `02-plugin-behavior-exploration.md` | Exploration | ☐ | ☐ | ☐ |
| C | `03-plugin-requirements.md` | Requirements | ☐ | ☐ | ☐ |
| P1 | `android-implementation-phase1.md` | Impl – Cold start | ✅ | ☐ | ☐ |
| P2 | `android-implementation-phase2.md` | Impl – Force stop | ✅ | ☐ | ☐ |
| P3 | `android-implementation-phase3.md` | Impl – Boot | ✅ | ☐ | ☐ |
(You can edit this directly in git as you go.)
---
## 4. Work Plan – "Do All of the Above"
This is the **concrete to-do list** that satisfies:
* Consolidation
* Versioning & ownership
* Status tracking
* Single-source master structure
* Next-phase readiness
* Improvements from `improve-alarm-directives.md`
### Step 1 – Normalize Platform Reference (Doc A)
1. Start from `platform-capability-reference.md` + `android-alarm-persistence-directive.md`
2. Merge into a single doc:
* Android matrix
* iOS matrix
* Core principles (no plugin rules)
3. Ensure each line is labeled:
* **OS-guaranteed**, **Plugin-required**, or **Forbidden** (where relevant)
4. Mark the old Android alarm persistence doc as:
* **Deprecated in favor of Doc A** (leave file but add a banner)
### Step 2 – Rewrite Exploration (Doc B)
1. Use `plugin-behavior-exploration-template.md` as the skeleton
2. Integrate concrete scenario descriptions and code paths from `explore-alarm-behavior-directive.md`
3. For **each scenario**:
* App swipe, OS kill, reboot, force stop, cold start, warm start, notification tap:
* Add row: Step-by-step actions + Expected (OS) + Expected (Plugin) + Actual + Notes
4. Remove any explanation that duplicates Doc A; replace with "See Doc A, section X"
### Step 3 – Rewrite Plugin Requirements (Doc C)
1. Start from `plugin-requirements-implementation.md` & improvement goals
2. Add / enforce sections:
* **Plugin Behavior Guarantees & Limitations**
* **Persistence Spec** (fields, mandatory vs optional)
* **Recovery Points** (boot, cold, warm, force stop, user tap)
* **Missed Alarm Contract**
* **JS/TS API Contract**
* **Unsupported / impossible guarantees** (Force Stop, iOS background, etc.)
3. Everywhere it relies on platform behavior:
* Link back to Doc A using short cross-reference ("See A §2.1")
4. Add a **"Traceability"** mini-table:
* Row per behavior → Platform fact in A → Tested scenario in B → Implemented in Phase N
### Step 4 – Align Implementation Directives with Doc C
1. Treat Phase docs as **canonical code spec**: P1, P2, P3
2. For each behavior required in Doc C:
* Identify which Phase implements it (or will implement it)
3. Update:
* `android-implementation-directive.md` to be explicitly **descriptive/integrative**, not normative, pointing to Phases 1–3 & Doc C
* Ensure scenario model, alarm existence checks, and boot handling match the **corrected model** already defined in Phase 2 & 3
4. Add acceptance criteria per phase that directly reference:
* Requirements in Doc C
* Platform constraints in Doc A
5. **Phase 1–3 must REMOVE**:
* Any scenario logic (moved to Doc C)
* Any platform behavioral claims (moved to Doc A)
* Any recovery responsibilities not assigned to that phase
### Step 5 – Versioning & Status
1. At the top of Docs A, B, C, and each Phase doc, add:
* `Version`, `Last Updated`, `Sync'd with Plugin vX.Y.Z`
2. Maintain the status matrix (Section 3.3) as the **single source of truth** for doc maturity
3. When a Phase is fully implemented and deployed:
* Mark "In Use?" = ✅
* Add link to code tags/commit hash
### Step 6 – Readiness Check for Next Work Phase
Before starting any *new* implementation work on alarms / schedules:
1. **Confirm:**
* Doc A exists and is stable enough (no "TODO" in core matrices)
* Doc B has at least the base scenarios scaffolded
* Doc C clearly defines:
* What we guarantee on each platform
* What we cannot do (e.g., Force Stop auto-resume)
2. Only then:
* Modify or extend Phase 1–3
* Or add new phases (e.g., warm-start optimizations, iOS parity work)
---
## 5. Acceptance Criteria for THIS Directive (Revised and Final)
This directive is complete **ONLY** when:
1. **Doc A exists, is referenced, and no other doc contains platform facts**
* File exists: `docs/alarms/01-platform-capability-reference.md`
* All old platform docs marked as deprecated with banner
* No platform facts duplicated in other docs
2. **Doc B contains**:
* At least 6 scenarios (swipe, reboot, force stop, cold start, warm start, notification tap)
* Expected OS vs Plugin behavior columns
* Space for Actual Result and Notes
* Links to source files/functions
3. **Doc C contains**:
* Guarantees by platform (table format)
* Recovery matrix (boot, cold, warm, force stop, user tap)
* JS/TS API contract
* Unsupported behaviors clearly called out
4. **Phase docs**:
* Contain NO duplication of Doc A (platform facts)
* Reference Doc C explicitly (requirements)
* Have acceptance criteria tied to Doc C requirements
5. **Deprecated files have**:
* Banner: "⚠️ **DEPRECATED**: Superseded by [000-UNIFIED-ALARM-DIRECTIVE](./000-UNIFIED-ALARM-DIRECTIVE.md)"
* Link to replacement document
6. **Status matrix fields are no longer empty** (Section 10)
* All docs marked as Drafted at minimum
---
## 6. Document Relationships & Cross-References
### 6.1 Reference Flow
```
Unified Directive (this doc)
↓
├─→ Doc A (Platform Reference)
│ └─→ Referenced by: B, C, P1-P3
│
├─→ Doc B (Exploration)
│ └─→ References: A (platform facts), C (expected behavior)
│ └─→ Feeds into: P1-P3 (test results inform implementation)
│
├─→ Doc C (Requirements)
│ └─→ References: A (platform constraints)
│ └─→ Referenced by: P1-P3 (implementation must satisfy)
│
└─→ P1-P3 (Implementation)
└─→ References: A (platform facts), C (requirements)
└─→ Validated by: B (exploration results)
```
### 6.2 Cross-Reference Format
When referencing between documents, use this format:
* **Doc A**: `[Platform Reference §2.1](../alarms/01-platform-capability-reference.md#21-android-alarm-persistence)`
* **Doc B**: `[Exploration §3.2](../alarms/02-plugin-behavior-exploration.md#32-cold-start-scenario)`
* **Doc C**: `[Requirements §4.3](../alarms/03-plugin-requirements.md#43-recovery-requirements)`
* **Phase docs**: `[Phase 1 §2.3](../android-implementation-directive-phase1.md#23-cold-start-recovery)`
---
## 7. Canonical Source of Truth Rules
### 7.1 Scenario Detection
**Only ReactivationManager.kt** performs scenario detection. No other component (BootReceiver, DailyNotificationPlugin, etc.) implements detection logic.
**Corrected Scenario Model** (from Phase 2):
```kotlin
enum class RecoveryScenario {
COLD_START, // Process killed, alarms may or may not exist
FORCE_STOP, // Alarms cleared, DB still populated
BOOT, // Device reboot
NONE // No recovery required (warm resume or first launch)
}
```
### 7.2 Recovery Logic
**Only ReactivationManager.kt** implements recovery logic. BootReceiver only sets flags and queues ReactivationManager.
### 7.3 Platform Facts
**Only Doc A** contains platform facts. All other docs reference Doc A, never duplicate platform behavior.
### 7.4 Requirements
**Only Doc C** defines plugin requirements. Phase docs implement Doc C requirements.
---
## 8. Conflict Resolution
If conflicts arise between documents:
1. **This directive (000)** wins for structure and organization
2. **Doc A** wins for platform facts
3. **Doc C** wins for requirements
4. **Phase docs (P1-P3)** win for implementation details
5. **Doc B** is observational (actual test results) and may reveal conflicts
When a conflict is found:
1. Document it in this section
2. Resolve by updating the lower-priority document
3. Update the status matrix
---
## 9. Next Steps
### ⚠️ Time-Based Triggers (Enforcement)
**Doc A must be created BEFORE any further implementation work.**
- No Phase 2 or Phase 3 changes until Doc A exists
- No new platform behavior claims in any doc until Doc A is canonical
**Doc B must be baseline-complete BEFORE Phase 2 changes.**
- At least 6 core scenarios scaffolded
- Expected behavior columns populated from Doc A + Doc C
**Doc C must be finalized BEFORE any JS/TS API changes.**
- All guarantees documented
- API contract defined
- No breaking changes to JS/TS API without Doc C update first
### Immediate (Before New Implementation)
1. Create stub documents A, B, C with structure
2. Migrate content from existing docs into new structure
3. Update all cross-references
4. Mark old docs as deprecated (with pointers to new docs)
**Deliverables Required**:
- Doc A exists as a file in repo
- Doc B exists with scenario tables scaffolded
- Doc C exists with required sections
- Status matrix updated in this document
- Deprecated docs marked with header banner
### Short-term (During Implementation)
1. Keep Doc B updated with test results
2. Update Phase docs as implementation progresses
3. Maintain status matrix
### Long-term (Post-Implementation)
1. Add iOS parity documentation
2. Expand exploration scenarios
3. Create regression test suite based on Doc B
---
## 10. Change-Control Rules
Any change to Docs A–C requires:
1. **Update version header** in the document
2. **Update status matrix** (Section 10) in this directive
3. **Commit message tag**: `[ALARM-DOCS]` prefix
4. **Notification in CHANGELOG** if JS/TS-visible behavior changes
**Phase docs may not be modified unless Doc C changes first** (or explicit exception documented).
**Example commit message**:
```
[ALARM-DOCS] Update Doc C with force stop recovery guarantee
- Added force stop detection requirement
- Updated recovery matrix
- Version bumped to 1.1.0
```
---
## 11. Status Matrix
| Doc | Path | Role | Drafted? | Cleaned? | In Use? | Notes |
| --- | ------------------------------------- | ----------------- | -------- | -------- | ------- | ---------------------------------------- |
| A | `01-platform-capability-reference.md` | Platform facts | ☐ | ☐ | ☐ | Merge from existing platform docs |
| B | `02-plugin-behavior-exploration.md` | Exploration | ☐ | ☐ | ☐ | Based on exploration template |
| C | `03-plugin-requirements.md` | Requirements | ☐ | ☐ | ☐ | Consolidate from requirements doc |
| P1 | `android-implementation-phase1.md` | Impl – Cold start | ✅ | ☐ | ☐ | Exists, needs alignment with Doc C |
| P2 | `android-implementation-phase2.md` | Impl – Force stop | ✅ | ☐ | ☐ | Exists, needs alignment with Doc C |
| P3 | `android-implementation-phase3.md` | Impl – Boot | ✅ | ☐ | ☐ | Exists, needs alignment with Doc C |
**Legend:**
- ✅ = Complete
- ☐ = Not started / In progress
- ⚠️ = Needs attention
---
## Related Documentation
* [Android Implementation Directive](../android-implementation-directive.md) – Umbrella overview
* [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) – Minimal viable recovery
* [Phase 2: Force Stop Recovery](../android-implementation-directive-phase2.md) – Force stop detection
* [Phase 3: Boot Recovery](../android-implementation-directive-phase3.md) – Boot receiver enhancement
* [Exploration Findings](../exploration-findings-initial.md) – Initial code discovery
---
**Status**: Active master coordination directive
**Last Updated**: November 2025
**Next Review**: After Docs A, B, C are created
---
## 12. Single Instruction for Team
**⚠️ BLOCKING RULE**: No engineering or documentation work on alarms/schedules/notifications may continue until Steps 1–3 in §9 ("Immediate") are complete and committed.
**Specifically**:
- Doc A must exist as a file
- Doc B must have scenario tables scaffolded
- Doc C must have required sections
- Status matrix must be updated
- Deprecated files must be marked
**Exception**: Only emergency bug fixes may proceed, but must be documented retroactively in the appropriate Doc A/B/C structure.