docs: add roadmap V2 review — gaps, common-plat reuse, bugs identified

- Audit 13 @bytelyst/* packages for ChronoMind reusability - Audit 17 platform-service modules reusable as-is - Identify 7 bugs (deprecated APIs, sync contradictions, TBD backend) - Identify 7 architectural gaps (no productId, no onboarding, no offline strategy) - Identify 10 missing features (no CI/CD, no analytics, no privacy policy) - Timeline realism check (Phase 3 too compressed) - Security, testing, design system, DevOps gap analysis - Recommend platform-service as backend (not Cloudflare Workers) - 10 key decisions pending user sign-off before implementation
2026-02-27 17:33:46 -08:00 · 2026-02-27 17:33:46 -08:00 · c6bef6a717
commit c6bef6a717
parent c02d8cf08c
1 changed files with 581 additions and 0 deletions
--- a/docs/roadmap-v2-review.md
+++ b/docs/roadmap-v2-review.md
@ -0,0 +1,581 @@
+# 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:** PENDING USER REVIEW — do not implement until signed off.
+> **Action:** Review each finding, then this doc becomes the implementation guide for roadmap v2.
+
+---
+
+## 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. [Recommendations Summary](#10-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/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. 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** |
+| D-01 | No design tokens integration | Use `@bytelyst/design-tokens` | **P0** |
+| B-02 | Phase 4/5 cloud sync contradiction | iCloud in Phase 3, REST API in Phase 5 | **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** |
+| 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** |
+| 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** |
+| 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 |