docs: add deep research roadmap packet

Author: SysAdminDoc

.ai/research/2026-05-17/CHANGESET_SUMMARY.md

@@ -0,0 +1,43 @@
+# Changeset Summary
+
+Date: 2026-05-17
+
+## Files Added
+
+- `PROJECT_CONTEXT.md` - canonical consolidated project context for future AI
+  and maintainer sessions.
+- `.ai/research/2026-05-17/STATE_OF_REPO.md` - local repository reconnaissance
+  memo.
+- `.ai/research/2026-05-17/MEMORY_CONSOLIDATION.md` - instruction/memory
+  inventory and reconciliation.
+- `.ai/research/2026-05-17/SOURCE_REGISTER.md` - local, memory, external,
+  competitor, and security source register.
+- `.ai/research/2026-05-17/RESEARCH_LOG.md` - search strategies, commands,
+  failed searches, and saturation notes.
+- `.ai/research/2026-05-17/COMPETITOR_MATRIX.md` - competitor and adjacent
+  project matrix.
+- `.ai/research/2026-05-17/FEATURE_BACKLOG.md` - raw harvested ideas before
+  prioritization.
+- `.ai/research/2026-05-17/PRIORITIZATION_MATRIX.md` - scored candidate matrix.
+- `.ai/research/2026-05-17/SECURITY_AND_DEPENDENCY_REVIEW.md` - dependency,
+  OSV, release, privacy, and platform hardening review.
+- `.ai/research/2026-05-17/DATASET_MODEL_INTEGRATION_REVIEW.md` - data,
+  model, Health Connect, integration, and evaluation review.
+- `app/schemas/com.sysadmindoc.alarmclock.data.local.AlarmDatabase/10.json` -
+  generated Room v10 schema export discovered missing during reconnaissance.
+
+## Files Modified
+
+- `ROADMAP.md` - added a 2026-05-17 deep-research refresh and corrected release
+  workflow drift language.
+- `app/src/main/java/com/sysadmindoc/alarmclock/ui/alarmedit/AlarmEditScreen.kt`
+  - restored the missing `AppFilterChip` import discovered during verification.
+- `app/src/main/java/com/sysadmindoc/alarmclock/ui/settings/SettingsScreen.kt`
+  - restored the missing `AppFilterChip` import discovered during verification.
+
+## Verification
+
+- `git diff --check` passed. Git reported the existing line-ending normalization
+  warning that `ROADMAP.md` will be converted to CRLF the next time Git touches
+  it.
+- `.\gradlew.bat :app:testPlayDebugUnitTest :app:assemblePlayDebug :app:assembleFdroidDebug :wear:assembleDebug --console=plain` passed after the import repair. Gradle still reports existing deprecation warnings for `PhoneStateListener`, `Vibrator.vibrate(...)`, `Icons.Filled.VolumeOff`, `rememberSwipeToDismissBoxState(confirmValueChange)`, `CrashLogger` package info, and Moshi KAPT codegen.

.ai/research/2026-05-17/COMPETITOR_MATRIX.md

