<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix/</id>
  <title>ADR 1 (2026-04-09): Mission Identity Uses ULID, Not Sequential Prefix</title>
  <updated>2026-04-09T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix/"/>
  <summary>Missions get a creation-time ULID as canonical machine identity; the sequential number becomes display metadata no selector or state file may resolve by.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Mission creation currently allocates the next mission number by scanning local
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; and local &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; for directory names that begin with a
three-digit prefix, then returning &lt;code dir=&quot;auto&quot;&gt;max(found) + 1&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;That allocator is local-only. It has no shared registry, no reservation step,
no merge-time canonicalization, and no protection against parallel authors who
branch from the same base commit. In a distributed workflow, two independent
clones can both observe the same maximum prefix and both allocate the same next
number for different missions.&lt;/p&gt;
&lt;p&gt;This is not a theoretical problem.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;PR #555 was created as &lt;code dir=&quot;auto&quot;&gt;077-planning-artifact-and-query-consistency&lt;/code&gt; while
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; independently landed &lt;code dir=&quot;auto&quot;&gt;077-mission-terminology-cleanup&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The resulting merge from &lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt; into that branch produces a real
collision in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; and content conflicts in docs, runtime, and test
files.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; already contains multiple duplicate numeric mission prefixes, proving
that the sequential prefix is not a globally unique identifier in production
data.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;At the same time, the codebase has already begun migrating to a different model:
downstream runtime and merge-state systems increasingly treat &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; as
the canonical machine-facing identity. The remaining gap is that mission
creation still emits only the sequential prefix and human-readable slug as the
effective primary key.&lt;/p&gt;
&lt;p&gt;The architecture decision is therefore not to design a new dense counter that
works under partition. The decision is to finish the migration to a stable,
partition-safe mission identity model.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Spec Kitty must support concurrent mission creation across independent clones.&lt;/li&gt;
&lt;li&gt;Canonical mission identity must be unique without requiring online
coordination.&lt;/li&gt;
&lt;li&gt;Existing dense numeric prefixes are already proven non-unique and cannot be
relied on as machine-facing identifiers.&lt;/li&gt;
&lt;li&gt;The codebase already has partial &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; adoption in runtime and merge
flows; the architecture should align with that direction instead of adding a
second identity scheme.&lt;/li&gt;
&lt;li&gt;Human-readable mission labels remain useful, but readability must not come at
the cost of correctness.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Option A: Keep sequential numeric mission prefixes as the canonical identity&lt;/li&gt;
&lt;li&gt;Option B: Keep sequential prefixes, but allow manual or explicit override&lt;/li&gt;
&lt;li&gt;Option C: Add an online reservation or registry for mission numbers&lt;/li&gt;
&lt;li&gt;Option D: Make &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; (ULID) the canonical mission identity and demote
&lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt; to display metadata&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option D — make &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; a creation-time ULID and treat it
as the canonical mission identity for all machine-facing behavior.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;decision&quot;&gt;Decision&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Every new mission must receive a &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; at creation time.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; is the canonical machine-facing identity for missions.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt; is not a canonical identifier. It is descriptive,
human-facing metadata only.&lt;/li&gt;
&lt;li&gt;Any machine-facing selector, state file, merge primitive, work-package
reference, status artifact, or synchronization payload must resolve by
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; rather than by sequential mission number.&lt;/li&gt;
&lt;li&gt;Human-facing mission handles such as path names, branch names, and UI labels
must stop assuming that the three-digit prefix is unique. These handles may
include a shortened mission-id-derived alias for readability, but the full
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; remains authoritative.&lt;/li&gt;
&lt;li&gt;Dense sequential mission numbers may still exist as display aliases, but
they are assigned or finalized only in a context that has a single source of
truth, such as &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. They must not be used as stable pre-merge identity.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Mission creation becomes partition-safe without requiring online
coordination.&lt;/li&gt;
&lt;li&gt;Existing runtime and merge-state code that already prefers &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;
aligns with the documented architecture.&lt;/li&gt;
&lt;li&gt;Duplicate numeric prefixes no longer threaten correctness because they cease
to be identity-bearing.&lt;/li&gt;
&lt;li&gt;The architecture cleanly separates stable machine identity from mutable,
human-facing display labels.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Existing missions require a backfill migration for &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Existing duplicate numeric prefixes on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; must be cleaned up so legacy
selectors and documentation stop encountering ambiguous mission references.&lt;/li&gt;
&lt;li&gt;Paths, branch names, selectors, and operator habits that currently rely on
numeric mission prefixes require a staged migration and deprecation window.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;ULID is chosen for uniqueness and rough chronological ordering. No stronger
causal ordering primitive is required for mission identity itself.&lt;/li&gt;
&lt;li&gt;This ADR does not lock in an exact short-handle format for paths or branch
names, only the architectural rule that the sequential prefix is no longer
canonical identity.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This ADR is considered implemented when all of the following are true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;New missions always write &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; at creation time.&lt;/li&gt;
&lt;li&gt;A repository audit can report zero missions missing &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Runtime and merge flows no longer depend on numeric mission prefixes being
unique.&lt;/li&gt;
&lt;li&gt;Duplicate mission prefixes on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; no longer create selector ambiguity or
identity ambiguity.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt; is absent from machine-facing contracts that require stable
identity, or is clearly documented there as display-only metadata.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a-keep-sequential-numeric-mission-prefixes-as-the-canonical-identity&quot;&gt;Option A: Keep sequential numeric mission prefixes as the canonical identity&lt;/h3&gt;
&lt;p&gt;Continue using &lt;code dir=&quot;auto&quot;&gt;max(local prefixes) + 1&lt;/code&gt; and rely on &lt;code dir=&quot;auto&quot;&gt;NNN-slug&lt;/code&gt; for mission
identity.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves the current naming model.&lt;/li&gt;
&lt;li&gt;Keeps mission references short and familiar.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Cannot survive concurrent offline creation.&lt;/li&gt;
&lt;li&gt;Already disproven by duplicate prefixes on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Forces correctness to depend on a dense counter in a distributed system.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The current model is already failing in real repository data.&lt;/p&gt;
&lt;h3 id=&quot;option-b-keep-sequential-prefixes-but-allow-manual-or-explicit-override&quot;&gt;Option B: Keep sequential prefixes, but allow manual or explicit override&lt;/h3&gt;
&lt;p&gt;Permit the caller to supply the number explicitly when collisions are expected.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Small local change to current behavior.&lt;/li&gt;
&lt;li&gt;Gives operators a manual escape hatch.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Pushes distributed coordination onto humans.&lt;/li&gt;
&lt;li&gt;Does not create a canonical unique machine identity.&lt;/li&gt;
&lt;li&gt;Leaves the underlying race intact.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Manual override is a workaround, not an architecture.&lt;/p&gt;
&lt;h3 id=&quot;option-c-add-an-online-reservation-or-registry-for-mission-numbers&quot;&gt;Option C: Add an online reservation or registry for mission numbers&lt;/h3&gt;
&lt;p&gt;Reserve the next number through &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; or another shared authority before
creating a mission.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves dense numbers as canonical from birth.&lt;/li&gt;
&lt;li&gt;Prevents duplicate allocation while online.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires coordination at mission creation time.&lt;/li&gt;
&lt;li&gt;Fails the partition-tolerant offline workflow requirement.&lt;/li&gt;
&lt;li&gt;Adds operational complexity around retries, lock ownership, and reservations.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Online reservation solves a different problem than the one
Spec Kitty needs to support.&lt;/p&gt;
&lt;h3 id=&quot;option-d-make-mission_id-ulid-the-canonical-mission-identity-and-demote-mission_number-to-display-metadata&quot;&gt;Option D: Make &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; (ULID) the canonical mission identity and demote &lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt; to display metadata&lt;/h3&gt;
&lt;p&gt;Mint a ULID at mission creation and use it as the stable identity everywhere
that correctness depends on uniqueness.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Partition-safe by design.&lt;/li&gt;
&lt;li&gt;Matches the direction already present in runtime and merge-state code.&lt;/li&gt;
&lt;li&gt;Separates stable identity from human-facing display labels.&lt;/li&gt;
&lt;li&gt;Enables a staged migration instead of a single all-or-nothing rewrite.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires backfill and migration for old missions.&lt;/li&gt;
&lt;li&gt;Requires follow-up work to remove remaining prefix-based assumptions.&lt;/li&gt;
&lt;li&gt;Human-facing handles need a new convention once numeric prefixes stop being
canonical.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Chosen:&lt;/strong&gt; It is the only option that matches Spec Kitty’s distributed
workflow model while fitting the repository’s partially completed migration
direction.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;Relevant repository evidence:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Mission number allocation scans local &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; only:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/worktree.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Mission creation currently formats the mission slug from that sequential
number and does not write &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/mission_creation.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Runtime lane manifests already describe &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; as the immutable
machine-facing identity:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/models.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Merge state is already scoped by &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/merge/state.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Follow-up implementation work is intentionally tracked outside this ADR so the
architectural decision remains stable while the migration plan is executed in
phases.&lt;/p&gt;</content>
</entry>
