taskledger 0.3.1__tar.gz → 0.4.0__tar.gz

{taskledger-0.3.1 → taskledger-0.4.0}/.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 = 87
 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.0}/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
@@ -233,6 +234,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 +265,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.0}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## v0.4.0 - 2026-05-18
+
+### 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.3.1
+Version: 0.4.0
 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`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -321,16 +322,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 +344,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 +368,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 +378,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 +396,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 +496,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."

{taskledger-0.3.1 → taskledger-0.4.0}/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`
+- `context`, `next-action`, `can`, `search`, `grep`, `symbols`, `deps`, `actor`, `view`, `serve`, `storage`, `sync`
 
 **Repair and inspection:**
 
@@ -278,16 +278,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
@@ -298,12 +300,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/
@@ -321,7 +324,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.
 
@@ -331,10 +334,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
@@ -349,15 +352,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:
@@ -408,6 +452,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."

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

@@ -42,6 +42,21 @@ Task-resource commands accept the task as their direct positional resource:
    taskledger task unarchive task-0001 --reason "Restore task"
    taskledger task report task-0001
 
+Root reporting commands render standalone HTML:
+
+.. code-block:: bash
+
+   taskledger report html task-0040 --output task-0040.html
+   taskledger report html --active --output active-task.html
+   taskledger report site --output .taskledger-report/
+
+Serve supports optional positional task selection and refresh in seconds:
+
+.. code-block:: bash
+
+   taskledger serve --refresh-seconds 2
+   taskledger serve --task task-0040 --refresh-seconds 2
+
 Optional positional task refs are not supported for workflow commands.
 
 Plan guidance command
@@ -191,7 +206,7 @@ Ledger commands
 ---------------
 
 Branch-scoped ledgers isolate ignored local task state by the checked-in
-``ledger_ref`` stored in ``.taskledger.toml``:
+``ledger_ref`` stored in ``taskledger.toml``:
 
 .. code-block:: bash
 
@@ -204,9 +219,49 @@ Branch-scoped ledgers isolate ignored local task state by the checked-in
 
 ``ledger fork`` creates a new local namespace under
 ``.taskledger/ledgers/<ref>/`` and updates only Taskledger-owned ledger keys in
-``.taskledger.toml``. ``ledger switch`` changes the checked-in pointer to an
+``taskledger.toml``. ``ledger switch`` changes the checked-in pointer to an
 existing local ledger. ``ledger adopt`` copies a task from another local ledger
 into the current ledger and renumbers on collision.
+
+Storage and sync helper commands
+--------------------------------
+
+Taskledger also exposes local storage discovery and sync helpers:
+
+.. code-block:: bash
+
+   taskledger storage where
+   taskledger storage move --to ../taskledger-state/project-a --mode copy|move [--adopt-existing] [--force]
+   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 status
+   taskledger sync git init --repo ../taskledger-state --project-path project-a
+   taskledger sync git commit --message "Sync project-a taskledger state"
+   cd "$(taskledger sync git cd)"
+   git pull --ff-only
+   git push
+   taskledger sync git hooks install
+   taskledger sync git hooks status
+   taskledger sync git hooks uninstall
+
+Rules:
+
+* ``storage where`` is read-only and reports the resolved workspace root,
+  config path, ``taskledger_dir``, project identity, ledger ref, Git detection,
+  and active lock count.
+* ``storage move`` updates ``taskledger.toml`` atomically after the target has
+  been copied or explicitly adopted.
+* ``sync preflight`` performs only local checks. It must not perform network
+  push/pull operations.
+* ``sync status`` and ``sync commit`` operate only on the Git repository that
+  contains the resolved ``taskledger_dir``.
+* ``sync export`` and ``sync import`` are archive aliases for the root
+  ``export``/``import`` commands.
+* ``sync git`` commands operate on a private external Git repository that stores
+  full project taskledger state under ``<repo>/<project_path>``.
 ``next-action`` result contract
 -------------------------------
 
@@ -356,12 +411,12 @@ Human monitoring UI
 
 .. code-block:: bash
 
-   taskledger serve [--host 127.0.0.1] [--port 8765] [--task TASK_REF] [--refresh-ms 1000] [--open/--no-open]
+   taskledger serve [TASK_REF] [--host 127.0.0.1] [--port 8765] [--refresh-seconds 2] [--open/--no-open]
 
 Rules:
 
 * the MVP binds only to localhost;
-* it serves read-only HTML plus read-only JSON endpoints;
+* it serves read-only server-rendered HTML pages;
 * browser actions are not part of the MVP;
 * agents should continue to use ``next-action``, ``context``, ``view``, and
   ``--json`` commands as the canonical automation interface.

{taskledger-0.3.1 → taskledger-0.4.0}/docs/index.rst

@@ -18,6 +18,7 @@ Contents
    public_surface
    command_contract
    transfer
+   sync
 
 Indices and tables
 ------------------

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

@@ -12,6 +12,7 @@ Supported CLI groups
 
 - ``task``, ``plan``, ``question``, ``implement``, ``validate``, ``todo``
 - ``intro``, ``file``, ``link``, ``require``, ``release``, ``lock``, ``handoff``
+- ``storage``, ``sync``
 - ``doctor``, ``repair``, ``next-action``, ``can``, ``reindex``
 - ``init``, ``status``, ``export``, ``import``, ``snapshot``
 - ``context``, ``view``, ``serve``, ``search``, ``grep``, ``symbols``, ``deps``
@@ -54,6 +55,12 @@ todo subcommands
 - ``todo add``, ``todo list``, ``todo done``, ``todo show``, ``todo status``, ``todo next``
 - Todo source is inferred from active lock: ``implementer`` during implementation, ``planner`` during planning, ``user`` otherwise.
 
+storage and sync subcommands
+----------------------------
+
+- ``storage where``, ``storage move --to PATH --mode copy|move [--adopt-existing] [--force]``
+- ``sync preflight``, ``sync status``, ``sync commit --message "..."``
+
 Supported Python API modules
 ----------------------------
 
@@ -66,6 +73,7 @@ Supported Python API modules
 - ``taskledger.api.locks``
 - ``taskledger.api.handoff``
 - ``taskledger.api.releases``
+- ``taskledger.api.storage``
 - ``taskledger.api.search``
 
 ``taskledger.api.task_runs`` includes the public lifecycle helpers