@@ -0,0 +1,37 @@
+# Competitor Matrix
+
+Date: 2026-05-17
+
+## Summary
+
+AlarmClockXtreme is already ahead of many FOSS clocks on heavy-sleeper features,
+backup, weather/news context, and wake-readiness UI. The leading gaps are not
+basic alarm CRUD; they are sleep data, wearable depth, Direct Boot/reproducible
+release discipline, and dependency/release trust.
+
+| Product / Project | Positioning | Notable Features | Lessons For AlarmClockXtreme | Sources |
+|---|---|---|---|---|
+| Alarmy | Commercial heavy-sleeper / morning wellness app | Missions such as math, shake, photo, barcode, memory, squat; sleep analysis; wake-up enforcement | ACX already has broad challenge coverage. Next differentiation should be mission stacking, wake-up verification after dismissal, and clearer challenge reliability metrics. | https://alar.my/en, https://alarmy-android.zendesk.com/hc/en-us/articles/360004242254--Mission-How-can-I-set-the-Alarm-off-method-math-shake-etc- |
+| Sleep as Android | Mature sleep tracker plus smart alarm | Health Connect integration, wearables, sleep tracking, sonar-style concepts, anti-snoring ecosystem | ACX should finish Health Connect read path before building its own classifier. Local-first sleep insights can compete without cloud coaching. | https://docs.sleep.urbandroid.org/services/health_connect.html |
+| Sleep Cycle | Commercial smart alarm and sleep coaching | Smart wake window, sound analysis, snore/cough tracking, sleep aid, statistics, coaching | ACX needs a credible smart-wake story: import sleep sessions first, then on-device signals. Avoid unsupported medical claims. | https://sleepcycle.com/features/smart-alarm-clock/, https://support.sleepcycle.com/hc/en-us/articles/7859664023452-Using-the-Sleep-Cycle-app |
+| Sleepwave | Commercial contactless smart alarm | Contactless motion/breathing estimates, sleep depth, sound recordings, dream journal, watch taps | Motion/breathing ideas are attractive but high-risk. Treat as experimental and opt-in, with battery/privacy controls. | https://sleepwave.com/ |
+| Fossify Clock | FOSS clock/timer/stopwatch baseline | Offline, no ads, widgets, custom alarm settings, timer/stopwatch, themes | ACX has richer alarm features but must match FOSS trust: F-Droid metadata, release reproducibility, and privacy statements need to be current. | https://github.com/FossifyOrg/Clock |
+| BlackyHawky Clock | Privacy-first AOSP-derived FOSS clock | Direct Boot, reproducible builds, date-specific alarms, random ringtones, shake/flip actions, permission issue notes | Direct Boot and reproducible-build/release discipline are high-value, concrete ACX roadmap items. | https://github.com/BlackyHawky/Clock |
+| QRAlarm | FOSS QR/barcode wake app | QR/barcode dismissal and signed release fingerprint communication | ACX already has QR challenge capability; add signed artifact/fingerprint trust to release docs. | https://github.com/sweakpl/qralarm-android |
+| AOSP / DeskClock lineage | Baseline Android clock source family | Stock alarm/timer/clock behavior and integration expectations | Preserve familiar Android alarm behavior while adding heavy-sleeper controls. | https://android.googlesource.com/platform/packages/apps/DeskClock/ |
+| yt-dlp ecosystem | Maintained downloader ecosystem | High release cadence for extractor breakage | ACX Play downloader should track a maintained update path or be isolated from alarm-critical runtime. | https://github.com/yt-dlp/yt-dlp |
+| NewPipeExtractor | Android-friendly extractor library | Hotfix releases for YouTube/SoundCloud extractor changes | Useful but volatile. Keep Play-only and covered by dependency/security review. | https://github.com/TeamNewPipe/NewPipeExtractor/releases |
+
+## Opportunity Patterns
+
+- Commercial leaders sell outcomes: "wake up during light sleep", "prove you
+  are awake", "understand your night". ACX can express the same outcomes while
+  staying local-first and transparent.
+- FOSS leaders win trust through offline operation, reproducible builds, Direct
+  Boot, and clear metadata. ACX needs to close its release/metadata drift to
+  match this trust posture.
+- Wearables are now a core expectation for sleep/alarm apps. ACX has a tile, but
+  should add complications, watch-side state, and physical-device QA.
+- Health Connect is the best first data integration because it avoids inventing
+  a cloud account or raw sleep-data import format.
+

.ai/research/2026-05-17/DATASET_MODEL_INTEGRATION_REVIEW.md

