docs(openspec): add SDD artifact trail for recent alarm and EQ changes

Persist the exploration, proposal, spec, design, tasks, and verify/archive reports produced during the multi-device EQ, alarm-countdown, and notification-visual-polish SDD cycles.
2026-07-04 12:42:11 +02:00
parent e5b6d8acb3
commit bccc5c48b8
64 changed files with 6020 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Alarm Snooze Dismiss Specification
+
+## Purpose
+
+Define the required behavior for dismissing the alarm screen when the user taps
+Snooze. The dismissal MUST work reliably regardless of whether the app was already
+running or was launched cold (dead-app state) by the full-screen intent.
+
+## Requirements
+
+### Requirement: Reliable Screen Dismissal on Snooze
+
+When the user taps Snooze, the alarm screen MUST be removed from view. The system
+MUST handle both a live Navigator stack (app was running) and an empty Navigator
+stack (app launched from dead state via full-screen intent).
+
+The system MUST use `Navigator.canPop()` to determine the stack state before
+calling `Navigator.pop()`. If `canPop()` returns false, the system MUST call
+`SystemNavigator.pop()` as a fallback to close the activity.
+
+#### Scenario: Snooze from a running app (Navigator stack non-empty)
+
+- GIVEN the alarm screen is displayed and the app was already running before the alarm fired
+- WHEN the user taps Snooze
+- THEN `Navigator.canPop()` returns true
+- AND `Navigator.pop()` is called
+- AND the alarm screen is dismissed
+- AND the app returns to the previous screen
+
+#### Scenario: Snooze from dead-app state (Navigator stack empty)
+
+- GIVEN the app was not running when the alarm fired
+- AND the alarm screen was launched by the full-screen intent as the root activity
+- WHEN the user taps Snooze
+- THEN `Navigator.canPop()` returns false
+- AND `SystemNavigator.pop()` is called
+- AND the alarm screen activity is closed
+- AND the device returns to the home screen or the previous app
+
+#### Scenario: Snooze side effects always complete regardless of dismiss path
+
+- GIVEN either app state (running or dead)
+- WHEN the user taps Snooze
+- THEN `_liberarAudioLocal()` is called before any navigation action
+- AND `radio.audio.pausar()` is called before any navigation action
+- AND `alarmas.posponerAlarma()` is called before any navigation action
+- AND the navigation dismissal is the LAST action in `_posponer()`
+
+---
+
+### Requirement: Snooze Re-Trigger Is Unaffected
+
+The snooze re-schedule logic MUST remain unchanged. The fix MUST NOT alter when or
+how `posponerAlarma()` reprograms the AlarmManager.
+
+#### Scenario: Snooze re-trigger after dead-app dismissal
+
+- GIVEN the alarm screen was dismissed via `SystemNavigator.pop()`
+- WHEN the snoozed time (`snoozeHasta`) is reached
+- THEN the AlarmManager fires the alarm again
+- AND the alarm screen is shown again via full-screen intent
+
+---
+
+### Requirement: No Unintended App Termination
+
+`SystemNavigator.pop()` MUST only be called when `canPop()` is false (i.e., the
+screen was the root route launched from a dead-app full-screen intent). It MUST NOT
+be called when a live Navigator stack exists.
+
+#### Scenario: Guard prevents accidental SystemNavigator.pop() in running-app state
+
+- GIVEN the app has a non-empty Navigator stack
+- WHEN the user taps Snooze
+- THEN `canPop()` returns true
+- AND `SystemNavigator.pop()` is NOT called
+- AND only `Navigator.pop()` is used for dismissal