# Andromida (Rituals) - Product Requirements Document

> **Version**: 1.0  
> **Last Updated**: February 2026  
> **Status**: Active Development

---

## 1. Overview

### 1.1 Product Vision

Andromida (branded as "Rituals") is a premium, offline-first habit tracker built around customizable "ritual arcs" rather than endless streaks. The app focuses on steady, daily check-ins with a calm visual language, zero paid backend dependencies, and optional iCloud sync.

### 1.2 Target Audience

- Health-conscious individuals seeking structured daily routines
- Productivity enthusiasts who prefer time-bound goals over infinite streaks
- Users who value privacy and offline-first functionality
- Apple ecosystem users who want seamless iCloud integration

### 1.3 Key Differentiators

- **Arc-Based Approach**: Habits are grouped into ritual arcs (7-365 days) with defined start and end dates, allowing for natural cycles of focus and renewal
- **No Paid APIs**: Entirely self-contained with no external service dependencies
- **Offline-First**: Full functionality without network connectivity
- **Privacy-Focused**: All data stored locally with optional iCloud sync

---

## 2. User Goals

| Goal | Description |
|------|-------------|
| **Build Habits** | Establish and maintain daily rituals through consistent check-ins |
| **Track Progress** | Visualize completion rates, streaks, and historical performance |
| **Stay Motivated** | Receive milestone achievements and contextual insights |
| **Customize Experience** | Create personalized rituals with flexible scheduling |
| **Maintain Privacy** | Keep personal data local with optional cloud backup |

---

## 3. Functional Requirements

### 3.1 Today Tab

The primary daily interaction surface for habit check-ins.

| Requirement | Description |
|-------------|-------------|
| FR-TODAY-01 | Display focus ritual cards with circular progress rings showing completion percentage |
| FR-TODAY-02 | Enable tap-to-complete habit check-ins with haptic and sound feedback |
| FR-TODAY-03 | Filter rituals by time of day (morning, midday, afternoon, evening, night, anytime) |
| FR-TODAY-04 | Show smart empty states distinguishing "no rituals" from "no rituals for this time" |
| FR-TODAY-05 | Display arc renewal prompts when ritual arcs complete |
| FR-TODAY-06 | Support adaptive 2-column grid layout on iPad and landscape orientations |
| FR-TODAY-07 | Fresh install starts clean with no pre-seeded rituals |

### 3.2 Rituals Tab

Ritual creation and management interface.

| Requirement | Description |
|-------------|-------------|
| FR-RITUALS-01 | Display all active rituals with card-based UI |
| FR-RITUALS-02 | Create rituals from scratch or browse preset library |
| FR-RITUALS-03 | Provide 14 categorized presets across 4 categories (Health, Productivity, Mindfulness, Self-Care) |
| FR-RITUALS-04 | Support full ritual lifecycle: create, edit, delete |
| FR-RITUALS-05 | Enable drag-to-reorder habits within rituals |

#### 3.2.1 Ritual Detail View

| Requirement | Description |
|-------------|-------------|
| FR-DETAIL-01 | Show progress card with day count and completion summary |
| FR-DETAIL-02 | Display time remaining countdown (e.g., "12 days remaining") |
| FR-DETAIL-03 | Track ritual-specific streaks |
| FR-DETAIL-04 | Show milestone achievements (First Day, One Week, Halfway, Three Weeks, Complete) |
| FR-DETAIL-05 | Display habit performance breakdown with per-habit completion rates |
| FR-DETAIL-06 | Show status badges for time of day and category |
| FR-DETAIL-07 | Provide action menu for edit, end arc/start new arc, and delete |

#### 3.2.2 Ritual Editor

| Requirement | Description |
|-------------|-------------|
| FR-EDITOR-01 | Support custom ritual creation with title, theme, and notes |
| FR-EDITOR-02 | Provide icon picker with 50+ categorized SF Symbols and search |
| FR-EDITOR-03 | Provide habit icon picker with 100+ icons organized by category |
| FR-EDITOR-04 | Allow custom category input beyond preset categories |
| FR-EDITOR-05 | Support flexible duration: slider (7-365 days), quick presets, and custom input |
| FR-EDITOR-06 | Enable time-of-day scheduling (morning, midday, afternoon, evening, night, anytime) |
| FR-EDITOR-07 | Support drag-to-reorder habits |

#### 3.2.3 Arc Renewal System

