semantic-merge

name	semantic-merge
description	Semantic branch integration. Use before git merge, rebase, or cherry-pick, or when syncing branches where conflicts or overlapping intent must be resolved deliberately.

Semantic Merge

Integrate branches by intent, not by lines. Understand what each side was trying to achieve, synthesize where both changes are valid, escalate decisions that would change what the branch means to the user, and leave a documented trail that later agents can follow.

Core principle: Treat conflicts as intent conflicts first and line conflicts second. Conflicts that change intent always go to the user. The agent implements the user's integration decisions; it does not override them.

Choose a Mode

Load exactly the mode reference that matches the call path:

• Workflow sync author: references/workflow-sync-author.md when superintegrate dispatches an agent to bring the current branch onto a confirmed base.
• Workflow sync reviewer: references/workflow-sync-reviewer.md when superintegrate dispatches a separate reviewer before maturation begins.
• Standalone merge: references/standalone-merge.md when this skill is invoked directly for a merge, rebase, cherry-pick, or branch sync outside the full integration workflow.

All modes walk the §Semantic Coherence Checklist below as the shared gated checklist.

Shared Steps

The following steps are shared by all modes.

1. Ground in repository state

Inspect before changing anything:

• Current branch, worktree status, and any ongoing merge / rebase / cherry-pick state.
• Merge base, incoming commit range, and the set of touched files.
• For workflow mode: the dispatched BASE_REF, PRE_SYNC_BASE_SHA, BASE_HEAD_SHA, and incoming range.

If the worktree is dirty with unrelated changes, preserve them reversibly with a named stash before any sync operation and report the stash in the status return. Stop and clarify only when the repository is already mid-operation (unresolved merge, in-flight rebase, detached HEAD) in a way that makes intent ambiguous.

Scope the merge first

Grounding (Step 1) gives the conflict status, the touched-file set, and the incoming range — size the work from them before investigating intent in depth. A merge is trivial when all three hold:

• it applies with no conflicts,
• the incoming range touches no file the current branch also changed since the merge base, and
• nothing incoming renames, moves, or redefines an identifier, path, schema, or output that current-branch code references.

For a trivial merge, land it and run the stale-reference sweep (Step 6) bounded to that near-empty reach — the sweep is what confirms the third condition held. Intent synthesis, the resolution plan, and escalation have no overlapping cluster to act on; skip them and record a clean sync. Treat the merge at full depth the moment any condition fails — a conflict, an overlapping file, or a rename reaching current-branch code. When unsure whether overlap or a rename reaches current-branch code, treat it as non-trivial: the full path costs investigation time, a wrong skip costs a silent semantic break.

2. Investigate intent on both sides

Read commit messages, diffs, and any task tree or docs for each side. For workflow mode, current-branch intent comes from the superRA/ task tree; for standalone mode, it comes from the branch name, commits, and diffs. Incoming intent comes from the commit range on the other side of the merge base.

Classify each cluster of changes by role. The role drives how the cluster is resolved:

• Behavior or API — code that changes what the program does or how it is called. Synthesize when both sides extend behavior compatibly; escalate when they contradict.
• Data or schema — column names, file formats, key definitions, sample filters. Escalate before choosing — the user owns these calls.
• Docs or narrative — prose explaining intent. Prefer synthesis; stale claims from either side get rewritten.
• Generated outputs — figures, tables, compiled artifacts, fixtures. Prefer regeneration from merged sources over hand-editing either side's copy.
• Tests — including drift tests. Preserve both sides' assertions unless a meaningful result change justifies re-expecting; escalate result changes rather than silently updating.
• Config or build — dependencies, pipeline wiring, environment. Synthesize when additive; escalate when directions diverge.

The agent classifies and executes within each role; calls that would change intent — data contracts, test expectations, outputs — go to the user.

3. Build a resolution plan

For each overlapping area, pick one of:

• keep incoming,
• keep current-branch,
• synthesize both (preferred when both are valid and compatible),
• regenerate derived artifacts from merged sources,
• escalate to the user.

Prefer synthesis over picking sides. Prefer regeneration over hand-editing generated files.

4. Escalate intent-changing choices

Ask the user before resolving — with intent and consequences, not raw diff chunks — when:

• both sides imply different valid intents,
• a conflict changes data contracts, inputs, test expectations, program outputs, or the meaning of a published result,
• task structure would change (routed through superplan §User Feedback and Changing the Task Tree),
• drift-test or result-level expectations would move because outputs meaningfully changed.

Fold every answer into the relevant task objective (rewriting it to be self-sufficient with the new context) before committing the resolution. When no task tree is present, record the decision in the sync commit body.

