taskledger 0.1.1__tar.gz → 0.2.0__tar.gz

taskledger-0.2.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,31 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Python tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "ruff==0.15.12"
+
+      - name: Install Node tools
+        run: |
+          npm install -g prettier@2.7.1 @prettier/plugin-xml@2.2.0 eslint
+
+      - uses: pre-commit/action@v3.0.1

{taskledger-0.1.1 → taskledger-0.2.0}/.pre-commit-config.yaml

@@ -17,14 +17,19 @@ exclude: |
   (LICENSE.*|COPYING.*)|
 default_language_version:
   python: python3
-  node: "16.17.0"
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.12
+  - repo: local
     hooks:
-      - id: ruff
-        args: [--fix, --exit-non-zero-on-fix, --config=.ruff.toml]
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check --fix --exit-non-zero-on-fix --config=.ruff.toml --force-exclude
+        language: system
+        types_or: [python, pyi]
       - id: ruff-format
+        name: ruff format
+        entry: ruff format --force-exclude
+        language: system
+        types_or: [python, pyi]
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.21.2
     hooks:

{taskledger-0.1.1 → taskledger-0.2.0}/.taskledger.toml

@@ -1,8 +1,11 @@
 # Project-local taskledger configuration.
 # This file lives in the source project root.
-config_version = 1
+config_version = 2
 taskledger_dir = '.taskledger'
 
+# Stable project identity. Commit this with your source tree.
+project_uuid = "081c7c05-2d10-42b7-9b37-3d814c2f400a"
+
 # Project-local taskledger overrides.
 # The source-budget settings below are the active composition defaults.
 # Lower them for stricter prompts, or raise them when a run needs more context.
@@ -18,3 +21,9 @@ taskledger_dir = '.taskledger'
 # workflow_schema = "opsx-lite"
 # project_context = "Project-specific workflow guidance."
 # default_artifact_order = ["analysis", "plan", "implementation", "validation"]
+
+# Taskledger branch-scoped state. This block is intentionally safe to commit.
+ledger_ref = "main"
+ledger_parent_ref = ""
+ledger_next_task_number = 60
+ledger_branch_guard = "off"

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

