---
type: "Migration"
title: "Migration: Mission ID as Canonical Identity"
description: "Migration to mission_id (ULID) as a mission's canonical identity, shipped with mission 083: the new identity model, the backfill, and the ADR behind it."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-30T00:00:00Z"
---

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

# Migration: Mission ID as Canonical Identity

**Status**: Shipped with mission `083-mission-id-canonical-identity-migration`.
**ADR**: [2026-04-09-1](https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix.md)
**Issue**: [Priivacy-ai/spec-kitty#557](https://github.com/Priivacy-ai/spec-kitty/issues/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

| Field | Before (2.x) | After (083+) |
|-------|--------------|--------------|
| Canonical machine identity | `mission_number` (3-digit string) | `mission_id` (26-char ULID) |
| Selector routing | `mission_number` / `mission_slug` prefix match | `mission_id`, `mid8`, or `mission_slug`, disambiguated by `mission_id` |
| Mission branch naming | `kitty/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 selector | Silent first-match fallback | Structured `MISSION_AMBIGUOUS_SELECTOR` error |
| When `mission_number` is assigned | At mission creation | At 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`](/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input.md)
  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](/architecture/execution-lanes.md#naming)).

## Step 1 — Upgrade `spec-kitty-cli`

Install the pre-release that contains the 083 work:

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

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

```json
{
  "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):

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

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

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

```json
{
  "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`](/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input.md)).
  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:

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

```text
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`](/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input.md)).

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

```text
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](https://github.com/Priivacy-ai/spec-kitty/issues/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.

## Related Documentation

- [Mission Identity Model in `CLAUDE.md`](https://github.com/spec-kitty/spec-kitty/blob/main/CLAUDE.md#mission-identity-model-083) — developer-facing contract summary.
- [Event Envelope Reference](/api/event-envelope.md) — how `mission_id` flows into the machine contract.
- [Orchestrator API Reference](/api/orchestrator-api.md) — `--mission` selector semantics.
- [Execution Lanes](/architecture/execution-lanes.md) — lane branch and worktree naming.
- [Feature Detection architecture note](https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/architecture/feature-detection.md) — historical context for the pre-083 selector.
- [Feature Flag Deprecation](/migrations/feature-flag-deprecation.md) — the earlier `--feature` → `--mission` migration.

## Related

- [Migration: --feature to --mission](/migrations/feature-flag-deprecation.md)
