Add zara-org-todos — Org-mode todo backend + durable remote sync #23

New issue

Open

opened 2026-08-31 23:34:50 +00:00 by lost-rob0t · 3 comments

lost-rob0t commented

2026-08-31 23:34:50 +00:00

(Migrated from github.com)

Plugin name

zara-org-todos

Purpose

Make Org-mode the durable todo/task backend for Zara and keep the live Org agenda synchronized with the user's durable gpt-todos Git repository.

The implementation must port the current synchronization semantics from lost-rob0t/dotfiles master, canonical source scripts/gpt-todos-sync.org / generated scripts/gpt-todos-sync, rather than inventing a simpler timestamp/rsync scheme.

Source behavior to preserve

Current master sync semantics include:

durable checkout defaults to ~/Documents/gpt-todos;
repository task source is agenda/;
live Org agenda defaults to ~/Documents/Notes/org/agenda;
recursive .org synchronization;
current durable checkout HEAD is the synchronization baseline;
fetch upstream and compare Git blob identities;
copy only the side changed relative to the baseline;
concurrent local + remote edits to the same file fail closed instead of timestamp merging;
repository-side deletion requires manual resolution;
filesystem aliases/symlinks resolving to the durable file are treated as synchronized;
local agenda changes are staged, committed with task-aware DONE/reopen/add/update messages, and pushed;
strictly-ahead local commits are published;
diverged unpushed local commits are replayed onto upstream, with rebase conflict abort + manual-resolution failure;
non-interactive Git/SSH operation;
file-save mode preserves the exact saved file, handles live files aliased into the durable checkout, and writes recovery copies on failure;
synchronization is serialized by a lock.

Dotfiles-specific literate tangling and cron/Home-Manager deployment are not part of the plugin runtime; Zara's managed service worker replaces the periodic timer. The port should remain behaviorally compatible with the current script's agenda sync path.

Entrypoint layout

Service plugin, API v1:

plugins/zara-org-todos/zara-plugin/zara_org_todos.py
implementation under plugins/zara-org-todos/lib/zara_org_todos_service/
deterministic tests under plugins/zara-org-todos/test/
CLI/installer at plugins/zara-org-todos/tools/zara-org-todos

Zara plugin API

api_version = "1"

Service plugin should expose tools for at least:

force sync now;
report sync/backend status.

The service should run bounded periodic sync through PluginRuntime.start_worker() and stop cooperatively.

Configuration

Support plugin configuration/environment defaults for:

repo directory;
Org agenda directory;
Git remote;
sync interval (minimum sane bound; default 300 seconds);
automatic periodic sync enable/disable.

Defaults should match the existing gpt-todos workflow.

Dependencies

Runtime/system commands required by the current sync contract include Git and standard POSIX/Linux file utilities. Keep Python dependencies stdlib-only where possible. Do not require Emacs, cron, or the dotfiles checkout for normal plugin operation.

Security / reliability

non-interactive Git operation;
no shell interpolation of user-controlled values;
bounded worker lifecycle;
serialized sync runs;
fail closed on same-file concurrent edits/rebase conflicts;
preserve recovery copies for interrupted/failed save-mode sync;
never overwrite both-side-changed files automatically.

License

GPL-3.0-or-later.

Zara currently hard-codes todo/reminder words to its internal Python todo skills. A separate Zara issue should add an explicit way to disable/replace the built-in todo intent/tool surface so zara-org-todos can become the authoritative backend without two competing todo stores.

Acceptance

plugin registry entry and installer are wired;
deterministic tests cover config, lock/single-run behavior, local-only change, remote-only change, same-file conflict rejection, commit/push behavior, and worker lifecycle;
compatibility test skips cleanly when Zara is absent;
python3 scripts/validate-registry.py passes;
plugin unittest suite passes;
nix flake check passes before publication/merge.

