Backlog

For completed tasks, see 911-completed.

Priority Legend

[P1] - High priority: bugs, blockers, quality issues affecting UX
[P2] - Medium priority: improvements, polish, technical debt
[P3] - Low priority: future enhancements, ideas, nice-to-have

Bugs [P1]

Test Coverage [P1]

Current: 619 unit tests passing (Shared package, 2026-10-15) + 120 app unit tests (MinutaTests target, iPhone simulator, 2026-10-15)

Audit Findings (2026-01-03) [P1]

Dead Code:

Remove unused dayCellSize constant (2026-01-03)
- Removed from CalendarDatePicker.swift
Remove unused UIKit import from ContentView (2026-01-03)
- Location: ContentView.swift:2
- No UIKit types used in file
~~Remove unused UIKit import from SettingsSheet~~ (2026-01-03)
- False positive: UIPasteboard is used for copy-to-clipboard functionality
Remove unused DateRangePickerView.swift (2026-01-03)
- Location: Views/History/DateRangePickerView.swift
- 114-line file never referenced - CalendarDatePicker is used instead
Remove unused Color(oklch:) initializer (2026-01-03)
- Location: Color+Hex.swift:30-40
- Never called; only Color(hex:) is used
- Also removed unused contrastingTextColor(for: OKLCH) overload

Maintainability:

Extract layout constants in CalendarDatePicker (2026-01-03)
- Location: CalendarDatePicker.swift:75-91
- Created LayoutMetrics enum with named constants for cellSize, fonts, padding, opacity, etc.
Refactor duplicated date range logic in CalendarDatePicker (2026-01-03)
- Added endOfDay() and setDateRange(from:to:) helper methods
- Reduced duplicate “add day, subtract second” pattern from 5 occurrences to 1
Clean up verbose comments in CalendarDatePicker (2026-01-03)
- Removed redundant section labels and implementation detail comments
- Kept useful explanatory comments (corner radius logic, week selection criteria)

UI Tests:

~~UI test failures - History section not found, Export sheet not opening, Missing fixture data, Tag management flow~~ (2026-05-14)
- The “16 failures” list from 2026-04-15 is stale; targeted re-run on 2026-05-14 (iPhone 17 sim, iOS 18) showed all those tests passing.
Fix PDF preview flake on standard fixture (2026-05-14)
- Affected: ReportFlowTests.testPDFReportPreview, ReportFlowTests.testExportSheetStaysDuringGeneration
- Root cause: Done button wait used timeout: 15, but PDF generation through WKWebView.pdf() over the 138-record standard fixture runs ~16–60s on the iOS 18 simulator with high variance (PNG/SVG/CSV complete in ~5–10s; PDF-with-images on a 2-record fixture is unaffected).
- Fix: bumped both Done-button waits to timeout: 60 and added a one-shot retry path (tapPreviewAndWaitForDone(timeout:) helper) that dismisses any “Export Error” alert and re-taps previewButton. Verified: when the first 60s wait misses, the retry succeeds (134s total).
Mac Catalyst UI tests: pre-existing failures (discovered 2026-05-14; resolved 2026-07-10)
- Update 2026-07-10: full Catalyst suite is green (24/24 including all PerformanceTests) after the journey consolidation plus two Catalyst-specific fixes: historyDurationRecord() regex-matches labels in Swift instead of an NSPredicate MATCHES query (numeric labels in the Catalyst a11y snapshot made the predicate throw NSInvalidArgumentException), and the settings sheet is closed via its Done button (swipe-down on the main window does not dismiss a Catalyst sheet). Test launches also pin the window to 783x971pt (SceneDelegate sizeRestrictions) so runs no longer inherit the user’s last window size.
- Update 2026-07-03: fixes for clusters 1 and 2 have landed since the re-run — toolbar bar buttons now carry accessibilityIdentifiers plus identifier-or-label test predicates (b4df387), section headers matched case-insensitively via sectionHeader(), coordinate scrolls window-anchored via dragScroll(), document picker flakes and the TCC prompt fixed (db416f2, a00971f). Needs a fresh full Catalyst run to confirm what remains — likely just cluster 4 (PerformanceTests).
- Update 2026-07-02: cluster 3 below is resolved — testEditSheetMinWidthOnMac passes since WidthClampedFittedSizing (commit 58c27bf). Remaining failures are clusters 1, 2, 4 plus DocumentPickerStabilityTests (2) and TagSelectorTests.testTappingChipCommitsFullNameToField; testViewExistingRecords fails with a coordinate-scroll NSInternalInconsistencyException (point.x != INFINITY).
- Failures cluster around:
  1. Catalyst NSToolbar a11y missing — app.buttons["settingsButton"] / ["pinButton"] not found. The SwiftUI toolbar (ContentView.swift:62-73) is wrapped in #if !targetEnvironment(macCatalyst); the Catalyst replacement is SceneDelegate’s NSToolbar (MinutaApp.swift:140+) which sets item.label = "Settings"/“Pin” but never sets an accessibility identifier. Tests must query app.buttons["Settings"]/["Pin"] on Catalyst — or NSToolbarItems should expose the identifiers used by the iOS path.
  2. “Running” header not found after floatingPlayButton.tap() on Mac — affects RecordEditingTests.testAddCommentToTimer, testTapToEditRecord, TimerFlowTests.testStartAndStopTimer, etc. Needs screenshot inspection during failure (Mac may render the running section differently or below the fold).
  3. ~~testEditSheetMinWidthOnMac regressed (611pt vs 640pt min)~~ — resolved 2026-07-02 by WidthClampedFittedSizing (640–800pt clamp with height re-measure, commit 58c27bf); passes in the full-suite run.
  4. 3 PerformanceTests fail at ~24s (testExportSheetPerformance, testReportGenerationPerformance, testTagFilterPerformance) — needs investigation.
- Note: iPhone-sim tests pass for the same flows because iOS uses the SwiftUI toolbar path which does have identifiers wired up. The Mac CI lane has likely been red since the 7992a0a add mac pin button (wip - not working) commit.

Audit Findings (2026-10-02)

