taskledger 0.3.0__tar.gz → 0.4.0__tar.gz

{taskledger-0.3.0 → taskledger-0.4.0}/.taskledger.toml

@@ -1,7 +1,7 @@
 # Project-local taskledger configuration.
 # This file lives in the source project root.
 config_version = 2
-taskledger_dir = '.taskledger'
+taskledger_dir = '../taskledger-state/taskledger'
 
 # Stable project identity. Commit this with your source tree.
 project_uuid = "081c7c05-2d10-42b7-9b37-3d814c2f400a"
@@ -9,7 +9,7 @@ project_uuid = "081c7c05-2d10-42b7-9b37-3d814c2f400a"
 # Taskledger branch-scoped state. This block is intentionally safe to commit.
 ledger_ref = "main"
 ledger_parent_ref = ""
-ledger_next_task_number = 81
+ledger_next_task_number = 87
 ledger_branch_guard = "off"
 
 [prompt_profiles.planning]
@@ -27,4 +27,4 @@ required_question_topics = []
 extra_guidance = ""
 
 [agent_logging]
-enabled = true
+enabled = false

{taskledger-0.3.0 → taskledger-0.4.0}/API.md

@@ -12,6 +12,7 @@ This repository exposes a task-first public API. The supported modules are:
 - `taskledger.api.locks`
 - `taskledger.api.handoff`
 - `taskledger.api.releases`
+- `taskledger.api.storage`
 - `taskledger.api.search`
 
 ## Import boundary