## Plugin name `zara-org-todos` ## Purpose Make Org-mode the durable todo/task backend for Zara and keep the live Org agenda synchronized with the user's durable `gpt-todos` Git repository. The implementation must port the current synchronization semantics from `lost-rob0t/dotfiles` `master`, canonical source `scripts/gpt-todos-sync.org` / generated `scripts/gpt-todos-sync`, rather than inventing a simpler timestamp/rsync scheme. ## Source behavior to preserve Current master sync semantics include: - durable checkout defaults to `~/Documents/gpt-todos`; - repository task source is `agenda/`; - live Org agenda defaults to `~/Documents/Notes/org/agenda`; - recursive `.org` synchronization; - current durable checkout `HEAD` is the synchronization baseline; - fetch upstream and compare Git blob identities; - copy only the side changed relative to the baseline; - concurrent local + remote edits to the same file fail closed instead of timestamp merging; - repository-side deletion requires manual resolution; - filesystem aliases/symlinks resolving to the durable file are treated as synchronized; - local agenda changes are staged, committed with task-aware DONE/reopen/add/update messages, and pushed; - strictly-ahead local commits are published; - diverged unpushed local commits are replayed onto upstream, with rebase conflict abort + manual-resolution failure; - non-interactive Git/SSH operation; - file-save mode preserves the exact saved file, handles live files aliased into the durable checkout, and writes recovery copies on failure; - synchronization is serialized by a lock. Dotfiles-specific literate tangling and cron/Home-Manager deployment are not part of the plugin runtime; Zara's managed service worker replaces the periodic timer. The port should remain behaviorally compatible with the current script's agenda sync path. ## Entrypoint layout Service plugin, API v1: - `plugins/zara-org-todos/zara-plugin/zara_org_todos.py` - implementation under `plugins/zara-org-todos/lib/zara_org_todos_service/` - deterministic tests under `plugins/zara-org-todos/test/` - CLI/installer at `plugins/zara-org-todos/tools/zara-org-todos` ## Zara plugin API `api_version = "1"` Service plugin should expose tools for at least: - force sync now; - report sync/backend status. The service should run bounded periodic sync through `PluginRuntime.start_worker()` and stop cooperatively. ## Configuration Support plugin configuration/environment defaults for: - repo directory; - Org agenda directory; - Git remote; - sync interval (minimum sane bound; default 300 seconds); - automatic periodic sync enable/disable. Defaults should match the existing `gpt-todos` workflow. ## Dependencies Runtime/system commands required by the current sync contract include Git and standard POSIX/Linux file utilities. Keep Python dependencies stdlib-only where possible. Do not require Emacs, cron, or the dotfiles checkout for normal plugin operation. ## Security / reliability - non-interactive Git operation; - no shell interpolation of user-controlled values; - bounded worker lifecycle; - serialized sync runs; - fail closed on same-file concurrent edits/rebase conflicts; - preserve recovery copies for interrupted/failed save-mode sync; - never overwrite both-side-changed files automatically. ## License GPL-3.0-or-later. ## Related Zara core requirement Zara currently hard-codes todo/reminder words to its internal Python todo skills. A separate Zara issue should add an explicit way to disable/replace the built-in todo intent/tool surface so `zara-org-todos` can become the authoritative backend without two competing todo stores. ## Acceptance - plugin registry entry and installer are wired; - deterministic tests cover config, lock/single-run behavior, local-only change, remote-only change, same-file conflict rejection, commit/push behavior, and worker lifecycle; - compatibility test skips cleanly when Zara is absent; - `python3 scripts/validate-registry.py` passes; - plugin unittest suite passes; - `nix flake check` passes before publication/merge.

lost-rob0t commented

2026-08-31 23:44:57 +00:00

(Migrated from github.com)

it should just be using a generic git repo, the "public" addon should not be forced into using MY repo. so make it a configuration option for the plugin!

lost-rob0t commented

2026-08-31 23:46:44 +00:00

(Migrated from github.com)

Implementation is now in PR #24 (feat/zara-org-todos). It ports the current gpt-todos-sync behavior from dotfiles master commit 7b88a3c2ddef7f3fffc09fd049476e06cf13d93a, adds stable-ID Org task CRUD/scheduling + managed periodic sync, and keeps tools org_todos_*-prefixed until Zara core can disable/replace its built-in todo surface. Core blocker/tracking issue: lost-rob0t/zara#246.

Implementation is now in PR #24 (`feat/zara-org-todos`). It ports the current `gpt-todos-sync` behavior from dotfiles master commit `7b88a3c2ddef7f3fffc09fd049476e06cf13d93a`, adds stable-ID Org task CRUD/scheduling + managed periodic sync, and keeps tools `org_todos_*`-prefixed until Zara core can disable/replace its built-in todo surface. Core blocker/tracking issue: lost-rob0t/zara#246.

lost-rob0t commented

2026-09-01 00:23:54 +00:00

(Migrated from github.com)

Updated PR #24 to match your comment: Org-mode is now the backend by itself, with Git completely optional. Defaults are git_sync = false, auto_sync = false, and no remote. Org CRUD/scheduling does not create a Git runner or spawn Git in default mode. Enabling Git requires git_sync = true plus an explicit user-supplied remote; the public plugin no longer defaults users into your repository. Zara core replacement support is implemented in lost-rob0t/zara#248.

Updated PR #24 to match your comment: Org-mode is now the backend by itself, with Git completely optional. Defaults are `git_sync = false`, `auto_sync = false`, and no remote. Org CRUD/scheduling does not create a Git runner or spawn Git in default mode. Enabling Git requires `git_sync = true` plus an explicit user-supplied remote; the public plugin no longer defaults users into your repository. Zara core replacement support is implemented in lost-rob0t/zara#248.