taskledger 0.4.0__tar.gz → 0.4.1__tar.gz

taskledger-0.4.1/.archledger.toml

@@ -0,0 +1,62 @@
+# Project-local archledger configuration.
+# This file lives in the source project root.
+config_version = 5
+archledger_dir = "../archledger-state/taskledger"
+
+# Stable project identity. Commit this with your source tree.
+project_uuid = "5d87017e-db40-4c72-90c8-5d3753e13f43"
+project_name = "taskledger"
+
+[source]
+format = "markdown"
+front_matter = "yaml"
+section_extension = ".md"
+record_extension = ".md"
+schema_version = 2
+
+[build]
+default_format = "markdown"
+default_output_dir = "build"
+include_draft = false
+include_superseded = false
+strict = false
+keep_intermediate = false
+converter = "auto"
+
+[arc42]
+template_version = "9.0-EN"
+language = "en"
+title = "Architecture Documentation"
+include_help = false
+
+[skill]
+installed = true
+path = "skills/archledger/SKILL.md"
+
+[tracking]
+enabled = true
+state_file = "source-state.json"
+scanner = "auto"
+include = [
+  "**/*.py",
+  "**/*.toml",
+  "**/*.md",
+  "**/*.adoc",
+  "**/*.rst",
+  "**/*.j2",
+  "**/*.yaml",
+  "**/*.yml",
+  "**/*.json",
+]
+exclude = [
+  ".git/**",
+  ".venv/**",
+  "**/__pycache__/**",
+  ".mypy_cache/**",
+  ".pytest_cache/**",
+  ".ruff_cache/**",
+  "dist/**",
+  "build/**",
+]
+max_file_bytes = 1000000
+hash_algorithm = "sha256"

