Skip to content

Migration: Mission ID as Canonical Identity

Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.

Status: Shipped with mission 083-mission-id-canonical-identity-migration. ADR: 2026-04-09-1 Issue: Priivacy-ai/spec-kitty#557 Audience: Operators upgrading existing Spec Kitty projects to the 3.x line that ships the mission_id identity model.

Why This Matters

Before mission 083, Spec Kitty used the three-digit numeric prefix (mission_number) that shows up in directory names like kitty-specs/001-auth-system/ as the canonical identity for every mission. This caused four distinct failure modes in real projects:

  1. Collision on import. Two repositories each had a 001-auth-system directory. Merging them or running a cross-repo dashboard scanner produced silently-merged state, because both missions looked identical to the selector.
  2. Silent fallback on ambiguous handles. A user ran spec-kitty agent tasks status --mission 020 in a project that had both 020-feature-a and 020-feature-b (from a botched rebase). The CLI picked one arbitrarily — and usually the wrong one.
  3. Branch and worktree name collisions. Two missions with the same human-chosen slug would fight over the same .worktrees/<slug>-lane-a directory and the same kitty/mission-<slug>-lane-a branch.
  4. Early numbering pressure. mission_number had to be assigned the moment a mission was created, which meant the number had to be globally unique at creation time, which forced a cross-checkout lock that did not actually exist.

Mission 083 fixes all four by making mission_id (a ULID) the canonical machine identity, minted at creation and immutable. mission_number becomes display-only metadata, null until merge time, and assigned as max(existing_numbers)+1 inside the merge-state lock — the only place where a global invariant can actually be enforced.

