<?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-08-6-global-agent-commands-supersede-project-copies/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-6-global-agent-commands-supersede-project-copies/</id>
  <title>ADR 6 (2026-04-08): Global Agent Commands Supersede Per-Project Copies</title>
  <updated>2026-04-08T00: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-08-6-global-agent-commands-supersede-project-copies/"/>
  <summary>Repairs the command-globalization migration with safety invariants that skip cleanup when the global runtime is absent, plus a second pass for already-migrated projects.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;When spec-kitty was a per-project tool, &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; wrote slash command files into each project’s agent directories:&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;plaintext&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:#d6deeb;--1:#403f53&quot;&gt;.claude/commands/spec-kitty.implement.md&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;.codex/prompts/spec-kitty.plan.md&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;.github/prompts/spec-kitty.specify.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;After the global runtime was introduced, spec-kitty also began installing these commands globally:&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;plaintext&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:#d6deeb;--1:#403f53&quot;&gt;~/.kittify/agent-skills/claude/spec-kitty.implement.md&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;~/.claude/commands/spec-kitty.implement.md   (depending on agent and global config)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Projects that upgraded now have both local (per-project) and global command files. AI tools that index multiple command directories — including Claude Code, Codex, and GitHub Copilot — present all discovered commands to the user. A developer sees &lt;code dir=&quot;auto&quot;&gt;spec-kitty.implement&lt;/code&gt; twice in their slash command list. This is the &lt;strong&gt;double-prompt problem&lt;/strong&gt;.&lt;/p&gt;
