<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-01-30-19-auto-discover-migrations-from-filesystem/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-30-19-auto-discover-migrations-from-filesystem/</id>
  <title>Auto-Discover Migrations from Filesystem</title>
  <updated>2026-01-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-01-30-19-auto-discover-migrations-from-filesystem/"/>
  <summary>Discovers upgrade migrations by scanning the package at import time, eliminating the forgotten registration line that repeatedly blocked releases at the CI gate.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;The recurring problem:&lt;/strong&gt;
Every release, we encountered this workflow:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Developer creates new migration file: &lt;code dir=&quot;auto&quot;&gt;m_X_Y_Z_name.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Developer decorates with &lt;code dir=&quot;auto&quot;&gt;@MigrationRegistry.register&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Developer forgets&lt;/strong&gt; to add &lt;code dir=&quot;auto&quot;&gt;from . import m_X_Y_Z_name&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;__init__.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;CI test fails: “Migration registry incomplete! Found N files but only N-1 registered”&lt;/li&gt;
&lt;li&gt;Release blocked until manual import added&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Why this keeps happening:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Two-step process: Create file + Edit &lt;strong&gt;init&lt;/strong&gt;.py&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;init&lt;/strong&gt;.py is far from the migration file in editor&lt;/li&gt;
&lt;li&gt;Easy to forget second step when focused on migration logic&lt;/li&gt;
&lt;li&gt;No IDE autocomplete reminder&lt;/li&gt;
&lt;li&gt;Error only caught at release time (not during development)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Impact:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Every release&lt;/strong&gt; blocked on this issue&lt;/li&gt;
&lt;li&gt;Developer frustration (“we forget every fucking time”)&lt;/li&gt;
&lt;li&gt;Wasted time adding manual imports&lt;/li&gt;
&lt;li&gt;Brittle architecture relying on human memory&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Current architecture (broken):&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame has-title not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;migrations/__init__.py&lt;/span&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:#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;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; m_0_2_0_specify_to_kittify&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;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; m_0_4_8_gitignore_agents&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:#919F9F;--1:#5F636F&quot;&gt;# ... 35 manual imports&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;import&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; m_0_14_0_centralized_feature_detection  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# ← Forgot this!&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Question:&lt;/strong&gt; Should migrations be auto-discovered from the filesystem instead of requiring manual imports?&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Eliminate recurring failure&lt;/strong&gt; - This issue blocks EVERY release&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single responsibility&lt;/strong&gt; - Creating a migration should be one step, not two&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-fast&lt;/strong&gt; - Errors should surface during development, not at release&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Developer experience&lt;/strong&gt; - Reduce cognitive load and manual bookkeeping&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard practice&lt;/strong&gt; - Most migration systems auto-discover (Django, Alembic, etc.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backward compatibility&lt;/strong&gt; - Existing migrations and tests must continue working&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Performance&lt;/strong&gt; - Auto-discovery must be fast (&amp;#x3C;1 second)&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;&lt;strong&gt;Option 1:&lt;/strong&gt; Auto-discovery using pkgutil + importlib (filesystem scan)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Code generation (auto-update &lt;strong&gt;init&lt;/strong&gt;.py on migration creation)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Status quo + better documentation/reminders&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Pre-commit hook to validate &lt;strong&gt;init&lt;/strong&gt;.py&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:&lt;/strong&gt; “Option 1: Auto-discovery using pkgutil + importlib”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Zero manual steps&lt;/strong&gt; - Create migration file, done&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Impossible to forget&lt;/strong&gt; - No second step to forget&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fast&lt;/strong&gt; - Filesystem scan + dynamic import takes &amp;#x3C;100ms&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard pattern&lt;/strong&gt; - Same approach as Django migrations&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Testable&lt;/strong&gt; - Easy to verify all migrations discovered&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backwards compatible&lt;/strong&gt; - Existing @register decorators still work&lt;/li&gt;
&lt;/ul&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;&lt;strong&gt;No more release blockers&lt;/strong&gt; - Migrations auto-discovered, no manual imports&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single-step workflow&lt;/strong&gt; - Create m_*.py file, auto-registered&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Better developer experience&lt;/strong&gt; - Focus on migration logic, not bookkeeping&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-fast&lt;/strong&gt; - Import errors surface immediately, not at release&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standard architecture&lt;/strong&gt; - Aligns with Django, Alembic, and other migration systems&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reduced code&lt;/strong&gt; - 43 lines of manual imports → 52 lines of auto-discovery (but scales to infinite migrations)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Slightly slower startup&lt;/strong&gt; - Must scan directory and import modules (adds ~50ms)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Module reload needed&lt;/strong&gt; - After &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.clear()&lt;/code&gt; in tests, must call &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations()&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Potential import errors&lt;/strong&gt; - Broken migration files fail loudly (but this is good!)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Less explicit&lt;/strong&gt; - Can’t see list of migrations in &lt;strong&gt;init&lt;/strong&gt;.py (but registry provides this)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Naming convention enforced&lt;/strong&gt; - Only &lt;code dir=&quot;auto&quot;&gt;m_*.py&lt;/code&gt; files auto-discovered&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Import-time execution&lt;/strong&gt; - Auto-discovery runs when migrations module imported&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Test isolation&lt;/strong&gt; - Tests must call &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations()&lt;/code&gt; after &lt;code dir=&quot;auto&quot;&gt;clear()&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We validated this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;✅ Auto-discovery finds all 35 existing migrations&lt;/li&gt;
&lt;li&gt;✅ 13 comprehensive tests covering discovery, performance, edge cases&lt;/li&gt;
&lt;li&gt;✅ Migration registry completeness test passes&lt;/li&gt;
&lt;li&gt;✅ Backwards compatible with manual @register decorators&lt;/li&gt;
&lt;li&gt;✅ Performance &amp;#x3C; 100ms (measured in test_auto_discovery_performance)&lt;/li&gt;
&lt;li&gt;✅ Handles import errors gracefully (logs warning, continues)&lt;/li&gt;
&lt;li&gt;✅ Idempotent (can call multiple times safely)&lt;/li&gt;
&lt;/ul&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-1-auto-discovery-using-pkgutil--importlib-chosen&quot;&gt;Option 1: Auto-discovery using pkgutil + importlib (CHOSEN)&lt;/h3&gt;
&lt;p&gt;Scan &lt;code dir=&quot;auto&quot;&gt;migrations/&lt;/code&gt; directory at runtime, dynamically import all &lt;code dir=&quot;auto&quot;&gt;m_*.py&lt;/code&gt; files.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero manual steps (just create file)&lt;/li&gt;
&lt;li&gt;Impossible to forget registration&lt;/li&gt;
&lt;li&gt;Standard pattern (Django, Alembic use this)&lt;/li&gt;
&lt;li&gt;Fast (&amp;#x3C;100ms)&lt;/li&gt;
&lt;li&gt;Testable and verifiable&lt;/li&gt;
&lt;li&gt;Scales to infinite migrations (no manual list)&lt;/li&gt;
&lt;li&gt;Fail-fast (import errors surface immediately)&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;Slightly slower startup (~50ms overhead)&lt;/li&gt;
&lt;li&gt;Module reload needed after clear() in tests&lt;/li&gt;
&lt;li&gt;Less explicit (can’t see migration list in &lt;strong&gt;init&lt;/strong&gt;.py)&lt;/li&gt;
&lt;li&gt;Potential import errors (but good - catches broken migrations early)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-code-generation-auto-update-initpy&quot;&gt;Option 2: Code generation (auto-update &lt;strong&gt;init&lt;/strong&gt;.py)&lt;/h3&gt;
&lt;p&gt;Generate &lt;strong&gt;init&lt;/strong&gt;.py automatically when migration created (e.g., via CLI command).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Explicit migration list visible in &lt;strong&gt;init&lt;/strong&gt;.py&lt;/li&gt;
&lt;li&gt;No runtime scanning overhead&lt;/li&gt;
&lt;li&gt;Familiar pattern (explicit imports)&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;Still two-step process (create migration, run codegen)&lt;/li&gt;
&lt;li&gt;Can forget to run codegen command&lt;/li&gt;
&lt;li&gt;Codegen complexity (when to run? pre-commit hook?)&lt;/li&gt;
&lt;li&gt;Diff noise (every migration adds line to &lt;strong&gt;init&lt;/strong&gt;.py)&lt;/li&gt;
&lt;li&gt;Doesn’t solve core problem (still manual step)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-status-quo--better-documentation&quot;&gt;Option 3: Status quo + better documentation&lt;/h3&gt;
&lt;p&gt;Keep manual imports, add reminders in docs and CI.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No code changes needed&lt;/li&gt;
&lt;li&gt;Explicit migration list in &lt;strong&gt;init&lt;/strong&gt;.py&lt;/li&gt;
&lt;li&gt;No performance overhead&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;&lt;strong&gt;Doesn’t solve the problem&lt;/strong&gt; - Still requires human memory&lt;/li&gt;
&lt;li&gt;Still blocks releases (proven track record)&lt;/li&gt;
&lt;li&gt;Documentation doesn’t prevent mistakes&lt;/li&gt;
&lt;li&gt;Developer frustration persists&lt;/li&gt;
&lt;li&gt;Wasted time on every release&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-pre-commit-hook-validation&quot;&gt;Option 4: Pre-commit hook validation&lt;/h3&gt;
&lt;p&gt;Git hook that checks &lt;strong&gt;init&lt;/strong&gt;.py matches filesystem before commit.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Catches errors before commit&lt;/li&gt;
&lt;li&gt;No runtime overhead&lt;/li&gt;
&lt;li&gt;Fails early in development&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;Still requires manual import (doesn’t eliminate problem)&lt;/li&gt;
&lt;li&gt;Pre-commit hooks can be skipped (&lt;code dir=&quot;auto&quot;&gt;--no-verify&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Adds setup complexity for contributors&lt;/li&gt;
&lt;li&gt;Doesn’t prevent the mistake, just catches it earlier&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Implementation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/__init__.py&lt;/code&gt; - Auto-discovery function&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/upgrade/test_auto_discovery.py&lt;/code&gt; - 13 comprehensive tests&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Auto-Discovery Logic:&lt;/strong&gt;&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:#C792EA;--1:#8844AE&quot;&gt;def&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;auto_discover_migrations&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;()&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; -&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&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;&quot;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Scan migrations/ directory and import all m_*.py files.&lt;/span&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 class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;migrations_dir &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:#B2CCD6;--1:#096E72&quot;&gt;Path&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;__file__&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;).parent&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 class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; module_info &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; pkgutil.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;iter_modules&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;[&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&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;migrations_dir&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;]&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;module_name &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; module_info.name&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 class=&quot;indent&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; module_name.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;startswith&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;m_&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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;or&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; module_name &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;base&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;            &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;module_full_name &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:#C792EA;--1:#8844AE&quot;&gt;f&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;{&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;__name__&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;}&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;{&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;module_name&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;}&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&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;/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:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; module_full_name &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; sys.modules:&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:#919F9F;--1:#5F636F&quot;&gt;# Reload to re-execute @register decorators (for tests)&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;importlib.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;reload&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;sys.modules&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;module_full_name&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:#C792EA;--1:#8844AE&quot;&gt;else&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:#919F9F;--1:#5F636F&quot;&gt;# Fresh import&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;importlib.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;import_module&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;f&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&quot;.&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;{module_name}&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&quot;&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;package&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;__name__&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;&lt;strong&gt;Key Features:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Filesystem scan&lt;/strong&gt; - Uses &lt;code dir=&quot;auto&quot;&gt;pkgutil.iter_modules()&lt;/code&gt; to find all modules&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pattern matching&lt;/strong&gt; - Only imports &lt;code dir=&quot;auto&quot;&gt;m_*.py&lt;/code&gt; files (migration naming convention)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Module reload&lt;/strong&gt; - Handles test isolation (after &lt;code dir=&quot;auto&quot;&gt;MigrationRegistry.clear()&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Graceful errors&lt;/strong&gt; - Logs import failures but continues (fail-fast for broken migrations)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Module-level call&lt;/strong&gt; - Runs automatically when migrations package imported&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Developer Workflow (Before):&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Step 1: Create migration&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:#82AAFF;--1:#3B61B0&quot;&gt;touch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;src/specify_cli/upgrade/migrations/m_0_15_0_my_feature.py&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:#919F9F;--1:#5F636F&quot;&gt;# Write migration class with @MigrationRegistry.register&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:#919F9F;--1:#5F636F&quot;&gt;# Step 2: Edit __init__.py (EASY TO FORGET!)&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:#82AAFF;--1:#3B61B0&quot;&gt;vim&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;src/specify_cli/upgrade/migrations/__init__.py&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:#919F9F;--1:#5F636F&quot;&gt;# Add: from . import m_0_15_0_my_feature&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:#919F9F;--1:#5F636F&quot;&gt;# Step 3: Test&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:#82AAFF;--1:#3B61B0&quot;&gt;pytest&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:#919F9F;--1:#5F636F&quot;&gt;# ❌ Fails if you forgot step 2!&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Developer Workflow (After):&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Step 1: Create migration&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:#82AAFF;--1:#3B61B0&quot;&gt;touch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;src/specify_cli/upgrade/migrations/m_0_15_0_my_feature.py&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:#919F9F;--1:#5F636F&quot;&gt;# Write migration class with @MigrationRegistry.register&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:#919F9F;--1:#5F636F&quot;&gt;# That&apos;s it! Auto-discovered on next import.&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:#82AAFF;--1:#3B61B0&quot;&gt;pytest&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:#919F9F;--1:#5F636F&quot;&gt;# ✅ Passes - migration auto-discovered&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Test Isolation Pattern:&lt;/strong&gt;&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:#C792EA;--1:#8844AE&quot;&gt;def&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;test_my_migration&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&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:#919F9F;--1:#5F636F&quot;&gt;# Clear registry for isolation&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;MigrationRegistry.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;clear&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Re-discover migrations (now includes reload logic)&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:#B2CCD6;--1:#096E72&quot;&gt;auto_discover_migrations&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Test migration&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:#C792EA;--1:#8844AE&quot;&gt;assert&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; MigrationRegistry.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;get_by_id&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;my_migration&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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;is&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;not&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;None&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Performance Benchmarks:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Auto-discovery: ~50-80ms (35 migrations)&lt;/li&gt;
&lt;li&gt;Manual imports: ~20-30ms (35 migrations)&lt;/li&gt;
&lt;li&gt;Overhead: ~30-50ms (acceptable for CLI tool)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Error Handling:&lt;/strong&gt;&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:#919F9F;--1:#5F636F&quot;&gt;# If a migration has import errors, it logs a warning:&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:#C5E478;--1:#3B61B0&quot;&gt;Warning&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Failed to &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; migration module m_broken: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;SyntaxError&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;...&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:#919F9F;--1:#5F636F&quot;&gt;# Then the migration registry validation catches it:&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;Error: Migration m_broken exists but failed to register&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Related Changes:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Removed 43 lines of manual imports from &lt;code dir=&quot;auto&quot;&gt;migrations/__init__.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Added &lt;code dir=&quot;auto&quot;&gt;auto_discover_migrations()&lt;/code&gt; function (52 lines)&lt;/li&gt;
&lt;li&gt;Added 13 comprehensive tests (&lt;code dir=&quot;auto&quot;&gt;test_auto_discovery.py&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Updated &lt;code dir=&quot;auto&quot;&gt;test_migration_robustness.py&lt;/code&gt; to verify discovery completeness&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Migration Naming Convention:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Pattern: &lt;code dir=&quot;auto&quot;&gt;m_&amp;#x3C;major&gt;_&amp;#x3C;minor&gt;_&amp;#x3C;patch&gt;_&amp;#x3C;description&gt;.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Example: &lt;code dir=&quot;auto&quot;&gt;m_0_13_20_auto_discover.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Auto-discovery only imports files matching &lt;code dir=&quot;auto&quot;&gt;m_*.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;None (this is a new pattern for spec-kitty)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Inspiration from:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Django migrations (&lt;code dir=&quot;auto&quot;&gt;django.db.migrations.loader.MigrationLoader&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Alembic migrations (&lt;code dir=&quot;auto&quot;&gt;alembic.script.ScriptDirectory&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Version:&lt;/strong&gt; 0.13.20 (bugfix/architectural improvement)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Real-world validation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;0.13.20 release preparation: Migration registry incomplete (m_0_14_0 forgotten)&lt;/li&gt;
&lt;li&gt;Post-fix: All 35 migrations auto-discovered without manual imports&lt;/li&gt;
&lt;li&gt;No regressions in existing tests (1841 passed)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