Breaking (3.2.5+): this backfill is now mandatory for coordination. As of 3.2.5, a pre-3.2.x mission with no resolvable mission_id/mid8 hard-fails on coordination operations (status transitions, move-task, review/merge coordination writes) instead of silently degrading — the coordination-workspace seam refuses to compose a malformed kitty/mission-<slug>- ref (#2091). If you see COORDINATION_WORKSPACE_MID8_REQUIRED, run the backfill below (spec-kitty migrate backfill-identity) to modernize the mission; audit first with spec-kitty doctor identity. The dual-era legacy-bridge fallback is intentionally removed (#2462).

What Changed

FieldBefore (2.x)After (083+)
Canonical machine identitymission_number (3-digit string)mission_id (26-char ULID)
Selector routingmission_number / mission_slug prefix matchmission_id, mid8, or mission_slug, disambiguated by mission_id
Mission branch namingkitty/mission-<slug>kitty/mission-<slug>-<mid8>
Lane branch naming†kitty/mission-<slug>-lane-<id>kitty/mission-<slug>-lane-<id> (unchanged — see footnote)
Lane worktree naming†.worktrees/<slug>-lane-<id>.worktrees/<slug>-lane-<id> (unchanged — see footnote)
Ambiguous selectorSilent first-match fallbackStructured MISSION_AMBIGUOUS_SELECTOR error
When mission_number is assignedAt mission creationAt merge time, under the merge-state lock
  • mid8 is the first 8 characters of the ULID. It is the short disambiguator used in the Mission branch and coordination identifiers.
  • Pre-083 missions without a mission_id are called legacy missions. The doctor and backfill commands below mint a mission_id for them.
  • † Lane branch and worktree naming never derived from mission_id. Mission 083 originally documented lane names as embedding mid8 the same way the Mission branch does. That was never what lane creation produced — lanes were always named from the slug and lane id alone — and the gap between what six other read sites assumed and what creation actually did caused a merge defect (#5108). ADR 2026-09-26-2 makes the created (slug-only) name the only name any caller can compose. mid8 appears in a lane name only when the recorded Mission slug happens to embed it (see Execution Lanes §Naming).

Step 1 — Upgrade spec-kitty-cli

Install the pre-release that contains the 083 work:

Terminal window
pipx install --force --pip-args="--pre" spec-kitty-cli
spec-kitty --version

Expected: a version at or above the 083 release tag.

Note: spec-kitty-cli is installed via pipx, not pip. See the project’s CLAUDE.md for the rationale.

Step 2 — Run the identity audit

From the root of each project you want to migrate:

Terminal window
spec-kitty doctor identity --json

The command walks kitty-specs/ and classifies every mission into one of four states, and every kitty-specs/ folder that is not a Mission as residue (the same contract spec-kitty doctor identity --help prints and docs/api/cli-commands.md carries):

  • assigned — mission_id present AND mission_number non-null (fully migrated, post-merge).

  • pending — mission_id present AND mission_number null (pre-merge; the number is assigned at merge time).

  • legacy — mission_id missing AND mission_number present (needs backfill).

  • orphan — both fields missing, or meta.json unreadable (needs triage).

  • residue — the folder is not a Mission, and selection does not list it. It has no meta.json; or, in a git repository, git tracks neither its meta.json nor its spec.md, and the meta.json has no mission_id or cannot be read. Each row’s residue_reason names which, and the report prints one remedy per reason (residue_remedies under --json):

    • no_meta: delete the folder if it is leftover. If it is a real Mission whose meta.json was deleted, run git restore <path>/meta.json when git status shows the deletion; when the deletion was committed, find it with git log --diff-filter=D --format=%h -1 -- <path>/meta.json, then run git checkout <sha>~1 -- <path>/meta.json. If its meta.json was never committed, re-create it with spec-kitty agent mission create and move its spec.md in.
    • untracked_idless_meta: for a real Mission, commit its meta.json or run spec-kitty migrate backfill-identity; otherwise delete the folder.
    • corrupt_meta: the Mission content is corrupt (the row’s error says why); do not delete the folder before checking. Fix its permissions or JSON. If git status shows it staged as deleted, run git checkout HEAD -- <path>/meta.json. If a commit removed it, find that commit with git log --diff-filter=D --format=%h -1 -- <path>/meta.json and run git checkout <sha>~1 -- <path>/meta.json. Otherwise re-create the Mission with spec-kitty agent mission create.

    --fail-on residue makes the audit exit 1 while any remain. A git index that cannot be read makes the audit exit 1 with one error line (GIT_INDEX_UNREADABLE under --json); run git reset, and if that fails too, delete the index file (git rev-parse --git-path index prints its path) and run git reset again.

Expected output for a project with one legacy mission, one pending mission and one leftover residue folder (path values are absolute; residue_remedies appears only when at least one folder is residue):

{
"summary": {
"assigned": 0,
"pending": 1,
"legacy": 1,
"orphan": 0,
"residue": 1
},
"missions": [
{
"path": "/srv/my-project/kitty-specs/001-auth-system",
"slug": "001-auth-system",
"mission_id": null,
"mission_number": 1,
"state": "legacy",
"error": null,
"residue_reason": null
},
{
"path": "/srv/my-project/kitty-specs/002-dashboard",
"slug": "002-dashboard",
"mission_id": "01J6XW9VMJ5Z3QRXPFW5K2H1MA",
"mission_number": null,
"state": "pending",
"error": null,
"residue_reason": null
},
{
"path": "/srv/my-project/kitty-specs/leftover-junk",
"slug": "leftover-junk",
"mission_id": null,
"mission_number": null,
"state": "residue",
"error": null,
"residue_reason": "no_meta"
}
],
"duplicate_prefixes": {},
"ambiguous_selectors": {},
"fail_on_triggered": false,
"residue_remedies": {
"no_meta": "No meta.json on disk, so Mission selection does not list it. If it is leftover residue, delete the folder. If it is a real Mission whose meta.json was deleted: when `git status` shows the deletion, run `git restore <path>/meta.json`; when the deletion was committed, find it with `git log --diff-filter=D --format=%h -1 -- <path>/meta.json` and run `git checkout <sha>~1 -- <path>/meta.json`. If its meta.json was never committed, re-create the Mission with `spec-kitty agent mission create` and move its spec.md into the new folder."
}
}

Every row in missions[] carries path, slug, mission_id, mission_number, state, error and residue_reason (null unless the row is residue). duplicate_prefixes reports every 3-digit numeric prefix shared by two or more missions, and ambiguous_selectors every selector handle that would resolve to more than one mission — residue folders are in neither, because Mission selection does not list them. fail_on_triggered is true when --fail-on matched at least one row (the command then exits 1).

If duplicate_prefixes or ambiguous_selectors is non-empty, resolve the collision before you rely on short handles: rename one of the colliding directories, or delete a stale checkout. An ambiguous handle fails with a structured MISSION_AMBIGUOUS_SELECTOR error, without fallback — see Step 6. The CLI does not guess.

Step 3 — Run the backfill

Once the audit reports no legacy missions (and no orphan or residue rows you need to triage):

Terminal window
spec-kitty migrate backfill-identity

This command:

  1. Loads every legacy mission.
  2. Mints a fresh mission_id (ULID) per mission.
  3. Writes mission_id into meta.json. No other field’s value is touched — mission_number, mission_slug, created_at, target_branch, friendly_name, mission_type all keep their values, except that a legacy string-typed mission_number (for example "042") is coerced to an integer.
  4. Leaves the change in your working tree for you to review and commit; it does not commit by itself.

Expected output (live run on a project with one legacy mission):

backfill-identity summary
Total missions scanned : 2
Written (mission_id) : 1
Skipped (already set) : 1
Errors : 0
Number coerced : 0
Done. 1 mission(s) received a ``mission_id``.

Rows with Errors > 0 name the failing mission and the reason; the command exits 1 when any row errors.

Backfill is additive-only. Existing data is never overwritten. The backfill is safe to re-run: missions that already have a mission_id are skipped.

Step 4 — Re-run the audit

Confirm the project is clean:

Terminal window
spec-kitty doctor identity --json

Expected output (the same project after the backfill and after triaging the leftover residue folder — legacy is 0, the backfilled mission is now assigned, and residue_remedies is absent because no residue row remains; the backfill itself does not remove residue folders):

{
"summary": {
"assigned": 1,
"pending": 1,
"legacy": 0,
"orphan": 0,
"residue": 0
},
"missions": [
{
"path": "/srv/my-project/kitty-specs/001-auth-system",
"slug": "001-auth-system",
"mission_id": "01M669SYJ4RPTTHW57DMY2KPY6",
"mission_number": 1,
"state": "assigned",
"error": null,
"residue_reason": null
},
{
"path": "/srv/my-project/kitty-specs/002-dashboard",
"slug": "002-dashboard",
"mission_id": "01J6XW9VMJ5Z3QRXPFW5K2H1MA",
"mission_number": null,
"state": "pending",
"error": null,
"residue_reason": null
}
],
"duplicate_prefixes": {},
"ambiguous_selectors": {},
"fail_on_triggered": false
}

A pending mission is healthy: its mission_number is assigned at merge time. If any mission is still legacy, rerun backfill against that mission directly (spec-kitty migrate backfill-identity --mission <slug>).

What Backfill Does Not Change

Backfill mints mission_id and writes it into meta.json; it does not touch lanes.json or rename anything already created on disk:

  • Lane branches and worktrees keep their created names. Backfilling a legacy mission’s identity does not rename its lane branches or lane worktrees, because lane naming never took the identity as an input in the first place (see the footnote in What Changed above and ADR 2026-09-26-2). A lane created before backfill and a lane created after backfill compose the identical name, for the identical slug and lane id.
  • lanes.json’s recorded mission_branch is preserved across re-finalize (FR-011). Only the first finalize-tasks for a mission defines its recorded Mission branch. Backfilling the identity and then re-running finalize-tasks leaves that recorded value byte-identical — it is never recomposed from the (now-different) identity. This is what keeps a backfilled mission’s later implement/merge steps targeting the Mission branch that was actually created, instead of a phantom name that was never created.

Step 5 — Understanding the new branch and worktree naming

This step applies only to a Mission’s first finalize-tasks — the one that defines lanes.json’s recorded Mission branch for the first time. Once a mission has a mission_id, that first finalize (via the following spec-kitty implement cycle) produces a Mission branch that embeds mid8. A re-finalize on an already-finalized Mission is a different case: it preserves the already-recorded Mission branch byte-identically (see What Backfill Does Not Change above) rather than recomputing it. Lane branches and lane worktrees are keyed on the slug and lane id only in either case, never on mission_id directly.

Case A — a legacy Mission backfilled after it was already finalized. Its lanes were created from the pre-backfill slug, so its lane names do not change:

Mission branch: kitty/mission-auth-system
Lane branch: kitty/mission-auth-system-lane-a
Lane worktree: .worktrees/auth-system-lane-a/

Backfilling this Mission’s identity does not by itself change any of the above — see What Backfill Does Not Change.

Case B — a Mission created fresh on 083+. Its recorded slug already embeds the mid8 (minted at mission create, before the first finalize ever runs), so the Mission branch and the lane names both contain it — not because lane naming looked up the identity, but because it is already part of the slug it composes from:

Mission branch: kitty/mission-auth-system-01J6XW9K
Lane branch: kitty/mission-auth-system-01J6XW9K-lane-a
Lane worktree: .worktrees/auth-system-01J6XW9K-lane-a/

Where 01J6XW9K is the first 8 characters of mission_id = 01J6XW9KQT7M0YB3N4R5CQZ2EX. Compare Case A: there, the slug never embedded a mid8, so the lane names never picked one up either — lane naming only ever reflects whatever the recorded slug already contains, never the identity directly (see ADR 2026-09-26-2).

What this means in practice:

  • You may see both legacy and new Mission branches side-by-side during the transition. That is expected.
  • Existing worktrees for a mission do not rename automatically. Lane worktrees never need to — they were never keyed on the identity.

Step 6 — What to do if a selector is ambiguous

The --mission flag on every command now accepts three forms:

  1. mission_id — full 26-char ULID. Always unique. Always works.
  2. mid8 — first 8 chars of the ULID. Unique in practice; the resolver falls through to a structured error if two missions somehow share mid8.
  3. mission_slug — human-readable slug. Preferred for interactive use; the resolver disambiguates by mission_id when two missions share a slug.

If the resolver cannot disambiguate, you get a MISSION_AMBIGUOUS_SELECTOR error without fallback:

Error: Handle 'auth-system' matches 2 missions:
- mission_id=01J6XW9KQT7M0YB3N4R5CQZ2EX slug=auth-system number=1
- mission_id=01J7YZ0DPN5A2B3C4D5E6F7G8H slug=auth-system number=14
Pass the full mission_id or mid8 to disambiguate, e.g. --mission 01J6XW9K.

Copy the mid8 from the error and re-run the command. This is deliberate — mission 083 removed silent fallback (work package WP07) because it was the root cause of the collision class of bugs.

Rollback Plan

mission_id is a forward-only, additive change. If something breaks after the migration:

  1. The stored data is safe. Backfill only adds mission_id to meta.json; it never removes or modifies existing fields. A project whose meta.json files have both mission_id and mission_number is in the normal state for 083+.
  2. Pin the CLI back. pipx install spec-kitty-cli==<pre-083-version> returns you to the 2.x line. The old CLI will ignore the new mission_id field in meta.json and continue to route by mission_number. The new Mission branches created under 083 will remain on disk but will not be used by the old CLI; you can either git worktree remove them or leave them as archived state.
  3. Report the failure. File an issue at Priivacy-ai/spec-kitty#557 or the tracking issue for the release with the output of spec-kitty doctor identity --json attached.

Do not hand-edit meta.json to remove mission_id. The file is watched by the event log, and a missing mission_id will cause it to classify the mission as legacy and prompt for another backfill — at which point the mission will receive a different ULID, and any event log entries keyed off the original ULID will become orphaned.