taskledger 0.3.1__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.3.1 → taskledger-0.4.1}/.taskledger.toml

@@ -1,7 +1,7 @@
 # Project-local taskledger configuration.
 # This file lives in the source project root.
 config_version = 2
-taskledger_dir = '.taskledger'
+taskledger_dir = '../taskledger-state/taskledger'
 
 # Stable project identity. Commit this with your source tree.
 project_uuid = "081c7c05-2d10-42b7-9b37-3d814c2f400a"
@@ -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 = 84
+ledger_next_task_number = 90
 ledger_branch_guard = "off"
 
 [prompt_profiles.planning]
@@ -27,4 +27,4 @@ required_question_topics = []
 extra_guidance = ""
 
 [agent_logging]
-enabled = true
+enabled = false

{taskledger-0.3.1 → 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.3.1 → taskledger-0.4.1}/API.md

@@ -12,6 +12,7 @@ This repository exposes a task-first public API. The supported modules are:
 - `taskledger.api.locks`
 - `taskledger.api.handoff`
 - `taskledger.api.releases`
+- `taskledger.api.storage`
 - `taskledger.api.search`
 
 ## Import boundary
@@ -197,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,
@@ -207,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,
@@ -224,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`
 
@@ -233,6 +239,14 @@ record body and return compact metadata, including `context_hash` and
 - `show_release`
 - `tag_release`
 
+### `taskledger.api.storage`
+
+- `storage_where`
+- `storage_move`
+- `sync_preflight`
+- `sync_status`
+- `sync_commit`
+
 ### `taskledger.api.search`
 
 - `search_workspace`
@@ -256,6 +270,8 @@ The public task-first CLI surface is organized around these command groups:
 - `require`
 - `release`
 - `lock`
+- `storage`
+- `sync`
 - `context`
 - `handoff`
 - `repair`

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

@@ -1,5 +1,74 @@
 # Changelog
 
+## 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
+
+- Added storage sync documentation (`docs/sync.rst`) explaining how to keep taskledger state outside the source repo, sync across PCs with a private Git repo, bootstrap a second machine, follow a daily sync protocol, and avoid active multi-writer conflicts.
+- Added `taskledger storage where` command reporting resolved project and storage location details in human and JSON output, including whether storage lives inside the workspace, is a Git repo, or has active locks.
+- Added `taskledger storage move` for safely migrating storage to a new `taskledger_dir` with atomic config updates, unsafe-target refusal, and follow-up command hints.
+- Added `taskledger sync preflight` read-only check combining doctor health, active-lock warnings, tracked in-repo state warnings, and local Git status.
+- Added `taskledger sync status` and `taskledger sync commit` local Git helper commands for committing taskledger state without network operations.
+- Added `taskledger sync export` and `taskledger sync import` as aliases for the existing archive transfer commands.
+- Added `taskledger sync git` command group for live external-state synchronization: `init`, `status`, `commit`, `cd`, `import-local`, `export-local`, `pull`, `push`, `sync`, and `hooks` subcommands with conservative lock/dirty checks.
+- Added project-scoped `sync git status` that separates current-project changes from outside-project changes in JSON payloads, safe with dirty sibling directories.
+- Added `sync git cd` helper returning the configured sync repo path for shell use.
+- Added `sync git commit` for committing only the configured project path while ignoring dirty sibling paths.
+- Added `[sync.git]` project config section with strict validation and documented defaults.
+- Added `taskledger/services/storage_locations.py` for storage reporting, migration, and sync helper services.
+- Added `taskledger/services/git_sync.py` for git sync orchestration.
+- Added `taskledger/cli_sync.py` as a dedicated sync CLI group.
+- Added `taskledger/api/sync.py` with public sync API wrappers.
+
+### Changed
+
+- Demoted whole-repo `sync git pull`, `push`, `sync`, and unsafe hook installation from recommended workflow to advanced/deprecated status in help, docs, and skill guidance.
+- Reframed docs, README, and skill around the project-scoped local helper workflow: `sync git status`, `sync git commit`, then manual Git via `sync git cd`.
+- Fixed stale config filename references so docs no longer claim init writes `.taskledger.toml` when `taskledger.toml` is canonical.
+- Updated external storage examples to use the current `ledgers/<ledger_ref>/...` layout.
+
+### Documentation
+
+- Added `docs/sync.rst` with cross-PC sync workflow, daily protocol, and multi-writer conflict avoidance guidance.
+- Updated README, `docs/usage.rst`, `docs/transfer.rst`, `docs/command_contract.rst`, `docs/public_surface.rst`, `API.md`, and `skills/taskledger/SKILL.md` for the new storage and sync command surface.
+
+### Quality
+
+- Added `tests/test_storage_sync.py` and `tests/test_sync_git.py` covering storage migration, sync commands, git sync workflows, shared dirty state, project-scoped commits, and JSON result kinds.
+- Expanded command inventory, CLI contract, and docs/skill tests for the new command surface.
+- Full suite: 897 tests passing, ruff and mypy clean.
+
 ## v0.3.1 - 2026-05-12
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.3.1
+Version: 0.4.1
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -28,6 +28,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer
 Requires-Dist: PyYAML
+Requires-Dist: Jinja2>=3.1
 Requires-Dist: tomli; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
@@ -72,7 +73,7 @@ The supported command surface is organized as:
 
 **Operations:**
 
-- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`
+- `context`, `pipeline`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -129,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
@@ -136,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:
@@ -321,16 +405,18 @@ Rules for agents:
 
 ## Human monitoring UI
 