@@ -0,0 +1,104 @@
+# Dataset, Model, And Integration Review
+
+Date: 2026-05-17
+
+## Applicability
+
+This project is not an ML-first repository. It has no current model training
+pipeline, no cloud analytics stack, and no dataset ingestion layer. However, it
+does have strong data and integration angles:
+
+- Health Connect sleep sessions.
+- Local alarm/event history.
+- Local wake-streak, snooze, missed-alarm, and challenge metrics.
+- Weather, holiday, alert, news, radio, Hue, webhook, Wear, and downloader
+  integrations.
+
+The file is therefore not thin: the best strategy is local-first data use, not a
+new cloud dataset.
+
+## Health Connect
+
+Recommended near-term integration:
+
+- Add `androidx.health.connect:connect-client` to the Play flavor only.
+- Request only `android.permission.health.READ_SLEEP` initially.
+- Read `SleepSessionRecord` for recent windows.
+- Show sleep duration/stage summaries in Bedtime and Stats.
+- Use data only on device.
+- Keep F-Droid copy honest: no SDK and no Health Connect read path unless a
+  compatible FOSS distribution path exists.
+
+Evidence:
+
+- Android Health Connect sleep-session docs define `SleepSessionRecord` for
+  session and stage data.
+- Android Health Connect publishing docs require Play Console declarations and
+  permission justification for data types.
+
+## Local Analytics
+
+Useful local-only derived metrics:
+
+- Time to dismiss by alarm and challenge.
+- Snooze count by alarm.
+- Missed alarm count by alarm/time of day.
+- Challenge retry count.
+- Wake-streak trend.
+- Sleep duration vs. alarm success once Health Connect is present.
+- Smart-wake window effectiveness.
+
+These can be computed from local Room/DataStore history without any remote
+service.
+
+## Candidate Models
+
+Near-term:
+
+- No ML model. Use rule-based Health Connect summaries and local statistics.
+
+Later, only if needed:
+
+- Actigraphy-light smart-wake heuristic using accelerometer motion while the
+  phone is charging.
+- Tiny on-device audio/noise classifier for snore/noise events, guarded by
+  explicit microphone consent and clear non-medical language.
+- On-device recommendation heuristics for challenge selection based on dismissal
+  history.
+
+Rejected for now:
+
+- Remote AI sleep coach by default.
+- Medical diagnosis language for snoring, apnea, or sleep quality.
+- Uploading sleep/audio/alarm history to a developer service.
+
+## Integration Inventory
+
+Current or planned external surfaces:
+
+- Open-Meteo weather and geocoding.
+- Nager.Date holidays.
+- National Weather Service alerts.
+- Windy map/forecast surface.
+- Google News/RSS-style feed URLs.
+- User-configured webhooks.
+- Philips Hue LAN bridge.
+- Internet radio streams.
+- YouTube downloader/resolution in the Play flavor.
+- Wear OS Data Layer and tile.
+- Health Connect sleep sessions, scaffolded but not yet wired.
+
+Privacy note: the policy should describe these surfaces as optional/user-driven
+where applicable and distinguish developer collection from third-party network
+requests triggered by app features.
+
+## Evaluation Opportunities
+
+- Unit-test Health Connect repository logic with fake client abstractions.
+- Add golden fixtures for sleep-session windows and time zones.
+- Add DST/time-zone regression cases for smart-wake calculations.
+- Add migration tests before any new DB field.
+- Add release smoke tests for both flavors to prove Play-only dependencies do
+  not leak into F-Droid.
+- Add Wear tile/complication render tests or screenshot QA.
+

.ai/research/2026-05-17/FEATURE_BACKLOG.md

