worktree-controller 1.30.6__tar.gz → 1.31.0__tar.gz

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.30.6
+Version: 1.31.0
 Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -23,7 +23,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 process, and records handoff, integration, recovery and release evidence. Git remains the source
 of truth for files, branches, commits and registered worktrees.
 
-**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.31.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -32,7 +32,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.30.6
+python -m pip install worktree-controller==1.31.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -41,7 +41,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
 On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
 distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
-Software version 1.30.6 retains CLI contract **60** and storage layout **5**.
+Software version 1.31.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -50,7 +50,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.30.6
+git checkout v1.31.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -69,6 +69,13 @@ To actually change a file, publish to a local bare remote, integrate and recover
 follow [your first change](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/first-change.md).
 That complete example additionally uses public Git Finalizer and Snapshot Runner installations.
 
+## Everyday tasks
+
+Use `worktree-controller task list` to see live checkout tasks and `task show --task-key <task>`
+for the recorded owner and next formal step. The [everyday task guide](docs/daily-workflow.md)
+covers simpler start, original-task checkpoint/resume, guarded no-change release and exact
+Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease and policy checks.
+
 ## Use WC in a real project
 
 A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/README.md

@@ -6,7 +6,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 process, and records handoff, integration, recovery and release evidence. Git remains the source
 of truth for files, branches, commits and registered worktrees.
 
-**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.31.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -15,7 +15,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.30.6
+python -m pip install worktree-controller==1.31.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -24,7 +24,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
 On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
 distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
-Software version 1.30.6 retains CLI contract **60** and storage layout **5**.
+Software version 1.31.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -33,7 +33,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.30.6
+git checkout v1.31.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -52,6 +52,13 @@ To actually change a file, publish to a local bare remote, integrate and recover
 follow [your first change](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/first-change.md).
 That complete example additionally uses public Git Finalizer and Snapshot Runner installations.
 
+## Everyday tasks
+
+Use `worktree-controller task list` to see live checkout tasks and `task show --task-key <task>`
+for the recorded owner and next formal step. The [everyday task guide](docs/daily-workflow.md)
+covers simpler start, original-task checkpoint/resume, guarded no-change release and exact
+Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease and policy checks.
+
 ## Use WC in a real project
 
 A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.

worktree_controller-1.31.0/docs/daily-workflow.md

