worktree-controller 1.32.0__tar.gz → 1.32.2__tar.gz

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.32.0
+Version: 1.32.2
 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.32.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.2 · 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.32.0
+python -m pip install worktree-controller==1.32.2
 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.32.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.2 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.32.0
+git checkout v1.32.2
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/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.32.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.2 · 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.32.0
+python -m pip install worktree-controller==1.32.2
 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.32.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.2 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.32.0
+git checkout v1.32.2
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/docs/architecture.md

@@ -10,8 +10,8 @@ development and recovery paths; exact public interfaces live in the [contract](.
 | --- | --- | --- |
 | CLI parsing and routing | `cli.py`, command modules | Dispatch explicit operations; do not duplicate authority decisions |
 | Git observations and mutations | `git_backend.py` | Git owns registrations, refs, paths, HEAD and cleanliness |
-| State and durable evidence | `models.py`, `store.py`, `metadata_codec.py` | Validate stored identities; serialize mutations under the repository lock |
-| Shared identity and semantic checks | `semantics.py` | Consume the caller's snapshot; do not acquire authority or write metadata |
+| State and durable evidence | `models.py`, `store.py`, `metadata_codec.py`, `record_updates.py` | Validate stored identities; serialize mutations under the repository lock; record updates bump their version, and both update helpers append history |
+| Shared identity and semantic checks | `semantics.py` | Consume the caller's snapshot, including effective intent state and terminal reconciliation; do not acquire authority or write metadata |
 | Budget admission | `resource_admission.py` | Preserve durable request identity and host reservations across retries |
 | Writer entitlement | `writer_lease.py`, `writer_session.py`, `governance.py` | Bind the real process identity and exact operation/target |
 | Lifecycle orchestration | `lifecycle.py` and focused recovery modules | Compose existing guards and append durable transition evidence |

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/docs/client-integration.md

@@ -105,6 +105,33 @@ This demonstrates two CLI consumers, not actual invocation or discovery by two A
 Vendor-specific discovery and live-client use require their own observed acceptance, as described
 in [checks and deployment evidence](operations.md#checks-and-deployment).
 
+## Accept a real AI client
+
+Accept a client by observing it use the installed WC interface during a real task,
+including a pause and continuation in a later native session. Running the offline
+protocol example checks the CLI workflow; it does not establish that an AI client
+discovers or invokes WC correctly. Keep the actual session identities and checkpoint
+evidence with the acceptance result, and limit claims to the client and workflow observed.
+
+Use the separate `worktree-session-end` executable for session closeout. Keep a practical
+evidence checklist:
+
+- Capture actual native-client WC invocations, raw results and exit codes, client version,
+  and distinct native session/run/holder identities before and after interruption.
+- Verify the raw checkpoint digest and unchanged Task/authority/owner, allocation, path,
+  branch, HEAD and scope; compare exact file SHA256 values before the next session edits.
+- Resume the original Task, acquire a fresh live writer, and pass its check and write guard;
+  record refusal of the previous identity without reviving it or bypassing a refusal.
+- While leases are recorded, check and end with the exact client/session/run/holder selector.
+  Include every allocation via `--expected-allocation-id`; retain every per-tree decision
+  and require `summary.terminal_complete` with `--require-complete` before claiming closeout.
+- Follow the [first-change workflow](first-change.md) to finish; keep separate Finalizer,
+  handoff, integration/publication and release evidence before claiming task completion.
+  A retained checkpoint preserves unfinished work; it is not delivery evidence.
+
+One tested vendor does not prove another vendor's discovery or invocation of WC; accept each
+client and workflow using its own observed evidence.
+
 ## Upgrade an existing managed installation
 
 A public package installation in a new environment is separate from activation of a shared

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/docs/reference.md

@@ -1478,9 +1478,10 @@ checkout rejects feature writes. `READY_TO_PUBLISH` is write-fenced until explic
 out-of-band HEAD, content, record, or binding drift makes old evidence unusable.
 
 The bounded `integration-keyed-document-scope/v1` refinement applies only when the entire
-overlap is the exact `docs/handbook/business-progress.json` path. Every pair of frozen source
-commits must have one non-ancestor merge base and the same committed `.gitattributes` declaring
-`merge=qp-handbook-progress`. QP schema 2 records are compared by whole `tasks.authority_key`
+overlap is exactly `docs/nexus/business-progress.json` with `merge=qp-nexus-progress`, or
+the historical `docs/handbook/business-progress.json` with `merge=qp-handbook-progress`.
+Cross-path moves retain the ordinary file fence. Every pair of frozen source commits must have
+one non-ancestor merge base and the same committed `.gitattributes` declaring the matching profile. QP schema 2 records are compared by whole `tasks.authority_key`
 or `development_lines/modules/decisions.id`, including additions and deletions. All changed key
 sets must be disjoint. Metadata, schema, ordering, duplicate keys, missing/oversized/non-regular
 blobs, unknown evidence, broad paths and code overlaps keep the ordinary file fence. Explicit

worktree_controller-1.32.2/docs/scope.md

@@ -0,0 +1,86 @@
+# Scope and consumer surface (draft for owner decision)
+
+This document records which parts of the public CLI are generic worktree governance and which
+exist mainly for one consumer. It is an inventory plus proposed boundaries; nothing here changes
+behavior, and every "proposed" line needs an owner decision before code moves.
+
+Snapshot: CLI contract 61, 81 commands, 65 `*_version` capability keys. The public contract
+counts were rechecked on 2026-10-23; consumer mappings below are the cloud audit
+reported in the maintainer handoff, not a runtime trace or proof of exclusive use.
+
+## How the inventory was made
+
+- **Agent Workspace (AW):** every `_invoke(...)` call in AW's controller client
+  (`backend/src/agent_workspace/infrastructure/worktree_controller.py`) plus its session-retirement
+  and external-execution modules. This was an exact static match in that audit, not a guarantee
+  that dynamic or other consumers do not exist.
+- **Git Finalizer (GF):** word match over `git-finalize*` and `tooling/*.py`. Common words
+  (`review`, `task`, `release`, `resume`, `status`, `doctor`) can be false positives; the
+  retirement and publication entries are confirmed by GF's adapter code.
+- **Docs/examples:** word match over `README.md`, `docs/`, `examples/` and the shipped Skill.
+
+## 1. Generic governance core (keep; any client)
+
+Checkout budget, ownership and safe release for any person or agent sharing a repository:
+
+`plan`, `status`, `doctor`, `capabilities`, `acquire`, `adopt`, `park`, `reopen`, `release`,
+`release-intent`, `quarantine`, `review`, `handoff`, `resume`, `task`, `complete-no-change`,
+`recovery-guide`, `lifecycle-history`, `write-guard`, `writer-lease-acquire`,
+`writer-lease-release`, `writer-session`, `lease-acquire`, `lease-complete`, `lease-abort`,
+`integration-enqueue`, `integration-claim`, `integration-validate`, `integration-queue`,
+`integration-refresh`, `reconcile`.
+
+## 2. Delivery-tool protocols (keep; versioned, consumed by GF)
+
+`branch-retirement-plan`, `-verify`, `-authorize`, `-complete`, `-record`, `-status`,
+`-executions`, and `publication-execution-session`. These are the public protocols GF consumes
+through capabilities; they should evolve by capability version, not by CLI contract number.
+
+## 3. Host-runtime integration (used by AW today)
+
+| Command | Used by AW | Note |
+| --- | --- | --- |
+| `host-execution` | yes | Budgets a host process with no repository writer lease; default `--client-id` is `agent-workspace` |
+| `execution-admit`, `execution-cancel` | yes | Durable admission of governed executions |
+| `admission-queue` | yes | Periodic queue reconciliation |
+| `binding-add`, `binding-remove`, `binding-transfer` | yes | Runtime bindings owned by a host |
+| `lifecycle-events`, `lifecycle-event-ack` | yes | Event feed with consumer acknowledgement |
+| `session-admit`, `session-bind`, `reconcile-session` | not found in AW's client | Need an owner answer: other host, legacy, or removable |
+
+**Proposed:** keep these in WC only if they are documented as a generic *host runtime protocol*
+(any host, explicit `--client-id`, no AW-specific defaults or wording). Otherwise move the
+AW-specific policy (memory budgets, default identities) into AW and keep WC's part to admission
+and binding records.
+
+## 4. Recovery and maintenance tail
+
+`recover-handoff`, `recover-published`, `recovery-adopt`, `release-recovery-inspect`,
+`integration-abort`, `-abandon`, `-reopen`, `-resolve`, `-retry`, `-equivalent`,
+`-recovery-matrix`, `close-delivered`, `close-preserved`, `adopt-delivered`, `archive-retained`,
+`externalize`, `resource-register`, `resource-clean`, `resource-recover`, `gc-plan`, `gc-apply`,
+`reconcile-writers`, `acquire-across`, `acquire-when-free`, `canonical-refresh`,
+`canonical-transition`, `namespace-migration-plan`, `-verify`, `-receipts`, `namespace-migrate`.
+
+Most of these have no consumer in AW or GF and appear only in reference docs, or not at all.
+
+**Proposed:** classify each as *supported*, *operator-only* or *deprecated* in the CLI contract,
+publish a deprecation window for the last group, and stop adding a new top-level command per
+recovery case — prefer one `recover` entry with typed subcases.
+
+## Open questions for the owner
+
+1. Is `host-execution` meant for hosts other than AW? If not, should its policy move to AW?
+2. Who uses `session-admit`, `session-bind` and `reconcile-session`?
+3. Which section-4 commands may be deprecated, and on what timeline?
+
+## Current compatibility decision
+
+Keep every existing command supported while these ownership questions are unresolved. Do not
+remove host commands, change default identities, relax recovery guards or deprecate commands
+from an absence of static matches. New hosts use explicit client/session identities and the
+versioned public contracts described in [client integration](client-integration.md). WC remains
+the lifecycle and policy authority; consumers retain their business and release approvals.
+
+Effective integration-state interpretation lives in `semantics.py`;
+record and intent updates live in `record_updates.py`. These moves preserve CLI contract 61 and
+storage layout 5. See [architecture](architecture.md) for module responsibilities.

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/pyproject.toml

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

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/pyproject.toml.orig

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

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/__init__.py

@@ -1,3 +1,3 @@
 """Worktree lifecycle controller."""
 
-__version__ = "1.32.0"
+__version__ = "1.32.2"

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/canonical_transition.py

@@ -19,7 +19,6 @@ from .git_backend import (
     update_branch_ref,
     validate_branch_name,
 )
-from .lifecycle import _updated_record
 from .models import (
     ControllerError,
     MetadataRecord,
@@ -29,6 +28,7 @@ from .models import (
     WorktreePolicy,
 )
 from .policy import default_policy, load_policy, parse_policy
+from .record_updates import updated_record
 from .semantics import managed_record as _managed_record
 from .store import MetadataStore
 from .transaction_scope import conflicts
@@ -274,7 +274,7 @@ def transition_canonical(
             if not refresh_main and item.branch == expected_branch:
                 git_write(item.path, ("checkout", "--no-overwrite-ignore", expected_branch))
             raise
-        updated = _updated_record(
+        updated = updated_record(
             record,
             "CANONICAL_MAIN_REFRESHED" if refresh_main else "CANONICAL_TRANSITIONED",
             lifecycle="ACTIVE",

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/controller.py

@@ -33,9 +33,9 @@ from .mount_diagnostics import diagnose_mounts, mount_warnings
 from .policy import load_policy
 from .semantics import (
     EVIDENCE_LIFECYCLES,
+    effective_intent_state,
     evidence_head_issues,
     integration_candidate_issues,
-    integration_intent_abandoned,
     integration_queue_order,
     normalize_scope_paths,
     path_scope_issues,
@@ -248,22 +248,6 @@ def _intent_for_allocation(snapshot: MetadataSnapshot, allocation_id: str | None
     return matches[0] if matches else None
 
 
-def _effective_intent_state(snapshot: MetadataSnapshot, intent: Any) -> str:
-    reconciliations = [
-        receipt
-        for receipt in snapshot.integration_reconciliation_receipts.values()
-        if receipt.intent_id == intent.intent_id
-        and receipt.result == "STALE_INTENT_TERMINAL_ACKNOWLEDGED"
-    ]
-    if len(reconciliations) > 1:
-        raise ControllerError(
-            "INVALID_METADATA", "integration intent has multiple terminal reconciliations"
-        )
-    if reconciliations:
-        return reconciliations[0].effective_terminal_state
-    return "ABANDONED" if integration_intent_abandoned(intent) else intent.state
-
-
 def _integration_intent_order(intent: Any) -> tuple[int, int | str, str]:
     if intent.queue_sequence > 0:
         return (1, intent.queue_sequence, intent.intent_id)
@@ -400,7 +384,7 @@ def _repository_payload(
         (
             intent
             for intent in snapshot.integration_intents.values()
-            if _effective_intent_state(snapshot, intent) in {"QUEUED", "WAITING_SCOPE"}
+            if effective_intent_state(snapshot, intent) in {"QUEUED", "WAITING_SCOPE"}
         ),
         key=lambda value: integration_queue_order(snapshot, value),
     )
@@ -543,7 +527,7 @@ def _worktree_payload(
         "source_allocations": list(record.source_allocations) if record else [],
         "integration_intent_id": intent.intent_id if intent else None,
         "integration_intent_state": (
-            _effective_intent_state(snapshot, intent)
+            effective_intent_state(snapshot, intent)
             if intent is not None and snapshot is not None
             else None
         ),
@@ -1317,7 +1301,7 @@ def _semantic_warnings(
         "RELEASED": {"RELEASED"},
     }
     for intent in snapshot.integration_intents.values():
-        effective_state = _effective_intent_state(snapshot, intent)
+        effective_state = effective_intent_state(snapshot, intent)
         if effective_state in {"QUEUED", "WAITING_SCOPE", "ABANDONED"}:
             continue
         if unallocated_integration_conflict(intent):

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/convergence.py

@@ -199,13 +199,13 @@ def _is_candidate(record: MetadataRecord) -> bool:
 
 
 def _integration_bound(snapshot: MetadataSnapshot, record: MetadataRecord) -> bool:
-    from .lifecycle import _effective_intent_state
+    from .semantics import effective_intent_state
 
     return any(
         intent.allocation_id == record.allocation_id
         or record.allocation_id in intent.source_allocations
         for intent in snapshot.integration_intents.values()
-        if _effective_intent_state(snapshot, intent) not in TERMINAL_INTEGRATION_STATES
+        if effective_intent_state(snapshot, intent) not in TERMINAL_INTEGRATION_STATES
     ) or any(
         other.lifecycle != "RELEASED" and record.allocation_id in other.source_allocations
         for other in snapshot.records.values()

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/delivered_closeout.py

@@ -345,11 +345,11 @@ def _eligible(
     for_typed_cleanup: bool = False,
 ) -> dict[str, str]:
     from .lifecycle import (
-        _effective_intent_state,
         _typed_runtime_blockers,
         _typed_runtime_evidence,
         _validate_release_environment,
     )
+    from .semantics import effective_intent_state
 
     if for_typed_cleanup and (state != "RETAINED" or require_publication):
         raise ControllerError("INVALID_LIFECYCLE", "typed cleanup does not authorize publication")
@@ -410,7 +410,7 @@ def _eligible(
             record.allocation_id in intent.source_allocations
             and (
                 not (
-                    (effective_state := _effective_intent_state(snapshot, intent)) == "ABANDONED"
+                    (effective_state := effective_intent_state(snapshot, intent)) == "ABANDONED"
                     or (not require_publication and effective_state == "RELEASED")
                 )
                 or not is_ancestor(
@@ -662,7 +662,7 @@ def close_delivered(
     plan_id: str | None = None,
 ) -> dict[str, Any]:
     from .controller import envelope
-    from .lifecycle import _updated_record
+    from .record_updates import updated_record
     from .semantics import assert_record_version as _cas
     from .semantics import managed_record as _managed_record
 
@@ -758,7 +758,7 @@ def close_delivered(
                     "plan_id": identity,
                     "plan": plan,
                 }
-                updated = _updated_record(record, EVENT, lifecycle=STATE)
+                updated = updated_record(record, EVENT, lifecycle=STATE)
                 event = {
                     **updated.history[-1],
                     "closeout_receipt_id": receipt_id,
@@ -803,7 +803,7 @@ def archive_retained(
 ) -> dict[str, Any]:
     """Freeze a clean, unfinished retained task for guarded physical release."""
     from .controller import envelope
-    from .lifecycle import _updated_record
+    from .record_updates import updated_record
     from .semantics import assert_record_version as _cas
     from .semantics import managed_record as _managed_record
 
@@ -896,7 +896,7 @@ def archive_retained(
                     "plan_id": identity,
                     "plan": plan,
                 }
-                updated = _updated_record(record, ARCHIVE_EVENT, lifecycle=ARCHIVE_STATE)
+                updated = updated_record(record, ARCHIVE_EVENT, lifecycle=ARCHIVE_STATE)
                 event = {
                     **updated.history[-1],
                     "archive_receipt_id": receipt_id,

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/frozen_recovery.py

@@ -20,10 +20,10 @@ from .lifecycle import (
     _cancel_release_intents,
     _typed_runtime_blockers,
     _typed_runtime_evidence,
-    _updated_record,
 )
 from .models import ControllerError
 from .policy import load_policy
+from .record_updates import updated_record
 from .semantics import assert_record_version as _cas
 from .semantics import integration_intent_abandoned, publication_ref
 from .semantics import managed_record as _managed_record
@@ -245,7 +245,7 @@ def recover_frozen_checkout(
                 git_write(item.path, ("symbolic-ref", "HEAD", f"refs/heads/{branch}"))
             elif latest.branch != branch:
                 raise ControllerError("BLOCK_DRIFT", "checkout branch changed during recovery")
-            updated = _updated_record(record, "PUBLISHED_CHECKOUT_REATTACHED")
+            updated = updated_record(record, "PUBLISHED_CHECKOUT_REATTACHED")
         else:
             _cancel_release_intents(
                 store,
@@ -254,7 +254,7 @@ def recover_frozen_checkout(
                 event="FROZEN_SOURCE_RECOVERED",
                 blocker="REOPENED",
             )
-            updated = _updated_record(
+            updated = updated_record(
                 record,
                 "PUBLISHED_SOURCE_RECOVERED",
                 lifecycle="ACTIVE",

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/integration_conflict.py

@@ -23,7 +23,8 @@ def resolve_integration(
     finalizer_record_id: str,
 ) -> dict[str, Any]:
     from .controller import status
-    from .lifecycle import _intent_for_allocation, _intent_payload, _updated_intent, _updated_record
+    from .lifecycle import _intent_for_allocation, _intent_payload
+    from .record_updates import updated_intent, updated_record
     from .semantics import assert_record_version as _cas
     from .semantics import managed_record as _managed_record
 
@@ -84,8 +85,8 @@ def resolve_integration(
         issues = integration_candidate_issues(item, record, snapshot, require_task_match=False)
         if issues:
             raise ControllerError(issues[0]["code"], issues[0]["message"])
-        updated = _updated_record(record, "INTEGRATION_CONFLICT_RESOLVED", task_commit=item.head)
-        resolved = _updated_intent(
+        updated = updated_record(record, "INTEGRATION_CONFLICT_RESOLVED", task_commit=item.head)
+        resolved = updated_intent(
             intent,
             "INTEGRATION_CONFLICT_RESOLVED",
             candidate_oid=item.head,

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/integration_retry.py

@@ -227,7 +227,8 @@ def _prerequisite(
     parent: IntegrationIntent,
     child: IntegrationIntent,
 ) -> dict[str, Any]:
-    from .lifecycle import _effective_intent_state, _scopes_overlap
+    from .lifecycle import _scopes_overlap
+    from .semantics import effective_intent_state
 
     if (
         child.owner != parent.owner
@@ -255,7 +256,7 @@ def _prerequisite(
     if any(
         other.intent_id != parent.intent_id
         and other.allocation_id is not None
-        and _effective_intent_state(snapshot, other) not in {"RELEASED", "ABANDONED"}
+        and effective_intent_state(snapshot, other) not in {"RELEASED", "ABANDONED"}
         and other.queue_sequence > parent.queue_sequence
         and _scopes_overlap(other.scope_paths, child.scope_paths)
         for other in snapshot.integration_intents.values()
@@ -295,7 +296,7 @@ def _plan(
     prerequisite_id: str | None,
     reason: str,
 ) -> dict[str, Any]:
-    from .lifecycle import _effective_intent_state
+    from .semantics import effective_intent_state
 
     failure = _failure(repository, snapshot, store, intent)
     source_records = _sources(repository, snapshot, store, intent)
@@ -324,7 +325,7 @@ def _plan(
         bound = integration_prerequisite(intent)
         if bound:
             child = snapshot.integration_intents.get(bound)
-            if child is None or _effective_intent_state(snapshot, child) != "RELEASED":
+            if child is None or effective_intent_state(snapshot, child) != "RELEASED":
                 raise ControllerError(
                     "RETRY_PREREQUISITE_PENDING",
                     "prerequisite needs formal publication and release",
@@ -379,7 +380,7 @@ def _plan(
         "queue_evidence": {
             other.intent_id: _digest(integration_intent_to_dict(other))
             for other in snapshot.integration_intents.values()
-            if _effective_intent_state(snapshot, other) not in {"RELEASED", "ABANDONED"}
+            if effective_intent_state(snapshot, other) not in {"RELEASED", "ABANDONED"}
         },
     }
     return {**value, "plan_id": _digest(value)}
@@ -397,7 +398,8 @@ def retry_integration(
 ) -> dict[str, Any]:
     """Plan/CAS an append-only dependency decision or restart the original intent."""
     from .controller import status
-    from .lifecycle import _blocking_scope_intent, _emit_lifecycle_event, _updated_intent
+    from .lifecycle import _blocking_scope_intent, _emit_lifecycle_event
+    from .record_updates import updated_intent
 
     detail = reason.strip()
     if not detail or len(detail) > 512 or "\x00" in detail:
@@ -451,9 +453,9 @@ def retry_integration(
                 raise ControllerError("BLOCK_DRIFT", "retry plan evidence changed; plan again")
             if not dry_run:
                 if prerequisite_intent_id:
-                    updated = _updated_intent(intent, "RETRY_PREREQUISITE_BOUND")
+                    updated = updated_intent(intent, "RETRY_PREREQUISITE_BOUND")
                 else:
-                    updated = _updated_intent(
+                    updated = updated_intent(
                         intent,
                         "PREPARATION_RETRY_QUEUED",
                         state="QUEUED",

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/keyed_document_scope.py

@@ -1,4 +1,4 @@
-"""Prove independent Handbook records from frozen Git objects, never working files.
+"""Prove independent Nexus records from frozen Git objects, never working files.
 
 This refines only the known keyed-document overlap. It does not choose merge results,
 change declared ownership, or replace candidate validation and main publication CAS.
@@ -13,8 +13,11 @@ from pathlib import Path
 from .git_backend import _git
 from .models import ControllerError
 
-PROGRESS_PATH = "docs/handbook/business-progress.json"
-_ATTRIBUTE = f"{PROGRESS_PATH} merge=qp-handbook-progress"
+PROGRESS_PATH = "docs/nexus/business-progress.json"
+PROGRESS_PROFILES = {
+    PROGRESS_PATH: "qp-nexus-progress",
+    "docs/handbook/business-progress.json": "qp-handbook-progress",
+}
 _COLLECTIONS = {
     "tasks": "authority_key",
     "development_lines": "id",
@@ -105,11 +108,11 @@ def _blob(repo: Path, commit: str, path: str, *, limit: int = _MAX_BYTES) -> byt
     return raw
 
 
-def _progress(repo: Path, commit: str) -> tuple[str, bytes]:
+def _progress(repo: Path, commit: str, path: str) -> tuple[str, bytes]:
     attributes = _blob(repo, commit, ".gitattributes", limit=64 * 1024).decode("utf-8")
-    if _ATTRIBUTE not in attributes.splitlines():
+    if f"{path} merge={PROGRESS_PROFILES[path]}" not in attributes.splitlines():
         raise ValueError("keyed merge protocol is not declared")
-    return attributes, _blob(repo, commit, PROGRESS_PATH)
+    return attributes, _blob(repo, commit, path)
 
 
 def independent_progress_scopes(
@@ -133,7 +136,10 @@ def independent_progress_scopes(
         for right in right_paths
         if left == right or left.startswith(right + "/") or right.startswith(left + "/")
     }
-    if overlaps != {(PROGRESS_PATH, PROGRESS_PATH)}:
+    if len(overlaps) != 1:
+        return False
+    path, other = next(iter(overlaps))
+    if path != other or path not in PROGRESS_PROFILES:
         return False
     if len(left_sources) > 8 or len(right_sources) > 8:
         return False
@@ -148,9 +154,9 @@ def independent_progress_scopes(
                 base = bases[0].decode("ascii")
                 if not _OID.fullmatch(base) or base in (left, right):
                     return False
-                attributes, original = _progress(repo, base)
-                left_attributes, left_document = _progress(repo, left)
-                right_attributes, right_document = _progress(repo, right)
+                attributes, original = _progress(repo, base, path)
+                left_attributes, left_document = _progress(repo, left, path)
+                right_attributes, right_document = _progress(repo, right, path)
                 if attributes != left_attributes or attributes != right_attributes:
                     return False
                 left_keys = _changed_keys(original, left_document)

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/lifecycle.py

@@ -77,6 +77,8 @@ from .models import (
 from .policy import load_policy
 from .preserved_cleanup import CONTRACT as PRESERVED_CLEANUP_CONTRACT
 from .preserved_cleanup import coverage, delete_preserved_state
+from .record_updates import updated_intent as _updated_intent
+from .record_updates import updated_record as _updated_record
 from .semantics import assert_record_version as _cas
 from .semantics import (
     attribution_base,
@@ -90,6 +92,8 @@ from .semantics import (
     path_scope_issues,
     publication_ref,
 )
+from .semantics import effective_intent_state as _effective_intent_state
+from .semantics import integration_reconciliation as _integration_reconciliation
 from .semantics import managed_record as _managed_record
 from .semantics import record_for as _record_for
 from .store import (
@@ -106,11 +110,9 @@ from .store import (
     RELEASE_RECEIPT_SCHEMA_VERSION,
     MetadataStore,
     integration_intent_from_dict,
-    integration_intent_to_dict,
     lifecycle_event_from_dict,
     new_record,
     now_iso,
-    record_from_dict,
     record_to_dict,
     release_intent_from_dict,
     release_intent_to_dict,
@@ -146,46 +148,6 @@ def _crash_point(name: str) -> None:
         os._exit(97)
 
 
-def _updated_record(record: MetadataRecord, event: str, **changes: Any) -> MetadataRecord:
-    payload = record_to_dict(record)
-    before = record.lifecycle
-    timestamp = now_iso()
-    payload.update(changes)
-    payload["record_version"] = record.record_version + 1
-    payload["last_reviewed_at"] = timestamp
-    history = list(record.history)
-    history.append(
-        {
-            "at": timestamp,
-            "event": event,
-            "from": before,
-            "to": payload.get("lifecycle", before),
-            "owner": payload.get("owner", record.owner),
-        }
-    )
-    payload["history"] = history
-    return record_from_dict(payload)
-
-
-def _updated_intent(intent: IntegrationIntent, event: str, **changes: Any) -> IntegrationIntent:
-    payload = integration_intent_to_dict(intent)
-    timestamp = now_iso()
-    payload.update(changes)
-    payload["updated_at"] = timestamp
-    history = list(intent.history)
-    history.append(
-        {
-            "at": timestamp,
-            "event": event,
-            "from": intent.state,
-            "to": payload.get("state", intent.state),
-            "candidate_oid": payload.get("candidate_oid"),
-        }
-    )
-    payload["history"] = history
-    return integration_intent_from_dict(payload)
-
-
 def _scope_digest(scope_paths: tuple[str, ...]) -> str:
     encoded = json.dumps(list(scope_paths), ensure_ascii=True, separators=(",", ":"))
     return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
@@ -211,28 +173,6 @@ def _scopes_overlap(left: tuple[str, ...], right: tuple[str, ...]) -> bool:
     return False
 
 
-def _integration_reconciliation(
-    snapshot: MetadataSnapshot, intent_id: str
-) -> IntegrationReconciliationReceipt | None:
-    matches = [
-        receipt
-        for receipt in snapshot.integration_reconciliation_receipts.values()
-        if receipt.intent_id == intent_id and receipt.result == "STALE_INTENT_TERMINAL_ACKNOWLEDGED"
-    ]
-    if len(matches) > 1:
-        raise ControllerError(
-            "INVALID_METADATA", "integration intent has multiple terminal reconciliations"
-        )
-    return matches[0] if matches else None
-
-
-def _effective_intent_state(snapshot: MetadataSnapshot, intent: IntegrationIntent) -> str:
-    receipt = _integration_reconciliation(snapshot, intent.intent_id)
-    if receipt is not None:
-        return receipt.effective_terminal_state
-    return "ABANDONED" if integration_intent_abandoned(intent) else intent.state
-
-
 def _released_intent_evidence(
     snapshot: MetadataSnapshot,
     intent: IntegrationIntent,

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/reconciler.py

@@ -20,7 +20,7 @@ from typing import Any
 
 from .controller import status
 from .git_backend import inventory
-from .lifecycle import _cancel_release_intents, _updated_record
+from .lifecycle import _cancel_release_intents
 from .models import (
     ControllerError,
     MetadataRecord,
@@ -28,6 +28,7 @@ from .models import (
     WriterReconciliationReceipt,
 )
 from .policy import load_policy
+from .record_updates import updated_record
 from .semantics import record_for as _record_for
 from .store import WRITER_RECEIPT_SCHEMA_VERSION, MetadataStore
 from .writer_lease import (
@@ -278,7 +279,7 @@ def reconcile_writers(
                     event="RECORD_CHANGED",
                     blocker="PARKED",
                 )
-                updated = _updated_record(record, "PARKED", lifecycle="RETAINED")
+                updated = updated_record(record, "PARKED", lifecycle="RETAINED")
                 store.replace_record(updated)
                 store.remove_writer_lease(record.allocation_id)
                 receipt = WriterReconciliationReceipt(

worktree_controller-1.32.2/src/worktree_controller/record_updates.py

@@ -0,0 +1,54 @@
+"""Versioned, history-preserving updates of allocation records and integration intents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .metadata_codec import (
+    integration_intent_from_dict,
+    integration_intent_to_dict,
+    record_from_dict,
+    record_to_dict,
+)
+from .models import IntegrationIntent, MetadataRecord
+from .store import now_iso
+
+
+def updated_record(record: MetadataRecord, event: str, **changes: Any) -> MetadataRecord:
+    payload = record_to_dict(record)
+    before = record.lifecycle
+    timestamp = now_iso()
+    payload.update(changes)
+    payload["record_version"] = record.record_version + 1
+    payload["last_reviewed_at"] = timestamp
+    history = list(record.history)
+    history.append(
+        {
+            "at": timestamp,
+            "event": event,
+            "from": before,
+            "to": payload.get("lifecycle", before),
+            "owner": payload.get("owner", record.owner),
+        }
+    )
+    payload["history"] = history
+    return record_from_dict(payload)
+
+
+def updated_intent(intent: IntegrationIntent, event: str, **changes: Any) -> IntegrationIntent:
+    payload = integration_intent_to_dict(intent)
+    timestamp = now_iso()
+    payload.update(changes)
+    payload["updated_at"] = timestamp
+    history = list(intent.history)
+    history.append(
+        {
+            "at": timestamp,
+            "event": event,
+            "from": intent.state,
+            "to": payload.get("state", intent.state),
+            "candidate_oid": payload.get("candidate_oid"),
+        }
+    )
+    payload["history"] = history
+    return integration_intent_from_dict(payload)

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/registration_prune.py

@@ -20,7 +20,6 @@ from .git_backend import (
     public_refs,
     worktree_content_fingerprint,
 )
-from .lifecycle import _updated_record
 from .models import (
     ControllerError,
     MetadataRecord,
@@ -29,6 +28,7 @@ from .models import (
     WorktreeGitState,
     WorktreePolicy,
 )
+from .record_updates import updated_record
 from .store import MetadataStore, now_iso
 
 CONTRACT = "registration-prune/v1"
@@ -343,7 +343,7 @@ def apply_prune(
         snapshot = store._load_unlocked()
         record = snapshot.records[journal["allocation_id"]]
         if record.record_version == journal["expected_record_version"]:
-            updated = _updated_record(
+            updated = updated_record(
                 record, "REGISTRATION_PRUNED", lifecycle="RELEASED", owner="unassigned"
             )
             store.replace_record(updated)

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/semantics.py

@@ -17,6 +17,7 @@ from .git_backend import (
 from .models import (
     ControllerError,
     IntegrationIntent,
+    IntegrationReconciliationReceipt,
     MetadataRecord,
     MetadataSnapshot,
     RepositoryInventory,
@@ -79,6 +80,29 @@ def integration_intent_abandoned(intent: IntegrationIntent) -> bool:
     )
 
 
+def integration_reconciliation(
+    snapshot: MetadataSnapshot, intent_id: str
+) -> IntegrationReconciliationReceipt | None:
+    matches = [
+        receipt
+        for receipt in snapshot.integration_reconciliation_receipts.values()
+        if receipt.intent_id == intent_id and receipt.result == "STALE_INTENT_TERMINAL_ACKNOWLEDGED"
+    ]
+    if len(matches) > 1:
+        raise ControllerError(
+            "INVALID_METADATA", "integration intent has multiple terminal reconciliations"
+        )
+    return matches[0] if matches else None
+
+
+def effective_intent_state(snapshot: MetadataSnapshot, intent: IntegrationIntent) -> str:
+    """Interpret terminal evidence from the caller's snapshot without changing authority."""
+    receipt = integration_reconciliation(snapshot, intent.intent_id)
+    if receipt is not None:
+        return receipt.effective_terminal_state
+    return "ABANDONED" if integration_intent_abandoned(intent) else intent.state
+
+
 def _current_attempt(intent: IntegrationIntent) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     """Split history at the last formal retry: (earlier attempts, current attempt)."""
     history = list(intent.history)

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/src/worktree_controller/tool_cli_contract.json

@@ -468,7 +468,7 @@
     "contract": "integration-keyed-document-scope/v1",
     "entry_points": "normal enqueue, claim, reconcile and retry scope checks",
     "identity": "original frozen source commits, scopes and queue sequence; no mutable checkout evidence",
-    "supported_document": "docs/handbook/business-progress.json, quant-platform schema 2, unchanged committed qp-handbook-progress merge profile",
+    "supported_document": "docs/nexus/business-progress.json with qp-nexus-progress, or historical docs/handbook/business-progress.json with qp-handbook-progress; quant-platform schema 2, unchanged committed merge profile",
     "proof": "unique non-ancestor merge base for every frozen source pair; whole-record changed keys must be disjoint across tasks.authority_key and development_lines/modules/decisions.id",
     "bounds": "at most 8 sources per intent, 2 MiB regular document blobs, 64 KiB attributes blobs",
     "fail_closed": "shared record, metadata/schema/order changes, broad paths, code overlap, duplicate keys, invalid/missing/oversized Git evidence, ancestry dependency, explicit prerequisite or earlier publishing/recovery/attention state",
@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.32.0",
+  "tool_version": "1.32.2",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,

{worktree_controller-1.32.0 → worktree_controller-1.32.2}/tool_cli_contract.json

@@ -468,7 +468,7 @@
     "contract": "integration-keyed-document-scope/v1",
     "entry_points": "normal enqueue, claim, reconcile and retry scope checks",
     "identity": "original frozen source commits, scopes and queue sequence; no mutable checkout evidence",
-    "supported_document": "docs/handbook/business-progress.json, quant-platform schema 2, unchanged committed qp-handbook-progress merge profile",
+    "supported_document": "docs/nexus/business-progress.json with qp-nexus-progress, or historical docs/handbook/business-progress.json with qp-handbook-progress; quant-platform schema 2, unchanged committed merge profile",
     "proof": "unique non-ancestor merge base for every frozen source pair; whole-record changed keys must be disjoint across tasks.authority_key and development_lines/modules/decisions.id",
     "bounds": "at most 8 sources per intent, 2 MiB regular document blobs, 64 KiB attributes blobs",
     "fail_closed": "shared record, metadata/schema/order changes, broad paths, code overlap, duplicate keys, invalid/missing/oversized Git evidence, ancestry dependency, explicit prerequisite or earlier publishing/recovery/attention state",
@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.32.0",
+  "tool_version": "1.32.2",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,