taskledger 0.2.0__tar.gz → 0.3.1__tar.gz

{taskledger-0.2.0 → taskledger-0.3.1}/.codecrate.toml

@@ -6,7 +6,7 @@ respect_gitignore = true
 # exclude = ["*/.venv/*", "integration_tests", "examples", "docs"]
 gitignore_allow = ["taskledger/_version.py"]
 exclude = ["*/.venv/*", "integration_tests", "todo.md"]
-include = ["**/*.py", "**/*.toml", "**/*.rst", "**/*.md", "**/*.typed"]
+include = ["**/*.py", "**/*.toml", "**/*.rst", "**/*.md", "**/*.typed", "**/*.js", "**/*.css"]
 split_max_chars = 0
 manifest = false
 layout = "full"

{taskledger-0.2.0 → taskledger-0.3.1}/.pre-commit-config.yaml

@@ -64,11 +64,3 @@ repos:
         args:
           - --plugin=@prettier/plugin-xml
         files: \.(css|htm|html|js|json|jsx|less|md|scss|toml|ts|xml|yaml|yml)$
-  - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.2.1
-    hooks:
-      - id: eslint
-        verbose: true
-        args:
-          - --color
-          - --fix

taskledger-0.3.1/.taskledger.toml

@@ -0,0 +1,30 @@
+# Project-local taskledger configuration.
+# This file lives in the source project root.
+config_version = 2
+taskledger_dir = '.taskledger'
+
+# Stable project identity. Commit this with your source tree.
+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 = 84
+ledger_branch_guard = "off"
+
+[prompt_profiles.planning]
+profile = "balanced"
+question_policy = "ask_when_missing"
+max_required_questions = 5
+min_acceptance_criteria = 1
+todo_granularity = "implementation_steps"
+require_files = true
+require_test_commands = true
+require_expected_outputs = true
+require_validation_hints = true
+plan_body_detail = "normal"
+required_question_topics = []
+extra_guidance = ""
+
+[agent_logging]
+enabled = true

{taskledger-0.2.0 → taskledger-0.3.1}/API.md