Full-project audit (8 auditors). Test runs that day: Shared 476/476 passed, iPhone UI tests 18 passed + 1 expected Mac-only skip, MinutaTests 36/36 passed, Mac Catalyst UI tests did not build (first entry under “Build, tests, CI”). Each entry carries its own priority tag. “Reproduced” means run against a temp storage folder with the built CLI; “by reading” means traced in code and not executed.

Data integrity:

Record edit across a month boundary duplicates the record [P1] (reproduced; fixed 2026-10-02)
- Fixed: AutomergeStorageService keeps an id-to-months index that survives cache eviction; updateRecord and deleteRecord refresh it under the lock from changed mtimes, write the target month, move the image files, then remove the id from the other months. deleteRecord also handles a stale start time. minuta doctor got a duplicate records check (warning)
- Existing duplicates are not collapsed on read (no reliable “newer copy” signal): saving one copy removes the others, deleting removes only that month’s copy
- Tests: 10 unit tests in AutomergeStorageServiceTests / AutomergeStorageConcurrencyTests, CLI testRecordsEditStartAcrossMonths_noDuplicate and testDoctor_reportsRecordInTwoMonths, UI RecordEditingTests.testMoveRecordToPreviousMonth (both platforms; verified failing with the move disabled)
- Not done, see follow-ups below: fixed-calendar bucketing and the timezone edge
- Location: AutomergeStorageService.swift:263-287; updateRecord is saveRecord, which writes into the month document of the new startTime and never deletes the key from the old month document
- Repro: minuta records add --start 2026-04-22..., then records edit <id> --start 2026-03-22...: the same ID is in 03.automerge and 04.automerge, records list shows it twice. Reachable from the editor (RecordEditorViews.swift) and the CLI (RecordsCommand.swift:263,292); a timezone change near a month boundary has the same effect
- Images are keyed by start month too (imageURL, :331), so attachments stay in the old records/YYYY/MM/ folder
- Fix: updateRecord looks up the old month (or takes the previous record), deletes from the old document and moves the images under the same lock; consider bucketing by a fixed calendar instead of Calendar.current
- Tests first: AutomergeStorageServiceTests.testUpdateRecordAcrossMonthMovesRecord (plus year boundary) and a UI test in RecordEditingTests; the legacy store already has testUpdateRecordWithDateChangeMovesFile
- Also decide how to repair folders that already contain duplicates (minuta doctor check)
External-change probe is always true with 13+ month files [P1] (confirmed by a failing test; fixed 2026-10-02)
- Fixed: eviction no longer drops recordDocumentMtimes; saveRecordDocument takes the document explicitly (it used to skip the write silently when the document had been evicted); a failed save discards the mutated cached document
- Tests: testHasExternalChanges_falseAfterLoadAllWith13Months, ..._detectsWriteToEvictedMonth, ..._detectsDeletedEvictedMonthFile, testFailedSaveRecord_unsavedRecordNotServedLater, testFailedDeleteRecord_recordStillServedLater
- Location: AutomergeStorageService.swift:209-217 (eviction also drops recordDocumentMtimes) and :383-389 (hasExternalChanges treats a month file without an mtime entry as new)
- loadAllRecords() always leaves at least one month evicted once there are more than 12, so the 5s probe fires invalidate + conflict resolution + full reload forever
- Fix: track observed mtimes separately from the document cache and never evict them; fix the stale comment at :13 (“12 covers ~2 weeks of daily records”, documents are per month)
- Test: unit test with 13 month files asserting hasExternalChanges() is false after a full load; add the “cached month file deleted” case
Conflict resolution writes outside the storage lock [P1] (fixed 2026-10-02)
- Fixed: each conflict group is merged inside StorageFileLock.withExclusiveLock; the primary is written before merged copies are deleted (the old order lost a merged copy when a later sibling was corrupt); a corrupt copy stays on disk and is reported in errors; the scan takes no lock
- Tests: testValidCopiesMergedDespiteCorruptSibling, testResolveConflictsWaitsForStorageLock, testNoConflicts_doesNotTakeLock
- Location: ConflictResolutionService.swift:106-119; mergeConflictFiles reads, merges, deletes conflict copies and rewrites the primary without StorageFileLock.withExclusiveLock
- Runs on every scene activation and external-change reload (MinutaApp.swift:669,830,866-880) and from minuta conflicts resolve, so it can clobber a concurrent app/CLI write
- Test: hold the lock on a second fd and assert resolveConflicts blocks, or race it against saveRecord
CSV export does not escape tag names [P1] (reproduced; fixed 2026-10-02)
- Fixed: every field goes through escapeField; columns follow ExportOptions.Column.allCases, so the header is Date,Start Time,End Time,Duration,Tag,Comment (it was alphabetical: Comment,Date,Duration,End Time,Start Time,Tag); duplicate tag ids no longer trap in ExportService and ExportCommand
- Tests: testExportEscapesCommaAndQuoteInTagName, testExportHeaderExactOrder, testExportSelectedColumnsKeepCanonicalOrder, testExportRecordSpanningMidnight, testExportDuplicateTagIdsDoesNotCrash, CLI testExportCSV_duplicateTagIdsInStorage_doesNotCrash
- Location: ExportService.swift:88-93; only the comment goes through csvParser.escapeField, a tag named A, B shifts the columns
- Same pass: pin the header with an exact-order test (code emits Start Time / End Time, CLAUDE.md documents Start / End; the audit also reported the columns come out sorted by raw value), and guard Dictionary(uniqueKeysWithValues:) at :16 against duplicate tag IDs
- Tests: testExportEscapesCommaAndQuoteInTagName, exact header order, record spanning midnight, running record row
Undo delete of a record with images [P1] (reproduced by a UI test; fixed 2026-10-02)
- Fixed: soft delete removes the record but keeps its image files (TimeTrackingService.deleteRecord(_:keepingImages:), purgeImages(of:)); files are purged on expiry, swipe-dismiss or storage switch; undoDelete is a no-op once the entry is gone and re-inserts it when the re-save fails; a second delete of the same record while one is pending is ignored; operations in flight across a storage switch no longer touch the new folder
- Also fixed on review: deleteRecord deletes image files only after the document write succeeded; the editor writes the saved value back to currentRecord (a start-date change followed by adding a photo used to revert the date)
- Tests: UI RecordDeletionTests.testDeleteUndoJourney (both platforms), 10 app-target tests in AppStateSoftDeleteTests, Shared tests in TimeTrackingServiceIntegrationTests
- The UI test fixture conversion now moves image files along with the date shift (with-images never showed real images before)
- softDeleteRecord deletes from storage immediately (MinutaApp.swift:1092-1108) and deleteRecord removes the image files (AutomergeStorageService.swift:290); undo re-saves the record but the files are gone
- Reproduce with a UI test first; then either defer the image deletion until the toast expires or restore the files on undo
HybridStorageService.invalidateCache() returns before invalidating [P2] (fixed 2026-10-02: now async, awaits both stores)
- Location: HybridStorageService.swift:115-120 wraps the work in an unstructured Task; AppState.reloadFromExternalChanges awaits it and reloads straight away (MinutaApp.swift:827-832,872)
- Fix: make it async and await both inner calls
Coalesce AppState.loadData and fix stale history after external edits [P2] (by reading) (done 2026-10-15)
- Was: History reloaded only on the date range, todayRecords, historyRevision (undo of a delete) and storageWarnings, so a record of an earlier day added, edited or deleted by the CLI or a sync stayed stale until the range changed (reproduced by the UI test below, which failed before)
- Now: every published load bumps historyRevision; ContentView reloads History through one .task(id:) keyed on the range, revision, today’s records, warnings and whether an editor or the share sheet is open (closing it reloads what was skipped), and a newer reload cancels an older one. Lists are published only by a load not older than the last published one and started after the state’s last local change (noteLocalChange()), otherwise it loads again; a failure is reported only by such a load; isLoading counts loads in flight; running timers come from the same loadAllRecords() pass as the tag usage (one full scan per load instead of two)
- Tests: UI ExternalChangeTests.testHistoryFollowsExternalChanges (failed before), AppStateLoadTests.testLoad_bumpsHistoryRevision (failed before), AppStateLoadTests.testLoadOvertakenByStartAndStop_keepsTheChange (a guard: the stale publish needs a load’s reads to straddle a write in storage and did not reproduce on the old code)
- Left: a seam to inject storage into AppState, to reproduce the stale publish deterministically
- loadData (MinutaApp.swift:882-917) is entered from at least six places with no coalescing or generation token: a slow older load can overwrite optimistic state or write the previous folder’s data after reinitializeStorage; isLoading flips false while another load runs; each load scans the full history twice (tagLastUsedAt + getRunningTimers)
- ContentView.swift:106-113 reloads history only on date range or todayRecords change, so an external edit to an older record or a tag merge leaves history stale; the two date onChange handlers spawn unordered Tasks
- Fix: load-generation counter or single in-flight task; dataRevision bumped in loadData driving one .task(id:) keyed on (start, end, revision)
mtime cache trusts an unchanged mtime on write paths [P2] (by reading) (done 2026-10-15)
- Was: saveRecord / updateRecord / deleteRecord reused the cached month document when the stamp (mtime and size) was equal and wrote it over the file; on exFAT, SMB or sync folders with 1s granularity an external write in the same tick with the same size was lost. The backlog’s test idea (restore the mtime) alone did not reproduce it: the size changed too
- Now: every record write and the consolidation in refreshIndexLocked read the month from disk under the lock (workingDocument(fresh: true)). Tests: AutomergeStorageConcurrencyTests.test{Save,Update,Delete}AfterSameStampExternalWrite_keepsTheExternalRecord (a same-size file with the same mtime; all three failed before)
- Left: the id-to-months index is still refreshed by stamp, so a record another process moved to another month within the same tick and size is not cleaned from the old month (a duplicate, reported by minuta doctor)
Widget publish path is not isolated in test mode or on Catalyst [P2] (by reading) (done 2026-10-15)
- Was: AppState.syncWidgetData ran under --test-storage= and on Catalyst and reached the real App Group container and suite (WidgetDataService.swift, RecentTagsStore.swift); app unit tests wrote their tags into the real recent-tags list
- Now: WidgetDataService.forApp(testLaunch:) publishes nothing for a test launch and on Catalyst, RecentTagsStore.forApp(testLaunch:) uses its own suite for a test launch; used by AppState and WidgetIntentService.live(). Tests: WidgetIntentServiceTests.testTestLaunch_publishesNothingAndKeepsRecentTagsOutOfTheAppGroup, AppStateEditorSaveTests.testTestLaunch_doesNotTouchTheAppGroupRecentTags (failed before)