| Requirement | Description |
|-------------|-------------|
| FR-RENEWAL-01 | Allow rituals to be renewed when arcs complete |
| FR-RENEWAL-02 | Preserve historical data (old arcs remain frozen and accessible) |
| FR-RENEWAL-03 | Copy habits from previous arc to new arc during renewal |
| FR-RENEWAL-04 | Display renewal prompts automatically when arcs complete |

### 3.3 History Tab

Historical view of past completions and performance.

| Requirement | Description |
|-------------|-------------|
| FR-HISTORY-01 | Display scrollable month calendar grid (expandable to 12 months) |
| FR-HISTORY-02 | Show daily progress rings with color coding (green=100%, accent=50%+, gray=<50%) |
| FR-HISTORY-03 | Enable filtering by ritual using horizontal pill picker |
| FR-HISTORY-04 | Support tap on any day to open detail sheet |
| FR-HISTORY-05 | Detail sheet shows: progress ring with percentage, comparison to weekly average, streak context, motivational message, grouped habit list by ritual |
| FR-HISTORY-06 | Support adaptive 2-column grid layout on iPad and landscape |
| FR-HISTORY-07 | In "All" filter mode, calculations must include completed and archived arcs (not only currently active arcs) |

### 3.4 Insights Tab

Analytics and trend visualization.

| Requirement | Description |
|-------------|-------------|
| FR-INSIGHTS-01 | Display 8 tappable insight cards with full-screen detail sheets |
| FR-INSIGHTS-02 | **Active Rituals**: Count with per-ritual breakdown |
| FR-INSIGHTS-03 | **Streak**: Current and longest perfect-day streak tracking (100% completion days) |
| FR-INSIGHTS-04 | **Habits Today**: Completed count with per-ritual breakdown |
| FR-INSIGHTS-05 | **Completion**: Today's percentage with 7-day trend chart |
| FR-INSIGHTS-06 | **Days Active**: Total active days with detailed breakdown |
| FR-INSIGHTS-07 | **7-Day Avg**: Weekly average completion percentage with trend chart |
| FR-INSIGHTS-08 | **Total Check-ins**: All-time habit completions across all rituals |
| FR-INSIGHTS-09 | **Best Ritual**: Highest-performing ritual by completion rate |
| FR-INSIGHTS-10 | Show trend indicators (up/down/stable) with week-over-week comparison |
| FR-INSIGHTS-11 | Display contextual tips based on performance |
| FR-INSIGHTS-12 | Enable drag-and-drop card reordering in edit mode |
| FR-INSIGHTS-13 | Show sparkline charts for trend visualization |

### 3.5 Settings Tab

Application configuration and preferences.

| Requirement | Description |
|-------------|-------------|
| FR-SETTINGS-01 | Configure smart reminders based on ritual time slots (morning 7:00 AM, midday 12:00 PM, evening 6:00 PM) |
| FR-SETTINGS-02 | Toggle haptic feedback for habit check-ins |
| FR-SETTINGS-03 | Toggle sound feedback for habit check-ins |
| FR-SETTINGS-04 | Select theme (light, dark, system) |
| FR-SETTINGS-05 | Enable/disable iCloud settings sync |
| FR-SETTINGS-06 | Manage categories (create, edit, delete user categories) |
| FR-SETTINGS-07 | Provide debug tools in DEBUG builds: reset onboarding, app icon generation, branding preview, preload demo data, clear all completions, simulate arc completion |

### 3.6 Widget

Home screen widget for at-a-glance progress.

| Requirement | Description |
|-------------|-------------|
| FR-WIDGET-01 | Support small, medium, and large widget sizes |
| FR-WIDGET-02 | Display today's completion rate |
| FR-WIDGET-03 | Show current streak |
| FR-WIDGET-04 | List next habits (up to 4) |
| FR-WIDGET-05 | Indicate current time of day |
| FR-WIDGET-06 | Show next ritual information |
| FR-WIDGET-07 | Support App Intents for widget configuration |
| FR-WIDGET-08 | Update widget content every 15 minutes |
| FR-WIDGET-09 | Use App Group shared container for SwiftData access |
| FR-WIDGET-10 | "Next ritual" label must correctly distinguish "later today" vs "tomorrow" based on target timeline date |

### 3.7 Onboarding

First-launch setup wizard.

