taskledger 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -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 = 84
 ledger_branch_guard = "off"
 
 [prompt_profiles.planning]

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

@@ -104,6 +104,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`

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

@@ -1,5 +1,68 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.3.0
+Version: 0.3.1
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -164,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."
 
@@ -512,7 +513,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 +525,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 +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.3.0 → taskledger-0.3.1}/README.md

@@ -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."
 
@@ -469,7 +470,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 +482,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 +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.3.0 → taskledger-0.3.1}/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``

{taskledger-0.3.0 → taskledger-0.3.1}/docs/command_contract.rst

@@ -84,6 +84,22 @@ storage, and ``taskledger plan amend`` applies structured plan-review edits:
 Plan proposal commands that accept ``--file`` reject file paths under
 ``.taskledger/`` because that directory is private durable ledger state.
 
+Plan review command
+-------------------
+
+``taskledger plan review`` is a read-only approval-facing plan renderer:
+
+.. code-block:: bash
+
+   taskledger plan review [--task TASK_REF] [--version N] [--format markdown|json] [-o PATH]
+
+Rules:
+
+* defaults to the active task when ``--task`` is omitted;
+* defaults to the latest proposed plan in ``plan_review`` stage when ``--version`` is omitted;
+* renders Markdown by default and can emit JSON-formatted content with ``--format json``;
+* when ``-o/--output`` is provided, writes rendered content to a file path.
+
 Archive import lock policy
 --------------------------
 
@@ -92,6 +108,7 @@ Archive imports support explicit lock handling:
 .. code-block:: bash
 
    taskledger import ./taskledger-transfer.tar.gz --replace [--lock-policy drop|quarantine|keep]
+   taskledger import ./taskledger-task-<project>-<ledger>-task-0040-<ts>.tar.gz [--id-policy preserve|renumber-on-conflict|fail-on-conflict]
 
 The default is ``quarantine`` so imported source-machine runtime locks are not
 restored as active ``lock.yaml`` files. ``keep`` is diagnostic-only behavior
@@ -122,6 +139,19 @@ still authoritative for import safety.
 ``taskledger import --dry-run`` must not mutate taskledger state for either
 archive or JSON payload imports.
 
+Export task selection
+---------------------
+
+Taskledger export supports full-ledger and task-scoped archives:
+
+.. code-block:: bash
+
+   taskledger export
+   taskledger export ./backup.tar.gz
+   taskledger export --task task-0040
+   taskledger export task-0040
+   taskledger export task-0040 -o ./task0040.tar.gz
+
 Positional Resource Refs
 ------------------------
 

{taskledger-0.3.0 → taskledger-0.3.1}/docs/public_surface.rst

@@ -39,7 +39,7 @@ question subcommands
 plan subcommands
 ----------------
 
-- ``plan start``, ``plan propose``, ``plan template``, ``plan upsert``, ``plan lint``, ``plan approve``, ``plan accept``, ``plan reject``, ``plan show``, ``plan diff``
+- ``plan start``, ``plan propose``, ``plan template``, ``plan upsert``, ``plan review``, ``plan lint``, ``plan approve``, ``plan accept``, ``plan reject``, ``plan show``, ``plan diff``
 - ``plan regenerate --from-answers``, ``plan materialize-todos``, ``plan command -- ...``
 
 task reporting and transcripts

{taskledger-0.3.0 → taskledger-0.3.1}/docs/transfer.rst

@@ -24,9 +24,41 @@ When no output path is passed to ``taskledger export``, taskledger writes:
 
    taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
 
+For task-scoped exports:
+
+.. code-block:: text
+
+   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
+------------------------------------------------
+
+.. code-block:: bash
+
+   # 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`` / ``.taskledger.toml``.
+- ``.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.
+- 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.
+
 Dry-run import
 --------------
 

{taskledger-0.3.0 → taskledger-0.3.1}/docs/usage.rst

@@ -56,8 +56,9 @@ Task-first workflow
    taskledger question add --text "Should exports include v2?"
    taskledger question answer-many --text "q-0001: Yes."
    taskledger plan upsert --from-answers --criterion "Accepted workflow is implemented." --file ./plan.md
-    taskledger plan lint --version 1
-    taskledger plan accept --version 1 --note "Ready."
+   taskledger plan review --version 1
+   taskledger plan lint --version 1
+   taskledger plan accept --version 1 --note "Ready."
 
 Planning guidance profiles
 --------------------------
@@ -192,6 +193,7 @@ parent and run the normal lifecycle on that child:
    taskledger task follow-up rewrite-v2 "Rename submit label" --description "Small post-completion delta." --activate
    taskledger plan start
    taskledger plan upsert --file ./plan.md
+   taskledger plan review --version 1
    taskledger plan accept --version 1 --note "Ready."
    taskledger implement start
    taskledger validate start
@@ -474,7 +476,11 @@ Export and snapshots
 
    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-task-planledger-main-task-0040-20260509T101500Z.tar.gz --id-policy fail-on-conflict
    taskledger import ./taskledger-transfer.tar.gz --replace
    taskledger snapshot ./artifacts
 
@@ -483,6 +489,7 @@ Default export filenames are project-specific:
 .. code-block:: 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 unset, taskledger falls back to the workspace directory name.
@@ -503,3 +510,19 @@ runtime locks by default. For an imported in-progress implementation, run:
 
 Use ``--lock-policy keep`` only when you explicitly want diagnostic lock
 restoration behavior.
+
+Single-task transfer from a config-only checkout
+------------------------------------------------
+
+.. code-block:: 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

{taskledger-0.3.0 → taskledger-0.3.1}/pyproject.toml

@@ -14,7 +14,7 @@ taskledger = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "-p no:odoo --strict-markers"
+addopts = "--strict-markers"
 testpaths = ["tests"]
 python_files = "test_*.py"
 markers = [

{taskledger-0.3.0 → taskledger-0.3.1}/skills/taskledger/SKILL.md

@@ -121,7 +121,7 @@ If any `taskledger ...` command fails with a Python traceback before taskledger
 19. A proposed plan must include concrete `acceptance_criteria` and `todos` in front matter unless the user explicitly says the task is trivial.
 20. After writing the plan, do not run `taskledger repair lock`; planning locks are released by plan proposal/upsert. Run `taskledger next-action`.
 21. After `taskledger plan upsert --from-answers`, run `taskledger question status`. If it still reports `Plan regeneration needed: True`, do not ask for approval. Inspect `taskledger question answers`, `taskledger plan show --version N`, and `taskledger doctor`.
-22. Before asking the user to approve, run `taskledger plan lint --version N` and fix lint errors. Lint waiver flags are on `plan approve`/`plan accept`, not on `plan lint`.
+22. Before asking the user to approve, run `taskledger plan review --version N` and paste or summarize the rendered review. Then run `taskledger plan lint --version N` if the review did not include lint. Do not record approval until the user explicitly approves.
 23. Record approval only with clear user intent such as approve, accept, go ahead, or start implementation. Prefer `taskledger plan accept --version N --note "User approved in harness: ..."` for normal chat approval. Use `taskledger plan approve --version N --actor user --approval-source explicit_chat --note "..."` only when explicit actor/source metadata is needed (advanced).
 24. Never replace a user-provided rich plan with only generated YAML criteria and todos. Preserve the user's plan body after the front matter and use front matter only to expose machine-readable fields to Taskledger.
 25. A Taskledger plan is not just YAML front matter. The YAML block is for machine-readable `goal`, `acceptance_criteria`, `todos`, file links, and test commands. The rich human plan must remain as Markdown after the second `---`. Before approval, inspect `taskledger plan show --version N` or the saved `plan-vN.md` and verify that the accepted plan body is non-empty and contains the implementation rationale.
@@ -142,7 +142,7 @@ The plan file should use version ids like `plan-v1`, `plan-v2` in references. Do
    - `taskledger implement change --path ... --kind edit --summary "..."`
    - Run verification through `taskledger implement command -- ...` so exit code and output are recorded.
    - `implement command` mirrors the inner command exit code by default. Use `--allow-failure` when you intentionally want to record a non-zero command without failing the wrapper command.
-   - Mark each todo done only after the relevant command or inspection evidence exists: `taskledger todo done <todo-id> --evidence "implement command change-NNNN exited 0"`.
+   - Mark each todo done only after the relevant command or inspection evidence exists: `taskledger todo done <todo-id> --evidence "check-NNNN exited 0"`.
    - Optional: add `--source planner|implementer|user` to override the inferred source, though this is rarely needed.
 6. `taskledger implement checklist` after each meaningful change to track progress.
 7. In Git workspaces, prefer `taskledger implement scan-changes --from-git --summary "..."` before `implement finish` so change evidence includes a git-backed reconciliation checkpoint.
@@ -321,6 +321,7 @@ taskledger next-action
 taskledger plan guidance
 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 "User approved in harness."
 taskledger context --for implementation --format markdown
@@ -330,6 +331,9 @@ taskledger context --for code-reviewer --run run-0008
 taskledger release tag 0.4.1 --at-task task-0030 --note "0.4.1 released"
 taskledger release changelog 0.4.2 --since 0.4.1 --until-task task-0035 --output /tmp/taskledger-0.4.2-changelog-source.md
 taskledger import ./taskledger-transfer.tar.gz --dry-run
+taskledger export --task task-0040
+taskledger export task-0040 -o ./task0040.tar.gz
+taskledger import ./task0040.tar.gz --id-policy renumber-on-conflict
 taskledger ledger status
 taskledger ledger fork feature-a
 taskledger ledger switch main

{taskledger-0.3.0 → taskledger-0.3.1}/taskledger/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
-__commit_id__ = commit_id = 'gabec514e0'
+__commit_id__ = commit_id = 'g9f557bd45'

{taskledger-0.3.0 → taskledger-0.3.1}/taskledger/api/plans.py

@@ -1,6 +1,11 @@
 from pathlib import Path
 
 from taskledger.services.plan_lint import lint_plan
+from taskledger.services.plan_review import (
+    PlanReviewOptions,
+    build_plan_review_payload,
+    render_plan_review,
+)
 from taskledger.services.tasks import (
     amend_plan,
     approve_plan,
@@ -36,6 +41,9 @@ __all__ = [
     "revise_plan",
     "run_planning_command",
     "lint_plan",
+    "PlanReviewOptions",
+    "build_plan_review_payload",
+    "render_plan_review",
     "plan_guidance",
 ]
 

{taskledger-0.3.0 → taskledger-0.3.1}/taskledger/api/project.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, cast
 
@@ -265,6 +266,8 @@ def project_export_archive(
     output_path: Path | None = None,
     include_bodies: bool = True,
     include_run_artifacts: bool = False,
+    task_refs: Sequence[str] = (),
+    overwrite: bool = False,
 ) -> dict[str, object]:
     """Export current-ledger state into a compressed archive file."""
     return write_project_archive(
@@ -272,6 +275,8 @@ def project_export_archive(
         output_path=output_path,
         include_bodies=include_bodies,
         include_run_artifacts=include_run_artifacts,
+        task_refs=task_refs,
+        overwrite=overwrite,
     )
 
 
@@ -282,6 +287,7 @@ def project_import_archive(
     replace: bool = False,
     dry_run: bool = False,
     lock_policy: str = "quarantine",
+    id_policy: str = "preserve",
 ) -> dict[str, object]:
     """Import a taskledger archive into the current project."""
     return import_project_archive(
@@ -290,6 +296,7 @@ def project_import_archive(
         replace=replace,
         dry_run=dry_run,
         lock_policy=lock_policy,
+        id_policy=id_policy,
     )
 
 

{taskledger-0.3.0 → taskledger-0.3.1}/taskledger/cli.py

@@ -1090,12 +1090,41 @@ def repair_task_dirs_command(ctx: typer.Context) -> None:
     )
 
 
+def _looks_like_archive_output_target(value: str) -> bool:
+    candidate = value.strip()
+    lowered = candidate.lower()
+    if (
+        lowered.endswith(".tar.gz")
+        or lowered.endswith(".tgz")
+        or lowered.endswith(".json")
+    ):
+        return True
+    path = Path(candidate)
+    if path.is_absolute():
+        return True
+    if "/" in candidate or "\\" in candidate:
+        return True
+    if path.parent != Path("."):
+        return True
+    return False
+
+
 @app.command("export")
 def export_command(
     ctx: typer.Context,
+    target_or_output: Annotated[
+        str | None,
+        typer.Argument(
+            help="Task ref convenience selector or output archive path (.tar.gz)."
+        ),
+    ] = None,
+    task_ref: Annotated[
+        str | None,
+        typer.Option("--task", help="Task ref to export as task-scoped archive."),
+    ] = None,
     output: Annotated[
         Path | None,
-        typer.Argument(help="Output archive path (.tar.gz)."),
+        typer.Option("--output", "-o", help="Output archive path (.tar.gz)."),
     ] = None,
     include_bodies: Annotated[
         bool,
@@ -1118,20 +1147,61 @@ def export_command(
 ) -> None:
     state = ctx.obj
     assert isinstance(state, CLIState)
-    if output is not None and output.exists() and not overwrite:
+    resolved_output = output
+    task_refs: list[str] = []
+    if task_ref is not None:
+        task_refs = [resolve_cli_task(state.cwd, task_ref).id]
+        if target_or_output is not None:
+            if output is not None:
+                emit_error(
+                    ctx,
+                    LaunchError(
+                        "export received both positional output and --output. Use one."
+                    ),
+                )
+                raise typer.Exit(code=2)
+            resolved_output = Path(target_or_output)
+    elif target_or_output is not None:
+        if _looks_like_archive_output_target(target_or_output):
+            if output is not None:
+                emit_error(
+                    ctx,
+                    LaunchError(
+                        "export received both positional output and --output. Use one."
+                    ),
+                )
+                raise typer.Exit(code=2)
+            resolved_output = Path(target_or_output)
+        else:
+            try:
+                task_refs = [resolve_cli_task(state.cwd, target_or_output).id]
+            except LaunchError as exc:
+                emit_error(
+                    ctx,
+                    LaunchError(
+                        f"No task found for '{target_or_output}'. To write an archive "
+                        "to that filename, use: taskledger export -o "
+                        f"{target_or_output}.tar.gz"
+                    ),
+                )
+                raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+    if resolved_output is not None and resolved_output.exists() and not overwrite:
         emit_error(
             ctx,
             LaunchError(
-                f"Output file already exists: {output}. Use --overwrite to replace."
+                "Output file already exists: "
+                f"{resolved_output}. Use --overwrite to replace."
             ),
         )
         raise typer.Exit(code=1)
     try:
         payload = project_export_archive(
             state.cwd,
-            output_path=output,
+            output_path=resolved_output,
             include_bodies=include_bodies,
             include_run_artifacts=include_run_artifacts,
+            task_refs=task_refs,
+            overwrite=overwrite,
         )
     except LaunchError as exc:
         emit_error(ctx, exc)
@@ -1148,6 +1218,7 @@ def export_command(
         f"exported taskledger archive: {payload['path']}\n"
         f"project: {project_label}\n"
         f"ledger: {payload['ledger_ref']}\n"
+        f"scope: {payload.get('archive_scope', 'ledger')}\n"
         f"tasks: {counts.get('tasks', 0)}"
     )
     emit_payload(ctx, payload, human=human)
@@ -1172,6 +1243,16 @@ def import_command(
             help="How imported live locks are handled: drop, quarantine, keep.",
         ),
     ] = "quarantine",
+    id_policy: Annotated[
+        str,
+        typer.Option(
+            "--id-policy",
+            help=(
+                "Task ID conflict policy for task archives: "
+                "preserve, renumber-on-conflict, fail-on-conflict."
+            ),
+        ),
+    ] = "preserve",
 ) -> None:
     state = ctx.obj
     assert isinstance(state, CLIState)
@@ -1210,6 +1291,7 @@ def import_command(
             replace=replace,
             dry_run=dry_run,
             lock_policy=lock_policy,
+            id_policy=id_policy,
         )
     except LaunchError as exc:
         emit_error(ctx, exc)
@@ -1234,8 +1316,18 @@ def import_command(
             f"imported taskledger archive: {source}\n"
             f"project: {project_label}\n"
             f"ledger: {payload['ledger_ref']}\n"
-            f"replace: {payload['replace']}"
+            f"replace: {payload['replace']}\n"
+            f"scope: {payload.get('archive_scope', 'ledger')}"
         )
+    task_id_map = payload.get("task_id_map")
+    if isinstance(task_id_map, dict) and task_id_map:
+        id_lines = ["id map:"]
+        for source_id, target_id in sorted(task_id_map.items()):
+            if source_id == target_id:
+                id_lines.append(f"  {source_id} -> {target_id}")
+            else:
+                id_lines.append(f"  {source_id} -> {target_id}  renumbered")
+        human = f"{human}\n" + "\n".join(id_lines)
     if isinstance(payload.get("next_command"), str):
         human = f"{human}\nnext: {payload['next_command']}"
     emit_payload(ctx, payload, human=human)

{taskledger-0.3.0 → taskledger-0.3.1}/taskledger/cli_implement.py

@@ -307,10 +307,14 @@ def command_command(
     except LaunchError as exc:
         emit_error(ctx, exc)
         raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+    check_data = payload.get("check") or {}
     emit_payload(
         ctx,
         payload,
-        human=f"ran implementation command exit={payload['exit_code']}",
+        human=(
+            f"recorded check {check_data.get('check_id', '?')}"
+            f" exit={payload['exit_code']}"
+        ),
     )
     raw_exit_code = payload.get("exit_code", 0)
     if isinstance(raw_exit_code, int):