Build, tests, CI:

Release and scripts:

Site would advertise 1.0.4 while only 1.0.3 artifacts exist [P1] (resolved 2026-10-03 by releasing 1.0.5 (7) / CLI 0.1.3 everywhere: notarized Homebrew artifacts, tap ed3711d, site deployed with version.json 1.0.5, TestFlight iOS and Mac App Store uploads; the release orchestrator now enforces artifacts before the site)
- 7ee2710 bumped all three targets to 1.0.4 (6) for the Mac App Store upload; minuta.tools/src/lib/appVersions.js:15 feeds the first MARKETING_VERSION into /downloads/version.json and the download link, dist/ and the server hold Minuta-1.0.3.zip
- Until fixed, do not run deploy.sh from HEAD: Homebrew users would see “Update available” pointing at a missing file
- Fix: either ship 1.0.4 through release-brew.sh (artifacts, tap, then site), or give the site its own “latest Homebrew release” source instead of project.yml
release-brew.sh fallback path and pipefail traps [P2] (fixed 2026-10-03 with the release orchestrator: empty-array-safe XCARGS, captured security output, no | head inside substitutions)
- :134-140: under set -u, "${XCARGS[@]}" on an empty array aborts on macOS bash 3.2 (unbound variable), so the documented path without DeveloperID.xcconfig or with MINUTA_NOTARIZE=0 dies before building
- :50-57 (also :33-36): SIGN_ID="$(security ... | grep ... | head -1 | sed ...)" exits 1 when nothing matches, set -e kills the script and the friendly error at :53-57 is unreachable; the script already documents this trap at :147-148
Script safety and duplication [P2] (deploy.sh part done 2026-10-03: set -euo pipefail and cd to its own directory)
- scripts/generate-perf-fixtures.sh:9,14 and scripts/generate-standard-fixture.sh:16,20: rm -rf "$OUTPUT_DIR" on a path relative to the caller’s cwd; resolve the repo root from $0 and use set -euo pipefail
- minuta.tools/deploy.sh has no cd "$(dirname "$0")" before rsync --delete build/; the remote host is duplicated in scripts/upload-brew-artifacts.sh:11
- scripts/run-ipad.sh is byte-identical to run-iphone.sh; MARKETING_VERSION is repeated three times in project.yml while release-brew.sh:35 reads head -1
- generate-standard-fixture.sh (260 lines) is referenced nowhere: document it or drop it
Personal data and large files in the repo and on the site [P2]
- The holder’s full name is in the tracked Minuta/ExportOptions-mac.plist:22 (required there) and repeated in docs that are served publicly (702-testflight:246, 919-plan-mac-distribution:159, this backlog); the next deploy publishes it on 702. Refer to the plist instead of repeating the identity string
- ImageAttachmentTests/03-photo-picker.png (1.8 MB) is stored twice (snapshots + site screenshots); it is a system photo-picker shot, the same class as the Finder panels banned on Mac
- The four DocumentPickerStabilityTests Finder-panel screenshots removed in d43bac2 are still in history; matters only if the repo goes public
Build config leftovers and stale config comments [P3]
- Minuta/TestFlight/MinutaWidgets.macOS.entitlements is unused: TestFlight-mac.xcconfig maps the widget to TestFlight/MinutaWidgets.entitlements
- project.yml:205-207 and CLAUDE.md describe MinutaArchive as “without MinutaTray”, but release-brew.sh:132-133,156 relies on it building and signing Tray as an implicit dependency
- TrayIconManager.swift:59-60 says the bundle is embedded under Resources (project.yml uses copy: plugins); project.yml says Catalyst avoids the group.* app group while Minuta.macOS.entitlements includes it
- .gitignore:58-61, 69-70 dead report-generator entries; --keep-animations debug flag (MinutaApp.swift:217-221) is undocumented
- Keep version bumps in their own commits (1.0.3 and 1.0.4 bumps rode in feature commits)