5. Resolve and land

Run the sync operation only after intent investigation. Resolve by the plan from Step 3. Preserve base-current deletions and relocations by default; restore branch-side content only when current-branch intent, an approved task objective, or a logged user decision justifies it.

Land one merge commit plus N propagation commits as needed to reach semantic coherence. Every commit must leave the tree passing the existing automated protection selected before Sync, or existing tests and drift tests when standalone. Per-commit protection-pass is the lower bound; the whole-mode stopping rule is §Semantic Coherence Checklist §Scope boundary.

Include the conflict resolution, resolved docs, and the mode-specific sync record with the commits that produce them — the git log (commit messages) plus the task-local ## Sync Impact sections in workflow mode, and the commit body in standalone mode. Broader codebase-coherence work is owned by refactor-and-integrate and out of scope here. The sync record may capture context that explains the post-sync diff for later codebase review; it does not carry unresolved semantic-merge work into Integrate.

6. Detect and resolve stale references

A "no conflict markers" check is not enough. Before returning, sweep for stale references within the merge's semantic reach and resolve them — this is part of semantic coherence:

• labels, identifiers, or variable names renamed on one side but still used on the other,
• paths or module locations moved on one side,
• docs and comments that reference the old shape,
• generated outputs that should have been regenerated,
• cross-file imports, registry entries, or config keys.

Run targeted checks for touched subsystems where cheap and relevant. Fix stale references that follow directly from the merge; defer broader codebase-fit work to refactor-and-integrate. Confirm the tree matches the integrated intent, not just a conflict-free state.

Semantic Coherence Checklist

Shared gated checklist. All modes walk it: the implementer as pre-handoff self-check, the reviewer as verification. It defines when semantic-merge is done — the merge's meaning is fully represented in the tree. Walk every item. A merge scoped trivial per §Scope the merge first satisfies the intent-preservation and resolution items by construction — there is no overlapping cluster to classify or synthesize — so confirm the verification items and move on; the stale-reference sweep is what validates the trivial scoping. [BLOCKING] items must be satisfied for the sync to be accepted; [ADVISORY] items may be flagged without blocking.

Intent preservation:

• [BLOCKING] Incoming intent understood from commits, diffs, docs, and caller context.
• [BLOCKING] Governing baseline and direction identified before conflict resolution.
• [BLOCKING] Each overlapping cluster classified by role (behavior/API, data/schema, docs/narrative, generated outputs, tests, config/build) before resolution.
• [BLOCKING] No silent losses from either side; dropped hunks have a documented rationale.
• [BLOCKING] No silent restorations of base-current deletions or relocations in workflow Sync.
• [ADVISORY] Synthesized changes are coherent and minimal.

Scope boundary (semantic coherence stopping rule):

• [BLOCKING] Stale references within the merge's semantic reach are resolved (per Step 6).
• [BLOCKING] Generated outputs made stale by the merged sources are regenerated, or — when regeneration would change a meaningful result — escalated per Step 4 and recorded in the sync record.
• [BLOCKING] Docs and comments that describe the merged code are updated to match.
• [BLOCKING] Existing protection passes on every commit landed by this skill (per Step 5).
• [BLOCKING] Broader codebase-coherence work is left to refactor-and-integrate; the sync record explains codebase-review context but does not define unresolved semantic-sync targets.

Intent integrity:

• [BLOCKING] Intent-changing choices were escalated, folded into the relevant task objective, and implemented as stated.
• [BLOCKING] Data-discipline artifacts and drift tests were preserved.
• [BLOCKING] Meaningful result changes were not silently accepted or re-expected.

Sync record:

• [BLOCKING] Task files remain coherent after the sync when present.
• [BLOCKING] Task-structure changes were routed through superplan §User Feedback and Changing the Task Tree before adaptation proceeded.
• [BLOCKING] Affected tasks carry a ## Sync Impact section (per references/workflow-sync-author.md) when workflow Sync leaves task-specific context needed to understand the post-sync diff.

Verification:

• [BLOCKING] No conflict markers remain.
• [BLOCKING] Stale-reference sweep covered labels, paths, docs, and generated outputs — not just absence of conflict markers.
• [BLOCKING] Targeted checks were run or explicitly reported as not applicable.
• [BLOCKING] Dirty-state stash (when used) was reported in the status return so the user can restore it.

Exception

Orchestrator-managed parallel worktrees bypass this skill. Branches matching <current-branch>-agent/parallel/<slug> merge with plain git merge --no-ff; the merge-guard hook exempts */parallel/* source refs.