---
type: "Guide"
title: "How to Merge a Mission"
description: "How to merge a mission with Spec Kitty 3.2: land approved work packages on the local target branch with spec-kitty consolidate, preview it, and choose cleanup."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-05T00:00:00Z"
---

# How to Merge a Mission

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](/guides/how-to/missions/accept-and-merge.md).
- 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:

```text
/spec-kitty.consolidate
```

In your terminal:

```bash
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](/guides/how-to/recovery/troubleshoot-merge.md).

## Preview with Dry-Run

```bash
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](/guides/how-to/recovery/troubleshoot-merge.md#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.

| Strategy | Effect |
| --- | --- |
| `squash` | Lands the mission branch as one commit. This is the default. |
| `merge` | Lands the mission branch with a merge commit. |
| `rebase` | Rebases the mission branch onto the target branch, then advances the target branch to the result. |

Values are lower-case:

```bash
spec-kitty consolidate --mission 015-user-authentication --strategy merge
```

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

```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:

```bash
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:

```bash
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:

```bash
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`.

```bash
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.

| Code | When | Next step |
| --- | --- | --- |
| `RETARGET_RECORD_UNWRITABLE` | Neither 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_UNWRITABLE` | The 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_UNWRITABLE` | The 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_TARGET` | A `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_REFUSED` | The 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_MISMATCH` | The 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/guides/how-to/missions/accept-and-merge.md#when-local-main-is-not-publishable) and [Run an Autonomous Mission](/guides/how-to/collaboration/run-an-autonomous-mission.md).

`--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](/guides/how-to/recovery/troubleshoot-merge.md#not-synchronized-with-origin-only-with---push).

## After Merge

Before you call the Mission done, run the mission review, check the retrospective, and read its findings. See [After Consolidation](/guides/how-to/missions/accept-and-merge.md#after-consolidation).

## Command Reference

| Flag | What it does | Default |
| --- | --- | --- |
| `--mission <slug>` | Names the Mission | Resolved from the current branch when possible; otherwise the command asks for `--mission` |
| `--strategy` | `merge`, `squash` or `rebase` | `squash` |
| `--target <branch>` | Target branch for the landing | The Mission's recorded target branch |
| `--retarget` | With `--target`: make that branch the Mission's recorded target in this run. See [Retarget the Mission](#retarget-the-mission) | Off |
| `--retarget-reason "<why>"` | With `--retarget`: the reason recorded in `retarget_history` | `operator retarget via spec-kitty consolidate --target <branch> --retarget` |
| `--delete-branch` / `--keep-branch` | Delete or keep lane branches | The retention policy, else delete |
| `--remove-worktree` / `--keep-worktree` | Remove or keep lane worktrees | The retention policy, else remove |
| `--push` | Publish to origin after the local landing | No push |
| `--dry-run` | Show the plan without changing anything | Off |
| `--json` | JSON output, with `--dry-run` only | Off |
| `--resume` | Continue an interrupted run | Off |
| `--abort` | Restore the branches the run moved and clear the record | Off |
| `--yes`, `-y` | Proceed after warnings without prompts | Off |
| `--skip-review-artifact-check` | Bypass the review-artifact consistency gate. Requires `--note "<reason>"`, which is recorded as override evidence | Off |
| `--skip-lanes` | Complete a direct-on-target Mission whose `lanes.json` is genuinely absent | Off |
| `--allow-sparse-checkout` | Proceed when legacy sparse-checkout state is detected | Off |
| `--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 FAIL | Off |
| `--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_APPROVAL` | Off |

Full reference: [CLI Commands](/api/cli-commands.md#spec-kitty-consolidate). Exit codes and refusal codes: [CLI reference](/api/cli-commands.md#spec-kitty-consolidate-exit-codes-and-refusal-codes).

## See Also

- [Accept and Merge](/guides/how-to/missions/accept-and-merge.md): validation before consolidation
- [Keep Main Clean](/guides/how-to/missions/keep-main-clean.md): choose a target branch without changing the planning location
- [Run an Autonomous Mission](/guides/how-to/collaboration/run-an-autonomous-mission.md): autonomous run and focused pull request path
- [How to Troubleshoot Merge Issues](/guides/how-to/recovery/troubleshoot-merge.md): resume, abort and refusals
- [Recover from an Interrupted Consolidation](/guides/how-to/recovery/recover-from-interrupted-merge.md): the record, the rollback and the exit codes

## Background

- [Execution Lanes](/architecture/execution-lanes.md): how worktrees work
- [Git Worktrees](/architecture/git-worktrees.md): git worktree fundamentals
- [Git workflow](/architecture/git-workflow.md#4-consolidated): what each consolidation step does

## Getting Started

- [Your First Mission](/guides/tutorials/your-first-mission.md): complete workflow walkthrough

## Related

- [Run an Autonomous Mission](/guides/how-to/collaboration/run-an-autonomous-mission.md)
- [How to Use Retrospective Learning](/guides/how-to/governance/use-retrospective-learning.md)
- [How to Accept and Consolidate a Mission](/guides/how-to/missions/accept-and-merge.md)
- [How to Keep Main Clean](/guides/how-to/missions/keep-main-clean.md)
- [How to review a work package](/guides/how-to/missions/review-work-package.md)

## Audience

- [Stakeholder Persona: Project Owner](/context/audience/external/project-owner.md) - Written for the Project Owner reader.