CLI:

-q/--quiet and -v/--verbose are advertised but not implemented [P2] (done 2026-10-15)
- Was: declared in Minuta.swift and the help; read only by doctor and the unreadable-file warning
- Now: informational stderr goes through CLIGlobalOptions.info (silenced by -q; error: lines stay), -v prints the storage folder, its source and the .minuta-version state through CLIGlobalOptions.debug. Tests: MarkerAndOutputIntegrationTests (-q on tags add, records add, export csv; errors kept; -v output)
Exit code 5 can never be returned [P2] (reproduced) (done 2026-10-15)
- Was: requireVersionMarkerForWrites always wrote the marker (garbage and newer versions such as 2 overwritten with 1); strictRequireVersionMarker, the only thrower of code 5, had no callers
- Decided: absent marker is created (new folder), older upgraded; newer version or not a number refuses the write with exit code 5, marker and data untouched; reads work. StorageVersionMarker.writeCurrent (app too) never downgrades or overwrites such a marker; doctor FAILs on it. CLIExit.versionMarkerAbsent renamed versionMarkerIncompatible, strictRequireVersionMarker removed. Tests: MarkerAndOutputIntegrationTests (fresh folder, newer, garbage, reads, doctor; failed before), 3 in StorageSafetyTests
- Left: the app itself does not refuse to write into a folder marked with a newer version
stop handles IDs differently from every other command [P2]
- StopCommand.swift:13,30 takes --id as an option and requires a full UUID; records show/edit/delete/image take a positional ID and accept an 8-char prefix (RecordsCommand.swift:352-376); status prints only 8-char prefixes, so its output cannot be fed to stop --id
- --all (:16-17) is declared and never read
CLI help text contradicts behaviour [P2]
- RecordsCommand.swift:231 “Pass an empty string to reopen the timer” vs :268-272 rejecting it (only --clear-end works)
- RecordFilters.swift:9 mentions a --tz flag that does not exist
- ExportCommand.swift:90-93 says --from / --to default to the current month, :193-198 requires both if either is given
Unify range filters across CLI commands [P2]
- export report --prev-month (ExportCommand.swift:96) vs --last-month (RecordFilters.swift:43); export report re-declares --from/--to/--tags/--untagged instead of using the shared RecordFilters group, so it lacks --today, --this-week and the rest
Regularize --json output shapes [P2]
- Tag mutations return {"tags":[one]}, record mutations {"record":{...}}; import hey emits "records": <count> where elsewhere records is an array; delete payloads differ between records and tags
- The JSON writer is copy-pasted seven times while RecordOutput.writePayload is private; document the shapes in 311-cli
Align app and CLI behaviour for the same operations [P2]
- Rename collision: the app merges into the existing tag (MinutaApp.swift:1037-1039), the CLI rejects it (TagsCommand.swift:198-202)
- Colour validation: tags recolor validates hex, tags add --color stores anything (TagsCommand.swift:155)
- HEY import: the app creates records through updateRecord inside the view (SettingsSheet.swift:298-334), the CLI uses createManualRecord with --resume dedupe (ImportCommand.swift:81-104); move “apply parsed import” into ImportService and call it from both
- TimeTrackingService: createTag validates but does not dedupe, getOrCreateTag dedupes but does not validate or trim and throws TagError.emptyName for “not found after create” (:41-67); use [Tag].findByName instead of the eight inline case-insensitive compares
CLI plain-mode output conventions [P3]
- stdout carries started <uuid>, a bare uuid, or stopped <uuid> (dur) depending on the command; records edit and tag rename print nothing; “no running timers” goes to stderr in stop and stdout in status; StartCommand is the only command without the execute() split
- Stale comments: CLIExit.swift:4 points at docs/300-services/304-cli/ (it is 311-cli); StorageResolver.swift:50-53 says it normalises via getpwuid but uses expandingTildeInPath

