# ChronoMind — Roadmap V2 Review

> **Purpose:** Systematic review of `roadmap.md` (v1) identifying bugs, gaps, missing details, and opportunities to leverage the `learning_ai_common_plat` shared ecosystem.
> **Date:** February 2026
> **Status:** ✅ APPLIED — All findings incorporated into `roadmap.md` v2.0. This doc is now an audit trail.
> **Action:** No further action needed. See `roadmap.md` for the implementation-ready version.

---

## Table of Contents

1. [Common Platform Reusability Audit](#1-common-platform-reusability-audit)
2. [Bugs & Errors in Roadmap v1](#2-bugs--errors-in-roadmap-v1)
3. [Architectural Gaps](#3-architectural-gaps)
4. [Missing Features & Details](#4-missing-features--details)
5. [Timeline Realism Check](#5-timeline-realism-check)
6. [Security & Privacy Gaps](#6-security--privacy-gaps)
7. [Testing & Quality Gaps](#7-testing--quality-gaps)
8. [Design System Gap](#8-design-system-gap)
9. [DevOps & Infrastructure Gaps](#9-devops--infrastructure-gaps)
10. [PRD ↔ Roadmap Cross-Reference Gaps](#10-prd--roadmap-cross-reference-gaps)
11. [Platform Dependencies & Blockers](#11-platform-dependencies--blockers)
12. [Recommendations Summary](#12-recommendations-summary)

---

## 1. Common Platform Reusability Audit

The `learning_ai_common_plat` repo contains **13 shared packages** and a **platform-service** (25 modules, 621 tests) that ChronoMind can leverage directly for its cloud/backend needs. The roadmap v1 treated ChronoMind as a fully standalone app with "TBD" backend — this is a significant missed opportunity.

### 1.1 Packages Directly Reusable

| Package | What It Does | ChronoMind Use Case | Phase |
|---------|-------------|---------------------|-------|
| **@bytelyst/auth** | JWT (jose), password hashing (bcryptjs) | User accounts, Pro/Family auth | 4-5 |
| **@bytelyst/react-auth** | React auth context factory (provider + hook) | Web dashboard auth for Pro users | 4-5 |
| **@bytelyst/api-client** | Configurable fetch wrapper with token injection | Web → sync API calls, shareable timer API | 4-5 |
| **@bytelyst/config** | Zod env loader, product identity, AKV resolver | Config management, `productId: "chronomind"` | 4-5 |
| **@bytelyst/cosmos** | Azure Cosmos DB singleton + container registry | Cloud sync storage, shared timers, user accounts | 4-5 |
| **@bytelyst/errors** | Typed HTTP errors (400-429) | Consistent error handling in sync API | 4-5 |
| **@bytelyst/logger** | Structured pino-based logging | Server-side logging | 4-5 |
| **@bytelyst/design-tokens** | JSON → CSS/TS/Kotlin/Swift token generator | Shared design system across web + native | 1-3 |
| **@bytelyst/monitoring** | Health-check utilities | Sync API health endpoint | 5 |
| **@bytelyst/blob** | Azure Blob Storage + SAS tokens | Custom alarm sound uploads (Pro feature) | 5 |
| **@bytelyst/extraction** | `createExtractionClient()`, shared extraction types | Advanced NL parsing via extraction-service (LLM-powered entity extraction as upgrade path from chrono-node) | 2+ |
| **@bytelyst/testing** | Shared test mocks, Fastify inject helpers | Backend test infrastructure | 4-5 |
| **@bytelyst/fastify-core** | `createServiceApp()` + `startService()` | If sync API is Fastify (not Cloudflare Workers) | 5 |

### 1.2 Platform-Service Modules Reusable

| Module | What It Does | ChronoMind Use Case |
|--------|-------------|---------------------|
| **auth** | JWT issue/verify, login/register, SSO | User accounts for Pro/Family |
| **subscriptions** | Subscription CRUD, tier management | Pro + Family tier management |
| **plans** | Plan definitions (free, pro, family) | Plan enforcement |
| **stripe** | Stripe webhooks, checkout sessions | Web payment processing |
| **licenses** | License key generation/validation | Alternative to Stripe for one-time purchases |
| **usage** | Usage tracking per user per day | Timer/sync usage limits for free tier |
| **settings** | Per-user global settings + device overrides | User preferences sync |
| **notifications** | Notification templates + delivery | Push notification delivery for shared timers |
| **invitations** | Invite-by-link with codes | Household/family invitations |
| **referrals** | Referral tracking + reward distribution | Referral program ("invite friend → 1 month Pro") |
| **flags** | Feature flags with FNV-1a rollout | Gradual feature rollout (neurodivergent mode, AI reschedule) |
| **audit** | Audit log for admin actions | Admin visibility into shared timer abuse |
| **telemetry** | Client event ingest + admin query | App analytics (timer created, cascade fired, etc.) |
| **waitlist** | Pre-launch signups | Pre-launch waitlist for iOS/Android |
| **public** | Public endpoints (no auth) | Public shared timer viewing |
| **ratelimit** | IP + user rate limiting | Sync API abuse prevention |
| **products** | Multi-product registry | Register ChronoMind as a product alongside LysnrAI/MindLyst |

### 1.3 What This Means for the Roadmap

**Gap G-01:** Roadmap v1 line 884 says `Sync API: TBD (Fastify or Cloudflare Workers)`. This should NOT be TBD — the answer is **platform-service on Fastify**, which already has auth, subscriptions, stripe, invitations, referrals, usage tracking, settings, feature flags, rate limiting, and telemetry. Building a separate sync API from scratch would duplicate thousands of lines of tested code.

**Recommendation:** Register ChronoMind as a new product in platform-service (`productId: "chronomind"`). Add ChronoMind-specific modules (timers, routines, shared-timers) to platform-service. Reuse everything else as-is.

**New modules needed in platform-service for ChronoMind:**

| Module | Purpose | Cosmos Container |
|--------|---------|-----------------|
| `timers` | Timer CRUD + sync | `timers` (pk: `productId:userId`) |
| `routines` | Routine CRUD + templates | `routines` (pk: `productId:userId`) |
| `shared-timers` | Household shared timers | `shared_timers` (pk: `productId:householdId`) |
| `households` | Household group management | `households` (pk: `productId:householdId`) |

---

## 2. Bugs & Errors in Roadmap v1

### B-01: Sync API "TBD" — Decision Gap (Critical)

- **Location:** Line 884, Appendix Tech Stack
- **Issue:** `Sync API: TBD (Fastify or Cloudflare Workers)` — this is the most critical architectural decision in the roadmap and it's left unresolved.
- **Impact:** Cannot plan Phase 4-5 properly without knowing the backend stack.
- **Fix:** Use platform-service (Fastify) in `learning_ai_common_plat`. See §1.3 above.

### B-02: Phase 4 Cloud Sync Contradicts Phase 5 Cloud Sync

- **Location:** Phase 4 (line 552-558) and Phase 5 (line 683-689)
- **Issue:** Phase 4 says "E2E encrypted sync via CloudKit (Apple) **or** custom API" and Phase 5 says "Cross-platform cloud sync — Sync API: REST endpoints." These are different systems. Which comes first? Is CloudKit used at all?
- **Impact:** Building CloudKit sync in Phase 4 then replacing it with a REST API in Phase 5 is wasted work.
- **Fix:** Pick one path. Recommendation: iCloud/CloudKit for Apple-only sync (Phase 3, via App Groups + CloudKit), then platform-service REST API for cross-platform sync (Phase 5). Phase 4 cloud sync should explicitly say "iCloud only — cross-platform deferred to Phase 5."

### B-03: macOS NSUserNotificationCenter is Deprecated

- **Location:** Line 881, Appendix Tech Stack
- **Issue:** `NSUserNotificationCenter` has been deprecated since macOS 11. macOS uses `UNUserNotificationCenter` now (same as iOS).
- **Fix:** Replace `NSUserNotificationCenter` with `UNUserNotificationCenter` in the macOS row.

### B-04: ClockKit Listed for watchOS — Deprecated

- **Location:** Line 880, Appendix Tech Stack
- **Issue:** `ClockKit` is deprecated as of watchOS 9. All complications should use `WidgetKit` (already mentioned in Phase 3 text, but the appendix still lists ClockKit).
- **Fix:** Remove `ClockKit` from the watchOS tech stack row. Replace with `WidgetKit` only.

### B-05: "Two-way sync" for Calendar is Overambitious

- **Location:** Phase 4, line 513
- **Issue:** "Two-way sync: imported events become timers with auto-cascade" — writing back to Google/Apple/Outlook calendars is extremely complex, fragile, and likely unwanted (users don't want timers appearing as calendar events).
- **Fix:** Change to one-way: calendar → ChronoMind. Users create timers in ChronoMind; calendar events are read-only.

### B-06: Week 2 Exit Criteria Mentions "5 beta testers" — No User Account System Exists

- **Location:** Phase 1, line 187
- **Issue:** "5 beta testers using it daily" — but there's no user accounts, no analytics, no way to measure this in Phase 1.
- **Fix:** Add analytics (Plausible or PostHog) in Phase 1 scaffold. It's mentioned in the architecture diagram (line 50) but never appears in any Phase 1 checklist item.

### B-07: Phase 2 Exit Says "App Store submission prepared" — App Doesn't Exist Yet

- **Location:** Phase 2, line 337
- **Issue:** "App Store / ProductHunt submission prepared" — but the iOS app isn't built until Phase 3.
- **Fix:** Change to "ProductHunt submission prepared (web)" — App Store prep belongs in Phase 3.

---

## 3. Architectural Gaps

### G-02: No `productId` Strategy for Multi-Product Ecosystem

- **Issue:** The ByteLyst ecosystem requires every Cosmos document to include `productId`. ChronoMind needs to be registered as a product (`productId: "chronomind"`) in platform-service's products module.
- **Impact:** Without this, ChronoMind data will collide with LysnrAI/MindLyst data in shared Cosmos containers.
- **Fix:** Add a Phase 4 task: "Register ChronoMind as product in platform-service (productId: chronomind, displayName: ChronoMind, licensePrefix: CHRONO)."

### G-03: No Data Model Specification for Cloud Sync

- **Issue:** The roadmap mentions cloud sync in Phase 4 and 5 but never defines the data schema for synced entities. What fields does a synced timer have? What about conflict resolution specifics?
- **Fix:** Add a data model appendix or reference the PRD's data model section. Specify:
  - Timer sync schema (all fields from web IndexedDB → Cosmos)
  - Routine sync schema
  - Conflict resolution: field-level merge vs document-level last-write-wins
  - Sync metadata: `syncedAt`, `deviceId`, `version` fields

### G-04: No Onboarding Flow

- **Issue:** Phase 1 has a landing page with "Try it now" but no onboarding experience once users enter the app. First-time users need guidance to create their first timer, understand cascades, and set urgency levels.
- **Fix:** Add to Phase 1 Week 2:
  - First-run onboarding: 3-step walkthrough (create timer → set cascade → see timeline)
  - "Create your first timer" prompt on empty dashboard
  - Tooltip hints on cascade and urgency pickers

### G-05: No Error Handling / Offline Resilience Strategy for Web

- **Issue:** PWA is mentioned but there's no strategy for:
  - What happens when a timer fires while offline?
  - What happens when Service Worker is killed by the browser?
  - What's the fallback when IndexedDB is full?
  - How do notifications work if the tab is closed?
- **Fix:** Add to Phase 1:
  - Document SW lifecycle: timers must survive SW termination → use IndexedDB timestamps + SW `periodicsync` or `alarm` events
  - Background sync queue for analytics events
  - IndexedDB size limit handling (warn user, purge old history)
  - "Tab must be open for notifications" disclaimer for iOS Safari

### G-06: No Migration Strategy Between Phases

- **Issue:** Phase 1 stores everything in IndexedDB. Phase 4 introduces cloud sync. How does data migrate? What happens to offline-only users?
- **Fix:** Add migration plan:
  - Phase 4: "Import from local" button — one-time upload of IndexedDB data to cloud
  - Cloud sync is always opt-in; local-only remains fully supported
  - Version field in IndexedDB schema to handle schema migrations between phases

### G-07: Shared Timer Architecture Not Defined

- **Issue:** Phase 5 mentions shared timers with "real-time sync" but doesn't specify the architecture. WebSocket? Server-Sent Events? Polling?
- **Fix:** Add architecture decision:
  - Real-time: WebSocket via platform-service (or SSE for simplicity)
  - Fallback: polling every 30 seconds for web, push notifications for iOS/Android
  - Cosmos change feed for server-side event propagation

---

## 4. Missing Features & Details

### M-01: No Privacy Policy / Terms of Service

- **Issue:** Phase 1 landing page lists "Footer: links, GitHub, privacy" but no task to actually write the privacy policy. This is required before any data collection or App Store submission.
- **Fix:** Add to Phase 2: "Write privacy policy and terms of service. Host at /privacy and /terms."

### M-02: No Data Export / Account Deletion

- **Issue:** GDPR and App Store require data export and account deletion capabilities. Not mentioned anywhere.
- **Fix:** Add to Phase 4:
  - "Export all my data" → JSON download of all timers, routines, stats
  - "Delete my account" → wipe all cloud data, revoke tokens
  - These are App Store requirements since 2022.

### M-03: No Settings Sync Between Web and Native

- **Issue:** Phase 1 stores settings in localStorage. Phase 3 uses SwiftUI `@AppStorage`. Phase 5 adds Android DataStore. There's no plan to sync settings across platforms.
- **Fix:** Phase 4 cloud sync should explicitly include user preferences sync. Use platform-service's existing `settings` module.

### M-04: No Waitlist / Pre-Launch for iOS

- **Issue:** Phase 3 goes straight to TestFlight with 100 testers. No mechanism to collect interest before Phase 3.
- **Fix:** Add to Phase 2:
  - Waitlist signup on web landing page ("Get notified when iOS launches")
  - Use platform-service's `waitlist` module (already exists)
  - Email collection for launch announcement

### M-05: No Routine Template Marketplace / Sharing

- **Issue:** Phase 2 has routine templates (Morning, Evening, Cooking) as hardcoded presets. Phase 4 has shareable timers. But there's no mechanism to share or discover routine templates.
- **Fix:** Add to Phase 4:
  - "Share routine as template" → generates a link
  - "Browse community templates" → curated list on web
  - Platform-service `public` module can serve public templates

### M-06: No iPad-Specific Layout

- **Issue:** Phase 3 targets iOS but never mentions iPad. iPadOS is a significant market for productivity apps.
- **Fix:** Add to Phase 3 Week 9:
  - iPad sidebar navigation (UISplitViewController equivalent in SwiftUI)
  - Wider timeline with side panel for timer detail
  - Stage Manager / multiple window support (iPadOS 16+)

### M-07: No Accessibility Testing in Phase 1-2

- **Issue:** Accessibility is only mentioned in Phase 3 (Week 9) for native apps. Web PWA also needs accessibility.
- **Fix:** Add to Phase 1 exit criteria:
  - WCAG 2.1 AA compliance for all interactive elements
  - Keyboard navigation works for all flows
  - Screen reader (NVDA/VoiceOver) tested on timeline and timer creation

### M-08: No Analytics Implementation Details

- **Issue:** Architecture diagram mentions "Plausible / PostHog" but no checklist item installs or configures analytics.
- **Fix:** Add to Phase 1 Week 1:
  - Install Plausible (privacy-first, no cookies) or PostHog (self-hosted option)
  - Track: page views, timer created, timer completed, cascade fired, Pomodoro completed, PWA installed
  - Dashboard for monitoring key metrics
  - Or: use platform-service telemetry module (`@bytelyst/telemetry`)

### M-09: No CI/CD Pipeline

- **Issue:** The roadmap never mentions CI/CD. No GitHub Actions, no automated testing, no deployment pipeline.
- **Fix:** Add to Phase 1 Week 1:
  - GitHub Actions: lint + typecheck + vitest on PR
  - Auto-deploy to Vercel on `main` push
  - Phase 3: Xcode Cloud or Fastlane for TestFlight builds
  - Phase 5: Gradle CI for Android builds

### M-10: No Feedback Collection Mechanism for Web

- **Issue:** Phase 3 has "Feedback form in Settings" for iOS TestFlight. Web MVP has no feedback mechanism.
- **Fix:** Add to Phase 1 Week 2:
  - Feedback button in web app (opens email or form)
  - Or: integrate with platform-service's notification/feedback pipeline
  - Bug report button with auto-attached browser info

---

## 5. Timeline Realism Check

### T-01: Phase 1 (2 Weeks) is Aggressive but Achievable

- Week 1: scaffold + timer engine + cascade + urgency + timeline + create flow + clock = **7 major features**
- Week 2: notifications + sounds + tab title + alarm overlay + Pomodoro + theme + PWA + shortcuts + landing = **9 major features**
- **Assessment:** Tight but doable for a solo developer if scope is strictly enforced. The timer engine and cascade are the hard parts; UI is mostly shadcn/ui components.
- **Risk:** Serwist (PWA) setup can be tricky. Budget 0.5-1 day just for Service Worker debugging.

### T-02: Phase 3 (4 Weeks for iOS + Watch + Mac) is Very Aggressive

- Week 6: Xcode setup + Swift port + data models + 7 screens + notifications + haptics
- Week 7: Watch app + 4 complications + Live Activities + Dynamic Island + widgets + Siri
- Week 8: macOS menu bar + AI reschedule + gamification
- Week 9: Continuity + accessibility + tests + TestFlight
- **Assessment:** This is the most compressed phase. Apple Watch complications + Live Activities alone can eat a full week of debugging. Siri Shortcuts with App Intents is another 2-3 days.
- **Recommendation:** Either extend Phase 3 to 5-6 weeks, or defer macOS and Siri to Phase 4. Prioritize: iOS app (Week 6-7) → Watch + Widgets (Week 8) → TestFlight (Week 9). macOS menu bar can wait.

### T-03: Phase 5 (8 Weeks) Has Room for Slip

- This is the longest phase and includes the most ambitious features (Android, Wear OS, shared timers, body doubling, API/webhooks, smart home, monetization).
- **Assessment:** Realistic if shared timers are simplified (no real-time, polling-based sync) and body doubling is deferred.
- **Recommendation:** Body doubling (line 702-707) should be labeled as "stretch goal" or "v3", not Phase 5.

---

## 6. Security & Privacy Gaps

### S-01: No Auth for Shared Timer Links

- **Issue:** Phase 4 says "Create a timer and share link: chronom.ind/t/abc123". But who can access this? Is it public? Can anyone add it to their account?
- **Fix:** Define access levels:
  - Public link: anyone can view timer details (read-only)
  - Authenticated link: only registered users can add to their timers
  - Private link: only invited household members can see

### S-02: No Abuse Prevention for Shared Timers

- **Issue:** Shared timers with "real-time sync" and "up to 6 members" need protection against abuse (spam timers, offensive labels, etc.).
- **Fix:** Add:
  - Rate limit on timer creation per household
  - Content filtering on timer labels (basic profanity filter)
  - Household admin can delete any shared timer
  - Report mechanism

### S-03: No Secret Management for Web App

- **Issue:** Phase 4-5 requires API keys (Stripe, Google Calendar OAuth, etc.) but no mention of how secrets are managed for the web deployment.
- **Fix:** Use platform-service's existing AKV integration. Web app server-side routes (Next.js API routes) access secrets via `@bytelyst/config` with `resolveKeyVaultSecrets()`, same pattern as other dashboards.

### S-04: E2E Encryption Not Specified

- **Issue:** "E2E encrypted sync" is mentioned twice (Phase 4 line 553, Phase 5 line 686) but the encryption scheme is never specified.
- **Fix:** Add specification:
  - Client generates AES-256 key on first sync
  - Key is derived from user's password (PBKDF2) — never sent to server
  - Timer data encrypted client-side before upload
  - Server stores encrypted blobs — cannot read timer content
  - Key recovery: user must remember password or loses data (acceptable for a timer app)
  - **Alternative:** Skip E2E encryption. Timer data is not particularly sensitive. TLS in transit + encrypted at rest in Cosmos is sufficient. E2E adds significant complexity for minimal benefit in a timer app.

---

## 7. Testing & Quality Gaps

### Q-01: No Test Strategy for Timer Accuracy

- **Issue:** The core value prop is timers firing at the right time. But no test verifies timing accuracy.
- **Fix:** Add to Phase 1:
  - Timing accuracy tests: create timer for T+5s, verify it fires within 100ms tolerance
  - Service Worker notification timing tests
  - Stress test: 50 concurrent timers with cascades → all fire correctly

### Q-02: No Performance Budget

- **Issue:** "Page load < 2 seconds" and "Lighthouse PWA > 90" are mentioned but no ongoing performance budget.
- **Fix:** Add to Phase 1:
  - Bundle size budget: < 200KB JS (gzipped)
  - Lighthouse CI in GitHub Actions (fail if score drops below 85)
  - Core Web Vitals monitoring via Plausible/PostHog

### Q-03: No Cross-Browser Testing Matrix

- **Issue:** "Chrome, Safari, Firefox" mentioned in exit criteria but no systematic test matrix.
- **Fix:** Add test matrix:
  - Chrome 120+ (desktop + Android)
  - Safari 17+ (macOS + iOS — PWA behavior differs significantly)
  - Firefox 120+ (desktop)
  - Edge 120+ (Chromium-based, should work)
  - Samsung Internet (large Android market share)

### Q-04: No Regression Test for Cascade Timing After DST

- **Issue:** Daylight Saving Time causes timers to shift. The recurrence module mentions DST in tests but cascades don't.
- **Fix:** Add cascade-specific DST test: "Timer at 2:30 AM on DST day — cascade fires correctly despite time jump."

---

## 8. Design System Gap

### D-01: No Shared Design Tokens Usage

- **Issue:** The roadmap mentions "Dark + light theme" with "CSS custom properties + Tailwind dark mode" but doesn't leverage `@bytelyst/design-tokens`. The design-tokens package already has a complete color palette, spacing scale, typography, and generates CSS + TypeScript + Swift + Kotlin outputs.
- **Impact:** ChronoMind will have an inconsistent design language from the rest of the ByteLyst ecosystem.
- **Fix:** Add to Phase 1 scaffold:
  - Extend `bytelyst.tokens.json` with ChronoMind-specific tokens (or create `chronomind.tokens.json`)
  - Use the `generate.ts` script to produce `tokens.css` (web), `ChronoMindTokens.swift` (iOS), `ChronoMindTokens.kt` (Android)
  - Map urgency levels to specific colors from the token palette
  - This gives automatic design consistency across all platforms

### D-02: No Design Mockups / Wireframes Phase

- **Issue:** The roadmap jumps straight to building components without any design phase. No mention of Figma, wireframes, or design review.
- **Fix:** Add to Phase 1 Week 1 (before coding):
  - Wireframe: timeline, create timer, Pomodoro, alarm overlay (low-fi sketches or Figma)
  - Define urgency level color mapping (Critical=red, Important=orange, Standard=blue, Gentle=green, Passive=gray)
  - Define typography scale (heading, body, caption, countdown digits)
  - This doesn't need to be elaborate — 1 day of wireframing saves a week of UI rework

---

## 9. DevOps & Infrastructure Gaps

### I-01: No Domain / DNS Planning

- **Issue:** The roadmap mentions "custom domain" for deployment (Phase 1 exit) and "chronom.ind/t/abc123" for shared timer links but never plans for domain acquisition.
- **Fix:** Add to Phase 1 pre-work:
  - Register domain: `chronomind.app` or `chronomind.io` or `chronom.ind`
  - Set up DNS for web deployment (Vercel/Netlify)
  - Set up Universal Links (Apple) and App Links (Android) for deep linking

### I-02: No Monitoring / Alerting for Cloud Services

- **Issue:** Phase 5 mentions "Sync API < 200ms p99" but no monitoring infrastructure to measure this.
- **Fix:** Add to Phase 5:
  - Use `@bytelyst/monitoring` for health checks
  - Grafana dashboard (already exists in common-plat monitoring service)
  - Alert on: sync API latency > 500ms, error rate > 1%, Cosmos RU consumption

### I-03: No Cost Estimation

- **Issue:** The roadmap mentions Cosmos DB, Azure Blob, Stripe, Plausible, domain, Apple Developer ($99/yr), Google Play ($25 one-time) — but no cost estimate.
- **Fix:** Add cost appendix:
  - Vercel Pro: $20/mo (or free tier for hobby)
  - Cosmos DB: ~$25/mo (400 RU/s, shared with other products)
  - Apple Developer: $99/yr
  - Google Play: $25 one-time
  - Domain: ~$15/yr
  - Plausible: $9/mo (or self-hosted free)
  - **Total pre-revenue: ~$50-70/mo + $124 one-time**

### I-04: No Backup / Disaster Recovery Plan

- **Issue:** User timer data is stored in IndexedDB (local, no backup) for Phases 1-3. If a user clears browser data, all timers are lost.
- **Fix:** Add to Phase 2:
  - "Export timers" → JSON download (manual backup)
  - "Import timers" → upload JSON to restore
  - Show warning: "Your timers are stored locally. Export regularly or enable cloud sync (coming in v1.1)."

---

## 10. PRD ↔ Roadmap Cross-Reference Gaps

Systematic comparison of `PRD.md` (v0.2) against `roadmap.md` (v1) revealed **12 inconsistencies** — several significant.

### X-01: Windows/Tauri Missing from Roadmap Entirely

- **PRD line 59:** `v2.0 | Windows | Tauri` is listed as a target platform.
- **Roadmap v1:** Phase 5 covers Android + Wear OS but never mentions Windows or Tauri.
- **Impact:** Either the PRD overpromises or the roadmap under-delivers. Windows/Tauri is a non-trivial addition.
- **Fix:** Either add a Phase 6 for Windows/Tauri, or remove it from the PRD and label it as "v3 / future" to match the roadmap's scope through v2.

### X-02: Event Countdown Timer Type Never Scheduled

- **PRD feature #26:** "Event countdowns — 132 days until wedding with milestone warnings" is listed as v1.0.
- **Roadmap v1:** No Phase 1 or 2 checklist item implements this timer type. The PRD data model includes `type: 'event'` but no roadmap task builds it.
- **Fix:** Add to Phase 2 Week 4: "Event countdown timer — days/hours until a future date with milestone warnings at configurable intervals (30 days, 7 days, 1 day, etc.)."

### X-03: Cascade Preset Names Don't Match

- **PRD (line 131-138):** Presets are `Aggressive`, `Standard`, `Light`, `Minimal`, `None`, `Custom`
- **Roadmap Phase 1 (line 79):** Presets are `Relaxed`, `Standard`, `Tight`, `Critical`
- **Impact:** Developers won't know which naming is canonical.
- **Fix:** Align on PRD naming (Aggressive → Critical can be added as an alias). The PRD version is more descriptive and covers more use cases (includes `None` and `Custom`).

### X-04: PRD Phase 3 Timeline Differs from Roadmap Phase 3

- **PRD (line 705-711):** Phase 3 is 3 weeks (Weeks 5-7)
- **Roadmap (line 341):** Phase 3 is 4 weeks (Weeks 6-9)
- **PRD summary (line 788):** "iOS + Apple Watch follows in weeks 5-7"
- **Impact:** Confusing for anyone reading both docs.
- **Fix:** Align both to the roadmap's 4-week version (Weeks 6-9), which is already more realistic per T-02. Update PRD phases section to match.

### X-05: Success Metrics Contradict Between PRD and Roadmap

- **PRD Section 12:** MVP targets: 100 PWA installs, 50 DAU, 500+ timers/week
- **Roadmap Success Playbook:** MVP targets: 50 MAU, >40% DAU/MAU ratio
- **Impact:** Two different success criteria for the same phase.
- **Fix:** Reconcile. PRD's are more specific and measurable. Roadmap should adopt PRD's metrics for Phase 1, then layer in the viral/growth metrics for later phases.

### X-06: PRD Says "Open-Source" — Roadmap Never Discusses Licensing

- **PRD line 664:** "ChronoMind is **free and open-source** for personal use."
- **Roadmap:** No mention of licensing, open-source, or repository visibility.
- **Impact:** Open-source has massive implications: competitors can fork, community can contribute, monetization strategy changes.
- **Fix:** Add to Appendix B decisions: "Open-source vs closed-source." If open-source, define license (MIT? AGPL? Business Source License?). If closed-source, remove from PRD. **Recommendation:** Start closed-source, open-source the timer engine library only (good for credibility + community), keep the app itself proprietary.

### X-07: PRD Feature #49 "AI Suggestions" Not in Roadmap

- **PRD line 232:** `AI suggestions — "You have a gap between 2-3pm, want to schedule focus time?"`
- **Roadmap:** Not mentioned in any phase.
- **Fix:** Add to Phase 4 or 5 as a stretch goal. Requires calendar integration (Phase 4) to detect gaps. Label as "v2 stretch" in both docs.

### X-08: Neurodivergent Mode — Toggle vs Default Contradicts

- **PRD Open Question #7 (line 747):** "Decision: design for neurodivergent by default (visual timers, gentle transitions); add 'compact mode' for power users"
- **Roadmap Phase 2 (line 290-299):** Treats neurodivergent mode as a separate toggle in settings ("Gentle mode")
- **Impact:** These are opposite approaches. Default-on vs opt-in toggle.
- **Fix:** Follow the PRD decision — neurodivergent-friendly IS the default UX. The toggle should be "Compact mode" (for power users who want dense UI), not "Gentle mode" (which implies the default is harsh). Update roadmap Phase 2 checklist.

### X-09: PRD Design System (`--cm-*`) Conflicts with ByteLyst Tokens

- **PRD Section 9.1:** Defines a complete ChronoMind-specific color palette with `--cm-*` prefix. Colors are notably different from ByteLyst's:
  - ChronoMind bg: `#0A0B0F`, ByteLyst bg: `#06070A`
  - ChronoMind accent: `#5B8DEE`, ByteLyst accent: `#5A8CFF`
  - ChronoMind has urgency-specific colors: critical `#FF4757`, important `#FF9F43`, standard `#FECA57`, gentle `#2ED573`
  - ByteLyst has no urgency-level colors at all
- **V2 review D-01** recommended extending `bytelyst.tokens.json` but didn't address this color conflict.
- **Fix:** ChronoMind needs its **own product section** in the token file (like the `brain` section exists for MindLyst). Add a `chronomind` section with urgency colors, timer-specific tokens, and the `--cm-*` prefix. The base palette (neutral, spacing, typography, motion) can be shared; the semantic/product colors are ChronoMind's own. Update `generate.ts` to produce `chronomind.tokens.css` alongside the existing outputs.

### X-10: PRD Typography Differs from ByteLyst Tokens

- **PRD line 594-596:** Display: Space Grotesk (shared), Body: **Inter**, Mono: **JetBrains Mono**
- **ByteLyst tokens line 80-83:** Display: Space Grotesk (shared), Body: **DM Sans**, Mono: **IBM Plex Mono**
- **Impact:** Different body and mono fonts across ecosystem products.
- **Fix:** Decision needed: match ByteLyst fonts (DM Sans / IBM Plex Mono) for ecosystem consistency, or keep Inter / JetBrains Mono for ChronoMind's identity? **Recommendation:** Keep ChronoMind's fonts — timer/clock apps need excellent tabular numbers, and JetBrains Mono has superior digit rendering for countdown displays. Add `fontFamily.chronomind` section to tokens.

### X-11: PRD Notification Architecture Mentions SW 30s Check — Roadmap Says `requestAnimationFrame`

- **PRD Section 8.3 (line 486-507):** Timer engine runs in Service Worker, scheduler checks every 30 seconds, has fallback to `setInterval` in active tab.
- **Roadmap Phase 1 (line 75):** Timer engine uses `requestAnimationFrame` + `setInterval` dual-loop.
- **Impact:** These are different architectures. `requestAnimationFrame` runs in the main thread (stops when tab is hidden). SW runs in background.
- **Fix:** Both are needed. Clarify in roadmap: `requestAnimationFrame` for UI countdown display (smooth 60fps), `setInterval` in SW for background notification scheduling. The timer engine must work in BOTH contexts.

### X-12: Extraction Service as NL Upgrade Path — Missed Reuse

- **Common-plat:** `@bytelyst/extraction` package + extraction-service (port 4005) provides LLM-powered entity extraction with configurable tasks, examples, and classes.
- **Roadmap Phase 2:** NL parsing uses `chrono-node` only (local regex-based). PRD Open Question #2 says "optional LLM v2."
- **Fix:** Add to Phase 4 as an upgrade path: "Advanced NL parsing via extraction-service — define a `timer-parse` extraction task with classes like `time`, `duration`, `urgency_hint`, `label`, `recurrence`. Falls back to chrono-node if extraction-service is unavailable." This reuses existing infrastructure instead of building a new LLM integration.

---

## 11. Platform Dependencies & Blockers

The common-plat `PLATFORM_COMPONENTS_ROADMAP.md` identifies **25 gap components** that don't exist yet. Several of these are **direct blockers** for ChronoMind features:

### Blockers for ChronoMind

| Gap Component | Priority | ChronoMind Feature Blocked | Status |
|---------------|----------|---------------------------|--------|
| **Email/Push Delivery (2.2)** | P0 | Shared timer notifications, waitlist emails, referral invites | Not built |
| **Password Reset + Email Verification (2.5)** | P0 | User account creation (Phase 4-5) | Not built |
| **Event Bus (2.4)** | P0 | Shared timer real-time sync, webhook delivery | Not built |
| **Data Export (2.9)** | P1 | GDPR compliance, "Export all my data" (M-02) | Not built |
| **Scheduled Jobs (2.1)** | P0 | Calendar sync polling (every 15 min), recurring timer generation | Not built |

### Impact

- **Phase 1-3 (Web + iOS):** No blockers — everything is local/offline.
- **Phase 4 (Accounts + Sync):** Blocked by Email Delivery (2.2) and Password Reset (2.5). Cannot create user accounts without email verification.
- **Phase 5 (Shared timers):** Blocked by Event Bus (2.4) for real-time updates, and Email Delivery (2.2) for household invitations.

### Mitigation

- **Phase 1-3:** Proceed independently — no backend needed.
- **Phase 4 preparation:** Coordinate with common-plat sprint plan. Email Delivery + Password Reset are on the critical path (Sprint 1-2 per PLATFORM_COMPONENTS_ROADMAP). If they aren't built by Phase 4, ChronoMind can:
  - Use Apple Sign-In / Google Sign-In only (skip email/password accounts initially)
  - Use CloudKit for Apple-only sync (no platform-service dependency)
- **Phase 5:** Event Bus is Sprint 1 priority. If delayed, shared timers can use polling (30s interval) as a degraded experience.

### AKV Secret Mapping Needed

Like `LYSNR_SECRETS` in `@bytelyst/config`, ChronoMind needs `CHRONO_SECRETS`:

```typescript
export const CHRONO_SECRETS = {
  COSMOS_KEY: { envVar: 'COSMOS_KEY', akvName: 'chrono-cosmos-key' },
  JWT_SECRET: { envVar: 'JWT_SECRET', akvName: 'chrono-jwt-secret' },
  STRIPE_SECRET_KEY: { envVar: 'STRIPE_SECRET_KEY', akvName: 'chrono-stripe-secret-key' },
  STRIPE_WEBHOOK_SECRET: { envVar: 'STRIPE_WEBHOOK_SECRET', akvName: 'chrono-stripe-webhook-secret' },
} as const;
```

**Or:** Share the same Cosmos DB and JWT secret as LysnrAI (since `productId` partitions data). Decision needed in Appendix B.

---

## 12. Recommendations Summary

### Critical (Must Fix Before Implementation)

| # | Finding | Fix | Priority |
|---|---------|-----|----------|
| G-01 | Sync API "TBD" | Use platform-service in common-plat | **P0** |
| B-01 | Sync API decision gap | Fastify on platform-service, not Cloudflare Workers | **P0** |
| G-02 | No productId strategy | Register `chronomind` in products module | **P0** |
| X-09 | Design tokens conflict (`--cm-*` vs ByteLyst) | Add ChronoMind product section to token file, keep urgency colors | **P0** |
| B-02 | Phase 4/5 cloud sync contradiction | iCloud in Phase 3, REST API in Phase 5 | **P0** |
| X-03 | Cascade preset names don't match PRD ↔ roadmap | Align on PRD naming (Aggressive/Standard/Light/Minimal/None) | **P0** |
| X-06 | Open-source vs closed-source undecided | Start closed-source, open-source timer engine lib only | **P0** |

### High (Should Fix Before Implementation)

| # | Finding | Fix | Priority |
|---|---------|-----|----------|
| G-04 | No onboarding flow | Add first-run walkthrough to Phase 1 | **P1** |
| G-05 | No offline resilience strategy | Document SW lifecycle, fallback behaviors | **P1** |
| M-09 | No CI/CD pipeline | GitHub Actions + Vercel auto-deploy | **P1** |
| M-08 | No analytics implementation | Add Plausible/PostHog in Phase 1 | **P1** |
| T-02 | Phase 3 too compressed | Extend to 5-6 weeks or defer macOS | **P1** |
| X-04 | PRD and roadmap Phase 3 timelines differ | Align both to 4 weeks (Weeks 6-9) | **P1** |
| X-05 | Success metrics contradict PRD ↔ roadmap | Adopt PRD's specific metrics (100 PWA installs, 50 DAU) | **P1** |
| X-08 | Neurodivergent mode toggle vs default | Follow PRD: neurodivergent-friendly IS default, add "Compact mode" | **P1** |
| X-11 | Timer engine architecture unclear (SW vs rAF) | Both needed: rAF for UI, setInterval in SW for background | **P1** |
| B-03 | NSUserNotificationCenter deprecated | Use UNUserNotificationCenter | **P1** |
| B-04 | ClockKit deprecated | Use WidgetKit only | **P1** |
| M-01 | No privacy policy | Write before any data collection | **P1** |
| Q-01 | No timer accuracy tests | Add timing tolerance tests | **P1** |
| I-01 | No domain planning | Register domain pre-Phase 1 | **P1** |

### Medium (Can Address During Implementation)

| # | Finding | Fix | Priority |
|---|---------|-----|----------|
| B-05 | Two-way calendar sync | Change to one-way (read-only) | **P2** |
| B-06 | "5 beta testers" unmeasurable | Add analytics first | **P2** |
| B-07 | App Store prep in Phase 2 | Move to Phase 3 | **P2** |
| G-03 | No cloud data model spec | Add data model appendix | **P2** |
| G-06 | No migration strategy | Add "import from local" flow | **P2** |
| G-07 | Shared timer architecture undefined | Define WebSocket vs polling | **P2** |
| X-01 | Windows/Tauri in PRD but not roadmap | Either add Phase 6 or move to v3 in PRD | **P2** |
| X-02 | Event countdown timer type never scheduled | Add to Phase 2 Week 4 | **P2** |
| X-10 | Typography differs (Inter vs DM Sans) | Keep ChronoMind fonts (better for digits) | **P2** |
| X-12 | Extraction service unused for NL | Add as Phase 4 upgrade path from chrono-node | **P2** |
| M-02 | No data export / deletion | Add to Phase 4 (App Store requirement) | **P2** |
| M-04 | No iOS waitlist | Use platform-service waitlist module | **P2** |
| M-06 | No iPad layout | Add to Phase 3 | **P2** |
| M-07 | No web accessibility testing | Add to Phase 1 | **P2** |
| M-10 | No web feedback mechanism | Add feedback button | **P2** |
| S-04 | E2E encryption not specified | TLS + at-rest encryption is sufficient | **P2** |
| D-02 | No wireframes phase | 1 day of wireframing pre-Phase 1 | **P2** |
| I-03 | No cost estimation | Add cost appendix | **P2** |
| I-04 | No backup plan | Add export/import in Phase 2 | **P2** |

### Low (Stretch / Future)

| # | Finding | Fix | Priority |
|---|---------|-----|----------|
| M-03 | No settings sync | Use platform-service settings module | **P3** |
| M-05 | No routine marketplace | Add community templates in Phase 4 | **P3** |
| X-07 | AI suggestions not in roadmap | Add to Phase 4-5 as stretch | **P3** |
| S-01 | Shared timer link access levels | Define public/auth/private | **P3** |
| S-02 | Shared timer abuse prevention | Rate limiting + content filter | **P3** |
| T-03 | Body doubling ambitious | Defer to v3 | **P3** |
| Q-02 | No performance budget | Add Lighthouse CI | **P3** |
| Q-03 | No cross-browser matrix | Define test matrix | **P3** |
| Q-04 | No DST cascade test | Add regression test | **P3** |
| I-02 | No monitoring | Use @bytelyst/monitoring | **P3** |

---

## Appendix A: Revised Architecture with Common Platform

```
learning_ai_clock/                      # ChronoMind repo
├── web/                                # Next.js 16 PWA (Track 1)
│   ├── src/
│   │   ├── app/                        # App Router pages
│   │   ├── components/                 # React components
│   │   ├── lib/
│   │   │   ├── timer-engine.ts         # Core timer engine
│   │   │   ├── cascade.ts             # Pre-warning cascade
│   │   │   ├── recurrence.ts          # Recurrence rules
│   │   │   ├── urgency.ts            # Urgency levels
│   │   │   ├── nl-parser.ts          # NL time parsing (chrono-node)
│   │   │   ├── store.ts              # Zustand + IndexedDB
│   │   │   ├── platform-client.ts    # @bytelyst/api-client → platform-service
│   │   │   ├── auth.ts               # @bytelyst/react-auth context
│   │   │   └── product-config.ts     # @bytelyst/config (productId: chronomind)
│   │   └── styles/                    # TailwindCSS + design tokens CSS
│   └── package.json                   # file: refs to @bytelyst/* packages
│
├── apple/                              # Xcode project (Track 2)
│   ├── Shared/                         # Shared across iOS + watchOS + macOS
│   │   ├── TimerEngine/               # Swift port of timer-engine.ts
│   │   ├── Models/                    # SwiftData models
│   │   ├── Notifications/            # UNUserNotificationCenter
│   │   ├── Sync/                     # CloudKit + platform-service client
│   │   └── Theme/                    # ChronoMindTokens.swift (generated)
│   ├── ChronoMind/                    # iOS app target
│   ├── ChronoMindWatch/              # watchOS target
│   └── ChronoMindMac/                # macOS menu bar target
│
├── android/                            # Jetpack Compose (Track 3, Phase 5)
│   └── app/src/main/
│       ├── TimerEngine/               # Kotlin port
│       ├── ui/                        # Compose screens
│       └── theme/                     # ChronoMindTokens.kt (generated)
│
├── docs/                               # Planning documents
│   ├── PRD.md
│   ├── INDUSTRY_RESEARCH.md
│   ├── roadmap.md                     # Roadmap v1
│   └── roadmap-v2-review.md          # This document
│
└── (no backend — uses learning_ai_common_plat/services/platform-service)

learning_ai_common_plat/               # Shared platform (sibling repo)
├── packages/                          # @bytelyst/* consumed via file: refs
│   ├── auth/                          # JWT + password → web auth
│   ├── react-auth/                    # React context → web auth UI
│   ├── api-client/                    # Fetch wrapper → web API calls
│   ├── config/                        # Env + productId → web config
│   ├── cosmos/                        # DB client → sync API storage
│   ├── design-tokens/                 # Tokens → web CSS + Swift + Kotlin
│   └── ...
├── services/
│   └── platform-service/              # Port 4003 — shared backend
│       └── src/modules/
│           ├── auth/                   # ← reuse for ChronoMind accounts
│           ├── subscriptions/         # ← reuse for Pro/Family tiers
│           ├── stripe/                # ← reuse for payments
│           ├── invitations/           # ← reuse for household invites
│           ├── referrals/             # ← reuse for referral program
│           ├── settings/              # ← reuse for user preferences
│           ├── flags/                 # ← reuse for feature rollout
│           ├── telemetry/             # ← reuse for app analytics
│           ├── waitlist/              # ← reuse for pre-launch signups
│           ├── ratelimit/             # ← reuse for API protection
│           ├── usage/                 # ← reuse for free tier limits
│           ├── timers/                # ← NEW: ChronoMind timer CRUD + sync
│           ├── routines/              # ← NEW: routine CRUD + templates
│           ├── shared-timers/         # ← NEW: household shared timers
│           └── households/            # ← NEW: household management
```

## Appendix B: Key Decisions Needed Before Implementation

| # | Decision | Options | Recommendation | Notes |
|---|----------|---------|----------------|-------|
| 1 | **Backend stack** | Platform-service (Fastify) vs Cloudflare Workers vs new service | Platform-service | Reuses 20+ existing modules, zero new infrastructure |
| 2 | **Apple-only sync (Phase 3)** | CloudKit vs skip until Phase 5 | CloudKit for Phase 3, platform-service for Phase 5 | CloudKit is free and fast for Apple-only; cross-platform needs REST |
| 3 | **E2E encryption** | Full E2E vs TLS + at-rest | TLS + at-rest | Timer data isn't sensitive enough to justify E2E complexity |
| 4 | **Real-time shared timers** | WebSocket vs SSE vs polling | SSE (simpler than WS) with polling fallback | Full WebSocket is overkill for timer updates |
| 5 | **Design tokens** | Extend bytelyst.tokens.json vs separate file | Extend existing | Maintains ecosystem consistency |
| 6 | **Analytics** | Plausible vs PostHog vs platform-service telemetry | Platform-service telemetry (already built) | Free, self-hosted, integrated with admin dashboard |
| 7 | **Phase 3 scope** | iOS + Watch + Mac (4 weeks) vs iOS + Watch (4 weeks) + Mac later | Defer macOS to Phase 4 | 4 weeks for iOS + Watch + Live Activities is already aggressive |
| 8 | **Calendar sync direction** | Two-way vs one-way (read-only) | One-way (calendar → ChronoMind) | Two-way is fragile and likely unwanted |
| 9 | **Body doubling** | Phase 5 vs v3 | Defer to v3 | Experimental, requires real-time infrastructure |
| 10 | **Domain name** | chronomind.app vs chronomind.io vs other | Check availability, decide before Phase 1 | Needed for deployment + Universal Links |
| 11 | **Open-source strategy** | Full open-source vs closed-source vs hybrid | Hybrid: open-source timer engine lib, proprietary app | Affects community, competitors, monetization |
| 12 | **Windows/Tauri** | Phase 5 vs Phase 6 vs v3 | Defer to v3 | Not enough market signal yet, focus on mobile |
| 13 | **Shared AKV secrets** | Own CHRONO_SECRETS vs share with LysnrAI | Share Cosmos/JWT (productId partitions), own Stripe keys | Fewer secrets to manage, same infra |
| 14 | **Fonts** | Match ByteLyst (DM Sans, IBM Plex Mono) vs own (Inter, JetBrains Mono) | Own fonts — JetBrains Mono has superior digit rendering | Timer app needs excellent tabular numbers |