agendula/docs/ROADMAP.md

Agendula — roadmap

Where the project is and where it's going. This is the status view; the design rationale behind each milestone lives in PLAN.md, and how the pieces fit together is in ARCHITECTURE.md.

Status legend: ✅ done · 🚧 in progress · ⬜ not started

---

Current state (one line)

Agendula now carries its own task store, and it is one we wrote: a Room database designed against VTODO, with recurrence expanded at read time. The vendored dmfs provider and the :provider module that held it are deleted, a v0.3.x install's tasks are imported on first launch, and an external provider (OpenTasks / tasks.org) is a user choice rather than a requirement. Export to iCalendar has landed, and the Material 3 Expressive UI is built through M5: lists → task list (swipe gestures, inline add, smart-list section headers) → detail / edit with full CRUD, date-time pickers, priority, percent-complete, conflict-safe saves, per-task reminders, and subtask create + reparent — plus a one-time reminder onboarding step and a Settings screen. The frontend surfaces for the new store have landed too: a Settings Storage section with the store picker and an export screen. Remaining work is verifying all of it on a device, then M6 (Glance widget, translations, F-Droid release) and the sync adapter.

---

Milestones

✅ M0 — Skeleton

Project scaffolding copied from Calendula (Gradle, version catalog, Hilt, Material 3 Expressive theme, Gitea CI/release workflows, F-Droid metadata), reseeded to a warm-mauve fallback palette. Builds, shows a themed placeholder.

✅ M1 — Read path + logic (the "backoffice")

The complete non-visual stack:

• Vendored TaskContract subset, ProviderResolver (runtime authority detection), ColumnReader, mappers, AndroidTasksDataSource (Instances query + ContentObserver), and TasksRepository exposing live Flows of lists / tasks / detail.
• Domain models, smart-list filtering (Today / Upcoming / Overdue / No-date / All / Completed), sorting, form validation, subtasks via parentId.
• Self-scheduled due-reminder engine (AlarmManager + boot / provider-change re-sync), notifications, DataStore prefs.
• Render-only ViewModels + UiState for every screen, so the UI is build-only from here.
• JVM unit tests across mappers, filtering, sorting, form, value mapping, and day windows.

✅ M2 — Screens: lists, task list, complete & CRUD

The real Material 3 Expressive UI, built screen by screen against the M1 ViewModels.

• ✅ Provider/permission onboarding gate (RootScreen).
• ✅ Lists overview (ListsScreen) — smart lists + user lists grouped by account.
• ✅ Navigation host wiring (AgendulaNavHost + Dest route table: lists → task list → detail / edit, each binding its M1 ViewModel from route args).
• ✅ Task list screen — checkbox rows + toggle-complete, swipe-to-complete / -delete (SwipeToDismissBox), inline add field (InlineAdd → quickAdd), smart-list section headers (TaskSections).
• ✅ Detail + edit screens — detail shows title / description / subtasks with edit+delete; edit has the full CRUD form (title, description, save) wired to a list picker.

✅ M3 — Detail / edit polish

• ✅ Due / start date-time pickers (DateTimePickerFlow in TaskEditScreen).
• ✅ Priority — coloured by level: green / amber / red pastels (priorityFill; M3 has no priority role, only error). A shared ui/common/PriorityChip on the list and detail screens, and the edit form's M3 segmented selector tints its active segment in the chosen level's hue.
• ✅ Smart-list section presentation (TaskSections headers on the task list).
• ✅ Percent-complete field — optional "Progress" slider (5% detents) on the edit form; writes Tasks.PERCENT_COMPLETE (clamped 0–100, status left to the complete toggle).
• ✅ Conflict-safe saves — updateTask re-checks last_modified against the value captured when the form loaded and throws TaskConflictException; the editor offers overwrite-or-cancel instead of clobbering an external change.

✅ M4 — Subtasks (UI)

RELATED-TO hierarchy in the UI. The data layer already reads parentId.