@@ -53,6 +53,8 @@ from taskledger.errors import (
 - `project_doctor`
 - `project_export`
 - `project_import`
+- `project_export_archive`
+- `project_import_archive`
 - `project_snapshot`
 - `project_tree`
 
@@ -71,7 +73,10 @@ from taskledger.errors import (
 - `cancel_task`
 - `uncancel_task`
 - `close_task`
+- `archive_task`
+- `unarchive_task`
 - `create_follow_up_task`
+- `list_archived_task_summaries`
 - `add_requirement`
 - `remove_requirement`
 - `waive_requirement`
@@ -99,17 +104,34 @@ 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`
 - `materialize_plan_todos`
 - `list_plan_versions`
 - `show_plan`
 - `diff_plan`
 - `lint_plan`
+- `plan_guidance`
 - `approve_plan`
 - `reject_plan`
 - `revise_plan`
 - `run_planning_command`
 
+Planning guidance API example:
+
+```python
+from pathlib import Path
+
+from taskledger.api.plans import plan_guidance
+
+payload = plan_guidance(Path.cwd(), "task-0001")
+# payload includes: kind, task_id, has_project_guidance, guidance, profile, question_policy
+```
+
 ### `taskledger.api.questions`
 
 - `add_question`

taskledger-0.3.1/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+## 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
+
+- Added `taskledger task record` for creating done tasks that represent manually completed work, with change records, evidence, and implementation summaries. Does not acquire locks or activate the task. Recorded tasks are included in release changelogs.
+- Added branch-scoped ledger state with `taskledger ledger` command group (`status`, `list`, `fork`, `switch`, `adopt`, `doctor`). Each git branch can maintain its own isolated task ledger, with `adopt` for copying branch-local task history into the current ledger.
+- Added `taskledger tree` command to render ledger and task structure with follow-up nesting, subtree filtering, release boundaries, and per-ledger release counts in both human and JSON output.
+- Added compressed export/import with a project UUID guard to prevent importing archives into the wrong project, plus archive member-count and manifest/payload size limits for safety.
+- Added `taskledger status --check` to run doctor diagnostics alongside status, keeping the default `status` fast by avoiding full record parsing.
+- Added structured diagnostics to `taskledger doctor` JSON output with task IDs, change IDs, run IDs, types, relative paths, and actionable repair hints.
+- Added explicit `repair` command for existing planning-command change records that were incorrectly persisted as code changes.
+- Added a top-level `Makefile` with a `release-check` automation target (compile, test, lint, type-check, build, twine check).
+- Added AST-based service boundary guardrail tests with explicit whitelists and documented rationale.
+
+### Changed
+
+- Split core plan/implement/validate service entrypoints from `tasks.py` into dedicated `planning_flow.py`, `implementation_flow.py`, and `validation_flow.py` modules. `tasks.py` remains a compatibility facade.
+- Decoupled validation service from private task helpers by extracting shared query logic into a new `task_queries` module.
+- Planning commands are now persisted as planning-run evidence (worklog/artifacts/event) instead of creating `CodeChangeRecord` entries.
+- Replaced chmod-dependent storage write failure test with a deterministic synthetic `OSError` monkeypatch.
+- Sped up test suite with test-only fast fsync bypass, command-runner seam, and reduced subprocess-heavy setup.
+
+### Fixed
+
+- Fixed import replace so it no longer restores stale locks across machines.
+
+### Documentation
+
+- Documented branch-scoped ledger workflow, `task record` usage and warnings, `tree` command, and `make release-check` across README, RST docs, API docs, and the taskledger skill.
+- Added `docs/service_boundary_whitelist.md` documenting temporary module/function boundary whitelist entries and split targets.
+
+### Quality
+
+- Expanded regression coverage for branch-scoped ledgers, task record, tree command, compressed export/import, doctor diagnostics, status performance, service boundaries, and planning command persistence. Repo-wide pytest, ruff, and mypy passed.
+
+## v0.1.2 - 2026-04-30
+
+### Fixed
+
+- Fixed orphaned planning run lifecycle recovery so plan regeneration safely finishes the latest orphaned planning run with audit evidence, plan approval rejects tasks with any running run, and `implement start` reports structured conflict details including run id, run type, lock match status, and suggested diagnostic command.
+- Aligned `next-action` and `can implement` so they never recommend `implement start` when a running run or run/lock mismatch blocks implementation.
+- Expanded `taskledger doctor` and `taskledger doctor locks` to report run/lock mismatches with specific repair guidance.
+
+### Added
+
+- Added `taskledger repair run` for guarded, reasoned, audited repair of orphaned running planning runs.
+
+### Documentation
+
+- Updated taskledger skill, command contract, and API docs with running-run conflict protocol and `repair run` usage.
+
+### Quality
+
+- Expanded regression coverage for plan regeneration recovery, approval guards, next-action alignment, doctor diagnostics, and repair lifecycle. Targeted pytest, ruff, format, and mypy passed.
+
+## v0.1.1 - 2026-04-29
+
+### Added
+
+- Added `task follow-up` to create linked post-completion child tasks, preserve closure metadata, and show parent and follow-up relationships in task and handoff views.
+- Added durable release records and a new `taskledger release` command group with `tag`, `list`, `show`, and `changelog`, including export/import support and public API coverage.
+- Added planning helpers with `question add-many`, `plan template`, richer regeneration hints in `next-action`, and recovery commands for orphaned implementation work with `implement resume`, `task uncancel`, and `can implement-resume`.
+
+### Changed
+
+- Hardened CLI startup so optional command-group import failures no longer block core commands, and launcher failures return structured diagnostics.
+
+### Fixed
+
+- Fixed recovery guidance for uncancelled tasks with orphaned implementation runs so `next-action` and `can implement` recommend `implement resume` instead of a fresh start.
+
+### Documentation
+
+- Documented release tagging, changelog generation, planning helpers, follow-up task workflow, and recovery semantics across README, RST docs, API docs, and the taskledger skill.
+
+### Quality
+
+- Expanded regression coverage for follow-up tasks, release workflow, CLI import resilience, planning helpers, and implementation recovery. Repo-wide pytest, ruff, and mypy passed.
+
+## v0.1.0 - 2026-04-29
+
+### Added
+
+- Added initial unit test coverage for `storage/common`, `storage/init`, `storage/repos`, `domain/policies`, and `services/doctor_v2`, raising overall coverage from 62% to 65%.
+- Added a second coverage pass for storage memories, items, contexts, validation, and dashboard services, raising overall coverage to 73%.
+- Added question status filtering plus `taskledger question answers` with markdown and JSON output.
+- Added `taskledger plan lint`, stricter executable-plan linting, and approval gating for lint failures.
+- Added focused worker contexts and durable handoff snapshots for implementer and reviewer workflows.
+- Added richer `next-action` output with next item, command hints, and progress details.
+- Added project-root config discovery and external storage roots via `taskledger.toml`.
+- Added the localhost-only read-only `taskledger serve` dashboard.
+- Added an explicit failed-validation recovery path with `taskledger implement restart`.
+- Added compact single-agent workflow guidance and richer `todo next` and `todo show` hints.
+
+### Changed
+
+- Hardened agent guardrails by requiring reasons for approval escape hatches, blocking empty-todo approvals by default, and adding durable `plan command` execution.
+- Finished agent-protocol hardening with stronger typed normalization, safer plan todo materialization, and automatic todo source inference from the active lock.
+- Removed redundant derived task, plan-version, and latest-run indexes so Markdown bundles remain canonical and JSON indexes remain rebuildable caches.
+- Completed the broader pre-release cleanup pass from `todo.md`, including public API export cleanup, stricter storage diagnostics, canonical module paths, normalized JSON command naming, and packaging cleanup.
+- Extended the serve dashboard with a dedicated read model, recent-event tail loading, route caching, and non-overlapping partial refreshes for better hot-path performance.
+- Redesigned the serve dashboard into a more human-focused layout with richer sidebar metadata, accessibility coverage, and updated docs.
+- Improved dashboard review ergonomics and refresh stability with pause and resume controls, diffed rerenders, preserved details state, and lazy raw-payload rendering.
+- Finished release-readiness cleanup by consolidating maintained docs under RST and keeping `skills/taskledger/SKILL.md` as the single canonical skill file.
+
+### Fixed
+
+- Fixed `taskledger view` so todo counts and item lists reflect persisted todos instead of always showing `0/0`.
+- Fixed orphan slug-directory creation under `.taskledger/tasks/` and added repair support for existing bad directories.
+- Fixed repo-wide pre-commit and mypy failures across more than twenty files.
+- Fixed serve response handling so client disconnects no longer produce `BrokenPipeError` tracebacks.
+- Fixed the serve dashboard todo-renderer JavaScript regression that broke refresh parsing.
+
+### Quality
+
+- Improved testing depth across storage, dashboard, lifecycle, and documentation surfaces to support release readiness and regression protection.

{taskledger-0.2.0/taskledger.egg-info → taskledger-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.2.0
+Version: 0.3.1
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -82,6 +82,53 @@ The supported command surface is organized as:
 
 - `init`, `status`, `export`, `import`, `snapshot`, `release`
 
+### Which read command to use
+
+| Need                       | Command                                             |
+| -------------------------- | --------------------------------------------------- |
+| Next step                  | `next-action`                                       |
+| Next implementation item   | `todo next`                                         |
+| Active task summary        | `task show`                                         |
+| Specific task summary      | `task show TASK_REF` or `task show --task TASK_REF` |
+| Project/ledger overview    | `status`, `tree`                                    |
+| Human dashboard            | `serve`                                             |
+| Reviewable markdown report | `task report`                                       |
+| Fresh worker context       | `context` or durable `handoff show`                 |
+| Command audit              | `task transcript`                                   |
+
+## Planning guidance profiles
+
+Taskledger supports project-local advisory planning guidance under
+`[prompt_profiles.planning]` in the active project config file (`taskledger.toml`
+or `.taskledger.toml` when legacy config is still present).
+
+```toml
+[prompt_profiles.planning]
+profile = "strict"
+question_policy = "always_before_plan"
+max_required_questions = 3
+min_acceptance_criteria = 2
+todo_granularity = "atomic"
+require_files = true
+require_test_commands = true
+require_expected_outputs = true
+require_validation_hints = true
+plan_body_detail = "detailed"
+required_question_topics = ["scope", "compatibility", "test strategy"]
+extra_guidance = "Every plan must mention docs, tests, and rollback or repair behavior."
+```
+
+Inspect guidance for the active task:
+
+```bash
+taskledger plan guidance
+taskledger --json plan guidance
+```
+
+This guidance is advisory and cannot override lifecycle gates, user approval,
+validation requirements, lock rules, or higher-priority harness instructions.
+See `docs/usage.rst` for the full key reference and workflow details.
+
 ## Install
 
 ```bash
@@ -117,6 +164,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."
 
@@ -137,6 +185,16 @@ taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -
 taskledger validate finish --result passed --summary "Validated the rewrite."
 ```
 
+To revise a proposed plan, re-enter planning and edit an exported workspace
+copy. Never edit `.taskledger/` files directly:
+
+```bash
+taskledger plan revise
+taskledger plan export --version latest --file ./plan.md
+# edit ./plan.md
+taskledger plan upsert --file ./plan.md
+```
+
 For manually completed work (e.g., manual testing, operations tasks, or work
 completed outside the task-first lifecycle), use `task record` to create a
 done task directly without acquiring lifecycle locks. **Note**: `task record`
@@ -148,6 +206,17 @@ taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod
 taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"
 ```
 
+Archive is a visibility operation: it hides tasks from default list/tree/dashboard
+views without deleting history. Task ids stay monotonic and are never reused.
+Slugs can be reused after archive.
+
+```bash
+taskledger task archive task-0030 --reason "Hide historical task"
+taskledger task list --archived
+taskledger task unarchive task-0030 --reason "Need to continue work" --slug task-0030-reopened
+taskledger tree --include-archived
+```
+
 If validation finds an implementation bug, keep the accepted plan and restart
 implementation explicitly:
 
@@ -340,6 +409,7 @@ Use `--json` for machine-readable payloads:
 taskledger --json status --full
 taskledger --json task active
 taskledger --json task show
+taskledger --json task show task-0001
 taskledger --json context --for validation --format json
 ```
 
@@ -441,11 +511,32 @@ for task-first handoff guidance.
 ## Export, import, and snapshots
 
 ```bash
-taskledger export ./taskledger-transfer.tar.gz
+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
 ```
 
+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
+`project_name` is missing, taskledger falls back to the workspace directory name.
+Import safety still relies on `project_uuid`, not the name/slug.
+
+`--include-bodies` and `--include-run-artifacts` now change archive content:
+
+- `--no-include-bodies` strips record body text (`body` / `context_body`) from exported payloads.
+- `--include-run-artifacts` embeds task and agent-log artifact files under `artifacts/` in the archive.
+
 Cross-machine imports preserve durable task/run data, but imported runtime locks
 are quarantined by default. After importing an in-progress implementation,
 run:
@@ -457,6 +548,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.2.0 → taskledger-0.3.1}/README.md

@@ -39,6 +39,53 @@ The supported command surface is organized as:
 
 - `init`, `status`, `export`, `import`, `snapshot`, `release`
 
+### Which read command to use
+
+| Need                       | Command                                             |
+| -------------------------- | --------------------------------------------------- |
+| Next step                  | `next-action`                                       |
+| Next implementation item   | `todo next`                                         |
+| Active task summary        | `task show`                                         |
+| Specific task summary      | `task show TASK_REF` or `task show --task TASK_REF` |
+| Project/ledger overview    | `status`, `tree`                                    |
+| Human dashboard            | `serve`                                             |
+| Reviewable markdown report | `task report`                                       |
+| Fresh worker context       | `context` or durable `handoff show`                 |
+| Command audit              | `task transcript`                                   |
+
+## Planning guidance profiles
+
+Taskledger supports project-local advisory planning guidance under
+`[prompt_profiles.planning]` in the active project config file (`taskledger.toml`
+or `.taskledger.toml` when legacy config is still present).
+
+```toml
+[prompt_profiles.planning]
+profile = "strict"
+question_policy = "always_before_plan"
+max_required_questions = 3
+min_acceptance_criteria = 2
+todo_granularity = "atomic"
+require_files = true
+require_test_commands = true
+require_expected_outputs = true
+require_validation_hints = true
+plan_body_detail = "detailed"
+required_question_topics = ["scope", "compatibility", "test strategy"]
+extra_guidance = "Every plan must mention docs, tests, and rollback or repair behavior."
+```
+
+Inspect guidance for the active task:
+
+```bash
+taskledger plan guidance
+taskledger --json plan guidance
+```
+
+This guidance is advisory and cannot override lifecycle gates, user approval,
+validation requirements, lock rules, or higher-priority harness instructions.
+See `docs/usage.rst` for the full key reference and workflow details.
+
 ## Install
 
 ```bash
@@ -74,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."
 
@@ -94,6 +142,16 @@ taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -
 taskledger validate finish --result passed --summary "Validated the rewrite."
 ```
 
+To revise a proposed plan, re-enter planning and edit an exported workspace
+copy. Never edit `.taskledger/` files directly:
+
+```bash
+taskledger plan revise
+taskledger plan export --version latest --file ./plan.md
+# edit ./plan.md
+taskledger plan upsert --file ./plan.md
+```
+
 For manually completed work (e.g., manual testing, operations tasks, or work
 completed outside the task-first lifecycle), use `task record` to create a
 done task directly without acquiring lifecycle locks. **Note**: `task record`
@@ -105,6 +163,17 @@ taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod
 taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"
 ```
 
+Archive is a visibility operation: it hides tasks from default list/tree/dashboard
+views without deleting history. Task ids stay monotonic and are never reused.
+Slugs can be reused after archive.
+
+```bash
+taskledger task archive task-0030 --reason "Hide historical task"
+taskledger task list --archived
+taskledger task unarchive task-0030 --reason "Need to continue work" --slug task-0030-reopened
+taskledger tree --include-archived
+```
+
 If validation finds an implementation bug, keep the accepted plan and restart
 implementation explicitly:
 
@@ -297,6 +366,7 @@ Use `--json` for machine-readable payloads:
 taskledger --json status --full
 taskledger --json task active
 taskledger --json task show
+taskledger --json task show task-0001
 taskledger --json context --for validation --format json
 ```
 
@@ -398,11 +468,32 @@ for task-first handoff guidance.
 ## Export, import, and snapshots
 
 ```bash
-taskledger export ./taskledger-transfer.tar.gz
+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
 ```
 
+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
+`project_name` is missing, taskledger falls back to the workspace directory name.
+Import safety still relies on `project_uuid`, not the name/slug.
+
+`--include-bodies` and `--include-run-artifacts` now change archive content:
+
+- `--no-include-bodies` strips record body text (`body` / `context_body`) from exported payloads.
+- `--include-run-artifacts` embeds task and agent-log artifact files under `artifacts/` in the archive.
+
 Cross-machine imports preserve durable task/run data, but imported runtime locks
 are quarantined by default. After importing an in-progress implementation,
 run:
@@ -414,6 +505,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.2.0 → taskledger-0.3.1}/docs/api.rst

@@ -32,6 +32,8 @@ Project API
 - ``project_doctor``
 - ``project_export``
 - ``project_import``
+- ``project_export_archive``
+- ``project_import_archive``
 - ``project_snapshot``
 - ``project_tree``
 
@@ -51,7 +53,10 @@ Task API
 - ``cancel_task``
 - ``uncancel_task``
 - ``close_task``
+- ``archive_task``
+- ``unarchive_task``
 - ``create_follow_up_task``
+- ``list_archived_task_summaries``
 - ``add_requirement``
 - ``remove_requirement``
 - ``waive_requirement``
@@ -80,10 +85,16 @@ Plan API
 - ``propose_plan``
 - ``plan_template``
 - ``upsert_plan``
+- ``PlanReviewOptions``
+- ``build_plan_review_payload``
+- ``render_plan_review``
+- ``export_plan``
+- ``amend_plan``
 - ``list_plan_versions``
 - ``show_plan``
 - ``diff_plan``
 - ``lint_plan``
+- ``plan_guidance``
 - ``approve_plan``
 - ``reject_plan``
 - ``revise_plan``
@@ -91,6 +102,15 @@ Plan API
 - ``materialize_plan_todos``
 - ``run_planning_command``
 
+Planning guidance example:
+
+.. code-block:: python
+
+   from pathlib import Path
+   from taskledger.api.plans import plan_guidance
+
+   payload = plan_guidance(Path.cwd(), "task-0001")
+
 Question API
 ------------