Skip to content

How to Merge a Mission

Who is this for (1)

Use this guide to land a Mission’s approved work packages on its target branch with spec-kitty consolidate.

consolidate lands the lane branches on the mission branch, then lands the mission branch on the local target branch. It never publishes to origin unless you pass --push. Publish through a topic branch and a pull request.

Prerequisites

  • Every WP is approved or done.
  • You ran acceptance. See Accept and Merge.
  • The repository root checkout is on the target branch and has no uncommitted changes. Lane worktrees have no uncommitted changes either, unless you keep them with --keep-worktree.

Quick Start

Run the command from the repository root checkout.

In your agent:

/spec-kitty.consolidate

In your terminal:

Terminal window
spec-kitty consolidate --mission 015-user-authentication

--mission names the Mission; it accepts the slug, the mid8 or the Mission ID. The command was renamed from spec-kitty merge, and the old name now exits with an error. Replace it in scripts and notes.

If a run stops, see How to Troubleshoot Merge Issues.

Preview with Dry-Run

Terminal window
spec-kitty consolidate --mission 015-user-authentication --dry-run

A dry run changes nothing. It prints the resolved plan as JSON: the strategy, the target branch, the mission branch, the lanes, whether branches and worktrees will be deleted, whether --push is set, and the mission number the run would assign. Add --json for plain JSON output; --json works only with --dry-run.

The dry run stops with a blocker, and exits 1, when the real run would refuse for a reason it can check in advance. The blockers include a review-artifact conflict and TARGET_BRANCH_CONTENT_CONFLICT. See Target-Branch Content Conflicts During Squash.

Strategies

--strategy sets how the mission branch lands on the target branch. The lane-to-mission step always uses merge commits.

StrategyEffect
squashLands the mission branch as one commit. This is the default.
mergeLands the mission branch with a merge commit.
rebaseRebases the mission branch onto the target branch, then advances the target branch to the result.

Values are lower-case:

Terminal window
spec-kitty consolidate --mission 015-user-authentication --strategy merge

To set a project default, add this to .kittify/config.yaml:

merge:
strategy: merge

The order is: --strategy, then merge.strategy, then squash. A value outside merge, squash and rebase in the config file is an error. A resumed run keeps the strategy of the interrupted run.

Restack onto a Newer Dependency Branch

Sometimes a Mission is built on another branch that is still moving — a shared component, a platform refactor — and it must pick up that branch’s newer head before it lands. Merge that head into the lane that depends on it, with a real merge so the reviewed commits are not rewritten, then have the lane reviewed again on the merged tree:

Terminal window
git switch kitty/mission-<slug>-lane-b
git merge --no-ff <dependency-branch>

consolidate treats every commit a merge’s second parent brought in as content no approved work package authored, so an undeclared restack is refused with an un-attributable verdict under both strategies (--dry-run refuses it too). Declare the dependency once, on the preview and on the real run:

Terminal window
spec-kitty consolidate --mission 015-user-authentication --dependency-ref <dependency-branch> --dry-run
spec-kitty consolidate --mission 015-user-authentication --dependency-ref <dependency-branch>

--dependency-ref is repeatable and is a spec-kitty consolidate flag only: orchestrator-api consolidate-mission cannot declare one and refuses an undeclared restack. The ref is recorded on the run and pinned to the commit it named when the claim was built, so --resume rebuilds the same claim; if the name has moved by the gate or the resume, the run refuses (DEPENDENCY_REF_MOVED). A --resume that names a different set is refused too (consolidate --abort first). A declaration is verified before anything lands: the ref must resolve, the mission branch or one of its lane branches must reach it, and no commit of any lane’s own history or of the mission branch may sit in it, and it may not be named in the Mission’s own branch namespace or hold a head a work package recorded. The check recognizes Mission work only by what the Mission recorded: a raw-SHA declaration skips the branch-name guard, and a removed work package that left no recorded lane head, no lane-tip ref and no namespaced branch cannot be detected, so declare only a branch you know is external. A declaration that covers mission-authored work is refused — that is what keeps a removed work package from riding a carrier lane — and the declared commits are attributed as inherited history, never to a work package.

Target Branch

By default consolidate lands on the Mission’s recorded target branch. Override it only when you intend a different destination:

Terminal window
spec-kitty consolidate --mission 015-user-authentication --target develop

