git-worktree-recovery

Git Worktree Recovery

Recover the pointer only after proving that Git state is already safe. Resolve $PLUGIN_ROOT from the host's plugin-root variable when defined; otherwise use the absolute path of this skill folder's ../...

Read $PLUGIN_ROOT/skills/git-worktree-recovery/references/recovery-contract.md before interpreting salvage evidence or authorizing repair.

Safety Boundary

• Start with audit; it is the default mode and performs only allowlisted read-only Git inspection.
• Treat a live refs/heads/... ref containing every expected commit as repair authority. Reflog-only or object-only retention is salvage evidence, never authority to repoint a convenience link.
• Require one unique registered replacement with the exact symbolic branch, HEAD equal to the live branch ref, a clean porcelain-v2 status including untracked files whose branch.oid and branch.head headers still equal that HEAD and requested short branch, no in-progress Git operation, and no locked or prunable annotation. Require at least one canonical full expected commit ID whose object type is directly commit.
• Do not infer writer ownership from a worktree lock or a clean checkout.
• Treat ref, reflog, and object evidence as committed-history evidence only. Uncommitted, untracked, or ignored content from a missing target cannot be proven or recovered; report that limit and never call pointer repair content recovery.
• Repair only a verified broken symlink outside the common Git directory and every registered worktree, after explicit authorization. Never overwrite a regular file, directory, live symlink target, missing pointer, or link whose raw target changed after audit.
• Never create, add, move, remove, prune, repair, unlock, or delete worktrees; restore or update refs; check out, reset, switch, rebase, or restack branches; recursively delete paths; or execute a shell.
• Raw absolute paths remain present in command arguments and local filesystem access, but are omitted from JSON. The helper emits path digests, stable state codes, full object IDs, and bounded fingerprints instead.
• Audit is host-neutral. Repair is limited to POSIX runtimes that feature-prove directory-relative no-follow inspection and atomic replacement; unsupported hosts remain read-only.

Workflow

1. Read repository policy and identify a surviving checkout from the same repository, the full refs/heads/... ref, the registered replacement directory, the convenience link, and any full expected commit IDs.
2. Run the read-only audit with the exact current raw link target and proposed new raw target. Relative symlink targets are resolved from the link parent.
3. Accept ready only when authority is repoint and every Git, worktree, cleanliness, link, and target gate passes. salvage-only, blocked, or an evidence error is a stop condition.
4. If pointer repair is authorized, pass the unchanged audit fingerprint to repair-link. The helper re-audits immediately, compares the fingerprint and raw target, replaces only the exact symlink, then proves relevant Git state remained unchanged.
5. Re-run audit independently and report the final link state, branch/ref object ID, Git fingerprint, and any remaining stop condition.

Read-only audit:

python3 "$PLUGIN_ROOT/scripts/git_worktree_recovery_guard.py" \
  --repo /path/to/surviving-checkout \
  --branch-ref refs/heads/example-branch \
  --replacement /path/to/registered-replacement \
  --link /path/to/convenience-link \
  --expected-old-target ../missing-checkout \
  --new-target ../registered-replacement \
  --expected-commit 0123456789abcdef0123456789abcdef01234567

Separately authorized repair:

python3 "$PLUGIN_ROOT/scripts/git_worktree_recovery_guard.py" \
  --mode repair-link \
  --repo /path/to/surviving-checkout \
  --branch-ref refs/heads/example-branch \
  --replacement /path/to/registered-replacement \
  --link /path/to/convenience-link \
  --expected-old-target ../missing-checkout \
  --new-target ../registered-replacement \
  --expected-commit 0123456789abcdef0123456789abcdef01234567 \
  --expected-fingerprint AUDIT_FINGERPRINT \
  --apply

Exit 0 means ready, noop, or repaired; exit 2 is a safety refusal; exit 1 means malformed input or unavailable evidence. A successful repair is pointer-only proof, not permission for any later Git or delivery mutation.