learning_ai_clock/docs/roadmap-v2-review.md

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
2. Bugs & Errors in Roadmap v1
3. Architectural Gaps
4. Missing Features & Details
5. Timeline Realism Check
6. Security & Privacy Gaps
7. Testing & Quality Gaps
8. Design System Gap
9. DevOps & Infrastructure Gaps
10. PRD ↔ Roadmap Cross-Reference Gaps
11. Platform Dependencies & Blockers
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:

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