<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/migration-and-shim-rules/">
  <id>https://docs.spec-kitty.ai/migrations/migration-and-shim-rules/</id>
  <title>Migration and Shim Ownership Rules</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/migration-and-shim-rules/"/>
  <summary>The migration and shim ownership rulebook governing bundle/runtime migrations and back-compat shims during package extraction, which every extraction mission must cite.</summary>
  <content type="html">&lt;span id=&quot;migration-and-shim-ownership-rules&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;em&gt;&lt;code dir=&quot;auto&quot;&gt;docs/migrations/migration-and-shim-rules.md&lt;/code&gt;&lt;/em&gt;
&lt;em&gt;Mission: migration-shim-ownership-rules-01KPDYDW (#615)&lt;/em&gt;
&lt;em&gt;See also: &lt;a href=&quot;/architecture/05_ownership_map/&quot;&gt;05_ownership_map.md&lt;/a&gt; (slice inventory)&lt;/em&gt;&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;1-scope-and-purpose&quot;&gt;1. Scope and Purpose&lt;/h2&gt;
&lt;p&gt;This rulebook governs how spec-kitty handles two related but distinct concerns during package extraction: &lt;strong&gt;bundle and runtime migrations&lt;/strong&gt; (code that transforms project state when a new spec-kitty version is installed) and &lt;strong&gt;compatibility shims&lt;/strong&gt; (thin Python re-export modules that preserve an old import path while the canonical location moves). It exists because mission #615 identified that ad-hoc handling of these concerns had produced undocumented shims, unclear removal timelines, and no CI gate to catch newly introduced shims that bypassed the registry.&lt;/p&gt;
&lt;p&gt;Every extraction mission — #612, #613, #614, and any future slice extraction — must cite this document in its implementation plan and follow the rule families described here. The CI enforcement surfaces are &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor shim-registry&lt;/code&gt; (exit codes 0/1/2) and the architectural pytest suite (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Doctrine versioning for these artifacts (schema-version extension to doctrine artifacts themselves) is tracked separately under #461 Phase 7 and is &lt;strong&gt;not&lt;/strong&gt; implemented by this mission.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;2-rule-family-a--project-schema-and-version-gating&quot;&gt;2. Rule Family (a) — Project Schema and Version Gating&lt;/h2&gt;
&lt;p&gt;Spec-kitty’s &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; artifacts and mission bundles carry a &lt;code dir=&quot;auto&quot;&gt;schema-version&lt;/code&gt; field. The current contract is:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; artifacts&lt;/strong&gt;: Schema version is defined per-artifact type in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/*/mission.yaml&lt;/code&gt;. A migration module must check the schema version of the artifact it is upgrading and refuse to apply if the version is outside its supported range, raising a clear error that names the installed spec-kitty version and the artifact’s schema version.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission bundles&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/meta.json&lt;/code&gt; carries a &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt; field. Tools that consume mission bundles should reject bundles with an unknown major schema version and warn on unknown minor versions.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The runtime reads the project version from &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;tomllib&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;[project].version&lt;/code&gt;). This value is used exclusively for semver comparison against &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; entries in the shim registry. Pre-release suffixes (e.g., &lt;code dir=&quot;auto&quot;&gt;3.3.0a1&lt;/code&gt;) are handled by &lt;code dir=&quot;auto&quot;&gt;packaging.version.Version&lt;/code&gt;, which correctly treats &lt;code dir=&quot;auto&quot;&gt;3.3.0a1 &amp;#x3C; 3.3.0&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cross-reference&lt;/strong&gt;: #461 Phase 7 plans to extend schema-version gating to doctrine artifacts (directives, paradigms, procedures). That work is not in scope here; this rule family covers only &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; artifacts and mission bundles.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;3-rule-family-b--bundle-and-runtime-migration-authoring-contract&quot;&gt;3. Rule Family (b) — Bundle and Runtime Migration Authoring Contract&lt;/h2&gt;
&lt;p&gt;A migration module lives under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/&lt;/code&gt; and is named &lt;code dir=&quot;auto&quot;&gt;m_&amp;#x3C;version_slug&gt;_&amp;#x3C;slug&gt;.py&lt;/code&gt; (e.g., &lt;code dir=&quot;auto&quot;&gt;m_0_9_1_complete_lane_migration.py&lt;/code&gt;). Each module must export a class that inherits from &lt;code dir=&quot;auto&quot;&gt;BaseMigration&lt;/code&gt; and implements a single &lt;code dir=&quot;auto&quot;&gt;apply(project_path: Path, dry_run: bool = False) -&gt; None&lt;/code&gt; method.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Idempotency requirement&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; must be safe to call multiple times on the same project. Use existence checks (&lt;code dir=&quot;auto&quot;&gt;if not target.exists()&lt;/code&gt;) or content-hash comparisons rather than unconditional writes. A failed partial migration followed by a retry must produce the same final state as a successful first run.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Dry-run contract&lt;/strong&gt;: When &lt;code dir=&quot;auto&quot;&gt;dry_run=True&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; must not write any files, run any shell commands, or emit any git commits. It should report what it &lt;em&gt;would&lt;/em&gt; do to stdout (using &lt;code dir=&quot;auto&quot;&gt;rich&lt;/code&gt; where appropriate). The dry-run path must be exercised by at least one test.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Detection reachability&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;MigrationRunner&lt;/code&gt; calls &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; before &lt;code dir=&quot;auto&quot;&gt;can_apply()&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt;, so a write-path safety guard is end-to-end reachable only when the same
unsafe path cannot make &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; return &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; first. &lt;code dir=&quot;auto&quot;&gt;Path.exists()&lt;/code&gt; follows
symlinks and returns &lt;code dir=&quot;auto&quot;&gt;False&lt;/code&gt; for a dangling symlink; a &lt;code dir=&quot;auto&quot;&gt;detect()&lt;/code&gt; existence check
can therefore skip the migration before a later &lt;code dir=&quot;auto&quot;&gt;can_apply()&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; guard runs.
Close unsafe reads in both the detection and write paths, and record that
reachability dependency in the migration PR’s blast-radius note.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Test expectations&lt;/strong&gt;: Each migration module must have a corresponding test in &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/migrations/&lt;/code&gt; that:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Creates a synthetic project directory via &lt;code dir=&quot;auto&quot;&gt;tmp_path&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Calls &lt;code dir=&quot;auto&quot;&gt;apply(project_path)&lt;/code&gt; once (normal run).&lt;/li&gt;
&lt;li&gt;Asserts the expected files/changes are present.&lt;/li&gt;
&lt;li&gt;Calls &lt;code dir=&quot;auto&quot;&gt;apply(project_path)&lt;/code&gt; a second time (idempotency check).&lt;/li&gt;
&lt;li&gt;Asserts the project state is unchanged after the second call.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Naming conventions&lt;/strong&gt;: The migration class must be named &lt;code dir=&quot;auto&quot;&gt;Migration&lt;/code&gt; (singular). The module-level constant &lt;code dir=&quot;auto&quot;&gt;MIGRATION_ID&lt;/code&gt; must be a string matching the filename without the &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; extension. The migration registry in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/registry.py&lt;/code&gt; discovers migrations by scanning this constant.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;How a migration entry-point is registered and invoked&lt;/strong&gt;: Migrations are discovered automatically by &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.discover()&lt;/code&gt;, which imports all &lt;code dir=&quot;auto&quot;&gt;m_*.py&lt;/code&gt; modules under the migrations directory and collects their &lt;code dir=&quot;auto&quot;&gt;Migration&lt;/code&gt; classes. The &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; command invokes &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.run_pending(project_path)&lt;/code&gt;, which filters to migrations with a version greater than the project’s last-applied migration version (stored in &lt;code dir=&quot;auto&quot;&gt;.kittify/migration-state.json&lt;/code&gt;).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;4-rule-family-c--compatibility-shim-lifecycle&quot;&gt;4. Rule Family (c) — Compatibility Shim Lifecycle&lt;/h2&gt;
&lt;p&gt;A compatibility shim is a Python module at the &lt;strong&gt;old&lt;/strong&gt; import path that re-exports all public symbols from the &lt;strong&gt;new canonical&lt;/strong&gt; package. Its sole purpose is to give downstream callers a deprecation window before the old path is removed.&lt;/p&gt;
&lt;h3 id=&quot;when-to-introduce-a-shim&quot;&gt;When to introduce a shim&lt;/h3&gt;
&lt;p&gt;A shim is required when all three conditions hold:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A package is being relocated (old path &lt;code dir=&quot;auto&quot;&gt;specify_cli.X&lt;/code&gt; → new path &lt;code dir=&quot;auto&quot;&gt;X&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The old path was part of a documented or discoverable public API.&lt;/li&gt;
&lt;li&gt;At least one external caller (outside the &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; package itself) imports from the old path.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If condition 3 is not met — that is, if all callers are internal and can be migrated atomically — no shim is needed. The removal of the old path is then a pure refactor with no deprecation window required. The shim registry records this as the “no-shim baseline case” (see Section 7).&lt;/p&gt;
&lt;h3 id=&quot;mandatory-shim-module-shape&quot;&gt;Mandatory shim module shape&lt;/h3&gt;
&lt;p&gt;Every shim must include these six attributes, with no omissions:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Compatibility shim — re-exports from &amp;#x3C;canonical_package&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Deprecated: import from &amp;#x3C;canonical_package&gt; instead. Scheduled for removal in &amp;#x3C;X.Y.Z&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; __future__ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; annotations&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; warnings&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;canonical_package&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# noqa: F401, F403&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;canonical_package&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; __all__  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# if canonical defines __all__&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;__deprecated__ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;True&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;__canonical_import__ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&amp;#x3C;canonical_package&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;__removal_release__ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&amp;#x3C;X.Y.Z&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;__deprecation_message__ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; (&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;specify_cli.&amp;#x3C;legacy_name&gt; is deprecated; import from &amp;#x3C;canonical_package&gt;. &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Scheduled for removal in &amp;#x3C;X.Y.Z&gt;.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;warnings.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;warn&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;__deprecation_message__&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--1:#3B61B0&quot;&gt;&lt;span style=&quot;--0:#82AAFF&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478&quot;&gt;DeprecationWarning&lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D7DBE0;--1:#403F53&quot;&gt;stacklevel&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;2&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;warnings.warn(..., stacklevel=2)&lt;/code&gt; call executes at import time so that any import of the shim module immediately surfaces the deprecation to the calling code’s stack frame (not the shim’s own frame).&lt;/p&gt;
&lt;p&gt;Lazy PEP 562 shims used to avoid eager CLI-startup imports are exempt from the eager re-export and eager &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; lines above. They must still expose &lt;code dir=&quot;auto&quot;&gt;__deprecated__&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;__canonical_import__&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;__removal_release__&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;__deprecation_message__&lt;/code&gt;, and warn on the first import or attribute access.&lt;/p&gt;
&lt;h3 id=&quot;deprecation-window&quot;&gt;Deprecation window&lt;/h3&gt;
&lt;p&gt;A shim must remain in place for &lt;strong&gt;at least one full minor release&lt;/strong&gt; after the canonical path is available. The &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; in the registry must be at least one minor version ahead of the release in which the shim was introduced (e.g., introduced in &lt;code dir=&quot;auto&quot;&gt;3.2.0&lt;/code&gt; → removal no earlier than &lt;code dir=&quot;auto&quot;&gt;3.3.0&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Extension beyond one release is permitted when external consumers have been notified but need additional time. In that case, the registry entry must include &lt;code dir=&quot;auto&quot;&gt;extension_rationale&lt;/code&gt; with a non-empty explanation (e.g., “downstream consumer org X requires migration window per support contract until 2026-Q3”). The &lt;code dir=&quot;auto&quot;&gt;grandfathered: true&lt;/code&gt; flag is reserved for shims that existed before this rulebook and for which a normal removal timeline cannot be applied; all new shims introduced after this mission must set &lt;code dir=&quot;auto&quot;&gt;grandfathered: false&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;5-rule-family-d--removal-plans-and-registry-contract&quot;&gt;5. Rule Family (d) — Removal Plans and Registry Contract&lt;/h2&gt;
&lt;h3 id=&quot;registry-schema&quot;&gt;Registry schema&lt;/h3&gt;
&lt;p&gt;The registry at &lt;code dir=&quot;auto&quot;&gt;docs/migrations/shim-registry.yaml&lt;/code&gt; is the authoritative list of all known compatibility shims. Its schema is defined in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/migration-shim-ownership-rules-01KPDYDW/contracts/shim-registry-schema.yaml&lt;/code&gt;. Each entry requires:&lt;/p&gt;


















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Field&lt;/th&gt;&lt;th&gt;Type&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;legacy_path&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;Dotted Python import path of the shim (e.g., &lt;code dir=&quot;auto&quot;&gt;specify_cli.charter&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;canonical_import&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string or list&lt;/td&gt;&lt;td&gt;The new canonical import path(s)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;introduced_in_release&lt;/code&gt;&lt;/td&gt;&lt;td&gt;semver string&lt;/td&gt;&lt;td&gt;Version when the shim was first introduced&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt;&lt;/td&gt;&lt;td&gt;semver string&lt;/td&gt;&lt;td&gt;Version when the shim will be removed; must be ≥ introduced_in_release&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tracker_issue&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string&lt;/td&gt;&lt;td&gt;GitHub issue reference (&lt;code dir=&quot;auto&quot;&gt;#NNN&lt;/code&gt; or URL) tracking the removal&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;grandfathered&lt;/code&gt;&lt;/td&gt;&lt;td&gt;boolean&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;true&lt;/code&gt; only for pre-rulebook shims; new entries must be &lt;code dir=&quot;auto&quot;&gt;false&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;extension_rationale&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string (optional)&lt;/td&gt;&lt;td&gt;Required if removal window extends past one minor release&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;notes&lt;/code&gt;&lt;/td&gt;&lt;td&gt;string (optional)&lt;/td&gt;&lt;td&gt;Free-form notes for reviewers&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;how-to-add-a-new-entry&quot;&gt;How to add a new entry&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Copy the shim template from Section 4 into the appropriate &lt;code dir=&quot;auto&quot;&gt;src/&amp;#x3C;dotted legacy path&gt;.py&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;src/&amp;#x3C;dotted legacy path&gt;/__init__.py&lt;/code&gt; (including top-level modules).&lt;/li&gt;
&lt;li&gt;Add an entry to &lt;code dir=&quot;auto&quot;&gt;docs/migrations/shim-registry.yaml&lt;/code&gt; with all required fields.&lt;/li&gt;
&lt;li&gt;Open a tracker issue for the removal and record its reference in &lt;code dir=&quot;auto&quot;&gt;tracker_issue&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor shim-registry&lt;/code&gt; and confirm it exits 0 with the new entry showing &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; status.&lt;/li&gt;
&lt;li&gt;Follow the quickstart at &lt;code dir=&quot;auto&quot;&gt;kitty-specs/migration-shim-ownership-rules-01KPDYDW/quickstart.md&lt;/code&gt; for a step-by-step checklist.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;removal-pr-contract&quot;&gt;Removal PR contract&lt;/h3&gt;
&lt;p&gt;When &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; is reached, the removal PR must:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Delete&lt;/strong&gt; the shim module file (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/&amp;#x3C;legacy_name&gt;.py&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/&amp;#x3C;legacy_name&gt;/__init__.py&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Update&lt;/strong&gt; the registry entry — either remove it entirely or mark it with a &lt;code dir=&quot;auto&quot;&gt;removed_in_release&lt;/code&gt; note (convention TBD by the removing engineer; the entry may be deleted once CI passes).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Add&lt;/strong&gt; a changelog fragment, &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&amp;#x3C;pr&gt;.breaking.md&lt;/code&gt;, that names the removal and the release version.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Close&lt;/strong&gt; the tracker issue referenced in &lt;code dir=&quot;auto&quot;&gt;tracker_issue&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Confirm&lt;/strong&gt; CI passes: &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor shim-registry&lt;/code&gt; must exit 0 after the removal.&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id=&quot;6-ci-enforcement&quot;&gt;6. CI Enforcement&lt;/h2&gt;
&lt;h3 id=&quot;spec-kitty-doctor-shim-registry&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor shim-registry&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;This command reads &lt;code dir=&quot;auto&quot;&gt;docs/migrations/shim-registry.yaml&lt;/code&gt;, loads &lt;code dir=&quot;auto&quot;&gt;[project].version&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;, and classifies each registered shim:&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Exit code&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;0&lt;/td&gt;&lt;td&gt;All entries are &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;grandfathered&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;removed&lt;/code&gt; — no action required&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;One or more entries are &lt;code dir=&quot;auto&quot;&gt;overdue&lt;/code&gt; (current project version ≥ &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; and shim file still present)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Configuration error — &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;shim-registry.yaml&lt;/code&gt; is missing or malformed&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Statuses:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;pending&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; &gt; current version; shim file exists — normal lifecycle&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;overdue&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;removal_target_release&lt;/code&gt; ≤ current version; shim file still exists — removal is due&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;grandfathered&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;grandfathered: true&lt;/code&gt; — never classified as overdue regardless of version&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;removed&lt;/strong&gt;: shim file no longer exists on disk — entry is historical&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;testsarchitecturaltest_unregistered_shim_scannerpy&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_unregistered_shim_scanner.py&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;This test walks &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; using Python’s &lt;code dir=&quot;auto&quot;&gt;ast&lt;/code&gt; module, detects any module containing &lt;code dir=&quot;auto&quot;&gt;__deprecated__ = True&lt;/code&gt;, and asserts that every detected path appears in the registry. The test fails if a shim module exists on disk but has no registry entry. This prevents engineers from introducing a shim without registering it.&lt;/p&gt;
&lt;p&gt;The scanner detects both &lt;code dir=&quot;auto&quot;&gt;__deprecated__ = True&lt;/code&gt; (assignment) and &lt;code dir=&quot;auto&quot;&gt;__deprecated__: bool = True&lt;/code&gt; (annotated assignment) forms.&lt;/p&gt;
&lt;h3 id=&quot;testsarchitecturaltest_shim_registry_schemapy&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_shim_registry_schema.py&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;This test loads the live &lt;code dir=&quot;auto&quot;&gt;docs/migrations/shim-registry.yaml&lt;/code&gt; and runs it through &lt;code dir=&quot;auto&quot;&gt;validate_registry()&lt;/code&gt;. It also exercises the validator against known-bad fixtures (missing required fields, wrong types, bad semver, invalid tracker references, &lt;code dir=&quot;auto&quot;&gt;removal_target_release &amp;#x3C; introduced_in_release&lt;/code&gt;) to confirm that &lt;code dir=&quot;auto&quot;&gt;RegistrySchemaError&lt;/code&gt; is raised with a field-specific message for each violation.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;7-worked-example--charter-mission&quot;&gt;7. Worked Example — Charter Mission&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;charter-ownership-consolidation-and-neutrality-hardening-01KPD880&lt;/code&gt; (GitHub #611, #653) is the reference case for applying this rulebook.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rule family (a) — Schema and version gating&lt;/strong&gt;: The charter mission performed a bulk-edit import-path migration from &lt;code dir=&quot;auto&quot;&gt;specify_cli.charter.*&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;charter.*&lt;/code&gt;. Schema version fields in &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; artifacts were not altered by this mission; the mission used the existing schema version contract without modification.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rule family (b) — Migration authoring contract&lt;/strong&gt;: The charter mission produced occurrence maps and bulk-edit tooling to migrate callers from &lt;code dir=&quot;auto&quot;&gt;specify_cli.charter.*&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;charter.*&lt;/code&gt;. Internal callers (within &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;) were migrated atomically as part of the bulk edit. No migration module in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/&lt;/code&gt; was required for this operation because it was a same-release refactor rather than a schema upgrade.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rule family (c) — Compatibility shim lifecycle (no-shim baseline case)&lt;/strong&gt;: The &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/charter/&lt;/code&gt; directory was audited before this mission. At mission start (2026-04-19), &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/charter/__init__.py&lt;/code&gt; did not exist — the directory contained only &lt;code dir=&quot;auto&quot;&gt;__pycache__/&lt;/code&gt;. This confirms that the canonical move from &lt;code dir=&quot;auto&quot;&gt;specify_cli.charter.*&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;charter.*&lt;/code&gt; had &lt;strong&gt;no external importers&lt;/strong&gt; at extraction time; all callers were internal and were migrated atomically.&lt;/p&gt;
&lt;p&gt;Consequently, &lt;strong&gt;no shim was introduced&lt;/strong&gt; for the charter migration. This is a valid exception to rule family (c): the shim precondition (external callers) was not met. The registry records this by remaining empty at mission-615 start, with a comment noting the zero-shim baseline.&lt;/p&gt;
&lt;p&gt;The charter mission therefore demonstrates rule family (c) by &lt;em&gt;not&lt;/em&gt; introducing a shim, and documents this decision explicitly rather than silently omitting the step. Any future extraction mission that similarly has no external callers should follow this precedent and add a comment in its implementation notes stating: &lt;em&gt;“No compatibility shim introduced — all callers were internal and migrated atomically.”&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rule family (d) — Removal plans and registry contract&lt;/strong&gt;: Because no shim was introduced, no registry entry was created for &lt;code dir=&quot;auto&quot;&gt;specify_cli.charter&lt;/code&gt;. The registry baseline remains &lt;code dir=&quot;auto&quot;&gt;shims: []&lt;/code&gt;. Future extraction missions that &lt;em&gt;do&lt;/em&gt; introduce shims (e.g., if a public-facing package with documented external callers is relocated) will add entries following the schema in Section 5.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;8-reference-index&quot;&gt;8. Reference Index&lt;/h2&gt;





















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Artifact&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/architecture/05_ownership_map.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Slice-by-slice ownership map (mission #610)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/migrations/shim-registry.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Machine-readable compatibility shim registry (this mission)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/migration-shim-ownership-rules-01KPDYDW/contracts/shim-registry-schema.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Authoritative YAML schema for registry entries&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/migration-shim-ownership-rules-01KPDYDW/quickstart.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;5-step registration recipe for new shims&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/compat/registry.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Python loader and validator for &lt;code dir=&quot;auto&quot;&gt;shim-registry.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/compat/doctor.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Classification engine powering &lt;code dir=&quot;auto&quot;&gt;doctor shim-registry&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_shim_registry_schema.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Schema validation tests (FR-011)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_unregistered_shim_scanner.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Unregistered shim detector (FR-010)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctor/test_shim_registry.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;CLI integration tests for &lt;code dir=&quot;auto&quot;&gt;doctor shim-registry&lt;/code&gt; (FR-009)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;#461 Phase 7&lt;/td&gt;&lt;td&gt;Planned doctrine-versioning extension (cross-ref only, not implemented here)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;#615&lt;/td&gt;&lt;td&gt;Tracker issue for this mission&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;</content>
</entry>