Code quality:

Documentation:

Follow-ups from the P1 fixes (found 2026-10-02):

Restored record lands in Today regardless of its date [P2] (done 2026-10-13)
- undoDelete (MinutaApp.swift) inserts the restored record into todayRecords unconditionally (it also counts toward Today’s total), and nothing re-adds it to HistorySection’s local list until the next reload; visible in the RecordDeletionTests 04-restored snapshot
- Now: the record returns to todayRecords only if it starts today, and AppState.historyRevision makes ContentView reload History. Tests: AppStateSoftDeleteTests.testUndoOfOlderRecord_notInsertedIntoToday, testUndoOfTodayRecord_backInToday, UI RecordDeletionTests.testUndoRestoresOlderRecordToHistoryOnly (skipped on the 25th and 26th, when a fixture record is of today)
Duplicate tag ids crash the app and reports [P2] (done 2026-10-07)
- Was: document keys that differ only in letter case parse to the same UUID, so duplicates are reachable from storage, and Dictionary(uniqueKeysWithValues:) trapped in AppState.rebuildTagsByID (the app crashed on load), ReportData.build (export report), stop, import hey (by id with --resume and by lowercased name), the two report image providers and the legacy FileStorageService cache
- Now: every lookup is built with uniquingKeysWith (first wins), as ExportService already was; no uniqueKeysWithValues is left in the sources. Tests: AppStateDuplicateTagTests, ReportServiceTests.testBuildWithDuplicateTagIdsDoesNotCrash, three in CLIIntegrationTests
- Left: storage still hands out both tags (the app lists the twin as a second tag); whether to normalize key case on load is open
Unparseable month file [P2] (done 2026-10-05, with the tags file included)
- Was: one unreadable MM.automerge made loadAllRecords throw (nothing loaded in the app, most CLI commands exited 1), hasExternalChanges() stayed true forever (full reload every 5s), nothing could be saved into that month, and a zero-byte file was read as an empty document and overwritten by the next save. A release build showed none of it: errorMessage is only visible in the Debug view
- Now: an unreadable or zero-byte file is never overwritten, renamed or deleted. Reads skip it; new records for that month go to MM.recovery.automerge, which is merged into the month file and removed once the file reads again (merge plus a fix-up for records that exist as two independent objects). The per-file stamp is (mtime, size); files that could not be opened are retried every 60s. Edits and deletes of records hidden inside an unreadable file are refused with a named error instead of being queued
- tags.automerge unreadable: no recovery file; the app keeps its last known tags, tag edits are refused, entries keep their tags. Also fixed on the way: the editor erased a record’s tag on any save while tags were missing, a timer with a tag that could not be created started untagged, the in-app HEY import imported untagged
- UI: banner under the toolbar plus a “Storage problems” section in Settings; alerts for refused save, stop, delete and tag operations. CLI: one stderr warning on commands that read records; doctor names each unreadable file, keeps duplicate records and image integrity meaningful, adds a recovery files row and an unreadable JSON array; export, records list --csv, import hey --resume and tags delete refuse when an unreadable month is in range
- ConflictResolutionService: no longer overwrites a zero-byte base file; a lone conflict copy with no base file is promoted instead of being ignored
- Docs: 312-automerge-storage-service, 506-cross-process-safety, 416-storage-warnings, 311-cli
- Not done, see “Follow-ups from the unreadable-file work” below
Soft-delete leftovers [P2]
- Quitting (or iOS killing the app) inside the 60s undo window leaves the deleted record’s image files as orphans; only minuta doctor reports them. Consider purging on termination or a launch-time sweep limited to ids the app itself deleted
- Deleting a record another process moved to a different month within the last 5s keeps a stale start time in the pending entry: the purge looks in the old month folder, and undo restores the record into the old month while its files sit in the new one
- softDeletesInFlight is not cleared on a storage switch; the reinitialize purge has no test
Record editor save edge cases [P2] (done 2026-10-13)
- Done 2026-10-05: onRecordUpdated fires only after a successful save; a failed save or stop shows an alert and keeps the editor open; buttons are disabled while an action is awaited
- Was: a save and an image add/remove could overwrite each other in storage, since each writes the whole record from its own snapshot. Now they run one at a time through SerialWriteQueue and read the record at their turn
- Was: the debounced auto-save was not cancelled on Stop or on the delete of a running timer, so it wrote the stopped timer back as running or re-created the deleted one (both reproduced at AppState level). Now Delete, Save and Stop cancel it, and it goes through AppState.autoSaveRunningTimer, which refuses a timer that left runningTimers or is being stopped or deleted (covers a stop from the mini window, Stop All and the tray)
- Tests: AppStateEditorSaveTests (9). No UI test: XCUITest takes about 4 seconds between a keystroke and the next tap, far outside the 300 ms window, and nothing can slow storage down for the image case; the editor’s use of the queue is covered only by the existing editor and image UI tests
- Left: ~~a stop through Shortcuts or the widget does not go through AppState, so until the next reload an auto-save can still reopen that timer~~ (fixed 2026-10-15, see “Route Shortcuts intents through WidgetIntentService”); a stop from the mini window uses its own copy of the record and can drop a keystroke typed in the main window in the last 300 ms
Storage move leftovers [P3]
- Timezone: loadRecords opens only the months of the range under the current calendar, so a boundary record bucketed in another timezone can be missed; widen monthsBetween by a day on each side or bucket by a fixed calendar
- A month document emptied by a move stays on disk as an empty file; deleteRecord for an id found nowhere still writes the start-month document; deleteRecord over several months can fail after an earlier month’s copy is already gone
- Every updateRecord / deleteRecord walks the records directory under the lock; negligible per call but multiplied in tag merge and the in-app HEY import (which calls updateRecord for brand-new records, SettingsSheet.swift:329)
Catalyst CI open questions [P2]
- Done 2026-10-13: the Catalyst UI-test step runs only on a manual run (workflow_dispatch, gh workflow run build.yml); on every push it took over the interactive session of the runner, which is the development machine. Not verified in Actions until the change is pushed
- Ad-hoc signing is unverified on a machine without an Xcode account for the team; each ad-hoc build is a new code identity, so macOS privacy grants do not persist between runs
- /private/tmp/MinutaUITests/ is left behind between runs
UI test findings [P2]
- FilterTests “Navigate previous month” is a silent no-op: it looks for buttons labelled chevron.left under if leftButtons.count >= 2, but the chevrons are labelled Back / Forward and the month toggle is not a button on Catalyst
- The historySection identifier on the History Section overrides its descendants’ identifiers (shareButton, recordRowImageThumbnail, historyRecordDuration)
- dragScroll at dx: 0.5 over the expanded calendar selects a date range instead of scrolling (its doc comment claims otherwise); the historyDurationRecord() comment is outdated (Today rows carry the identifier too)
- AppStateSoftDeleteTests fixture record starts at now minus 2h, so one todayRecords assertion depends on the clock between 00:00 and 02:00
- BareRecordEditorTests.testOpenEditorForBareRecord failed once on Mac Catalyst as the first test of a full run (2026-10-07): “Failed to get matching snapshot” for the Total: label right after waitForExistence; passed 4 of 4 alone
- Fixed 2026-10-13: StorageWarningTests.testStartTimerErrorIsShown failed on Mac Catalyst on every run that day (the click on the error toast’s x did nothing), also on the sources that passed on 2026-10-07. The x had a 7 by 7 point hit area; it is now padded. Why the same click hit it a week earlier is not established
Small leftovers [P3]
- scripts/release-brew.sh:128-130 comment still says the Minuta scheme builds MinutaWidgets on Catalyst
- Docs: 301-file-storage “Record Caching” section describes the legacy cache as current; 403-app-state snippet still shows @Published var pendingDeletion; 412-deletion-toast Related points at 402-ios for the toast container (it is in ContentView); 311-cli synopsis minuta doctor [--json] omits -v, and its duckdb example sums the H:MM Duration string; 305-storage-location:64 still calls the Mac App Store build “Planned”; 914-plan-cli-tool:272,309 shows --tag as the filter flag

