/operations-worktree

name: operations-worktree
description: Create managed Git worktrees from a verified healthy owner, verify dependency reuse, and report explicit checkout and recovery outcomes.
license: MIT
metadata:
  source: "https://github.com/vincentkoc/dotskills"

Operations Worktree

Purpose

Create and manage worktrees safely and consistently across projects while avoiding stale branch bases.

When to use

• You need a new task branch in a new worktree.
• You are juggling many concurrent worktrees.
• You need to avoid branching from stale local `main` or local `HEAD`.

Workflow

1. Identify the producer: shell GWT, a repository-native wrapper, or an application that owns sessions or sandbox projections. Resolve the repository identity, canonical owning checkout, Git common directory, and existing worktree registrations. A `.git` entry does not make an application-owned workspace a personal GWT task; preserve its native allocation, relocation and retention lifecycle. Preserve dirty owner state. Read the repository's worktree and dependency rules. 2. Inspect existing worktrees before creating another checkout. Reuse an existing task-owned worktree only when its identity, branch, and ownership match. Do not adopt another session's checkout. 3. Use a healthy owning checkout accepted by the installed wrapper. An unsafe, shallow, or promisor source is not permission to create an ad hoc clone. Do not bypass worktree creation with raw Git, copied repositories, or temporary clones. A refusal stops creation, not diagnosis. Repair that same verified owner within existing task authorization, then let the wrapper recheck it. Report the concrete blocker if no qualified owner is available. 4. Use `gwt help` for discovery and `gwt root` to resolve the configured managed root. Keep new worktrees under that root or a repository-native managed root. Do not place new checkouts in arbitrary sibling or temporary directories. For server placement policy, use the existing account-specific `DOTFILES_WORKTREES_ROOT` setting; preserve unrelated workstation defaults. Check the host policy, actual account homes, physical path, mount and permissions separately: `gwt root` reports a value, not an access boundary. Changing this setting neither relocates existing work nor controls application allocators. Use the native owner to update registrations and persisted references; do not substitute shell GWT for an application's workspace lifecycle. 5. Verify the download policy before any fetch. Task-required additive fetch or unshallow is not GC, repacking, pruning, or owner consolidation. Recheck current state; do not repeat completed repair or ask again for an already authorized step. Respect contention, suppress automatic maintenance/pruning, and preserve local branches, HEAD/index, patches, and registrations. Distinguish a verified current remote base from a cached local ref. Cached refs do not prove the latest head. When freshness cannot be verified, report that gap rather than silently substituting a stale base. 6. Before creation, choose the repository-prescribed, documented closeout route supported on this host.

• Use `gwt new <branch> <start-point> --finish-managed` when required, requested, or supported by a qualified closeout route.

An advertised flag alone does not qualify that route. The start-point is optional. Keep the runtime `CODEX_THREAD_ID`. Outside Codex, set a stable task-specific `GWT_OWNER_ID` before creation.

• Where repository policy permits, use ordinary `gwt new <branch> <start-point>` from the verified owner and configured root.

Preserve its normal ownership, recovery, and non-force removal guards.

• Repository-native wrappers use their documented creation and closeout commands.

Finish enrollment is optional and creation-only. It records ownership and does not authorize removal. It is not a prerequisite for development, maintainer work, or ordinary authorized cleanup; keep repository-native lifecycles independent. Never unenroll, recreate, relocate, or adopt an existing managed tree to bypass its record. Stop creation if the wrapper is unavailable or still refuses the repaired owner. Do not substitute an unrestricted raw-Git creation route. 7. Verify the returned path, managed root, registration, owner, branch, and HEAD. For personal finish, confirm enrollment with `gwt finish-status` before starting work. 8. Verify dependency reuse under [Dependency Ownership](#dependency-ownership). 9. Read `references/task-artifacts.md` before work that retains evidence, publishes expensive artifacts, or needs a resumable phase/blocker receipt. 10. For OpenClaw, use its current `AGENTS.md` and native review/release lifecycle helpers. Do not override their exact-head or evidence rules here. 11. Finish with the explicit [Closeout](#closeout) result.

Dependency Ownership

Inspect the source pin and actual installed package-manager metadata separately. Verify lockfile compatibility, workspace dependency graph, patches, platform, linker layout, and resolved dependency paths before reuse. A matching store path or package-manager major version does not prove compatibility. Do not assume a root dependency symlink supplies every workspace package.

APFS copy-on-write package imports can share storage without sharing a Git checkout. They are not Git snapshots, worktree creation, or cleanup. Do not infer physical reclaim from logical dependency sizes. Inspect the installed package manager's contract before applying an APFS optimization.

Follow the repository and user dependency rules, existing authorization, and shared-symlink guards. If the install is incompatible or missing, use the repository's approved proof route. Do not add a new approval requirement for dependency work already authorized by that route.

Closeout

Report the exact task-owned path, branch, HEAD, owner,