Git Safety Net

Prevent losing work in a tangle of branches/stashes/rebases, and recover it forensically when something already went sideways. The commands here are all non-destructive or additive until a step is explicitly labeled destructive — recovery must never make the loss worse.

Outcome contract — keep the safety net subordinate to the user's job

Before Mode B/E or any command that writes a ref or backup, state the following in the conversation (do not create another file):

• Outcome: the user-visible end state, in the user's words.
• Current phase: what is authorized now. "Later" work is not authorized in this phase.
• Authorized targets: named objects this phase may inspect, plus the subset it may change.
• Stop condition: observable facts that end the task.

Then enforce these boundaries:

• Evidence scope is not action scope. A read-only audit may discover another clone, ref, repository, or dangling object. That discovery may widen the report; it does not authorize preserving, uploading, merging, deleting, or otherwise changing the newly found object.
• Authorization is object-specific, not repository-wide by implication. "Take over", "continue", or "finish the cleanup" applies only to the checkout/ref/PR the user identified. A collaborator-owned worktree, branch, or PR discovered later stays report-only until the user names it as a change target. If the user says to leave it alone, record that exclusion and do not inspect its working-tree contents, back it up, merge it, unlock/remove it, or mutate its refs.
• Preserve the smallest set threatened by the next authorized destructive action. If the current phase is only commit/push/verify and no deletion, reset, gc, history rewrite, or worktree removal is authorized, do not create an all-refs bundle or pin every dangler.
• Classify an artifact before choosing its transport. Durable project source follows the repository's normal Git/LFS policy. A temporary recovery artifact (bundle, working-tree diff, snapshot, transport chunk) belongs in a repository-external backup directory. Do not stage, commit, push, or route it through Git LFS merely to make the backup remote; Git LFS is for durable versioned project binaries, not a fallback transport for temporary recovery material.
• Keep preservation and retirement as separate phases. A verified recovery artifact proves recoverability; it does not prove the business code landed. Keep it through the destructive action and the content-level postconditions. Retire an exact task-owned temporary artifact only when every payload is landed or proven superseded and the artifact itself has explicit cleanup authorization. Keep backup-only, unresolved, and mixed artifacts.
• Treat a new storage or execution surface as a scope change. A second repository, new remote, cloud upload, Git LFS, or full-history export requires re-planning and explicit authority when the stated outcome actually depends on it. Do not solve a transport problem the user did not ask to create.
• Prove completion in the user's world. A remote containing the intended commit, preserved WIP, and the requested branch/worktree state are outcomes. Bundle counts, checksums, upload receipts, and audit breadth are supporting evidence, never substitutes for that outcome. Stop when the contract is satisfied; record unrelated findings separately without acting on them.

Entry router — pick the mode from what the user is worried about

When in doubt, run the smallest read-only probe that selects a mode. Use Mode B Step 0's machine-wide discovery only when the outcome is an exhaustive loss audit or the target checkout is unknown. A named repository/branch/worktree task stays named; findings outside that target are report-only until the user expands the authorized targets.

Load-bearing rules (internalize these; the modes apply them)

