taskledger 0.5.1__tar.gz → 0.5.2__tar.gz

{taskledger-0.5.1 → taskledger-0.5.2}/.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 = 136
+ledger_next_task_number = 139
 ledger_branch_guard = "off"
 
 [prompt_profiles.planning]

{taskledger-0.5.1 → taskledger-0.5.2}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [v0.5.2] - 2026-07-10
+
+### Added
+
+- Added plan review approval brief with decision status, question status, and structured body heading lint rule
+
+### Quality
+
+- Improved type safety in WorkspaceContentSnapshot and WorktreePathEntry deserialization with round-trip tests
+
+<!-- generated by releaseledger -->
+
+## [v0.5.1] - 2026-06-26
+
+### Added
+
+- Added plan check command and plan input service for validating editable plan input without creating or revising plans
+- Added implement snapshot refresh command to accept current workspace as implementation snapshot when validation is blocked by IMPLEMENTATION_SNAPSHOT_MISMATCH
+
+### Documentation
+
+- Converted Sphinx RST documentation to Markdown with myst-parser
+
+<!-- generated by releaseledger -->
+
 ## [v0.5.0] - 2026-06-14
 
 ### Added

{taskledger-0.5.1/taskledger.egg-info → taskledger-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.5.1
+Version: 0.5.2
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt

{taskledger-0.5.1 → taskledger-0.5.2}/skills/taskledger/SKILL.md

@@ -215,6 +215,41 @@ not create changelog entries, render changelog context, or edit `CHANGELOG.md`.
 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 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).
+
+### Approval presentation protocol
+
+Before asking the user to approve a proposed plan:
+
+1. Run `taskledger plan review --version N`.
+2. Present a readable approval brief in chat. Do not only say that the plan is ready.
+3. Include, in this order:
+   - scope / decision status
+   - required question status as `Questions X/Y answered`
+   - proposed plan title
+   - `Summary`
+   - `Implementation Changes`
+   - `Tests`
+   - `Assumptions`
+   - `Out of Scope / Deferred`
+   - exact approval instruction
+4. Use the stored plan body and machine-readable commitments from the review output. Do not invent extra scope.
+5. If review output reports blockers, do not ask for approval. Present the blockers and the next remediation command.
+6. If no blockers remain, ask for explicit approval using wording like:
+   `Reply with "approve" or "go ahead" to start implementation.`
+
+Bad approval prompt:
+
+```text
+Plan plan-v1 is ready for approval. It covers tests and docs. Reply approve.
+```
+
+Good approval prompt:
+
+```text
+Use the structured approval brief above, including scope status, question counts,
+summary, implementation changes, tests, assumptions, and out-of-scope notes.
+```
+
 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.
 

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.1'
-__version_tuple__ = version_tuple = (0, 5, 1)
+__version__ = version = '0.5.2'
+__version_tuple__ = version_tuple = (0, 5, 2)
 
-__commit_id__ = commit_id = 'ga6ec6591d'
+__commit_id__ = commit_id = 'g1e080d8af'

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/cli.py

@@ -14,7 +14,7 @@ import typer
 
 try:
     from typer._click import (
-        exceptions as _typer_click_exceptions,  # type: ignore[import-not-found]
+        exceptions as _typer_click_exceptions,
     )
 except ImportError:  # pragma: no cover - older Typer
     TyperClickException: Any = None

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/services/plan_lint.py

@@ -34,6 +34,13 @@ _PLACEHOLDER_PATTERNS: list[re.Pattern[str]] = [
     re.compile(r"\bclean up\b", re.IGNORECASE),
 ]
 
+_REQUIRED_APPROVAL_HEADINGS = (
+    "Summary",
+    "Implementation Changes",
+    "Tests",
+    "Assumptions",
+)
+
 
 @dataclass(frozen=True, slots=True)
 class PlanLintIssue:
