Table of Contents

Recover from an Interrupted Merge

Learn how to resume or abort a spec-kitty merge that was interrupted before it completed.

Why Merges Can Be Interrupted

A spec-kitty merge operation touches multiple git refs in sequence (lane branches → mission branch → target branch). It can be interrupted by:

  • Network loss during a git push after merge
  • Linear-history branch protection rejecting a merge or rebase commit
  • Process kill (Ctrl-C, timeout, OOM) mid-sequence
  • Merge conflict that requires manual resolution

When an interruption occurs, spec-kitty saves progress to .kittify/merge-state.json before exiting. This file records which WPs have already been merged and which remain, so the operation can be resumed without re-doing completed work.

Resuming with --resume

Once the blocking condition is resolved (conflict fixed, push retried, etc.), run:

spec-kitty merge --resume

This reads .kittify/merge-state.json, skips already-completed WPs, and continues from the current WP. The --strategy and --target values from the original invocation are preserved in the state file and do not need to be repeated.

Aborting a Merge

To discard saved state and abort any in-progress git merge:

spec-kitty merge --abort

This runs git merge --abort (if a merge is in progress) and deletes .kittify/merge-state.json. The worktrees and branches are left intact so you can restart from scratch.

The Merge State File

.kittify/merge-state.json is written atomically at each WP boundary. Fields:

Field Type Description
feature_slug str Mission slug being merged (e.g., 017-my-feature)
target_branch str Branch being merged into (e.g., main)
wp_order list[str] Ordered WP IDs for the full merge sequence
completed_wps list[str] WPs already successfully merged
current_wp str \| null WP in progress when interrupted (null if between WPs)
has_pending_conflicts bool True if git merge conflicts are unresolved
strategy str MERGE, SQUASH, or REBASE
started_at str ISO 8601 timestamp of merge start
updated_at str ISO 8601 timestamp of last state write

Do not edit this file manually. Use --resume or --abort.

Merge Strategy Selection

The strategy is set at the start of a merge with --strategy:

Strategy Effect
MERGE Creates a merge commit; preserves full lane history. Default.
SQUASH Collapses all lane commits into one commit on the target branch.
REBASE Replays commits linearly; may conflict with remote linear-history protection if the branch was already pushed. 
spec-kitty merge --strategy SQUASH
spec-kitty merge --strategy REBASE --target main

Once a merge is started with a strategy, that strategy is stored in merge-state.json and used automatically on --resume.

Manual Git Fallback

If spec-kitty merge --resume itself fails, you can complete the merge manually:

# 1. Check which lane branch needs merging (from merge-state.json)
cat .kittify/merge-state.json

# 2. Merge the lane branch into the mission branch manually
git checkout kitty/mission-<feature>
git merge kitty/mission-<feature>-lane-a --no-edit

# 3. Merge the mission branch into target
git checkout main
git merge kitty/mission-<feature> --no-edit

# 4. Clean up merge state
rm .kittify/merge-state.json

After a manual merge, run spec-kitty upgrade to ensure any post-merge hooks (worktree cleanup, status events) complete correctly.

See Also

Edit this page