---
type: "Guide"
title: "How to Accept and Consolidate a Mission"
description: "How to accept and consolidate a mission with Spec Kitty 3.2: Use this guide to validate mission readiness and consolidate into the mission's target branch."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-04T00:00:00Z"
---

# How to Accept and Consolidate a Mission

Use this guide to validate mission readiness and consolidate into the mission's target branch.

## Prerequisites

- All WPs are `approved` or `done`, with review feedback resolved
- You are in a checkout where the mission can be resolved (repository root checkout or execution workspace)

## Accept the Mission

Run acceptance after the implement-review loop approves every WP and before
consolidation. This is a readiness nudge for humans and LLMs; consolidation still performs its
own gates and remains the mission-close operation.

In your agent:

```text
/spec-kitty.accept
```

Or in your terminal:

```bash
spec-kitty accept
```

### What Accept Checks

- All WPs are `approved` or `done`
- Required metadata and activity logs are present
- No unresolved `[NEEDS CLARIFICATION]` markers remain

To run a read-only checklist (in your terminal):

```bash
spec-kitty accept --mode checklist
```

### What Accept Tells You Next

The next steps `accept` prints follow the Mission's topology, because the way a
Mission lands is not the same everywhere:

- **Lane and single-branch Missions** end with `spec-kitty consolidate --mission
  <handle>`. The one exception is a pull-request-mode `accept` run on the
  integration branch itself, where there is no separate Mission branch to
  consolidate: it says to push and open a pull request if needed. A
  `--mode local` `accept` on the integration branch says no merge is needed.
- **Coordination-topology Missions** are landed by `spec-kitty consolidate`. Their
  coordination branch is internal, so `accept` names that command and does not
  suggest pushing the branch and opening a pull request.

A coordination-topology Mission's `accept` therefore never asks for a pull
request. When a Mission's issue matrix is refused at `done`, the message names
the validation diagnostics; the `spec-kitty agent issue-verdict` remedy appears
only when a verdict is actually missing, still `in-mission`, or an `unknown`
placeholder.

### When a Mission Defines No Contracts

The software-dev Mission type requires a `contracts/` directory, and strict
`spec-kitty accept` blocks without it. A Mission that defines no interfaces, such as a
test remediation or a refactor, can say so in its `meta.json` instead of creating an
empty directory or running `accept --lenient`:

```json
{
  "contracts": "none",
  "contracts_rationale": "Test-drift remediation; this Mission defines no interfaces."
}
```

- **Exact value.** `contracts` must be the string `"none"`. Any other value, including
  `null`, `false` or `"None"`, is not a waiver.
- **Rationale required.** `contracts_rationale` must be a non-empty string.
- **Malformed declarations keep the requirement.** Accept still blocks and prints a
  warning that says what is wrong with the declaration.
- **Only `contracts/` is waived.** Other path conventions, such as `src/`, `tests/` and
  `docs/`, stay in force.
- **Accept shows the waiver.** A valid waiver prints its rationale in the accept warnings,
  so reviewers can see why the requirement was skipped.

Nothing writes these fields for you yet: add them by hand to the Mission's `meta.json`, or let
the plan step do it. For the reasoning, see the
[ADR](/adr/4.x/2026-10-04-1-mission-contracts-waiver-in-meta-json.md).

### When the Project Layout Differs

