OpenAI Codex f88d9e5953 docs(roadmap): record accessibility item status

2026-05-05 01:21:51 -07:00

40 KiB

Raw Blame History

ChronoMind — Agentic AI Roadmap

Product: ChronoMind — AI-Powered Contextual Clock & Timer Repo: learning_ai_clock Created: March 31, 2026 Strategy: Transform ChronoMind from a smart timer app into the time execution layer for the agentic AI era. Depends on: Existing backend (port 4011), web engine (373+ Vitest tests), iOS/Android native apps.

Open TODO Index

For AI agents: Scan this table, pick the next unresolved TODO by priority, and address it. Search the codebase for TODO-NNN to find the in-code comment with full instructions. After completing a TODO, remove it from this table and mark the corresponding roadmap checkbox.

TODO	Priority	Phase	File(s)	Summary
TODO-001	medium	0	`web/src/app/providers.tsx`	Kill switch maintenance banner — create `<MaintenanceBanner />`, set React state when `checkKillSwitch()` returns `disabled=true`, disable timer creation buttons
✅ TODO-002	medium	0	`web/src/app/settings/page.tsx`	~~Wire feedback button into settings page using `feedbackClient`~~ — settings feedback form submits through `@bytelyst/feedback-client`; verification blocked locally by missing `GITEA_NPM_TOKEN` for private `@bytelyst/*` install (`d38b974`)
✅ TODO-003	medium	0	`web/src/components/CreateTimerModal.tsx`, `web/src/components/AlarmOverlay.tsx`	~~Apply `@bytelyst/accessibility` focus trap + screen reader announcements~~ — shared helpers added in common-plat `42f60cb`, consumed by ChronoMind modals (`bfc4670`)
✅ TODO-004	medium	A.1	`backend/src/modules/routines/routes.ts`	~~Clone template~~ — templates now cloned via `crypto.randomUUID()`, original stays reusable (`0e7c1ae`)
✅ TODO-005	high	A.4	`backend/src/lib/ai-context.ts`	~~Wire LLM~~ — dual-path: extraction-service → Ollama `/api/generate` (5s timeout, feature-gated) (`229ce4f`)
✅ TODO-006	low	A.4	`web/src/lib/context-messages.ts`	~~Centralize backend URL~~ — uses `getBackendBaseURL()` from `product-config.ts` (`5dafcc2`)
TODO-007	medium	A.3	`learning_ai_common_plat/services/mcp-server/`	Add integration tests for 5 new ChronoMind MCP tools (reschedule, availability, routine start, agent-actions list, agent-actions approve)
TODO-008	medium	B	`backend/src/lib/telemetry-events.ts`, `web/src/lib/telemetry-events.ts`	Wire `trackEvent()` / `bufferEvent()` calls into routes and components using the defined telemetry constants. See in-code comments for specific call sites
✅ TODO-009	medium	A.4	`backend/src/lib/ai-context.test.ts`, `web/src/lib/context-messages.test.ts`	Unit tests for `generateContextMessage()` (13 tests: keyword, generic, LLM flag-off, extraction-service, Ollama cascade, error paths, prompt construction) + `fetchEnrichedMessage()` (5 tests: LLM success, keyword fallback on 500/throw, generic fallback, payload shape)
✅ TODO-010	low	cleanup	`backend/src/modules/timers/routes.ts`, `routines/routes.ts`, `households/routes.ts`, `webhooks/routes.ts`, `shared-timers/routes.ts`	~~Replace hardcoded PRODUCT_ID~~ — imports from `product-config.js` in all 5 files (`d74c80a`)
✅ TODO-011	low	cleanup	`web/src/app/error.tsx`	~~Wire error boundary to telemetry~~ — `trackEvent('error', 'app', 'error_boundary', ...)` (`9e63418`)

Current State Summary

Layer	Status	Key Files
Web engine	52 lib files, 16 components, 373+ tests	`web/src/lib/*.ts`
Backend	5 modules + webhooks, port 4011	`backend/src/modules/` (timers, routines, households, shared-timers, webhooks)
iOS	Full SwiftUI + Watch + Mac + Widgets, 129 XCTests	`ios/`
Android	Jetpack Compose + Wear OS + Glance, 30 JUnit5 tests	`android/`
Sync	`@bytelyst/sync` engine + platform-sync.ts client	`web/src/lib/platform-sync.ts`
Webhooks	Subscription CRUD + dispatcher (HMAC + retries) + 15 event types	`backend/src/modules/webhooks/`

Ecosystem Integration Status

