Semantic Merge

Semantic Merge

Integrate branches by intent, not by lines: understand what each side was achieving, synthesize where both changes are valid, escalate decisions that change what the branch means to the user, leave a trail later agents can follow.

Treat conflicts as intent conflicts first, line conflicts second. Intent-changing conflicts always go to the user; implement their decisions, never override them.

Choose a Mode

Load exactly the mode reference matching 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 §Semantic Coherence Checklist below.

Shared Steps

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.

Dirty worktree with unrelated changes: stash them under a name 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

Size the work from Step 1's conflict status, touched-file set, and incoming range 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.

Trivial merge: land it and run the stale-reference sweep (Step 6) bounded to that near-empty reach — the sweep confirms the third condition held. Skip intent synthesis, the resolution plan, and escalation; they have no overlapping cluster to act on. Record a clean sync. Any condition failing — a conflict, an overlapping file, a rename reaching current-branch code — takes the merge at full depth. Unsure whether overlap or a rename reaches current-branch code: treat it as non-trivial.

2. Investigate intent on both sides

Read commit messages, diffs, and any task tree or docs for each side. Current-branch intent: the superRA/ task tree in workflow mode, the branch name, commits, and diffs in standalone mode. Incoming intent: the commit range on the other side of the merge base.

Classify each cluster of changes by role. The role drives its resolution:

• Behavior or API — 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; rewrite stale claims from either side.
• Generated outputs — figures, tables, compiled artifacts, fixtures. Regenerate from merged sources rather than hand-edit 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.

Classify and execute within each role; intent-changing calls — 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, 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 — rewritten self-sufficient with the new context — before committing the resolution. No task tree: 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 leaves the tree passing the 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 producing them — commit messages plus task-local ## Sync Impact sections in workflow mode, the commit body in standalone mode. Broader codebase-coherence work belongs to refactor-and-integrate. The sync record may capture context explaining the post-sync diff for later codebase review; it never carries unresolved semantic-merge work into Integrate.

6. Detect and resolve stale references

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

• 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. Fix stale references following 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

Semantic-merge is done when the merge's meaning is fully represented in the tree. The implementer walks this as a pre-handoff self-check; the reviewer walks what its focus covers. A merge scoped trivial per §Scope the merge first satisfies the intent-preservation and resolution items by construction — confirm the verification items and move on. [BLOCKING] items must be satisfied for the sync to be accepted; [ADVISORY] items are recorded and do not block.

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.

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 escalated per Step 4 and recorded when regeneration would change a meaningful result.
• [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 defines no 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] Stale-reference sweep covered labels, paths, docs, and generated outputs — not just the absence of conflict markers.
• [BLOCKING] Targeted checks were run, or the sync record says why none applied.
• [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.