Sync taskledger state across PCs

Schema-3 project state

The canonical layout is:

/home/me/src/project-a/.ledger/ledger.toml
/home/me/src/project-a/.ledger/taskledger/config.toml
/home/me/src/ledger/taskledger/<project-uuid>/data
<user-cache>/taskledger/<project-uuid>/<checkout>/indexes

Initialize and inspect the resolved mounts explicitly:

taskledger init
taskledger storage where
taskledger storage path data
taskledger storage path indexes
taskledger storage set data user-data --local --move

The project UUID and Ledgercore binding keep shared projects isolated.

Shared state Git repo

The sibling store can be an explicit Git repository. Taskledger Git sync derives the repository root and limits canonical operations to the resolved project path:

taskledger sync git init
taskledger sync git status
taskledger sync git pull
taskledger sync git push

Second PC bootstrap

Clone both repositories as siblings:

cd ~/src
git clone <source-repo-url> project-a
git clone <private-state-repo-url> taskledger-state

cd project-a
taskledger status --full
taskledger doctor
taskledger task list

Daily sync protocol

Taskledger provides a Git sync command group that supports this workflow:

taskledger sync git init --repo ../taskledger-state --project-path project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git push
taskledger sync git push --message "Sync project-a taskledger state"

In a shared taskledger-state repository, Taskledger can safely inspect and report project-local vs outside-project dirty paths. sync git push commits repository-wide changes by design to match the standard Git workflow. Use sync git cd for advanced manual inspection or conflict resolution.

For manual conflict resolution or debugging:

cd "$(taskledger sync git cd)"
git status --short

Before starting work on a PC:

cd ~/src/project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git import-local
taskledger doctor
taskledger next-action

After finishing a task cycle or stopping at a safe boundary:

cd ~/src/project-a
taskledger doctor
taskledger sync git status
taskledger sync git push

Active lock rule

Do not use the same Taskledger state concurrently from multiple PCs. Prefer to switch machines only when:

• the task is done;

• the task is approved and no implementation lock exists;

• implementation is finished and validation has not started; or

• no active lock is present.

Keep one active writer per project. Concurrent writes can produce Git conflicts or semantic conflicts across canonical task records.

When to use export/import instead

Archive commands are still the transfer primitive and remain available at both the root and under sync:

taskledger export task-0040
taskledger import ./taskledger-task-project-a-main-task-0040-...tar.gz
taskledger sync export --output ./taskledger-transfer.tar.gz
taskledger sync import ./taskledger-transfer.tar.gz --dry-run

If work must move mid-run, prefer task-scoped transfer archives instead of syncing the full live state directory:

taskledger export task-0040
# copy archive to the other PC
taskledger import ./taskledger-task-project-a-main-task-0040-...tar.gz
taskledger next-action
taskledger implement resume --reason "Continue imported implementation."

Imported runtime locks are quarantined by default, which makes archive transfer safer than syncing an active lock between machines.

Syncthing/rclone caveats

Syncthing and rclone bisync can transport the external state directory, but Git is the safer default for Taskledger’s text-first state because it preserves history and exposes conflicts directly.

If Syncthing is used:

• avoid concurrent writers;

• stop one agent before starting another PC;

• run taskledger doctor after sync; and

• resolve conflict files before continuing.

Treat rclone bisync as an advanced workflow. Keep Git push/pull under user control and do not automate network sync from Taskledger itself.

Task-centered traceability

Taskledger owns temporal work truth: task history, plans, acceptance criteria, implementation changes, validation checks, reviews, locks, and handoffs. Cross-ledger links are opaque file or ID references.

Use taskledger trace TASK --format json to emit a read-only taskledger.trace.v1 task bundle. The bundle links task IDs, accepted AC IDs, opaque link refs, source refs, evidence refs, changes, reviews, and handoffs.

Evidence import is explicit and auditable through taskledger validate check --criterion ... --status ... --evidence ....

Canonical mounts

Canonical sync includes the durable data mount and optional logs mount. Cache indexes are excluded and can be deleted and rebuilt. Workspace and cache family roots are resolved by Ledgercore and are not changed by taskledger storage move.