| Requirement | Description |
|-------------|-------------|
| FR-ONBOARD-01 | **Welcome**: Introduction to the app |
| FR-ONBOARD-02 | **Goal Selection**: Choose from predefined goals |
| FR-ONBOARD-03 | **Time Selection**: Select preferred ritual times (morning/evening/both) |
| FR-ONBOARD-04 | **Ritual Preview**: Preview and optionally create preset rituals |
| FR-ONBOARD-05 | **First Check-In**: Complete first habit check-in |
| FR-ONBOARD-06 | **Notifications**: Set up reminder permissions |
| FR-ONBOARD-07 | **What's Next**: Orientation to Today, Rituals, and Insights tabs |
| FR-ONBOARD-08 | Allow onboarding reset from Settings (DEBUG builds) |

### 3.8 Deep Linking

URL scheme support for navigation.

| Requirement | Description |
|-------------|-------------|
| FR-DEEPLINK-01 | Support `andromida://today` to navigate to Today tab |
| FR-DEEPLINK-02 | Support `andromida://rituals` to navigate to Rituals tab |
| FR-DEEPLINK-03 | Support `andromida://insights` to navigate to Insights tab |
| FR-DEEPLINK-04 | Support `andromida://history` to navigate to History tab |

---

## 4. Non-Functional Requirements

### 4.1 Performance

| Requirement | Description |
|-------------|-------------|
| NFR-PERF-01 | Analytics calculations must use caching to avoid recalculation on each access |
| NFR-PERF-02 | History view must cache progress data for smooth scrolling |
| NFR-PERF-03 | App launch must complete without white flash using native LaunchScreen.storyboard |
| NFR-PERF-04 | Widget updates must complete within WidgetKit timeline constraints |

### 4.2 Accessibility

| Requirement | Description |
|-------------|-------------|
| NFR-A11Y-01 | Support Dynamic Type for all text elements |
| NFR-A11Y-02 | Provide VoiceOver accessibility labels and hints |
| NFR-A11Y-03 | Ensure sufficient color contrast ratios |
| NFR-A11Y-04 | Support reduced motion preferences |

Implementation note: Onboarding flows and root-level shell transitions should avoid motion-heavy animations when iOS Reduce Motion is enabled.

### 4.3 Localization

| Requirement | Description |
|-------------|-------------|
| NFR-L10N-01 | All user-facing strings must be localized using String Catalogs |
| NFR-L10N-02 | Support English (en), Spanish (es-MX), and French (fr-CA) |
| NFR-L10N-03 | Use locale-appropriate date and number formatting |

### 4.4 Privacy & Security

| Requirement | Description |
|-------------|-------------|
| NFR-PRIV-01 | All user data must be stored locally on device |
| NFR-PRIV-02 | iCloud sync must be opt-in and clearly disclosed |
| NFR-PRIV-03 | No user data may be transmitted to external services |
| NFR-PRIV-04 | App must function fully offline |

---

## 5. Technical Requirements

### 5.1 Platform

| Requirement | Description |
|-------------|-------------|
| TR-PLAT-01 | iOS 18.6+ minimum deployment target |
| TR-PLAT-02 | Swift 5 with modern concurrency (async/await, actors) |
| TR-PLAT-03 | SwiftUI for all user interface |
| TR-PLAT-04 | SwiftData for persistence with `@Observable` pattern |
| TR-PLAT-05 | WidgetKit for Home screen widgets |

### 5.2 Architecture

| Requirement | Description |
|-------------|-------------|
| TR-ARCH-01 | Follow Clean Architecture with separation: Views, State, Services, Models |
| TR-ARCH-02 | Use protocol-oriented design for testability |
| TR-ARCH-03 | Implement `@Observable` stores (not ObservableObject) |
| TR-ARCH-04 | Use dependency injection via protocols |

### 5.3 Data Persistence

| Requirement | Description |
|-------------|-------------|
| TR-DATA-01 | Use SwiftData with optional CloudKit sync for ritual data |
| TR-DATA-02 | Use NSUbiquitousKeyValueStore (via Bedrock CloudSyncManager) for settings sync |
| TR-DATA-03 | Use UserDefaults for user-created categories and preferences |
| TR-DATA-04 | Use App Group shared container for widget data access |
| TR-DATA-05 | Run a startup integrity migration to normalize arc date ranges, in-progress arc state, and persisted sort indexes |
| TR-DATA-06 | Enable iCloud runtime compatibility by shipping `com.apple.developer.ubiquity-kvstore-identifier` and `remote-notification` background mode when CloudKit/KVS sync is enabled |
| TR-DATA-07 | For SwiftData CloudKit sync, ship Push Notifications entitlement (`aps-environment`) with per-configuration environment values |
| TR-DATA-08 | Observe `.NSPersistentStoreRemoteChange` and reload SwiftData-backed state when remote merges arrive |
| TR-DATA-09 | Maintain a foreground sync safety-net refresh, but do not rely on app relaunch for cross-device update visibility |
| TR-DATA-10 | Ensure UI invalidation on each remote merge so batched updates appear without manual pull-to-refresh |
| TR-DATA-11 | Emit sync diagnostics (remote event count and timestamp) to support field debugging on physical devices |
| TR-DATA-12 | Validate every release with a two-device real-time sync test matrix (single toggle, rapid batch toggles, background/foreground recovery) |