• ✅ Create subtask (AddSubtaskField → TaskDetailViewModel.addSubtask sets parentId); subtasks render as a grouped section in the detail screen. Tapping a subtask opens its own detail (a new TaskDetail entry, so it can have children too), and the subtask's detail shows a tappable "Part of …" parent card so it never reads as a stray standalone task.
• ✅ Inline expansion on the task list — a parent row has a dedicated expand button (trailing chevron, separate from the count chip). Each section flattens into one grouped run (parents + their expanded children) and corners are chosen per-edge (cornerPosition): top-level tasks keep their own run, an expanded parent opens its bottom to its children, and the child group rounds off on its last segment while the next top-level task stays mid-run. Children are full-width, set a step down in tone (surfaceContainer vs the parents' surfaceContainerHigh) and with no colour bar (checkbox stays aligned). An expanded group ends with an inline "add a subtask" row (on by default; opt out in Settings → Tasks since M5). Offered only where the list holds all the children (a real list; smart lists that omit off-day children stay collapsed). TaskDetail.parent carries the parent for the detail card.
• ✅ Reparent — a full-width, searchable "Parent task" sheet on the edit form groups active candidates by due-date section (Overdue / Today / Upcoming / No date) and files a task under any top-level task in its list (or "None" to promote it); switching list clears the now-invalid parent. Candidates stay active + top-level to keep nesting one level deep, matching the detail screen.

✅ M5 — Reminders onboarding & polish

The engine exists (M1: ReminderScheduler + boot / provider-change re-sync, DueReminderReceiver, TaskNotifier).

• ✅ Per-task reminder-offset UI (ReminderPickerDialog → TaskForm reminderMinutesBeforeDue).
• ✅ POST_NOTIFICATIONS onboarding flow — a one-time ReminderOnboardingScreen (Calendula's shell + copy adapted for tasks) gated in RootScreen after the provider/permission grant; it requests the runtime permission (API 33+) and records the choice (reminderOnboardingDone). Re-requestable from Settings.
• ✅ Exact-alarm surface — a status row in Settings → Reminders, shown only on Android 12 (where SCHEDULE_EXACT_ALARM is revocable), deep-linking to the system grant screen; on 13+ the app holds USE_EXACT_ALARM (always granted).
• ✅ Default reminder-offset settings UI — exposed as "When to remind" in Settings → Reminders (reminderLeadMinutes), behind a master remindersEnabled switch that gates the entire engine (ReminderScheduler clears all alarms when off; DueReminderReceiver suppresses any in-flight fire).
• ⬜ End-to-end verification on device (build + unit tests green; not yet run on a device with a live provider).

🚧 M6 — Settings, widget, i18n, release

• ✅ F-Droid metadata scaffolded (fdroid-metadata/).
• ✅ Settings screen — landed early with M5 (SettingsScreen in the nav graph, reached by the gear on the lists overview). Covers theme, dynamic colour, due reminders (toggle + default offset + exact-alarm status), default list, and the add-a-subtask-row opt-out — plus the App language picker, which landed with the 0.4.0 translations.
• ⬜ Glance task-list widget — still just an idea, and now without a foothold: the glance-appwidget / glance-material3 dependencies were declared but never used by a single line, so they were shipping dead weight in the APK and have been removed. Re-add them with the implementation, not before.
• ✅ Translations — German and Brazilian Portuguese, via Weblate, shipped in 0.4.0 (res/values-de, res/values-pt-rBR, res/xml/locales_config.xml).
• ⬜ Finalize F-Droid metadata, confirm CI release flow.

✅ Posture B — our own task store

Agendula stopped depending on a provider app being installed. Direction and reasoning in STORAGE-AND-SYNC.md; note it redefined what Posture B means (our own store, coexisting with everything — not squatting org.dmfs.tasks, which is a dead end).

• ✅ fix/provider-interaction-review merged (step 1).
• ✅ Step 2, first pass — the Apache-2.0 dmfs provider 1.4.2 (DB 23) vendored in-tree as :provider, under de.jeanlucmakiola.agendula.tasks and our own permission namespace. Shipped in v0.3.x and since superseded: see "our own store" below.
• ✅ Storage modes + the permission-gate bypass — ProviderStatus.NEEDS_PERMISSION can no longer fire in our own mode, and an upgrading Posture A user stays on the provider that holds their data (ProviderResolver.autoMode).
• ✅ Export to iCalendar (step 3) — a v1 feature now that own-mode data lives only in our app's private storage. One .ics per list, to a folder or a zip, via SAF. Backend only.
• ✅ Frontend surfaces for the above — Settings gained a Storage section holding both: a full-screen store picker (Own / an installed external provider, which is dimmed when none is present) that asks for the provider's runtime permission before committing the switch, and an export screen with a per-list tick and the two SAF destinations, a folder or a single zip. Two consequences of the mode becoming switchable at runtime came with it: reminders are re-armed against the new store on every switch (AgendulaApp listens on ProviderResolver.onModeChanged; previously only a restart, a boot or an edit resynced them), and the permission gate offers a way back to our own store — otherwise a user whose provider app went away is held on a gate with Settings behind it.
• ⬜ File the DAVx5 issue (step 4) — non-blocking, cheap, serves F-Droid users. Note it now means "sync into an app that has no provider", so the ask has changed shape.
• ⬜ Sync adapter (step 5) — the 1.x arc. Designed in SYNC.md, not started: mapper → auth → engine → hardening, ~8–9 weeks, minus the 2.5–4 weeks owning the store deletes from it (OWN-STORE.md, "Effects on the sync plan"). The account model is settled (AccountManager) and ical4android is closed out (superseded by synctools, GPLv3, so we write the mapper in-house); what's still open is dav4jvm's JitPack-only distribution, conflict policy, and whether External mode survives the milestone.

✅ Our own store — Room, and the provider deleted

The vendored provider was kept because it appeared to hand us the sync bookkeeping for free; the phase-1 sync audit measured that bookkeeping and found most of it broken, absent or unusable. Reasoning in STORAGE-DECISION.md, architecture and six-phase plan in OWN-STORE.md.

• ✅ Phase 0 — occurrences addressed by (taskId, occurrenceStart). Task.id (the materialised instance row id) dropped for occurrenceStart, lazy-list keys moved to Task.occurrenceKey, updateInstance re-signed, domain/ stopped importing TasksContract. Done while the provider was still the store, so the External path exercised the new seam first.
• ✅ Phase 1 — the schema: task_lists, tasks, task_alarms, accounts, a DAO per table, the v1 schema JSON committed for migration testing. Masters and RECURRENCE-ID overrides share the tasks table, so the unique index is (list_id, uid, recurrence_id).
• ✅ Phase 2 — RecurrenceExpander over lib-recur 0.12.2: a series expanded in memory at read time, bounded by a window (1 year back, 2 forward) and a hard per-series ceiling. No materialised instances table, so none of its staleness bugs. 38 tests against RFC 5545 directly, since the provider only ever materialised one occurrence to compare against.
• ✅ Phase 3 — RoomTasksDataSource implements all 14 seam methods, picked per call by ModeRoutingTasksDataSource. Editing one occurrence writes a RECURRENCE-ID override sharing the master's UID (RFC 5545 model (a)), where the provider forked a new task with a new UID (model (d)). Completion rules are stated directly rather than worked around, so a task can no longer strand itself "done at 75%".
• ✅ Phase 4 — OneShotImport moves a v0.3.x install's databases/tasks.db into Room on first launch, archiving the source as tasks.db.imported; OWN is the default; StartupGate holds the first store read until the mode has landed and the import has run; backup rules take the database with its WAL sidecars and the app checkpoints on ON_STOP.
• ✅ Phase 5 — :provider deleted: 84 Java files, 14,555 lines, its <provider>, its two custom permissions and its three dmfs runtime dependencies. StorageMode.LOCAL is gone (a stored LOCAL reads as OWN); ProviderResolver narrows to discovering external providers; ProviderChangeReceiver filters on the two external authorities only. provider/PROVENANCE.md is replaced by a postscript in STORAGE-DECISION.md. Not a breaking change for anyone, as it turns out: the de.jeanlucmakiola.agendula.tasks authority and its two custom permissions were added and deleted inside this same unreleased cycle (git tag --contains on the commit that added :provider comes back empty), so no published version ever carried them and nobody could have pointed DAVx5 at one. The release notes must not warn about losing something that never shipped.
• ✅ Phase 6 — harden: MigrationTestHelper wired against the committed v1 schema so v1 → v2 is cheap when sync adds columns, an Auto Backup restore test covering the WAL case in both directions, and a performance check at 5,000 tasks with 20 recurring series.
• ✅ Fallout: ReminderScheduler.sync() gated on resolve() != null, which is what OWN returns, so no due reminder armed in the default mode. It now gates on ProviderResolver.canReadStore(), with tests.
• ✅ Fallout, second pass — four defects a review of the branch turned up: completing one occurrence closed the whole series (setCompleted wrote the master, which is the row TaskDao.tasks filters on, so every occurrence left every list); the expansion ceiling was spent on the past, so a sub-daily series stopped expanding months before today and never reached Today or Upcoming; an imported START-referenced reminder fired off DUE, because the seam collapsed alarms to a bare minute count; and registerObserver bound a live flow to whichever store was active at subscription, so a Settings store switch would have left every screen listening to the store it had stopped reading. setCompletedInstance now forks a RECURRENCE-ID override the way updateInstance does — phase 2 always specified this, only the edit half had it.
• ✅ Ran the instrumented suite on a device — 52 tests, 0 failures, Pixel 10 / API 36, 13 Aug 2026; all six classes (the Room seam, the DAOs, the import, the migration harness, the restore path, the performance check). Mind the ARM64 aapt trap: the task can exit non-zero on a fully green run, so read app/build/outputs/androidTest-results/connected/debug/*.xml before believing the exit code.
• ✅ Re-ran it against the branch tip — 66 tests, 0 failures, Pixel 10 / API 37, 22 Sep 2026, now including ExternalImportTest. Worth having done: the first run failed one test. RoomTasksDataSourceTest.alarmsRoundTripAndReplaceRatherThanAccumulate asserted alarms()[id] == 30, from before the seam returned a TaskReminder rather than a bare minute count — the production value was right (TaskReminder(minutesBefore=30, fromStart=false)) and the assertion was stale. It compiled because Truth's isEqualTo takes Any?, so nothing but executing it could have caught it. Exactly the defect class this item existed to find.
• ⬜ Verify on a device — and note that the upgrade path this phase was designed around is not the one real users are on. OneShotImport reads a bundled dmfs provider's databases/tasks.db, and no release ever bundled one, so every existing install's tasks sit in OpenTasks or tasks.org instead. What has to be checked is therefore:
  1. a fresh install landing on the Room store with nothing installed;
  2. an upgrade from the 0.4.0 APK with OpenTasks installed and permitted — autoMode() must keep them on External and show their tasks unchanged;
  3. Settings → Storage → Copy tasks from … moving those tasks into the Room store, then the switch to On this device showing them, reminders included;
  4. OneShotImport itself, which on a real device is only reachable by side-loading a dev build of this branch first.
• ⬜ Release notes for 1.0.0. Nothing to say about the dropped authority or permissions (see Phase 5); what needs saying is the own store, the copy path out of an external provider, iCalendar export and list management.

✅ A way onto the new store for the people already using Agendula

The migration this branch was planned around turned out to serve nobody: the vendored provider it reads from never shipped, so no install has the file OneShotImport looks for. Everyone on 0.4.0 keeps their tasks in OpenTasks or tasks.org, which autoMode() correctly keeps them on — and until now the only route to the new store was to retype everything.

• ✅ ExternalImport (data/tasks/transfer/) copies the external provider's lists, tasks and alarms into Room in one transaction with verified counts, the same discipline as the legacy import. Task uids survive, so these rows can be attached to a CalDAV collection once sync lands instead of duplicating.
• ✅ Offered as Settings → Storage → Copy tasks from …, behind a confirm that names the real number of tasks, and only while a provider is installed, permitted, and no copy has succeeded yet — a second run would leave two of everything, since what it writes is indistinguishable from hand-typed tasks afterwards.
• ✅ One-directional by design. Writing a list into a third-party provider means impersonating its sync adapter, and the external store is already the one that can sync. What does not come across is documented on the class: per-occurrence overrides, EXDATE, CLASS, DURATION, the per-task timezone, and a task's exact PRIORITY digit.
• ✅ Switching stores at all now asks first. Neither store hands its rows to the other, so the app looks emptied to anyone who expected a move.
• ✅ A failed OneShotImport is no longer silent. It used to return an ImportResult.Failed that every caller dropped, leaving an upgrading user an empty app and no explanation; it is now recorded, logged, and surfaced in Settings → Storage as a retry — which is also what finally makes reimportFromArchive() reachable from the app.

✅ Managing lists in the app

Owning the store made this mandatory: there is no longer a provider app to create a list in, so a fresh install had no lists, no way to make one, and therefore no way to save a task. The seam gained updateList / deleteList beside the existing createLocalList, implemented on both the Room and the External path (which addresses the row as its own account's sync adapter, the only caller the provider lets write tasklists).

• ✅ ListEditorSheet — the family's full-screen sheet with a name field, the 12-colour palette and, when editing, a destructive row behind a confirm.
• ✅ Entry points: a "New list" row under the home Lists section, a real empty state with a create button, and the home FAB switching to "New list" while there are none. Editing is the pencil in a list's own top bar.
• ✅ Deleting a list deletes its tasks — tasks.list_id cascades — and is offered only for device-only lists; an account's collection is its server's.

---

Open decisions / to verify

These carry over from PLAN.md §9; resolved ones are struck through.

1. Name — Agendula confirmed (appId de.jeanlucmakiola.agendula).
2. tasks.org provider authority verified on device: org.tasks.opentasks + org.tasks.permission.*.
3. jtx Board — support its richer contract later, or stay OpenTasks-only? (Not in the candidate list today.) Note this is now downstream of SYNC.md open question 3: if External mode is retired once we sync ourselves, the question disappears with it.
4. Posture B authority choice moot: Agendula publishes no provider and holds no authority at all. The question was live while the store was a vendored provider, and squatting org.dmfs.tasks was a dead end even then — two apps cannot declare the same authority or permission name, so anyone with OpenTasks installed could not have installed Agendula at all.
5. Recurring tasks — recurrence-aware editing out of scope for v1 resolved: our own store expands a series at read time and writes an edit to one occurrence as a RECURRENCE-ID override sharing the master's UID; in External mode the edit still goes through the instances URI.
6. Resolver ordering / mode-selection UX resolved: autoMode() picks the default (see ARCHITECTURE.md §4.1) and Settings → Storage → Task store is the override it always assumed.
7. Sync protocol coverage, account model, conflict resolution — the next design discussion. Taken up in SYNC.md; the remaining opens live on that document's list.

---

How to contribute / verify

• Build: ./gradlew :app:assembleDebug
• Unit tests: ./gradlew :app:testDebugUnitTest
• Instrumented tests: ./gradlew :app:connectedDebugAndroidTest — the Room schema, RoomTasksDataSource and OneShotImport (the last against app/src/androidTest/assets/tasks-v23.db, regenerated by scripts/make_import_fixture.py).
• Any device or emulator will do for the default path: the store is ours and needs nothing installed. Debug builds seed an "Agendula Demo" list via DemoSeeder unless it already exists. To exercise External mode, use a device with OpenTasks or tasks.org installed, and ideally DAVx5 syncing a CalDAV task list.