Git merge is excellent at reconciling text. AI coding agents create a different failure mode: two changes can merge cleanly while breaking a shared architectural contract. Agent A edits a helper. Agent B edits a caller. Git sees separate files. The system sees a changed invariant.
flowchart TD
A[Agent A: auth helper] --> C[Clean Git merge]
B[Agent B: billing route] --> C
C --> D{Semantic invariant still true?}
D -- Unknown in Git --> E[Production risk]
D -- Checked in Nool --> F[Governed proposal]
F --> G[nool solidify]
Semantic merge asks whether the combined transitions still satisfy declared intent, impact boundaries, and known findings. Nool does not pretend Git is obsolete. Git remains the transport. Nool adds the semantic gate above it.
A practical workflow starts before the merge. Each agent announces intent with `nool announce intent --intent "..."`, optionally associating work with a thread via `--thread <name>`. Agents can check coordination risk with `nool discover conflicts --compact`. During implementation, record reusable constraints with `nool learn --about <thread-or-file> --kind finding --content "..."`.
Before acceptance, compute impact with `nool debug blast-radius <path> --compact`. If the blast radius is broader than the task, either split the task, block it with `nool task block --id <id> --reason "..."`, or justify the broader proposal explicitly with `nool propose --all --intent "..." --fast`.
Semantic merge matters most when architecture is spread across files: auth, billing, data migrations, generated clients, CI configuration, and shared model types. The dangerous merge is not the one Git rejects. It is the one Git accepts while the system quietly changes meaning.
For teams running several agents, treat every clean merge as only a syntactic result. The semantic review still asks whether the combined work respects thread decisions, task boundaries, and recorded findings. `nool thread show <name> --full` and `nool findings <topic>` make that review concrete. Without that layer, a green merge can still be a red architectural event.
This is why semantic merge belongs before release, not after incident response. The earlier the logical conflict is visible, the cheaper it is to renegotiate scope.
Two extra commands can save a review cycle.