orbyn-worktree ยท diff
git:20261110.7bb26e4 to git:20261112.1d55984
72 added, 114 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: orbyn-worktree
description: "Manage local task branches, private contribution storage when supported and Git worktree isolation; use sibling <repo>-wt directories, purpose-based names and preservation before cleanup."
---
# Worktree ownership and lifecycle
Use this skill when a task needs checkout isolation, the user requests a worktree,
- or an existing worktree needs reconciliation/cleanup. The
- [workflow](../orbyn-workflow/SKILL.md) selects it from the ordinary task request,
- without a separate invocation. Follow the consuming project's instructions,
- requested checkout and host permissions. A small clear edit can stay in its
- current checkout.
+ or a worktree needs reconciliation/cleanup. The [workflow](../orbyn-workflow/SKILL.md)
+ selects it from the ordinary request. Follow the consuming project's instructions,
+ requested checkout and host permissions.
## Create a worktree by work mode
- Read the repository's `work mode` from `harness.py resolve` first. `simple`: no
- worktree; edit in the current checkout. `isolated`: one worktree per task. `parallel`:
- one worktree per active task, at most `max_active` at once, the rest queued. A small
- clear edit stays in the current checkout in every mode, and a chat instruction such
- as "just do it here" overrides the mode for that task. `parallel` leaves more trees
- to retire, so run the cleanup report at every closeout.
+ Read the repository's `work mode` from `harness.py resolve` first and follow the
+ [mode table](../orbyn-workflow/references/harness-settings.md#the-work-mode):
+ `simple` no worktree, `isolated` one per task, `parallel` one per active task with
+ at most `max_active`, the rest queued. A small clear edit stays in the current
+ checkout in every mode, and "just do it here" overrides the mode for that task.
+ In `parallel`, run the cleanup report at every closeout.
## Resolve the repository and owner first
- Inspect the current checkout, branch, HEAD, tracked/untracked changes and
- `git worktree list --porcelain`. Resolve the primary clone and common repository
- from Git registration and the task; the current directory may be a linked worktree.
- A linked worktree's `.git` is normally a pointer: do not treat it as an independent
- clone or derive another `-wt` root from it.
+ Inspect the current checkout, branch, HEAD, changes and `git worktree list --porcelain`.
+ Resolve the primary clone from Git registration; the current directory may be a
+ linked worktree (its `.git` is a pointer), so derive no other `-wt` root from it.
- Preserve unrelated changes and outputs. Do not stash, reset, switch another owner's
- checkout, copy dirty files or move existing worktrees merely to enforce this convention.
+ Preserve unrelated changes and outputs; do not stash, reset, switch another owner's
+ checkout, copy dirty files or move worktrees to enforce this convention.
## Reuse before cloning or replacing
- Before creating a checkout, inspect registered trees, canonical repository/remotes,
- host attachments and bindings, and any existing reference cache. Reuse a worktree
- only when its repository, task owner, branch, source and local work fit this task.
- Confirm that no active session still holds a clean directory before reusing it.
-
- Continue the same task/PR in its owned branch and checkout through review and
- corrections. Start a new independent task from the verified current default branch
- and a stack from its exact reviewed dependency. Do not use a historical task branch
- just because it is current, or create a clone per agent/day/retry.
+ Before creating a checkout, inspect registered trees, remotes, host attachments and
+ any reference cache. Reuse a worktree only when repository, owner, branch,
+ source and local work fit and no active session holds it. Continue a task/PR in its
+ owned branch; start independent work from the verified default branch and a stack
+ from its exact reviewed dependency; never reuse a historical branch because it is
+ current or create a clone per agent/day/retry.
## Sibling location and names
- For a primary clone `<parent>/<repo>`, the default root is its sibling
- `<parent>/<repo-slug>-wt/`. Use a stable lowercase hyphenated repo slug; reuse an
- existing established sibling root rather than creating a case-only alternative.
- Each worktree has one direct child directory named for its purpose slug, not the
- branch's slash-separated path:
-
- ```text
- orbyn-fullstack-skills/repo/
- orbyn/ primary clone
- orbyn-wt/
- task-rescheduling/ feat/task-rescheduling
- save-retry/ fix/save-retry
- worktree-policy/ chore/worktree-policy
- ```
-
- Targets use the library-root ignored `repo/` workspace by default under the
- [nested repository contract](../orbyn-setup/references/repository-workspaces.md):
- `orbyn-fullstack-skills/repo/widget` uses sibling `repo/widget-wt/<purpose>/`.
- An explicit user location or an established consuming-project policy wins.
-
- Use lowercase letters, digits and hyphens for a short directory slug, normally
- under 64 characters. Use neutral branch prefixes such as `feat/`, `fix/`, `chore/`,
- `docs/` or `refactor/`. Do not use agent, assistant, vendor or model branding in a
- new branch or directory name. Avoid path separators, traversal, spaces, Windows
- device names and case-only distinctions.
-
- Inspect collisions before choosing a name. If the existing path/branch is unrelated
- or still owned, choose a distinct purpose or a suffix such as `-2`; never overwrite
- a directory, reuse a foreign branch or use force to bypass Git's already-checked-out
- protection. Keep existing legacy paths/branch names intact.
+ The default root is the primary clone's sibling `<parent>/<repo-slug>-wt/`, with one
+ direct child per worktree named for its purpose slug, not the branch path; a target in the library's `repo/` workspace uses `repo/<target>-wt/<purpose>/`. An explicit user location or an
+ established project policy wins. Use neutral branch prefixes, no agent/vendor/model branding. Inspect collisions first; never overwrite a directory, reuse a
+ foreign branch or force past Git's already-checked-out protection; keep legacy paths
+ intact. Slugs, reuse and creation steps: [naming and creation](references/naming-and-creation.md).
## Keep task branches local and publish deliberately
- A worktree and its branch are local Git state; they need no branch on the company's
- remote. Reuse one owned task branch and worktree through implementation, correction
- and review instead of creating one per agent, phase or retry. Never push every
- delegate branch. Serialize operations on shared Git refs, remotes and configuration
- under one owner.
-
- Keep work local by default. Before any push, follow
- [contribution storage](references/contribution-storage.md). A local branch is
- recoverable only while its checkout/Git data remain; preserve valuable unpushed
- work before cleanup.
+ A worktree and its branch are local Git state and need no remote branch. Reuse one
+ owned branch and worktree through review, never one per agent, phase or retry; never
+ push every delegate branch. Serialize operations on shared Git refs, remotes
+ and configuration under one owner. Before any push, follow
+ [contribution storage](references/contribution-storage.md). Preserve valuable
+ unpushed work before cleanup; a local branch survives only with its checkout.
## Create and verify the selected checkout
- Resolve the requested base revision before writes. Continue an existing task/PR
- from its actual branch or reviewed commit. For new work, use the project's verified
- default branch/ref, not an unrelated current feature branch or a stale local `main`.
- Fetch only when available and authorized; label an offline/cached base as such.
-
- Create a **new** branch from a verified base with
- `git worktree add -b <branch> <path> <base>`. Reuse an existing branch with
- `worktree add <path> <branch>` only after ownership/checkout inspection. Avoid `-B`,
- `--force` and duplicate branch checkouts. Verify the final path, branch, base/HEAD
- and status before editing.
-
- Use the selected worktree as the working directory for every subsequent edit/check.
- After selecting or switching checkout, reread nested instructions and re-resolve
- search roots there under [action scope](../orbyn-setup/references/action-scope.md).
-
- Preserve project environment files; do not automatically copy secrets or run setup
- hooks from source. Worktrees share Git objects and may still share databases, ports,
- fixtures or external services: assign those separately.
-
+ Resolve the base before writes: continue a task/PR from its actual branch, start new
+ work from the verified default branch (not a stale local `main`). Fetch only when
+ available and authorized; label an offline/cached base as such. Create a branch with
+ `git worktree add -b <branch> <path> <base>`; reuse an existing branch only after
+ ownership inspection; avoid `-B`, `--force` and duplicate branch checkouts. Verify
+ path, branch, base/HEAD and status before editing, then use that worktree for every
+ edit/check. After selecting or switching checkout, reread nested instructions and
+ re-resolve search roots there ([action scope](../orbyn-setup/references/action-scope.md)).
+ Preserve project environment files; never copy secrets or run setup hooks from
+ source; assign shared databases, ports and services separately.
If the host denies Git metadata writes, preserve the patch and report delivery as
- blocked. Never rewrite `.git`, supply an alternate index or bypass the sandbox.
+ blocked; never rewrite `.git`, supply an alternate index or bypass the sandbox.
## Designate task verification
- Before expensive runs, use the CI owner's [feature-worktree gates](../orbyn-ci-design/references/change-scope.md#designate-gates-for-the-feature-worktree).
- Name focused checks, exclusions and conditions for widening in the existing task
- brief. A new worktree adds no entire-app suite, hosted CI or deployment.
+ Before expensive runs, name focused checks, exclusions and widening conditions in the
+ task brief ([feature-worktree gates](../orbyn-ci-design/references/change-scope.md#designate-gates-for-the-feature-worktree)).
+ A new worktree adds no entire-app suite, hosted CI or deployment.
## Preserve before cleanup
- For Windows paths and capabilities, read [native retirement](references/task-closeout.md#windows-retirement).
-
At delivery, follow [task closeout](references/task-closeout.md): reconcile source,
- commit, push, PR and resources; record retention reasons/review triggers and assess
- exact-path retirement separately from permission to remove it.
+ commit, push, PR and resources, record retention reasons/review triggers and assess
+ exact-path retirement separately from permission to remove it (Windows:
+ [native retirement](references/task-closeout.md#windows-retirement)).
Never delete another owner's work; unknown ownership means hold. A squash merge or
clean status alone does not clear a tree for removal. Retire a tree only through
- `worktree_retire.py`, which moves the whole folder to the system Trash and then clears
- that one Git registration (a restored folder is files only). `apply` proves only
- what the report shows: landing, a clean tree, no hidden changes, nothing open and no
- hold. The owning task or a person still judges ownership, dependent work, shared
- resources, live previews and recovery, and records any open question as a `HOLD.json`.
- A refusal has no automatic force fallback; local/remote ref deletion and tracking
- prune remain separate.
+ `worktree_retire.py` (whole folder to the system Trash, then that one Git registration
+ cleared). Its `apply` proves only landing, a clean tree, no hidden changes, nothing open and no hold; the owner still
+ judges the rest ([retirement gate](references/task-closeout.md#retirement-gate-for-an-exact-path-or-ref)).
+ A refusal has no automatic force fallback; ref deletion and tracking prune stay separate.
After a merge, [retire the worktree in the same closeout](references/task-closeout.md#retire-at-delivery)
- when you have cleanup authority: the tool moves the whole folder, ignored files
- included, to the Trash, so never hand-run `git worktree remove` on a live tree, which deletes them.
- Keep a merged tree only with a named reason and
- review event, recorded in a `HOLD.json` at its root. At closeout, before creating a
- worktree and when `harness.py resolve` reports low disk, [run the workspace cleanup](references/task-closeout.md#clean-the-workspace):
- `worktree_retire.py report`, then `apply`. It trashes only finished worktrees, rebuildable
- caches and idle output, archive and references; everything else in `repo/` is report-only.
+ when you have cleanup authority; never hand-run `git worktree remove` on a live tree,
+ which deletes ignored files. Keep a merged tree only with a named reason and review
+ event in a `HOLD.json`. At closeout, before creating a worktree and on low disk, [run workspace cleanup](references/task-closeout.md#clean-the-workspace)
+ (`worktree_retire.py report`, then `apply`). It trashes only finished worktrees,
+ rebuildable caches and idle output, archive and references; everything else in
+ `repo/` is report-only.
- Return the selected path/base/head, verified delivery state, retained resources,
- recovery pointers and actual closeout disposition. A dry run changes nothing.
+ ### Worked failure
+ PR 17 merged by squash, but its tree has a later local commit, ignored review
+ captures and a live preview. Treating the merged badge, a clean status or ancestry as
+ proof it is disposable cache is the failure: keep the later source and a verified
+ evidence package, check dependent work and get the owner's release first
+ ([closeout example](references/task-closeout.md#synthetic-closeout-example)).
+
+ Return the path/base/head, verified delivery state, retained resources, recovery
+ pointers and closeout disposition.
+
## Read when needed
- - Pushing, forks, private storage, backups or a public PR: [contribution storage](references/contribution-storage.md).
- - Recloning, replacing a checkout or an empty partial cache: [checkout replacement](references/checkout-replacement.md).
- - In-place, external or bare layouts, delegate branches, unattended runs, denied metadata writes, required dirty primary changes, host worktree tools, search results from another checkout, required statuses at delivery or a worked command example: [checkout setup](references/checkout-setup.md).
- - Preview/evidence storage, server/volume ownership or retention classes: [artifact lifecycle](../orbyn-workflow/references/artifact-lifecycle.md).
+ - Push, fork, private storage, backup or public PR: [contribution storage](references/contribution-storage.md).
+ - Reclone, replace a checkout or empty partial cache: [checkout replacement](references/checkout-replacement.md).
+ - Layouts other than nested, delegate branches, unattended runs, dirty primary changes, host worktree tools, another checkout's search results, delivery statuses, a worked command: [checkout setup](references/checkout-setup.md).
+ - Preview/evidence storage, servers, retention classes: [artifact lifecycle](../orbyn-workflow/references/artifact-lifecycle.md).