#### 5.3.1 SwiftData to CloudKit Reuse Standard

Use `SWIFTDATA_CLOUDKIT_SYNC_REQUIREMENTS.md` as the canonical implementation and QA checklist for any app that uses SwiftData with CloudKit.

Standard coverage includes:

- capabilities/entitlements baseline (CloudKit, Push Notifications, Remote Notifications background mode)
- runtime remote-change handling and stale-context mitigation
- deterministic UI refresh behavior for remote merges and rapid batched edits
- repeatable two-device verification and CloudKit Console validation flow

### 5.4 Third-Party Dependencies

| Requirement | Description |
|-------------|-------------|
| TR-DEPS-01 | Bedrock design system package (internal) for theming, branding, and common UI components |
| TR-DEPS-02 | No external third-party frameworks without explicit approval |

---

## 6. Data Model

### 6.1 Core Entities

#### Ritual

Primary entity representing a habit collection.

| Property | Type | Description |
|----------|------|-------------|
| id | UUID | Unique identifier |
| title | String | Ritual name |
| theme | String | Visual theme identifier |
| notes | String? | Optional user notes |
| defaultDurationDays | Int | Default arc duration (7-365) |
| timeOfDay | TimeOfDay | Scheduling preference |
| iconName | String | SF Symbol name |
| category | String | Category identifier |
| sortIndex | Int | Display order |
| arcs | [RitualArc] | Related arcs (one-to-many, cascade delete) |

**Computed Properties**: `currentArc`, `hasActiveArc`, `sortedArcs`, `latestArc`, `completedArcCount`, `habits`

#### RitualArc

Time-bound period for a ritual.

| Property | Type | Description |
|----------|------|-------------|
| id | UUID | Unique identifier |
| startDate | Date | Arc start date |
| endDate | Date | Arc end date |
| arcNumber | Int | Sequential arc number |
| isActive | Bool | Whether arc is currently active |
| habits | [ArcHabit] | Related habits (one-to-many, cascade delete) |
| ritual | Ritual | Parent ritual (inverse relationship) |

**Computed Properties**: `durationDays`, **Methods**: `contains(date:)`, `dayIndex(for:)`, `createRenewalArc()`

#### ArcHabit

Individual habit within an arc.

| Property | Type | Description |
|----------|------|-------------|
| id | UUID | Unique identifier |
| title | String | Habit name |
| symbolName | String | SF Symbol name |
| goal | Int | Target completions |
| completedDayIDs | [String] | Array of date identifiers |
| sortIndex | Int | Display order |
| arc | RitualArc | Parent arc (inverse relationship) |

**Methods**: `copyForNewArc()`

### 6.2 Supporting Models

#### Category

User-defined or preset category.

| Property | Type | Description |
|----------|------|-------------|
| id | String | Unique identifier |
| name | String | Display name |
| colorName | String | Color identifier (13 available colors) |
| isPreset | Bool | Whether system-defined |

**Preset Categories**: Health, Productivity, Mindfulness, Self-Care

#### TimeOfDay

Scheduling enumeration.

| Case | Time Range |
|------|------------|
| morning | Before 11:00 AM |
| midday | 11:00 AM - 2:00 PM |
| afternoon | 2:00 PM - 5:00 PM |
| evening | 5:00 PM - 9:00 PM |
| night | After 9:00 PM |
| anytime | Flexible timing |

#### InsightCard

Analytics display card.

| Type | Description |
|------|-------------|
| Active | Active ritual count with breakdown |
| Streak | Current and longest perfect-day streak (100% completion days) |
| HabitsToday | Today's completed habits |
| Completion | Today's percentage with trend |
| DaysActive | Total active days |
| SevenDayAvg | Weekly average percentage |
| TotalCheckins | All-time completions |
| BestRitual | Top-performing ritual |

#### Milestone