@@ -0,0 +1,127 @@
+# Everyday task operations
+
+Use `worktree-controller task` for named feature/audit checkout tasks. It resolves the recorded
+path, owner and record version, then calls the existing guarded lifecycle operation. The existing
+low-level commands remain available. No separate task database or lifecycle is introduced.
+
+These entrypoints require **WC 1.31.0, CLI 61, task_workflow_version 1**. Storage layout remains 5.
+Check the installed `--version`, `capabilities --json` and `task --help` before using them. A newer
+source checkout does not update a separately installed Controller. Governed installations still
+need their normal compatibility, deployment and activation checks.
+
+Start in an already governed repository: inspect `status`, `doctor` and its selected policy;
+adopt existing checkouts explicitly. Examples below use `/project` as that repository's canonical
+checkout. These commands operate locally and do not grant permission to publish or deploy.
+
+## See the current work
+
+```bash
+worktree-controller task list --repo /project
+worktree-controller task show --repo /project --task-key report-fix
+```
+
+`list` shows live linked checkouts, their recorded owner, lifecycle, writer lease observation,
+cleanliness and any checkpoint dependency. It is not a list of all business Tasks or queued
+integrations. `show` explains the named checkout and its next formal step. After release, the
+task key queries the original lifecycle history instead of inventing a new task.
+
+Task keys can be ambiguous in imported or historical work. Mutations never pick a checkout by
+owner, age or directory order. If multiple live checkouts share a key, select its exact `--path`
+instead. Historical results retain their proof status and pagination; absence is not completion.
+
+## 1. Start and finish a task with no changes
+
+```bash
+worktree-controller task start --repo /project --task-key report-fix \
+  --owner alice --scope src/reports
+
+# An inspection that made no file changes and produced no task commit:
+worktree-controller task finish --repo /project --task-key report-fix \
+  --owner alice --outcome no-change
+```
+
+Start requires an explicit task key, owner and file scope. It defaults to feature role,
+`authority_key=task_key`, module `task`, branch `task/<task-key>`, and the repository policy's
+publication remote/branch as base. Override `--authority-key`, `--module`, `--branch`, `--base-ref`
+or `--path` when your existing task requires different values. It does not fetch or substitute
+another base when the policy base is unavailable locally. An existing live task is not duplicated.
+
+Admission creates a checkout, **not write entitlement**. Before editing, bind the real writer
+with the existing writer-session/lease flow and require `write-guard` to allow the operation.
+Use the admitted path and declared task/authority. End only that writer's exact lease before
+finishing. See [start or resume development](operations.md#start-or-resume-development).
+
+The no-change finish first records the existing `complete-no-change` result, then attempts normal
+guarded release. It retains the branch. A task commit or dirty worktree refuses no-change completion.
+Unknown ignored files or registered resources can block the separate release step. In that case,
+exit status is **2**, `TASK_RELEASE_BLOCKED` retains the completed prefix and provides a release
+dry-run command. Preserve/classify those files through their existing owner flow. Repeating this
+finish while `NO_CHANGE_COMPLETED` retries release without creating another completion receipt.
+After successful release, use `task show`; another finish refuses the absent live allocation.
+
+## 2. Pause and continue the original task
+
+First save a checkpoint in your existing Task system. Obtain its content-addressed ID and the
+exact HEAD it records. WC records that owner's attestation; it does not create or verify the
+checkpoint payload and does not copy uncommitted files into it. Then, after the writer ends:
+
+```bash
+worktree-controller task finish --repo /project --task-key report-fix --owner alice \
+  --outcome checkpoint --checkpoint-id "$checkpoint_id" --checkpoint-head "$checkpoint_head" \
+  --waiting-on 'Awaiting source data'
+
+worktree-controller task resume --repo /project --task-key report-fix --owner alice
+```
+
+The checkpoint ID must use the existing `sha256:<64 hex>` or `art_<64 hex>` format. Its HEAD
+must still match the checkout. Parking preserves the same checkout, branch, uncommitted files
+and unknown files; work remains unfinished. Resume uses the same allocation and owner, without
+creating a replacement task or writer lease. Obtain fresh write entitlement before editing again.
+This entry does not release an unfinished checkout; that remains a separate reviewed owner flow.
+
+## 3. Hand off a completed change
+
+Run appropriate tests/review and publish the task branch through your authorized Git Finalizer
+flow. Use the actual returned record and the exact commit it binds; do not invent evidence.
+After ending the exact writer:
+
+```bash
+worktree-controller task finish --repo /project --task-key report-fix --owner alice \
+  --outcome handoff --finalizer-record-id "$finalizer_record_id" --commit "$commit"
+```
+
+`TASK_HANDED_OFF` freezes the original scope and commit. It does not integrate or publish main,
+release the checkout, declare the business Task complete or authorize a production deployment.
+Continue the existing [handoff and integration](operations.md#handoff-and-integrate) flow, or use
+the complete [first change example](first-change.md). Scope/commit drift and unknown files keep
+their existing refusals. Active **or expired but still recorded** writer leases remain blocked;
+these entrypoints never steal, renew or remove them.
+
+## Inspect a blocked integration
+
+```bash
+worktree-controller task recover --repo /project --task-key original-integration-task
+# Also works after its candidate checkout has been released:
+worktree-controller task recover --repo /project --intent-id "$original_intent_id" --json
+```
+
+`recover` is a read-only entry to the existing `recovery-guide`. It shows the recorded owner,
+blockers and exact next formal command, retaining the original intent and evidence. For an
+unchanged BLOCKED integration, the supported path starts with quarantine, then formal abort,
+guarded release and retry of the original intent. Execute only the current owner-authorized
+step, then run `recover` again: every transition can change the next command and record version.
+Source/scope drift, dirty files, active publication and missing evidence still block recovery.
+The entry does not run commands, edit Controller metadata or make a recovery plan executable.
+
+## Read results accurately
+
+All actions accept `--json`. `list`, `show` and `recover` return 0 when observation succeeds,
+including when that observation describes a blocker. This is not recovery or task completion.
+Mutating actions return 0 only when the requested supported operation finishes; refusals,
+`RESOURCE_WAIT` and incomplete release return 2. A waiting admission keeps its existing request;
+inspect `admission-queue` instead of creating another task or branch.
+
+Task selectors do not replace exact session closeout. At normal session exit, use the real
+client/session/holder/run and every known expected allocation with `worktree-session-end --check
+--require-complete`; read all rows and `summary.terminal_complete`. Business Task completion,
+checkout release and published integration each require their own evidence.

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/docs/first-change.md

@@ -6,6 +6,10 @@ pause after handoff and continue in a new process with the original task and int
 It creates a **local bare Git remote**, never contacts a hosting service, and needs no credentials.
 Use a disposable workspace; do not point it at an existing project.
 
+This release uses the CLI 61 [task entrypoints](daily-workflow.md) for start, handoff and
+recovery inspection; use WC 1.31.0 or newer with `task_workflow_version` 1. The underlying
+writer, review, integration and closeout guards are the same as the low-level flow.
+
 ## Install the example's tools
 
 WC itself needs Linux, Python 3.12, Git and readable `/proc`. Install the released version using

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/docs/operations.md

@@ -7,6 +7,10 @@ the [getting started guide](getting-started.md) provides an isolated first run.
 
 ## Start or resume development
 
+For everyday feature/audit work, the [task entrypoints](daily-workflow.md) resolve the original
+checkout and record identity by task key, covering start, checkpoint/resume and finish. The
+steps below remain the underlying authority and the route for advanced integration/recovery.
+
 For a worked local task, use [your first change](first-change.md). Core inspection/allocation needs
 WC and Git. The integration flow below additionally uses Git Finalizer and separate test and
 Snapshot evidence; policy schema 4+ requires both receipt identities explicitly. The worked example

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/docs/reference.md

@@ -1,5 +1,8 @@
 # Technical reference
 
+For the task-oriented CLI 61 entrypoints, see [everyday task operations](daily-workflow.md).
+They delegate to the existing lifecycle guards and introduce no additional stored state.
+
 For a first run, use the [getting started guide](getting-started.md). This reference retains
 the detailed contracts, historical compatibility notes and benchmark evidence previously in the README.
 The [CLI contract](../tool_cli_contract.json) is authoritative for exact interfaces.

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/examples/change_task.py

@@ -99,7 +99,11 @@ def main():
         (workspace / name).write_text(json.dumps(value, indent=2) + "\n")
 
     def wc(command, *arguments):
-        value = json.loads(run(controller, command, "--repo", repo, "--json", *arguments))
+        if command == "task":
+            action, *arguments = arguments
+            value = json.loads(run(controller, command, action, "--repo", repo, "--json", *arguments))
+        else:
+            value = json.loads(run(controller, command, "--repo", repo, "--json", *arguments))
         require(not value.get("errors"), f"Controller refused {command}; see commands.jsonl")
         print(f"{command}: {(value.get('decision') or {}).get('code', 'observed')}", flush=True)
         return value
@@ -146,11 +150,10 @@ def main():
            "--message", "Initialize local demo", "--", "README.md", ".agents/worktree-policy.toml")
         wc("adopt", "--path", repo, "--task-key", "demo-control", "--authority-key", "demo-control",
            "--module", "demo", "--role", "control-plane", "--owner", OWNER, "--lifecycle", "ACTIVE")
-        request = ["--task-key", "demo-change", "--authority-key", "demo-change", "--module", "demo", "--role", "feature"]
-        require(wc("plan", *request)["decision"]["code"] == "CREATE_ALLOWED", "admission refused")
-        acquired = wc("acquire", *request, "--owner", OWNER, "--branch", "demo/change",
-                      "--base-ref", "main", "--path", source, "--scope", "README.md")
-        allocation = acquired["decision"]["allocation_id"]
+        acquired = wc("task", "start", "--task-key", "demo-change", "--module", "demo",
+                      "--owner", OWNER, "--branch", "demo/change", "--base-ref", "main",
+                      "--path", source, "--scope", "README.md")
+        allocation = acquired["decision"]["operation"]["allocation_id"]
         lease = wc("writer-lease-acquire", "--path", source, "--owner", OWNER,
                    "--holder-pid", os.getpid(), *identity)["decision"]
         guard = wc("write-guard", "--path", source, "--task-key", "demo-change",
@@ -168,8 +171,8 @@ def main():
         wc("writer-lease-release", "--path", source, "--lease-id", lease["lease_id"],
            "--holder-pid", holder["pid"], "--holder-boot-id", holder["boot_id"],
            "--holder-start-ticks", holder["start_ticks"], *identity)
-        wc("handoff", "--path", source, "--expected-record-version", row(source)["record_version"],
-           "--kind", "integration-ready", "--commit", commit, "--finalizer-commit", commit,
+        wc("task", "finish", "--task-key", "demo-change", "--owner", OWNER,
+           "--outcome", "handoff", "--commit", commit,
            "--finalizer-record-id", workspace / "source-finalizer.json")
         queued = wc("integration-enqueue", "--task-key", "demo-integration", "--authority-key",
                     "demo-integration", "--module", "demo", "--owner", OWNER,
@@ -197,7 +200,7 @@ def main():
                 require(not run("git", "-C", path, "status", "--porcelain"),
                         f"uncommitted files remain in {path}; preserve them and follow recovery-guide")
 
-    guide = wc("recovery-guide", "--intent-id", checkpoint["intent_id"])["decision"]
+    guide = wc("task", "recover", "--intent-id", checkpoint["intent_id"])["decision"]["guidance"]
     if guide.get("terminal_status") != "PUBLISHED_RELEASED":
         require(guide["intent"]["state"] in {"QUEUED", "PREPARING_INTEGRATION"},
                 "this demo resumes only queued or unchanged claimed work; follow recovery-guide")

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.30.6"
+version = "1.31.0"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.30.6"
+version = "1.31.0"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/__init__.py

@@ -1,3 +1,3 @@
 """Worktree lifecycle controller."""
 
-__version__ = "1.30.6"
+__version__ = "1.31.0"

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/cli.py

@@ -104,6 +104,10 @@ def build_parser() -> argparse.ArgumentParser:
     commands = parser.add_subparsers(dest="command", required=True)
     common = _common_parser()
 
+    from .task_workflow import add_parser as add_task_parser
+
+    add_task_parser(commands, common)
+
     status_parser = commands.add_parser("status", parents=[common], help="show Git and controller state")
     status_parser.add_argument("--namespace-pid", type=int,
                                help="compare mounts with an existing writer process")
@@ -1020,7 +1024,8 @@ def _main(argv: list[str] | None) -> int:
             payload = envelope("capabilities")
             payload["decision"] = {
                 "code": "CAPABILITIES",
-                "contract_version": 60,
+                "contract_version": 61,
+                "task_workflow_version": 1,
                 "exited_holder_release_version": 1,
                 "canonical_refresh_version": 1,
                 "host_handoff_continuation_version": HOST_HANDOFF_CONTINUATION_VERSION,
@@ -1119,6 +1124,10 @@ def _main(argv: list[str] | None) -> int:
                 release_receipt_id=parsed.release_receipt_id,
                 limit=parsed.limit, after=parsed.after,
             )
+        elif parsed.command == "task":
+            from .task_workflow import dispatch as dispatch_task
+
+            payload = dispatch_task(parsed)
         elif parsed.command == "recovery-guide":
             from .recovery_guidance import recovery_guide
 
@@ -1888,6 +1897,10 @@ def _main(argv: list[str] | None) -> int:
         _print(payload, parsed.json)
         return 2
     _print(payload, parsed.json)
+    if parsed.command == "task" and (
+        payload.get("errors") or payload.get("decision", {}).get("operation_complete") is False
+    ):
+        return 2
     if (payload.get("decision") or {}).get("code") in {
         "RESOURCE_CLEANUP_BLOCKED",
         "RECOVERY_ATTEMPT_INCOMPLETE",

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/lifecycle.py

@@ -2305,6 +2305,8 @@ def complete_no_change(
     expected_record_version: int,
     owner: str,
     preserve_only: bool = False,
+    expected_allocation_id: str | None = None,
+    require_no_writer_lease: bool = False,
 ) -> dict[str, Any]:
     """Record a genuine no-change completion for a task that produced no commit.
 
@@ -2320,7 +2322,9 @@ def complete_no_change(
         repository = inventory(repository_path)
         snapshot = store._load_unlocked()
         item, record = _managed_record(repository, snapshot, target)
-        _cas(record, expected_record_version)
+        _cas(record, expected_record_version, expected_allocation_id)
+        if require_no_writer_lease and record.allocation_id in snapshot.writer_leases:
+            raise ControllerError("WRITER_LEASE_PRESENT", "end the exact writer before task completion")
         policy = load_policy(repository.canonical_path)
         if policy.retained_slots < 1:
             raise ControllerError(
@@ -2683,6 +2687,8 @@ def resume(
     target: Path,
     expected_record_version: int,
     owner: str,
+    expected_allocation_id: str | None = None,
+    require_no_writer_lease: bool = False,
 ) -> dict[str, Any]:
     """Return a retained checkout to writer status under normal admission."""
 
@@ -2692,7 +2698,9 @@ def resume(
         repository = inventory(repository_path)
         snapshot = store._load_unlocked()
         item, record = _managed_record(repository, snapshot, target)
-        _cas(record, expected_record_version)
+        _cas(record, expected_record_version, expected_allocation_id)
+        if require_no_writer_lease and record.allocation_id in snapshot.writer_leases:
+            raise ControllerError("WRITER_LEASE_PRESENT", "an existing writer blocks task resume")
         if record.lifecycle != "RETAINED":
             raise ControllerError(
                 "INVALID_LIFECYCLE", f"lifecycle {record.lifecycle} is not retained"
@@ -3091,6 +3099,9 @@ def handoff(
     scope_paths: tuple[str, ...] = (),
     mainline_commit: str | None = None,
     scope_changed: bool = False,
+    expected_allocation_id: str | None = None,
+    expected_owner: str | None = None,
+    require_no_writer_lease: bool = False,
 ) -> dict[str, Any]:
     if kind not in {"integration-ready", "preserved"}:
         raise ControllerError("INVALID_HANDOFF", "handoff kind is invalid")
@@ -3102,7 +3113,11 @@ def handoff(
         repository = inventory(repository_path)
         snapshot = store._load_unlocked()
         item, record = _managed_record(repository, snapshot, target)
-        _cas(record, expected_record_version)
+        _cas(record, expected_record_version, expected_allocation_id)
+        if expected_owner is not None and record.owner != expected_owner:
+            raise ControllerError("OWNER_MISMATCH", "handoff owner does not match")
+        if require_no_writer_lease and record.allocation_id in snapshot.writer_leases:
+            raise ControllerError("WRITER_LEASE_PRESENT", "end the exact writer before task handoff")
         if record.lifecycle in {"QUARANTINED", "INTEGRATING", "PUBLISHED", "RELEASED"}:
             raise ControllerError(
                 "INVALID_LIFECYCLE", f"lifecycle {record.lifecycle} cannot be handed off"
@@ -8219,6 +8234,7 @@ def _release_registered_target(
     publication_receipt_id: str | None = None,
     release_intent_id: str | None = None,
     expected_governance_plan_id: str | None = None,
+    expected_allocation_id: str | None = None,
 ) -> dict[str, Any]:
     repository_initial = inventory(repository_path)
     store = MetadataStore(repository_initial.common_dir)
@@ -8231,6 +8247,8 @@ def _release_registered_target(
         repository = inventory(repository_path)
         snapshot = store._load_unlocked()
         item, record = _managed_record(repository, snapshot, target)
+        if expected_allocation_id is not None and record.allocation_id != expected_allocation_id:
+            raise ControllerError("IDENTITY_MISMATCH", "release allocation differs from the selected task")
         target_path = str(item.path)
         publication_receipt = (
             snapshot.publication_receipts.get(publication_receipt_id)
@@ -8927,6 +8945,7 @@ def release(
     publication_receipt_id: str | None = None,
     release_intent_id: str | None = None,
     expected_governance_plan_id: str | None = None,
+    expected_allocation_id: str | None = None,
 ) -> dict[str, Any]:
     target_path = str(target.expanduser().resolve(strict=False))
     repository = inventory(repository_path)
@@ -8947,6 +8966,7 @@ def release(
                 publication_receipt_id=publication_receipt_id,
                 release_intent_id=release_intent_id,
                 expected_governance_plan_id=expected_governance_plan_id,
+                expected_allocation_id=expected_allocation_id,
             )
         except ControllerError as error:
             if error.code not in {"INVALID_TARGET", "UNREGISTERED_WORKTREE"}:
@@ -8965,6 +8985,8 @@ def release(
                 }
                 return refreshed
             return payload
+    if expected_allocation_id is not None:
+        raise ControllerError("TASK_CHECKOUT_MISSING", "selected task checkout is absent; inspect its original lifecycle history")
     if expected_governance_plan_id is not None:
         raise ControllerError("GC_PLAN_DRIFT", "GC target is no longer registered")
     payload = _recover_or_replay_removed_release(

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/recovery_guidance.py

@@ -194,6 +194,13 @@ def recovery_guide(repository_path: Path, *, target: Path | None = None,
                   str(item["record_version"]), "--dry-run", "--json"])
             step("retry_original_intent", "After complete release, select the original intent with "
                  "recovery-guide --intent-id; retry requires its public plan and fresh admission")
+        elif lifecycle == "NO_CHANGE_COMPLETED":
+            decision["reason"] = "No-change completion is recorded; checkout release still has its own guards"
+            step("inspect_release", "Do not create another completion receipt; inspect release guards "
+                 "and preserve unclassified content before cleanup",
+                 ["worktree-controller", "release", "--repo", canonical, "--path", item["path"],
+                  "--owner-release", item["owner"], "--expected-record-version",
+                  str(item["record_version"]), "--dry-run", "--json"])
         elif lifecycle == "HANDOFF_READY":
             decision["reason"] = "A frozen handoff needs exact Finalizer identity before session closeout"
             step("check_session", "Run worktree-session-end --check with the real client/session/holder/run "

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/rendering.py

@@ -8,6 +8,8 @@ from typing import Any
 
 def render(payload: dict[str, Any]) -> str:
     command = payload.get("command")
+    if command == "task":
+        return _render_task(payload)
     repository = payload.get("repository") or {}
     lines: list[str] = []
     if repository:
@@ -177,3 +179,43 @@ def render(payload: dict[str, Any]) -> str:
         for error in errors:
             lines.append(f"  {error.get('code')}: {error.get('message')}")
     return "\n".join(lines)
+
+
+def _render_task(payload: dict[str, Any]) -> str:
+    decision = payload.get("decision") or {}
+    lines = [f"Repository: {(payload.get('repository') or {}).get('canonical_path', 'unknown')}",
+             f"{decision.get('code', 'ERROR')}: {decision.get('reason', '')}"]
+    for row in decision.get("tasks", []):
+        lines.append(f"  {row['task_key'] or 'unmanaged'} | owner={row['owner'] or 'unknown'} | "
+                     f"{row['lifecycle'] or 'unknown'} | writer={row['writer']} | "
+                     f"{'clean' if row['clean'] else 'dirty'} | {row['path']}")
+        if row.get("waiting_on"):
+            lines.append(f"    Waiting on: {row['waiting_on']}")
+    guidance = decision.get("guidance") or {}
+    task = guidance.get("identity") or decision.get("task")
+    if task:
+        lines.append(f"Task: {task['task_key']} | owner={task['owner']} | {task['lifecycle']}")
+        lines.append(f"Checkout: {task['path']}")
+    if operation := decision.get("operation"):
+        lines.append(f"Operation: {operation['code']}")
+        if operation.get("path"):
+            lines.append(f"Checkout: {operation['path']}")
+    if guidance.get("intent"):
+        lines.append(f"Integration: {guidance['intent']['intent_id']} | {guidance['intent']['state']}")
+    for blocker in guidance.get("blockers", []):
+        lines.append(f"Blocker: {blocker}")
+    for step in (*guidance.get("next_steps", []), *decision.get("next_steps", [])):
+        lines.append(f"Next: {step['message']}")
+        if step.get("argv"):
+            lines.append(f"  {shlex.join(step['argv'])}")
+    if history := decision.get("history"):
+        for row in history["closed_releases"]:
+            lines.append(f"Released: owner={row['owner']} | proof={row['proof_status']} | {row['branch']} | {row['worktree_path']}")
+        for row in history["incomplete_history"]:
+            lines.append(f"Incomplete history: {row['reason']}")
+        if history["next_after"]:
+            lines.append(f"More history: lifecycle-history --task-key (cursor {history['next_after']})")
+    for group in ("errors", "warnings"):
+        for item in payload.get(group, []):
+            lines.append(f"{item['code']}: {item['message']}")
+    return "\n".join(lines)

worktree_controller-1.31.0/src/worktree_controller/task_workflow.py

@@ -0,0 +1,269 @@
+"""Small task-oriented entrypoints over the existing Controller authorities.
+
+No task database, inferred owner, writer entitlement or new lifecycle is introduced.
+Mutations resolve one live allocation and pass its identity into the locked verb.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from .controller import envelope, status
+from .git_backend import resolve_commit
+from .lifecycle import acquire, complete_no_change, handoff, park, release, resume
+from .lifecycle_history import lifecycle_history
+from .models import ControllerError
+from .policy import load_policy
+from .recovery_guidance import recovery_guide
+
+CONTRACT = "task-workflow/v1"
+ACTIONS = ("list", "show", "start", "resume", "finish", "recover")
+
+
+def add_parser(commands: Any, common: argparse.ArgumentParser) -> None:
+    task = commands.add_parser("task", help="start, inspect, resume and settle a named task")
+    actions = task.add_subparsers(dest="task_action", required=True)
+    for action in ACTIONS:
+        parser = actions.add_parser(action, parents=[common])
+        if action == "list":
+            parser.add_argument("--owner", help="show only this recorded owner")
+            continue
+        if action == "start":
+            parser.add_argument("--task-key", required=True)
+            parser.add_argument("--owner", required=True)
+            parser.add_argument("--scope", action="append", required=True)
+            parser.add_argument("--authority-key", help="defaults to the explicit task key")
+            parser.add_argument("--module", default="task")
+            parser.add_argument("--branch", help="defaults to task/<task-key>")
+            parser.add_argument("--base-ref", help="defaults to policy publication remote/branch")
+            parser.add_argument("--path", type=Path)
+            continue
+        selector = parser.add_mutually_exclusive_group(required=True)
+        selector.add_argument("--task-key")
+        selector.add_argument("--path", type=Path)
+        if action in {"show", "recover"}:
+            selector.add_argument("--intent-id", help="original integration identity, also after release")
+        else:
+            parser.add_argument("--owner", required=True)
+        if action == "finish":
+            parser.add_argument("--outcome", choices=("no-change", "checkpoint", "handoff"), required=True)
+            parser.add_argument("--checkpoint-id")
+            parser.add_argument("--checkpoint-head", help="HEAD bound by the existing Task checkpoint")
+            parser.add_argument("--waiting-on")
+            parser.add_argument("--finalizer-record-id")
+            parser.add_argument("--commit", help="exact commit bound by the Finalizer record")
+
+
+def _row(observed: dict[str, Any], *, task_key: str | None, target: Path | None) -> dict[str, Any]:
+    if (task_key is None) == (target is None):
+        raise ControllerError("INVALID_SELECTOR", "select exactly one task key or checkout path")
+    resolved = str(target.expanduser().resolve(strict=False)) if target is not None else None
+    matches = [row for row in observed["worktrees"]
+               if (row["task_key"] == task_key if task_key is not None else row["path"] == resolved)]
+    if not matches:
+        raise ControllerError("UNKNOWN_TASK", "no live allocation matches; use task show for retained history")
+    if len(matches) != 1:
+        raise ControllerError("AMBIGUOUS_TASK", "multiple live allocations share this task key; select --path explicitly")
+    row = matches[0]
+    if row["metadata_missing"]:
+        raise ControllerError("MISSING_METADATA", "checkout has no recorded task authority")
+    return row
+
+
+def _identity(row: dict[str, Any]) -> dict[str, Any]:
+    return {field: row[field] for field in (
+        "allocation_id", "task_key", "authority_key", "owner", "path", "branch", "head",
+        "record_version", "lifecycle", "role", "scope_paths", "wait_checkpoint",
+    )}
+
+
+def _response(observed: dict[str, Any], action: str, code: str, reason: str, **extra: Any) -> dict[str, Any]:
+    payload = envelope("task")
+    payload["repository"] = observed["repository"]
+    payload["warnings"] = observed["warnings"]
+    payload["decision"] = {
+        "code": code, "contract": CONTRACT, "action": action, "reason": reason,
+        "business_task_completed": False, **extra,
+    }
+    return payload
+
+
+def inspect_task(repository_path: Path, *, task_key: str | None = None,
+                 target: Path | None = None, intent_id: str | None = None) -> dict[str, Any]:
+    """Keep original recovery commands/evidence; never turn observation into success."""
+    if sum(value is not None for value in (task_key, target, intent_id)) != 1:
+        raise ControllerError("INVALID_SELECTOR", "select exactly one task, path or original intent")
+    observed = status(repository_path)
+    if intent_id is not None:
+        guide = recovery_guide(repository_path, intent_id=intent_id)
+    else:
+        try:
+            row = _row(observed, task_key=task_key, target=target)
+        except ControllerError as error:
+            if error.code != "UNKNOWN_TASK" or task_key is None:
+                raise
+            history = lifecycle_history(repository_path, task_key=task_key)
+            decision = history["decision"]
+            if not (decision["closed_releases"] or decision["incomplete_history"]):
+                raise error
+            return _response(observed, "show", "TASK_HISTORY", "No live checkout; inspect the original release evidence",
+                             mutation_performed=False, history=decision)
+        guide = recovery_guide(repository_path, target=Path(row["path"]))
+    return _response(observed, "show", "TASK_GUIDANCE", guide["decision"]["reason"],
+                     mutation_performed=False, guidance=guide["decision"])
+
+
+def start_task(repository_path: Path, *, task_key: str, owner: str, scope_paths: tuple[str, ...],
+               authority_key: str | None = None, module: str = "task", branch: str | None = None,
+               base_ref: str | None = None, target: Path | None = None) -> dict[str, Any]:
+    if not scope_paths or any(not value.strip() for value in scope_paths):
+        raise ControllerError("MISSING_TASK_SCOPE", "declare the task's repository-relative file scope")
+    observed = status(repository_path)
+    if any(row["task_key"] == task_key for row in observed["worktrees"]):
+        raise ControllerError("TASK_ALREADY_EXISTS", "inspect or resume the existing task; no second checkout was requested")
+    policy = load_policy(Path(observed["repository"]["canonical_path"]))
+    base = f"{policy.publication_remote}/{policy.publication_branch}" if base_ref is None else base_ref
+    if base_ref is None:
+        try:
+            resolve_commit(Path(observed["repository"]["canonical_path"]), base)
+        except ControllerError as error:
+            if error.code != "INVALID_COMMIT":
+                raise
+            raise ControllerError("TASK_BASE_UNAVAILABLE", f"policy base {base} is unavailable locally; "
+                                  "fetch through your Git workflow or select --base-ref explicitly") from error
+    operation = acquire(repository_path, task_key=task_key,
+                        authority_key=task_key if authority_key is None else authority_key,
+                        module=module, role="feature", owner=owner,
+                        branch=f"task/{task_key}" if branch is None else branch,
+                        base_ref=base,
+                        target=target, scope_paths=scope_paths)
+    complete = operation["decision"]["code"] == "ACQUIRED"
+    return _response(operation, "start", "TASK_STARTED" if complete else "TASK_WAITING",
+                     "Checkout admitted; obtain a live writer lease before editing" if complete else
+                     "Admission did not create a checkout; keep the original request and inspect its decision",
+                     operation_complete=complete, operation=operation["decision"],
+                     writer_entitlement_granted=False)
+
+
+def _owned(repository_path: Path, task_key: str | None, target: Path | None,
+           owner: str) -> tuple[dict[str, Any], dict[str, Any]]:
+    observed = status(repository_path)
+    row = _row(observed, task_key=task_key, target=target)
+    if row["owner"] != owner:
+        raise ControllerError("OWNER_MISMATCH", "task owner does not match the recorded owner")
+    if row["canonical"] or row["role"] not in {"feature", "audit"}:
+        raise ControllerError("INVALID_ROLE", "this entry settles only feature/audit tasks; inspect recovery guidance for other roles")
+    return observed, row
+
+
+def resume_task(repository_path: Path, *, owner: str, task_key: str | None = None,
+                target: Path | None = None) -> dict[str, Any]:
+    _observed, row = _owned(repository_path, task_key, target, owner)
+    operation = resume(repository_path, target=Path(row["path"]), owner=owner,
+                       expected_record_version=row["record_version"],
+                       expected_allocation_id=row["allocation_id"], require_no_writer_lease=True)
+    return _response(operation, "resume", "TASK_RESUMED", "Original checkout resumed; obtain a live writer lease before editing",
+                     task=_identity(_row(operation, task_key=None, target=Path(row["path"]))),
+                     operation_complete=True, operation=operation["decision"],
+                     writer_entitlement_granted=False)
+
+
+def finish_task(repository_path: Path, *, owner: str, outcome: str, task_key: str | None = None,
+                target: Path | None = None, checkpoint_id: str | None = None,
+                checkpoint_head: str | None = None, waiting_on: str | None = None,
+                finalizer_record_id: str | None = None, commit: str | None = None) -> dict[str, Any]:
+    if outcome not in {"no-change", "checkpoint", "handoff"}:
+        raise ControllerError("INVALID_OUTCOME", "select no-change, checkpoint or handoff explicitly")
+    if (outcome != "checkpoint" and any(value is not None for value in (checkpoint_id, checkpoint_head, waiting_on))
+            or outcome != "handoff" and any(value is not None for value in (finalizer_record_id, commit))):
+        raise ControllerError("INVALID_OUTCOME", "evidence options must belong to the selected outcome")
+    if outcome == "checkpoint" and (not checkpoint_id or not checkpoint_head):
+        raise ControllerError("INVALID_CHECKPOINT", "save the existing Task checkpoint first and provide its ID and bound HEAD")
+    if outcome == "handoff" and (not finalizer_record_id or not commit):
+        raise ControllerError("MISSING_FINALIZER_RECORD", "provide the actual Finalizer record and its exact commit")
+    observed, row = _owned(repository_path, task_key, target, owner)
+    arguments = dict(target=Path(row["path"]), expected_record_version=row["record_version"],
+                     expected_allocation_id=row["allocation_id"], require_no_writer_lease=True)
+    if outcome == "checkpoint":
+        operation = park(repository_path, owner=owner, checkpoint_id=checkpoint_id,
+                         checkpoint_head=checkpoint_head, waiting_on=waiting_on, **arguments)
+        return _response(operation, "finish", "TASK_CHECKPOINT_RETAINED",
+                         "Checkpoint retained with its original checkout and branch; work remains unfinished",
+                         operation_complete=True, operation=operation["decision"],
+                         task=_identity(_row(operation, task_key=None, target=Path(row["path"]))), checkout_released=False)
+    if outcome == "handoff":
+        operation = handoff(repository_path, kind="integration-ready", commit=commit,
+                            finalizer_commit=commit, finalizer_record_id=finalizer_record_id,
+                            expected_owner=owner, **arguments)
+        return _response(operation, "finish", "TASK_HANDED_OFF",
+                         "Exact commit handed off; integration and publication are still separate steps",
+                         operation_complete=True, operation=operation["decision"],
+                         task=_identity(_row(operation, task_key=None, target=Path(row["path"]))), checkout_released=False)
+    operations = []
+    if row["lifecycle"] != "NO_CHANGE_COMPLETED":
+        operation = complete_no_change(repository_path, owner=owner, **arguments)
+        operations.append(operation["decision"])
+        row = {**row, "record_version": operation["decision"]["record_version"],
+               "lifecycle": "NO_CHANGE_COMPLETED"}
+    try:
+        operation = release(repository_path, target=Path(row["path"]), owner_release=owner,
+                            expected_record_version=row["record_version"],
+                            expected_allocation_id=row["allocation_id"])
+    except (ControllerError, OSError) as error:
+        # Completion and release have distinct durable boundaries. Preserve and
+        # report the completed prefix; a cleanup refusal must never read as PASS.
+        code = getattr(error, "code", "FILESYSTEM_ERROR")
+        next_step = {
+            "message": "Inspect release guards; preserve unknown content before cleanup",
+            "argv": ["worktree-controller", "release", "--repo",
+                     observed["repository"]["canonical_path"], "--path", row["path"],
+                     "--owner-release", owner, "--expected-record-version",
+                     str(row["record_version"]), "--dry-run", "--json"],
+        }
+        if code in {"IDENTITY_MISMATCH", "TASK_CHECKOUT_MISSING", "CAS_MISMATCH", "BINDING_IDENTITY_DRIFT"}:
+            next_step = {
+                "message": "Inspect the original allocation; do not act on a replacement checkout",
+                "argv": ["worktree-controller", "lifecycle-history", "--repo",
+                         observed["repository"]["canonical_path"], "--allocation-id",
+                         row["allocation_id"], "--json"],
+            }
+        payload = _response(observed, "finish", "TASK_RELEASE_BLOCKED",
+                            "No-change completion recorded; checkout release still needs owner action",
+                            operation_complete=False, operations=operations, task=_identity(row),
+                            checkout_released=False, next_steps=[next_step])
+        payload["errors"] = [{"code": code, "message": str(error)}]
+        return payload
+    operations.append(operation["decision"])
+    return _response(operation, "finish", "TASK_CHECKOUT_RELEASED", "No-change completion recorded and checkout released; branch retained",
+                     operation_complete=True, operations=operations, task=_identity(row),
+                     checkout_released=True)
+
+
+def dispatch(parsed: argparse.Namespace) -> dict[str, Any]:
+    action = parsed.task_action
+    if action == "list":
+        observed = status(parsed.repo)
+        rows = [row for row in observed["worktrees"] if not row["canonical"]
+                and (parsed.owner is None or row["owner"] == parsed.owner)]
+        return _response(observed, action, "TASK_LIST", "Live checkouts only; clean or idle does not mean completed",
+                         mutation_performed=False, tasks=[{
+                             **{key: row[key] for key in ("task_key", "owner", "path", "lifecycle", "clean", "metadata_missing")},
+                             "writer": (row.get("lifecycle_observation") or {}).get("lease", {}).get("status", "UNKNOWN"),
+                             "waiting_on": (row.get("wait_checkpoint") or {}).get("waiting_on"),
+                         } for row in rows])
+    if action == "start":
+        return start_task(parsed.repo, task_key=parsed.task_key, owner=parsed.owner,
+                          scope_paths=tuple(parsed.scope), authority_key=parsed.authority_key,
+                          module=parsed.module, branch=parsed.branch, base_ref=parsed.base_ref, target=parsed.path)
+    selector = {"task_key": parsed.task_key, "target": parsed.path}
+    if action in {"show", "recover"}:
+        result = inspect_task(parsed.repo, **selector, intent_id=parsed.intent_id)
+        result["decision"]["action"] = action
+        return result
+    if action == "resume":
+        return resume_task(parsed.repo, owner=parsed.owner, **selector)
+    return finish_task(parsed.repo, owner=parsed.owner, outcome=parsed.outcome, **selector,
+                       checkpoint_id=parsed.checkpoint_id, checkpoint_head=parsed.checkpoint_head,
+                       waiting_on=parsed.waiting_on, finalizer_record_id=parsed.finalizer_record_id, commit=parsed.commit)

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/src/worktree_controller/tool_cli_contract.json

@@ -1,5 +1,10 @@
 {
   "commands": [
+    {
+      "name": "task",
+      "operation_class": "git_worktree_mutation",
+      "result_contract": "worktree-controller/v1"
+    },
     {
       "name": "acquire",
       "operation_class": "git_worktree_mutation",
@@ -404,7 +409,8 @@
   "branch_retirement_version": 1,
   "branch_retirement_verify_version": 1,
   "cleanup_hardlink_topology_version": 2,
-  "contract_version": 60,
+  "contract_version": 61,
+  "task_workflow_version": 1,
   "release_recovery_inspection_version": 1,
   "release_recovery_inspection_contract": {
     "contract": "release-recovery-inspection/v1",
@@ -1065,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.30.6",
+  "tool_version": "1.31.0",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,
@@ -1787,5 +1793,34 @@
     "retention": "history records the checkpoint reference; status exposes wait_checkpoint while RETAINED",
     "release": "explicit reviewed archive-retained plan then unchanged guarded release; branches kept, unknown files block",
     "resume": "the Task restores the exact retained HEAD through controlled admission and revalidates context before a new writer"
+  },
+  "task_workflow_contract": {
+    "contract": "task-workflow/v1",
+    "version": 1,
+    "actions": [
+      "list",
+      "show",
+      "start",
+      "resume",
+      "finish",
+      "recover"
+    ],
+    "read_only": [
+      "list",
+      "show",
+      "recover"
+    ],
+    "selectors": "One exact task key or checkout path; show/recover also accept the original integration intent. Ambiguous live task keys fail closed.",
+    "start": "Feature allocation only; explicit owner and scope. Defaults: authority=task key, module=task, branch=task/<task-key>, base=policy publication remote/branch. No writer lease is granted.",
+    "resume": "Original retained allocation only, exact owner/allocation/record CAS and no writer lease; does not grant write entitlement.",
+    "finish": {
+      "no-change": "Complete no-change then guarded release; retain branch. Partial release failures preserve completion evidence and exit 2.",
+      "checkpoint": "Require existing Task checkpoint ID and explicitly bound HEAD; park with no writer lease, preserve files and checkout.",
+      "handoff": "Require actual Finalizer record and exact commit; freeze handoff with exact owner/allocation/CAS and no writer lease. Integration/publication remain separate."
+    },
+    "recovery": "Read-only forwarding of existing recovery-guidance/v1; execute its formal steps separately and reobserve after every transition.",
+    "exit": "0 for successful observation or completed requested operation; 2 for refusal, RESOURCE_WAIT or incomplete checkout release. Observation exit 0 never proves task completion.",
+    "storage": "No additional state, lifecycle states or database; storage layout remains 5.",
+    "compatibility": "CLI 61 adds task-workflow/v1; existing low-level commands and contracts remain compatible."
   }
 }

{worktree_controller-1.30.6 → worktree_controller-1.31.0}/tool_cli_contract.json

@@ -1,5 +1,10 @@
 {
   "commands": [
+    {
+      "name": "task",
+      "operation_class": "git_worktree_mutation",
+      "result_contract": "worktree-controller/v1"
+    },
     {
       "name": "acquire",
       "operation_class": "git_worktree_mutation",
@@ -404,7 +409,8 @@
   "branch_retirement_version": 1,
   "branch_retirement_verify_version": 1,
   "cleanup_hardlink_topology_version": 2,
-  "contract_version": 60,
+  "contract_version": 61,
+  "task_workflow_version": 1,
   "release_recovery_inspection_version": 1,
   "release_recovery_inspection_contract": {
     "contract": "release-recovery-inspection/v1",
@@ -1065,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.30.6",
+  "tool_version": "1.31.0",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,
@@ -1787,5 +1793,34 @@
     "retention": "history records the checkpoint reference; status exposes wait_checkpoint while RETAINED",
     "release": "explicit reviewed archive-retained plan then unchanged guarded release; branches kept, unknown files block",
     "resume": "the Task restores the exact retained HEAD through controlled admission and revalidates context before a new writer"
+  },
+  "task_workflow_contract": {
+    "contract": "task-workflow/v1",
+    "version": 1,
+    "actions": [
+      "list",
+      "show",
+      "start",
+      "resume",
+      "finish",
+      "recover"
+    ],
+    "read_only": [
+      "list",
+      "show",
+      "recover"
+    ],
+    "selectors": "One exact task key or checkout path; show/recover also accept the original integration intent. Ambiguous live task keys fail closed.",
+    "start": "Feature allocation only; explicit owner and scope. Defaults: authority=task key, module=task, branch=task/<task-key>, base=policy publication remote/branch. No writer lease is granted.",
+    "resume": "Original retained allocation only, exact owner/allocation/record CAS and no writer lease; does not grant write entitlement.",
+    "finish": {
+      "no-change": "Complete no-change then guarded release; retain branch. Partial release failures preserve completion evidence and exit 2.",
+      "checkpoint": "Require existing Task checkpoint ID and explicitly bound HEAD; park with no writer lease, preserve files and checkout.",
+      "handoff": "Require actual Finalizer record and exact commit; freeze handoff with exact owner/allocation/CAS and no writer lease. Integration/publication remain separate."
+    },
+    "recovery": "Read-only forwarding of existing recovery-guidance/v1; execute its formal steps separately and reobserve after every transition.",
+    "exit": "0 for successful observation or completed requested operation; 2 for refusal, RESOURCE_WAIT or incomplete checkout release. Observation exit 0 never proves task completion.",
+    "storage": "No additional state, lifecycle states or database; storage layout remains 5.",
+    "compatibility": "CLI 61 adds task-workflow/v1; existing low-level commands and contracts remain compatible."
   }
 }