SHAPE

SHIFT

Back to homepage

Merging Is Routing

A merge is often described as a mechanical act.

Take two changes. Apply them. Resolve conflicts. Move on.

That model is too small for agent work. An agent merge is a review object first and a routing decision second. The system has to read the patch, the current head, the claimed regions, the evidence, the stale assumptions, and the remaining uncertainty before it decides where the candidate goes.

A merge review reads the patch, evidence, and current head before deciding whether the candidate can move.

The Review Object

A patch says what text changed.

It does not say whether the change is current, whether the tests cover the right behavior, whether the public contract moved, or whether another worker invalidated the same assumption.

The review object is larger:

candidate patch
current head
semantic regions touched
claims made by the worker
tests, traces, and gates
staleness markers
known limits
requested decision

Once those pieces are visible, the merge stops being a button and becomes a decision the system can inspect later.

The Router

The decision should not collapse into applied or failed.

Most useful agent outputs are somewhere between those two states. A stale patch can contain the right diagnosis. A failed test can be the strongest artifact a worker produced. A broad patch can contain one safe hunk and one risky hunk.

The merge router reads the review object and sends the candidate to the next correct place.

The route should preserve that meaning:

Route Decision TableCandidate Routes
RouteSignalRequiresProduces
ApplyLow risk, current head, strong evidenceOutput-bound proof matches the touched boundaryShared state moves
ReviewEvidence is useful but incompleteHuman or coordinator judgment on the remaining riskNarrow decision or stronger proof request
RebaseIdea still fits, but the head movedSame semantic intent survives current headFresh output and gate run
RerunEvidence is stale, failed, or too weakNew attempt with sharper contextReplacement candidate
SplitOne candidate contains multiple risksIndependent hunks, regions, or proof boundariesSeparate review objects
AskA human decision is missingTyped question with scope and optionsAnswer node and continuation
BlockCandidate conflicts with the systemConflict, unsafe proof, or rejected boundaryRecorded non-admission
The router preserves useful partial work by sending each candidate to the next route supported by its evidence.

The route is part of the output. A future coordinator should be able to ask why a candidate was applied, why it became a rerun, or why it turned into a human question instead of disappearing into a failed transcript.

Rebase Is Not Rerun

Rebase means the candidate still has useful shape.

The patch may need to move, but the evidence says the idea is probably alive. The next job is to test whether the same meaning survives the new head.

Rerun means the evidence itself is no longer enough.

Maybe the worker used stale context. Maybe the gate failed. Maybe another lane changed the public contract. The next useful action is not to massage the old patch. It is to ask for a fresh attempt with sharper inputs.

A semantic rebase checks whether the same candidate still means the same thing against the new head.

That distinction matters because it saves useful work without pretending stale work is current.

Split Is A Route

Some candidates contain more than one decision.

One hunk updates a private helper. Another changes a public API. One file has clean evidence. Another touches runtime effect order.

The right route might be:

Split DecisionOne Candidate, Several Routes
RouteSignalRequiresProduces
ApplyPrivate helper hunkFocused unit fixtureSafe hunk admitted
ReviewPublic API hunkDeclaration impact and accepted compatibility decisionHuman-visible decision
RerunRuntime effect hunkEffect trace or replay proofFresh runtime-proof task
A broad candidate can become several smaller decisions instead of one flattened verdict.

That is not a partial failure. It is the merge system refusing to flatten different risks into one verdict.

Questions Are Routes

A human question is not an interruption.

It is a route for work that cannot proceed honestly without a missing decision:

ask: should this behavior be public?
ask: is this migration allowed to drop old fixtures?
ask: which product behavior wins?

Once the answer exists, the candidate can continue from that point in the graph. The answer becomes evidence, not side-channel context.

The Outcome Loop

Routing is cyclic.

Every route either changes shared state or creates a better next task.

Routes either update shared state or create the next backlog item with better evidence.

Apply updates the state. Review creates a narrower decision. Rebase tests an idea against a new head. Rerun creates a better attempt. Split turns an overloaded candidate into separate decisions. Ask turns missing judgment into explicit control flow. Block records that the candidate should not enter the system as-is.

The Mental Model

The merge is where evidence becomes a route.

More workers can produce more candidates, but shared state should only move when the merge system can explain which review object it saw and why that object supported the selected route.