@bytelyst/* Package	Status	Notes
`@bytelyst/fastify-core`	✅ Used	`createServiceApp` + `startService`
`@bytelyst/auth` / `fastify-auth`	✅ Used	JWT verify via `registerOptionalJwtContext`
`@bytelyst/auth-client`	✅ Used	`createAuthClient` in `web/src/lib/auth-api.ts`
`@bytelyst/react-auth`	✅ Used	`createAuthProvider` in `web/src/lib/auth-context.tsx`
`@bytelyst/config` / `backend-config`	✅ Used	`baseBackendConfigSchema` in backend config
`@bytelyst/datastore`	✅ Used	Cosmos/memory abstraction in backend
`@bytelyst/cosmos`	✅ Used	Container registration
`@bytelyst/errors`	✅ Used	Typed HTTP errors
`@bytelyst/field-encrypt`	✅ Used	Encryption at rest
`@bytelyst/backend-flags`	✅ Used	`createFlagRegistry` in backend
`@bytelyst/backend-telemetry`	✅ Used	`createTelemetryBuffer` in backend
`@bytelyst/feature-flag-client`	✅ Used	Web client with streaming
`@bytelyst/telemetry-client`	✅ Used	Web telemetry via `createWebTelemetry`
`@bytelyst/diagnostics-client`	✅ Used	Web diagnostics via `createWebDiagnostics`
`@bytelyst/api-client`	✅ Used	`createApiClient` in platform-sync
`@bytelyst/sync`	✅ Used	Sync engine in platform-sync.ts
`@bytelyst/design-tokens`	✅ Used	`--cm-*` CSS props in globals.css
`@bytelyst/ui`	✅ Used	Imported in providers.tsx
`@bytelyst/kill-switch-client`	❌ MISSING	Every other product has this — critical for prod safety
`@bytelyst/feedback-client`	✅ Used	Settings feedback form submits via shared SDK
`@bytelyst/event-store`	❌ MISSING	Domain events not persisted — needed for webhooks + audit
`@bytelyst/webhook-dispatch`	❌ MISSING	Backend uses hand-rolled dispatcher instead of shared package
`@bytelyst/accessibility`	❌ MISSING	Shared accessibility helpers not consumed
`@bytelyst/celebrations`	❌ MISSING	Streak/plan completion should use shared celebrations
`@bytelyst/gentle-notifications`	❌ MISSING	Tempo warnings should use shared gentle notifications
`@bytelyst/ollama-client`	⬜ Not needed yet	Will be needed for Phase A.5 (AI context messages)
`@bytelyst/extraction`	⬜ Not needed yet	Will be needed for Phase A.5 (LLM parsing fallback)

MCP Server Integration (Important)

The centralized MCP server (learning_ai_common_plat/services/mcp-server, port 4007) already has ChronoMind tools:

chronomind.timers.create / .list / .delete
chronomind.routines.list / .validate
chronomind.syncStatus
chronomind.sharedTimers.share
chronomind.households.list

These proxy to chronomind-backend (port 4011) via chronomind-client.ts.

Architecture for new MCP tools:

Backend (port 4011): Add new REST endpoints (planner, agent-actions, reschedule, availability, context-message)
MCP Server (port 4007): Extend chronomind-tools.ts + chronomind-client.ts to expose new endpoints as MCP tools
Product backend does NOT host its own MCP layer — all MCP goes through the centralized server

Phase Overview

Phase	Features	Effort	Timeline
Phase 0	Ecosystem Gap Fixes (kill-switch, feedback, event-store, accessibility)	Low	~1 day
Phase A	MCP Backend Endpoints + MCP Server Extension + AI Context Messages	Medium	~3 days
Phase B	AI Day Planner + Agent Inbox	Medium	~4 days
Phase C	Webhook Migration to @bytelyst/webhook-dispatch + Zapier Compat	Low	~1.5 days
Phase D	Smart Routine Suggestions + Tempo Mode	Medium	~3 days
Phase E	Client-Side Sync Integration (Web ↔ iOS ↔ Android)	High	~4 days

Total estimated: ~16.5 working days across 6 phases. Dependency order: 0 (first) → A → B → C/D (parallel) → E

Phase 0 — Ecosystem Gap Fixes

Goal: Bring ChronoMind into full compliance with the @bytelyst ecosystem before adding new features. Why first: These are production-safety and consistency gaps. Fixing them first prevents new code from repeating the same gaps.

0.1 — Kill Switch Client (Web)

web/src/lib/kill-switch.ts — integrate @bytelyst/kill-switch-client (commit: f3e14e2)
- Same pattern as NomGap/NoteLett: createKillSwitchClient({ baseUrl, productId, platform })
- Check on app init → if killed, show maintenance banner and disable timer creation
- Add pnpm add @bytelyst/kill-switch-client to web/package.json
Wire into web/src/app/providers.tsx — init on mount (commit: f3e14e2)

0.2 — Feedback Client (Web)

web/src/lib/feedback.ts — integrate @bytelyst/feedback-client (commit: f3e14e2)
- createFeedbackClient({ baseUrl, productId, getAccessToken })
Add feedback button to settings page (or floating FAB) (commit: d38b974; status: implemented, verification blocked locally because pnpm install requires GITEA_NPM_TOKEN for private @bytelyst/* packages)
- TODO-002: Wire feedback button into settings page using feedbackClient from web/src/lib/feedback.ts

0.3 — Accessibility Package (Web)

Add @bytelyst/accessibility to web/package.json (commit: f3e14e2)
Integrate helpers into existing modals (commit: bfc4670; shared package: learning_ai_common_plat 42f60cb; status: @bytelyst/accessibility build passed, web typecheck/test/build passed, modal small text promoted from tertiary to secondary for AA contrast)
- TODO-003: Apply @bytelyst/accessibility focus trap + screen reader to CreateTimerModal, AlarmOverlay
- Ensure all --cm-* color tokens meet WCAG AA contrast

0.4 — Feature Flags for New Features (Backend)

Add feature flags for all new agentic features to backend/src/lib/feature-flags.ts (commit: f3e14e2)

'mcp.enabled': false,
'planner.enabled': false,
'agent_inbox.enabled': false,
'tempo.enabled': false,
'routine_suggestions.enabled': false,
'ai_context_messages.enabled': false,
'webhooks.zapier': false,

Gate all new backend routes behind their respective flags (ongoing — applied per-route as built)

0.5 — Telemetry Events for New Features

Define telemetry event names for all new features (commit: f3e14e2)
- mcp.tool_executed, mcp.tool_failed
- planner.day_planned, planner.plan_applied, planner.plan_rejected
- agent_inbox.action_approved, agent_inbox.action_rejected, agent_inbox.batch_approved
- tempo.drift_detected, tempo.adjustment_applied
- routine_suggest.shown, routine_suggest.accepted, routine_suggest.dismissed
- ai_context.enriched, ai_context.fallback_used
- webhook.dispatched, webhook.failed
Add trackEvent() calls in backend routes and web components as they're built (ongoing through all phases)

Phase 0 Exit Criteria

Kill switch client initialized on web app startup (f3e14e2)
Feedback client created (f3e14e2) — UI entry point deferred to TODO-002
Accessibility package added (f3e14e2) — modal integration deferred to TODO-003
7 new feature flags registered (all default false) (f3e14e2)
Telemetry event names defined (16 events, backend + web) (f3e14e2)
All existing tests still pass (182 backend + 394 web)

Phase A — MCP Backend Endpoints + MCP Server Extension + AI Context Messages

Goal: Let any AI agent create, query, reschedule, and dismiss timers via the centralized MCP server. Upgrade context messages with LLM fallback. Why first: This is the single most differentiating feature for 2026. It positions ChronoMind as infrastructure, not just an app.

Architecture: Two-layer approach (see "MCP Server Integration" above):

Layer 1 (this repo): New REST endpoints in backend/src/modules/ — standard Fastify routes
Layer 2 (common-plat): Extend mcp-server/src/modules/chronomind/ to proxy new endpoints as MCP tools

A.1 — New Backend REST Endpoints (chronomind-backend, port 4011)

Add 4 new endpoint groups to the product backend. These are plain REST routes — NOT MCP tools:

backend/src/modules/timers/routes.ts — add reschedule + availability endpoints (commit: 686f5fb)
- POST /api/timers/:id/reschedule — shift timer by delta or to new time
- GET /api/timers/availability?start=<ISO>&end=<ISO>&minSlotMinutes=<N> — find free slots
- Gate behind isFeatureEnabled('mcp.enabled') flag
backend/src/modules/routines/routes.ts — add start-routine endpoint (commit: 686f5fb)
- POST /api/routines/:id/start — start a routine template (changes status → running)
- Gate behind isFeatureEnabled('mcp.enabled') flag
Tests for new timer + routine endpoints (commit: 29a4802)

A.2 — Agent Action Audit Trail (New Backend Module)

backend/src/modules/agent-actions/types.ts — Zod schemas (commit: 29a4802)
- Fields: id, userId, productId, actorId, actorType (agent/user/mcp), toolName, actionType, state (proposed/approved/applied/rejected), reason, payload, createdAt
- Every Cosmos doc includes productId: "chronomind"
backend/src/modules/agent-actions/repository.ts — CRUD (commit: 29a4802)
- Container: cm_agent_actions, partition: /userId
- Uses @bytelyst/datastore getCollection() — never direct Cosmos SDK
backend/src/modules/agent-actions/routes.ts — REST endpoints (commit: 29a4802)
- GET /api/agent-actions — list (filterable by state, actorId, toolName)
- POST /api/agent-actions — create action (used by MCP tools)
- POST /api/agent-actions/:id/approve — approve proposed action
- POST /api/agent-actions/:id/reject — reject proposed action
- POST /api/agent-actions/batch-approve — batch approve by actorId
- Gate behind isFeatureEnabled('agent_inbox.enabled') flag
Register agentActionRoutes in server.ts (commit: 29a4802)
Register cm_agent_actions container in cosmos-init.ts (commit: 29a4802)
Agent action tests — 22 tests (commit: 29a4802)

A.3 — Extend Centralized MCP Server (common-plat)

Extend learning_ai_common_plat/services/mcp-server/src/modules/chronomind/:

chronomind-client.ts — add 6 client functions for new endpoints (commit: efde14ba in common-plat)
- chronomindTimerReschedule, chronomindTimerAvailability, chronomindRoutineStart
- chronomindAgentActionCreate, chronomindAgentActionsList, chronomindAgentActionApprove
chronomind-tools.ts — register 5 new MCP tools (commit: efde14ba in common-plat)
- chronomind.timers.reschedule — shift timer by delta or to new time
- chronomind.timers.availability — find free time slots
- chronomind.routines.start — start a routine template
- chronomind.agentActions.list — list pending agent actions
- chronomind.agentActions.approve — approve a proposed action
- Write tools (reschedule, routines.start) record agent action for audit trail (fail-open)
MCP tool tests (commit: )
- TODO-007: Add integration tests for the 5 new ChronoMind MCP tools in common-plat

A.4 — Context-Aware AI Messages (LLM upgrade)

Upgrade web/src/lib/context-messages.ts with optional LLM enrichment:

backend/src/lib/ai-context.ts — LLM-powered context message generator (commit: c80c1e4)
- Accepts: timer label, category, urgency, user's recent timers, time of day
- Returns: enriched prep message with source indicator (llm/keyword/generic)
- Falls back to keyword rules if LLM unavailable or flag off
- Calls extraction-service timer-context task when EXTRACTION_SERVICE_URL is set
- Gate behind isFeatureEnabled('ai_context_messages.enabled') flag
Backend route: POST /api/context-message (commit: c80c1e4)
web/src/lib/context-messages.ts — add fetchEnrichedMessage() (commit: c80c1e4)
- Graceful degradation: keyword rules remain primary, LLM messages shown as "AI suggestion"
- TODO-008: Wire trackEvent() calls for ai_context.enriched / ai_context.fallback_used
Tests for AI context generation (commit: )
- TODO-009: Add unit tests for generateContextMessage() and fetchEnrichedMessage()

Phase A Exit Criteria

3 new REST endpoints in chronomind-backend (reschedule, availability, routine start) (686f5fb)
Agent action module with full CRUD + batch approve (29a4802)
5 new MCP tools registered in centralized mcp-server (efde14ba in common-plat)
Context messages enriched by LLM with keyword fallback (c80c1e4)
All gated behind feature flags (default off) (f3e14e2)
Telemetry events defined but trackEvent() calls needed in routes (ongoing)
All existing tests still pass (219 backend + 394 web)
No breaking changes to existing timer/routine APIs

Phase B — AI Day Planner + Agent Inbox UI

Goal: "Plan my day" command + web UI for reviewing agent-proposed timers. Depends on: Phase A (MCP tools + agent actions module).

B.1 — Day Planner Engine (Backend)

backend/src/modules/planner/types.ts — Zod schemas for plan requests/responses (commit: )
- PlanDayRequest: activities array (label, duration, priority, category, constraints)
- PlanDayResponse: proposed timeline (timer array with computed times, urgency, cascades)
- PlanConstraint: "after 2pm", "before lunch", "back-to-back with X", "needs 15m break between"
- Every Cosmos doc includes productId: "chronomind"
backend/src/modules/planner/engine.ts — deterministic slot-fitting algorithm (commit: )
- Step 1: Load existing timers for the target day
- Step 2: Compute available slots (gaps between timers)
- Step 3: Fit requested activities into slots respecting constraints + priority order
- Step 4: Assign urgency based on keywords/category (reuse context-messages rules)
- Step 5: Assign cascade presets based on urgency (reuse cascade.ts defaults)
- Step 6: Add prep time buffers (reuse prep-time.ts logic)
- Returns: ordered timer list with state: 'proposed' — not yet committed
backend/src/modules/planner/routes.ts — REST endpoints (commit: )
- POST /api/planner/plan-day — generate proposed plan (does NOT create timers)
- POST /api/planner/apply — commit proposed plan (creates timers + agent action records)
- POST /api/planner/replan — modify an existing plan with new constraints
- Gate behind isFeatureEnabled('planner.enabled') flag
- Track planner.day_planned / planner.plan_applied telemetry events
- Use req.log for logging — never console.log
Planner engine tests (commit: )
- Test: empty day → all activities fit
- Test: busy day → overflow reported with alternatives
- Test: constraints respected (after/before/back-to-back)
- Test: prep time buffers added correctly

B.2 — Day Planner NL Interface

Backend NL → plan translation (commit: )
- POST /api/planner/plan-nl — accepts natural language ("prep slides 2h, standup 30m, lunch, deep coding 3h — plan my afternoon")
- Parses via @bytelyst/extraction client to extraction-service, or regex-based NL parser (ported from web nl-parser.ts)
- Returns same PlanDayResponse as structured endpoint
Tests for NL plan parsing (commit: )

B.2b — Extend MCP Server with Planner Tools (common-plat)

chronomind-client.ts — add planner client functions (commit: )
- chronomindPlanDay(request, opts), chronomindApplyPlan(planId, opts), chronomindPlanNl(text, opts)
chronomind-tools.ts — register 2 new MCP tools (commit: )
- chronomind.planner.planDay — generate proposed plan from activities
- chronomind.planner.planNl — generate proposed plan from natural language

B.3 — Agent Inbox (Web UI)

web/src/components/AgentInbox.tsx — review queue for agent-proposed timers (commit: )
- Use @bytelyst/ui components: Card, Badge, Button, Toast — never build custom equivalents
- List all state: 'proposed' agent actions
- Show: agent name, reason, proposed timer details, timestamp
- Actions: Approve, Reject, Modify then Approve
- Batch approve: "Accept all from [agent]"
- Trust level badge per agent (auto-approve toggle)
- Every interactive element must have aria-label or visible text label
- Colors via --cm-* CSS custom properties — never hardcode hex values
- Track agent_inbox.action_approved / .action_rejected / .batch_approved telemetry
web/src/lib/agent-client.ts — typed API client for agent actions (commit: )
- listAgentActions(filters), approveAction(id), rejectAction(id), batchApprove(actorId)
web/src/app/(app)/inbox/page.tsx — agent inbox page route (commit: )
Sidebar navigation: add "Inbox" nav item with unread badge count (commit: )
Tests for agent inbox (commit: )

B.4 — Day Planner UI (Web)

web/src/components/DayPlanner.tsx — plan-my-day interface (commit: )
- Use @bytelyst/ui components: Card, Button, Badge, Toast — never build custom equivalents
- NL input bar: "Plan my afternoon" → calls /api/planner/plan-nl
- Structured form fallback: add activities with duration + constraints
- Timeline preview: visual preview of proposed plan alongside existing timers
- "Apply Plan" button → creates all timers at once + fire @bytelyst/celebrations confetti on success
- "Edit" per-item before applying (change time, urgency, cascade)
- Overflow warnings: "3 activities don't fit — 2h overflow. Suggestions: extend day, shorten activities, move to tomorrow"
- Every interactive element must have aria-label or visible text label
- Colors via --cm-* CSS custom properties — never hardcode hex values
web/src/lib/planner-client.ts — typed API client for planner (commit: )
web/src/app/(app)/planner/page.tsx — planner page route (commit: )
Sidebar navigation: add "Plan Day" nav item (commit: )

Phase B Exit Criteria

POST /api/planner/plan-day returns valid proposed timeline
NL input parses multi-activity requests correctly
2 new MCP tools in centralized mcp-server (planDay, planNl)
Agent inbox shows proposed timers with approve/reject/batch actions
Day planner UI shows timeline preview with apply/edit controls
All UI uses @bytelyst/ui components + --cm-* tokens + aria-label
All gated behind feature flags, telemetry events tracked
All existing tests still pass
New tests cover planner engine, NL parsing, agent client

Phase C — Webhook Event Wiring + @bytelyst/event-store + Zapier Compatibility

Goal: Wire lifecycle events into the existing webhook dispatcher, add domain event persistence via @bytelyst/event-store, and add Zapier-compatible endpoints. Can run in parallel with Phase D.

Note: The webhook dispatcher is already fully functional — HMAC-SHA256 signing, exponential backoff retries, event logging, auto-disable after failures. No hardening needed. The gaps are: (1) no lifecycle events actually call the dispatcher, (2) no domain event persistence, (3) no Zapier-compatible format.

C.1 — Domain Event Store Integration

Add @bytelyst/event-store dependency to backend (commit: )
backend/src/lib/events.ts — create event store singleton + emitDomainEvent() helper (commit: )
- Uses MemoryEventStore (or FileEventStore for local persistence)
- All domain events flow through this — webhook dispatcher subscribes to it
- Event shape: { type, userId, productId, payload, timestamp, correlationId }

C.2 — Wire Lifecycle Events into Dispatcher

This is the main missing piece — timer/routine state changes should emit events:

backend/src/modules/timers/routes.ts — emit events on state transitions (commit: )
- timer.created on POST create
- timer.fired / timer.completed / timer.dismissed / timer.snoozed / timer.paused / timer.resumed on state change
- Each event calls emitDomainEvent() which fans out to webhook dispatcher
- Track webhook.dispatched / webhook.failed telemetry
backend/src/modules/routines/routes.ts — emit events (commit: )
- routine.started / routine.completed / routine.step_completed
backend/src/modules/households/routes.ts — emit events (commit: )
- household.member_joined / household.member_left
backend/src/modules/shared-timers/routes.ts — emit events (commit: )
- shared_timer.created / shared_timer.fired / shared_timer.acknowledged
Tests for event emission + webhook dispatch integration (commit: )

C.3 — Zapier-Compatible Webhook Format

Zapier REST hook endpoints (commit: )
- GET /api/webhooks/zapier/subscribe — Zapier registers its callback URL
- DELETE /api/webhooks/zapier/unsubscribe — Zapier unregisters
- GET /api/webhooks/zapier/sample — sample payloads per event type (Zapier trigger testing)
- Gate behind isFeatureEnabled('webhooks.zapier') flag
Document webhook payload schemas in docs/WEBHOOK_API.md (commit: )

C.4 — Webhook Management UI (Web)

web/src/components/WebhookManager.tsx — manage webhook subscriptions (commit: )
- Use @bytelyst/ui components: Card, Button, Badge, Toast
- Create subscription: URL, secret, event types (multi-select from 15 event types)
- List subscriptions with status (active, paused, failed)
- Delivery log per subscription
- Test button: fire a test event
- Every interactive element must have aria-label or visible text label
- Colors via --cm-* CSS custom properties
web/src/lib/webhook-client.ts — typed API client (commit: )
Add to settings page or new /settings/webhooks route (commit: )

Phase C Exit Criteria

Domain events emitted on all 15 lifecycle state changes
Events persisted via @bytelyst/event-store
Webhook dispatcher called automatically on domain events
Zapier subscribe/unsubscribe/sample endpoints work
Webhook management UI in web app with @bytelyst/ui components
All gated behind feature flags, telemetry events tracked
All existing tests still pass

Phase D — Smart Routine Suggestions + Tempo Mode

Goal: Proactive intelligence — suggest routines from patterns + adjust pacing when behind schedule. Can run in parallel with Phase C.

D.1 — Smart Routine Suggestions (Web Engine)

Build on existing adaptive-snooze.ts pattern detection approach:

web/src/lib/routine-suggestions.ts — pattern detection engine (commit: )
- Scan timer history for recurring sequences (same labels/categories within similar time windows)
- Group by day-of-week patterns (weekday vs weekend)
- Min threshold: 3 occurrences of same sequence before suggesting
- Output: RoutineSuggestion { name, steps[], confidence, occurrences, dayPattern }
- Pure TS engine — no React imports, testable with Vitest
web/src/lib/routine-suggestions.test.ts — tests (commit: )
- Test: 3x "coffee → standup → email" on weekdays → suggests "Weekday Morning" routine
- Test: fewer than 3 occurrences → no suggestion
- Test: weekend vs weekday patterns differentiated
- Test: overlapping sequences handled (longest match wins)

D.2 — Routine Suggestions UI

web/src/components/RoutineSuggestionCard.tsx — dismissable suggestion card (commit: )
- Use @bytelyst/ui components: Card, Button, Badge — never build custom equivalents
- Shows on dashboard when suggestions available
- "Create Routine" → opens RoutineEditor pre-filled + fire @bytelyst/celebrations on creation
- "Dismiss" → hide for 7 days
- "Never suggest this" → permanent dismiss for this pattern
- Every interactive element must have aria-label or visible text label
- Colors via --cm-* CSS custom properties
- Track routine_suggest.shown / .accepted / .dismissed telemetry
Wire into Dashboard.tsx below the quick timer bar (commit: )
Store dismissed suggestions in localStorage (commit: )

D.3 — Tempo Mode Engine (Web)

web/src/lib/tempo.ts — pace monitoring engine (commit: )
- Track: actual timer completion/dismissal times vs scheduled times
- Detect: running behind by >10 minutes (configurable threshold)
- Generate TempoSuggestion:
  - Option A: Compress next N timers by X minutes each
  - Option B: Skip lowest-priority timer
  - Option C: Push remaining timers back by delay amount
  - Option D: Extend day (shift evening timers)
- Consider energy/mood if check-in data available
- Pure TS engine — no React imports, testable with Vitest
- Gate behind isFeatureEnabled('tempo.enabled') (checked in UI, engine is pure)
web/src/lib/tempo.test.ts — tests (commit: )
- Test: 20 min behind → 3 options generated
- Test: on-time → no suggestions
- Test: critical timers never suggested for compression
- Test: mood data influences suggestions ("low energy → suggest skip gym")

D.4 — Tempo Mode UI

web/src/components/TempoBar.tsx — pace indicator bar (commit: )
- Use @bytelyst/ui Badge for status + @bytelyst/gentle-notifications for soft pace warnings
- Shows current pace: "On track", "10 min behind", "30 min behind"
- Color: green → yellow → red based on delay (using --cm-* tokens)
- Expandable: shows suggestion options when behind
- Actions: accept suggestion → auto-apply reschedule via POST /api/timers/:id/reschedule
- Every interactive element must have aria-label or visible text label
- Track tempo.drift_detected / tempo.adjustment_applied telemetry
Wire into Dashboard header area (commit: )
Gentle notification when pace shifts from green to yellow (via @bytelyst/gentle-notifications) (commit: )

Phase D Exit Criteria

Routine suggestions detect patterns from timer history
Suggestion card appears on dashboard with create/dismiss actions using @bytelyst/ui
Tempo engine detects schedule drift and generates adjustment options
Tempo bar shows pace status with actionable suggestions
Gentle notifications for pace warnings via @bytelyst/gentle-notifications
Celebrations on routine creation via @bytelyst/celebrations
All gated behind feature flags, telemetry events tracked
All existing tests still pass
New engine tests cover edge cases

Phase E — Client-Side Sync Integration

Goal: Make cross-device sync actually work end-to-end (Web ↔ Backend ↔ iOS ↔ Android). Depends on: All other phases (uses the APIs they create).

E.1 — Web Sync Manager Activation

platform-sync.ts already has full sync code. Wire it into the app lifecycle:

web/src/lib/use-sync.ts — verify/fix the React hook that triggers sync (commit: )
- Auto-sync on app launch (if authenticated + sync enabled)
- Auto-sync on timer create/update/delete (debounced, 5s)
- Manual sync button in settings
- Sync status indicator: "Last synced 2m ago" / "Syncing..." / "Offline (3 queued)"
- Handle pulled timers: merge into Zustand store (upsert by ID, respect syncVersion)
- Handle conflicts: server-wins for now, show conflict toast
web/src/app/(app)/settings/page.tsx — add sync section (commit: )
- Toggle: "Enable cross-device sync"
- Sign in / sign out (via @bytelyst/react-auth)
- Sync status display
- "Sync Now" button
- "Clear local data" button
Web sync integration tests (commit: )

E.2 — iOS Sync Manager

ios/ChronoMind/Shared/Cloud/PlatformSyncManager.swift — verify/complete REST sync client (commit: )
- Uses existing BLSyncEngine from ByteLystPlatformSDK (or direct REST if SDK not ready)
- Pull delta: GET /timers/sync?since=<ISO> + GET /routines/sync?since=<ISO>
- Push batch: POST /timers/batch + POST /routines/batch
- Map between CMTimer ↔ SyncTimerDTO (same shape as web DTOs)
- Offline queue: persist pending changes in UserDefaults
- Auto-sync on app foreground + after timer changes
Wire into TimerStore.swift — sync on state changes (commit: )
Settings UI: sync toggle + sign in + last sync time (commit: )
iOS sync tests (commit: )

E.3 — Android Sync Manager

android/app/.../sync/SyncRepository.kt — verify/complete REST sync client (commit: )
- Same delta sync + batch upsert pattern as iOS/web
- Map between TimerEntity ↔ SyncTimerDTO
- Offline queue in Room database (or SharedPreferences)
- WorkManager for background sync (periodic, 15m interval)
Wire into TimerViewModel.kt — sync on state changes (commit: )
Settings screen: sync toggle + sign in + last sync time (commit: )
Android sync tests (commit: )

E.4 — Auth Flow (All Platforms)

Web: sign in / register via @bytelyst/react-auth + platform-service (commit: )
iOS: sign in via BLAuthClient (commit: )
Android: sign in via BLAuthClient Kotlin SDK (commit: )
Verify JWT token flow: login → access token → sync API calls → token refresh (commit: )

Phase E Exit Criteria

Create timer on web → appears on iOS and Android after sync
Create timer on iOS → appears on web and Android after sync
Offline changes queue and flush when connectivity restored
Auth flow works on all 3 platforms
No data loss during sync (conflict resolution: server-wins)
All existing tests still pass on all platforms

Verification Commands

# ── Backend ────────────────────────────────────────
cd backend && pnpm test && pnpm run typecheck && pnpm run build

# ── Web ────────────────────────────────────────────
cd web && pnpm test && pnpm run typecheck && pnpm run build

# ── iOS ────────────────────────────────────────────
cd ios && xcodegen generate && xcodebuild -scheme ChronoMind -sdk iphonesimulator build

# ── Android ────────────────────────────────────────
cd android && ./gradlew :app:assembleDebug && ./gradlew :app:test

Commit Convention

All commits follow: type(scope): description

Scope	Examples
`ecosystem`	Kill switch, feedback, accessibility, feature flags, telemetry (Phase 0)
`mcp`	Backend REST endpoints, MCP server tool extensions (Phase A)
`agent-actions`	Agent action audit trail module (Phase A)
`ai-context`	LLM-powered context messages (Phase A)
`planner`	Day planner engine, NL interface, routes (Phase B)
`agent-inbox`	Agent inbox UI, client (Phase B)
`webhook`	Event wiring, Zapier compat, management UI (Phase C)
`events`	Domain event store integration (Phase C)
`routine-suggest`	Pattern detection engine, suggestion UI (Phase D)
`tempo`	Tempo engine, pace bar UI (Phase D)
`sync`	Client-side sync managers (web, iOS, Android) (Phase E)
`auth`	Auth flow integration (Phase E)

Risk Mitigation

Risk	Mitigation
MCP tools break existing timer API	New backend endpoints are additive; MCP tools proxy via centralized mcp-server — no coupling
Planner engine conflicts with manual timers	Plans are proposed first, user must approve before creating
Webhook dispatch overloads	Rate limit: max 100 webhooks/min per user, exponential backoff (already implemented in dispatcher)
Sync conflicts lose data	Server-wins strategy + conflict toast notification, full export always available
LLM context messages slow	LLM is optional enhancement — keyword rules remain primary with <1ms latency
Phase E scope creep	Auth flow is minimal: login/token/refresh only. No registration, password reset, OAuth in v1
New features break existing	All 7 new features gated behind feature flags (default `false`). Can ship incrementally
Missing ecosystem packages	Phase 0 fills all gaps before new code — prevents cascading omissions

Audit Findings (Ecosystem Gap Review)

Systematic audit against learning_ai_common_plat/packages/ (58 packages) revealed:

Already Correct ✅

Auth pipeline: @bytelyst/auth-client + @bytelyst/react-auth + registerOptionalJwtContext — fully wired
Backend config: @bytelyst/backend-config + backend-flags + backend-telemetry — all used
Web clients: @bytelyst/feature-flag-client + telemetry-client + diagnostics-client — all integrated
Data layer: @bytelyst/datastore + cosmos + field-encrypt — all used in backend
Sync: @bytelyst/sync + api-client — integrated in platform-sync.ts
Design: @bytelyst/design-tokens (--cm-* CSS props) + @bytelyst/ui — both in web
Product config: PRODUCT_ID = 'chronomind' properly sourced from auth-api.ts, not hardcoded in backend

Gaps Fixed in This Roadmap ❌ → ✅

Gap	Severity	Fixed In
No `@bytelyst/kill-switch-client`	Critical	Phase 0.1
No settings feedback entry point using `@bytelyst/feedback-client`	Medium	Phase 0.2 — complete (`d38b974`)
No `@bytelyst/accessibility` focus trap and screen reader helpers	Medium	Phase 0.3 — complete (`bfc4670`, shared 42f60cb)
No feature flags for new features	Critical	Phase 0.4
No telemetry events for new features	Medium	Phase 0.5
MCP tools built in product backend (wrong arch)	Critical	Phase A (dual-layer: backend REST + mcp-server proxy)
Webhook dispatcher never called (no event wiring)	High	Phase C.2
No domain event persistence (`@bytelyst/event-store`)	Medium	Phase C.1
No `@bytelyst/celebrations` for achievements	Low	Phase B.4, D.2
No `@bytelyst/gentle-notifications` for warnings	Low	Phase D.4
No `aria-label` requirements stated for new UI	Medium	All UI tasks now require it
No `@bytelyst/ui` usage requirement for new components	Medium	All UI tasks now require it
No `--cm-*` token requirement for new components	Medium	All UI tasks now require it

MCP Architecture Correction

Wrong (original roadmap): Build backend/src/mcp/ with tool contracts + registration in product backend. Correct: The centralized MCP server (learning_ai_common_plat/services/mcp-server, port 4007) already has chronomind.* tools (7 existing). New tools extend that server; product backend only provides REST endpoints.

Existing MCP tools in mcp-server: chronomind.timers.create, .list, .delete, chronomind.routines.list, .validate, chronomind.syncStatus, chronomind.sharedTimers.share, chronomind.households.list.

Webhook Dispatcher Status Correction

Wrong (original roadmap): Called it a "skeleton" needing hardening. Correct: backend/src/modules/webhooks/dispatcher.ts is fully implemented (201 LOC):

HMAC-SHA256 signing with t=<timestamp>,v1=<signature> format
Exponential backoff retries (100ms × 2^attempt, max 5s)
Event log creation + delivery tracking
Auto-increment failure count on subscription
verifySignature() consumer helper with constant-time comparison
10s timeout per delivery attempt

The actual gap is that no code path calls dispatchEvent() — it's built but unwired.

Notes

Backend migration (original item #5) is ALREADY DONE — backend lives at learning_ai_clock/backend/ (port 4011) with 5 modules + webhooks. No work needed.
Webhook dispatcher (original item #7) is FULLY BUILT — HMAC, retries, event logging all done. Phase C wires lifecycle events into it and adds Zapier compat.
Platform-sync client (original item #9) is FULLY BUILT — web/src/lib/platform-sync.ts has 547 LOC with full sync, DTOs, offline queue, @bytelyst/sync engine. Phase E wires it into the app lifecycle and verifies iOS/Android clients.
MCP server already has 8 ChronoMind tools in learning_ai_common_plat/services/mcp-server/src/modules/chronomind/. New tools extend this, not the product backend.
All new code must include productId: "chronomind" on every Cosmos document.
All new UI must use @bytelyst/ui components, --cm-* CSS properties, and aria-label on every interactive element.
All new backend routes must be gated behind feature flags (default false), use req.log (never console.log), and track telemetry events.

40 KiB Raw Blame History Unescape Escape