Recover from an Interrupted Consolidation
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Learn how to resume or abort a spec-kitty consolidate run that was interrupted before it completed.
Why Consolidation Runs Can Be Interrupted
A spec-kitty consolidate operation touches multiple git refs in sequence (lane branches → mission branch → target branch). It can be interrupted by:
- Network loss during a
git pushafter consolidation - 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/runtime/merge/<mission_id>/state.json before exiting. This file records which WPs have already been consolidated and which remain, so the operation can be resumed without re-doing completed work.
One exception decides whether there is anything to resume. A run that fails after it started moving branches rolls back: if the rollback restored every branch it moved, the run also drops that attempt’s recorded baseline and snapshot, so its record no longer describes a half-finished landing — a later run re-derives the target’s current tip as its pre-mutation baseline instead of attempt 1’s. Resume still works (it re-derives the target baseline; the coordination anchor is kept on a coordination topology), and --abort still works (it clears what is left), but a re-run is the straightforward next step: spec-kitty consolidate --mission <slug>. See A failed run that rolled back completely drops its baseline.
Resuming with --resume
Once the blocking condition is resolved (conflict fixed, push retried, etc.), run:
spec-kitty consolidate --resumeThis reads .kittify/runtime/merge/<mission_id>/state.json, skips already-completed WPs, and continues from the current WP. A resume reads the strategy and the target branch recorded in that file, so you do not repeat --strategy or --target. A --strategy that contradicts the recorded one is refused, and an explicit --target takes precedence over the recorded target.
A worktree that shows staged deletions after an interruption
A run that is interrupted after it advanced a branch, but before it refreshed the
worktree that has that branch checked out, leaves the worktree behind its own
HEAD. git status there shows the newly integrated files as staged deletions.
They are the integrated work read in reverse.
Do not commit, stage or stash them. Committing them reverts the work that was
just integrated; a later consolidate then fails with APPROVED_CONTENT_MISSING
and rolls back.
Run spec-kitty consolidate --resume instead. When the worktree only lags its
own HEAD, the resume refreshes it in place and continues. This applies to the
repository root checkout, the coordination worktree, a mission worktree and a
lane worktree.
The resume refuses, before it changes anything, in these cases:
- The worktree lags and also holds an edit of your own (coordination,
mission or lane worktree). The refusal prints the exact commands, in this
order: save your edit as a patch outside the worktree (
git diff --binary), refresh the worktree (git reset --hard HEAD), runspec-kitty consolidate --resume, and only then re-apply the patch (git apply). Follow them as printed;git stashis ruled out by name because popping the stash after the refresh deletes the integrated files again. - A git
index.lockis left behind. The checkout state is unknown. Confirm that no other git process is running, remove the lock file named in the message, and resume.
Exit code 75: the landing stands, the cleanup did not finish
spec-kitty consolidate exits with code 75 and a message ending in
Error code: COORD_MOVED_AFTER_LANDING. when the landing was verified and the
coordination branch (or the mission branch of a Mission without a coordination
topology) then received a commit before it could be deleted. The branch is kept,
the late commit is intact and the target is not rolled back.
- Coordination branch: review the late commit(s) with the
git logcommand in the message, then runspec-kitty consolidate --resume. It lands the late commit(s) on the target and finishes the teardown. - Mission branch without a coordination topology: land the commit(s) that belong on the target yourself, then delete the branch.
The lane workspace contexts are committed on teardown
consolidate tombstones each lane’s .kittify/workspaces/<slug>-<lane>.json when
it removes that lane’s worktree. Those tombstones are committed as one scoped
bookkeeping commit, so a landed run ends with a clean target branch even in a
project that tracks those files; the commit is skipped when nothing tracked was
removed, and a --push run pushes it too. If the commit cannot land (a
protected-ref refusal, a concurrent move), the run warns and names the paths
rather than failing a merge that already landed — commit them yourself before
the next consolidate.
What a resume lands from the coordination branch
A --resume that finishes the teardown projects every coordination record the
coordination branch changed since the merge began — review-cycle files,
tracer files, the decision log and the status pair, and a gate-matrix commit
such as spec-kitty agent issue-verdict. The window starts at the snapshot the
consolidation persisted before it touched anything, so it reaches back to the
START of the merge; it is not limited to what landed after the landing was
verified. That is why the remedy for a COORD_TEARDOWN_KEPT_ONLY_COPY (exit
76) refusal is to commit the files it names on the coordination branch and
resume: the resume carries them across instead of deleting them with the branch.
The resume proves that before it deletes anything, and refuses when it cannot:
- It will not bring a gate-matrix copy forward that would drop a row the target
already holds, or turn an established judgment (a terminal issue-matrix
verdict, a
passacceptance criterion, a terminal negative-invariant result) into a non-established one. - It will not express a deletion. A coordination record the window deletes does stay on the target — a projection can only bring content forward — so the resume REFUSES the window instead of treating the deletion as landed.
- It refuses if any change made in that window is not on the target: a coordination record, a status event, or a file the target authors for itself (see What the late window proves).
This is stricter than earlier releases. On ANY --resume — not only one
that follows COORD_TEARDOWN_KEPT_ONLY_COPY — a window that holds a record the
resume cannot land (a deleted record, a copy that would lose evidence, an
unreadable matrix) now makes spec-kitty consolidate exit 1, where it used to
exit 0 and let the record vanish with the coordination branch. The message ends
with Error code: COORD_LATE_PROJECTION_REFUSED.
A refusal there names the file, exits 1 and keeps the coordination
branch, its worktree and the Mission’s coordination marker together, so nothing
is lost and nothing is rolled back. spec-kitty consolidate --abort does not
clear it: the landing is already verified, so an abort keeps it and refuses too.
What to do depends on the refusal, and each one names its own repair:
- A coordination copy that would drop or overturn a judgment the target
holds: fix the copy on the coordination branch — commit the newer
judgment there (
spec-kitty agent issue-verdict …), or revert the coordination commit that regressed it — then runspec-kitty consolidate --resumeagain. Do not copy it onto the target: that writes the stale or regressing bytes over the judgment the guard just protected. - A coordination copy that cannot be read: rewrite it on the coordination
branch as the document its own writer produces (
spec-kitty agent issue-verdictforissue-matrix.json,spec-kitty acceptforacceptance-matrix.json), or revert the commit that corrupted it. - A target gate matrix that cannot be read: repair the target’s copy and commit the repair on the target — the guard will not overwrite the target’s acceptance evidence until it can prove what that copy holds, so restoring it from the target branch would hand back the same unreadable bytes. A repair commit moves the target off the verified landing, so the next resume stops at the branch-move guard, whose message prints the command that releases the move and clears the record; delete the coordination branch by hand afterwards.
- A coordination record deleted in the window: restore it on the coordination
branch — revert the commit that removed it, or
git checkout <sha-before-the-deletion> -- <path>there. A projection can only bring content forward, and the target still holds the record. - A coordination record that is not on the target: land it on the target from
the coordination branch (
git checkout <coordination-branch> -- <path>in the target checkout, then commit it), or, if it must not exist at all, delete it on both branches. - A status event that is not in the target’s log: the resume folds the
coordination worktree’s working-tree
status.events.jsonl, not the coordination branch’s commits, so add the missing events to that copy. Save a copy of the file first, then append each line ofgit show <coordination-branch>:<the log the refusal names>whoseevent_idit does not already hold, and keep every line it has. Do not check the branch file out over it: the working-tree log can hold events nobody has committed yet. You can instead append the events to the target’s log the same way and rematerializestatus.jsonfrom the union. Do not copy the coordination file over the target’s log either: that would drop the events the target already holds. - A status log that cannot be reconciled:
status.events.jsonlon the coordination branch either does not parse as events, or carries an event id with different bytes than the target’s log — the pair the merge’s own event union refuses. Repair it on the coordination branch: revert the commit that corrupted or forked it, or rewrite the event so the two sides agree, then runspec-kitty consolidate --resumeagain. Checking the same bytes out into the coordination worktree cannot help: they are the bytes the union already refused. - A file the target authors for itself (for example
meta.json) that the target’s copy does not carry: merge your intended change into the target’s own copy by hand and commit it, or revert the coordination commit that made it. Do not check the coordination file out over the target’s: that replaces the mission number, baseline stamp and marker the target owns — the exact overwrite a consolidation refuses to perform — with the stale coordination bytes. A consolidation never projects these files, so the merge is the operator’s call. Committing on the target yourself moves it off the verified landing, so the next resume may stop at the branch-move guard, whose message prints the command that releases the move and clears the record.
Then run spec-kitty consolidate --resume again.
What the late window proves
Before the coordination branch is deleted, every change the window made inside the Mission directory is accounted for, on a first run and on a resume alike. Each one is either landed on the target, or excluded by a rule that says why its bytes carry nothing the target lacks:
- Landed: the file is byte-identical on the target branch.
- Landed by the status union: every event id committed to the coordination
branch’s
status.events.jsonlis present in the target’s committed event log. The two logs must also reconcile: an event id carrying different bytes on the two sides is refused, exactly as the merge’s own event union refuses it. - Derived, so not proved:
status.jsonis a reduced snapshot the consolidation rematerializes from the unioned event log, so its own bytes are not an independent record — but only while the target’s committed snapshot really is that reduction. A Mission with no event log keepsstatus.jsonas a record, and it is judged like any other document. - Carried by the target’s own copy: a document the target authors for itself
(for example
meta.json) when the change the window made is already on the target’s committed copy. The comparison is the change since the window began, not the whole file, because the merge legitimately rewrites other fields there (the mission-number bake, the baseline stamp). A key the window removed must be absent from the target; a key nobody touched is not compared. - A rename is judged by both halves: the new path must be on the target, and the old one must not still be there.
Anything else refuses, keeps the coordination branch, worktree and marker, and names the repair above. A change to a file the target does not carry is never approved just because the consolidation did not project it.
The other codes consolidate can report are listed in the
CLI reference.
What a run lands before it tears down
Both run kinds project and prove the late window before the coordination branch is deleted; they differ only in where that window starts.
A first run (no --resume) gets the protection over a narrower window. The
merge records the coordination tip it verified — its own last write to the
coordination branch, after everything it was going to project had been projected
(the following bookkeeping commit lands it) — and
anything committed to the coordination branch after that tip is late by
definition. Before the branch is deleted, a first run projects that window and
proves it landed, exactly as a resume does:
- A late record that can be landed is committed on the target, then proven there, and only then does the coordination branch go.
- A record that cannot be landed (a deletion, a copy that would lose evidence, an
unreadable matrix, a status event the union could not see, a target-authored
file the target does not carry) refuses with
Error code: COORD_LATE_PROJECTION_REFUSED., keeps the coordination branch, worktree and marker, and names its own repair — the same per-kind remedies listed above. - A run where nothing landed late projects nothing and makes no extra commit, so a clean consolidation behaves exactly as it did before.
A resume’s window is wider on purpose — it spans everything the coordination branch changed since the merge began, because a resume has no in-memory record of what the interrupted attempt verified — and it uses the same projection and the same proof.
Once a run has proven the window landed, that tip becomes the tip the projection teardown gate and the branch delete approve, on either run kind. So a resume that lands a commit made after it captured its own coordination tip finishes the consolidation instead of refusing a landing it just completed.
The window is read once, at the coordination tip the teardown opened it on. A
commit that lands on the coordination branch while the teardown runs is not in
that window: unless it is a status event in the worktree, which the union folds in, it is not projected, the approved tip does not move to it, and the
teardown refuses at the projection teardown gate with the branch kept. Run
spec-kitty consolidate --resume again, and the next window judges it: a status
event or coordination record lands or is refused with its remedy, and a change to
a primary artifact such as meta.json is refused until it is on the target.
A Mission whose coordination directory is named <slug>-<mid8> (a bare-slug
Mission) gets the same proof for that directory, against the target’s copy. Nothing
is projected from it, so a record committed there is refused until you copy it to
the same relative path under the target’s own Mission directory, or revert it on
the coordination branch.
This closes the window where a verification or status write made between the gate and the teardown was refused after a landing that was already complete, leaving you to hand-assemble it. A first run that recorded no coordination tip has no window to build and is still unprotected: such a commit can be lost with the branch (#7121). A commit made while the merge is running, before that tip is captured, is not judged on a first run either (#7300).
Aborting a Consolidation
To undo what an interrupted run moved and discard its record:
spec-kitty consolidate --abort--abort first restores the branches the run moved: the target branch, the mission branch and the coordination branch. Each branch goes back to the commit it had before the run, and only while it is still at the commit this run recorded. A commit that someone else added since then is never overwritten. It clears the record only after every branch is restored.
The command prints a rollback report that starts Rollback to the pre-consolidation snapshot:, with one line per branch:
restoredshows the commit the branch left and the commit it returned to.unchangedmeans the branch was already at its snapshot.NOT restorednames the branch, the commit observed and the commit expected, and the reason. A branch moved by another actor, or one that moved without a recorded tip, is reported this way.
What happens next depends on the report:
-
Everything restored. The command prints
Aborted consolidation for <mission>and exits 0. It also aborts a git merge left in the Mission’s own scratch workspace, removes that workspace, and releases the merge lock it took. -
A branch is
NOT restored. Nothing was cleared, and the command exits 1. UnderNext steps:the report names one step per branch, by cause, each of which completes the abort:- A checkout holds local changes: commit or stash the changes in the named checkout, then re-run
spec-kitty consolidate --abort. - Another actor moved the branch: inspect the commits it shows (
git log <expected>..<observed>); to keep them and finish the abort, runspec-kitty consolidate --abort --release-branch <branch> --release-reason "<why>". - The branch no longer exists: recreate it with the
git branch <branch> <sha>command the report prints, then re-runspec-kitty consolidate --abort. - The restore was refused (the branch moved while it was being restored, or git failed): inspect it (
git log -3 <branch>), then re-runspec-kitty consolidate --abort. - The coordination worktree holds a change that is not the tool’s own: commit or stash it there, then re-run
spec-kitty consolidate --abort.
The report then closes with
Kept the consolidation record so nothing is lost; complete the next steps above to finish the abort. - A checkout holds local changes: commit or stash the changes in the named checkout, then re-run
-
The landing was already verified. The command prints
Kept the landing verified by an earlier reconciliation, rolls nothing back, exits 1 and keeps the record. A verified landing is never rolled back, so--abortcannot finish here; its next step isspec-kitty consolidate --resume, which finishes the teardown of that landing. -
The record has no snapshot (written by an older release). The command prints a notice that no branch is restored, clears the record and exits 0.
-
Another Mission’s consolidation holds the merge lock and is still active. The command refuses, exits 1, and restores and clears nothing. Finish or abort that consolidation first.
Lane branches are never moved by a consolidation, so --abort never moves them. A lane branch that was deleted since the run began is reported with the git branch command that recreates it, and does not block the abort.
--abort does not touch a git merge in progress in your own checkout. For a Mission with a coordination topology, it also removes the coordination worktree unless the Mission’s meta.json retains worktrees (retain_worktrees); it then prints a notice.
The consolidation state file
.kittify/runtime/merge/<mission_id>/state.json is written atomically at each WP boundary. Fields:
| Field | Type | Description |
|---|---|---|
mission_slug | str | Mission slug being consolidated (e.g., 017-my-mission) |
target_branch | str | Branch being consolidated into (e.g., main) |
wp_order | list[str] | Ordered WP IDs for the full consolidation sequence |
completed_wps | list[str] | WPs already successfully consolidated |
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 consolidation start |
updated_at | str | ISO 8601 timestamp of last state write |
The file also holds the snapshot of the branches taken before the run moved anything, which --abort restores from. Do not edit or delete it. Use --resume or --abort.
Consolidation Strategy Selection
The strategy is set at the start of a consolidation run with --strategy. Values are lower-case; --strategy SQUASH is rejected.
| Strategy | Effect |
|---|---|
merge | Creates a merge commit; preserves full lane history. |
squash | Collapses all lane commits into one commit on the target branch. Default. |
rebase | Replays commits linearly; may conflict with remote linear-history protection if the branch was already pushed. |
spec-kitty consolidate --strategy squashspec-kitty consolidate --strategy rebase --target mainOnce a consolidation run is started with a strategy, that strategy is stored in state.json and used automatically on --resume.
Manual Git Fallback
If spec-kitty consolidate --resume keeps failing, do not finish the landing with git merge, and do not delete state.json.
- A landing made by hand skips the reconciliation gate and the done bookkeeping that
consolidaterecords. state.jsonholds the snapshot of the branches before the run moved anything. Deleting it removes what--abortneeds to restore them.
Do this instead:
# 1. Read the progress and the recorded branch tips (read-only).cat .kittify/runtime/merge/<mission_id>/state.json
# 2. Undo the run and clear the record.spec-kitty consolidate --abortFix the cause the refusal named, then run spec-kitty consolidate again.
If the rollback restored every branch, the record was re-baselined and there is nothing for --abort to restore: it prints Aborted, clears the record and exits 0, and --resume re-derives the target baseline rather than reusing the failed attempt’s. Read the state file only when the run left a branch NOT restored.
If --abort reports NOT restored for a branch, that branch holds a commit the run did not record. Inspect it, resolve it, and run --abort again.
See Also
- Merge Feature — full merge workflow
- Recover from Implementation Crash — when a WP is stuck mid-implementation
- CLI Reference: spec-kitty consolidate