Loom Merge Queue Worker

Purpose

Process merge queue items for a Loom team's merge worker role.

When To Use

• You are configured as a merge worker (ROLE: merge, WORKTREE: team/merge-queue)
• Running loom team wait wakes you with queue items

Constraints

• Do NOT implement features; ship only manager-approved branches
• You do NOT ship to main. You only merge into the merge-queue branch shown above
• If your merge worktree is wedged, ask the manager to run: loom team spawn-merge <TEAM> --force
• Use loom team merge commands for deterministic queue operations

Procedure

1. Claim next item

loom team merge <TEAM> next --claim-by merge

2. Ensure merge-queue is current

git fetch origin
git merge origin/main --ff-only

3. Stash any local changes

If git status shows unstaged changes, stash them first:

git stash push -m "Merge preparation for <ticket_id>"

4. Merge the feature branch

git merge <branch> --no-ff -m "Merge <branch> into merge-queue (ticket: <ticket_id>)"

Handle Merge Conflicts

If merge fails with conflicts:

For compound-managed files (AGENTS.md, LOOM_ROADMAP.md, etc.)

git checkout --theirs AGENTS.md LOOM_ROADMAP.md
git add AGENTS.md LOOM_ROADMAP.md

Rationale: Compound blocks are auto-generated; accept incoming version.

For dependency files (pyproject.toml, uv.lock, egg-info/)

git checkout --theirs pyproject.toml uv.lock
git checkout --theirs src/vibe_piper.egg-info/PKG-INFO
git checkout --theirs src/vibe_piper.egg-info/requires.txt
git add -f pyproject.toml uv.lock src/vibe_piper.egg-info/

Rationale: Accept incoming dependencies; newer branches add new optional deps.

Complete the merge

git commit -m "Merge <branch> into merge-queue (ticket: <ticket_id>)"

5. Mark as done

loom team merge <TEAM> done <ITEM_ID> --result merged|blocked --note "..."

Use one of:

• --result merged for successful merges
• --result blocked for unresolvable merge conflicts

Handling No-Op Merges

When git merge returns "Already up to date"

This means commits are already in merge-queue history, even if Loom reports them as "NOT in merge-queue".

Verify first-parent history

git log --oneline --first-parent team/merge-queue | grep <commit_hash>

If not in the first-parent chain, it's a no-op due to a prior main → merge-queue sync.

Mark as done with an explanatory note

loom team merge <TEAM> done <ITEM_ID> --result merged --note "Branch already merged (commits already in merge-queue). Merge was a no-op as expected."

Why this happens

• The feature branch was merged into main
• Main was merged into merge-queue
• When merging the feature branch again, it's a no-op
• The commits are in the full history, just not in the merge commit chain

Queue Ops Reference

• Claim next: loom team merge <TEAM> next --claim-by <worker>
• Mark done: loom team merge <TEAM> done <ITEM_ID> --result merged|blocked --note "..."
• Manager ships: loom team ship <TEAM> --push
• List queue: loom team merge <TEAM> list

Idling

If no work, run loom team wait 10m and stop output.

Manual notes

This section is preserved when the skill is updated. Put human notes, caveats, and exceptions here.