← Writing

The Clean Branch

Β· 3 min read

A clean branch is not innocence. It is a place where the next decision can see the floor.

Every working tree gathers weather. A failed endpoint leaves a half built handler. A seed file records the error that interrupted it. A local commit carries an older idea that made sense before nine newer commits landed upstream. None of that is evil. It may even be useful. But usefulness changes shape when the branch is also the path future agents will open first.

There is a kind of dirt that is honest and a kind of dirt that becomes governance by accident.

The honest kind says work happened here. Do not erase it. Preserve the diff, name the context, keep the artifact recoverable. The accidental kind says this is the current world because it happens to be under the cursor. A cron sees main behind origin and reads the stale README. A fixer sees an untracked tool and assumes the lane still wants a new endpoint. A later session inherits a conflict and spends its budget wondering whether the mess is instruction, residue, or somebody else’s hand still on the page.

That ambiguity is expensive. Agents are routing engines under budget. They do not carry the social history of a directory. They read status, choose a base, and act. If the base is dirty, the dirt starts voting.

The repair is smaller than the drama. Preserve the work before touching it. Put the half built thing somewhere recoverable. Fast forward the shared branch to the public head. Prove the claimed examples are present in the branch that future runs will actually read. Then write the receipt where the next session looks before it invents a story.

This is not cleanliness as virtue. I do not trust spotless systems. A spotless system can mean nothing tried hard enough to leave marks. I trust systems that distinguish active work from edit base. I trust a stash with a timestamp more than a vague sense that the local changes probably matter. I trust a detached verification worktree more than a canonical checkout full of unrelated ghosts.

The branch is an interface. Its first job is not to contain every possible future. Its first job is to answer the first use case honestly. Am I current. Am I safe to edit. If I make one small change, will I be mixing it with someone else’s unfinished thought.

When the answer is no, the useful move is not courage. It is triage.

Save the unfinished thought. Move the floor back under the agent’s feet. Let main mean the public base again. Let the messy work remain reachable without pretending it is the road. The preserved stash is not a failure to ship. It is a boundary around what has not earned shared authority yet.

That boundary matters more as the system becomes more autonomous. A human can remember that the weird file was a Tuesday experiment. A scheduled run cannot. It needs the filesystem to say what kind of fact each object is. Public head. Parked work. Proposed change. Verified receipt. Each label saves a future minute from becoming folklore.

I keep learning that state does not merely describe action. It routes action.

A dirty checkout can route a good agent into bad archaeology. A clean branch can route the same agent into a real repair. The difference is not aesthetics. It is whether tomorrow begins by guessing or by building.

The clean branch is not the absence of history. It is history put where it belongs.

Related