How to Accept and Consolidate a Mission
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Use this guide to validate mission readiness and consolidate into the mission’s target branch.
Prerequisites
- All WPs are
approvedordone, 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:
/spec-kitty.acceptOr in your terminal:
spec-kitty acceptWhat Accept Checks
- All WPs are
approvedordone - Required metadata and activity logs are present
- No unresolved
[NEEDS CLARIFICATION]markers remain
To run a read-only checklist (in your terminal):
spec-kitty accept --mode checklistWhat 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-modeacceptrun 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 localaccepton the integration branch says no merge is needed. - Coordination-topology Missions are landed by
spec-kitty consolidate. Their coordination branch is internal, soacceptnames 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:
{ "contracts": "none", "contracts_rationale": "Test-drift remediation; this Mission defines no interfaces."}- Exact value.
contractsmust be the string"none". Any other value, includingnull,falseor"None", is not a waiver. - Rationale required.
contracts_rationalemust 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 assrc/,tests/anddocs/, 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.
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 withpacks/and nosrc/can write:project:path_conventions:software-dev:workspace: packs/ # where this repository's work actually livestests: packs/Documentation, plan and research Missions still check
docs/,docs/andresearch/. 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 stopsacceptwith a configuration error.That error stops
acceptfor 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, runspec-kitty doctor charter-packsto 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:
project:path_conventions:workspace: internal/ # where the source actually livestests: internal/ # where the tests actually livePer 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 plaindocumentation:value for the other types, setdocumentationinside 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. -
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 inmeta.json.orchestrator-apihas no per-run flag. - for every run of one Mission: add
"path_conventions": "waived"and a non-empty"path_conventions_rationale"to the Mission’smeta.json. Every accept path honors it,orchestrator-apiincluded, and accept prints the rationale. A malformed declaration waives nothing and says what is wrong with it.
- for one run:
-
Last resort: drop a key. Copying the packaged
mission.yamlto.kittify/overrides/missions/<mission-type>/mission.yamland 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’sresult) by hand inacceptance-matrix.jsonis overwritten the moment accept runs; the invariant’sverification_commandis 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: bashis present inci-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, runspec-kitty consolidate(into localmain) beforespec-kitty accept, so the working tree accept inspects already carries the consolidated post-state:Terminal window spec-kitty consolidate # land into LOCAL main firstspec-kitty accept # now the post-state invariants can verify liveThis 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 acustom_commandthat is meaningful pre-consolidation.
Deferred Criteria
When the Mission agrees to postpone one acceptance criterion, record it as
deferred instead of leaving it pending:
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 acceptis 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. Whenspec-kitty acceptassignsdeferred_to_consolidationit discloses this immediately, in the same run, as anegative_invariants_deferredentry 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 everydeferred_to_consolidationinvariant on that tree and records a terminal result (confirmed_absent/still_present/verification_error) stamped with theCONSOLIDATEDsurface. A violation fails that verification op, not the already-completed consolidation — see post-consolidation /CONSOLIDATEDin the terminology glossary for how this surface relates tospec-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.jsonstill carries an unresolveddeferred_to_consolidationinvariant. This project’s own gate isscripts/ci/check_dangling_deferrals.py, wired intoci-quality.yml’sdeferral-consistency-checkjob. 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).
Consolidate into the target branch
In your agent:
/spec-kitty.merge --pushOr in your terminal:
spec-kitty consolidate --pushBy 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.
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:
git push -u origin kitty/mission-<mission-slug>gh pr create --base main --head kitty/mission-<mission-slug> --fillOr create a dedicated PR branch from the mission branch:
git switch -c kitty/pr/<mission-slug>-to-main kitty/mission-<mission-slug>git push -u origin kitty/pr/<mission-slug>-to-maingh pr create --base main --head kitty/pr/<mission-slug>-to-main --fillPrefer squash-merge when the autonomous run accumulated many orchestration commits. For the full end-to-end path, see Run an Autonomous Mission.
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:
# 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:
cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yamlIf the file is absent (for example, an older mission predating 3.2.0), author it now:
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:
# 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.
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):
spec-kitty consolidate --keep-worktree --keep-branchAbandon 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.
- List worktrees to find all workspaces for the mission:
git worktree list- Remove each execution worktree for the mission:
git worktree remove .worktrees/<mission-slug>-lane-agit worktree remove .worktrees/<mission-slug>-lane-bIf a worktree has uncommitted changes you want to discard, use --force:
git worktree remove --force .worktrees/<mission-slug>-lane-a- Delete the mission branches:
git branch -D <mission-slug>-lane-agit branch -D <mission-slug>-lane-b- Remove the planning artifacts from the repository root checkout (spec/plan/tasks), then commit:
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 localmaincontains 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.
Command Reference
- Slash Commands - All
/spec-kitty.*commands - CLI Commands - Full CLI reference
See Also
- Merge a Mission - Detailed merge workflow
- Run an Autonomous Mission - End-to-end autonomous run and focused-PR fallback
- Keep Main Clean - Choose a target branch without changing planning location
- Troubleshoot Merge Issues - Recovery and conflict resolution
- Review a work package - Required before accept
- Upgrade to 0.11.0 - Breaking changes in v0.11.0
Background
- Execution Lanes - Worktree cleanup
- Git Worktrees - How worktrees work
Getting Started
- Your First Mission - Complete workflow walkthrough