The other path conventions, such as `src/`, `tests/` and `docs/`, stay in force for the
Mission type. A project whose real layout differs has honest project-level levers. The strict
failure text leads with the per-type remap for the failing Mission type, then names both
waivers and `accept --lenient`, then the last-resort copy; `mkdir -p` is offered only for real
deliverables such as `contracts/`, never for these directories: an empty `src/` would pass the
check without making it true (#7512). The levers in full:

- **Remap for one Mission type** (#7748). Key a section by the Mission type in
  `.kittify/config.yaml`. Only Missions of that type see the remap; the other types keep their
  own conventions. A content repository with `packs/` and no `src/` can write:

  ```yaml
  project:
    path_conventions:
      software-dev:
        workspace: packs/   # where this repository's work actually lives
        tests: packs/
  ```

  Documentation, plan and research Missions still check `docs/`, `docs/` and `research/`.
  The section id must be a Mission type the project knows (built-in, org or project), and
  every value must be a repository-relative directory; anything else stops `accept` with a
  configuration error.

  That error stops `accept` for every Mission in the project, not only the type the section
  names. If a section names a Mission type that no longer exists (for example a type removed
  from an org pack), delete or rename that section in `.kittify/config.yaml`; the error names
  the unknown id and lists the known types. If the error says the mission-type roster could
  not be read, run `spec-kitty doctor charter-packs` to find the broken pack, fix or
  re-sync it, or remove the per-type sections until it is fixed (plain values need no roster).
- **Remap for every Mission type.** A plain string value applies to every type that
  declares the key:

  ```yaml
  project:
    path_conventions:
      workspace: internal/   # where the source actually lives
      tests: internal/       # where the tests actually live
  ```

  Per key, a type's section wins over the plain value, which wins over the Mission type's
  default. YAML holds a key once, so `documentation:` is either a plain value or the
  documentation type's section, not both: to give documentation Missions their own paths
  next to a plain `documentation:` value for the other types, set `documentation` inside each
  type's section instead.

  Both forms are remap-only: they move a required directory, never add or drop one, and
  `deliverables` (artifact-routed) is not in their vocabulary. See the
  [ADR](/adr/3.x/2026-08-28-1-project-path-convention-override-precedes-doctrine.md).
- **Waive only the path check** (#7566). When a layout mismatch is genuine and you do not
  want to remap it, waive the layout-path check while every other accept check stays strict.
  A missing Mission artifact such as `contracts/` is not waived; declare `"contracts": "none"`
  for that instead:
  - for one run: `spec-kitty accept --waive-path-conventions --waive-reason "<why>"`. The
    reason is required and is recorded on the acceptance history entry in `meta.json`.
    `orchestrator-api` has no per-run flag.
  - for every run of one Mission: add `"path_conventions": "waived"` and a non-empty
    `"path_conventions_rationale"` to the Mission's `meta.json`. Every accept path honors
    it, `orchestrator-api` included, and accept prints the rationale. A malformed
    declaration waives nothing and says what is wrong with it.
- **Last resort: drop a key.** Copying the packaged `mission.yaml` to
  `.kittify/overrides/missions/<mission-type>/mission.yaml` and deleting the key's line drops
  it, but the copy freezes that Mission type's definition at the CLI version you copied it
  from, so later changes to the packaged Mission type no longer reach you.

Prefer all of these over `accept --lenient`: lenient mode also skips the per-work-package
`agent`, `assignee` and `shell_pid` metadata checks, so it gives up more than the path
check.

### Negative Invariants That Assert the Consolidated Post-State

The accept gate **re-runs each acceptance negative-invariant `verification_command`
live** against the working tree at accept time — it does not trust a stored
`result` or a hand-set `overall_verdict`. Two consequences follow:

- **Hand-editing a verdict does not stick.** Setting `overall_verdict` (or a
  negative invariant's `result`) by hand in `acceptance-matrix.json` is
  overwritten the moment accept runs; the invariant's `verification_command` is
  the single source of truth, and it must actually pass in the checkout accept
  runs from.
- **Consolidated-post-state invariants must be verified after consolidation.** If an invariant
  asserts a state that only exists **once the mission is consolidated** — for example,
  "`shell: bash` is present in `ci-quality.yml`" when that line is added by the
  consolidation — it cannot pass while the mission still lives on its lane branch. For
  such missions, run `spec-kitty consolidate` (into **local** `main`) **before**
  `spec-kitty accept`, so the working tree accept inspects already carries the
  consolidated post-state:

  ```bash
  spec-kitty consolidate    # land into LOCAL main first
  spec-kitty accept         # now the post-state invariants can verify live
  ```

  This inverts the usual accept-then-consolidate order and is only needed for missions
  whose negative invariants assert the post-consolidation result. Missions whose
  invariants describe the lane's own diff verify fine in the normal order.

  If you prefer not to re-order, scope the invariant to a path that exists on the
  lane branch (see `NegativeInvariant.scope`) or express it as a `custom_command`
  that is meaningful pre-consolidation.

### Deferred Criteria

When the Mission agrees to postpone one acceptance criterion, record it as
`deferred` instead of leaving it `pending`:

```bash
spec-kitty agent acceptance-verdict --mission <slug> --criterion FR-004 \
  --result deferred --reason "needs the read service" --follow-up "#7400"
```

`--reason` and `--follow-up` (an issue number, URL or ruling id) are both
required; a deferral without them is refused. A justified deferral does not
block `overall_verdict` (`pass` plus `deferred` reads `pass`), but it is never
silent: `spec-kitty accept` lists each one under "Deferred criteria" in the
console and as a `criteria_deferred` entry in `skipped_checks` in `--json`.
`--description` and `--notes` replace a criterion's scaffolded text in the same
command.

### Deferred Invariants and the Post-Consolidation Gate

A scoped `grep_absence` invariant whose subject does not exist yet — because it
is added only by consolidating the mission's lane branches — cannot be honestly
judged at `accept` time. Rather than report a false "still present" or a false
"pass", accept records that invariant's result as `deferred_to_consolidation`
and the mission's `overall_verdict` as `pass_pending_consolidation`: acceptance
is **not blocked**, but the mission cannot reach `done` while the deferral is
outstanding.

**What this means for you as the operator:**

- **The mission loop does not verify a deferred invariant.** `spec-kitty accept`
  is the acceptance matrix's only pre-consolidation reader, and it is the gate
  that *creates* the deferral — it cannot also be the thing that resolves it.
  When `spec-kitty accept` assigns `deferred_to_consolidation` it discloses this
  immediately, in the same run, as a `negative_invariants_deferred` entry under
  "Skipped checks" — look for it in the console output or the JSON summary.
- **What verifies it instead** is the **post-consolidation verification op** —
  dispatched after `spec-kitty consolidate` (lane consolidation) completes, against
  the consolidated mission tree. It re-judges every `deferred_to_consolidation`
  invariant on that tree and records a terminal result
  (`confirmed_absent` / `still_present` / `verification_error`) stamped with the
  `CONSOLIDATED` surface. A violation fails **that verification op**, not the
  already-completed consolidation — see
  [post-consolidation / `CONSOLIDATED`](/context/orchestration.md#topology-surface)
  in the terminology glossary for how this surface relates to `spec-kitty
  consolidate`'s three overloaded "merge" senses.
- **What your repository needs**: a CI check on the pull request that fails when
  any `kitty-specs/*/acceptance-matrix.json` still carries an unresolved
  `deferred_to_consolidation` invariant. This project's own gate is
  `scripts/ci/check_dangling_deferrals.py`, wired into `ci-quality.yml`'s
  `deferral-consistency-check` job. **A repository without an equivalent check
  never verifies the deferral** — the disclosure above exists precisely so that
  gap is visible rather than silently assumed away (ADR
  [2026-07-23-2](/adr/3.x/2026-07-23-2-post-consolidation-deferral-and-external-enforcement.md)).

## Consolidate into the target branch

In your agent:

```text
/spec-kitty.merge --push
```

Or in your terminal:

```bash
spec-kitty consolidate --push
```

By default, `spec-kitty consolidate` lands in the mission's recorded target branch. Use `spec-kitty consolidate --target <branch>` only when you intentionally need to override that destination.

For detailed consolidation options including dry-run, strategies, and cleanup flags, see [Merge a Mission](/guides/how-to/missions/merge-mission.md).

### When Local `main` Is Not Publishable

Autonomous local runs can leave `main` ahead of or diverged from `origin/main`
with planning, status, review, and orchestration commits. If consolidation refuses with
`TARGET_BRANCH_NOT_SYNCHRONIZED`, do not reset, rebase, force-push, or push
local `main` only to satisfy the pre-flight.

Open a focused PR from the mission result instead:

```bash
git push -u origin kitty/mission-<mission-slug>
gh pr create --base main --head kitty/mission-<mission-slug> --fill
```

Or create a dedicated PR branch from the mission branch:

```bash
git switch -c kitty/pr/<mission-slug>-to-main kitty/mission-<mission-slug>
git push -u origin kitty/pr/<mission-slug>-to-main
gh pr create --base main --head kitty/pr/<mission-slug>-to-main --fill
```

Prefer squash-merge when the autonomous run accumulated many orchestration
commits. For the full end-to-end path, see
[Run an Autonomous Mission](/guides/how-to/collaboration/run-an-autonomous-mission.md).

## After Consolidation

Complete the following three steps before declaring the mission done.

**1. Mission review** — run the post-consolidation mission review to confirm spec→code fidelity and FR
coverage:

```bash
# In your agent:
/spec-kitty-mission-review

# Or directly:
spec-kitty agent mission review --mission <handle>
```

**2. Author or verify the retrospective** — under default policy the record was already written
during consolidation. Verify with:

```bash
cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yaml
```

If the file is absent (for example, an older mission predating 3.2.0), author it now:

```bash
spec-kitty retrospect create --mission <handle>
```

Reserve the noun "capture" for the event-log fact `RetrospectiveCaptured`, not for the
operator verb.

**3. Surface findings** — aggregate across recent missions or inspect proposals for this one:

```bash
# Cross-mission view (read-only aggregation)
spec-kitty retrospect summary

# Preview proposals in this mission's retrospective.yaml (dry-run by default)
spec-kitty agent retrospect synthesize --mission <handle>

# Apply a proposal (requires explicit --apply)
spec-kitty agent retrospect synthesize --mission <handle> --apply <proposal-id>
```

For full details on each command, see
[How to Use Retrospective Learning](/guides/how-to/governance/use-retrospective-learning.md).

## Consolidation Strategies

- **Default (merge commit)**: `spec-kitty consolidate`
- **Squash**: `spec-kitty consolidate --strategy squash`

Note: Rebase is not supported for multi-workspace missions. Use `merge` or `squash` instead.

## Cleanup

By default, consolidation removes resolved execution worktrees and deletes the mission branch. Use these flags to keep them (in your terminal):

```bash
spec-kitty consolidate --keep-worktree --keep-branch
```

## Abandon a Mission (Manual Cleanup)

If you decide to drop a mission without consolidating, remove its execution worktrees and branches manually.
These steps are safe and reversible until you delete the branch and commit the cleanup.

1. List worktrees to find all workspaces for the mission:
```bash
git worktree list
```

2. Remove each execution worktree for the mission:
```bash
git worktree remove .worktrees/<mission-slug>-lane-a
git worktree remove .worktrees/<mission-slug>-lane-b
```

If a worktree has uncommitted changes you want to discard, use `--force`:
```bash
git worktree remove --force .worktrees/<mission-slug>-lane-a
```

3. Delete the mission branches:
```bash
git branch -D <mission-slug>-lane-a
git branch -D <mission-slug>-lane-b
```

4. Remove the planning artifacts from the repository root checkout (spec/plan/tasks), then commit:
```bash
rm -rf kitty-specs/<mission-slug>
git add kitty-specs/
git commit -m "Remove abandoned mission <mission-slug>"
```

## Troubleshooting

- **Accept reports blockers**: Resolve the listed issues, then rerun `/spec-kitty.accept`.
- **Consolidation fails**: Ensure your current checkout is clean and the mission resolves correctly.
- **Consolidation reports `TARGET_BRANCH_NOT_SYNCHRONIZED`**: Use the focused-PR path when local `main` contains autonomous-run history that should not be published directly.
- **Consolidation is heading to the wrong branch**: Inspect the mission's recorded target branch before retrying, and use `spec-kitty consolidate --target <branch>` only if you intend to override it.

For detailed troubleshooting including pre-flight failures, conflict resolution, and consolidation recovery, see [Troubleshoot Merge Issues](/guides/how-to/recovery/troubleshoot-merge.md).

---

## Command Reference

- [Slash Commands](/api/slash-commands.md) - All `/spec-kitty.*` commands
- [CLI Commands](/api/cli-commands.md) - Full CLI reference

## See Also

- [Merge a Mission](/guides/how-to/missions/merge-mission.md) - Detailed merge workflow
- [Run an Autonomous Mission](/guides/how-to/collaboration/run-an-autonomous-mission.md) - End-to-end autonomous run and focused-PR fallback
- [Keep Main Clean](/guides/how-to/missions/keep-main-clean.md) - Choose a target branch without changing planning location
- [Troubleshoot Merge Issues](/guides/how-to/recovery/troubleshoot-merge.md) - Recovery and conflict resolution
- [Review a work package](/guides/how-to/missions/review-work-package.md) - Required before accept
- [Upgrade to 0.11.0](/guides/how-to/installation/install-and-upgrade.md) - Breaking changes in v0.11.0

## Background

- [Execution Lanes](/architecture/execution-lanes.md) - Worktree cleanup
- [Git Worktrees](/architecture/git-worktrees.md) - How worktrees work

## 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 Install and Upgrade Spec Kitty](/guides/how-to/installation/install-and-upgrade.md)
- [How to Keep Main Clean](/guides/how-to/missions/keep-main-clean.md)
- [How to Merge a Mission](/guides/how-to/missions/merge-mission.md)
- [How to review a work package](/guides/how-to/missions/review-work-package.md)
- [How to Troubleshoot Merge Issues](/guides/how-to/recovery/troubleshoot-merge.md)

## Audience

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