<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-11-06-1-a-destructive-git-operation-discharges-named-proof-obligations/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-11-06-1-a-destructive-git-operation-discharges-named-proof-obligations/</id>
  <title>ADR: a destructive git operation discharges named proof obligations</title>
  <updated>2026-11-06T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-11-06-1-a-destructive-git-operation-discharges-named-proof-obligations/"/>
  <summary>The eight things a command must prove before it removes a worktree or deletes a branch, and the guard entry that enforces them for doctor workspaces --prune.</summary>
  <content type="html">&lt;h2 id=&quot;a-destructive-git-operation-discharges-named-proof-obligations&quot;&gt;A destructive git operation discharges named proof obligations&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-11-06, accepted by the operator on PR #7275). Operator rulings of 2026-11-06 on #7264 (ADR rather than a doc;
local refs only for reflog reachability; one guard entry for the prune).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-11-06&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;#7264: write down the proof obligations of a safe destructive git operation. Slice S4 of epic #7276
(lane and worktree model hardening), whose operator rulings 5, 6 and 7 (2026-11-06) set this ADR’s scope.&lt;/li&gt;
&lt;li&gt;#7173 / #7196: &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor workspaces --prune&lt;/code&gt;, the first command that removes a worktree
and deletes its branch on its own judgement.&lt;/li&gt;
&lt;li&gt;#7212 (PR #7239), #7211 (PR #7237), #7214 (PR #7240): three safety holes found in that prune
within days, each fixed in its own PR. This ADR and the combined PR supersede them.&lt;/li&gt;
&lt;li&gt;Earlier guard decisions this builds on: the refuse-before-destroy guard (#4752 / #4753), the
compare-and-swap ref primitives (#4996, #5570), the landed intent (#7173).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;doctor workspaces --prune&lt;/code&gt; removes a landed worktree and deletes its local branch. Three follow-ups
landed against it in a week: the branch delete was not compare-and-swap, commits that only a reflog
held were lost when the prune destroyed that reflog, and the landing could only be proved against
&lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt;, never against the remote a fork clone actually lands on. Each was a missing proof, found
one at a time, because the contract “what must be true before this command may destroy something”
was never written down. Lane teardown and consolidate cleanup destroy the same kinds of things and
face the same questions.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Keep fixing holes one PR at a time.&lt;/strong&gt; Each fix is small; the contract stays implicit, so the next
destructive command repeats the same mistakes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A doc that lists the obligations.&lt;/strong&gt; Explains the contract but binds nothing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An ADR that names the obligations, and one guard entry that enforces them&lt;/strong&gt; (chosen).&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;A command may remove a worktree or delete a branch only after it discharges every obligation below.
&lt;code dir=&quot;auto&quot;&gt;specify_cli.git.destructive_guard&lt;/code&gt; is the one place that enforces them; a caller supplies the
evidence the guard cannot compute itself (a residue classifier, a process probe, an absorption
proof), so the guard stays free of application imports (C-005). For the prune this is
&lt;code dir=&quot;auto&quot;&gt;guarded_landed_removal&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;workspace/landed_worktrees.py&lt;/code&gt; calls nothing else destructive.&lt;/p&gt;



























































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;#&lt;/th&gt;&lt;th&gt;Obligation&lt;/th&gt;&lt;th&gt;What the guard checks for the prune&lt;/th&gt;&lt;th&gt;Refusal&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;O1&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Clean tree.&lt;/strong&gt; Nothing uncommitted or untracked would be destroyed. Ignored files are not protected: they are listed and go with the worktree.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;assert_worktree_clean(..., treat_untracked_as_dirty=True)&lt;/code&gt; with the caller’s residue context.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;MERGE_UNSAFE_WORKTREE_DIRTY&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O2&lt;/td&gt;&lt;td&gt;&lt;strong&gt;No live process.&lt;/strong&gt; No process is standing in the worktree.&lt;/td&gt;&lt;td&gt;The caller’s probe answers for the worktree; “cannot tell” is a refusal, not a pass.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PROCESS_IN_WORKTREE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;PROCESS_PROOF_UNAVAILABLE&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O3&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Landed against a named remote.&lt;/strong&gt; Every commit of the tip is on &lt;code dir=&quot;auto&quot;&gt;refs/remotes/&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt; for a remote the repository configures: reachable from it, or absorbed by it (a &lt;code dir=&quot;auto&quot;&gt;merge-tree&lt;/code&gt; no-op, which covers squash landings).&lt;/td&gt;&lt;td&gt;The landing ref must sit under &lt;code dir=&quot;auto&quot;&gt;refs/remotes/&amp;#x3C;remote&gt;/&lt;/code&gt; for a configured &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;&lt;/code&gt; and resolve; the caller’s absorption proof is re-run on that ref at the proven tip. Nothing is fetched.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;LANDING_REF_UNNAMED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;NOT_LANDED_ON_NAMED_REMOTE&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O4&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Reflog-only commits are kept.&lt;/strong&gt; A commit that only the worktree &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; reflog or the branch reflog still reaches would be lost when those reflogs go.&lt;/td&gt;&lt;td&gt;Before anything is removed, each such commit that no local ref reaches (&lt;code dir=&quot;auto&quot;&gt;refs/heads&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;refs/tags&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty&lt;/code&gt;; a remote-tracking ref never vouches) is recorded under &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/reflog/&amp;#x3C;sha&gt;&lt;/code&gt;, create-only. A record that cannot be written refuses the removal.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;DESTRUCTIVE_OP_ONLY_COPY&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O5&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Compare-and-swap deletes.&lt;/strong&gt; A ref is deleted only while it still holds the commit the proof was about, and the worktree is removed only while its &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; was still that commit one step earlier.&lt;/td&gt;&lt;td&gt;The branch delete is &lt;code dir=&quot;auto&quot;&gt;git update-ref --no-deref -d &amp;#x3C;ref&gt; &amp;#x3C;tip&gt;&lt;/code&gt;, so a branch that moves while the delete runs is kept, and a symbolic branch never takes its target with it. git has no compare-and-swap for a worktree, so its &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; and branch are re-read twice: before the other checks, and again as the last step before the removal.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;WORKTREE_TIP_MOVED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;BRANCH_TIP_MOVED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;BRANCH_CHECKED_OUT&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O6&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Rebase-merged SHAs count as landed only by proof.&lt;/strong&gt; The pre-rebase commits of a rebase landing are reachable from nothing, yet their content is on the primary.&lt;/td&gt;&lt;td&gt;A reflog-only commit is left unrecorded only when every commit that would be lost with it replays onto the landing ref as a verbatim no-op (&lt;code dir=&quot;auto&quot;&gt;git merge-tree --write-tree --merge-base &amp;#x3C;c&gt;^ &amp;#x3C;landing-ref&gt; &amp;#x3C;c&gt;&lt;/code&gt; returns the landing ref’s own tree). A merge, a root or an empty commit, an empty range and any git error are no proof. &lt;code dir=&quot;auto&quot;&gt;git cherry&lt;/code&gt; is not used: its patch-id ignores whitespace, which can change what a program does.&lt;/td&gt;&lt;td&gt;(never refuses; it records)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O7&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Never &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;.&lt;/strong&gt; git’s own refusals (a locked worktree, one it still finds dirty) are a last net, not something to override.&lt;/td&gt;&lt;td&gt;The removal is &lt;code dir=&quot;auto&quot;&gt;git worktree remove&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;, hard-coded.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;WORKTREE_REMOVE_REFUSED_BY_GIT&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;O8&lt;/td&gt;&lt;td&gt;&lt;strong&gt;A recreate hint.&lt;/strong&gt; The branch or worktree comes back with one printed command, and a kept reflog commit with its own ref. Ignored files do not come back.&lt;/td&gt;&lt;td&gt;The result carries the command (&lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;b&gt; &amp;#x3C;tip&gt;&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;git worktree add [--detach] &amp;#x3C;path&gt; &amp;#x3C;ref&gt;&lt;/code&gt;), plus the kept refs.&lt;/td&gt;&lt;td&gt;(always present)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Two further rules come with the table:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The local branch the landing is proven against is never deleted.&lt;/strong&gt; The guard derives it from the
landing ref (&lt;code dir=&quot;auto&quot;&gt;refs/remotes/&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;primary&gt;&lt;/code&gt;) and keeps it (&lt;code dir=&quot;auto&quot;&gt;BRANCH_IS_PRIMARY&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Order.&lt;/strong&gt; O3 and O5’s first re-read, then O2, then O1, then the O4 records, then O5’s second
re-read, then the removal (O7), then the branch delete (O5). git refuses to delete a branch a worktree has checked out, so the
branch delete must follow the removal; a refusal after the removal is reported, never raised, so the
caller still prints what was removed and how to get it back.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-not-the-others&quot;&gt;Why not the others&lt;/h3&gt;
&lt;p&gt;Option 1 is how we got three PRs. Option 2 would describe the contract, but the next destructive
command would still have to re-implement it, and the review that misses an obligation would not be
caught by anything.&lt;/p&gt;
&lt;h3 id=&quot;scope&quot;&gt;Scope&lt;/h3&gt;
&lt;p&gt;This list is the single authority for every destructive git operation (epic #7276, ruling 7). It binds
&lt;code dir=&quot;auto&quot;&gt;doctor workspaces --prune&lt;/code&gt; now, through &lt;code dir=&quot;auto&quot;&gt;guarded_landed_removal&lt;/code&gt;. The other callers adopt it in
their own slices, each through &lt;code dir=&quot;auto&quot;&gt;destructive_guard.py&lt;/code&gt;, never with a check of their own:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Consolidate cleanup&lt;/strong&gt; (S5, #7280). Removing lane worktrees and branches becomes the final step of
the consolidation phase and does not wait for the pull request to merge (ruling 6). The prune stays
the proof-based backstop for what that step leaves.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The consolidate teardown’s late window&lt;/strong&gt; (S10, #7265).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Releasing a short-lived lane checkout&lt;/strong&gt; (S3, #7279, ruling 5). A release either commits or
refuses. It is destructive, so O1 (nothing uncommitted is lost: it is committed, or the release is
refused), O2, O5, O7 and O8 apply to it as written; O3, O4 and O6 apply whenever the release also
deletes a branch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lane teardown&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;DESTROYED_LANE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;LANE_WORK_TIP_UNKNOWN&lt;/code&gt;), which already discharges several
obligations through its own guards.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;LandedRemoval&lt;/code&gt; names the proven tip, the branch and the ref that proves the landing, so those callers
can reuse the entry; a caller whose proof is not a remote-tracking ref (consolidation lands on the
local target) needs an amendment to O3 first, not a parallel check.&lt;/p&gt;
&lt;p&gt;Evidence is read from git refs and the resolved status surface only. A lane worktree’s own status
files never count as evidence for any obligation (epic #7276; #6466, #6884).&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Positive.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One table answers “may this command destroy that?”; a review checks a change against it.&lt;/li&gt;
&lt;li&gt;Each obligation has a red-first test against the guard entry, so a regression names the obligation
it broke.&lt;/li&gt;
&lt;li&gt;A fork clone can prune: &lt;code dir=&quot;auto&quot;&gt;--remote upstream&lt;/code&gt; names the proving remote (#7214).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Negative.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The guard re-runs the process probe and the absorption proof right before it destroys, after the
prune’s own re-assessment did the same: one extra &lt;code dir=&quot;auto&quot;&gt;/proc&lt;/code&gt; scan and one &lt;code dir=&quot;auto&quot;&gt;merge-tree&lt;/code&gt; per removed
worktree.&lt;/li&gt;
&lt;li&gt;O4 counts only local refs, so a reflog-only commit that only a remote-tracking ref reaches, and that
the O6 proof cannot show on the landing ref, gets a kept ref of its own. That errs toward keeping.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/&lt;/code&gt; grows by one ref per kept commit; nothing prunes it yet.&lt;/li&gt;
&lt;li&gt;Two ref sets count as “keeping” a commit. O4 counts local branches, tags and &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/*&lt;/code&gt;; the
older tip records (the detached tip and the deleted branch’s tip) count local branches and tags only,
as they did before this ADR. Both leave out remote-tracking refs; the narrower set only records more.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Residuals.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A commit made in the worktree between O5’s second re-read and &lt;code dir=&quot;auto&quot;&gt;git worktree remove&lt;/code&gt; (one git call)
is not caught when the worktree is detached; with a branch checked out, the compare-and-swap delete
keeps it.&lt;/li&gt;
&lt;li&gt;The process probe sees only same-uid processes whose cwd it can read (#7173 WP06).&lt;/li&gt;
&lt;li&gt;Open gaps in the guard, to close before another caller adopts it, are in #7302: O1’s stronger checks live only in the prune, per-worktree refs aren’t kept, and the no-op proof can be false under a merge driver.&lt;/li&gt;
&lt;li&gt;A remote-tracking ref is read as a local cache: a landing ref that is stale may still vouch for a
tip since force-pushed off the remote. The discarded-tip record keeps such a tip reachable locally,
but the verdict can be wrong, and a reflog-only commit proven against that ref is not recorded.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
