pluriwave/openspec/specs/alarm-pre-notice-countdown/spec.md

Alarm Pre-Notice Countdown Specification

Purpose

True per-minute live countdown for the 30-minute alarm pre-notice notification, mirroring the proven snooze-countdown repeating-alarm pattern. Replaces the current frozen, single-shot pre-notice ("30 min" forever) with a self-healing chain that updates every minute (29, 28, ... 1) until the real alarm fires.

Requirements

Requirement: First Pre-Notice Post

The system MUST post the initial pre-notice notification at triggerAtMillis - 30min (T-30min), unchanged from current behavior.

Scenario: First post at T-30min

• GIVEN an alarm scheduled to fire at time T
• WHEN the system clock reaches T-30min
• THEN an exact alarm fires ACTION_PRE_NOTICE
• AND a notification showing "30 min" remaining is posted using notificationIdForAlarm(id)

Requirement: Per-Minute Tick Re-Arm

After posting a pre-notice notification, the system MUST re-arm itself to fire again at the next minute boundary, reusing ACTION_PRE_NOTICE for both the first post and every subsequent tick (no separate action constant).

Scenario: Tick re-arms next minute

• GIVEN ACTION_PRE_NOTICE has just fired and posted a notification with remaining minutes R where R > 1
• WHEN the post completes
• THEN AlarmScheduler.armNextPreNoticeCountdownTick(id, R) arms a new exact alarm at triggerAtMillis - (R - 1) * 60_000L
• AND the new alarm uses requestCode slot 9

Scenario: Tick updates notification content

• GIVEN the tick chain is active for alarm id
• WHEN a re-armed ACTION_PRE_NOTICE fires at a later minute boundary
• THEN the notification at notificationIdForAlarm(id) is updated (not duplicated) to show the new remaining-minutes value

Requirement: Self-Healing Minute Computation

Each tick MUST compute remaining minutes from the current wall-clock time relative to triggerAtMillis, using ceilMinutes(), rather than decrementing a stored counter.

Scenario: Normal tick sequence

• GIVEN consecutive ticks fire close to their scheduled minute boundaries
• WHEN each tick computes remaining minutes via ceilMinutes(triggerAtMillis - now)
• THEN the displayed sequence is 29, 28, 27, ... 1 with no manual decrement state

Scenario: Missed tick self-heals by jumping, not crashing

• GIVEN the OS delays or coalesces a scheduled tick (e.g. Doze quota) so the receiver fires late
• WHEN the delayed tick recomputes remaining minutes from wall clock
• THEN the displayed countdown jumps forward to the correct current value (e.g. skips from 15 to 12) instead of crashing, looping, or showing a stale/negative value

Requirement: Self-Stop at Final Minute

The tick chain MUST stop re-arming once computed remaining minutes is <= 1; the final minute is left to the real fire alarm, not a tick.

Scenario: Chain stops before final minute

• GIVEN a tick fires and computes remaining minutes R <= 1
• WHEN the tick finishes posting/updating the notification
• THEN no further armNextPreNoticeCountdownTick call is made
• AND the alarm's existing setAlarmClock fire alarm remains the sole next trigger

Requirement: Consistent Rounding via ceilMinutes

The system MUST use ceilMinutes() for pre-notice remaining-minutes computation, replacing the prior floor-based computeRemainingMinutes(), for consistency with the snooze-countdown chain.

Scenario: Rounding matches snooze countdown

• GIVEN identical time-remaining deltas for a pre-notice tick and a snooze-countdown tick
• WHEN both compute their displayed minute value
• THEN both use ceilMinutes() and produce the same rounding result for equivalent inputs

Requirement: Tick Chain Cancellation

The system MUST tear down the pending pre-notice tick alarm at all of the following sites: cancelAlarm(), the scheduleSpec no-next-trigger branch, the snooze-transition branch, ACTION_SKIP_NEXT, and ACTION_POSTPONE_NEXT. No site may leave an orphaned repeating alarm.

Scenario: Full alarm cancellation tears down tick chain

• GIVEN a pre-notice tick chain is active for alarm id
• WHEN cancelAlarm(id) is called
• THEN the pending pre-notice tick PendingIntent (slot 9) is cancelled
• AND no further ACTION_PRE_NOTICE ticks fire for id

Scenario: No-next-trigger reschedule cancels tick chain

• GIVEN a pre-notice tick chain is active for alarm id
• WHEN scheduleSpec recomputes and finds no next trigger time for id
• THEN the pending pre-notice tick is cancelled in the same branch that already cancels the single-shot pre-notice and snooze-countdown pendings

Scenario: Snooze transition cancels pre-notice tick chain

• GIVEN a pre-notice tick chain is active for alarm id
• WHEN the user snoozes the alarm, transitioning it into snooze-countdown mode
• THEN the pre-notice tick chain is cancelled
• AND no pre-notice notification or alarm remains pending while snooze-countdown is active

Scenario: Skip-next action cancels tick chain

• GIVEN a pre-notice tick chain is active for alarm id
• WHEN the user taps "Skip" on the pre-notice notification, triggering ACTION_SKIP_NEXT
• THEN the pending pre-notice tick alarm for id is cancelled
• AND no further pre-notice ticks fire for the skipped occurrence

Scenario: Postpone-next action cancels tick chain

• GIVEN a pre-notice tick chain is active for alarm id
• WHEN the user taps "Postpone" on the pre-notice notification, triggering ACTION_POSTPONE_NEXT
• THEN the pending pre-notice tick alarm for id is cancelled
• AND no further pre-notice ticks fire for the postponed occurrence

Requirement: Notification ID Reuse and Mutual Exclusivity with Snooze

The pre-notice tick chain MUST reuse the same notification ID (notificationIdForAlarm(id)) as snooze-countdown, and the two chains MUST remain mutually exclusive in time for the same alarm id.

Scenario: Pre-notice and snooze-countdown never run concurrently

• GIVEN alarm id has an active pre-notice tick chain
• WHEN the alarm is not snoozed
• THEN no snooze-countdown chain is scheduled for id concurrently, preserving the existing scheduleSpec branch invariant on snoozeUntilMillis

Scenario: Notification updates in place, no duplicate

• GIVEN a pre-notice tick posts an update for alarm id
• WHEN the notification ID matches a previously posted pre-notice or snooze-countdown notification for the same id
• THEN the system tray shows a single updated notification, not a duplicate entry