&lt;h3 id=&quot;migration-312-original-behavior--unsafe&quot;&gt;Migration 3.1.2 (Original Behavior — Unsafe)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;m_3_1_2_globalize_commands.py&lt;/code&gt; was introduced to address the double-prompt problem. It removes local per-project command files by deleting &lt;code dir=&quot;auto&quot;&gt;.claude/commands/spec-kitty.*.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/spec-kitty.*.md&lt;/code&gt;, and so on.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Critical flaw:&lt;/strong&gt; Migration 3.1.2 deletes local command files unconditionally — it performs no check for the presence of global equivalents. On a developer’s machine where &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; was never created, the migration deletes local command files and leaves the developer with no slash commands at all. There is no recourse; the migration does not leave the local files as a fallback.&lt;/p&gt;
&lt;p&gt;That original &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; behavior was correct enough to identify the desired cleanup, but unsafe for upgrade paths where the global runtime had not been bootstrapped yet.&lt;/p&gt;
&lt;h3 id=&quot;main-branch-correction-for-320a4-this-feature--safe&quot;&gt;Main-Branch Correction for 3.2.0a4 (This Feature — Safe)&lt;/h3&gt;
&lt;p&gt;On &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, before the &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt; pre-release ships, the command-globalization flow is corrected in two places:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;m_3_1_2_globalize_commands.py&lt;/code&gt; is hardened in place so upgrades from versions &lt;em&gt;before&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; get the safe behavior immediately.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4_safe_globalize_commands.py&lt;/code&gt; adds the same safety rules under a new migration ID for projects that already recorded &lt;code dir=&quot;auto&quot;&gt;3.1.2_globalize_commands&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Together, these migrations implement four safety invariants before any deletion:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Global runtime present:&lt;/strong&gt; Checks that &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; exists and is a valid runtime directory. If absent, the migration logs a warning and skips all deletions.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Global agent commands present:&lt;/strong&gt; For each agent being processed, checks that at least one spec-kitty command file exists in the global command location for that agent. If the global equivalent is absent, that agent is skipped (its local files are preserved).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Version marker check:&lt;/strong&gt; Command files generated by spec-kitty contain a version marker on the first line:&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;3.1.0&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Any file without this marker is treated as user-authored and is never touched.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Per-agent skip on failure:&lt;/strong&gt; If any check fails for a given agent, that agent’s local files are left intact. The migration does not fail globally; it reports which agents were processed and which were skipped.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;why-both-312-and-320a4-exist&quot;&gt;Why Both 3.1.2 and 3.2.0a4 Exist&lt;/h3&gt;
&lt;p&gt;The next actual release line is &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; can still harden &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; before that release ships. That covers upgrade chains coming from versions older than &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;However, some projects already recorded &lt;code dir=&quot;auto&quot;&gt;3.1.2_globalize_commands&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. Those projects would never re-run the hardened &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; body, because the migration runner tracks applied migrations by &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4_safe_globalize_commands.py&lt;/code&gt; exists to give that population a safe second pass without mutating migration history.&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;Safety first:&lt;/strong&gt; No user should lose all slash commands because a migration ran before the global runtime was bootstrapped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Release-graph correctness:&lt;/strong&gt; Projects upgrading from pre-&lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; versions and projects that already recorded &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; both need a safe path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Version marker as fingerprint:&lt;/strong&gt; User-authored command files must never be touched. Only spec-kitty-generated files can be removed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-agent granularity:&lt;/strong&gt; A failure or missing global state for one agent must not block processing of other agents.&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 A: Harden &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; and add &lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4_safe_globalize_commands&lt;/code&gt; for already-upgraded projects (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Only add a later safe migration&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Force re-run of &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; via a flag or migration log reset&lt;/strong&gt;&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 A — Harden &lt;code dir=&quot;auto&quot;&gt;m_3_1_2_globalize_commands.py&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; and add &lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4_safe_globalize_commands.py&lt;/code&gt; for projects that already recorded &lt;code dir=&quot;auto&quot;&gt;3.1.2_globalize_commands&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;safety-invariants-in-detail&quot;&gt;Safety Invariants in Detail&lt;/h3&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;apply&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;self&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;project_path&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;dry_run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;bool&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:#FF6A83;--1:#A24848&quot;&gt;False&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; MigrationResult:&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;global_runtime &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; Path.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;home&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:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;.kittify&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;/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;# Invariant 1: Global runtime must exist&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;if&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; global_runtime.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;exists&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;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; MigrationResult.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;skipped&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;Global runtime (~/.kittify) not found. &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;Run `spec-kitty init` first.&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:#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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;agent_dirs &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;get_agent_dirs_for_project&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;project_path&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;results &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;[]&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; agent_root, subdir &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; agent_dirs:&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;local_cmd_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; project_path &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; agent_root &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; subdir&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;# Invariant 2: Local directory must exist&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;if&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; local_cmd_dir.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;exists&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;continue&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;# Invariant 3: Per-agent: global commands must be present&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;global_cmd_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; global_runtime &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;agent-commands&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;/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; agent_root.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;lstrip&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;.&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&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; &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; global_cmd_dir.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;exists&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; &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:#C5E478;--1:#3B61B0&quot;&gt;any&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;global_cmd_dir.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;iterdir&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;results.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;append&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;Skipped &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;{agent_root}&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;: no global commands found&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&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;continue&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; local_file &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; local_cmd_dir.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;glob&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;spec-kitty.*.md&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&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Invariant 4: Version marker check&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;first_line &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; local_file.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;read_text&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;splitlines&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:#F78C6C;--1:#AA0982&quot;&gt;0&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;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; local_file.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;exists&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;else&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;&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:#C792EA;--1:#8844AE&quot;&gt;if&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;spec-kitty-command-version:&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;not&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;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; first_line:&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;continue&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;# User-authored file, do not touch&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; &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; dry_run:&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;local_file.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;unlink&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:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; MigrationResult.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;success&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;results&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;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;Developers who have never run &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; (e.g., CI environments, new machines) do not lose their local command files.&lt;/li&gt;
&lt;li&gt;User-authored command files in agent directories are never touched.&lt;/li&gt;
&lt;li&gt;Per-agent granularity means a missing global config for one agent does not block cleanup of other agents.&lt;/li&gt;
&lt;li&gt;The double-prompt problem is resolved for developers who have completed machine-level setup.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The existence of two safe command-globalization paths (&lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4&lt;/code&gt;) may confuse developers reading the migration log. The relationship between them must be documented in the migration modules.&lt;/li&gt;
&lt;li&gt;Projects that already had local files deleted by the original unsafe &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; behavior do not regain those files automatically. These users must rely on the global runtime for commands — which is the intended steady state.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The version marker (&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!-- spec-kitty-command-version: X.Y.Z --&gt;&lt;/code&gt;) becomes a documented invariant for spec-kitty-generated command files. All future generated files must include it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Correct behavior is confirmed when: running &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; on a project without &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; leaves local command files intact and emits a warning; and running the same upgrade on a project with a valid global runtime removes local spec-kitty command files while leaving user-authored files untouched. Integration tests cover Scenario F and Scenario G from the spec.&lt;/p&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-harden-m_3_1_2-on-main-and-add-m_3_2_0a4-for-already-upgraded-projects-chosen&quot;&gt;Option A: Harden &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; and add &lt;code dir=&quot;auto&quot;&gt;m_3_2_0a4&lt;/code&gt; for already-upgraded projects (chosen)&lt;/h3&gt;
&lt;p&gt;Main-branch hardening plus a follow-up pre-release migration. Operates safely across both upgrade populations that matter for &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Runs on all projects (new ID not in migration log).&lt;/li&gt;
&lt;li&gt;Safety invariants prevent data loss.&lt;/li&gt;
&lt;li&gt;Does not require migration log manipulation.&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;Two migrations addressing the same concern appear in the migration log; requires documentation.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-only-add-a-later-safe-migration&quot;&gt;Option B: Only add a later safe migration&lt;/h3&gt;
&lt;p&gt;Leave &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; untouched and rely solely on a later migration ID.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Keeps &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; immutable.&lt;/li&gt;
&lt;li&gt;Still provides a second pass for projects that already recorded &lt;code dir=&quot;auto&quot;&gt;3.1.2_globalize_commands&lt;/code&gt;.&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;Projects upgrading from versions older than &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; would still encounter the original unsafe behavior on the way to &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The active upgrade path would remain wrong until a later migration repairs it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The next actual release is &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt;, so leaving the active &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt; path unsafe would ship known-bad behavior to users upgrading from older versions.&lt;/p&gt;
&lt;h3 id=&quot;option-c-force-re-run-via-a-flag-or-migration-log-reset&quot;&gt;Option C: Force re-run via a flag or migration log reset&lt;/h3&gt;
&lt;p&gt;Add a mechanism to force &lt;code dir=&quot;auto&quot;&gt;m_3_1_2&lt;/code&gt; to re-run, or clear it from the migration log.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Avoids creating a second migration for the same concern.&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;Forcing re-execution of a migration that already ran and deleted files on some projects may delete files that were never supposed to be deleted (e.g., files created manually after the first run).&lt;/li&gt;
&lt;li&gt;Migration log reset is a destructive operation. It voids the audit trail of what state transitions have occurred.&lt;/li&gt;
&lt;li&gt;Adds complexity (a new “force” mechanism) to solve a problem that is solved cleanly by a new migration ID.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Manipulating the migration log is a destructive operation with unpredictable side effects. A new migration ID is the designed mechanism for “do this again, but correctly”.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Spec:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/076-init-command-overhaul/spec.md&lt;/code&gt; — FR-021 (migration removes per-project command files when global equivalents are confirmed present), FR-022 (must never delete if global equivalent absent), FR-023 (must not touch non-spec-kitty files)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-A (2026-04-08-1) — Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime (the global runtime whose presence is the prerequisite for safe deletion)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-C (2026-04-08-3) — Global skill installation with per-project symlinks (root cause of why per-project copies exist)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-6 (2026-01-23-6) — Config-driven agent management (the &lt;code dir=&quot;auto&quot;&gt;get_agent_dirs_for_project()&lt;/code&gt; helper used by the migration)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code locations:&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_1_2_globalize_commands.py&lt;/code&gt; — hardened active migration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_0a4_safe_globalize_commands.py&lt;/code&gt; — follow-up safe migration for projects already past &lt;code dir=&quot;auto&quot;&gt;3.1.2&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/shims/generator.py:101&lt;/code&gt; — version marker generation (referenced in invariant 4)&lt;/li&gt;
&lt;li&gt;Spec: Scenario F and Scenario G in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/076-init-command-overhaul/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