Follow-ups from the unreadable-file work (found 2026-10-05):

Errors that are still invisible in release builds [P2] (done 2026-10-07)
- Was: AppState.errorMessage is shown only in the DEBUG DebugStateView, so every action without an alert of its own failed silently
- Now: those actions call AppState.reportError and the message shows as an error toast (417-error-toast) in the main window, Settings, the CSV export sheet and the mini window: start (play button, Cmd+N, tray, mini window), Stop All (Cmd+., tray), the mini-window drop button, tag create/archive/unarchive, Reset Colors, undo of a delete, loadHistoryRecords, the Settings CSV export, a failed loadData (stays until a load succeeds). Image add/remove in the editor shows an “Image Error” alert like the editor’s other failures
- Left: a tray command that fails while no window is open is gone after 10 seconds unseen; App Intents report through the intent’s own error
Phantom Fonts panel keeps coming back in Mac UI tests [P2] (found 2026-10-05, fixed 2026-10-06)
- Cause: with a non-Latin keyboard layout active (Russian), XCUITest typeText reaches the app as Command chords, so typing a comment started timers (Cmd+N), minimized the window (Cmd+M) and opened Fonts (Cmd+T); tests kill the app, so AppKit window restoration brought the panel and the minimized window back on every later launch. The NSFontPanelAttributes default was a red herring
- Fix: the UI test base class switches to an ASCII-capable layout per test on Catalyst and restores it, and launches with -ApplePersistenceIgnoreState YES; the app’s Format menu is removed in AppDelegate.buildMenu
Unreadable-file leftovers [P3]
- No in-app action to give up on a lost original; the user moves or deletes it in Finder or Files and the recovery file takes its place on the next write
- A stale update of a record that lives only in an unreadable recovery file next to a readable original is still accepted; saveRecord with an existing id whose copy sits in an unreadable month leaves a duplicate after repair; deleteRecord with a stale start time pointing at a readable month while the record sits in an unreadable one is a silent no-op
- Lone-copy promotion in ConflictResolutionService applies to any .automerge file in the folder whose name matches a conflict pattern
- WidgetIntentService.publish() still loads tags, so with unreadable tags and no live app a widget start does not refresh the widget snapshot
- CLI: --this-month-style ranges end at the next month’s first instant, so an unreadable next-month file also blocks an export; with unreadable tags records show --json gives "tag": null with only the stderr line as a signal; a default records list with no date filter walks every month from 1970 to 2100
loadData across a storage-folder switch [P2] (done 2026-10-07)
- Was: it read trackingService from self after its first await while storage was captured before it, so a switch during the load read tags and records from the new folder and tag usage from the old one; tags, todayRecords, runningTimers and tagLastUsedAt were assigned without the folder guard that storageWarnings had
- Now: both services are captured together and nothing is published once the folder has changed (migrationChecked, isLoading and the load error included); reinitializeStorage also clears tagLastUsedAt. Test: AppStateErrorNoticeTests.testLoadOvertakenByStorageSwitch_doesNotPublishOldFolder
NewTimerSheet is unreachable [P3]
- showingNewTimer is never set to true; either wire the sheet up or remove it
Home-directory path in published screenshots [P2] (done 2026-10-07)
- Confirmed: the iPhone snapshots of Settings (SettingsTests 02-settings-open, TagManagementTests 02-settings-open) showed the simulator path under the developer’s home directory in the “Data Folder” row
- Now: simulator test storage lives in /private/tmp/MinutaUITests/, the folder Mac Catalyst already used, so the row shows that path on both platforms
- Left: the old images are in git history, and the live site keeps them until the next deploy

Code Quality [P2]

Remove debug cellBorder() from HistoryGrid (2026-09-07)
- Was only wrapped in #if DEBUG, so Debug builds (and every screenshot) showed gray cell outlines that Release/TestFlight builds did not. Removed the gray cellBorder() and its six call sites for good; the colored gridBorder() outlines (green around a month’s days grid, orange around a day’s records) lost their #if DEBUG and are part of the design in all builds
Split AppState into smaller services
- Location: MinutaApp.swift (320+ lines)
- Handles: state, tags, records, deletion undo, tag merging
- Consider: TagManagementService, RecordManagementService
Split RecordEditorViews
- Location: RecordEditorViews.swift:1-450 (450+ lines)
- Mixed concerns: display, editing, formatting, image operations
- Extract image handling to separate component
Consolidate history reload triggers (2026-01-03)
- Merged two .task modifiers into one for initial load
- Added comments explaining each reload trigger
- Location: ContentView.swift:113-126