-`taskledger serve` starts a read-only local dashboard for humans monitoring task
-state. It now emphasizes the active task, next action, progress, blockers, and
-compact task browsing while staying local-only, read-only, and dependency-free.
-The MVP still binds to localhost only, refreshes with read-only JSON polling,
-and exposes no browser mutation endpoints.
+`taskledger serve` starts a read-only local server-rendered HTML dashboard for
+human monitoring. It emphasizes the active task, next action, progress, and
+task browsing while staying local-only and read-only.
 
 ```bash
-taskledger serve
+taskledger report html task-0040 --output task-0040.html
+taskledger report html --active --output active-task.html
+taskledger report site --output .taskledger-report/
+
+taskledger serve --refresh-seconds 2
 taskledger serve --open
-taskledger serve --task rewrite-v2 --refresh-ms 2000
+taskledger serve --task task-0040 --refresh-seconds 2
 ```
 
 Agents should keep using `taskledger next-action`, `taskledger todo next`, and
@@ -341,12 +427,13 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root. The checked-in `.taskledger.toml`
-stores only a branch-scoped ledger pointer and next task number. Operational task
-state remains ignored under `.taskledger/ledgers/<ledger_ref>/`:
+records under the configured storage root. The checked-in `taskledger.toml`
+stores project identity plus the current branch-scoped ledger pointer and next
+task number. Operational task state remains ignored under
+`.taskledger/ledgers/<ledger_ref>/`:
 
 ```text
-.taskledger.toml
+taskledger.toml
 .taskledger/
   storage.yaml
   ledgers/
@@ -364,7 +451,7 @@ optional derived caches or registries and are not required for task correctness.
 
 ### Branch-scoped ledgers
 
-`.taskledger/` stays ignored and local. `.taskledger.toml` is safe to commit and
+`.taskledger/` stays ignored and local. `taskledger.toml` is safe to commit and
 contains the current `ledger_ref`, optional parent ref, and the next logical task
 number for the checked-out source branch.
 
@@ -374,10 +461,10 @@ the Git branch:
 ```bash
 git checkout -b feature-a
 taskledger ledger fork feature-a
-git add .taskledger.toml
+git add taskledger.toml
 ```
 
-Returning to a branch whose `.taskledger.toml` points back to `main` hides the
+Returning to a branch whose `taskledger.toml` points back to `main` hides the
 feature branch's active task and task list. Two ledgers may both contain a logical
 `task-0030`; this is expected because task IDs are scoped by `ledger_ref`. Use
 `taskledger ledger adopt --from REF TASK_REF` when branch-local task history
@@ -392,15 +479,56 @@ taskledger init --taskledger-dir /mnt/cloud/taskledger/project-a
 ```text
 /home/me/src/project-a/taskledger.toml
 /mnt/cloud/taskledger/project-a/storage.yaml
-/mnt/cloud/taskledger/project-a/releases/
-/mnt/cloud/taskledger/project-a/tasks/
-/mnt/cloud/taskledger/project-a/events/
-/mnt/cloud/taskledger/project-a/indexes/
+/mnt/cloud/taskledger/project-a/ledgers/main/releases/
+/mnt/cloud/taskledger/project-a/ledgers/main/tasks/
+/mnt/cloud/taskledger/project-a/ledgers/main/events/
+/mnt/cloud/taskledger/project-a/ledgers/main/indexes/
 ```
 
 Use one `taskledger_dir` per source project. Do not share one storage directory
 across unrelated repositories.
 
+### Sync across PCs without committing `.taskledger/`
+
+Use a sibling private Git repository for the external storage root instead of
+committing `.taskledger/` into the source repository:
+
+```toml
+# /home/me/src/project-a/taskledger.toml
+taskledger_dir = "../taskledger-state/project-a"
+```
+
+```text
+/home/me/src/project-a/                  # source repo
+/home/me/src/taskledger-state/           # private state repo
+/home/me/src/taskledger-state/project-a/ # taskledger_dir
+```
+
+Keep one active writer at a time. Before starting on a PC, pull the private
+state repo, then run `taskledger doctor` and `taskledger next-action`. After
+stopping at a clean lifecycle boundary, commit and push the state repo. If work
+must move mid-run, prefer `taskledger export TASK_REF` / `taskledger import ARCHIVE` because imported runtime locks are quarantined by default.
+
+Helpful local commands:
+
+```bash
+taskledger storage where
+taskledger sync preflight
+taskledger sync status
+taskledger sync commit --message "Sync project-a taskledger state"
+taskledger sync export --output ./taskledger-transfer.tar.gz
+taskledger sync import ./taskledger-transfer.tar.gz --dry-run
+taskledger sync git init --repo ../taskledger-state --project-path project-a
+taskledger sync git status
+taskledger sync git commit --message "Sync project-a taskledger state"
+cd "$(taskledger sync git cd)"
+git pull --ff-only
+git push
+```
+
+See `docs/sync.rst` for the full second-PC bootstrap, daily sync protocol, and
+Syncthing/rclone caveats.
+
 ## JSON output
 
 Use `--json` for machine-readable payloads:
@@ -451,6 +579,7 @@ taskledger context --for implementation --format markdown
 taskledger context --for validation --format json
 taskledger task dossier --format markdown
 taskledger task report --task task-0030 -o task30.md
+taskledger report html task-0030 --output task30.html
 taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."