--- 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-02 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-18 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.