Achievement markers.

| Milestone | Description |
|-----------|-------------|
| First Day | First day completed (day 1) |
| One Week | First week completed (day 7) |
| Halfway | 50% of arc completed (dynamic based on arc duration) |
| Three Weeks | 21 days completed |
| Complete | Full arc completed |

### 6.3 Entity Relationships

```
Ritual (1) ──────< RitualArc (many)
                       │
                       └────< ArcHabit (many)
```

- Ritual → RitualArc: One-to-many with cascade delete
- RitualArc → ArcHabit: One-to-many with cascade delete
- RitualArc → Ritual: Inverse relationship

---

## 7. Design System

### 7.1 Theme Integration

The app uses the Bedrock design system with a custom `RitualsTheme` providing:

- **Surface Colors**: primary, secondary, tertiary, card backgrounds
- **Text Colors**: primary, secondary, tertiary, disabled, inverse
- **Accent Colors**: primary, light, dark, secondary
- **Status Colors**: success, warning, error, info
- **Border Colors**: subtle, standard, emphasized, selected
- **Interactive Colors**: selected, hover, pressed, focus

### 7.2 Color Assets

| Asset | Purpose |
|-------|---------|
| Background, BackgroundAlt, BackgroundTertiary | Surface backgrounds |
| Card | Card backgrounds |
| Divider | Separator lines |
| Accent, AccentLight, AccentDark, AccentSecondary, AccentSoft | Brand and interactive colors |
| TextPrimary, TextSecondary, TextTertiary, TextDisabled | Typography |
| Success, Warning, Error, Info | Status indicators |

### 7.3 Branding

| Element | Specification |
|---------|---------------|
| App Name | Andromida (displayed as "Rituals") |
| Bundle ID | com.mbrucedogs.Andromida |
| App Group | group.com.mbrucedogs.Andromida |
| CloudKit Container | iCloud.com.mbrucedogs.Andromida |

### 7.4 Adaptive Layout

| Requirement | Description |
|-------------|-------------|
| Max content width constraints for iPad and landscape |
| 2-column grid layouts where appropriate |
| Responsive spacing and typography |

---

## 8. Preset Library

### 8.1 Health (3 presets)

- Morning Hydration
- Midday Movement
- Sleep Preparation

### 8.2 Productivity (3 presets)

- Deep Work Prep
- End-of-Day Review
- Focus Reset

### 8.3 Mindfulness (4 presets)

- Morning Meditation
- Gratitude Practice
- Breathwork
- Evening Reflection

### 8.4 Self-Care (4 presets)

- Morning Skincare
- Digital Detox
- Evening Wind-Down
- Weekly Reset

---

## 9. TODO

Remaining features and enhancements to be implemented.

### 9.1 HealthKit Integration

Sync habit completions to Apple Health for relevant habit types.

| Item | Description |
|------|-------------|
| Water tracking | Sync hydration habits to HealthKit water intake |
| Mindfulness | Sync meditation/breathwork habits to HealthKit mindful minutes |
| Exercise | Sync movement habits to HealthKit activity |
| Implementation plan | See `.cursor/plans/healthkit_integration_plan_ce4f933c.plan.md` |

### 9.2 Watch App

Companion watchOS app for quick habit check-ins.

| Item | Description |
|------|-------------|
| Quick check-ins | Allow habit completion directly from Apple Watch |
| Complications | Show today's progress on watch face |
| Sync | Real-time sync with iOS app via WatchConnectivity |

### 9.3 Export/Import

Backup and restore ritual data.

| Item | Description |
|------|-------------|
| Export format | JSON or other portable format for ritual data |
| Import | Restore rituals from backup file |
| Share | Share ritual templates with others |

### 9.4 Statistics

Extended analytics with longer time horizons.

| Item | Description |
|------|-------------|
| Monthly summary | Aggregate completion stats by month |
| Yearly summary | Year-in-review style analytics |
| Trend analysis | Long-term habit formation insights |

---

## 10. Project Structure