@@ -0,0 +1,105 @@
+# Feature Backlog
+
+Date: 2026-05-17
+
+This is the raw harvested backlog before final prioritization. Scored items are
+in `PRIORITIZATION_MATRIX.md`; active roadmap order is in `ROADMAP.md`.
+
+## Release, Trust, And Documentation
+
+- Fix `.github/workflows/release.yml` so tag builds produce signed release
+  artifacts for Play, F-Droid, and Wear instead of debug APKs.
+- Refresh F-Droid metadata to current version/code and current anti-feature
+  language.
+- Update privacy policy and data-safety narrative for every network/data
+  surface, not only Health Connect.
+- Add signed artifact SHA-256 and certificate fingerprint publication pattern.
+- Add SBOM/dependency inventory artifact for releases.
+- Add Dependabot or Renovate for Gradle dependencies and GitHub Actions.
+- Add OSV/dependency vulnerability check that works with Gradle Kotlin DSL.
+- Add release checklist covering build, sign, verify, tag, GitHub release,
+  install smoke, and metadata sync.
+- Add `PROJECT_CONTEXT.md` as canonical memory and keep it in version control.
+
+## Reliability And Android Platform
+
+- Enforce Room schema export checks and migration tests. The missing v10 schema
+  export was generated and added by this research changeset.
+- Add migration tests for every schema bump and verify fresh-install parity.
+- Add Direct Boot support for the minimum alarm data required before first
+  unlock.
+- Add full-screen intent / notification permission diagnostic for Android 14+ and
+  vendor-specific settings.
+- Add Android 15 foreground-service timeout audit for `dataSync` and
+  media-processing paths.
+- Add app standby/battery optimization troubleshooting export.
+- Add crash log export/share from Settings.
+- Tighten Hue v2 TLS by pinning bridge identity or Signify trust material.
+- Add backup-export warning when optional secrets/integration URLs are present.
+
+## Health, Sleep, And Analytics
+
+- Complete Play-flavor Health Connect SDK integration for sleep sessions.
+- Surface last-night sleep duration/stages in Bedtime and Stats.
+- Use Health Connect sleep windows to choose a smart-wake point inside a user
+  configured window.
+- Add local-only sleep trend charts.
+- Add local sleep quality correlations with wake-streak, snooze count, missed
+  alarms, and alarm difficulty.
+- Add optional manual sleep/mood note after dismissal.
+- Add actigraphy-light experimental mode using accelerometer while charging.
+- Add local-only snore/noise event detection behind explicit microphone consent.
+- Add Vico or equivalent charting library for trend views.
+
+## Wear OS
+
+- Add next-alarm complication data source.
+- Add Wear tile refresh QA and physical-device verification notes.
+- Add watch-side quick actions for skip/snooze/dismiss state with sync failure
+  recovery.
+- Add haptic-only watch alarm profile.
+- Add standalone watch fallback investigation for users without phone nearby.
+- Add Wear screenshot/test harness for tile/complication outputs.
+
+## Challenges And Wake Enforcement
+
+- Add mission stacking / multi-step dismissal.
+- Add wake-up check after dismissal with configurable grace period.
+- Add typing phrase challenge.
+- Add brightness/light-sensor challenge.
+- Add NFC tag challenge.
+- Add floor/room QR challenge templates with recovery codes.
+- Add challenge effectiveness analytics: dismiss time, retries, false starts,
+  snooze loops.
+- Add per-alarm recommended challenge profiles.
+
+## Audio, Media, And Integrations
+
+- Evaluate Media3/ExoPlayer for internet radio/alarm audio path.
+- Isolate or replace `youtubedl-android` Play dependency path.
+- Add safer update path for extractor/downloader dependencies.
+- Add per-alarm audio fallback tests for local URI, ringtone URI, stream, and
+  downloaded audio.
+- Add local network integration test stubs for Hue and webhook delivery.
+- Add NWS/Open-Meteo/Nager/Windy/RSS privacy and failure-mode docs.
+
+## UX And Product Polish
+
+- Update README architecture/version facts.
+- Add first-run trust walkthrough that explains exact alarms, notifications,
+  battery, full-screen alarm, and Health Connect separately.
+- Add empty/error/recovery states for every integration settings card.
+- Add tablet/foldable two-pane Settings and alarm edit layout.
+- Add home-screen/lock-screen widget roadmap once Android platform APIs are
+  stable enough.
+- Add user-visible release notes source from `CHANGELOG.md` or "What's New".
+
+## Research-Only Or Conditional
+
+- AI sleep coach: only after local sleep/session data exists and only if local
+  model or explicit opt-in remote model is viable.
+- Menstrual-cycle aware alarms: only if Health Connect read/write policy and
+  user value justify the sensitivity.
+- Blood pressure/weight/mood quick-entry: weak product fit for an alarm app.
+- Cloud sync/account: conflicts with current privacy-first stance unless the
+  user explicitly chooses a self-hosted or BYO backend model.

.ai/research/2026-05-17/MEMORY_CONSOLIDATION.md

