/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-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 trustwor