Transfer archives

Transfer archives are portable taskledger state bundles for moving work between machines and harnesses.

What transfer archives include

  • Current-ledger durable records (tasks, plans, questions, runs, changes, todos, links, requirements, events, releases, handoffs).

  • Project identity metadata: - project.uuid (safety identity) - project.name (human-facing label) - project.slug (filename/report slug) - project.ledger_ref (exported ledger)

  • Optional run artifacts under artifacts/ when --include-run-artifacts is set.

Filename policy

When no output path is passed to taskledger export, taskledger writes into the resolved workspace root:

taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz

For task-scoped exports, the same workspace-root default applies:

taskledger-task-{project_slug}-{ledger_ref}-{task_id}-{timestamp}.tar.gz

project_slug comes from project_name (or workspace fallback). Import safety still depends on UUID checks, not name matching.

Single-task transfer from a config-only checkout

# fresh checkout on another PC
taskledger init
taskledger task create "Fix import edge case" --slug fix-import-edge-case --description "..."
# ... normal plan/implement/validate workflow ...
taskledger export task-0040

# main dev repo
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
taskledger task list
taskledger task show task-0040

Rules:

  • Keep project_uuid committed in taskledger.toml (or legacy .taskledger.toml if the project still uses it).

  • .taskledger/ is local operational state and can be absent on another PC.

  • Run taskledger init after cloning to create local state.

  • taskledger export --task TASK_REF and taskledger export TASK_REF export task-scoped archives.

  • taskledger sync export and taskledger sync import are aliases for the same archive transfer primitives.

  • Task-scoped import is additive by default; if the task id already exists locally, import renumbers and reports an id map.

  • --replace is for full-state replacement, not the normal single-task workflow.

  • Import repairs ledger_next_task_number so future task create ids remain unique.

  • Use Sync taskledger state across PCs when you want to keep an external taskledger_dir in a private Git repository and sync full project state between PCs.

Dry-run import

Use taskledger import --dry-run to validate archive or JSON payload imports without mutating local state:

taskledger import ./taskledger-transfer.tar.gz --dry-run
taskledger import ./taskledger-export.json --dry-run

Lock policy and next action

Imported runtime locks are quarantined by default. After import, follow:

taskledger next-action
taskledger implement resume --reason "Continue imported implementation."