@@ -0,0 +1,86 @@
+# Memory Consolidation
+
+Date: 2026-05-17
+
+## Files Inventoried
+
+Repo-local:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `README.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `PRIVACY_POLICY.html`
+- `.github/workflows/release.yml`
+- `.github/workflows/version-lint.yml`
+- `metadata/com.sysadmindoc.alarmclock.yml`
+- `metadata/en-US/fdroid.yml`
+
+No nested `.claude`, `.cursor`, `GEMINI.md`, `COPILOT_INSTRUCTIONS.md`,
+`ARCHITECTURE*`, `CONTRIBUTING*`, or existing `.ai` files were present before
+this research run.
+
+Shared instruction and memory files inspected:
+
+- `C:\Users\--\.claude\CLAUDE.md`
+- `C:\Users\--\CLAUDE.md`
+- `C:\Users\--\.claude\projects\c--Users----repos\memory\MEMORY.md`
+- `C:\Users\--\.claude\projects\c--Users----repos\memory\stack-android.md`
+- `C:\Users\--\.claude\projects\c--Users----repos\memory\android-apk.md`
+- `C:\Users\--\.codex\memories\MEMORY.md`
+- `C:\Users\--\.codex\memories\skills\autonomous-roadmap-loop\SKILL.md`
+
+## Instruction Reconciliation
+
+`AGENTS.md` delegates repo-specific details to `CLAUDE.md` and shared global
+files. It should remain tool-specific.
+
+`CLAUDE.md` is useful as living working notes, but it is ignored by `.gitignore`.
+Treat it as active local memory, not as the only durable project source.
+
+Shared global rules that mattered in this run:
+
+- Read repo `CLAUDE.md` and recent git history at session start.
+- Use `rtk` as a command prefix when available.
+- Keep roadmap/state files synchronized with implementation or planning.
+- Commit and push after completing autonomous work unless a real blocker stops
+  the session.
+
+The consolidated durable context is now `PROJECT_CONTEXT.md`. Future sessions
+should read it after tool-specific instructions.
+
+## Stale Or Contradictory Claims
+
+| Claim | Location | Current Evidence | Disposition |
+|---|---|---|---|
+| Current version around v1.6.3 or v1.9.5 | shared memories | `app/build.gradle.kts`, `wear/build.gradle.kts`, `CHANGELOG.md` are v1.13.1 | Stale memory; use only for historical release workflow. |
+| Room DB v6 | `CLAUDE.md` path notes | `AlarmDatabase.kt` is version 10 | Stale local memory. |
+| Room DB v8 | `README.md` architecture box | `AlarmDatabase.kt` is version 10 | Tracked doc drift. |
+| 19 challenge types/views | `README.md`, `CLAUDE.md` path notes | `ROADMAP.md` and code describe 22 user-facing dismiss challenges | Tracked/local doc drift. |
+| Release workflow builds both flavor artifacts | `ROADMAP.md` release hygiene note | `.github/workflows/release.yml` runs `assembleDebug` | Corrected in new roadmap refresh as an active gap. |
+| Privacy policy says only Open-Meteo/geocoding network requests | `PRIVACY_POLICY.html` older section | README and source include Nager.Date, NWS, Windy, RSS/news, webhooks, Hue LAN, internet radio, YouTube resolution | Active compliance/doc gap. |
+| Latest release tag reflects current app version | tag namespace | latest local tag is `v1.9.5`, app is `v1.13.1` | Release hygiene gap. |
+
+## Durable Facts Extracted To `PROJECT_CONTEXT.md`
+
+- Current version, DB version, backup format, modules, flavors, and branch state.
+- Product stance and privacy-first operating principles.
+- Architecture map for core files.
+- Verification and release commands.
+- Active risks from this research pass.
+- Pointer to the new research packet.
+
+## Open Conflicts
+
+- `CLAUDE.md` is helpful but ignored. Decide whether to track it, keep it local,
+  or move its durable content into `PROJECT_CONTEXT.md` and keep `CLAUDE.md`
+  as a local-only operational scratchpad.
+- The release automation story is not aligned across roadmap and workflow. The
+  workflow is authoritative for actual behavior; roadmap now treats signed
+  release automation as unshipped.
+- The Play flavor's downloader value is real, but the transitive dependency
+  security profile is worse than the privacy-first product posture. Decide
+  whether to force safer transitive versions, isolate the downloader, or move
+  to a maintained update path.
+