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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.30.5
+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.5 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.31.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -32,14 +32,16 @@ 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.5
+python -m pip install worktree-controller==1.31.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
 
 WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
-Software version 1.30.5 retains CLI contract **60** and storage layout **5**.
+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.31.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -48,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.5
+git checkout v1.31.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -63,6 +65,17 @@ The [getting started guide](https://github.com/xuanheng-tech/worktree-controller
 explains the output and how to proceed to tasks that change files. The example also ships in the
 source distribution; it requires only WC and Git, with no companion delivery tools.
 
+To actually change a file, publish to a local bare remote, integrate and recover a paused task,
+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.
@@ -74,7 +87,8 @@ for task admission, writer identity, handoff, integration and safe release.
 WC manages checkout authority and lifecycle. It does not implement your task, commit changes or
 publish a branch. Real handoff and integration flows use separate delivery evidence from
 [Git Finalizer](https://github.com/xuanheng-tech/git-finalizer).
-Context Loader and Snapshot Runner are optional companion tools; see
+Context Loader and the maintenance checker are optional. The complete integration example uses
+Snapshot Runner for the explicit review receipts required by its policy; see
 [optional integrations](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md#optional-integrations-and-dependencies).
 
 When blocked, run `worktree-controller recovery-guide --repo /path/to/repo --path /path/to/checkout --json`
@@ -90,6 +104,7 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [Architecture](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/architecture.md)
 - [Exact CLI and capability contract](https://github.com/xuanheng-tech/worktree-controller/blob/main/tool_cli_contract.json)
 - [Changelog](https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md)
+- [Publishing and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/publishing.md)
 - [Releases](https://github.com/xuanheng-tech/worktree-controller/releases) · [PyPI](https://pypi.org/project/worktree-controller/)
 - [Report a bug](https://github.com/xuanheng-tech/worktree-controller/issues) · [Contribute](https://github.com/xuanheng-tech/worktree-controller/blob/main/CONTRIBUTING.md)
 - [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)

{worktree_controller-1.30.5 → 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.5 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.31.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -15,14 +15,16 @@ 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.5
+python -m pip install worktree-controller==1.31.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
 
 WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
-Software version 1.30.5 retains CLI contract **60** and storage layout **5**.
+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.31.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -31,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.5
+git checkout v1.31.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -46,6 +48,17 @@ The [getting started guide](https://github.com/xuanheng-tech/worktree-controller
 explains the output and how to proceed to tasks that change files. The example also ships in the
 source distribution; it requires only WC and Git, with no companion delivery tools.
 
+To actually change a file, publish to a local bare remote, integrate and recover a paused task,
+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.
@@ -57,7 +70,8 @@ for task admission, writer identity, handoff, integration and safe release.
 WC manages checkout authority and lifecycle. It does not implement your task, commit changes or
 publish a branch. Real handoff and integration flows use separate delivery evidence from
 [Git Finalizer](https://github.com/xuanheng-tech/git-finalizer).
-Context Loader and Snapshot Runner are optional companion tools; see
+Context Loader and the maintenance checker are optional. The complete integration example uses
+Snapshot Runner for the explicit review receipts required by its policy; see
 [optional integrations](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md#optional-integrations-and-dependencies).
 
 When blocked, run `worktree-controller recovery-guide --repo /path/to/repo --path /path/to/checkout --json`
@@ -73,6 +87,7 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [Architecture](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/architecture.md)
 - [Exact CLI and capability contract](https://github.com/xuanheng-tech/worktree-controller/blob/main/tool_cli_contract.json)
 - [Changelog](https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md)
+- [Publishing and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/publishing.md)
 - [Releases](https://github.com/xuanheng-tech/worktree-controller/releases) · [PyPI](https://pypi.org/project/worktree-controller/)
 - [Report a bug](https://github.com/xuanheng-tech/worktree-controller/issues) · [Contribute](https://github.com/xuanheng-tech/worktree-controller/blob/main/CONTRIBUTING.md)
 - [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)

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.31.0/docs/first-change.md

@@ -0,0 +1,144 @@
+# Deliver your first change
+
+This example changes one README, commits and publishes its branch through Git Finalizer, hands
+it off to WC, reviews and validates an integration candidate, and publishes local main. It can
+pause after handoff and continue in a new process with the original task and integration request.
+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
+the [README](../README.md#install). On Ubuntu, a Python installation without `ensurepip` also
+needs its distribution's `python3.12-venv` package before `python3.12 -m venv` can work.
+
+This complete delivery example also uses these public tools:
+
+- [Git Finalizer 1.9.3](https://github.com/xuanheng-tech/git-finalizer#installation): download its
+  published release tarball and checksum file, verify them, and keep all `git-finalize*` companions
+  together as its installation instructions describe. It is not a PyPI package.
+- [Snapshot Runner 2.5.11](https://github.com/xuanheng-tech/snapshot-runner#requirements-and-installation):
+  install its PyPI package in a separate virtual environment. Its own interpreter needs
+  Python 3.12.13 or a later supported version; using Python 3.12.13+ for both environments meets
+  WC's Python 3.12 requirement too. WC's core Python requirement is unchanged.
+
+For example, with a suitable Python 3.12 already installed and a new `runner-venv` path:
+
+```bash
+python3.12 --version
+python3.12 -m venv /absolute/path/to/runner-venv
+/absolute/path/to/runner-venv/bin/python -m pip install 'snapshot-runner==2.5.11'
+```
+
+Use the WC environment's Python to run the example. Pass the two installed entrypoints
+explicitly, or put their directories on PATH. `tool-skill-sync`, Context Loader, agent clients,
+model APIs and personal Skills are not required by this example.
+
+WC policy schema 4 and newer requires separate explicit **test and Snapshot receipt identities**
+at `integration-validate`. The example creates real Snapshot Runner artifacts and reads their
+README evidence; it checks the expected README content and clean candidate separately. A tool's
+successful evidence collection alone is not a passed test or code review. No fake receipt, lowered
+policy version or changed Controller state is used.
+
+## Run the whole task
+
+From this release's source checkout, with the WC environment active:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-first-change" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner
+```
+
+The workspace path must be new and its parent must exist. The script refuses an existing path
+without changing it. The source archive includes both `change_task.py` and its neighboring
+`quickstart.py`; keep them together. Missing tools are refused before the workspace is created.
+
+`PASS` means all of the following were checked:
+
+1. The admitted feature's real writer passed the write guard before changing `README.md`.
+2. The exact file scope was reviewed, committed and published to the local remote with Finalizer.
+3. The writer ended and its exact commit was handed off, then queued and claimed through WC.
+4. Tests and Snapshot evidence were bound to the candidate before its main-publication lease.
+5. Finalizer and WC independently verified the published commit; WC released both linked checkouts.
+6. Canonical main was refreshed, the delivered README was checked, strict closeout proof covered
+   both known allocations, and `doctor` passed.
+
+The example intentionally changes only a known text file, so its content review is narrow and
+deterministic. Real application changes need their own tests and appropriate review.
+This local demonstration does not authorize a hosted publication or production deployment.
+
+## Pause and resume the same task
+
+Use a different new workspace for this exercise:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-change-resume" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner \
+  --pause-after-handoff
+```
+
+The output is **`PAUSED`**, not `PASS`. The change and its branch have reached the local remote,
+the feature writer is released, and `handoff.json` records the original task's source, repository
+and integration identities. The integration is queued, with no candidate checkout yet.
+The preserved source is still awaiting integration; this is not completed business work.
+
+Run in a new process with the **same** workspace and installed tools:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-change-resume" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner --resume
+```
+
+Resume checks the existing repository, local remote, source identity and uncommitted files. It
+claims the original queued intent, or observes the same unchanged claimed candidate. It does not
+create another task, replace source evidence, reset a branch or delete unknown files. Repeating
+resume after verified completion only rechecks the delivered result and closeout evidence.
+
+## Inspect a failure and keep the evidence
+
+Every command's actual exit code, stdout and stderr is saved in `commands.jsonl`. The workspace
+also retains Finalizer receipts, Snapshot summaries and artifacts, content-check results, branches,
+the local remote and final `closeout.json`. Linked checkouts are removed only through WC.
+
+An unexpected refusal stops with nonzero exit status and preserves the current result. This
+example's resume entry covers queued or unchanged claimed handoffs and verified completion;
+it is not a general crash-recovery engine. For a different interruption point, unknown files,
+identity drift or a publication in progress, inspect the saved command and the formal
+[recovery guidance](operations.md#recovery-guidance-and-session-closeout). Do not rerun without
+`--resume` into an old workspace or clear metadata to make the example continue.
+
+The isolated state is under the workspace's `home/`. For inspection, activate the WC environment
+and use the actual workspace path:
+
+```bash
+workspace="$HOME/wc-change-resume"
+HOME="$workspace/home" XDG_STATE_HOME="$workspace/home/.local/state" \
+  worktree-controller status --repo "$workspace/main" --json
+```
+
+Use the original `intent_id` from `handoff.json` with `recovery-guide --intent-id` even after a
+checkout is released. Follow each returned owner/CAS step and reobserve. `doctor PASS` and an
+observation command's exit 0 do not prove recovery, integration or task completion.
+
+## Repeat the regression as a contributor
+
+The default test suite checks refusal of existing workspaces and missing prerequisites. The real
+cross-tool regression is explicit opt-in, runs entirely against temporary local repositories,
+and covers unknown-file preservation, source drift, pause/resume and completed replay:
+
+```bash
+WC_DEMO_FINALIZER=/absolute/path/to/git-finalize \
+WC_DEMO_SNAPSHOT_RUNNER=/absolute/path/to/runner-venv/bin/snapshot-runner \
+  uv run --locked --python 3.12 --no-env-file python -m pytest -q tests/test_change_task.py \
+  -p no:cacheprovider --basetemp /absolute/path/to/a/new/demo-pytest
+```
+
+Install the contributor environment as described in [CONTRIBUTING](../CONTRIBUTING.md). Without
+both opt-in entrypoints, the cross-tool case is skipped; a skipped case is not acceptance evidence.

{worktree_controller-1.30.5 → worktree_controller-1.31.0}/docs/getting-started.md

@@ -63,9 +63,10 @@ not establish completion.
 
 The example deliberately performs a genuine no-change inspection, so `complete-no-change` is
 appropriate. A task that edits files or creates commits must preserve or deliver that work;
-it cannot use this shortcut. See the [operations guide](operations.md) for the existing
-handoff, integration and recovery contracts and [Git Finalizer](https://github.com/xuanheng-tech/git-finalizer)
-for delivery evidence. WC itself does not commit, push or approve a production release.
+it cannot use this shortcut. Follow [your first change](first-change.md) for an executable local
+commit, handoff, integration and pause/resume example with public companion tools. See the
+[operations guide](operations.md) for the existing contracts. WC itself does not commit, push
+or approve a production release.
 
 For real session closeout, pass the complete recorded selector (`--client-id`, `--session-id`,
 `--run-id` when present, and `--holder`) and every known `--expected-allocation-id` to

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

@@ -7,8 +7,19 @@ the [getting started guide](getting-started.md) provides an isolated first run.
 
 ## Start or resume development
 
-1. Run `tool-skill-sync doctor --repo <checkout> --summary`, then Controller `status --json`.
+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
+uses the public Snapshot Runner package. Context Loader and `tool-skill-sync` are optional.
+
+1. Run Controller `--version`, `capabilities --json`, `status --json` and `doctor --json`.
    Read the selected repository policy and distinguish installed runtime from source candidates.
+   If your site installed the optional maintenance checker, also run
+   `tool-skill-sync doctor --repo <checkout> --summary` for its tool/Skill pairing checks.
 2. Use `plan` for the existing task/authority. Reuse its allocation when supported; otherwise use
    `acquire` with explicit owner, branch, base and scope. A waiting request is not an allocation.
 3. Bind the real writer process and session/run through `writer-session` or `writer-lease-acquire`.

worktree_controller-1.31.0/docs/publishing.md

@@ -0,0 +1,104 @@
+# Publishing WC packages
+
+The `Publish release` workflow in `.github/workflows/release.yml` releases an existing stable tag
+that is already integrated into public `main`. It does not create tags, commit, merge or push Git
+branches. Source delivery continues to use the repository's Controller and Git Finalizer flow.
+The software version, CLI contract and storage layout remain independently versioned.
+
+## One-time setup
+
+The repository uses a GitHub environment named **`pypi`**, restricted to workflow runs from **main**.
+The environment grants no additional review exemption. Keep any existing platform protections.
+
+In the PyPI project's **Manage → Publishing → Add a new publisher → GitHub** form, register:
+
+| Field | Exact value |
+| --- | --- |
+| PyPI project | `worktree-controller` |
+| Owner | `xuanheng-tech` |
+| Repository | `worktree-controller` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+The owner completes this authenticated PyPI account step. Do not put a long-lived PyPI token in
+GitHub secrets. The workflow uses `uv publish --trusted-publishing always`: an unavailable or
+mismatched publisher fails rather than falling back to another credential. Existing local
+credentials are not read, copied, revoked or changed by this workflow.
+
+See [PyPI's publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) and
+[uv's GitHub integration](https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi).
+
+## Audit an existing release
+
+Run from an authenticated GitHub CLI with access to the public repository:
+
+```bash
+gh workflow run release.yml --repo xuanheng-tech/worktree-controller --ref main \
+  -f tag=v1.30.5 -F publish=false
+```
+
+This checks and builds the exact tag in a job with read-only repository permissions. Automation
+comes from the immutable workflow commit; the payload is checked out separately at its tag.
+The workflow records a manifest and checksums and audits the existing GitHub/PyPI inventory.
+For an already published release, it also downloads and installs both distributions in fresh
+environments and runs the onboarding example shipped in the source archive.
+
+For an unpublished tag, audit reports the missing remote files and skips post-publication
+installation. A successful audit is preparation evidence, not proof of a new publication or a
+successful OIDC upload. WC's packaged onboarding contract introduced in 1.30.5 is required.
+
+## Publish a real version
+
+After the actual source change and version update have been validated and integrated, create and
+publish its exact stable version tag through the normal release process. Then trigger once:
+
+```bash
+gh workflow run release.yml --repo xuanheng-tech/worktree-controller --ref main \
+  -f tag=vX.Y.Z -F publish=true
+```
+
+Replace `vX.Y.Z` with that existing tag. The tag must exactly match `pyproject.toml` and the CLI
+contract's software version. A tag outside main, a moved tag, dirty source, unknown file or
+checksum mismatch stops the workflow. No force operation or Controller-state edit is used.
+
+The workflow performs these stages:
+
+1. Run `scripts/check-project` on the tag: lint, full default suite, wheel/sdist build, sdist
+   rebuild and installed checks. Freeze one authoritative wheel/sdist pair in an immutable run
+   artifact. Rebuilding the sdist for validation does not replace that pair.
+2. With publishing permissions, recheck the source identity and both remote inventories. Store
+   the exact pair and SHA256SUMS in a GitHub draft, upload only missing PyPI files using short-lived
+   publishing credentials, verify the registry, and make the matching GitHub release public.
+   Building or installing package code never runs in this privileged job.
+3. In a separate job without publishing permissions, independently download both PyPI files,
+   compare their hashes, install them with fresh caches, verify metadata and all three CLI entry
+   points, and run the source archive's onboarding example. A short bounded retry handles a newly
+   uploaded version missing from the package index; functional failures are not retried.
+
+## Recover a failed or interrupted run
+
+Inspect the failing step and its real exit code. A nonzero uploader exit remains a failed step,
+even if a file reached the server. The GitHub draft and immutable Actions artifact retain the
+original bytes. Resolve the stated blocker and use **Re-run failed jobs** in that same run:
+
+```bash
+gh run rerun RUN_ID --failed --repo xuanheng-tech/worktree-controller
+```
+
+The publish job consumes the successful build job's original artifact name, including its original
+run attempt. It checks already uploaded bytes, uploads only missing files, and never uses
+`--clobber` or blindly skips an existing PyPI filename. An already complete matching release is
+observed without another upload. Unknown assets, yanked files, identity drift and different bytes
+remain blocked; do not delete or replace them to make a retry pass.
+
+A repository-wide workflow concurrency group serializes release runs without interrupting an
+active publisher. GitHub retains only one pending run per concurrency group, so use failed-job
+recovery instead of submitting a queue of duplicate dispatches. Bundles and check evidence have
+90-day retention. Once an artifact expires, a new run must build and validate again; if its bytes
+differ from existing remote files, it stops and requires review of the retained original evidence.
+It never overwrites the old release.
+
+Receipts distinguish a read-only audit, `PUBLISHED_VERIFIED`, and `FRESH_INSTALLS_VERIFIED`.
+Skipped tests remain skipped. Local installation or activation of a maintainer's WC runtime is a
+separate operation; publishing a package does not update that runtime or authorize a production
+release in any repository governed by WC.

{worktree_controller-1.30.5 → 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.
@@ -7,14 +10,17 @@ The [CLI contract](../tool_cli_contract.json) is authoritative for exact interfa
 ## Optional integrations and dependencies
 
 The core control plane has a single runtime dependency (`websockets>=15,<16`) and works standalone
-against any local Git repository on the supported platform. Everything below is optional and is
-exercised only when the corresponding context or companion tool is present:
+against any local Git repository on the supported platform. The integrations below are optional
+for core inspection/allocation; selecting a delivery flow can add explicit evidence requirements:
 
 - **Companion delivery tools.** WC composes with, but does not require or embed, the separate
   **Context Loader** (context reading), **Snapshot Runner** (read-only review evidence) and
   **Git Finalizer** (commit and publication). Each owns its own authority; WC never merges,
   publishes or commits on their behalf. The handoff and integration flows in
   [docs/operations.md](operations.md) assume Git Finalizer is installed for delivery evidence.
+  Policy schema 4+ also requires explicit test and Snapshot receipt identities for preparation;
+  [your first change](first-change.md) uses the public Snapshot Runner package to produce them.
+  Context Loader and the optional maintenance checker are not required by that example.
 - **Client-specific recovery.** The `archived_codex_binding_recovery_version` capability
   (`--recover-archived-codex-session`) recovers a released writer lease whose original session
   belonged to the Codex CLI client, by verifying that client's own archived-session and