@@ -54,10 +54,12 @@ from taskledger.errors import (
 - `project_export`
 - `project_import`
 - `project_snapshot`
+- `project_tree`
 
 ### `taskledger.api.tasks`
 
 - `create_task`
+- `record_completed_task`
 - `show_active_task`
 - `activate_task`
 - `deactivate_task`
@@ -82,10 +84,14 @@ from taskledger.errors import (
 - `todo_status`
 - `next_todo`
 - `task_dossier`
+- `render_task_report`
+- `TaskReportOptions`
 - `next_action`
 - `can_perform`
 - `reindex`
 - `repair_task_record`
+- `repair_orphaned_planning_run`
+- `repair_planning_command_changes`
 
 ### `taskledger.api.plans`
 

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

@@ -1,5 +1,49 @@
 # Changelog
 
+## v0.1.2 - 2026-04-30
+
+### Fixed
+
+- Fixed orphaned planning run lifecycle recovery so plan regeneration safely finishes the latest orphaned planning run with audit evidence, plan approval rejects tasks with any running run, and `implement start` reports structured conflict details including run id, run type, lock match status, and suggested diagnostic command.
+- Aligned `next-action` and `can implement` so they never recommend `implement start` when a running run or run/lock mismatch blocks implementation.
+- Expanded `taskledger doctor` and `taskledger doctor locks` to report run/lock mismatches with specific repair guidance.
+
+### Added
+
+- Added `taskledger repair run` for guarded, reasoned, audited repair of orphaned running planning runs.
+
+### Documentation
+
+- Updated taskledger skill, command contract, and API docs with running-run conflict protocol and `repair run` usage.
+
+### Quality
+
+- Expanded regression coverage for plan regeneration recovery, approval guards, next-action alignment, doctor diagnostics, and repair lifecycle. Targeted pytest, ruff, format, and mypy passed.
+
+## v0.1.1 - 2026-04-29
+
+### Added
+
+- Added `task follow-up` to create linked post-completion child tasks, preserve closure metadata, and show parent and follow-up relationships in task and handoff views.
+- Added durable release records and a new `taskledger release` command group with `tag`, `list`, `show`, and `changelog`, including export/import support and public API coverage.
+- Added planning helpers with `question add-many`, `plan template`, richer regeneration hints in `next-action`, and recovery commands for orphaned implementation work with `implement resume`, `task uncancel`, and `can implement-resume`.
+
+### Changed
+
+- Hardened CLI startup so optional command-group import failures no longer block core commands, and launcher failures return structured diagnostics.
+
+### Fixed
+
+- Fixed recovery guidance for uncancelled tasks with orphaned implementation runs so `next-action` and `can implement` recommend `implement resume` instead of a fresh start.
+
+### Documentation
+
+- Documented release tagging, changelog generation, planning helpers, follow-up task workflow, and recovery semantics across README, RST docs, API docs, and the taskledger skill.
+
+### Quality
+
+- Expanded regression coverage for follow-up tasks, release workflow, CLI import resilience, planning helpers, and implementation recovery. Repo-wide pytest, ruff, and mypy passed.
+
 ## v0.1.0 - 2026-04-29
 
 ### Added

taskledger-0.2.0/Makefile

@@ -0,0 +1,9 @@
+.PHONY: release-check
+
+release-check:
+	python3 -m compileall -q taskledger tests
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest -q
+	python3 -m ruff check --config=.ruff.toml .
+	python3 -m mypy taskledger
+	python3 -m build
+	python3 -m twine check dist/*

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskledger
-Version: 0.1.1
+Version: 0.2.0
 Summary: Durable project-state storage and CLI for coding workflows
 Author: Taskledger Contributors
 Maintainer: Holger Nahrstaedt
@@ -33,6 +33,7 @@ Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
@@ -40,6 +41,11 @@ Provides-Extra: rich
 Requires-Dist: rich; extra == "rich"
 Dynamic: license-file
 
+[![PyPI - Version](https://img.shields.io/pypi/v/taskledger)](https://pypi.org/project/taskledger/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/taskledger)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/taskledger)
+[![codecov](https://codecov.io/gh/holgern/taskledger/graph/badge.svg?token=6usFHwM5Ul)](https://codecov.io/gh/holgern/taskledger)
+
 # taskledger
 
 `taskledger` is a task-first durable state layer for staged coding work. It keeps
@@ -131,14 +137,15 @@ taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -
 taskledger validate finish --result passed --summary "Validated the rewrite."
 ```
 
-If validation finds an implementation bug, keep the accepted plan and restart
-implementation explicitly:
+For manually completed work (e.g., manual testing, operations tasks, or work
+completed outside the task-first lifecycle), use `task record` to create a
+done task directly without acquiring lifecycle locks. **Note**: `task record`
+does not replace the normal task lifecycle; it is for recording work already
+completed, not as a shortcut for active task management.
 
 ```bash
-taskledger validate finish --result failed --summary "Parser edge case still fails."
-taskledger next-action
-taskledger context --for implementation --format markdown
-taskledger implement restart --summary "Fix failed validation findings."
+taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod" --change "infra/deploy.sh:run:Updated prod config" --evidence "Monitoring shows no errors"
+taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"
 ```
 
 If validation finds an implementation bug, keep the accepted plan and restart
@@ -265,21 +272,47 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root:
+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>/`:
 
 ```text
-taskledger.toml
+.taskledger.toml
 .taskledger/
-  intros/
-  releases/
-  tasks/
-  events/
-  indexes/   # optional derived caches and registries
+  storage.yaml
+  ledgers/
+    main/
+      intros/
+      releases/
+      tasks/
+      events/
+      indexes/   # optional derived caches and registries
 ```
 
-Markdown files are canonical. Task, plan, and run listings scan those records
-directly. JSON files under `.taskledger/indexes/` are optional derived caches or
-registries and are not required for task correctness.
+Markdown files are canonical. Task, plan, and run listings scan only the current
+ledger by default. JSON files under the current ledger's `indexes/` directory are
+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
+contains the current `ledger_ref`, optional parent ref, and the next logical task
+number for the checked-out source branch.
+
+When starting long-lived branch-local work, fork the ledger pointer after creating
+the Git branch:
+
+```bash
+git checkout -b feature-a
+taskledger ledger fork feature-a
+git add .taskledger.toml
+```
+
+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
+should be copied into the current ledger.
 
 You can also point `taskledger.toml` at an external storage root:
 
@@ -347,6 +380,7 @@ taskledger context --for planning --format markdown
 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 handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."
@@ -407,24 +441,50 @@ for task-first handoff guidance.
 ## Export, import, and snapshots
 
 ```bash
-taskledger --json export
-taskledger import ./taskledger-export.json --replace
+taskledger export ./taskledger-transfer.tar.gz
+taskledger import ./taskledger-transfer.tar.gz --replace
 taskledger snapshot ./artifacts
 ```
 
+Cross-machine imports preserve durable task/run data, but imported runtime locks
+are quarantined by default. After importing an in-progress implementation,
+run:
+
+```bash
+taskledger next-action
+taskledger implement resume --reason "Continue imported implementation."
+```
+
+Use `--lock-policy keep` only for diagnostic full-fidelity lock restoration.
+
 ## Skill packaging
 
+Agent workflows work best when the `taskledger` skill is installed in the
+coding harness. The CLI has a task-first lifecycle with explicit planning,
+approval, implementation, validation, locks, and handoff gates; without the
+skill, an agent may not know the intended command sequence or gate semantics.
+
 The canonical skill file lives at:
 
 ```text
 skills/taskledger/SKILL.md
 ```
 
-No additional `skills/taskledger/examples/` directory is required.
+Keep this skill outside the Python package. No additional
+`skills/taskledger/examples/` directory is required.
 
 ## Development
 
 ```bash
-pytest -q
+python -m pytest -m "not slow"
+python -m pytest -m "not slow" -n auto
+python -m pytest -n auto
+python -m pytest
 ruff check .
 ```
+
+Full release-readiness sweep:
+
+```bash
+make release-check
+```

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

@@ -1,3 +1,8 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/taskledger)](https://pypi.org/project/taskledger/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/taskledger)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/taskledger)
+[![codecov](https://codecov.io/gh/holgern/taskledger/graph/badge.svg?token=6usFHwM5Ul)](https://codecov.io/gh/holgern/taskledger)
+
 # taskledger
 
 `taskledger` is a task-first durable state layer for staged coding work. It keeps
@@ -89,14 +94,15 @@ taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -
 taskledger validate finish --result passed --summary "Validated the rewrite."
 ```
 
-If validation finds an implementation bug, keep the accepted plan and restart
-implementation explicitly:
+For manually completed work (e.g., manual testing, operations tasks, or work
+completed outside the task-first lifecycle), use `task record` to create a
+done task directly without acquiring lifecycle locks. **Note**: `task record`
+does not replace the normal task lifecycle; it is for recording work already
+completed, not as a shortcut for active task management.
 
 ```bash
-taskledger validate finish --result failed --summary "Parser edge case still fails."
-taskledger next-action
-taskledger context --for implementation --format markdown
-taskledger implement restart --summary "Fix failed validation findings."
+taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod" --change "infra/deploy.sh:run:Updated prod config" --evidence "Monitoring shows no errors"
+taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"
 ```
 
 If validation finds an implementation bug, keep the accepted plan and restart
@@ -223,21 +229,47 @@ fresh-context transfer.
 ## Storage layout
 
 `taskledger` keeps project-local configuration in the workspace root and durable
-records under the configured storage root:
+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>/`:
 
 ```text
-taskledger.toml
+.taskledger.toml
 .taskledger/
-  intros/
-  releases/
-  tasks/
-  events/
-  indexes/   # optional derived caches and registries
+  storage.yaml
+  ledgers/
+    main/
+      intros/
+      releases/
+      tasks/
+      events/
+      indexes/   # optional derived caches and registries
 ```
 
-Markdown files are canonical. Task, plan, and run listings scan those records
-directly. JSON files under `.taskledger/indexes/` are optional derived caches or
-registries and are not required for task correctness.
+Markdown files are canonical. Task, plan, and run listings scan only the current
+ledger by default. JSON files under the current ledger's `indexes/` directory are
+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
+contains the current `ledger_ref`, optional parent ref, and the next logical task
+number for the checked-out source branch.
+
+When starting long-lived branch-local work, fork the ledger pointer after creating
+the Git branch:
+
+```bash
+git checkout -b feature-a
+taskledger ledger fork feature-a
+git add .taskledger.toml
+```
+
+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
+should be copied into the current ledger.
 
 You can also point `taskledger.toml` at an external storage root:
 
@@ -305,6 +337,7 @@ taskledger context --for planning --format markdown
 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 handoff create --mode implementation --intended-actor agent --intended-harness codex
 taskledger handoff claim handoff-0001
 taskledger handoff close handoff-0001 --reason "Implementation started."
@@ -365,24 +398,50 @@ for task-first handoff guidance.
 ## Export, import, and snapshots
 
 ```bash
-taskledger --json export
-taskledger import ./taskledger-export.json --replace
+taskledger export ./taskledger-transfer.tar.gz
+taskledger import ./taskledger-transfer.tar.gz --replace
 taskledger snapshot ./artifacts
 ```
 
+Cross-machine imports preserve durable task/run data, but imported runtime locks
+are quarantined by default. After importing an in-progress implementation,
+run:
+
+```bash
+taskledger next-action
+taskledger implement resume --reason "Continue imported implementation."
+```
+
+Use `--lock-policy keep` only for diagnostic full-fidelity lock restoration.
+
 ## Skill packaging
 
+Agent workflows work best when the `taskledger` skill is installed in the
+coding harness. The CLI has a task-first lifecycle with explicit planning,
+approval, implementation, validation, locks, and handoff gates; without the
+skill, an agent may not know the intended command sequence or gate semantics.
+
 The canonical skill file lives at:
 
 ```text
 skills/taskledger/SKILL.md
 ```
 
-No additional `skills/taskledger/examples/` directory is required.
+Keep this skill outside the Python package. No additional
+`skills/taskledger/examples/` directory is required.
 
 ## Development
 
 ```bash
-pytest -q
+python -m pytest -m "not slow"
+python -m pytest -m "not slow" -n auto
+python -m pytest -n auto
+python -m pytest
 ruff check .
 ```
+
+Full release-readiness sweep:
+
+```bash
+make release-check
+```

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

@@ -33,11 +33,13 @@ Project API
 - ``project_export``
 - ``project_import``
 - ``project_snapshot``
+- ``project_tree``
 
 Task API
 --------
 
 - ``create_task``
+- ``record_completed_task``
 - ``show_active_task``
 - ``activate_task``
 - ``deactivate_task``
@@ -62,10 +64,14 @@ Task API
 - ``todo_status``
 - ``next_todo``
 - ``task_dossier``
+- ``render_task_report``
+- ``TaskReportOptions``
 - ``next_action``
 - ``can_perform``
 - ``reindex``
 - ``repair_task_record``
+- ``repair_orphaned_planning_run``
+- ``repair_planning_command_changes``
 
 Plan API
 --------

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

@@ -34,6 +34,19 @@ when explicitly targeting another task.
 
 Optional positional task refs are not supported.
 
+Archive import lock policy
+--------------------------
+
+Archive imports support explicit lock handling:
+
+.. code-block:: bash
+
+   taskledger import ./taskledger-transfer.tar.gz --replace [--lock-policy drop|quarantine|keep]
+
+The default is ``quarantine`` so imported source-machine runtime locks are not
+restored as active ``lock.yaml`` files. ``keep`` is diagnostic-only behavior
+for full-fidelity lock restoration.
+
 Positional Resource Refs
 ------------------------
 
@@ -41,6 +54,8 @@ Positional refs are reserved for the direct resource being changed or shown:
 
 .. code-block:: bash
 
+   taskledger task create TITLE [options]
+   taskledger task record TITLE [options]
    taskledger task activate TASK_REF
    taskledger task follow-up PARENT_REF TITLE [options]
    taskledger todo done TODO_ID --task TASK_REF --evidence "pytest -q"
@@ -61,11 +76,32 @@ Release boundaries are durable project records, not task lifecycle states:
    taskledger release show 0.4.1
    taskledger release changelog 0.4.2 --since 0.4.1 --until-task task-0035 --output /tmp/taskledger-0.4.2-changelog-source.md
 
-``release tag`` writes a durable release record under ``.taskledger/releases/``.
+``release tag`` writes a durable release record under the current ledger's
+``releases/`` directory.
 ``release changelog`` is read-oriented: it renders Markdown or JSON changelog
 context from done tasks and may write an external output file, but it does not
 mutate ledger state.
 
+Ledger commands
+---------------
+
+Branch-scoped ledgers isolate ignored local task state by the checked-in
+``ledger_ref`` stored in ``.taskledger.toml``:
+
+.. code-block:: bash
+
+   taskledger ledger status
+   taskledger ledger list
+   taskledger ledger fork feature-a
+   taskledger ledger switch main
+   taskledger ledger adopt --from feature-a task-0030
+   taskledger ledger doctor
+
+``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
+existing local ledger. ``ledger adopt`` copies a task from another local ledger
+into the current ledger and renumbers on collision.
 ``next-action`` result contract
 -------------------------------
 
@@ -114,9 +150,55 @@ status but ``active_stage`` is missing, ``next-action`` must not report
 ``The task is cancelled.`` For an orphaned implementation with a still-running
 latest implementation run and no active lock, it should direct agents to
 ``taskledger implement resume --task TASK_REF --reason "..."``.
+For an approved task with a non-implementation run still marked running,
+``next-action`` must not direct agents to ``taskledger implement start``.
+It should report a repair-oriented action and point to ``taskledger doctor``.
 Truly cancelled tasks recover through ``taskledger task uncancel --reason "..."``
+
+Compact mutation output
+........................
+
+Mutation commands emit compact acknowledgements instead of full task or run records.
+This reduces LLM context consumption during implementation loops.
+
+The following commands produce compact output:
+
+- ``todo add``: emits ``todo_added`` result with new todo, progress, and next command.
+- ``todo done`` / ``todo undone``: emits ``todo_update`` result with todo id, status, progress, and next command.
+- ``implement finish``: emits ``task_lifecycle`` result with task id, run id, status, and next command.
+
+Human mode shows a one-line summary:
+
+.. code-block:: text
+
+   added todo-0001 on task-0001  (0/3 done)
+   done todo-0001 on task-0001  (1/3 done)
+   finished implementation run-0001  task task-0001 -> implemented
+
+JSON mode wraps the compact result in the standard success envelope with ``result_type``.
+
+For full task, run, or todo details after a mutation, use:
+
+- ``taskledger task show`` or ``taskledger status`` for task-level detail.
+- ``taskledger todo show TODO_ID`` for individual todo detail.
+- ``taskledger next-action`` for the next concrete step.
+- ``taskledger todo next`` for the next open todo.
 to a durable non-active stage rather than directly re-entering an active stage.
 
+Run and lock repair
+-------------------
+
+``taskledger doctor`` and ``taskledger doctor locks`` report running runs without
+matching active locks. Orphaned running planning runs can be finished only
+through an explicit repair command with a reason:
+
+.. code-block:: bash
+
+   taskledger repair run --task TASK_REF --run RUN_ID --reason "Planning was already completed."
+
+The repair command refuses to finish non-planning runs, non-running runs, or
+runs that still have a matching active lock.
+
 Post-completion follow-up deltas
 --------------------------------
 
@@ -244,6 +326,11 @@ Taskledger uses:
 * per-record ``object_type``
 * per-file ``file_version`` for durable Markdown/YAML/JSON record files
 
+Storage layout version history:
+
+* Layout 2: Introduced branch-scoped ledgers under ``taskledger_dir/ledgers/<ledger_ref>/``
+* Layout 3: Consolidates layout-2 root-level task state into branch-scoped ledgers; migrates legacy root ``tasks/``, ``events/``, ``intros/``, ``releases/``, and ``active-task.yaml`` into the active ledger namespace
+
 Taskledger does not silently rewrite storage during read-only commands.
 
 If the installed taskledger version can read but not write an older workspace,
@@ -257,7 +344,14 @@ To migrate:
    taskledger migrate plan
    taskledger migrate apply --backup
 
-Indexes under ``taskledger_dir/indexes/`` are optional derived caches or
+After migration to layout 3, verify health with:
+
+.. code-block:: bash
+
+   taskledger doctor
+   taskledger ledger doctor
+
+Indexes under ``taskledger_dir/ledgers/<ledger_ref>/indexes/`` are optional derived caches or
 registries. Task, plan, and run commands must continue to work from canonical
 Markdown/YAML records even when task/run/plan JSON cache files are absent. The
 remaining derived caches may be plain JSON arrays with no version metadata and