1. Get the EVIDENCE SCOPE right before you trust any verdict, without silently expanding the work scope: every instrument here only sees the repository it runs in. git worktree list, git branch -a, git fsck, git stash list, git log --not --remotes — all of them are structurally blind to an independent clone of the same repository elsewhere on the machine. A linked worktree (git worktree add) has a gitlink file pointing home, so it shows up; a second git clone has its own complete .git and no back-reference, so it shows up in nothing. Run git_find_all_checkouts.sh first only for an exhaustive audit or unknown target; otherwise audit the named target. Real incident: a repository audited clean, every branch pushed, while 440 lines of a working feature sat as untracked files in a sibling clone one rm -rf from gone. Scope has a second axis: TIME. Every origin/* ref is a cached snapshot from your last fetch, not the remote — so git fetch --all --prune before you trust any verdict that depends on one. Read a stale cache in the right direction: for "what would be lost" it errs safe (it can over-report unpushed work, never hide it), which is why the scripts here still run offline. For "is this already upstream?" it fails the other way — work the remote already has reads as unique, so you re-ship it, and if the remote improved it meanwhile your "restore" silently reverts those improvements while looking like a rescue. Real incident: a comparison base one day old made an already-merged change look unshipped; the rescue PR would have reverted three fixes a later review added on top, one of them a security fix. Scope has a third axis: the REF SET itself moves. A branch inventory and a verified bundle prove what existed at one instant; they do not authorize deletion five minutes later. Immediately before deleting, re-enumerate local refs and hosting-service branches, then require every target ref to still equal the object recorded in the bundle. A new branch, a moved tip, or a new parallel PR reopens classification and requires a new bundle. Do not delete against a stale inventory. Scope has a fourth axis: OWNERSHIP. Repository visibility does not make every visible object part of this task. Partition discovered refs/worktrees/PRs into change-authorized, inspect-only, and explicitly excluded sets before acting; compute cleanup success over the authorized set.
2. Run git_loss_audit.sh for the authoritative "what would be lost" check within a checkout. It compares the current HEAD, every linked-worktree HEAD, local branches, and tags against every remote, then inspects each worktree for tracked/untracked changes plus stashes and dangling commits. The shorter git log HEAD --branches --tags --not --remotes misses a detached HEAD in a different worktree and all uncommitted files. Ahead/behind counts do not answer this. Run it in the named checkout, and in additional Step 0 checkouts only after each is explicitly change-authorized. Run this repository-wide script only when every surface it enumerates—linked worktrees, local refs/tags, stashes, and dangling commits—is inside the declared evidence scope. It has no exclusion flags. Otherwise limit the claim to the authorized checkout/ref and use its own status, HEAD, upstream/remote identity, and git log HEAD --not --remotes as scoped evidence; report the other surfaces as not audited.
3. git reflog is the first move for "I lost a commit," not fsck. Reflog records every HEAD position (commits, checkouts, resets, rebases) for ~90 days and the lost commit is usually in its top few lines. git fsck is the deeper net for commits reflog can't reach.
4. Preserve before you clean up — and know which backup tool can actually reach the work. Pin at-risk/dangling commits somewhere garbage collection can't reach them before deleting a branch, running gc, or force-pushing. Cleanup is reversible only while a ref (or the reflog window) still points at the work. Critical asymmetry: bundle, archive, and format-patch can only reach objects git already knows about. An untracked file that was never git added and never stash -ued is invisible to those formats — the copy on disk is the only copy, so preserving it means literally copying the file out. Backing up "the repository" and believing untracked work came along is how a clean-looking backup silently omits the only thing at risk. When the backup is a branch pushed into an already-existing repository rather than this one's own remote, verify shared history before the push (Mode B Step 2) — a similar name proves nothing.
5. Verify "merged" by CONTENT, never by commit count — and know that most content checks are also unsound. After a squash-merge, main..branch shows the branch's original commits as "unmerged" even though their content is on main — often 100+ phantom commits. But swapping counts for the nearest content check is not enough: in one audit, three successive "surely this is content-level now" instruments each returned a wrong answer — git cherry (squash rewrites patch-ids → false UNMERGED), a three-dot diff base...ref used to ask "what does base lack" (three-dot answers a different question and under-reported missing files by 5×), and a file-level existence check (a file present on base can still be missing the ref's lines). Only the trial merge (git merge-tree, what git_verify_branch_merged.sh runs) was right every time. Diff-form and rung-by-rung reliability: references/merge_verification.md.
6. For a high-stakes exhaustive "is everything merged?" call that will authorize deletion, verify adversarially. One independent reviewer is the default. Use multiple reviewers only when distinct repositories or evidence axes cannot be covered by one pass and the user has authorized that fan-out. Make one pass try to falsify the declared evidence scope (rule 1), but keep any newly found target report-only under the Outcome contract.

Mode A — Recover lost work

A commit/branch/stash that "disappeared" is almost always still in the object store for ~90 days — why that is true, and what ends it, is references/recovery_playbook.md § Mental model: nothing is gone until gc runs. The ladder there is indexed by symptom, so go straight to your rung — § Ladder step 1 — git reflog (where most recoveries end), § Ladder step 2 — dropped stashes, § Ladder step 3 — detached-HEAD work, § Ladder step 4 — git fsck for true orphans. The 30-second version:

git reflog --date=iso | head -40          # find the lost HEAD position (most recoveries are here)
git show <sha>                            # CONFIRM it's the right commit before acting
git switch -c rescue/<name> <sha>         # recover onto a NEW branch — never reset onto live work

If reflog doesn't show it, fall through by symptom rather than reaching for fsck first: a dropped stash has its own recovery route (references/recovery_playbook.md § Ladder step 2), work abandoned on a detached HEAD has another (§ Ladder step 3), and only a true orphan — from a rebase, say — needs git fsck --dangling (§ Ladder step 4).

Mode B — Audit what's at risk, then preserve it

Step 0 — establish the evidence scope (rule 1). What "at risk" covers, and the checkout kinds that hide it, are references/recovery_playbook.md § The authoritative "is anything at risk" check and § Linked worktrees and detached worktree HEADs. Run machine-wide checkout discovery only when the Outcome contract calls for an exhaustive audit or the target checkout is unknown. For a named target, record that checkout and continue to Step 1 without turning an unrelated clone into work. When exhaustive discovery is warranted, find every checkout of this repository on the machine, including the independent clones no in-repo command can see:

scripts/git_find_all_checkouts.sh              # defaults to this repo's parent + grandparent
DEPTH=6 scripts/git_find_all_checkouts.sh ~    # widen when clones live far from each other

It matches sibling checkouts by normalized remote URL (so the SSH and HTTPS forms of one repository compare equal), falling back to any shared commit history whenever either the current or a candidate checkout has no origin. That history check works for shallow clones that cannot see the repository's true root. It never matches by directory name, because an independent clone is usually named differently from the original (repo vs repo-hotfix), which is exactly when name matching fails. It canonicalizes path aliases before identifying the current checkout, disables repository-provided fsmonitor commands while inspecting candidates, and treats commits reachable from any locally known remote-tracking ref as pushed even when a branch has no upstream. Exit is 1 when any other checkout holds uncommitted, untracked, unpushed, or uninspectable work. For an inspect-only checkout, stop at discovery: Step 1 fetches and changes its remote-tracking refs. Run Step 1 only after that checkout is change-authorized; apply Step 2 only to authorized items. A "nothing at risk" claim covers only the checkouts actually audited.

Maintainer verification

Run the isolated regression suite after changing checkout discovery:

uv run python -m unittest discover -s tests -p 'test_*.py'

Step 1 — audit (non-destructive). What, if anything, is at risk of loss right now:

When every worktree/ref/tag/stash/dangler the script enumerates is inside the declared evidence scope:

scripts/git_loss_audit.sh          # defaults to remote "origin"; pass a remote name to override

When any surface listed above is excluded, skip that script and collect only checkout/ref-scoped evidence:

git status --porcelain=v1 --untracked-files=all
git rev-parse HEAD
git log --oneline HEAD --not --remotes
git ls-remote --exit-code <remote> refs/heads/<branch>   # 0 present · 2 absent · 128 probe failed

Both the --exit-code and the fully-qualified refs/heads/ prefix are load-bearing here, not style: a bare git ls-remote <remote> <branch> reports an unreachable remote and an absent ref identically (each prints nothing), and a bare branch name also matches a same-named tag. The trap is measured in both directions under Troubleshooting § "A 'did that branch get deleted?' probe says it still exists".

For the full audit, expected output is every worktree with branch/detached state and cleanliness, plus counts of local-only commits, dirty/unavailable worktrees, stashes, and dangling commits. Exit is 1 when commits exist on no remote or a worktree is dirty/uninspectable; stashes and danglers remain visible but do not alone make the audit fail. Exit 0 is therefore not permission to delete a visible stash/dangler: triage or preserve every reported item. Do not claim cleanup is safe until the named worktree is clean and its HEAD is proven contained or deliberately preserved. The scoped path proves only the authorized checkout/ref; it says nothing about excluded worktrees, other local refs, stashes, or danglers, which must remain listed as not audited.

Step 2 — preserve only what the next authorized destructive action threatens (additive, gc-proof). A finding alone does not need a backup. If deletion, gc, or history rewriting can make a reported commit unreachable, preserve that exact commit before the action. Use the whole-set helper only when every reported dangler is actually in the authorized target set:

scripts/git_preserve_danglers.sh --patch-dir ~/git-danglers   # pin + export patches

Why pinning survives gc, and the targeted single-ref form when the whole set is not in scope: references/recovery_playbook.md § Preserve: pin authorized danglers so gc can never take them.

This pins every dangling commit under refs/dangling-backup/<sha> (garbage collection can never reach a referenced commit) without cluttering git branch, and optionally writes a .patch per non-stash commit. For a specific important commit, also give it the full treatment — local branch and a pushed remote branch and a git format-patch file — so a single disk or a single git gc can't take it. Details + why triple-backup: references/recovery_playbook.md § Triple-backup a critical commit.

Before pushing that preservation branch into an already-existing repository, verify shared history first — a similar name is not evidence of the right repository. Fetch the candidate repository's default branch (git fetch <candidate-url> <default-branch>) and run git merge-base <that-default-branch> <ref>; a local merge-base exiting 1, or the hosting service's own compare view reporting no common ancestor, means the two share no history and the target is a different project. Push the branch back to this work's own remote first; if none exists, create a new repository; if neither applies or the correct home is unclear, ask the user — but never push anyway because the name matched. Keep the merge-base check as the test whenever the right home is not obvious: only a repository that already shares this work's history can host the branch without being a different project. Real incident: a deployment source's backup branch was pushed to an unrelated private repository chosen by name resemblance alone. If a push already landed and a later readback finds no common ancestor, treat the branch as misplaced: move its content to the correct home, then delete it from the wrong one, rather than leaving it there as "already backed up somewhere."

Untracked files need a different tool — plain copying (rule 4). Put <backup> outside the target repository and every checkout being retired. Everything above moves git objects; a file git was never told about is not one. Preserve those explicitly, and keep the channels separate so a later reader knows what each restores:

git -C <checkout> status --porcelain | grep '^??'                     # what is untracked
cp <each-untracked-path> <backup>/                                    # the ONLY copy — plain cp
git -C <checkout> diff > <backup>/uncommitted.diff                    # tracked-but-uncommitted
git -C <checkout> bundle create <backup>/history.bundle origin/main..HEAD   # unpushed commits
git bundle verify <backup>/history.bundle                             # prove it restores

Write a one-paragraph README beside them saying where they came from, which branch, and when the session stopped. A backup nobody can interpret six weeks later is only slightly better than none — and the person reading it will not be the person who made it.

Mode C — Verify everything is merged (without being fooled by counts)

The trap: a stale branch shows "173 commits ahead of main" yet every line is already on main (squash-merge artifact) — the mechanism is references/merge_verification.md § Why commit counts lie. Never conclude "unmerged" from counts. Per-branch content check (procedure and output reading: § Per-branch verdict procedure):

scripts/git_verify_branch_merged.sh <branch> [<base>]   # base defaults to origin/main

This mode is the one direction where a stale base is unsafe (rule 1): judged against yesterday's origin/main, a branch whose content landed hours ago still reads UNMERGED, and "rescuing" it re-applies an older version over whatever was built on top. The script fetches first for exactly that reason. Because fetch moves remote-tracking refs, run it only after existing coordination has quiesced every checkout writer and transferred exclusive ownership. If that cannot happen, stay read-only and report that the merge verdict is unavailable. If the fetch itself fails after ownership transfer, the script falls back to cached refs and says so on stderr only. Treat that line as a blocker, not a footnote: rerun once the network is back before acting on the verdict. Comparing by hand (git diff origin/main <branch>, git log origin/main..<branch>) has no such safety net at all — the sole writer must refresh authority first, and two-dot vs three-dot answers different questions (references/merge_verification.md § Pick the diff FORM from the question you're asking). Signals that may inform a human but must never auto-decide are fenced off in § Manual-only investigation hints.

It reports MERGED (ancestor) or MERGED (content contained) — content-safe for a separately authorized Mode E deletion gate — versus UNMERGED / NEEDS REVIEW, listing the files the branch would still change. The verdict is sound, not heuristic: it does a trial 3-way merge of the branch into the base with git merge-tree (in memory, no checkout) and only reports content containment when that merge changes nothing — so a squash-merged branch reads MERGED despite a nonzero commit count, while a revert/edit/new-file the base lacks reads UNMERGED. It is safety-biased: anything it can't prove contained is reported for review, because a false "merged" loses work while a false "unmerged" only costs a look (references/merge_verification.md § Why safety-biased). Why the trial merge is sound rather than a heuristic, and why --find-object/blob comparison is not: § The sound content check. When base has changed the SAME lines again since a squash-merge (not just any later edit — an unrelated file or unrelated lines still leave the current-base trial merge sound) and it now conflicts instead of reproducing base's tree, --merge-commit <sha> proves containment at that historical merge commit instead — a different, narrower question than "does base have it now" (§ The historical-merge-commit rung). For a whole repo of branches against one frozen base, scripts/git_classify_refs.sh --base <sha> [--pr-map <json>] runs this same ladder — including the merge-commit rung, via --pr-map — in one offline pass instead of one invocation per branch. For a whole repo of branches, the read-only fan-out pattern — one agent per batch, each told to falsify "everything is merged," every finding independently re-checked — is § Adversarial multi-agent verification, with the constraints those agents must be given in § Rules for the verification agents.

Mode D — Prevent the disaster

The habits that keep a branch tangle from ever stranding work: references/prevention_practices.md. Each bullet below carries the § name of its full treatment there — follow the one that matches your situation rather than reading the whole file. The load-bearing few:

• Read the current collaboration contract before prescribing topology. An explicit user or project decision about shared checkouts, worktrees, branches, or contribution flow outranks this generic guidance. Do not turn one messy audit into a permanent "one worktree per session" rule. (§ Choose topology from current authority.)
• One physical checkout gets one writer; parallel agents and sessions stay read-only. A topic branch inside the same checkout does not isolate the shared working files, current branch, or index. Writer ownership comes from the repository's task/coordination contract, not a guessed file list. If ownership is unclear or another writer is active, do not mutate the checkout. (§ Shared checkout and concurrent sessions: one writer — also governs the two "parallel session" bullets below, and now also covers finding an unidentified writer by process evidence rather than a guessed name.)
• Commit before switching and push WIP early. Prefer a remote-backed commit over stash juggling, but preserve a higher-authority narrow stash exception; never use an unscoped stash to make a dirty checkout look ready. (§ Parallel / multi-branch work; § Push work-in-progress branches early.)
• Worktrees are explicitly authorized, named exceptions — not the standing default. They isolate working files, HEAD, and index but still share refs, stashes, object storage, config, and hooks, and do not copy ignored dependencies. When approved, a linked worktree is safer than an invisible independent clone but remains a separately audited retirement target. (§ Audit every authorized worktree before retirement.)
• Handoff and merge by exact commit, then finish with an AND gate. Record branch, local HEAD, and fresh remote tip; require them to equal the handoff SHA. Direct merges name that SHA, not the branch. Hosted merges use an expected-head-SHA precondition when available, or an immediately preceding hosted head readback that must still equal the handoff SHA. Every session-owned byte must be in that remote-backed commit, and every residual path must be enumerated and attributed.
• A process snapshot is not a lock, and a merge is not cleanup authority. Any scheduler that can write this checkout counts as a writer even when its paths are disjoint. Before Git mutation, the project's existing coordination must prove it quiescent and transfer exclusive ownership; without that mechanism, stay read-only and report the gap. Do not stop, reconfigure, or invent a lease for automation under this generic Skill. Retire refs or checkouts only through separately authorized Mode E evidence. (§ Known automated writers are not session-owned WIP.)
• Confirm the current branch before committing (git branch --show-current) — a fix committed onto the wrong feature branch is invisible to its real PR and easy to lose on cleanup. (§ Confirm the branch before every commit — including why removal from the wrong branch waits for Mode E.)
• Never race another writer with checkout-relative mutation. If another writer is active, stop until the repository's coordination system transfers exclusive write ownership. After transfer, name the exact ref and object when repairing or advancing state; do not rely on whichever branch happens to be checked out. reset --hard, merge, and rebase all act on whatever is checked out at the instant they run. Use checkout-independent forms for ref repair when they match the authorized outcome:

  git branch -f <branch> <target>          # instead of: switch <branch> && reset --hard <target>
  git fetch origin <branch>:<branch>       # fast-forward a branch you are not on
  git push origin <sha>:refs/heads/<branch>
  

  Real incident: a reset --hard origin/main issued while another session still owned the checkout landed on that session's feature branch and moved it back two commits. The correct first action is to stop and transfer ownership; once transferred, an explicitly targeted ref repair avoids making checkout position part of the operation.
• If a parallel session previously switched the shared tree and stranded your uncommitted work, do not mutate it until that session is quiescent and exclusive ownership has transferred. Then follow the incident-only relocation procedure in § Recover stranded work after a parallel session switched the shared tree: prove your files match across bases, commit only explicit paths, and restore the prior branch before handing ownership back. Branch deletion remains a separately authorized Mode E action.
• The inverse case: another session's commit lands on your branch, and every check you already run stays green. In a shared checkout, a commit a sibling session makes while HEAD sits on your branch becomes a parent of yours and ships inside your PR. git branch --show-current names your branch, the tree is clean, and git diff --cached --name-status shows exactly your paths — all true, all blind, because their work left the index the moment they committed. It appears only in the branch's cumulative range against the base you branched from. Detection is read-only, so run it before every push and before opening any PR:

  base=<the base SHA you recorded when you created the branch>
  git rev-parse --verify "$base^{commit}"   # must print a SHA — see below before trusting the rest
  git log  --oneline "$base"..HEAD     # every commit here must be yours
  git diff --name-only "$base" HEAD    # every path here must be yours
  

  The verify line is load-bearing. An empty $base turns "$base"..HEAD into HEAD..HEAD: no output at exit 0, indistinguishable from "no foreign commits". That silent case is the one the guard exists for; § A foreign commit adopted onto your branch has it and the louder one measured. And "yours" is not derivable from Git: in a shared checkout both sessions write the same author and committer, so no flag separates them. It comes from the SHAs you recorded as you committed. If you cannot say which commits are yours, stop and ask — the repair deletes a commit, so a guess here is the loss this skill exists to prevent. Record that base SHA when you branch — deriving it later reads a cached remote ref, and the fetch that would refresh it is itself ownership-gated § A foreign commit adopted onto your branch. A foreign commit in that range is evidence another writer was in this checkout, so repair is not yours to start. Stop; the ownership rules above apply unchanged. Once ownership has transferred, repair is a history rewrite of your branch — git rebase --onto checks out the branch it rewrites — so it runs the existing sequence rather than a shortcut: the applicable Mode B evidence path, then git branch backup/pre-rewrite <your-branch> (Snapshot before any history rewrite — this is what makes the rebase reversible), then git branch rescue/foreign-<short-sha> <foreign-sha> (this preserves their work, a separate obligation and a different ref), then git rebase --onto "<foreign-sha>^" "<foreign-sha>" <your-branch> — onto the foreign commit's parent, never onto the base, because --onto "$base" discards everything before the foreign commit, your own earlier commits included, and exits 0. Then re-run the detection above: the rebase's exit code does not tell you whether it took something of yours with it. Retiring either ref afterwards requires Mode C/E deletion-grade evidence, not a guess. Full procedure, and why the two obvious "did their work survive?" probes return the wrong answer, in A foreign commit adopted onto your branch in references/prevention_practices.md. Real incident: a sibling session committed while HEAD sat on a freshly created branch; the PR carried that session's in-progress work, and the only signal was a repo validator reporting two changed components when the author had touched one.
• If a parallel session is actively writing the shared tree, all repository mutation stops. Do not switch, add, reset, create commits with a temporary index, update refs, or push. Use the repository's coordination system to quiesce that writer and transfer exclusive ownership; if none exists, report the gap and preserve the current evidence. Once you are the sole writer, an object-store-only commit can keep attributable foreign WIP out of the shared index and working tree. Freeze every candidate as the exact Git entry tuple (mode, object ID, path) — bytes alone are insufficient because 100755, 120000, and 160000 carry executable, symlink, and gitlink behavior. The safest source is an immutable candidate commit:

  candidate_ref=<immutable-candidate-commit-oid>
  candidate_path=path/to/file
  candidate_entry=$(git ls-tree "$candidate_ref" -- "$candidate_path")
  candidate_mode=$(printf '%s\n' "$candidate_entry" | awk 'NR == 1 { print $1 }')
  candidate_oid=$(printf '%s\n' "$candidate_entry" | awk 'NR == 1 { print $3 }')
  test -n "$candidate_mode" && test -n "$candidate_oid" || exit 1
  
  candidate_index=$(mktemp /tmp/git_safety_candidate_index.XXXXXX)
  export GIT_INDEX_FILE="$candidate_index"   # the tree's real index is untouched
  git read-tree origin/main           # start from the pushed base, not the dirty tree
  git update-index --add --cacheinfo "$candidate_mode,$candidate_oid,$candidate_path"
  tree=$(git write-tree)
  commit=$(git commit-tree "$tree" -p origin/main -m "…")   # HEAD does not move
  unset GIT_INDEX_FILE
  rm "$candidate_index"
  git push origin "$commit":refs/heads/<branch>             # open the PR from here
  

  For an owned temporary regular file that is not yet in an immutable commit, derive its intended mode explicitly (100755 when executable, otherwise 100644) and hash its bytes; fail instead of applying that route to a symlink or submodule. For those entry types, first freeze an immutable candidate commit and copy its mode/object tuple as above. Never source an entry from a shared path that another session is editing. The sequence reads and writes only the object store and a throwaway index, so git status in the shared tree is byte-for-byte unchanged. It is a sole-writer preservation technique, not permission to mutate while someone else owns the repo. commit-tree does not run the normal git commit hook path: execute the repository's exact pre-commit/security gates against the candidate before push, and still let pre-push run. Use it only after ownership transfer, when preserved foreign WIP makes checkout switching or shared-index staging unsuitable.
• A bare git commit snapshots the whole index, not just what you staged — and a commit that bypassed the index leaves a trap in it. Moving the current branch without updating the shared index advances HEAD while the index stays on its old baseline — via commit-tree + update-ref on that branch, or a git commit through a temporary GIT_INDEX_FILE. (The sole-writer push-to-another-branch path above moves no local ref, so it leaves no drift.) Every file the new commit introduced then shows as a staged deletion (git status prints D lines plus matching ?? untracked entries). git commit -- <path> neither creates nor repairs this drift — it only updates its own paths. The drift detonates on anyone's next bare git commit: that commit snapshots the entire index, turning the phantom deletions real — delivered files vanish from HEAD while the working tree looks untouched. Real incident: a 24-file delivered directory sat in that window after a temporary-index commit; one bare commit by a parallel session would have deleted it from the branch tip, and the only sign anywhere was D lines in git status. Two obligations follow. Whoever advanced the branch past the index re-syncs immediately — git diff --cached --name-status, then git restore --staged -- <the paths the commit touched> until those paths no longer appear in the diff (a parallel session's own staged entries are theirs, not yours to clear). And before any bare commit on a shared tree, read that same diff as your blast radius — every entry, D lines included, must be one you intended; an entry you don't recognize means stop, not commit. (§ Commit-scope hygiene.)
• Before any rebase or branch-delete, run the applicable Mode B evidence path. Use the full loss audit only when every worktree/ref/tag/stash/dangler it enumerates is in evidence scope; otherwise use the authorized checkout/ref's scoped checks and limit the safety claim accordingly.
• Before bumping a shared version/lockfile, check the base's current value so two parallel branches don't both claim the same bump (a silent collision that blocks the later change from shipping). (§ Version / lockfile collisions between parallel branches.)

Mode E — Retire worktrees, stashes, and branches safely

The opposite worry from Mode A: not "I lost something" but "these leftovers are piling up — which can I destroy?" Deleting is trivial; proving each item is superseded is the work. Start from the Outcome contract. For an exhaustive audit or unknown target, run checkout discovery; for one named worktree/branch, stay in its owning repository. Run git_loss_audit.sh only when all worktrees/refs/tags/stashes/danglers it enumerates are inside evidence scope; treat inspect-only objects as report-only, keep explicitly excluded collaborator resources out of both the retirement plan and its terminal counts, then retire only the named targets. If any enumerated surface is excluded, do not run the full loss audit or an --all-refs export; use checkout/ref-scoped checks and targeted exports instead:

Step 1 — classify each leftover: live WIP, or superseded draft? Evidence ladder, strongest first:

1. Fresh authority plus trial merge — refresh the base and exact branch tip, then run scripts/git_verify_branch_merged.sh. An ancestor/content-contained verdict is deletion-grade evidence. If it returns NEEDS REVIEW, continue down this ladder; do not convert uncertainty to MERGED with a weaker heuristic. For many leftovers against one frozen base, scripts/git_classify_refs.sh runs this exact rung across every branch in one offline pass.
2. git cherry <base> <branch> is a hint, not a verdict. A - proves that one patch-id is upstream; a + does not prove missing work because squash merges deliberately create a new patch-id. Never rescue or delete a whole branch from this output alone.
3. Same-file supersession check — for a stash or + commit touching files that were later reworked on the base: extract its version of the file and compare with the base's current version (git show <ref>:<path> | wc -l vs git show <base>:<path> | wc -l, then spot-diff). If the base's version is a superset (has everything the leftover has, plus later work), the leftover is a superseded draft. Real case: a stash labeled "unfinished dev" held a 1128-line renderer; main's version was 1151 lines — the same functions plus a later feature parameter. Restoring that stash would have been a regression, not a recovery.
4. Function/marker-level probe — grep the base for the leftover's distinctive additions (def new_helper, a constant, an error string). All present on the base → superseded. This catches "absorbed into a refactor" cases where file shapes changed too much for rung 2.

Anything you cannot prove superseded stays alive (same safety bias as Mode C: a false "superseded" loses work; a false "still live" costs a branch name). One warning that changes verdicts: the leftover's label is not evidence — a stash named "unfinished development" can be a fully-landed early draft; judge content against the current base, never the name. Worked examples of the rungs (including the squash-artifact and absorbed-into-refactor cases): references/merge_verification.md § Supersession triage.

Step 2 — after deletion authority exists and immediately before deletion, preserve exactly what that deletion threatens:

# Targeted branch cleanup: prefer the narrow export.
scripts/git_export_before_drop.sh --branch <branch> --out <external-backup-dir>
# Pin only an authorized dangling SHA; leave unrelated danglers report-only.
git update-ref refs/dangling-backup/<sha> <sha>
# Full ref topology: only when every captured ref is explicitly authorized.
scripts/git_export_before_drop.sh --all-refs --out <external-backup-dir>
scripts/git_export_before_drop.sh --verify-current <external-backup-dir>/all-refs.bundle

The targeted update-ref reaches only the authorized dangling commit. If every reported dangler is in scope, the whole-set git_preserve_danglers.sh may replace it. Prefer repeated --branch options for named branch/worktree retirement. --all-refs captures branches, tags, stashes, hidden backup refs, and linked-worktree HEAD refs, so it is valid only when that whole captured set is authorized; add --all-stashes only when stashes are also deletion targets. --verify-current is the final compare-and-swap gate: it exits 1 if any recorded ref moved or disappeared. Refresh remote authority before it, and rebuild the bundle on any mismatch. Keep backups outside the repository; never turn one branch into a repo export.

For a multi-branch "only one main" cleanup while other sessions may still commit or open PRs, read references/merge_verification.md § Converging many branches to one main through single-writer windows before Step 3. While another writer is active, that route is read-only: fetch, object/ref creation, bundle export, push/PR, and deletion wait for existing coordination to prove quiescence and transfer exclusive ownership through final readback. The reference adds the moving-ref inventory, dirty-WIP preservation, immutable-candidate, duplicate-PR, and final branch-count gates that a single-branch retirement does not need.

Step 3 — destroy, in the safe order:

• Stashes: drop from the highest index down (drop stash@{2} before stash@{1}) — indices shift as you drop, and top-down keeps every number meaning what your backup filenames say.
• Linked worktrees: require an empty git -C <path> status --porcelain=v1 --untracked-files=all, then inventory ignored paths separately with --ignored. A normal clean status hides !! files, and no bundle can preserve them; copy out anything not proven reproducible, preserve its relative path, and verify it against a recorded pre-removal content hash. Record the exact HEAD, prove it contained/superseded against a freshly fetched base, export its branch or collision-checked recovery ref into a verified targeted bundle, and obtain current-session deletion authority. As the final pre-remove gate, re-run the empty status and the complete ignored inventory. Require exact equality with the frozen pre-removal manifest for every ignored path, entry type, file hash, and symlink target, and re-verify each preserved source and backup copy; any difference aborts. Removal must be the next operation. Remove only with git worktree remove <absolute-path> without --force. Afterwards prove the path and registration are gone while the recorded HEAD still resolves through the kept branch/base or the verified bundle and every copied ignored item still matches its recorded hash. Never remove the primary/current checkout; retire its branch only as a separate, separately authorized action. Follow references/merge_verification.md § Worktree retirement.
• Local branches: prefer git branch -d (refuses unmerged); use -D only for items Step 1 proved superseded, backed up, and the user authorized deleting. A squash-merge is the usual reason -d refuses a branch whose content is fully merged: -d judges by commit ancestry, and the squash replaced the branch's commits with one new-SHA commit, so ancestry is broken even though every line landed. That is not license to reach for -D reflexively — it means fall back to Step 1's content check (git cherry, superset diff) and only -D once that proves containment. -d also judges "merged" relative to the checkout's CURRENT HEAD (or the branch's configured upstream), not relative to the base you have in mind — a checkout sitting on a stale branch makes -d refuse a branch that genuinely is an ancestor of the intended base, which reads exactly like the squash case above but has a different fix: don't reach for -D, confirm ancestry directly against the intended base with git merge-base --is-ancestor <tip> <base> and switch/target correctly instead. Delete remote branches only after re-verifying the exact remote and repository visibility/ownership.
• Before -D, check one thing neither containment nor ancestry covers: no open PR may have this branch as head. A branch with zero unique content can still be an open PR's head, and deleting it takes that PR's head with it — refs/pull/<N>/head usually still serves the objects, but that is recovery by luck, not by design (the ladder is in references/recovery_playbook.md § Ladder step 4). On GitHub, confirm by PR number, not by branch name: gh pr list --head <branch> has returned an empty result for a branch whose pull request already existed, and "a branch-deletion decision built on the empty result would have been wrong" (measured — the record lives in references/merge_verification.md § The historical-merge-commit rung, under "On GitHub, do that confirmation by PR number"). Use gh pr view <number> --json headRefOid,state,mergeCommit, or the REST equivalent gh api repos/<owner>/<repo>/pulls/<number>; when the number is not yet known, REST search still beats pr list: gh api "repos/<owner>/<repo>/pulls?state=all&head=<owner>:<branch>". On a non-GitHub remote, use the platform's own PR lookup — a branch-name grep is not a substitute. Do it immediately before the delete, never from an inventory taken earlier: refs move, and "a PR opened after your inventory" is exactly the case this catches. Measured 2026-09-22 — a peer relayed "that branch maps to a closed PR, safe to delete" into a dispatch prompt, and the executing agent's own pre-delete recheck found it was the head of a newly opened PR.
• After deleting a remote branch, read the result back through an exit code, not through output. Two shapes mislead here, in opposite directions. A repository configured to delete branches on merge already removed it at merge time, so a later git push <remote> --delete <branch> exits 1 with remote ref does not exist — the end state you wanted, reported as an error. And the obvious readback is the one that breaks: git ls-remote <remote> <branch> printing nothing is not proof the branch is gone, because an unreachable remote prints nothing either. Use git ls-remote --exit-code <remote> refs/heads/<branch> and read the code — 0 present, 2 absent, 128 the probe itself failed, where 128 means the branch's fate is unknown and nothing may be retired on that reading. Both traps are measured in both directions under Troubleshooting § "A 'did that branch get deleted?' probe says it still exists", which also covers why the ref must be fully qualified.
• Independent clones need ref-complete preparation before retirement. A clean worktree says nothing about clone-only refs, reflog history, ignored bytes, stashes, hooks/config, or an objects/info/alternates dependency created by git clone --shared. Run scripts/git_prepare_clone_retirement.sh --clone <absolute-clone> --survivor <absolute-kept-checkout> --out <new-external-backup-dir>; it refuses those hidden loss states, every clone-only unreachable Git object, partial/promisor clones, attached linked worktrees, local submodule repositories, known Git LFS/annex object stores, tracked content filters, and repository-local config/hook indirection that the recovery archive cannot resolve safely. It disables repository fsmonitor execution, freezes ref tips plus symbolic-ref topology and metadata file types/modes, then creates a self-contained all-refs bundle and a content-bound receipt. Finish every preliminary Git probe, freeze the absent quarantine target, run process occupancy by itself, then run --verify-current <backup-dir> as the final probe with the authorized no-clobber quarantine move as the next operation. This order keeps lsof from observing a sibling Git process without opening a larger post-verification gap. Prove old-path absence + new-path presence; permanent deletion is a separate explicit decision. Full READ-DO sequence and --shared boundary: references/merge_verification.md § Independent clone retirement. This retirement occupancy check is the second of the Skill's three lsof uses — the shared-file writer probe in references/prevention_practices.md and references/merge_verification.md's clone-occupancy probe share the same read-only, stop-on-any-genuine-writer rule; change the criterion in one, change it in the others.

Step 4 — after the delete, re-check by content, not by filename. When a cleanup (or a batch of squash-merges) is already done and the question becomes "did any of it drop work?", the naming-based check that felt sufficient — comm over git ls-tree filenames, "every file is still on main" — is not enough: identical filenames say nothing about identical content. A file the deleted branch and the survivor both have can still differ line-for-line. Re-verify at blob level, and read the diff in the right direction:

git diff <survivor-ref> <deleted-or-merged-tip>    # survivor first, the gone thing second

Lines marked - are on the survivor but not the tip → the survivor is a superset (safe: it has everything the tip had, and more). Lines marked + are on the tip but not the survivor → candidate loss — run each through Step 1's ladder: is that symbol on the survivor under a different shape (a rename or refactor, not a deletion)? A diff that is mostly - with a few + is the fingerprint of "the survivor moved on and the deleted branch was an older version" — a merge that succeeded, not work lost. Apply the same test to any preserved backup: byte-identical or survivor-superset is safe; a line the survivor genuinely lacks anywhere is the one to escalate.

Recovery, if you regret it: patches re-apply with git apply; the untracked tar extracts in place; the bundle restores full history via git fetch <file>.bundle <branch>:restored/<branch>.

Step 5 — close the temporary recovery-artifact lifecycle only when it is separately authorized. First finish Step 4 and prove the maintained survivor contains or intentionally supersedes every payload. Then follow references/merge_verification.md § Retire task-owned temporary recovery artifacts. A general request to converge onto one main branch does not authorize deleting the external backup. Keep any artifact that remains the only copy of work, contains an unresolved payload, mixes cleared and unresolved payloads, or was not created or explicitly adopted by this task. After an authorized retirement, independently prove every exact artifact path is absent; the deletion command's receipt is not the postcondition.

Scripts (execute these; they are non-destructive unless noted)

Every scripts/... path below is relative to this Skill's bundle root, not a command promised on PATH or in the target repository. Resolve the loaded Skill directory and invoke the bundled path; never tell a user to run bare git_verify_branch_merged.sh unless command -v actually finds it.

These helpers run from the repository root. They use read-only enumeration/configuration commands such as find, config, symbolic-ref, submodule status, status, cat-file, rev-list, rev-parse, fsck, for-each-ref, and remote get-url; plus scoped fetch, archive, bundle create/verify, metadata hashing/archive, and (preserve only) update-ref where each script's table row says so. Only git_find_all_checkouts.sh is repository-read-only and safe beside read-only agents; it never fetches, so it also works offline and behind a proxy. Any helper that fetches, writes backup state, or adds refs runs only after existing coordination transfers exclusive writer ownership. None of the helpers authorizes checkout, reset, push, stash drop, branch -d, or gc.

Troubleshooting

• An audit came back clean but the user still thinks something is missing — believe them and suspect scope, not thoroughness. The in-repo instruments were probably all correct about the one directory they could see. Run Step 0 (git_find_all_checkouts.sh) before re-running anything you already ran; repeating a correctly-executed check in the wrong scope returns the same clean answer with more confidence behind it, which is worse than the first pass.
• git_find_all_checkouts.sh finds nothing, but you're fairly sure another copy exists — three likely causes, in order: (1) the copy lives outside the default roots (pass an explicit root such as ~, and raise DEPTH); (2) it sits under a pruned path — the sweep skips node_modules, .venv, vendor, .terraform; (3) its origin points somewhere else entirely (a fork, or a path remote), so remote matching rejects it — check with git -C <suspect> remote -v and compare root commits by hand: git rev-list --max-parents=0 HEAD. A copy made by cp -r before the repo had any remote will only match on root commit.
• git_loss_audit.sh reports dangling commits that look like old stashes — expected after stash-heavy work. They're reflog-reachable now; pin one authorized SHA with targeted update-ref, or use git_preserve_danglers.sh only when every reported dangler is in scope, then inspect with git show <sha> at leisure.
• A branch shows huge "commits ahead" but you suspect it's merged — trust git_verify_branch_merged.sh (content), not the count. See Mode C.
• A recovery artifact becomes unexpectedly large, or an upload/LFS transfer stalls — stop retrying and re-run the Outcome contract. This is a scope/placement signal, not a transport puzzle. If no authorized imminent deletion threatens the data, the backup was premature. If the backup is necessary, keep and verify it in the external backup directory; remote transport is a separate decision, not an automatic fallback.
• git fetch in a script hangs behind a proxy / offline — loss detection still works on cached remote refs, because a stale cache can only over-report unpushed work. Merge and supersession verdicts (Mode C, Mode E) are the exception and genuinely need a fetch; without one, say so in the report rather than presenting the verdict as settled.
• Your work looks unmerged, but the repository moved while you were working — check the clock before you rescue anything: git_find_all_checkouts.sh prints when each checkout last fetched, and git log --oneline <cached-base>..origin/main after a fresh fetch shows what arrived meanwhile. A long session is the risk window — the base you compared against at the start can be many hours old by the end. Symptom to recognise: a change you know you committed appears absent upstream, so you prepare to re-ship it. Fetch first, then compare by content; if it did land, check whether anyone improved it before re-applying your version over theirs.
• A push or merge command lost its receipt (timeout, TLS error, EOF) and the remote ref has moved — a moved ref is not proof your write landed. On a repo with concurrent sessions the new tip can be someone else's merge, and retrying on that assumption either double-applies your change or reports success for work that never shipped. Settle it by content — with two cautions first. Refreshing remote-tracking refs is a fetch, which Mode C gates on exclusive ownership — which cuts both ways. Once you are the sole writer, fetch before you read: rule 1 above applies to this question specifically, because a stale origin/<branch> makes work the remote already has read as unique, which is the double-apply this entry opened with. On a contended checkout you may not fetch, and a verdict read off a cached ref is not a verdict — report it as unavailable. And git merge-base --is-ancestor <your-sha> origin/<branch> answers only where the merge preserved your commit — a squash or rebase merge re-writes it, so exit 1 there means "not this object", not "not landed", and acting on it produces exactly the double-apply this entry warns about (measured in one repository on one day: one merged PR's commit was an ancestor, another's was not, and both had landed). It has a third exit code too: 128 when <your-sha> is not a commit this repository has — which is what you get for a hosted merge that created its own object, and it is not the same answer as 1. The probe that survives either merge strategy is content, with its control line:

  git show origin/<branch>:<path> | grep -cF '<a string only your version contains>'
  git show origin/<branch>:<path> | grep -cF 'string-that-cannot-exist'  # must be 0, or the probe is broken
  

  Real incident: three merge attempts failed at the network layer while origin/main advanced twice — once for this author's merge, once for a parallel session's.
• A "did that branch get deleted?" probe says it still exists — check the shape of the probe before believing it, because git ls-remote <remote> <ref> > f followed by [ -s f ] is wrong in both directions and which one you get depends on a redirection detail. Measured against an unreachable remote: bare > f leaves the file at 0 bytes (Git writes the failure to stderr), so the test reports "already gone" for a branch whose fate is unknown — and you stop preserving it. Merge the streams (> f 2>&1, &> f) and the same failure writes 155 bytes, so the test reports "still there" for a branch that is long gone. Use the exit code the command has for exactly this: git ls-remote --exit-code <remote> refs/heads/<branch> returns 0 when the ref matched, 2 when it did not, and anything else (128 for an unreachable remote) means the probe itself failed — outcomes the file-size test collapses incorrectly, differently each time. On 128 the branch's fate is unknown, which is not the same as gone: keep whatever preserves it, retire nothing on this reading, and either retry once the remote is reachable or hand the question to a human. An unreachable remote is a reason to wait, never a reason to clean up. Pass the fully-qualified ref: ls-remote matches on the tail of the name across all namespaces, so a bare branch name also matches a same-named tag and returns 0 for a branch that was deleted (measured — a common shape after a release tags its branch name). Same trap in the working tree: [ -e <path> ] cannot tell a tracked-and-clean file from an untracked collision. Ask Git instead — git cat-file -e <branch>:<path>, where 0 means the branch has it. Do not read non-zero as "it does not": 128 also covers a mistyped branch name and a path that traverses a tracked symlink, and Git distinguishes them only in the stderr text — so read that text rather than the code alone, or you have rebuilt the very defect this entry opened with.
• You're on a detached HEAD after checking out a commit — that commit is safe as long as you git switch -c <branch> HEAD (or the reflog remembers it for ~90 days). Don't leave important new work on a detached HEAD across a gc. Recovering work already abandoned there: references/recovery_playbook.md § Ladder step 3 — detached-HEAD work. If ~90 days is too short for how this repo is used, widen it once: that reference's § Widen the safety window (config), and references/prevention_practices.md § Set a wider reflog safety window once.
• Only one worktree remains after cleanup — git worktree list always includes the primary repository checkout. Do not delete it merely to make the count zero; the goal is one maintained checkout, not no checkout.
• refs/dangling-backup/* refs are cluttering things later — once you've confirmed (Mode C) their content is on a remote, delete them with git for-each-ref --format='%(refname)' refs/dangling-backup/ | xargs -n1 git update-ref -d. Only after you've verified.

Next step

After recovery/audit, if the repo also needs routine setup, safe commit/push, conflict handling, or handoff hygiene, that's the auto-repo-setup skill's job (invoke /auto-repo-setup) — this skill is the forensic/recovery layer, that one is the routine-workflow layer.