@@ -104,6 +105,9 @@ from taskledger.errors import (
 - `propose_plan`
 - `plan_template`
 - `upsert_plan`
+- `PlanReviewOptions`
+- `build_plan_review_payload`
+- `render_plan_review`
 - `export_plan`
 - `amend_plan`
 - `regenerate_plan_from_answers`
@@ -230,6 +234,14 @@ record body and return compact metadata, including `context_hash` and
 - `show_release`
 - `tag_release`
 
+### `taskledger.api.storage`
+
+- `storage_where`
+- `storage_move`
+- `sync_preflight`
+- `sync_status`
+- `sync_commit`
+
 ### `taskledger.api.search`
 
 - `search_workspace`
@@ -253,6 +265,8 @@ The public task-first CLI surface is organized around these command groups:
 - `require`
 - `release`
 - `lock`
+- `storage`
+- `sync`
 - `context`
 - `handoff`
 - `repair`

{taskledger-0.3.0 → taskledger-0.4.0}/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## v0.4.0 - 2026-05-18
+
+### Added
+
+- Added storage sync documentation (`docs/sync.rst`) explaining how to keep taskledger state outside the source repo, sync across PCs with a private Git repo, bootstrap a second machine, follow a daily sync protocol, and avoid active multi-writer conflicts.
+- Added `taskledger storage where` command reporting resolved project and storage location details in human and JSON output, including whether storage lives inside the workspace, is a Git repo, or has active locks.
+- Added `taskledger storage move` for safely migrating storage to a new `taskledger_dir` with atomic config updates, unsafe-target refusal, and follow-up command hints.
+- Added `taskledger sync preflight` read-only check combining doctor health, active-lock warnings, tracked in-repo state warnings, and local Git status.
+- Added `taskledger sync status` and `taskledger sync commit` local Git helper commands for committing taskledger state without network operations.
+- Added `taskledger sync export` and `taskledger sync import` as aliases for the existing archive transfer commands.
+- Added `taskledger sync git` command group for live external-state synchronization: `init`, `status`, `commit`, `cd`, `import-local`, `export-local`, `pull`, `push`, `sync`, and `hooks` subcommands with conservative lock/dirty checks.
+- Added project-scoped `sync git status` that separates current-project changes from outside-project changes in JSON payloads, safe with dirty sibling directories.
+- Added `sync git cd` helper returning the configured sync repo path for shell use.
+- Added `sync git commit` for committing only the configured project path while ignoring dirty sibling paths.
+- Added `[sync.git]` project config section with strict validation and documented defaults.
+- Added `taskledger/services/storage_locations.py` for storage reporting, migration, and sync helper services.
+- Added `taskledger/services/git_sync.py` for git sync orchestration.
+- Added `taskledger/cli_sync.py` as a dedicated sync CLI group.
+- Added `taskledger/api/sync.py` with public sync API wrappers.
+
+### Changed
+
+- Demoted whole-repo `sync git pull`, `push`, `sync`, and unsafe hook installation from recommended workflow to advanced/deprecated status in help, docs, and skill guidance.
+- Reframed docs, README, and skill around the project-scoped local helper workflow: `sync git status`, `sync git commit`, then manual Git via `sync git cd`.
+- Fixed stale config filename references so docs no longer claim init writes `.taskledger.toml` when `taskledger.toml` is canonical.
+- Updated external storage examples to use the current `ledgers/<ledger_ref>/...` layout.
+
+### Documentation
+
+- Added `docs/sync.rst` with cross-PC sync workflow, daily protocol, and multi-writer conflict avoidance guidance.
+- Updated README, `docs/usage.rst`, `docs/transfer.rst`, `docs/command_contract.rst`, `docs/public_surface.rst`, `API.md`, and `skills/taskledger/SKILL.md` for the new storage and sync command surface.
+
+### Quality
+
+- Added `tests/test_storage_sync.py` and `tests/test_sync_git.py` covering storage migration, sync commands, git sync workflows, shared dirty state, project-scoped commits, and JSON result kinds.
+- Expanded command inventory, CLI contract, and docs/skill tests for the new command surface.
+- Full suite: 897 tests passing, ruff and mypy clean.
+
+## v0.3.1 - 2026-05-12
+
+### Added
+
+- Added task-scoped export/import with `--task` positional ref on export, safe ID remapping (`--id-policy preserve|renumber`), counter repair, and artifact path remapping on import. Full-ledger export remains the default; single-task archives filter task-scoped records and clear `active_task`.
+- Added `taskledger plan review` command to show the current or specified plan version with structured JSON output and content rendering.
+- Added `next-action` routing to recommend `plan review --version N` when a plan is awaiting approval.
+
+### Documentation
+
+- Updated README, command contract, and SKILL.md for task-scoped transfer workflow and `plan review` command.
+
+### Quality
+
+- Added regression coverage for task-scoped export/import ID mapping, conflict policy, counter repair, artifact remap, and plan review end-to-end.
+- Full suite: 878 tests passing, ruff and mypy clean.
+
+## v0.3.0 - 2026-05-05
+
+### Added
+
+- Added agent command transcript logging: opt-in config, append-only NDJSON storage, CLI stdout/stderr tee capture, managed-shell capture, `task transcript` command, and `task report --include command-log` section. Export/import preserves transcript archives.
+- Added planning guidance profiles: `plan guidance` command, `--include-guidance` plan template injection, and `prompt_profiles.planning` config with advisory required-fields rendering.
+- Added transcript review mode as the default `task transcript` output, with `--raw` flag for the original table view, duplicate log ID warnings, and logical-row grouping for wrapper/managed-shell pairs.
+- Added enriched command metadata: tier, deprecated, replaced_by, ledger_effect, workspace_effect, external_effect, and agent_safe fields on CommandSpec. Added `--tier` and `--include-deprecated` CLI filters. Deprecated `lock break` in favor of `repair lock`.
+- Added first-class expired-lock resume path: `implement resume --repair-expired-lock` releases expired implementation locks with audit trail, and `next-action` emits `expired-lock-resume` when applicable.
+- Added task-resource positional refs for read-only commands (`task show`, `task view`, etc.) with explicit `--task` required for destructive commands (`task cancel`, `task uncancel`, `task edit`).
+- Added JSON usage-error envelopes for workflow positional-ref rejection and CLI parse errors.
+- Added soft task archive: `task archive`/`task unarchive` commands, archived-task visibility filtering across list/tree/status, and slug reuse semantics.
+- Added export/import project metadata guard, dry-run safety, and include-flag controls.
+- Added plan revision workflow: `plan export`, `plan amend`, and `--auto-revise` with safe plan input path guard and plan.amended audit events.
+- Added plan approval provenance: approval_source and approved_plan_hash stored on acceptance, with hash-mismatch warnings in reports.
+- Added implement finish warning for missing git change scans.
+
+### Changed
+
+- Split run/lock helpers into `services/run_store.py` from the tasks.py monolith; `tasks.py` re-exports for backward compatibility.
+- Wrapper commands now mirror inner exit status by default instead of always succeeding.
+- Planning guidance recommendation is now integrated into `plan start` and `next-action` with a one-time viewed marker.
+- Plan lint human output now renders summary and issue details instead of bare pass/fail.
+- Question `answer-many` now validates repeat inputs, aliases, and provenance.
+- Doctor mismatch guidance and verbose output improved with actionable repair hints.
+
+### Fixed
+
+- Fixed task report Plans section so non-accepted plans show reviewable details instead of being omitted.
+- Fixed pre-commit `--all-files` regressions across test files.
+
+### Documentation
+
+- Documented planning guidance profiles in README, usage, command contract, API, and skill.
+- Documented transcript logging, managed command capture, and review mode in usage and skill.
+- Documented expired-lock-resume path and `--repair-expired-lock` in SKILL.md.
+- Documented command-surface safety guidance, task-resource positional refs, and destructive-target rules in SKILL.md and command contract.
+- Documented plan revision workflow commands and safety semantics in SKILL.md and command examples.
+- Updated failure-review remediation hints for known mistakes in docs and skill.
+
+### Quality
+
+- Added regression test modules for agent command logging, expired-lock resume, task archive, and plan revision workflow.
+- Expanded command inventory, CLI contract, JSON contract, and docs/skill tests for metadata enrichment, deprecation, targeting, and envelope behavior.
+- Full suite: 770+ tests passing, ruff and mypy clean.
+
 ## v0.2.0 - 2026-05-03
 
 ### Added

{taskledger-0.3.0/taskledger.egg-info → taskledger-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.3.0
+Version: 0.4.0
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -28,6 +28,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer
 Requires-Dist: PyYAML
+Requires-Dist: Jinja2>=3.1
 Requires-Dist: tomli; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
@@ -72,7 +73,7 @@ The supported command surface is organized as:
 
 **Operations:**
 
-- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`
+- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -164,6 +165,7 @@ taskledger question answer-many --text $'q-0001: Yes.\nq-0002: No.'
 taskledger question status
 taskledger plan template --from-answers --file ./plan.md
 taskledger plan upsert --from-answers --file ./plan.md
+taskledger plan review --version 1
 taskledger plan lint --version 1
 taskledger plan accept --version 1 --note "Ready."
 
@@ -320,16 +322,18 @@ Rules for agents:
 
 ## Human monitoring UI
 
-`taskledger serve` starts a read-only local dashboard for humans monitoring task
-state. It now emphasizes the active task, next action, progress, blockers, and
-compact task browsing while staying local-only, read-only, and dependency-free.
-The MVP still binds to localhost only, refreshes with read-only JSON polling,
-and exposes no browser mutation endpoints.
+`taskledger serve` starts a read-only local server-rendered HTML dashboard for
+human monitoring. It emphasizes the active task, next action, progress, and
+task browsing while staying local-only and read-only.
 
 ```bash
-taskledger serve
+taskledger report html task-0040 --output task-0040.html
+taskledger report html --active --output active-task.html
+taskledger report site --output .taskledger-report/
+
+taskledger serve --refresh-seconds 2
 taskledger serve --open
-taskledger serve --task rewrite-v2 --refresh-ms 2000
+taskledger serve --task task-0040 --refresh-seconds 2
 ```
 
 Agents should keep using `taskledger next-action`, `taskledger todo next`, and
@@ -340,12 +344,13 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root. The checked-in `.taskledger.toml`
-stores only a branch-scoped ledger pointer and next task number. Operational task
-state remains ignored under `.taskledger/ledgers/<ledger_ref>/`:
+records under the configured storage root. The checked-in `taskledger.toml`
+stores project identity plus the current branch-scoped ledger pointer and next
+task number. Operational task state remains ignored under
+`.taskledger/ledgers/<ledger_ref>/`:
 
 ```text
-.taskledger.toml
+taskledger.toml
 .taskledger/
   storage.yaml
   ledgers/
@@ -363,7 +368,7 @@ optional derived caches or registries and are not required for task correctness.
 
 ### Branch-scoped ledgers
 
-`.taskledger/` stays ignored and local. `.taskledger.toml` is safe to commit and
+`.taskledger/` stays ignored and local. `taskledger.toml` is safe to commit and
 contains the current `ledger_ref`, optional parent ref, and the next logical task
 number for the checked-out source branch.
 
@@ -373,10 +378,10 @@ the Git branch:
 ```bash
 git checkout -b feature-a
 taskledger ledger fork feature-a
-git add .taskledger.toml
+git add taskledger.toml
 ```
 
-Returning to a branch whose `.taskledger.toml` points back to `main` hides the
+Returning to a branch whose `taskledger.toml` points back to `main` hides the
 feature branch's active task and task list. Two ledgers may both contain a logical
 `task-0030`; this is expected because task IDs are scoped by `ledger_ref`. Use
 `taskledger ledger adopt --from REF TASK_REF` when branch-local task history
@@ -391,15 +396,56 @@ taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a
 ```text
 /home/me/src/project-a/taskledger.toml
 /mnt/cloud/taskledger/project-a/storage.yaml
-/mnt/cloud/taskledger/project-a/releases/
-/mnt/cloud/taskledger/project-a/tasks/
-/mnt/cloud/taskledger/project-a/events/
-/mnt/cloud/taskledger/project-a/indexes/
+/mnt/cloud/taskledger/project-a/ledgers/main/releases/
+/mnt/cloud/taskledger/project-a/ledgers/main/tasks/
+/mnt/cloud/taskledger/project-a/ledgers/main/events/
+/mnt/cloud/taskledger/project-a/ledgers/main/indexes/
 ```
 
 Use one `taskledger_dir` per source project. Do not share one storage directory
 across unrelated repositories.
 
+### Sync across PCs without committing `.taskledger/`
+
+Use a sibling private Git repository for the external storage root instead of
+committing `.taskledger/` into the source repository:
+
+```toml
+# /home/me/src/project-a/taskledger.toml
+taskledger_dir = "../taskledger-state/project-a"
+```
+
+```text
+/home/me/src/project-a/                  # source repo
+/home/me/src/taskledger-state/           # private state repo
+/home/me/src/taskledger-state/project-a/ # taskledger_dir
+```
+
+Keep one active writer at a time. Before starting on a PC, pull the private
+state repo, then run `taskledger doctor` and `taskledger next-action`. After
+stopping at a clean lifecycle boundary, commit and push the state repo. If work
+must move mid-run, prefer `taskledger export TASK_REF` / `taskledger import ARCHIVE` because imported runtime locks are quarantined by default.
+
+Helpful local commands:
+
+```bash
+taskledger storage where
+taskledger sync preflight
+taskledger sync status
+taskledger sync commit --message "Sync project-a taskledger state"
+taskledger sync export --output ./taskledger-transfer.tar.gz
+taskledger sync import ./taskledger-transfer.tar.gz --dry-run
+taskledger sync git init --repo ../taskledger-state --project-path project-a
+taskledger sync git status
+taskledger sync git commit --message "Sync project-a taskledger state"
+cd "$(taskledger sync git cd)"
+git pull --ff-only
+git push
+```
+
+See `docs/sync.rst` for the full second-PC bootstrap, daily sync protocol, and
+Syncthing/rclone caveats.
+
 ## JSON output
 
 Use `--json` for machine-readable payloads:
@@ -450,6 +496,7 @@ taskledger context --for implementation --format markdown
 taskledger context --for validation --format json
 taskledger task dossier --format markdown
 taskledger task report --task task-0030 -o task30.md
+taskledger report html task-0030 --output task30.html
 taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."
@@ -512,7 +559,10 @@ for task-first handoff guidance.
 ```bash
 taskledger init --project-name "Taskledger"
 taskledger export
+taskledger export --task task-0040
+taskledger export task-0040
 taskledger import ./taskledger-transfer.tar.gz --dry-run
+taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
 taskledger import ./taskledger-transfer.tar.gz --replace
 taskledger snapshot ./artifacts
 ```
@@ -521,6 +571,7 @@ Default export filenames use this policy:
 
 ```text
 taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
+taskledger-task-{project_slug}-{ledger_ref}-{task_id}-{timestamp}.tar.gz
 ```
 
 `project_slug` is derived from `project_name` in `taskledger.toml`. If
@@ -543,6 +594,21 @@ taskledger implement resume --reason "Continue imported implementation."
 
 Use `--lock-policy keep` only for diagnostic full-fidelity lock restoration.
 
+Single-task transfer from a config-only checkout:
+
+```bash
+# fresh checkout on another PC
+taskledger init
+taskledger task create "Fix import edge case" --slug fix-import-edge-case --description "..."
+# ... normal plan / implementation / validation lifecycle ...
+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
+```
+
 ## Skill packaging
 
 Agent workflows work best when the `taskledger` skill is installed in the

{taskledger-0.3.0 → taskledger-0.4.0}/README.md

@@ -29,7 +29,7 @@ The supported command surface is organized as:
 
 **Operations:**
 
-- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`
+- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -121,6 +121,7 @@ taskledger question answer-many --text $'q-0001: Yes.\nq-0002: No.'
 taskledger question status
 taskledger plan template --from-answers --file ./plan.md
 taskledger plan upsert --from-answers --file ./plan.md
+taskledger plan review --version 1
 taskledger plan lint --version 1
 taskledger plan accept --version 1 --note "Ready."
 
@@ -277,16 +278,18 @@ Rules for agents:
 
 ## Human monitoring UI
 
-`taskledger serve` starts a read-only local dashboard for humans monitoring task
-state. It now emphasizes the active task, next action, progress, blockers, and
-compact task browsing while staying local-only, read-only, and dependency-free.
-The MVP still binds to localhost only, refreshes with read-only JSON polling,
-and exposes no browser mutation endpoints.
+`taskledger serve` starts a read-only local server-rendered HTML dashboard for
+human monitoring. It emphasizes the active task, next action, progress, and
+task browsing while staying local-only and read-only.
 
 ```bash
-taskledger serve
+taskledger report html task-0040 --output task-0040.html
+taskledger report html --active --output active-task.html
+taskledger report site --output .taskledger-report/
+
+taskledger serve --refresh-seconds 2
 taskledger serve --open
-taskledger serve --task rewrite-v2 --refresh-ms 2000
+taskledger serve --task task-0040 --refresh-seconds 2
 ```
 
 Agents should keep using `taskledger next-action`, `taskledger todo next`, and
@@ -297,12 +300,13 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root. The checked-in `.taskledger.toml`
-stores only a branch-scoped ledger pointer and next task number. Operational task
-state remains ignored under `.taskledger/ledgers/<ledger_ref>/`:
+records under the configured storage root. The checked-in `taskledger.toml`
+stores project identity plus the current branch-scoped ledger pointer and next
+task number. Operational task state remains ignored under
+`.taskledger/ledgers/<ledger_ref>/`:
 
 ```text
-.taskledger.toml
+taskledger.toml
 .taskledger/
   storage.yaml
   ledgers/
@@ -320,7 +324,7 @@ optional derived caches or registries and are not required for task correctness.
 
 ### Branch-scoped ledgers
 
-`.taskledger/` stays ignored and local. `.taskledger.toml` is safe to commit and
+`.taskledger/` stays ignored and local. `taskledger.toml` is safe to commit and
 contains the current `ledger_ref`, optional parent ref, and the next logical task
 number for the checked-out source branch.
 
@@ -330,10 +334,10 @@ the Git branch:
 ```bash
 git checkout -b feature-a
 taskledger ledger fork feature-a
-git add .taskledger.toml
+git add taskledger.toml
 ```
 
-Returning to a branch whose `.taskledger.toml` points back to `main` hides the
+Returning to a branch whose `taskledger.toml` points back to `main` hides the
 feature branch's active task and task list. Two ledgers may both contain a logical
 `task-0030`; this is expected because task IDs are scoped by `ledger_ref`. Use
 `taskledger ledger adopt --from REF TASK_REF` when branch-local task history
@@ -348,15 +352,56 @@ taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a
 ```text
 /home/me/src/project-a/taskledger.toml
 /mnt/cloud/taskledger/project-a/storage.yaml
-/mnt/cloud/taskledger/project-a/releases/
-/mnt/cloud/taskledger/project-a/tasks/
-/mnt/cloud/taskledger/project-a/events/
-/mnt/cloud/taskledger/project-a/indexes/
+/mnt/cloud/taskledger/project-a/ledgers/main/releases/
+/mnt/cloud/taskledger/project-a/ledgers/main/tasks/
+/mnt/cloud/taskledger/project-a/ledgers/main/events/
+/mnt/cloud/taskledger/project-a/ledgers/main/indexes/
 ```
 
 Use one `taskledger_dir` per source project. Do not share one storage directory
 across unrelated repositories.
 
+### Sync across PCs without committing `.taskledger/`
+
+Use a sibling private Git repository for the external storage root instead of
+committing `.taskledger/` into the source repository:
+
+```toml
+# /home/me/src/project-a/taskledger.toml
+taskledger_dir = "../taskledger-state/project-a"
+```
+
+```text
+/home/me/src/project-a/                  # source repo
+/home/me/src/taskledger-state/           # private state repo
+/home/me/src/taskledger-state/project-a/ # taskledger_dir
+```
+
+Keep one active writer at a time. Before starting on a PC, pull the private
+state repo, then run `taskledger doctor` and `taskledger next-action`. After
+stopping at a clean lifecycle boundary, commit and push the state repo. If work
+must move mid-run, prefer `taskledger export TASK_REF` / `taskledger import ARCHIVE` because imported runtime locks are quarantined by default.
+
+Helpful local commands:
+
+```bash
+taskledger storage where
+taskledger sync preflight
+taskledger sync status
+taskledger sync commit --message "Sync project-a taskledger state"
+taskledger sync export --output ./taskledger-transfer.tar.gz
+taskledger sync import ./taskledger-transfer.tar.gz --dry-run
+taskledger sync git init --repo ../taskledger-state --project-path project-a
+taskledger sync git status
+taskledger sync git commit --message "Sync project-a taskledger state"
+cd "$(taskledger sync git cd)"
+git pull --ff-only
+git push
+```
+
+See `docs/sync.rst` for the full second-PC bootstrap, daily sync protocol, and
+Syncthing/rclone caveats.
+
 ## JSON output
 
 Use `--json` for machine-readable payloads:
@@ -407,6 +452,7 @@ taskledger context --for implementation --format markdown
 taskledger context --for validation --format json
 taskledger task dossier --format markdown
 taskledger task report --task task-0030 -o task30.md
+taskledger report html task-0030 --output task30.html
 taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."
@@ -469,7 +515,10 @@ for task-first handoff guidance.
 ```bash
 taskledger init --project-name "Taskledger"
 taskledger export
+taskledger export --task task-0040
+taskledger export task-0040
 taskledger import ./taskledger-transfer.tar.gz --dry-run
+taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
 taskledger import ./taskledger-transfer.tar.gz --replace
 taskledger snapshot ./artifacts
 ```
@@ -478,6 +527,7 @@ Default export filenames use this policy:
 
 ```text
 taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
+taskledger-task-{project_slug}-{ledger_ref}-{task_id}-{timestamp}.tar.gz
 ```
 
 `project_slug` is derived from `project_name` in `taskledger.toml`. If
@@ -500,6 +550,21 @@ taskledger implement resume --reason "Continue imported implementation."
 
 Use `--lock-policy keep` only for diagnostic full-fidelity lock restoration.
 
+Single-task transfer from a config-only checkout:
+
+```bash
+# fresh checkout on another PC
+taskledger init
+taskledger task create "Fix import edge case" --slug fix-import-edge-case --description "..."
+# ... normal plan / implementation / validation lifecycle ...
+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
+```
+
 ## Skill packaging
 
 Agent workflows work best when the `taskledger` skill is installed in the

{taskledger-0.3.0 → taskledger-0.4.0}/docs/api.rst

@@ -85,6 +85,9 @@ Plan API
 - ``propose_plan``
 - ``plan_template``
 - ``upsert_plan``
+- ``PlanReviewOptions``
+- ``build_plan_review_payload``
+- ``render_plan_review``
 - ``export_plan``
 - ``amend_plan``
 - ``list_plan_versions``