{taskledger-0.4.0 → taskledger-0.4.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 = 87
+ledger_next_task_number = 90
 ledger_branch_guard = "off"
 
 [prompt_profiles.planning]

{taskledger-0.4.0 → taskledger-0.4.1}/AGENTS.md

@@ -356,10 +356,7 @@ Docs, examples, command inventory, and skill files must agree.
 When changing commands or workflow behavior, update as needed:
 
 - `README.md`
-- `docs/command_contract.rst`
-- `docs/full_task_cycle.rst`
-- `docs/usage.rst`
-- `docs/public_surface.rst`
+- rst files in `docs/`
 - `API.md`
 - `skills/taskledger/SKILL.md`
 - `taskledger/command_inventory.py`
@@ -375,23 +372,7 @@ Do not package skills inside `taskledger/`.
 
 Every non-trivial behavior change needs verification.
 
-Prefer the test closest to the changed logic:
-
-- policy/gate change -> `tests/test_domain_policies.py` or lifecycle tests
-- task lifecycle change -> `tests/test_taskledger_v2_cli.py`, `tests/test_delta_remaining_contracts.py`, or service tests
-- active-task behavior -> `tests/test_active_task.py`
-- CLI grammar -> `tests/test_cli_command_contract.py`, `tests/test_taskledger_cli_api_parity.py`
-- JSON envelope -> `tests/test_json_contracts.py`
-- docs/skill command examples -> `tests/test_docs_and_skill.py`, `tests/test_command_example_linter.py`
-- plan approval -> `tests/test_plan_approval_contract.py`
-- plan todos -> `tests/test_plan_todo_materialization.py`
-- questions/regeneration -> `tests/test_question_filter_answers.py`, `tests/test_question_plan_regeneration.py`
-- todo gates -> `tests/test_todo_implementation_gate.py`
-- locks -> `tests/test_locks_audit.py`, doctor tests
-- storage -> `tests/test_storage_*.py`, `tests/test_storage_bundle_layout.py`, `tests/test_sidecar_collections.py`
-- handoff -> `tests/test_handoff_lifecycle.py`
-- search -> `tests/test_search.py`
-- export/import -> `tests/test_taskledger_v2_exchange.py`
+Prefer the test closest to the changed logic.
 
 ### 12.2 Regression paths to test
 
@@ -416,33 +397,11 @@ Include error paths when relevant:
 
 ### 12.3 Verification command progression
 
-Start narrow. Expand only when needed.
+Start narrow. Expand only when needed. Try to run specific test files first,
+only one example for a single pytest is given, figure it out which test to run.
 
 ```bash
-python -m pip install -e .
-python -m pip install -e ".[dev]"
-
 pytest tests/test_domain_policies.py
-pytest tests/test_active_task.py
-pytest tests/test_taskledger_v2_cli.py
-pytest tests/test_delta_remaining_contracts.py
-pytest tests/test_plan_approval_contract.py
-pytest tests/test_plan_todo_materialization.py
-pytest tests/test_question_filter_answers.py
-pytest tests/test_question_plan_regeneration.py
-pytest tests/test_todo_implementation_gate.py
-pytest tests/test_locks_audit.py
-pytest tests/test_handoff_lifecycle.py
-pytest tests/test_json_contracts.py
-pytest tests/test_docs_and_skill.py
-pytest tests/test_command_example_linter.py
-pytest tests/test_storage_bundle_layout.py
-pytest tests/test_storage_common.py
-pytest tests/test_storage_contexts.py
-pytest tests/test_storage_items.py
-pytest tests/test_storage_memories.py
-pytest tests/test_storage_repos.py
-pytest tests/test_storage_validation.py
 pytest
 
 ruff check --config=.ruff.toml .

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

@@ -198,6 +198,7 @@ render_handoff(
     *,
     mode: str | None = None,
     context_for: str | None = None,
+    worker_step_id: str | None = None,
     scope: str | None = None,
     todo_id: str | None = None,
     focus_run_id: str | None = None,
@@ -208,8 +209,9 @@ create_handoff(
     workspace_root: Path,
     task_ref: str,
     *,
-    mode: str,
+    mode: str | None = None,
     context_for: str | None = None,
+    worker_step_id: str | None = None,
     scope: str | None = None,
     todo_id: str | None = None,
     focus_run_id: str | None = None,
@@ -225,7 +227,10 @@ create_handoff(
 
 Focused handoffs store the generated Markdown context snapshot in the handoff
 record body and return compact metadata, including `context_hash` and
-`context_path`.
+`context_path`. When `worker_step_id` is supplied, taskledger derives the
+handoff mode and context from the configured worker step, persists
+`worker_step_id` in the handoff record, and includes the resolved worker-step
+details in JSON context payloads.
 
 ### `taskledger.api.releases`
 

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

@@ -1,6 +1,37 @@
 # Changelog
 
-## v0.4.0 - 2026-05-18
+## v0.4.1 - 2026-05-22
+
+### Added
+
+- Added optional configurable worker pipeline overlay: opt-in `[worker_pipeline]` project config, read-only `pipeline show`, `pipeline list`, and `pipeline next` commands, worker-aware `context --worker` and `handoff create --worker` support, and worker-tagged plan todos with materialization and template hints.
+- Added guided worker-pipeline next-action metadata and command hints in `next-action` output for `guided` mode projects.
+- Added worker-pipeline config extraction into `taskledger/storage/worker_pipeline_config.py` and worker-only context rendering into `taskledger/services/worker_context.py`.
+- Added doctor warning diagnostics for stale worker-step todo and handoff references.
+- Added shell completion support: root Typer app now enables completion options, with `--install-completion` and `--show-completion` available.
+
+### Changed
+
+- Worker handoff defaults now derive from configured pipeline steps when `--worker` is specified.
+- Worker step metadata is rendered in task reports when present.
+- Review-stage worker routing advances from closed worker handoffs.
+- Plan template and todo parsing preserve `worker_step` metadata across export, regeneration, and materialization.
+- Updated service boundary whitelists for worker-pipeline and doctor scan import sites.
+
+### Documentation
+
+- Documented worker pipeline configuration, commands, guided workflow, and config fields in README, `docs/usage.rst`, `docs/full_task_cycle.rst`, and `docs/command_contract.rst`.
+- Updated `skills/taskledger/SKILL.md` with optional worker pipeline protocol guidance and guided next-action hints.
+- Updated `API.md` for public handoff API signatures with `worker_step_id`.
+- Added shell completion install and show command documentation in README and `docs/usage.rst`.
+
+### Quality
+
+- Added regression test modules for worker pipeline config, CLI commands, worker context, worker handoffs, worker todo materialization, guided next-action, and doctor warnings.
+- Expanded command inventory, JSON contract, docs/skill, and service boundary tests for the new surface.
+- Full suite: ruff and mypy clean.
+
+## v0.4.0 - 2026-05-19
 
 ### Added
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.4.0
+Version: 0.4.1
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -73,7 +73,7 @@ The supported command surface is organized as:
 
 **Operations:**
 
-- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
+- `context`, `pipeline`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -130,6 +130,73 @@ 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.
 
+## Optional worker pipelines
+
+Projects may optionally configure worker pipelines in `taskledger.toml` to guide
+fresh-context handoffs. Worker pipelines are advisory overlays on the existing
+planning, implementation, and validation lifecycle. They can be three steps,
+four steps, five steps, or custom. When no worker pipeline is configured, the
+default taskledger behavior is unchanged.
+
+```toml
+[worker_pipeline]
+enabled = true
+name = "tdd-four-context"
+mode = "guided"
+
+[[worker_pipeline.steps]]
+id = "planner"
+lifecycle_stage = "planning"
+base_context = "planner"
+
+[[worker_pipeline.steps]]
+id = "tester"
+label = "Test Writer"
+lifecycle_stage = "implementation"
+base_context = "implementer"
+actor_role = "implementer"
+kind = "check"
+description = "Add or update failing tests before code changes."
+required_output = ["New or updated failing tests with a short summary."]
+must_not = ["Do not change production code in this step."]
+todo_tag = "tests"
+test_command_policy = "may_fail"
+
+[[worker_pipeline.steps]]
+id = "coder"
+lifecycle_stage = "implementation"
+base_context = "implementer"
+kind = "todo"
+description = "Implement the approved change and make the tests pass."
+required_output = ["Code changes plus passing targeted checks."]
+must_not = ["Do not skip required validation evidence."]
+todo_tag = "implementation"
+test_command_policy = "must_pass"
+
+[[worker_pipeline.steps]]
+id = "reviewer"
+lifecycle_stage = "review"
+base_context = "code-reviewer"
+kind = "review"
+```
+
+Supported top-level keys are `enabled`, `name`, `mode`, and `steps`. Supported
+step keys are `id`, `label`, `lifecycle_stage`, `base_context`, `actor_role`,
+`kind`, `description`, `required_output`, `must_not`, `todo_tag`, and
+`test_command_policy`. `mode = "guided"` does not add lifecycle gates; it adds
+worker-step hints to `taskledger next-action`, including the pending step id plus
+ready-to-run worker context and handoff commands.
+
+```bash
+taskledger pipeline show
+taskledger pipeline next
+taskledger next-action
+taskledger context --worker tester
+taskledger pipeline context tester
+taskledger handoff create --worker tester --summary "Add failing tests only."
+taskledger plan template --with-worker-pipeline --file ./plan.md
+```
+
 ## Install
 
 ```bash
@@ -137,6 +204,22 @@ python -m pip install -e .
 python -m pip install -e ".[dev]"
 ```
 
+### Shell completion
+
+After installing `taskledger`, install completion for your current shell:
+
+```bash
+taskledger --install-completion
+```
+
+To inspect the generated completion script instead of installing it:
+
+```bash
+taskledger --show-completion
+```
+
+Restart your shell session after installation.
+
 ## Quick start
 
 Initialize durable state in the current workspace:

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

@@ -29,7 +29,7 @@ The supported command surface is organized as:
 
 **Operations:**
 
-- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
+- `context`, `pipeline`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -86,6 +86,73 @@ 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.
 
+## Optional worker pipelines
+
+Projects may optionally configure worker pipelines in `taskledger.toml` to guide
+fresh-context handoffs. Worker pipelines are advisory overlays on the existing
+planning, implementation, and validation lifecycle. They can be three steps,
+four steps, five steps, or custom. When no worker pipeline is configured, the
+default taskledger behavior is unchanged.
+
+```toml
+[worker_pipeline]
+enabled = true
+name = "tdd-four-context"
+mode = "guided"
+
+[[worker_pipeline.steps]]
+id = "planner"
+lifecycle_stage = "planning"
+base_context = "planner"
+
+[[worker_pipeline.steps]]
+id = "tester"
+label = "Test Writer"
+lifecycle_stage = "implementation"
+base_context = "implementer"
+actor_role = "implementer"
+kind = "check"
+description = "Add or update failing tests before code changes."
+required_output = ["New or updated failing tests with a short summary."]
+must_not = ["Do not change production code in this step."]
+todo_tag = "tests"
+test_command_policy = "may_fail"
+
+[[worker_pipeline.steps]]
+id = "coder"
+lifecycle_stage = "implementation"
+base_context = "implementer"
+kind = "todo"
+description = "Implement the approved change and make the tests pass."
+required_output = ["Code changes plus passing targeted checks."]
+must_not = ["Do not skip required validation evidence."]
+todo_tag = "implementation"
+test_command_policy = "must_pass"
+
+[[worker_pipeline.steps]]
+id = "reviewer"
+lifecycle_stage = "review"
+base_context = "code-reviewer"
+kind = "review"
+```
+
+Supported top-level keys are `enabled`, `name`, `mode`, and `steps`. Supported
+step keys are `id`, `label`, `lifecycle_stage`, `base_context`, `actor_role`,
+`kind`, `description`, `required_output`, `must_not`, `todo_tag`, and
+`test_command_policy`. `mode = "guided"` does not add lifecycle gates; it adds
+worker-step hints to `taskledger next-action`, including the pending step id plus
+ready-to-run worker context and handoff commands.
+
+```bash
+taskledger pipeline show
+taskledger pipeline next
+taskledger next-action
+taskledger context --worker tester
+taskledger pipeline context tester
+taskledger handoff create --worker tester --summary "Add failing tests only."
+taskledger plan template --with-worker-pipeline --file ./plan.md
+```
+
 ## Install
 
 ```bash
@@ -93,6 +160,22 @@ python -m pip install -e .
 python -m pip install -e ".[dev]"
 ```
 
+### Shell completion
+
+After installing `taskledger`, install completion for your current shell:
+
+```bash
+taskledger --install-completion
+```
+
+To inspect the generated completion script instead of installing it:
+
+```bash
+taskledger --show-completion
+```
+
+Restart your shell session after installation.
+
 ## Quick start
 
 Initialize durable state in the current workspace:

{taskledger-0.4.0 → taskledger-0.4.1}/docs/command_contract.rst

@@ -276,6 +276,9 @@ Human output should stay concise but actionable:
    todo-work: Implementation is in progress; 1 todos remain.
    Next todo: todo-0001 -- Update next-action JSON payload.
    Command: taskledger todo show todo-0001
+   Worker step: tester
+   Worker context: taskledger pipeline context tester
+   Worker handoff: taskledger handoff create --worker tester --summary "..."
    Mark todo done after evidence exists: taskledger todo done todo-0001 --evidence "..."
    Progress: 0/1 todos done
 
@@ -295,6 +298,9 @@ and may also include:
 * ``next_item`` for the concrete target
 * ``commands`` for ordered command hints with one primary command
 * ``progress`` for question, todo, or validation queues
+* ``worker_pipeline`` when an enabled ``guided`` worker pipeline has a pending
+  step; this object includes ``enabled``, ``mode``, ``next_step``,
+  ``context_command``, and ``handoff_command``
 * ``template_command`` plus ``required_plan_fields`` and
   ``recommended_plan_fields`` when the next step is regenerating a plan from
   answered questions
@@ -431,6 +437,8 @@ Focused worker contexts keep lifecycle ``mode`` separate from worker-role
 
    taskledger context --for planner|implementer|validator|spec-reviewer|code-reviewer|reviewer|full [--scope task|todo|run] [--todo TODO_ID] [--run RUN_ID] [--format markdown|json|text] [--task TASK_REF]
    taskledger handoff create --mode planning|implementation|validation|review|full [--for planner|implementer|validator|spec-reviewer|code-reviewer|reviewer|full] [--scope task|todo|run] [--todo TODO_ID] [--run RUN_ID] [--task TASK_REF]
+   taskledger handoff create --worker STEP_ID [--scope task|todo|run] [--todo TODO_ID] [--run RUN_ID] [--task TASK_REF]
+   taskledger pipeline context STEP_ID [--scope task|todo|run] [--todo TODO_ID] [--run RUN_ID] [--format markdown|json|text] [--task TASK_REF]
    taskledger handoff show HANDOFF_ID --format text|markdown|json [--task TASK_REF]
 
 Rules:
@@ -441,6 +449,11 @@ Rules:
 * ``--scope run`` requires ``--run``.
 * ``--for implementation|validation|planning|review|full`` remain accepted as
   compatibility aliases.
+* ``handoff create --worker`` derives mode and context from the configured
+  worker step and stores ``worker_step_id`` in the handoff record.
+* ``pipeline context STEP_ID`` is equivalent to ``context --worker STEP_ID``.
+* ``spec-reviewer`` and ``code-reviewer`` worker contexts require ``--run`` or
+  explicit ``--scope task`` when they are not bound to a validation/review run.
 * ``handoff show --format markdown`` prints the stored snapshot body.
 
 Removed Pre-Release Aliases

{taskledger-0.4.0 → taskledger-0.4.1}/docs/full_task_cycle.rst

@@ -149,6 +149,25 @@ may also materialize structured plan todos:
 Mandatory todos gate implementation completion. Optional todos remain visible but
 do not block ``implement finish``.
 
+If the project has an enabled worker pipeline, plan todos may optionally target
+configured worker steps. This is an advisory overlay, not a new lifecycle stage:
+
+.. code-block:: yaml
+
+   todos:
+     - id: plan-todo-0001
+       text: "Add failing regression tests."
+       worker_step: "tester"
+       validation_hint: "pytest tests/test_parser.py -q"
+
+Use the worker overlay explicitly:
+
+.. code-block:: bash
+
+   taskledger pipeline next
+   taskledger context --worker tester
+   taskledger handoff create --worker tester --summary "Add failing tests only."
+
 All approval escape hatches require ``--reason``:
 
 - ``--allow-empty-criteria --reason "..."``

{taskledger-0.4.0 → taskledger-0.4.1}/docs/usage.rst

@@ -9,6 +9,23 @@ Installation
    python -m pip install -e .
    python -m pip install -e ".[dev]"
 
+Shell completion
+----------------
+
+After installing ``taskledger``, install completion for the current shell:
+
+.. code-block:: bash
+
+   taskledger --install-completion
+
+To print the generated completion script without installing it:
+
+.. code-block:: bash
+
+   taskledger --show-completion
+
+Restart your shell session after installation.
+
 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
@@ -139,6 +156,100 @@ enforce plan fields by itself. It cannot override lifecycle gates, plan approval
 validation requirements, lock rules, required user answers, or higher-priority
 harness instructions.
 
+Optional worker pipelines
+-------------------------
+
+Projects may optionally configure worker pipelines in ``taskledger.toml`` to
+guide fresh-context handoffs without changing the underlying task lifecycle.
+Worker pipelines are advisory overlays on the existing planning,
+implementation, and validation lifecycle. They can be three steps, four steps,
+five steps, or custom. When no worker pipeline is configured, taskledger
+behavior is unchanged.
+
+Example configuration:
+
+.. code-block:: toml
+
+   [worker_pipeline]
+   enabled = true
+   name = "api-contract-first"
+   mode = "guided"
+
+   [[worker_pipeline.steps]]
+   id = "planner"
+   lifecycle_stage = "planning"
+   base_context = "planner"
+
+   [[worker_pipeline.steps]]
+   id = "tester"
+   label = "Test Writer"
+   lifecycle_stage = "implementation"
+   base_context = "implementer"
+   actor_role = "implementer"
+   kind = "check"
+   description = "Add or update failing tests before code changes."
+   required_output = ["New or updated failing tests with a short summary."]
+   must_not = ["Do not change production code in this step."]
+   todo_tag = "tests"
+   test_command_policy = "may_fail"
+
+   [[worker_pipeline.steps]]
+   id = "coder"
+   lifecycle_stage = "implementation"
+   base_context = "implementer"
+   kind = "todo"
+   description = "Implement the approved change and make the tests pass."
+   required_output = ["Code changes plus passing targeted checks."]
+   must_not = ["Do not skip required validation evidence."]
+   todo_tag = "implementation"
+   test_command_policy = "must_pass"
+
+   [[worker_pipeline.steps]]
+   id = "domain-reviewer"
+   lifecycle_stage = "review"
+   base_context = "spec-reviewer"
+   kind = "review"
+
+Supported top-level keys are ``enabled``, ``name``, ``mode``, and ``steps``.
+Supported step keys are ``id``, ``label``, ``lifecycle_stage``,
+``base_context``, ``actor_role``, ``kind``, ``description``,
+``required_output``, ``must_not``, ``todo_tag``, and
+``test_command_policy``. ``guided`` mode remains advisory: it does not add
+new planning, implementation, or validation gates. Instead it augments
+``taskledger next-action`` with worker-step metadata plus ready-to-run worker
+context and handoff commands for the pending step.
+
+Inspect and use the configured overlay explicitly:
+
+.. code-block:: bash
+
+   taskledger pipeline show
+   taskledger pipeline list
+   taskledger pipeline next
+   taskledger next-action
+   taskledger pipeline context tester
+   taskledger context --worker tester
+   taskledger handoff create --worker tester --summary "Add failing tests only."
+   taskledger handoff create --worker domain-reviewer --scope task --summary "Review the implementation."
+
+To include worker-step todo hints in a plan template, enable a worker pipeline
+with ``mode = "template"`` or ``mode = "guided"`` and opt in per task:
+
+.. code-block:: bash
+
+   taskledger plan template --with-worker-pipeline --file ./plan.md
+
+Use ``worker_step`` only on plan todos for projects that have an enabled worker
+pipeline:
+
+.. code-block:: yaml
+
+   todos:
+     - id: plan-todo-0001
+       text: "Add failing regression tests."
+       worker_step: "tester"
+       validation_hint: "pytest -q tests/test_parser.py"
+
 Release tagging and changelog context
 -------------------------------------
 

{taskledger-0.4.0 → taskledger-0.4.1}/skills/taskledger/SKILL.md

@@ -89,6 +89,18 @@ If any `taskledger ...` command fails with a Python traceback before taskledger
   `taskledger ledger adopt --from REF TASK_REF` when branch-local task history
   should be copied into the current ledger.
 
+## Optional worker pipeline overlay
+
+- Worker pipelines are optional project-local overlays, not mandatory lifecycle stages.
+- No `[worker_pipeline]` config means no workflow change.
+- Use `taskledger pipeline show`, `taskledger pipeline list`, and `taskledger pipeline next` to inspect the configured overlay.
+- Use `taskledger context --worker STEP_ID` or `taskledger pipeline context STEP_ID` to render a worker-specific context on top of the existing base context.
+- Use `taskledger handoff create --worker STEP_ID` to derive handoff mode and context from a configured worker step.
+- In `guided` mode, inspect `taskledger next-action` for `worker_pipeline.next_step`, `context_command`, and `handoff_command` hints. These are advisory only; they do not add new lifecycle gates.
+- Reviewer worker steps (`spec-reviewer`, `code-reviewer`) may require `--scope task` when no focused run is available.
+- Use `taskledger plan template --with-worker-pipeline --file ./plan.md` only when the project has an enabled worker pipeline and the task should use worker-tagged plan todos.
+- `worker_step` on plan todos is valid only when the project has an enabled worker pipeline.
+
 ## Planning protocol
 
 1. `taskledger task create "Short task request" --slug <slug>` when creating a fresh task.
@@ -105,6 +117,7 @@ If any `taskledger ...` command fails with a Python traceback before taskledger
 10. When the user answers in chat, record the answers yourself with `taskledger question answer-many` or `taskledger question answer`.
 11. Run `taskledger question status` and review all answered questions with `taskledger question answers` before writing the plan.
 12. Before reading source files to discover plan format, run `taskledger plan template --from-answers --file ./plan.md` when answered questions exist, or `taskledger plan template --file ./plan.md` for a fresh plan skeleton.
+    - If the project has an enabled worker pipeline and this task should use worker-tagged todos, add `--with-worker-pipeline`.
 13. If answered questions exist, write the next plan with `taskledger plan upsert --from-answers --file ./plan.md`.
 14. Use `taskledger plan upsert --file ./plan.md` for plans that are not based on newly answered questions.
 15. Never edit `.taskledger/` files directly. Treat `.taskledger/` as Taskledger private durable state.

{taskledger-0.4.0 → taskledger-0.4.1}/taskledger/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
-__commit_id__ = commit_id = 'g0b2a991e6'
+__commit_id__ = commit_id = 'gde39c5f9d'