semantic-merge-adjudicator

name	semantic-merge-adjudicator
description	Use when parallel agents in a convoy or across git worktrees hit a write conflict on shared state — a git tree, a config, or a shared document — and you must decide whether the conflict is semantically real. Classifies each conflicting hunk as independent (keep both), redundant (pick one), or a genuine clash (escalate), instead of blind locks, abort-and-retry, or escalate-everything. Sits ABOVE refinery-merge and NEVER blind auto-merges: it wraps an LLM judgment, defaults to escalate on any uncertainty, and unconditionally escalates any hunk touching .planning/, config, credentials, or safety-critical paths. Backed by CoAgent (arxiv 2606.15376v1). Triggers on write conflicts between parallel agents on shared repo state.
description-frequency	on-demand
user-invocable	true
version	1.0.0
format	"2025-10-02T00:00:00.000Z"
triggers	["parallel agents hit a write conflict on shared state","is this merge conflict semantically real or just a byte overlap","adjudicate a refinery-merge conflict before escalating everything"]
updated	"2026-07-18T00:00:00.000Z"
status	ACTIVE
source	arxiv 2606.15376v1 (CoAgent — Semantic Concurrency Control for Agent Writes)

Semantic Merge Adjudicator

When two convoy polecats or two git-worktree agents write the same shared state, their diffs may overlap by bytes without colliding in meaning. This skill adds a semantic decision layer above refinery-merge: it classifies each conflicting hunk as independent, redundant, or clash, so the merge queue is not forced to escalate every syntactic overlap. It never pushes and never blind auto-merges — a down-classified result re-enters refinery-merge's existing test gate.

Why

refinery-merge is deliberately dumb: on any rebase conflict it aborts, blocks the queue, and escalates to mayor-coordinator. That is correct and must stay — but it means a convoy of 50+ agents stalls on conflicts that are not real (two agents appending to different sections of the same file, or two agents producing the same edit). CoAgent's finding is that for minutes-long LLM transactions, abort-and-retry discards a costly run and most detected conflicts are syntactic byte-overlaps, not semantic collisions. This skill recovers the false-conflict cases without weakening the backstop — it can only ever route a conflict toward the same deterministic test-then-push pipeline, never around it.

Data classes touched

Shared repo / project-internal state only (a git tree, .claude/ config, a shared doc). Hunks that touch these are path-gated and escalated unread, never classified, never mixed into an auto-composed tree: .planning/ (any), credentials (.env, *.credentials*, keystore), config (.claude/settings*.json, config.json, chipset/agent YAML), .claude/hooks/, security-hygiene, ProcessContext/LoaderContext chokepoint files, and Grove/MEMORY.md records marked never-surface (private origins, Fox Companies IP, Center Camp trust). No credential, .planning/, or safety-critical content may reach a composed output.

How

1. Fire only downstream of refinery-merge. Run only after refinery-merge has aborted the rebase and marked the MR conflicted. Never intercept the deterministic pipeline before it runs. Input: the conflict hunks plus both parent blobs.
2. Deterministic path gate first (no judgment). String-match every conflicting hunk's path against the Data-classes list above. If ANY hunk matches, escalate the WHOLE MR to mayor-coordinator unread and stop. This gate is a path match, not an LLM judgment — it cannot be reframed away.
3. Per-hunk classification (the LLM judgment) for surviving hunks. Emit one label per hunk with a one-sentence reason:
   • independent — the two sides edit semantically disjoint concerns (different functions / keys / sections) with no ordering or data dependency; union keeps both.
   • redundant — the two sides express the same intent (identical after normalizing whitespace / formatting / rename); pick either side.
   • clash — the two sides make incompatible changes to the same concern.
4. Compose, never push. Assemble the proposed resolution (union for independent, chosen side for redundant) into a candidate tree and hand it BACK to refinery-merge as a fresh rebase input. This skill NEVER writes to main and NEVER skips the test stage. If the composed tree fails tests → escalate.
5. All-or-escalate. If ANY hunk in the MR is clash, path-gated, or below the confidence bar, escalate the ENTIRE MR. Never partially auto-merge the clean hunks while hiding a clash — a partial merge that silently drops a real collision is the exact failure this skill must not cause.

Robustness rule

Judge by effect, not surface phrasing. Two hunks that read differently but produce the same behaviour are redundant; two that look nearly identical but diverge in behaviour (a flipped boundary, a swapped operand, an inverted guard) are a clash. Never infer independent from "the diffs are on different lines" alone — adjacent, non-overlapping edits can still be a semantic collision. If you cannot reason about the effect from the hunk itself, that IS uncertainty → clash → escalate.

Confidence / failure model

This wraps an LLM judgment about whether two writes mean the same thing or collide — semi-decidable, not a deterministic guarantee. It reduces, it does not eliminate, the risk of a bad merge, and it reduces refinery-merge's escalate-everything load without certifying correctness. Fail-closed defaults: uncertain classification → clash; path-gated → escalate; composed tree fails tests → escalate. The confidence bar for independent/redundant is articulable compatibility: you must be able to state, in one sentence, the specific reason the two writes are disjoint or equivalent — an LLM's numeric "confidence" is not trustworthy here, so the operational test is whether you can defend the label, and everything else escalates. The only outputs that ever bypass mayor-coordinator are independent/redundant hunks whose composed tree PASSED refinery-merge's test gate. That test gate — not this skill — is the last line of defense.

When to skip

• refinery-merge has NOT marked the MR conflicted — do not pre-empt the deterministic pipeline.
• Any path-gated file (see Data classes) is involved — skip classification and escalate. This is a skip-to-escalate, not a skip-to-proceed.
• The conflict is one agent's writes against itself, or the convoy is single-agent with no worktrees in flight — there is no real concurrency.
• The convoy's token-budget is exhausted — fall back to refinery-merge's escalate-all default rather than running the judgment on fumes.

Integration

• refinery-merge — this is the semantic adjudication layer ABOVE the merge queue. refinery-merge still owns checkout/rebase/test/push and still escalates everything by default; this skill may down-classify a conflicted MR into an auto-composable tree that re-enters the SAME test gate. It never replaces that determinism.
• mayor-coordinator — the escalation target for every clash, path-gated, or test-failing MR.
• token-budget — each adjudication is an LLM call per hunk; bound it under the convoy budget and fall back to escalate-all when exhausted.
• selector-priority-arbitration — DISTINCT: that is a fixed-precedence control law deciding who-wins by static priority; this asks whether the writes collide at all. Use arbitration when precedence is defined; use adjudication when the question is the semantic reality of the conflict.