docs(alarms): unify and enhance alarm directive documentation stack

Create unified alarm documentation system with strict role separation:
- Doc A: Platform capability reference (canonical OS facts)
- Doc B: Plugin behavior exploration (executable test harness)
- Doc C: Plugin requirements (guarantees, JS/TS contract, traceability)

Changes:
- Add canonical rule to Doc A preventing platform fact duplication
- Convert Doc B to pure executable test spec with scenario tables
- Complete Doc C with guarantees matrix, JS/TS API contract, recovery
  contract, unsupported behaviors, and traceability matrix
- Remove implementation details from unified directive
- Add compliance milestone tracking and iOS parity gates
- Add deprecation banners to legacy platform docs

All documents now enforce strict role separation with cross-references
to prevent duplication and ensure single source of truth.
This commit is contained in:
Matthew Raymer
2025-11-25 10:09:46 +00:00
parent afbc98f7dc
commit 35babb3126
10 changed files with 2159 additions and 36 deletions

View File

@@ -15,20 +15,27 @@ This directive provides **descriptive overview and integration guidance** for An
**⚠️ CRITICAL**: This document is **descriptive and integrative**. The **normative implementation instructions** are in the Phase 13 directives below. **If any code or behavior in this file conflicts with a Phase directive, the Phase directive wins.**
**Reference**: See [Plugin Requirements](./alarms/03-plugin-requirements.md) for requirements that Phase directives implement.
**Reference**: See [Exploration Findings](./exploration-findings-initial.md) for gap analysis.
**⚠️ IMPORTANT**: For implementation, use the phase-specific directives (these are the canonical source of truth):
- **[Phase 1: Cold Start Recovery](./android-implementation-directive-phase1.md)** - Minimal viable recovery
- Implements: [Plugin Requirements §3.1.2](./alarms/03-plugin-requirements.md#312-app-cold-start)
- Explicit acceptance criteria, rollback safety, data integrity checks
- **Start here** for fastest implementation
- **[Phase 2: Force Stop Detection & Recovery](./android-implementation-directive-phase2.md)** - Comprehensive force stop handling
- Implements: [Plugin Requirements §3.1.4](./alarms/03-plugin-requirements.md#314-force-stop-recovery-android-only)
- Prerequisite: Phase 1 complete
- **[Phase 3: Boot Receiver Missed Alarm Handling](./android-implementation-directive-phase3.md)** - Boot recovery enhancement
- Implements: [Plugin Requirements §3.1.1](./alarms/03-plugin-requirements.md#311-boot-event-android-only)
- Prerequisites: Phase 1 and Phase 2 complete
**See Also**: [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) for master coordination document.
---
## 1. Implementation Overview