alaro

Read ALL documentation files in /home/dev/projects/alaro/docs/ (api-contract.md, app-state-and-sync.md, app-ui-behavior.md, delivery-architecture.md, scheduling-model.md, implementation-checklist.md). Then systematically compare the documented behavior against the actual Swift and Go code. For each discrepancy found where the code does NOT match what the docs describe: 1. Note the doc file, the relevant section, what the docs say, and what the code actually does. 2. Create a new task in this nightshift run via the dashboard API (POST http://127.0.0.1:9100/api/runs/{run_id}/tasks) for fixing that discrepancy. Each fix task should take 20-90 minutes and include the doc reference, what needs to change, and which files are likely involved. After creating all fix tasks, add one final task titled 'Commit, push, and merge to main' with description: 'Commit all remaining changes if any, push the branch, create a PR to main and merge it. Ensure origin/main has all changes. Commands: git add -A && git diff --cached --quiet || git commit -m "final: remaining fixes" && git push origin nightshift/docs-verification && gh pr create --title "Docs verification fixes" --body "Automated fixes from docs audit" --base main --head nightshift/docs-verification && gh pr merge --merge --delete-branch' Be thorough — check models, API endpoints, sync logic, scheduling, UI behavior, delivery/escalation, and the implementation checklist. Use the dashboard API to add tasks: curl -s -X POST http://127.0.0.1:9100/api/runs/<RUN_ID>/tasks -H 'Content-Type: application/json' -d '{"title": "...", "description": "..."}'

Doc: api-contract.md (Reminder writable fields) The docs say reminder writable fields are flat top-level fields: max_urgency, interval_minutes, stop_window_minutes, prearm_rescue. But the code nests them under an "escalation" object in both the request (ReminderRequest.Escalation) and response (Reminder.Escalation). What needs to change: - Go ReminderRequest: move max_urgency, interval_minutes, stop_window_minutes, prearm_rescue to top-level fields (remove Escalation wrapper) - Go Reminder: expose these as flat JSON fields instead of nested escalation object - Go store_normalize.go: update normalizeReminderRequest to handle flat fields - Go store_reminder.go: update CreateReminderWithStatus, UpsertReminderFromApp, scanReminder, sameReminderCreatePayload - Go server_handler_reminder.go: verify handlers work with flat shape - Swift APIClient+Reminder.swift and APIClientModels.swift: update request/response encoding to use flat fields - Update all tests that use the escalation nesting Files: cmd/alaro-server/models.go, cmd/alaro-server/store_normalize.go, cmd/alaro-server/store_reminder.go, cmd/alaro-server/server_handler_reminder.go, Alaro/Services/APIClient+Reminder.swift, Alaro/Services/APIClientModels.swift, cmd/alaro-server/reminder_store_test.go, cmd/alaro-server/reminder_e2e_test.go, cmd/alaro-server/server_test.go

Doc: api-contract.md (Read Model > Status semantics, Delete Contract > history ordering) Two related issues: 1. Alarm.syncStatus() (models.go:261-270) only produces "scheduled" or "deleted". The docs say "completed" for past non-deleted alarms in history. Past fixed alarms whose fire_at has passed should have status "completed", not "scheduled". 2. Alarm history detection in store_alarm.go uses enabled=0 as a history criterion. The docs say "alarms should use trigger time as their history event". History should be based on whether the alarm trigger time has passed, not the enabled flag. What needs to change: - Go Alarm.syncStatus(): add logic to compute "completed" for past alarms based on trigger time - Go store_alarm.go listAlarmsView: update history view query to use trigger time (fire_at < now for fixed, or an equivalent heuristic for recurring) instead of enabled=0 - Ensure alarm list ordering in history view uses trigger time as the docs specify - Update alarm tests to verify completed status Files: cmd/alaro-server/models.go, cmd/alaro-server/store_alarm.go, cmd/alaro-server/store_test.go, cmd/alaro-server/store_list_test.go

Doc: api-contract.md (Read Model, List response envelope, Alarm writable fields) Several undocumented fields leak into API responses: 1. List response envelopes (AlarmListResponse, ReminderListResponse) include "mirror_updated_at". The docs say the list response envelope should only contain: items, view, next_cursor. 2. Alarm struct has Enabled bool json:"enabled" which is not a documented alarm field. The docs alarm writable fields are: title, schedule, prearm_rescue, external_id. The read response should not include enabled. 3. Alarm struct has Revision int64 json:"revision,omitempty" - this is a server-managed field. The docs list specific read response fields and revision is not among them. Consider hiding it from the public API or documenting it. What needs to change: - Remove mirror_updated_at from AlarmListResponse and ReminderListResponse in models.go - Remove mirror_updated_at population in server_handler_alarm.go and server_handler_reminder.go - Change Alarm.Enabled to json:"-" or remove from JSON output - Evaluate whether Revision should be hidden (json:"-") in public responses - If mirror_updated_at is needed internally for sync, move it to a separate internal endpoint or the snapshot API only Files: cmd/alaro-server/models.go, cmd/alaro-server/server_handler_alarm.go, cmd/alaro-server/server_handler_reminder.go, cmd/alaro-server/store_alarm.go, cmd/alaro-server/store_reminder.go

Doc: api-contract.md (Read Model > Public status values) The docs define four public status values: scheduled, completed, expired, deleted. Issues in Alaro/Models/Reminder.swift: 1. ReminderStatus enum (line 37-73) is missing a "deleted" case. The init?(normalizing:) returns nil for "DELETED", and the computed var status defaults nil to .scheduled. This means deleted reminders from the server appear as scheduled in the app. 2. The normalizing init maps legacy undocumented statuses: CREATED, PENDING, NOTIFYING, ACTIVE -> scheduled; ESCALATED -> expired; ACKNOWLEDGED -> completed. The docs only define scheduled/completed/expired/deleted. These legacy mappings should be removed to match the documented contract. What needs to change: - Add .deleted case to ReminderStatus enum - Remove legacy status normalizations (CREATED, PENDING, NOTIFYING, ACTIVE, ESCALATED, ACKNOWLEDGED) - Only normalize the four documented values: scheduled, completed, expired, deleted - Update any Swift views that switch on ReminderStatus to handle the new .deleted case - Update the Reminder model status getter to handle deleted properly - Verify ReminderListView filter predicate still works (currently filters by statusRaw == "SCHEDULED") Files: Alaro/Models/Reminder.swift, Alaro/Views/Reminders/ReminderListView.swift, Alaro/Views/Reminders/ReminderHistoryView.swift, Alaro/Views/Reminders/ReminderHistorySupport.swift, Alaro/Views/Reminders/CompletedReminderDetailView.swift, Alaro/Views/Reminders/ExpiredReminderDetailView.swift

Doc: implementation-checklist.md (Section 1: Server API Contract) The checklist says: "remove notification_count from reminder request, update, storage, and read models" The Swift side is clean, but the Go server still has remnants: - cmd/alaro-server/store_migrate.go line 84: migration adds reminder_notification_count column - cmd/alaro-server/store_migrate.go line 345: table definition includes reminder_notification_count - cmd/alaro-server/store_test.go: multiple references to reminder_notification_count and notification_count (lines 36, 106, 148, 207, 329, 352) What needs to change: - Remove reminder_notification_count from the database schema (add a migration to drop the column, or if the column is still in the create table statement, remove it) - Clean up all test references to notification_count - Verify no other Go code references this field Files: cmd/alaro-server/store_migrate.go, cmd/alaro-server/store_test.go

Doc: app-state-and-sync.md (Local Records, SyncStateRecord, CapabilitySnapshot) The docs define five primary record types the app should persist. OccurrenceRecord, AlarmRecord (Alarm), ReminderRecord (Reminder), and TombstoneRecord exist, but two are missing: 1. SyncStateRecord (app-state-and-sync.md lines 132-153) - Should persist per-resource sync bookkeeping: resource_id, resource_type, dirty_state, last_enqueued_at, last_attempted_at, retry_count, pending_operation_type, last_error_code, last_error_at. Currently the app embeds sync state (dirty flag) directly on Alarm/Reminder models, which the docs explicitly say NOT to do ("Do not embed full sync bookkeeping into AlarmRecord or ReminderRecord"). 2. CapabilitySnapshot (app-state-and-sync.md lines 155-165) - Should persist: alarmkit_authorized, notifications_authorized, critical_alerts_authorized, reported_at, optional app_version. This is needed for the device capability reporting flow. What needs to change: - Create Alaro/Models/SyncStateRecord.swift as a SwiftData @Model with the documented fields - Create Alaro/Models/CapabilitySnapshot.swift as a SwiftData @Model with the documented fields - Refactor sync bookkeeping from Alarm/Reminder dirty flags into SyncStateRecord - Keep only lightweight local execution fields (local_schedule_state, local_delete_state) on the resource models Note: This is a larger refactor. The task should focus on creating the models and making the minimal integration. Full sync engine refactoring may be a separate effort. Files: Alaro/Models/ (new files), Alaro/Services/SyncEngine.swift, Alaro/Services/AlarmStore.swift

Commit all remaining changes if any, push the branch, create a PR to main and merge it. Ensure origin/main has all changes. Commands: git add -A && git diff --cached --quiet || git commit -m "final: remaining fixes" && git push origin nightshift/docs-verification && gh pr create --title "Docs verification fixes" --body "Automated fixes from docs audit" --base main --head nightshift/docs-verification && gh pr merge --merge --delete-branch