```
Andromida/
├── Andromida/                      # App target
│   ├── App/
│   │   ├── Localization/           # String catalogs
│   │   ├── Models/                 # SwiftData + DTOs
│   │   │   ├── Ritual.swift
│   │   │   ├── RitualArc.swift
│   │   │   ├── ArcHabit.swift
│   │   │   ├── Category.swift
│   │   │   ├── InsightCard.swift
│   │   │   ├── Milestone.swift
│   │   │   ├── OnboardingGoal.swift
│   │   │   └── RitualPresets.swift
│   │   ├── Protocols/              # Interfaces for stores/services
│   │   │   ├── RitualStoreProviding.swift
│   │   │   ├── RitualSeedProviding.swift
│   │   │   └── InsightTipsProviding.swift
│   │   ├── Services/               # Stateless logic
│   │   │   ├── ReminderScheduler.swift
│   │   │   └── RitualSeedService.swift
│   │   ├── State/                  # @Observable stores
│   │   │   ├── RitualStore.swift
│   │   │   ├── CategoryStore.swift
│   │   │   └── SettingsStore.swift
│   │   └── Views/                  # SwiftUI features
│   │       ├── Today/
│   │       ├── Rituals/
│   │       ├── History/
│   │       ├── Insights/
│   │       ├── Settings/
│   │       └── Onboarding/
│   ├── Shared/                     # Theme + branding + analytics
│   │   ├── Configuration/          # xcconfig files
│   │   ├── Services/               # RitualAnalytics
│   │   └── Theme/                  # RitualsTheme
│   └── Resources/                  # LaunchScreen.storyboard
├── AndromidaWidget/                # Widget extension
│   ├── Intents/                    # App Intents
│   ├── Models/                     # Widget-specific models
│   ├── Providers/                  # Timeline provider
│   └── Views/                      # Widget views
├── AndromidaTests/                 # Unit tests
├── AndromidaUITests/               # UI tests
└── Bedrock/                        # Shared design system package
```

---

## 11. Key Files Reference

| File | Purpose |
|------|---------|
| `Andromida/AndromidaApp.swift` | App entry point |
| `Andromida/Shared/Theme/RitualsTheme.swift` | Bedrock theme configuration |
| `Andromida/Shared/BrandingConfig.swift` | Branding constants |
| `Andromida/Shared/Configuration/Base.xcconfig` | Build configuration source of truth |
| `SWIFTDATA_CLOUDKIT_SYNC_REQUIREMENTS.md` | Reusable SwiftData to CloudKit sync standard and test checklist |
| `Andromida/Resources/LaunchScreen.storyboard` | Native launch screen |
| `Andromida/App/State/RitualStore.swift` | Primary data store |
| `Andromida/App/State/SettingsStore.swift` | Settings with cloud sync |
| `Andromida/App/State/CategoryStore.swift` | Category management |
| `Andromida/App/Services/ReminderScheduler.swift` | Notification scheduling |
| `AndromidaWidget/AndromidaWidget.swift` | Widget entry point |

---

## 12. Testing Requirements

| Requirement | Description |
|-------------|-------------|
| Unit tests in `AndromidaTests/` covering store logic and analytics |
| UI tests in `AndromidaUITests/` for critical user flows |
| Unit-test harness should use deterministic in-memory SwiftData setup to prevent host-app test instability |
| UI-test harness should run app launches with deterministic flags (`UITEST_MODE`, optional reset/onboarding overrides) and in-memory SwiftData |
| UI launch coverage should prioritize stable smoke validation over exhaustive simulator configuration matrices |
| UI coverage should include onboarding state transition validation and ritual creation flow from the Rituals tab |
| Test command: `xcodebuild test -scheme Andromida -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2'` |

---

## Revision History

| Version | Date | Description |
|---------|------|-------------|
| 1.0 | February 2026 | Initial PRD based on implemented features |
| 1.1 | February 2026 | Fixed time-of-day refresh bug in Today view and Widget; added debug time simulation |
| 1.2 | February 2026 | Added deterministic UI-test launch harness and expanded critical UI flow coverage |
| 1.3 | February 2026 | Added reusable SwiftData to CloudKit sync requirements, runtime expectations, and two-device verification standard |

---

## Known Limitations

### KIB-001 - Mac Runtime Inbound CloudKit Updates May Require Activation Transition

- **Summary**: On Mac runtime, inbound SwiftData+CloudKit updates from iPhone/iPad may not appear while app remains active.
- **Observed**: iPhone/iPad to iPhone/iPad sync is near-real-time; Mac to iPhone/iPad sync is near-real-time; iPhone/iPad to Mac may require foreground/background transition or relaunch.
- **Status**: Known platform/runtime behavior under investigation; not introduced by recent Bedrock safe-core extraction.
- **Tracking**: Detailed investigation notes are maintained in `BEDROCK_DEFERRED_REFACTOR_PLAN.md` under `Known Issue Backlog (KIB-001)`.