Skip to content

How to Accept and Consolidate a Mission

Who is this for (1)

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:

/spec-kitty.accept

Or in your terminal:

Terminal window
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):

Terminal window
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:

{
"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.

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:

    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:

    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.

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

    Terminal window
    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:

Terminal window
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 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).

Consolidate into the target branch

In your agent:

/spec-kitty.merge --push

Or in your terminal:

Terminal window
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.

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:

Terminal window
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:

Terminal window
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.

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:

Terminal window
# 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:

Terminal window
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:

Terminal window
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:

Terminal window
# 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):

Terminal window
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:
Terminal window
git worktree list
  1. Remove each execution worktree for the mission:
Terminal window
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:

Terminal window
git worktree remove --force .worktrees/<mission-slug>-lane-a
  1. Delete the mission branches:
Terminal window
git branch -D <mission-slug>-lane-a
git branch -D <mission-slug>-lane-b
  1. Remove the planning artifacts from the repository root checkout (spec/plan/tasks), then commit:
Terminal window
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.


Command Reference

See Also

Background

Getting Started