Performance [P2]

Layout optimization (2026-07-12)
- Covered by the HistoryGrid work below: row-per-month restructure (List cell reuse), sticky labels via onGeometryChange, removed dead DEBUG debugInfo state that re-evaluated the whole page every scroll frame
- Scroll confirmed smooth after the fixes; further ideas tracked in the HistoryGrid entry below
Improve HistoryGrid performance (2026-07-09)
- Root cause of year-range slowness: the whole grid was a single List row containing eager nested Grids, so a year selection built every record view upfront (the progressive-loading LoadMoreTrigger had been removed by then)
- Fix: HistoryGrid restructured into HistoryMonthRow — HistorySection emits one List row per month, so the List’s native cell reuse only builds on-screen months. Columns still align across months via fixed HistoryColumnSizes widths. Editor sheet moved into the month row owning the edited record.
- Grid geometry reporting (GridDebugPreferenceKey and friends) kept in release — part of the design, not debug-only
- Follow-up (scroll felt janky after the restructure): sticky labels moved from GeometryReader+onChange to onGeometryChange; removed dead DEBUG debugInfo state in ContentView that re-evaluated the whole page on every scroll frame (its preference emission in the grid stays — part of the design)
- Remaining ideas if profiling still shows hotspots: one List row per day instead of per month (bounds cell-build cost — the likely fix if big months still hitch on scroll-in), incremental re-grouping on single-record edits (updateFilteredRecords() re-groups everything), debounce filter changes
- Related: 801-optimization-plan Phase 6, 802-scroll-profiling, 803-load-more-bug
Investigate slow year report generation
- Year range report is noticeably slow (about 500 records)
- Profile SVGReportRenderer and WebKitReportService
Add pagination for large record sets
- Location: FileStorageService.swift:218-256
- All records loaded into memory - problematic for years of data

UI/UX Improvements [P2]

Add 300ms debounce to record saving while editing (2026-06-01)
- Already implemented for running timers: scheduleSave() cancels the prior saveTask and sleeps 300ms before saveChanges(createTag: false) (RecordEditorViews.swift:412-419), wired to tagInput/editedComment/editedStartTime onChange handlers (:386-394). createTag: false avoids creating tags mid-typing (tags created on timer stop).
- Completed records intentionally keep explicit Save/Cancel (Cancel discards). Extending auto-save there is a separate behavior change (Cancel/tag-creation semantics) — not part of this item.

Infrastructure [P2]

Fix GitHub Actions
- Figure out good way to run and fix setup
Monorepo structure (turborepo or bazel)
- Build and screenshots cached, triggered on code changes
- Use code hash as cache key

Publishing [P2]

macOS Enhancements [P3]

Minified/PiP mode (Mac only) (2026-08-06)
- Plan: 916-plan-pip-mini-timer — supersedes the same-window sketch below with a companion-window design; shipped as the mini timer window (pip toolbar button + tray icon), docs at 400-ui/415-mini-timer-window
- Compact floating view showing only running timers
- Toggle via pip icon in title bar toolbar (next to pin/settings)
- Layout: small window with just timer list + play button
- Behavior:
  - Remembers minified state separately from main window size
  - Works with existing pin (always-on-top) feature
  - Hides History section, Today section, settings button
  - Shows: running timers, floating play button, expand button
  - Expand button (pip.exit) returns to full view
- Implementation:
  - Add isMinified state to WindowPinManager (rename to WindowStateManager?)
  - Add pip toolbar button in SceneDelegate
  - Conditionally render sections in ContentView based on minified state
  - Animate window resize transition
  - Store minified window frame separately in UserDefaults
- Related: pairs well with pin button for “mini always-on-top timer”
Menu Bar app
- Mostly shipped 2026-08-06 via 916-plan-pip-mini-timer: tray icon with play symbol, summon/hide mini window, quick start/stop menu
- Remaining (deferred there): per-timer rows with ticking elapsed in the right-click menu, elapsed text next to the icon — needs timer snapshots across the tray bridge
Always-on-top widget (superseded by Minified mode above)
- Floating window with current timer state
- Minimal, non-intrusive design

Widgets [P3]