--target moves only the landing. The rest of the run still writes its bookkeeping (the work packages’ done transitions on a Mission without a coordination branch, and the coordination flatten) to the recorded target, from the repository root checkout. That checkout must be on the --target branch, so it cannot commit to the recorded one. The run is then refused before anything moves, with TARGET_OVERRIDE_RECORDED_TARGET_UNWRITABLE. --dry-run reports the same code (#5783). To land on a branch other than the recorded one, make it the Mission’s recorded target with --retarget (see below). You can still change target_branch in the Mission’s meta.json by hand, commit that, and run consolidate without --target.

Retarget the Mission

--retarget makes the --target branch the Mission’s recorded target in this run. Every write of the run then lands there: the landing, the work packages’ done transitions and the coordination flatten. Use it when the branch you deliver to changed after the Mission was created, for example a develop branch cut from main.

Terminal window
git checkout develop
spec-kitty consolidate --mission 015-user-authentication --dry-run --json --target develop --retarget
spec-kitty consolidate --mission 015-user-authentication --target develop --retarget --retarget-reason "release train moved"
git show develop:kitty-specs/015-user-authentication/meta.json

The forecast adds "retarget": {"from": "main", "to": "develop"} to its JSON and reports the same refusal codes as the real run. --retarget needs --target, and --retarget-reason needs --retarget. Either one alone is a usage error: exit 2, nothing moves. Naming the recorded target again is not a retarget.

What is recorded. The first change the run makes is a commit of the Mission’s meta.json. It sets target_branch to the new target and appends one entry to retarget_history: from, to, actor, at and reason. The history keeps the newest 20 entries. The default reason is operator retarget via spec-kitty consolidate --target <branch> --retarget. The commit is made on every branch whose tree carries the Mission’s meta.json: the Mission branch (for a Mission created without --topology, its topic branch) and the new target when it carries the file. lanes.json is not rewritten.

On a Mission created without --topology, the commit is made on the topic branch. The default squash landing folds it into the landing, so the new target shows no separate retarget commit. retarget_history holds exactly one entry.

Refusals. Each one is reported before any branch moves.

CodeWhenNext step
RETARGET_RECORD_UNWRITABLENeither the Mission branch nor the new target carries the Mission’s meta.json. Or the new target carries it, but the repository root checkout is not on the new target, or meta.json there is untracked or has an uncommitted edit.Consolidate into the recorded target; or integrate the recorded target into the new one first. For a checkout problem: git checkout <branch>, commit or discard the edit, then re-run.
RETARGET_RECORD_UNWRITABLEThe new target carries the Mission’s meta.json, and in the repository root checkout the file has the skip-worktree or assume-unchanged bit, even with no edit.Clear the bit with the command the message prints (git update-index --no-skip-worktree <path>, git update-index --no-assume-unchanged <path>, or both when the file carries both), then re-run.
RETARGET_RECORD_UNWRITABLEThe new target does not carry the Mission yet, and the repository root checkout, on the new target, has untracked files under kitty-specs/<slug>/ that the landing would overwrite.Remove the untracked copies, or move them aside, then re-run.
RETARGET_WRITE_BRANCH_IS_RECORDED_TARGETA single_branch Mission created with --commit-to-target: its work is written on the recorded target itself. A retarget would land that branch and then delete it.Consolidate into the recorded target, then integrate it into the new one with git.
PROTECTED_BRANCH_REFUSEDThe new target is protected (#6464), or the workflow mutation policy would refuse the done bookkeeping on the new target (#5385).Pick an unprotected target.
RETARGET_RESUME_MISMATCHThe run record holds a retarget from an earlier run, and this run names another target, with or without --retarget (--target <old target> included).Re-run with --target <recorded new target> --retarget, or a bare --resume; or --abort first.

A retarget away from a protected recorded target onto an unprotected branch is allowed: the old target receives nothing. A plain --target without --retarget keeps refusing with TARGET_OVERRIDE_RECORDED_TARGET_UNWRITABLE, and its next step now names --retarget.

Scope. --retarget works on Missions with an explicit lanes or lanes_with_coord topology, and on Missions created without --topology once finalize-tasks has settled them to lanes_with_coord or single_branch. --attest-* flags given with --retarget follow the retarget: on a Mission without a coordination branch, their status events land on the new target. orchestrator-api consolidate-mission cannot retarget, because it has no rollback. A target that differs from the record still fails there with PREFLIGHT_FAILED and TARGET_OVERRIDE_RECORDED_TARGET_UNWRITABLE. While a run record holds a retarget, it fails with PREFLIGHT_FAILED and RETARGET_RESUME_MISMATCH for any target. Finish the retarget with spec-kitty consolidate --resume, or drop it with --abort.

Abort and resume. If the run fails after the retarget commit, it restores the new target and the Mission branch to their tips from before the run. That includes the status events of --attest-* flags given with --retarget on a Mission without a coordination branch: they are part of the run, so they are undone with it. After a kill, a re-run or --resume that then fails undoes them too, and so does --abort once the killed run had taken its snapshot. Pass the --attest-* flags again on the re-run: a bare --resume does not record them and fails the same claim check. They are kept by a refusal before the first branch moves (for example a claim-time refusal), as on any run; by a kill between the attestation commit and saving the run record; and by --abort after a kill before the snapshot, which has nothing to restore and only clears the record. The retarget stays in the run record. A bare spec-kitty consolidate --resume, or a re-run, applies it again. spec-kitty consolidate --abort drops it. If the run is killed between the retarget commit and saving the run record, a bare spec-kitty consolidate --resume finishes the run. It exits 0 and lands with exactly one retarget record. No --release-branch is needed (tests/terminus/test_consolidate_retarget_resume.py).

Skip-worktree entries in the target’s checkout

consolidate writes its bookkeeping (the Mission’s meta.json and status files) in the checkout of the target branch, and resyncs every checkout of the target or the Mission branch when it moves them. A skip-worktree bit on a file under kitty-specs/<slug>/ hides the run’s own write from its bookkeeping commit. The post-merge check then fails, and the rollback cannot resync the checkout over the edited file, so the landing stays staged there. A run is therefore refused before any branch moves, with CHECKOUT_SKIP_WORKTREE_ENTRIES, when such a checkout has a skip-worktree entry under kitty-specs/<slug>/ or on a path the Mission’s branches change. Entries on the changed paths are refused to be safe: an edit under the bit does not show in git status and would be overwritten or block the resync. An unedited one would land, but is refused too. --dry-run and orchestrator-api consolidate-mission report the same code. Clear the bit, then re-run:

Terminal window
git update-index --no-skip-worktree kitty-specs/015-user-authentication/meta.json

Entries a sparse checkout excludes have no file and are not refused. The assume-unchanged bit is not refused either, except under --retarget, where the record commit refuses it (RETARGET_RECORD_UNWRITABLE). Listing the index expands a sparse index in memory.

Cleanup Options

After a successful landing, consolidate removes the lane worktrees and deletes the lane branches. Each flag pair overrides that default for one resource:

Terminal window
spec-kitty consolidate --mission 015-user-authentication --keep-worktree
spec-kitty consolidate --mission 015-user-authentication --keep-branch
spec-kitty consolidate --mission 015-user-authentication --keep-worktree --keep-branch

--remove-worktree and --delete-branch state the default explicitly. They also override a Mission’s retention policy.

Mission Retention Policy

A Mission can record a standing retention policy in its meta.json: retain_branches: true, retain_worktrees: true, or both. The policy is absent unless you set it, so a Mission that never opts in keeps the default cleanup.

Effective cleanup follows this order:

  1. An explicit flag (--keep-branch or --delete-branch, --keep-worktree or --remove-worktree).
  2. The meta.json retention policy.
  3. The default: delete branches and remove worktrees.

retain_branches acts as --keep-branch, and retain_worktrees acts as --keep-worktree. Retention is never silent:

  • With no flag and a retaining policy, consolidate keeps the resource and prints a warning that names meta.json as the source.
  • An explicit --delete-branch or --remove-worktree against a retaining Mission proceeds and prints a notice that the flag overrode the policy.
  • A corrupt meta.json stops the run with an error. A retention value that is not a boolean counts as retain and prints a warning.
  • --dry-run shows the resolved decision, with a retention object that names its source.

For a Mission with a coordination topology, the coordination branch, its worktree and its marker in meta.json are kept or removed together. They are removed only when branches are deleted and worktrees are removed. Keeping either one keeps all three. --abort follows the same rule for the coordination worktree.

The private scratch worktree that consolidate uses under .kittify/runtime/merge/<mission_id>/workspace is not a retained resource. It is always removed.

Declaring Retention at Creation

Set the policy when you create the Mission:

Terminal window
spec-kitty agent mission create "<slug>" --retain-branches --retain-worktrees ...

Complete a Direct-on-Target Mission (--skip-lanes)

A direct-on-target Mission commits its work packages straight onto the target branch: no lane branch exists, and there is no kitty-specs/<slug>/lanes.json. --skip-lanes (alias --no-lanes) completes one transactionally:

Terminal window
spec-kitty consolidate --mission 015-user-authentication --skip-lanes

The flag is an explicit opt-in and does nothing for a Mission that has a lanes.json. With no lanes.json to read, the run synthesizes the lanes manifest it needs, and that manifest takes its implementation-evidence base from the target branch’s own history: the target tip immediately before the commit that introduced kitty-specs/<slug>/. (When that commit is the repository root it has no parent and is its own base, so content that root already carries is outside the window.) The evidence window is the net tree diff from that base to the target tip: a path changed and then reverted counts as unchanged, and Mission bookkeeping never counts as implementation.

The review and evidence gates are the same as on any other Mission, and --skip-lanes does not relax them:

  • A work package approved with no change to its owned_files inside that window is refused IMPLEMENTATION_MISSING, unless a no-implementation attestation is in force for it (--attest-no-implementation, recorded on accept or consolidate).
  • An approval recorded by the implementer itself is refused REVIEW_NOT_INDEPENDENT.
  • A work package whose owned_files cannot be read is refused OWNERSHIP_UNRESOLVED, and no attestation lifts it.

When the Mission’s planning artifacts are not in the target branch’s history, no window can be computed and the run refuses EVIDENCE_WINDOW_UNCOMPUTABLE. spec-kitty agent mission finalize-tasks records nothing this gate reads on this topology; commit kitty-specs/<slug>/ on the target branch so the Mission’s start is in history, then re-run.

Publish the Result

consolidate lands on the local target branch only. Publish through a topic branch and a pull request. See When Local main Is Not Publishable and Run an Autonomous Mission.

--push publishes to origin after the local landing. Use it only where your repository’s workflow allows direct pushes to the target branch. With --push, a local target branch that is ahead of, behind or diverged from its tracking branch is refused with TARGET_BRANCH_NOT_SYNCHRONIZED. See How to Troubleshoot Merge Issues.

After Merge

Before you call the Mission done, run the mission review, check the retrospective, and read its findings. See After Consolidation.

Command Reference

FlagWhat it doesDefault
--mission <slug>Names the MissionResolved from the current branch when possible; otherwise the command asks for --mission
--strategymerge, squash or rebasesquash
--target <branch>Target branch for the landingThe Mission’s recorded target branch
--retargetWith --target: make that branch the Mission’s recorded target in this run. See Retarget the MissionOff
--retarget-reason "<why>"With --retarget: the reason recorded in retarget_historyoperator retarget via spec-kitty consolidate --target <branch> --retarget
--delete-branch / --keep-branchDelete or keep lane branchesThe retention policy, else delete
--remove-worktree / --keep-worktreeRemove or keep lane worktreesThe retention policy, else remove
--pushPublish to origin after the local landingNo push
--dry-runShow the plan without changing anythingOff
--jsonJSON output, with --dry-run onlyOff
--resumeContinue an interrupted runOff
--abortRestore the branches the run moved and clear the recordOff
--yes, -yProceed after warnings without promptsOff
--skip-review-artifact-checkBypass the review-artifact consistency gate. Requires --note "<reason>", which is recorded as override evidenceOff
--skip-lanesComplete a direct-on-target Mission whose lanes.json is genuinely absentOff
--allow-sparse-checkoutProceed when legacy sparse-checkout state is detectedOff
--attest-canceled-superseded <WP>Attest, after checking by hand, that a canceled WP’s content is absent or superseded. Repeatable, requires --attest-reason "<what you checked>", never lifts a FAILOff
--attest-approved-reviewed <WP>Attest, after checking the lane by hand, that an approval with no recorded lane commit (APPROVAL_STAMP_MISSING, any approval made before 4.0.0rc5) covers the lane as it stands. Repeatable, requires --attest-reason "<what you checked>". Does not lift LANE_MOVED_AFTER_APPROVALOff

Full reference: CLI Commands. Exit codes and refusal codes: CLI reference.

See Also

Background

Getting Started