Hierarchical Merge Skill

Purpose

Validate and enforce the Hierarchical Merge Protocol (HMP) which ensures branches merge to their parent branch, not directly to main. This creates controlled convergence through parent-child relationships.

When to Use

• Before merging any feature/task branch
• When completing work in a worktree
• Before closing a sprint or feature branch
• When validating branch structure

Trigger Phrases

• "merge this branch"
• "ready to merge"
• "complete this task"
• "close this branch"

Protocol Rules

Core Principle

Branches merge to their PARENT branch, not directly to main.

Merge Direction

Child Completion Constraint

A branch can ONLY merge to its parent when ALL children are complete:

• Child branch has been merged back (or abandoned with record)
• Associated worktree has been removed
• tasks.md status is COMPLETED

Exception Prefixes

These prefixes bypass the Child Completion Constraint:

• bugfix/* - Bug fixes that shouldn't wait
• hotfix/* - Critical production fixes
• emergency/* - System-critical changes
• selective/* - Intentional partial merge (documented)
• partial/* - Known incomplete work (documented)

Validation Checklist

Before allowing merge:

[ ] All child branches merged or abandoned
[ ] All child worktrees removed (git worktree prune)
[ ] tasks.md entries show COMPLETED
[ ] No active lock files for child branches
[ ] CI/CD passes
[ ] Code review approved (if required)

Commands

# Verify children are complete
git branch --list "feature/task-A*" | wc -l  # Should be 1

# Merge to parent (not main!)
git checkout feature/sprint-01
git merge --no-ff feature/task-A -m "merge: task-A complete"

Anti-Pattern Warning

NEVER merge directly to main from a subtask:
  git checkout main
  git merge feature/subtask-A1  # WRONG!

CORRECT approach:
  git checkout feature/task-A
  git merge feature/subtask-A1  # Merge to parent first

Integration

• Uses tasks.md for completion status
• Integrates with worktree cleanup
• Enforced by pre-merge validation

Skill based on Hierarchical Merge Protocol v1.0 | multi-agent-os