Home Screen / Desktop widgets (WidgetKit) (2026-01-05)
- Small: running timer with stop button, or today summary with start button
- Medium: running timer + quick start tags with interactive buttons
- Large: running timers list with stop buttons, today summary, quick start tags grid
- App Groups for shared data (group.tools.minuta.apps)
- Timeline provider with 1-minute updates for running timers
- Interactive buttons using App Intents (start/stop timers)
- Note: Widget extension enabled 2026-08-29, iOS only (platformFilter: iOS); Catalyst builds ship without widgets
Time by Tag widget (2026-10-13)
- Home screen widget, medium and large: hours per tag for a period chosen in Edit Widget (Today, This Week, This Month), total in the header, the rest folded into “Other”
- The snapshot carries per-day totals by tag; the widget sums its period per timeline entry, so it rolls over without the app. Docs: 205-widget-data
- Checked in the simulator’s widget gallery and through the published snapshot; the configured widget on a home screen is unverified until a TestFlight build (the simulator’s SpringBoard crashes when any widget is placed)
- Not done: more periods (last month, last 7 or 30 days, custom dates), a small size, share bars, a Mac version
Lock Screen widgets (iOS) (2026-01-05)
- Circular: gauge showing running timer progress or today’s hours
- Rectangular: running timer with tag name and duration, or today summary
- Inline: compact text showing timer or today’s total
Enable widget extension (2026-08-29)
- App Group group.tools.minuta.apps and bundle ID tools.minuta.app.widgets registered under the TestFlight publishing team
- Widget target enabled in project.yml (iOS only)
- Committed entitlements stay empty (personal free team cannot hold the App Group); TestFlight builds swap in Minuta/TestFlight/*.entitlements via xcconfig, see Publishing to TestFlight
Re-enable widgets in TestFlight (done 2026-10-02)
- Was blocked 2026-09-06: the holder’s widget profile was issued for App ID tools.minuta.app.widget (missing trailing “s”); the widget dependency and its MinutaArchive entry were commented out so the first TestFlight build shipped app-only
- 2026-10-01: Daler registered tools.minuta.app.widgets (App Group group.tools.minuta.apps) and reissued tools.minuta.app.widgets AppStore (plus a reissued tools.minuta.app AppStore); profiles installed, dependency + scheme entry restored, ExportOptions-ios.plist committed with both profiles; see 919-plan-mac-distribution
Rework the widget data flow (added 2026-10-02, done 2026-10-02; two corrections to the original sketch below: Text(style: .timer) cannot hide seconds, so elapsed is H:MM from per-minute precomputed entries with .atEnd; and an intent defined in the app target does not launch a killed app, the app-side copies conform to ForegroundContinuableIntent instead, see 205-widget-data)
- Today: the app writes a JSON snapshot (WidgetDataService -> widget-data.json in the App Group) and calls reloadAllTimelines(); the widget’s StartTimerFromWidgetIntent / StopTimerFromWidgetIntent only drop pending-timer.json into the group container, which AppState.processPendingWidgetRequests() consumes the next time the app becomes active, so a tap on the widget does nothing until the app is opened; running durations are rendered as static text from a single timeline entry with .after(60s), which WidgetKit throttles (40-70 refreshes/day budget), so the elapsed time goes stale
- Intents: move the widget buttons to the app-target intents (StartTimerIntent / StopTimerIntent in AppIntents.swift, exposed to the extension through a shared AppIntentsPackage); the system then runs perform() in the app process in the background with full storage access (bookmarks, AutomergeStorageService, write lock), the intent writes the record, refreshes the snapshot and calls WidgetCenter.shared.reloadTimelines(ofKind:); delete pending-timer.json and processPendingWidgetRequests()
- Rendering: show elapsed time with Text(timer.startTime, style: .timer) (ticks without timeline refreshes) and today’s total as a static value; build the timeline with a few entries (now, next midnight for the “today” rollover) and policy: .atEnd, no per-minute reloads
- Reload triggers: only on data changes — after start/stop/edit/delete in AppState, after ExternalChangeMonitor reloads (CLI / sync drops), on scene activation; use reloadTimelines(ofKind:) for the affected widget kinds instead of reloadAllTimelines() everywhere
- Snapshot: keep widget-data.json as the read model for the extension (it cannot resolve the app’s security-scoped bookmark), include lastUpdated and the storage folder display name so a stale snapshot can show “open Minuta to refresh”
- Tests: unit tests for the intent path through an injected storage (both targets), a UI test that taps the widget intent in the simulator is not possible, so cover the AppState side
iPhone nightstand mode widget

Watch App [P3]

Apple Watch companion
- Start/stop timers, show current state
- Complication for quick access
- WatchConnectivity for sync

Integrations [P3]

Architecture [P3]

Introduce view model layer
- Reduce direct AppState coupling from views
Implement repository pattern
- Abstract storage implementation details
Stop storing tag colors
- Tag colors are deterministically derived from tag names via TagColorGenerator (OKLCH-based)
- Remove color field from the stored Tag model; compute on read instead
- Drop migration logic that carries forward legacy stored colors
- Location: Shared/Sources/MinutaShared/Models/Tag.swift, call sites in views
Create shared reports library
- Extract report generation (SVG/PDF/PNG/CSV) into a reusable module consumable by both app and CLI
- Location: Shared/Sources/MinutaShared/Services/ (ReportService, SVGReportRenderer, WebKitReportService)

Websites [P3]

Add downloads page to the website (2026-07-03)
- Public page at /downloads/ (src/routes/downloads/) with Homebrew instructions and direct links to the release artifacts served from the same path; linked from header and footer nav
- Versions read at prerender time from Minuta/project.yml and Shared/Sources/MinutaCLI/Minuta.swift (+page.server.js), so links track releases on each site deploy
- Fixed deploy.sh: rsync --delete was wiping the server’s downloads/ artifacts on every site deploy (confirmed: the directory was gone on the server); added --filter='P downloads/*' and re-uploaded artifacts via scripts/upload-brew-artifacts.sh
Docs and promo sites
- SvelteKit + IDS styles
- Static generation with backlinks component
- Prepare scaffold project with Daler

CalendarDatePicker [P3]

TagFilterView [P3]

Animate tags filter expand/collapse
- Add animation to the tag filter DisclosureGroup, similar to the calendar expand/collapse animation
- Location: TagFilterView.swift, HistorySection.swift
Rework the filter overall
- Rethink the whole filter area (calendar + tag filters + summary) — layout, interaction, visual design
- Subsumes/relates to “Rearrange filter components” below
All tags unselected by default
- Currently all tags are selected on first open; change default to no tags selected (show all records unfiltered)
Rearrange filter components
- Review layout and order of CalendarDatePicker, tag filters, and summary controls
- Improve visual hierarchy and discoverability
Add drag-to-select for tag filters
- Press and drag across tags to toggle selection
- Similar to calendar drag-to-select behavior

Inbox

Unsorted ideas. Review periodically.

Play button background gradient in OKLCH with hours marks
Logo: play button with gradient and hours/minutes marks, 3D watch concept
Sort new timers consistent with file system
Heatmap view for records (monthly calendar visualization)
Auto start/stop based on app activity (macOS, accessibility permissions)
Better timeline navigation (swipe gestures, scrubber)
Native Apple Charts in history view (iOS 16+ / macOS 13+)
Not sure if we need to show Today section when it falls within the selected date span — experiment with hiding it
Record a short demo video of real usage to show people after installation (user feedback); could live on the website / downloads page

911-completed - Completed tasks archive
912-audit-2025-12-25 - Audit report
901-2025-12-08-init - Project initialization
902-2025-12-09-editor - Editor implementation