Review the change. Name the conflict accurately.
Switchyard treats review findings, Git merge conflicts, semantic incompatibilities and policy blocks as different things. They can all stop integration, but they require different evidence and different repair paths.
Structured Review Findings
Review output is durable data rather than an unstructured Agent transcript. A finding can carry severity, message and file/location context so it can drive the Pull Request, editor, repair loop and Needs Attention without each surface reinterpreting prose.
| Field | Example | Used by |
|---|---|---|
| Severity | info, warning, error | Review summaries, integration gating, Needs Attention prioritisation. |
| File/path | internal/app/router.go | Editor findings and PR file context. |
| Message | “merged API version does not match consumer requirement” | Human explanation and repair input. |
| Status | open / resolved | Determines whether repair/re-review still has work to do. |
Conflict taxonomy
| Kind | Detected by | Example | Typical action |
|---|---|---|---|
| Textual Git conflict | git merge during preview | Both candidates edit the same lines. | Three-way/content repair on the Attempt branch. |
| Semantic conflict | Deterministic validation of the clean preview-merged tree | API moves to v2 while a newly-added consumer requires v3. | Change one candidate until the repository contract holds. |
| Policy conflict | Repository/org policy evaluation | High-risk integration requires explicit approval. | Escalate a bounded decision or deny. |
| Intent ambiguity | Review/Agent/human reasoning | Two valid implementations satisfy different interpretations of the task. | Needs Attention or additional Work clarification. |
Textual conflicts
A textual conflict is deliberately boring: it is ordinary Git merge behavior surfaced early. Preview integration runs a real merge in isolated Git state. If Git reports overlapping content, Switchyard records findings and parks the Attempt rather than discovering the problem only after somebody clicks “merge.”
main: timeout = 10
attempt: timeout = 60
other PR: timeout = 30
# preview merge reports a content conflict
# → Attempt enters conflict state
# → repair writes a resolved version onto the source branch
# → preview runs again before queue integration
Semantic conflicts
The more interesting case is: Git says the combined tree is fine, but Switchyard knows the pieces are incompatible. A repository can declare a deterministic contract in switchyard.contract.json. After a clean preview merge, Switchyard validates that contract against the merged tree.
{
"rules": [
{
"kind": "field_equals",
"a": "api/version.json:version",
"b": "consumers/consumer.json:requires_version"
}
]
}
Attempt A moves the API and its existing consumer to v2 together and integrates. Attempt B adds a new consumer requiring v3. The files do not overlap, so Git merges B cleanly into the new main; the repository contract then fails. Switchyard records a semantic error finding, parks the Attempt in semantic_conflict and blocks the Integration Queue. Canonical remains internally consistent.
Layered repair instead of one magic Conflict Agent
- Deterministic resolution when the system has a safe mechanical answer.
- Original implementer repair when the finding is concrete and bounded.
- Specialist/reviewer when another role can provide independent correction.
- Human escalation only when the remaining decision genuinely needs direction.
Autonomous loops are bounded. A system that can call reviewers forever is not durable orchestration; it is an unbounded retry machine.