Skip to content

A worktree nobody can decide to delete

Isolation is cheap to create and expensive to reason about: nothing records what a worktree was for or whether its work landed.

→ found five worktrees and could not say which of them still mattered

cost when it happens
medium
how often
common
area
coordination
work-tracking
recognised by
ai-native-team
solo-builder
agency

The moment

git worktree list prints five entries. Two are obviously current. The other three have uncommitted changes, branches whose names are not quite descriptive, and no way to tell whether they contain an afternoon of work or nothing at all.

Why it happens

Creating isolation is one command and recording intent is nobody's job. A worktree is a directory; a directory carries no objective, no owner and no state. So the decision to delete one is always made on the evidence of a diff, which is expensive to read and ambiguous when read.

Why a better model does not fix it

Nothing is running. The information that would settle the question — what this was for, how far it got, whether it was superseded — was never written by the session that knew it.

What it costs

Either the sprawl is kept, in which case every audit repeats this question, or it is cleared, in which case somebody occasionally deletes work. Both are paid repeatedly, and the second one is paid loudly.

What Majordomus does

A task record belongs to a checkout and carries the objective, the declared scope and the git identity computed at start. Reading it back compares that identity with git now and labels it exact, advanced, diverged or different_context, so a worktree announces its own staleness. When a session ends, handover writes objective, current state and next action, each required and non-empty. watch reports every drift it can see across the records this repository holds.

The worktrees themselves have one topology: a branch's checkout is at <repo>-wt/<branch>, derived from git's identity and never registered, so "where is branch X" is a derivation and not a search. worktree.topology gives every checkout a standing — canonical, misplaced, detached, ephemeral, missing — and every branch a verdict on cleanup eligibility: merged into the trunk, and clean or not checked out. A stray checkout is brought home with its uncommitted work, fingerprinted before and after; nothing is deleted by the tool, and the list of what could go is derived state for a person to act on.

Before and after

before   $ git worktree list
         ../wt-3  8c31f0e  [fix/auth-2]        ...and then what?

after    $ majordomus handover --resolve --repo ../wt-3
         t-20260812…  diverged (-40 commits)
         # Objective: split the auth callback validation
         # Next Action: the legacy mobile form still needs a decision

What it does not do

It does not delete or merge anything, and it cannot see clones on other machines. It reports what each worktree says about itself; whether to keep one is a decision it hands to a person.

What this looks like

Concrete situations, one per audience. Each is declared in the moment's front matter, so the before and the after are data rather than prose a page could drift from.

  1. Forty isolated checkouts ai-native-team

    before
    Every worker gets a worktree; after a fortnight there are dozens, each with uncommitted changes and no record of intent.
    after
    Each worktree''s active task record names its objective, its scope and its head, and reading it back says how far git has moved since.

  2. The branch from last month solo-builder

    before
    A branch called `fix/auth-2` exists; whether it was abandoned or finished is a question only the diff can answer, slowly.
    after
    The record says `partial` with a next action, or there is no record and the branch is genuinely orphaned — which is itself an answer.

  3. Handing the repository back agency

    before
    The client inherits a dozen branches and a paragraph of explanation written from memory.
    after
    Each carries a handover record with objective, current state and next action, and the ledger says which were finished and with what outcome.

How you would know

The observable symptoms this moment declares. They are the questionnaire on the index and the input of majordomus why diagnose; nothing else defines them.

  • There are more worktrees or branches than anyone can account for. many-worktrees
  • Nobody can say whether a given branch or worktree still holds anything worth keeping. safe-to-delete
  • Workers create isolated checkouts routinely and nothing records what for. created-and-forgotten

Where this lives in the tool

Everything below is read out of this moment's own front matter and resolved against the repository. A name here that did not exist would fail validation.

the commands that answer it

the capabilities of the executable that answer it

what it supervises — derived from the claims below

the claims that back this page, and the evidence behind each

the rules that govern it

  • majordomus.handover-integrity
  • majordomus.state-consistency
  • majordomus.isolated-parallelism
  • majordomus.one-worker-one-scope

the use cases that show the way out

If this one is familiar, so is the next

What this moment names, what names it, and what shares its area, audience or tags. The second and third are derived; only the first is written down.

All 38, and how they connect to the tool →