@@ -154,6 +161,31 @@ def _run_lint_rules(plan: PlanRecord, strict: bool) -> list[PlanLintIssue]:
                 hint="Add implementation notes after the closing `---` separator.",
             )
         )
+
+    # 3c. missing_approval_heading
+    missing_approval_headings = [
+        heading
+        for heading in _REQUIRED_APPROVAL_HEADINGS
+        if _body_section(plan.body, heading) is None
+    ]
+    if missing_approval_headings:
+        severity: Severity = "error" if strict else "warning"
+        issues.append(
+            PlanLintIssue(
+                severity=severity,
+                code="missing_approval_heading",
+                location="plan.body",
+                message=(
+                    "Plan body should include approval-ready headings: "
+                    + ", ".join(_REQUIRED_APPROVAL_HEADINGS)
+                    + "."
+                ),
+                hint=(
+                    "Use `taskledger plan template --file ./plan.md` and keep the "
+                    "approval-ready body structure."
+                ),
+            )
+        )
     # 4. todo_not_concrete
     for index, todo in enumerate(plan.todos):
         if not _todo_is_concrete(todo):

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/services/plan_review.py

@@ -49,6 +49,24 @@ def build_plan_review_payload(
     open_required = _required_open_question_ids(questions)
     stale_answer_ids = _stale_answer_question_ids(questions, plan)
 
+    required_questions = [
+        question for question in questions if question.required_for_plan
+    ]
+    answered_required_questions = [
+        question for question in required_questions if question.status == "answered"
+    ]
+    open_required_questions = [
+        question for question in required_questions if question.status == "open"
+    ]
+    question_status = {
+        "required_answered": len(answered_required_questions),
+        "required_total": len(required_questions),
+        "required_open": [
+            {"id": question.id, "text": question.question}
+            for question in open_required_questions
+        ],
+    }
+
     if task.status_stage != "plan_review":
         blockers.append(
             {
@@ -125,6 +143,23 @@ def build_plan_review_payload(
         warnings.append("Plan lint was not included in this review output.")
 
     approval_ready = len(blockers) == 0
+
+    if open_required_questions:
+        decision_status = (
+            "Approval is blocked because required planning questions remain unanswered."
+        )
+    elif stale_answer_ids:
+        decision_status = (
+            "Approval is blocked because answered questions are not reflected "
+            "in this plan."
+        )
+    elif blockers:
+        decision_status = "Approval is blocked by review blockers."
+    else:
+        decision_status = (
+            "No required planning decision remains; review assumptions and "
+            "out-of-scope notes before approving."
+        )
     commands = (
         _review_commands(plan.plan_version) if options.include_next_commands else []
     )
@@ -140,6 +175,8 @@ def build_plan_review_payload(
         "plan_version": plan.plan_version,
         "plan_status": plan.status,
         "approval_ready": approval_ready,
+        "decision_status": decision_status,
+        "question_status": question_status,
         "blockers": blockers,
         "warnings": warnings,
         "lint": lint_payload,
@@ -208,6 +245,7 @@ def render_plan_review_markdown(payload: dict[str, object]) -> str:
             lines.append(f"- {warning}")
         lines.append("")
 
+    _append_approval_brief(lines, payload)
     lines.append("## Summary")
     lines.append("")
     lines.append(str(payload.get("summary") or "(no summary available)"))
@@ -296,6 +334,32 @@ def render_plan_review_markdown(payload: dict[str, object]) -> str:
     return result
 
 
+def _append_approval_brief(lines: list[str], payload: dict[str, object]) -> None:
+    lines.append("## Approval Brief")
+    lines.append("")
+    lines.append(f"- Decision status: {payload.get('decision_status')}")
+    question_status = payload.get("question_status")
+    if isinstance(question_status, dict):
+        answered = question_status.get("required_answered", 0)
+        total = question_status.get("required_total", 0)
+        lines.append(f"- Questions {answered}/{total} answered.")
+    lines.append("")
+    lines.append("### Unanswered Required Questions")
+    lines.append("")
+    open_questions = (
+        question_status.get("required_open")
+        if isinstance(question_status, dict)
+        else None
+    )
+    if isinstance(open_questions, list) and open_questions:
+        for question in open_questions:
+            if isinstance(question, dict):
+                lines.append(f"- {question.get('id')}: {question.get('text')}")
+    else:
+        lines.append("- none")
+    lines.append("")
+
+
 def render_plan_review(
     workspace_root: Path,
     task_ref: str,

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/services/tasks.py

@@ -2012,15 +2012,29 @@ def _render_plan_template(
         "<!-- Required: keep this body. It is the implementation handoff context.",
         "     Run `taskledger plan check --file ./plan.md` before upsert. -->",
         "",
-        "## Goal",
+        "# <short approval plan title>",
         "",
-        "<repeat or expand the goal in human prose>",
+        "## Summary",
         "",
-        "## Implementation notes",
+        "<2-5 sentences describing the outcome, rationale, and boundaries>",
         "",
-        "<describe the approach, architecture, and key decisions>",
+        "## Implementation Changes",
         "",
-        "## Validation plan",
+        "- <specific code/config/docs change>",
+        "- <specific code/config/docs change>",
+        "",
+        "## Tests",
+        "",
+        "- <test command or regression case>",
+        "- <manual verification, if needed>",
+        "",
+        "## Assumptions",
+        "",
+        "- <assumption the approver should accept>",
+        "",
+        "## Out of Scope",
+        "",
+        "- <nearby cleanup or behavior change intentionally excluded>",
         "",
         "## Plan input checklist before upsert",
         "",

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/services/workflow_guidance.py

@@ -93,6 +93,32 @@ Use this editable plan-input contract:
   Todo-level `files:` is not captured.
 - Keep enough Markdown body content for the implementer handoff.
 
+Approval-ready Markdown body structure:
+
+Use these headings after the closing `---` front matter:
+
+# <Plan title>
+
+## Summary
+
+Explain the intended outcome and why the plan is bounded.
+
+## Implementation Changes
+
+List the concrete code, config, docs, and behavior changes.
+
+## Tests
+
+List the automated and manual checks that prove the plan.
+
+## Assumptions
+
+List assumptions the user should accept before approval.
+
+## Out of Scope
+
+List adjacent cleanup or behavior changes intentionally excluded.
+
 Minimal front matter:
 
 ```yaml

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger/services/workspace_snapshot.py

@@ -34,15 +34,15 @@ class WorktreePathEntry:
 
     @classmethod
     def from_dict(cls, data: dict[str, object]) -> WorktreePathEntry:
+        size = data.get("size")
+        content_hash = data.get("content_hash")
         return cls(
             path=str(data["path"]),
             status=str(data["status"]),
             exists=bool(data["exists"]),
             kind=str(data["kind"]),
-            size=data.get("size") if isinstance(data.get("size"), int) else None,
-            content_hash=data.get("content_hash")
-            if isinstance(data.get("content_hash"), str)
-            else None,
+            size=size if isinstance(size, int) else None,
+            content_hash=content_hash if isinstance(content_hash, str) else None,
         )
 
 
@@ -70,29 +70,30 @@ class WorkspaceContentSnapshot:
 
     @classmethod
     def from_dict(cls, data: dict[str, object]) -> WorkspaceContentSnapshot:
-        entries = tuple(
-            WorktreePathEntry.from_dict(item)
-            for item in data.get("entries", [])
-            if isinstance(item, dict)
+        raw_entries = data.get("entries")
+        entries = (
+            tuple(
+                WorktreePathEntry.from_dict(item)
+                for item in raw_entries
+                if isinstance(item, dict)
+            )
+            if isinstance(raw_entries, list)
+            else ()
         )
+        git_commit = data.get("git_commit")
+        dirty = data.get("dirty")
+        content_hash = data.get("content_hash")
+        paths_hash = data.get("paths_hash")
+        entry_count = data.get("entry_count")
+        captured_at = data.get("captured_at")
         return cls(
-            git_commit=data.get("git_commit")
-            if isinstance(data.get("git_commit"), str)
-            else None,
-            dirty=data.get("dirty") if isinstance(data.get("dirty"), bool) else None,
-            content_hash=data.get("content_hash")
-            if isinstance(data.get("content_hash"), str)
-            else None,
-            paths_hash=data.get("paths_hash")
-            if isinstance(data.get("paths_hash"), str)
-            else None,
-            entry_count=data.get("entry_count")
-            if isinstance(data.get("entry_count"), int)
-            else len(entries),
+            git_commit=git_commit if isinstance(git_commit, str) else None,
+            dirty=dirty if isinstance(dirty, bool) else None,
+            content_hash=content_hash if isinstance(content_hash, str) else None,
+            paths_hash=paths_hash if isinstance(paths_hash, str) else None,
+            entry_count=entry_count if isinstance(entry_count, int) else len(entries),
             entries=entries,
-            captured_at=data.get("captured_at")
-            if isinstance(data.get("captured_at"), str)
-            else None,
+            captured_at=captured_at if isinstance(captured_at, str) else None,
         )
 
 

{taskledger-0.5.1 → taskledger-0.5.2/taskledger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.5.1
+Version: 0.5.2
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger.egg-info/SOURCES.txt

@@ -379,6 +379,7 @@ tests/test_agent_session_protocol.py
 tests/test_atomic_fast_io.py
 tests/test_cli_command_contract.py
 tests/test_cli_import_resilience.py
+tests/test_cli_runner_compatibility.py
 tests/test_code_reviews.py
 tests/test_command_example_linter.py
 tests/test_command_inventory.py
@@ -456,6 +457,7 @@ tests/test_worker_pipeline_handoff.py
 tests/test_worker_pipeline_plan_template.py
 tests/test_worker_pipeline_todos.py
 tests/test_workflow_guidance.py
+tests/test_workspace_snapshot.py
 tests/support/__init__.py
 tests/support/builders.py
 tests/support/fake_command_runner.py

{taskledger-0.5.1 → taskledger-0.5.2}/taskledger.egg-info/scm_file_list.json

@@ -293,6 +293,7 @@
     "tests/test_sync_git.py",
     "tests/test_docs_and_skill.py",
     "tests/test_worker_pipeline_handoff.py",
+    "tests/test_workspace_snapshot.py",
     "tests/test_worker_pipeline_todos.py",
     "tests/test_storage_init.py",
     "tests/test_help_subprocess.py",
@@ -319,6 +320,7 @@
     "tests/test_storage_yaml_store.py",
     "tests/test_command_example_linter.py",
     "tests/test_taskledger_v2_cli.py",
+    "tests/test_cli_runner_compatibility.py",
     "tests/test_storage_repos.py",
     "tests/test_command_inventory.py",
     "tests/test_domain_policies.py",

taskledger-0.5.2/taskledger.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.2",
+  "distance": 0,
+  "node": "g1e080d8afa12581b6fc5d5484e86b05060f16b56",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-10"
+}

{taskledger-0.5.1 → taskledger-0.5.2}/tests/conftest.py

@@ -12,32 +12,30 @@ if str(ROOT) not in sys.path:
 sys.dont_write_bytecode = True
 
 
-# Tests create many short-lived Markdown/YAML records under tmp_path.
-# Production durability still fsyncs; pytest opts into faster temporary IO.
-os.environ.setdefault("TASKLEDGER_TEST_FAST_IO", "1")
-
 import shutil  # noqa: E402
 import weakref  # noqa: E402
-from collections.abc import Mapping, Sequence  # noqa: E402
-from typing import IO, Any  # noqa: E402
+from typing import Any  # noqa: E402
 
-import click  # noqa: E402
-import click.testing  # noqa: E402
 import pytest  # noqa: E402
+import typer.testing as typer_testing  # noqa: E402
 from typer import Typer  # noqa: E402
 from typer.main import get_command as _typer_get_command  # noqa: E402
 from typer.testing import CliRunner as _TyperCliRunner  # noqa: E402
 
-# Click 8.2+ removed ``mix_stderr`` from CliRunner.__init__.  Typer's
-# CliRunner inherits from Click, so passing ``mix_stderr=False`` raises
-# TypeError/AttributeError on modern Click.  Patch __init__ to silently
-# accept and discard the parameter so every test file keeps working.
+# Some test modules still instantiate ``CliRunner(mix_stderr=False)`` for
+# historical reasons. Newer Typer/Click releases reject that argument, so the
+# constructor wrapper below discards it. This shim exists only for test
+# source compatibility and is unrelated to command caching.
 _original_cli_runner_init = _TyperCliRunner.__init__
 
 
-def _patched_cli_runner_init(self: _TyperCliRunner, **kwargs: Any) -> None:
+def _patched_cli_runner_init(
+    self: _TyperCliRunner,
+    *args: Any,
+    **kwargs: Any,
+) -> None:
     kwargs.pop("mix_stderr", None)
-    _original_cli_runner_init(self, **kwargs)
+    _original_cli_runner_init(self, *args, **kwargs)
 
 
 _TyperCliRunner.__init__ = _patched_cli_runner_init  # type: ignore[assignment]
@@ -52,8 +50,16 @@ from tests.support.builders import (  # noqa: E402
 
 # Typer rebuilds the full Click command tree on every CliRunner.invoke call.
 # Taskledger's CLI is intentionally broad, so repeated rebuilds dominate the
-# CLI-heavy test suite, especially on Windows. Cache the immutable Click command
-# tree per Typer app for tests; each invocation still gets a fresh Click context.
+# CLI-heavy test suite, especially on Windows. Cache the immutable Click
+# command tree per Typer app for tests; each invocation still gets a fresh
+# Click context.
+#
+# The cache is implemented by swapping the private command-lookup helper used
+# by ``typer.testing``. Typer's own ``CliRunner.invoke`` then calls our cached
+# function instead of rebuilding the command tree. We do NOT replace
+# ``CliRunner.invoke`` with ``click.testing.CliRunner.invoke`` because the two
+# runner implementations do not share instance state; on Click 8.1.x the
+# cross-class call reads ``self.mix_stderr`` and raises AttributeError.
 _CLICK_COMMAND_CACHE: weakref.WeakKeyDictionary[Typer, Any] = (
     weakref.WeakKeyDictionary()
 )
@@ -67,31 +73,8 @@ def _cached_click_command(app: Typer) -> Any:
     return cached
 
 
-def _invoke_with_cached_click_command(
-    self: _TyperCliRunner,
-    app: Typer,
-    args: str | Sequence[str] | None = None,
-    input: bytes | str | IO[Any] | None = None,
-    env: Mapping[str, str | None] | None = None,
-    catch_exceptions: bool = True,
-    color: bool = False,
-    **extra: Any,
-) -> click.testing.Result:
-    if not hasattr(self, "capture"):
-        self.capture = "sys"
-    return click.testing.CliRunner.invoke(
-        self,  # type: ignore[arg-type]
-        _cached_click_command(app),
-        args=args,
-        input=input,
-        env=env,
-        catch_exceptions=catch_exceptions,
-        color=color,
-        **extra,
-    )
-
-
-_TyperCliRunner.invoke = _invoke_with_cached_click_command  # type: ignore[assignment]
+if hasattr(typer_testing, "_get_command"):
+    typer_testing._get_command = _cached_click_command  # type: ignore[attr-defined]
 
 
 def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None: