<?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-05-10-1-deterministic-historical-mission-state-repair/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-10-1-deterministic-historical-mission-state-repair/</id>
  <title>ADR 1 (2026-05-10): Deterministic Historical Mission-State Repair Identity</title>
  <updated>2026-05-10T00: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-05-10-1-deterministic-historical-mission-state-repair/"/>
  <summary>Repairing legacy missions derives absent identifiers from a deterministic ULID seeded by on-disk mission material, and never rewrites an existing valid identity.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Historical &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; directories may predate &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;. TeamSpace import
requires stable mission identity, but public migration must be safe in
distributed Git: two clones of the same historical repository must produce the
same repaired artifacts without consulting a server, a clock, or randomness.&lt;/p&gt;
&lt;p&gt;New missions still use creation-time ULIDs as decided in
&lt;code dir=&quot;auto&quot;&gt;2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix.md&lt;/code&gt;. This ADR
only governs deterministic repair for historical missions that lack a valid
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Historical repair derives missing &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; values deterministically from
repository-local mission material:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Existing valid &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; values are authoritative and are never changed.&lt;/li&gt;
&lt;li&gt;Missing or invalid IDs are replaced by &lt;code dir=&quot;auto&quot;&gt;deterministic_ulid(seed)&lt;/code&gt;, where the
seed is JSON serialized with sorted keys from:
&lt;ul&gt;
&lt;li&gt;canonical mission slug,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;slug&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;friendly_name&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;created_at&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_type&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;first status-event &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, when present,&lt;/li&gt;
&lt;li&gt;first status-event &lt;code dir=&quot;auto&quot;&gt;at&lt;/code&gt;, when present.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;When historical material is sparse, repair still uses deterministic defaults
already written by the canonicalizer, including the mission directory name
and the Unix epoch fallback for missing &lt;code dir=&quot;auto&quot;&gt;created_at&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The generated identifier must be ULID-compatible in shape: 26 Crockford
Base32 characters accepted by the current &lt;code dir=&quot;auto&quot;&gt;ULID_PATTERN&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Timestamp bits are not interpreted as wall-clock time for repaired IDs. The
full 128-bit value is derived from SHA-256 seed material, so the encoded
prefix is deterministic hash material, not a chronological claim.&lt;/li&gt;
&lt;li&gt;Fork behavior is content-based: two clones with byte-identical historical
mission material produce the same repaired ID; forks that change seed
material before repair can produce different repaired IDs. Once a valid
&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; exists, later forks preserve it unchanged.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Repair is reproducible across clones and CI runners.&lt;/li&gt;
&lt;li&gt;Repair does not need hosted TeamSpace, tracker, auth, or sync configuration.&lt;/li&gt;
&lt;li&gt;Sparse historical missions remain repairable, but the manifest and audit
output show what was defaulted.&lt;/li&gt;
&lt;li&gt;Operators must coordinate the repair commit before TeamSpace import so forked
branches inherit the same persisted &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This ADR is implemented when tests prove:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;two cloned historical fixtures produce byte-identical repair diffs;&lt;/li&gt;
&lt;li&gt;running repair twice yields no second diff;&lt;/li&gt;
&lt;li&gt;existing valid IDs are preserved;&lt;/li&gt;
&lt;li&gt;divergent pre-repair seed material produces different deterministic IDs;&lt;/li&gt;
&lt;li&gt;TeamSpace dry-run refuses audit-blocking historical shapes before import.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
