taskledger 0.1.1__tar.gz → 0.1.2__tar.gz

{taskledger-0.1.1 → taskledger-0.1.2}/API.md

@@ -86,6 +86,7 @@ from taskledger.errors import (
 - `can_perform`
 - `reindex`
 - `repair_task_record`
+- `repair_orphaned_planning_run`
 
 ### `taskledger.api.plans`
 

{taskledger-0.1.1 → taskledger-0.1.2}/CHANGELOG.md

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

{taskledger-0.1.1/taskledger.egg-info → taskledger-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.1.1
+Version: 0.1.2
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -40,6 +40,11 @@ Provides-Extra: rich
 Requires-Dist: rich; extra == "rich"
 Dynamic: license-file
 
+[![PyPI - Version](https://img.shields.io/pypi/v/taskledger)](https://pypi.org/project/taskledger/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/taskledger)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/taskledger)
+[![codecov](https://codecov.io/gh/holgern/taskledger/graph/badge.svg?token=6usFHwM5Ul)](https://codecov.io/gh/holgern/taskledger)
+
 # taskledger
 
 `taskledger` is a task-first durable state layer for staged coding work. It keeps
@@ -414,13 +419,19 @@ taskledger snapshot ./artifacts
 
 ## Skill packaging
 
+Agent workflows work best when the `taskledger` skill is installed in the
+coding harness. The CLI has a task-first lifecycle with explicit planning,
+approval, implementation, validation, locks, and handoff gates; without the
+skill, an agent may not know the intended command sequence or gate semantics.
+
 The canonical skill file lives at:
 
 ```text
 skills/taskledger/SKILL.md
 ```
 
-No additional `skills/taskledger/examples/` directory is required.
+Keep this skill outside the Python package. No additional
+`skills/taskledger/examples/` directory is required.
 
 ## Development
 

{taskledger-0.1.1 → taskledger-0.1.2}/README.md

@@ -1,3 +1,8 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/taskledger)](https://pypi.org/project/taskledger/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/taskledger)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/taskledger)
+[![codecov](https://codecov.io/gh/holgern/taskledger/graph/badge.svg?token=6usFHwM5Ul)](https://codecov.io/gh/holgern/taskledger)
+
 # taskledger
 
 `taskledger` is a task-first durable state layer for staged coding work. It keeps
@@ -372,13 +377,19 @@ taskledger snapshot ./artifacts
 
 ## Skill packaging
 
+Agent workflows work best when the `taskledger` skill is installed in the
+coding harness. The CLI has a task-first lifecycle with explicit planning,
+approval, implementation, validation, locks, and handoff gates; without the
+skill, an agent may not know the intended command sequence or gate semantics.
+
 The canonical skill file lives at:
 
 ```text
 skills/taskledger/SKILL.md
 ```
 
-No additional `skills/taskledger/examples/` directory is required.
+Keep this skill outside the Python package. No additional
+`skills/taskledger/examples/` directory is required.
 
 ## Development
 

{taskledger-0.1.1 → taskledger-0.1.2}/docs/api.rst

@@ -66,6 +66,7 @@ Task API
 - ``can_perform``
 - ``reindex``
 - ``repair_task_record``
+- ``repair_orphaned_planning_run``
 
 Plan API
 --------

{taskledger-0.1.1 → taskledger-0.1.2}/docs/command_contract.rst

@@ -114,9 +114,26 @@ status but ``active_stage`` is missing, ``next-action`` must not report
 ``The task is cancelled.`` For an orphaned implementation with a still-running
 latest implementation run and no active lock, it should direct agents to
 ``taskledger implement resume --task TASK_REF --reason "..."``.
+For an approved task with a non-implementation run still marked running,
+``next-action`` must not direct agents to ``taskledger implement start``.
+It should report a repair-oriented action and point to ``taskledger doctor``.
 Truly cancelled tasks recover through ``taskledger task uncancel --reason "..."``
 to a durable non-active stage rather than directly re-entering an active stage.
 
+Run and lock repair
+-------------------
+
+``taskledger doctor`` and ``taskledger doctor locks`` report running runs without
+matching active locks. Orphaned running planning runs can be finished only
+through an explicit repair command with a reason:
+
+.. code-block:: bash
+
+   taskledger repair run --task TASK_REF --run RUN_ID --reason "Planning was already completed."
+
+The repair command refuses to finish non-planning runs, non-running runs, or
+runs that still have a matching active lock.
+
 Post-completion follow-up deltas
 --------------------------------
 

{taskledger-0.1.1 → taskledger-0.1.2}/docs/usage.rst

@@ -9,6 +9,11 @@ Installation
    python -m pip install -e .
    python -m pip install -e ".[dev]"
 
+Agent workflows work best when the ``taskledger`` skill is installed in the
+coding harness. The CLI uses a task-first lifecycle with explicit planning,
+approval, implementation, validation, locks, and handoff gates; without the
+skill, an agent may not know the intended command sequence or gate semantics.
+
 Initialize state
 ----------------
 
@@ -125,6 +130,7 @@ over a broad generated context read:
 
 Rules for agents:
 
+* Install the ``taskledger`` skill in the coding harness before relying on agent-driven workflows.
 * Prefer ``next-action`` and ``todo next`` over generated context during normal work.
 * Use the todo ``validation_hint`` before marking a todo done.
 * Record concise evidence with ``todo done``.

{taskledger-0.1.1 → taskledger-0.1.2}/skills/taskledger/SKILL.md

@@ -22,7 +22,7 @@ Use taskledger for staged coding work that needs a durable task record, reviewab
 - Do not mark validation passed without checking every mandatory acceptance criterion.
 - Do not inline large source files into taskledger records by default; use `@path` references.
 - Do not import or call `taskledger.storage.*`, `taskledger.services.*`, or `taskledger.domain.*` from ad-hoc Python during normal task work. Use CLI commands or public `taskledger.api.*` only.
-- Do not use repair commands (`lock break`, `repair lock`, `repair task`, `repair index`) in the normal lifecycle. Use them only after `doctor`/`lock show` proves there is stale or corrupted state.
+- Do not use repair commands (`lock break`, `repair lock`, `repair run`, `repair task`, `repair index`) in the normal lifecycle. Use them only after `doctor`/`lock show` proves there is stale or corrupted state.
 - Do not pass approval escape hatches such as `--allow-empty-criteria`, `--allow-open-questions`, `--allow-empty-todos`, `--no-materialize-todos`, `--allow-lint-errors`, or `--allow-agent-approval` unless the user explicitly requested that bypass and gave a reason. All escape hatches require `--reason`.
 
 ## Fresh context entry protocol
@@ -90,8 +90,9 @@ If any `taskledger ...` command fails with a Python traceback before taskledger
 14. For diagnostic commands needed to build the plan, preserve their output in a linked artifact or use `taskledger plan command -- ...`.
 15. A proposed plan must include concrete `acceptance_criteria` and `todos` in front matter unless the user explicitly says the task is trivial.
 16. After writing the plan, do not run `taskledger lock break`; planning locks are released by plan proposal/upsert. Run `taskledger next-action`.
-17. Before asking the user to approve, run `taskledger plan lint --version N` and fix lint errors. Do not ask for approval on plans with lint errors.
-18. Record approval only with clear user intent such as approve, accept, go ahead, or start implementation: `taskledger plan approve --version N --actor user --note "User approved in harness: ..."` or `taskledger plan accept --version N --note "User approved in harness: ..."`.
+17. 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`.
+18. Before asking the user to approve, run `taskledger plan lint --version N` and fix lint errors. Do not ask for approval on plans with lint errors.
+19. Record approval only with clear user intent such as approve, accept, go ahead, or start implementation: `taskledger plan approve --version N --actor user --note "User approved in harness: ..."` or `taskledger plan accept --version N --note "User approved in harness: ..."`.
 
 The plan file should use version ids like `plan-v1`, `plan-v2` in references. Do not use zero-padded forms.
 
@@ -100,6 +101,8 @@ The plan file should use version ids like `plan-v1`, `plan-v2` in references. Do
 1. `taskledger context --for implementation --format markdown`
 2. `taskledger implement start`
    - If validation already failed and the plan is still correct, prefer `taskledger implement restart --summary "Fix failed validation findings."`
+   - If implementation start fails because another run is already running, stop and run `taskledger doctor`, not only `taskledger doctor locks`.
+   - Do not edit project code until implementation has started or a valid implementation resume command succeeds.
 3. `taskledger implement checklist` - review the mandatory and optional todo checklist before starting.
 4. If no todos exist, create a concrete checklist: `taskledger todo add --text "..."`. Todo source is inferred automatically from the active lock: `implementer` during implementation, `planner` during planning, `user` otherwise.
 5. Work one todo at a time:
@@ -223,6 +226,9 @@ To receive work:
 - If breaking an implementation lock leaves a running implementation run behind, use `taskledger implement resume --reason "..."` instead of `implement start`.
 - If `task show` reports `status_stage=implementing` but `active_stage` is missing, do not run `task uncancel`; run `taskledger next-action` and resume when it reports `implement-resume`.
 - If a cancelled task is restored with `task uncancel`, run `taskledger next-action` before starting work. If the task still has a running implementation run, resume that run instead of starting a new one.
+- If `taskledger next-action` recommends a command but `taskledger can <action>` rejects it, treat this as a lifecycle inconsistency. Run `taskledger doctor` and follow the repair guidance.
+- Use `taskledger repair run --task TASK --run RUN --reason "..."` only when diagnostics identify an orphaned running planning run with no matching active lock.
+- Never use repair to bypass approval, validation, or active implementation locks.
 - If validation fails, record the failure and return to implementation or replanning.
 - If indexes are stale, run `taskledger repair index`; `taskledger reindex` is a compatibility alias.
 - If a task is truly cancelled and the user wants to continue, use `taskledger task uncancel --reason "..." [--to STAGE]` to restore a safe durable stage before re-entering an active stage.

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
 
-__commit_id__ = commit_id = 'g5289096c8'
+__commit_id__ = commit_id = 'g9eda38db5'

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/api/tasks.py

@@ -20,6 +20,7 @@ from taskledger.services.tasks import (
     reindex,
     remove_file_link,
     remove_requirement,
+    repair_orphaned_planning_run,
     repair_task_record,
     resolve_active_task,
     set_todo_done,
@@ -62,4 +63,5 @@ __all__ = [
     "can_perform",
     "reindex",
     "repair_task_record",
+    "repair_orphaned_planning_run",
 ]

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/cli.py

@@ -518,6 +518,41 @@ def repair_task_command(
     emit_payload(ctx, payload, human="\n".join(human_lines))
 
 
+@repair_app.command("run")
+def repair_run_command(
+    ctx: typer.Context,
+    reason: Annotated[str, typer.Option("--reason")],
+    run_id: Annotated[str | None, typer.Option("--run")] = None,
+    task_ref: Annotated[
+        str | None,
+        typer.Option("--task", help="Task ref. Defaults to the active task."),
+    ] = None,
+) -> None:
+    from taskledger.api.tasks import repair_orphaned_planning_run
+
+    state = ctx.obj
+    assert isinstance(state, CLIState)
+    try:
+        task = resolve_cli_task(state.cwd, task_ref)
+        payload = repair_orphaned_planning_run(
+            state.cwd,
+            task.id,
+            run_id=run_id,
+            reason=reason,
+        )
+    except LaunchError as exc:
+        emit_error(ctx, exc)
+        raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+    emit_payload(
+        ctx,
+        payload,
+        human=(
+            f"finished orphaned {payload['run_type']} run {payload['run_id']} "
+            f"for {payload['task_id']}\nnext: {payload['next_command']}"
+        ),
+    )
+
+
 @repair_app.command("task-dirs")
 def repair_task_dirs_command(ctx: typer.Context) -> None:
     from taskledger.services.doctor import cleanup_orphan_slug_dirs

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/cli_misc.py

@@ -911,7 +911,7 @@ def emit_doctor_locks_command(ctx: typer.Context) -> None:
     emit_payload(
         ctx,
         payload,
-        human=_expired_locks_human(payload["expired_locks"]),
+        human=_lock_inspection_human(payload),
     )
 
 
@@ -996,6 +996,29 @@ def _emit_handoff(
     emit_payload(ctx, payload, human=human)
 
 
+def _lock_inspection_human(payload: dict[str, object]) -> str:
+    expired = payload.get("expired_locks")
+    mismatches = payload.get("run_lock_mismatches")
+    lines = ["EXPIRED LOCKS"]
+    if isinstance(expired, list) and expired:
+        for item in expired:
+            if isinstance(item, dict):
+                lines.append(str(item.get("task_id")))
+    else:
+        lines.append("(empty)")
+    lines.append("RUN/LOCK MISMATCHES")
+    if isinstance(mismatches, list) and mismatches:
+        for item in mismatches:
+            if isinstance(item, dict):
+                lines.append(
+                    f"{item.get('task_id')} {item.get('run_type')} "
+                    f"{item.get('run_id')} next: {item.get('next_command')}"
+                )
+    else:
+        lines.append("(empty)")
+    return "\n".join(lines)
+
+
 def _expired_locks_human(payload: object) -> str:
     if not isinstance(payload, list) or not payload:
         return "EXPIRED LOCKS\n(empty)"

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/command_inventory.py

@@ -126,6 +126,7 @@ COMMAND_METADATA: dict[str, tuple[str, str]] = {
     "doctor indexes": (REPAIR, "safe_read_only"),
     "repair index": (REPAIR, "ledger_mutation"),
     "repair lock": (REPAIR, "ledger_mutation"),
+    "repair run": (REPAIR, "ledger_mutation"),
     "repair task": (REPAIR, "ledger_mutation"),
     "repair task-dirs": (REPAIR, "ledger_mutation"),
     "migrate status": (STABLE_FOR_AGENTS, "safe_read_only"),

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/services/doctor.py

@@ -39,6 +39,7 @@ def inspect_v2_project(workspace_root: Path) -> dict[str, object]:  # noqa: C901
     errors: list[str] = []
     warnings: list[str] = []
     repair_hints: list[str] = []
+    run_lock_mismatches: list[dict[str, object]] = []
     config_candidates = [
         resolved_paths.workspace_root / filename
         for filename in PROJECT_CONFIG_FILENAMES
@@ -175,6 +176,24 @@ def inspect_v2_project(workspace_root: Path) -> dict[str, object]:  # noqa: C901
             errors.append(
                 f"Task {task.id} has a running run without a matching active lock."
             )
+            for run in running_runs:
+                next_command = "taskledger doctor"
+                if run.run_type == "planning":
+                    next_command = (
+                        "taskledger repair run "
+                        f"--task {task.id} --run {run.run_id} "
+                        '--reason "Finish orphaned planning run."'
+                    )
+                run_lock_mismatches.append(
+                    {
+                        "kind": "running_run_without_matching_lock",
+                        "task_id": task.id,
+                        "run_id": run.run_id,
+                        "run_type": run.run_type,
+                        "status": run.status,
+                        "next_command": next_command,
+                    }
+                )
             running_implementation = next(
                 (
                     run
@@ -198,7 +217,7 @@ def inspect_v2_project(workspace_root: Path) -> dict[str, object]:  # noqa: C901
                 )
             else:
                 repair_hints.append(
-                    "Inspect the run/lock pair and either repair it or break the lock "
+                    "Inspect the run/lock pair and repair the orphaned run "
                     f"for task {task.id} explicitly."
                 )
         if active_lock is not None and active_stage is None and not running_runs:
@@ -211,13 +230,13 @@ def inspect_v2_project(workspace_root: Path) -> dict[str, object]:  # noqa: C901
             )
 
         for change in list_changes(workspace_root, task.id):
-            run = run_map.get((task.id, change.implementation_run))
-            if run is None:
+            change_run = run_map.get((task.id, change.implementation_run))
+            if change_run is None:
                 errors.append(
                     f"Change {change.change_id} references missing "
                     f"implementation run {change.implementation_run}."
                 )
-            elif run.run_type != "implementation":
+            elif change_run.run_type != "implementation":
                 errors.append(
                     f"Change {change.change_id} references "
                     f"non-implementation run {change.implementation_run}."
@@ -346,16 +365,19 @@ def inspect_v2_project(workspace_root: Path) -> dict[str, object]:  # noqa: C901
         "repair_hints": repair_hints,
         "broken_links": broken_links,
         "expired_locks": expired_locks,
+        "run_lock_mismatches": run_lock_mismatches,
     }
 
 
 def inspect_v2_locks(workspace_root: Path) -> dict[str, object]:
     payload = inspect_v2_project(workspace_root)
     expired_locks = list(cast(list[object], payload["expired_locks"]))
+    run_lock_mismatches = list(cast(list[object], payload["run_lock_mismatches"]))
     return {
         "kind": "taskledger_lock_inspection",
-        "healthy": not expired_locks,
+        "healthy": not expired_locks and not run_lock_mismatches,
         "expired_locks": expired_locks,
+        "run_lock_mismatches": run_lock_mismatches,
     }
 
 

{taskledger-0.1.1 → taskledger-0.1.2}/taskledger/services/navigation.py

@@ -26,6 +26,8 @@ from taskledger.services.tasks import (
     _optional_run,
     _planning_template_hints,
     _resumable_implementation_run,
+    _running_run_details,
+    _running_runs,
     _task_active_stage,
     _task_with_sidecars,
     _todo_command_hints,
@@ -322,6 +324,38 @@ def _inactive_status_next_action(
         )
     if task.status_stage == "approved":
         next_item = _task_next_item(task)
+        running_runs = _running_runs(workspace_root, task)
+        non_resumable_runs = [
+            run
+            for run in running_runs
+            if not (
+                run.run_type == "implementation"
+                and run.run_id == task.latest_implementation_run
+                and lock is None
+            )
+        ]
+        if non_resumable_runs:
+            run = non_resumable_runs[0]
+            blockers.append(
+                {
+                    "kind": "running_run",
+                    "message": (
+                        f"Task has running {run.run_type} run {run.run_id}; "
+                        "run `taskledger doctor`."
+                    ),
+                    **_running_run_details(task, run, lock),
+                }
+            )
+            return (
+                "repair-run-state",
+                (
+                    f"Task is approved, but {run.run_type} run {run.run_id} "
+                    "is still marked running."
+                ),
+                next_item,
+                blockers,
+                progress,
+            )
         resumable_run = _resumable_implementation_run(
             workspace_root,
             task,
@@ -416,7 +450,7 @@ def can_perform(workspace_root: Path, task_ref: str, action: str) -> dict[str, o
     active_stage = _task_active_stage(workspace_root, task, lock=lock)
     ok = False
     reason = ""
-    blocking: list[dict[str, str]] = []
+    blocking: list[dict[str, object]] = []
     if action == "plan":
         ok = task.status_stage in {"draft", "plan_review"} and lock is None
         reason = (
@@ -437,11 +471,7 @@ def can_perform(workspace_root: Path, task_ref: str, action: str) -> dict[str, o
                 }
             )
     elif action == "implement":
-        running_runs = [
-            item
-            for item in list_runs(workspace_root, task.id)
-            if item.status == "running"
-        ]
+        running_runs = _running_runs(workspace_root, task)
         ok = (
             task.status_stage in IMPLEMENTABLE_TASK_STAGES
             and task.accepted_plan_version is not None
@@ -462,17 +492,33 @@ def can_perform(workspace_root: Path, task_ref: str, action: str) -> dict[str, o
             blocking.append(
                 {"kind": "approval", "message": "No accepted plan version."}
             )
-        blocking.extend(_dependency_blockers(workspace_root, task))
+        blocking.extend(
+            cast(list[dict[str, object]], _dependency_blockers(workspace_root, task))
+        )
         if running_runs:
             running_run = running_runs[0]
+            can_resume = (
+                running_run.run_type == "implementation"
+                and running_run.run_id == task.latest_implementation_run
+            )
             blocking.append(
                 {
                     "kind": "implementation",
                     "message": (
                         f"Task already has running {running_run.run_type} run "
-                        f"{running_run.run_id}; use taskledger implement resume."
+                        f"{running_run.run_id}; "
+                        + (
+                            "use taskledger implement resume."
+                            if can_resume
+                            else "run taskledger doctor."
+                        )
+                    ),
+                    "command_hint": (
+                        _implement_resume_command(task.id)
+                        if can_resume
+                        else "taskledger doctor"
                     ),
-                    "command_hint": _implement_resume_command(task.id),
+                    **_running_run_details(task, running_run, lock),
                 }
             )
         if lock is not None:
@@ -534,7 +580,7 @@ def can_perform(workspace_root: Path, task_ref: str, action: str) -> dict[str, o
                     "message": "No running implementation run is available to resume.",
                 }
             )
-        blocking.extend(dependency_blockers)
+        blocking.extend(cast(list[dict[str, object]], dependency_blockers))
         if lock is not None:
             blocking.append(
                 {
@@ -599,7 +645,9 @@ def can_perform(workspace_root: Path, task_ref: str, action: str) -> dict[str, o
                     "message": "No previous implementation run is available.",
                 }
             )
-        blocking.extend(_dependency_blockers(workspace_root, task))
+        blocking.extend(
+            cast(list[dict[str, object]], _dependency_blockers(workspace_root, task))
+        )
         if lock is not None:
             blocking.append(
                 {
@@ -952,6 +1000,7 @@ def _next_action_command(action: str) -> str | None:
             "taskledger validate finish --result passed --summary SUMMARY"
         ),
         "repair-lock": "taskledger lock show",
+        "repair-run-state": "taskledger doctor",
     }.get(action)