Retire alias command groups on toggle; scope preset cleanup to switched-away agent (#2948)

Fixes three current Copilot review findings on HEAD d0d152e:

1. Command->skills toggle cleanup only matched a stale command's own
   name against the returned replacement skill name. Aliases
   (CommandRegistrar tracks and returns primary + alias names flattened
   into one list) never have their own skill rendered -- only the
   primary command's skill is rendered -- so an alias's name could never
   match, leaving its command artifact and tracking behind forever even
   after the primary's replacement landed. Fixed identically in both
   presets (register_enabled_presets_for_agent) and extensions
   (register_enabled_extensions_for_agent): build a primary->alias
   mapping from the manifest, group stale names by primary, and
   retire/keep the whole group together based solely on whether the
   primary's skill replacement actually landed.

2. `integration switch` to a not-yet-installed target unregistered the
   old agent's extension artifacts but had no preset equivalent, so a
   preset's command overrides (including custom preset commands) and
   skill mirrors for the deactivated agent lingered as orphans. Added
   `PresetManager.unregister_agent_artifacts()`, mirroring
   `ExtensionManager.unregister_agent_artifacts()`: scoped strictly to
   the given agent, migrates a legacy flat-list `registered_skills`
   entry via existing on-disk provenance inference before removing
   anything (so other agents' real ownership is preserved rather than
   guessed or dropped), and guards against double-processing an
   artifact through both the commands and skills paths for native
   SKILL.md agents. Wired via a new `_unregister_presets_for_agent()`
   helper into the integration switch command's existing old-agent
   cleanup phase.

Added red-first regression tests:
- tests/test_presets.py: alias-group retire/keep/partial-multi-group
  tests for the command->skills toggle; unregister_agent_artifacts
  scoping tests for commands and legacy-list skill provenance.
- tests/test_extension_skills.py: alias-group retire/keep tests for the
  extension command->skills toggle.
- tests/integrations/test_integration_subcommand.py: end-to-end switch
  test proving a preset's custom command override is cleaned up when
  switching to a not-yet-installed integration, with tracking updated
  correctly and the new agent's registration unaffected.

All new tests confirmed red (AttributeError / orphaned file assertions)
before the fix and green after. Full suite: 3980 passed, 109 skipped.
ruff check clean on all changed files.

Assisted-by: GitHub Copilot (model: Claude Sonnet 5, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: marcelsafin

src/specify_cli/extensions/__init__.py

@@ -2158,10 +2158,46 @@ def register_enabled_extensions_for_agent(self, agent_name: str) -> None:
                         # would leave neither artifact (#2948).
                         if deferred_stale_commands:
                             replaced_skill_names = set(registered_skills or [])
+                            # Commands may carry aliases (CommandRegistrar.
+                            # register_commands_for_agent() tracks and
+                            # returns primary + alias names flattened
+                            # together into one list), but
+                            # _register_extension_skills() only ever
+                            # renders/returns the *primary* command name's
+                            # skill — running an alias's own name through
+                            # _skill_name_from_command() never matches
+                            # anything real, so an alias would stay
+                            # tracked/on-disk forever even after its
+                            # primary's skill replacement landed. Map each
+                            # stale name back to its manifest command's
+                            # primary so the whole primary+alias group is
+                            # retired or kept together, based solely on
+                            # whether the *primary*'s skill replacement
+                            # actually landed (#2948).
+                            alias_to_primary: Dict[str, str] = {}
+                            for cmd_info in manifest.commands:
+                                primary_name = cmd_info.get("name")
+                                if not isinstance(primary_name, str):
+                                    continue
+                                for alias in cmd_info.get("aliases", []) or []:
+                                    if isinstance(alias, str):
+                                        alias_to_primary[alias] = primary_name
+
+                            group_fully_replaced: Dict[str, bool] = {}
+                            for cmd_name in deferred_stale_commands:
+                                primary_name = alias_to_primary.get(cmd_name, cmd_name)
+                                if primary_name in group_fully_replaced:
+                                    continue
+                                group_fully_replaced[primary_name] = (
+                                    HookExecutor._skill_name_from_command(primary_name)
+                                    in replaced_skill_names
+                                )
+
                             fully_replaced = [
                                 cmd_name for cmd_name in deferred_stale_commands
-                                if HookExecutor._skill_name_from_command(cmd_name)
-                                in replaced_skill_names
+                                if group_fully_replaced.get(
+                                    alias_to_primary.get(cmd_name, cmd_name), False
+                                )
                             ]
                             if fully_replaced:
                                 registrar.unregister_commands(

src/specify_cli/integrations/_helpers.py

@@ -451,6 +451,39 @@ def _register_presets_for_agent(
         )
 
 
+def _unregister_presets_for_agent(
+    project_root: Path,
+    agent_key: str,
+    *,
+    continuing: str,
+) -> None:
+    """Best-effort removal of ``agent_key``'s preset command/skill artifacts.
+
+    Mirrors ``_unregister_extensions_for_agent``: used by ``switch`` when
+    uninstalling the previous integration so its preset command overrides
+    and skill mirrors don't linger as orphans in the old agent's directory
+    once a different (possibly not-yet-installed) integration becomes
+    active (#2948).
+
+    Best-effort: never aborts the surrounding integration operation.
+    """
+    try:
+        from ..presets import PresetManager
+
+        preset_mgr = PresetManager(project_root)
+        preset_mgr.unregister_agent_artifacts(agent_key)
+    except Exception as preset_err:
+        from .. import _print_cli_warning
+
+        _print_cli_warning(
+            "clean up preset artifacts for",
+            "integration",
+            agent_key,
+            preset_err,
+            continuing=continuing,
+        )
+
+
 # ---------------------------------------------------------------------------
 # CLI formatting helpers (re-exported from _commands.py)
 # ---------------------------------------------------------------------------

src/specify_cli/integrations/_migrate_commands.py

@@ -36,6 +36,7 @@
     _set_default_integration,
     _set_default_integration_or_exit,
     _unregister_extensions_for_agent,
+    _unregister_presets_for_agent,
     _update_init_options_for_integration,
     _write_integration_json,
 )
@@ -196,6 +197,19 @@ def integration_switch(
             continuing="Continuing with integration switch; old extension artifacts may need manual cleanup.",
         )
 
+        # Unregister preset commands/skills for the old agent for the same
+        # reason: without this, a preset's command overrides (including
+        # custom preset commands) and skill mirrors rendered for
+        # installed_key would remain orphaned in its directory once a
+        # different, possibly not-yet-installed integration becomes active
+        # (#2948). Scoped strictly to installed_key; other agents' files,
+        # tracking, and the preset packs themselves are untouched.
+        _unregister_presets_for_agent(
+            project_root,
+            installed_key,
+            continuing="Continuing with integration switch; old preset artifacts may need manual cleanup.",
+        )
+
         # Clear metadata so a failed Phase 2 doesn't leave stale references
         installed_keys = [installed for installed in installed_keys if installed != installed_key]
         _clear_init_options_for_integration(project_root, installed_key)

src/specify_cli/presets/__init__.py

@@ -902,11 +902,46 @@ def register_enabled_presets_for_agent(self, agent_name: str) -> None:
                 # unreplaced stays tracked and on disk (#2948).
                 if stale_command_names:
                     replaced_skill_names = set(registered_skills.get(agent_name) or [])
+                    # Commands may carry aliases (CommandRegistrar.register_
+                    # commands() tracks and returns primary + alias names
+                    # flattened together into one list), but _register_
+                    # skills() only ever renders/returns the *primary*
+                    # command name's skill — running an alias's own name
+                    # through _skill_names_for_command() never matches
+                    # anything real, so an alias would stay tracked/on-disk
+                    # forever even after its primary's skill replacement
+                    # landed. Map each stale name back to its template's
+                    # primary via the manifest so the whole primary+alias
+                    # group is retired or kept together, based solely on
+                    # whether the *primary*'s skill replacement actually
+                    # landed (#2948).
+                    alias_to_primary: Dict[str, str] = {}
+                    for tmpl in manifest.templates:
+                        if tmpl.get("type") != "command":
+                            continue
+                        primary_name = tmpl.get("name")
+                        if not isinstance(primary_name, str):
+                            continue
+                        for alias in tmpl.get("aliases", []):
+                            if isinstance(alias, str):
+                                alias_to_primary[alias] = primary_name
+
+                    group_fully_replaced: Dict[str, bool] = {}
+                    for cmd_name in stale_command_names:
+                        primary_name = alias_to_primary.get(cmd_name, cmd_name)
+                        if primary_name in group_fully_replaced:
+                            continue
+                        modern_name, legacy_name = self._skill_names_for_command(primary_name)
+                        group_fully_replaced[primary_name] = (
+                            modern_name in replaced_skill_names
+                            or legacy_name in replaced_skill_names
+                        )
+
                     fully_replaced = []
                     remaining_stale = []
                     for cmd_name in stale_command_names:
-                        modern_name, legacy_name = self._skill_names_for_command(cmd_name)
-                        if modern_name in replaced_skill_names or legacy_name in replaced_skill_names:
+                        primary_name = alias_to_primary.get(cmd_name, cmd_name)
+                        if group_fully_replaced.get(primary_name, False):
                             fully_replaced.append(cmd_name)
                         else:
                             remaining_stale.append(cmd_name)
@@ -952,6 +987,105 @@ def register_enabled_presets_for_agent(self, agent_name: str) -> None:
                     stacklevel=2,
                 )
 
+    def unregister_agent_artifacts(self, agent_name: str) -> None:
+        """Remove ``agent_name``'s tracked preset command/skill artifacts.
+
+        Mirrors ``ExtensionManager.unregister_agent_artifacts()`` (#2948):
+        used by ``integration switch`` when deactivating the previous
+        integration, so a preset's command overrides and skill mirrors
+        written for that agent don't linger as orphans in its directory
+        once a different (possibly not-yet-installed) integration becomes
+        active — including custom preset commands and files the registrar
+        would otherwise skip as user-modified.
+
+        Scoped strictly to ``agent_name``: only that agent's own tracked
+        artifacts and registry entries are touched. Other agents' files,
+        tracking, and preset packs themselves are left untouched, and no
+        priority-stack reconciliation runs — this is agent-scoped cleanup
+        only, not preset removal.
+        """
+        if not agent_name:
+            return
+
+        try:
+            from ..agents import CommandRegistrar
+
+            agent_config = CommandRegistrar().AGENT_CONFIGS.get(agent_name)
+        except ImportError:
+            agent_config = None
+        if agent_config is None:
+            return
+
+        for pack_id, metadata in list(self.registry.list().items()):
+            pack_dir = self.presets_dir / pack_id
+            updates: Dict[str, Any] = {}
+
+            raw_skills = metadata.get("registered_skills", [])
+            if isinstance(raw_skills, list) and raw_skills:
+                # Legacy flat-list value predating per-agent provenance:
+                # infer real ownership from on-disk markers before removing
+                # anything, so only agent_name's actual share is unregistered
+                # and the rest migrates to per-agent form instead of either
+                # guessing every name belongs to agent_name or blindly
+                # leaving other agents' shares unrecoverable (#2948).
+                registered_skills_all = self._infer_legacy_skill_provenance(
+                    [n for n in raw_skills if isinstance(n, str)],
+                    pack_id,
+                    fallback_agent=agent_name,
+                )
+                skills_migrated = True
+            elif isinstance(raw_skills, dict):
+                registered_skills_all = copy.deepcopy(raw_skills)
+                skills_migrated = False
+            else:
+                registered_skills_all = {}
+                skills_migrated = False
+
+            registered_commands = metadata.get("registered_commands", {})
+            if not isinstance(registered_commands, dict):
+                registered_commands = {}
+
+            agent_command_names = [
+                n for n in registered_commands.get(agent_name, []) if isinstance(n, str)
+            ]
+
+            # Native SKILL.md agents (claude/codex/agy/…) materialize their
+            # preset override in _register_commands(), tracked under
+            # registered_commands, not registered_skills — see
+            # _register_skills()'s own docstring ("Native skill agents …
+            # materialize brand-new preset skills in _register_commands()").
+            # A legacy flat-list registered_skills value predating that
+            # split can still attribute the very same on-disk file to this
+            # agent via provenance inference; unregistering through both
+            # paths would double-process the identical directory (delete
+            # via the commands path, then no-op "restore" via the skills
+            # path since the directory is already gone). Mirror remove()'s
+            # own coordination: whenever this agent's artifact is already
+            # handled via registered_commands, never additionally treat it
+            # as a registered_skills entry for the same agent.
+            if agent_command_names and agent_config.get("extension") == "/SKILL.md":
+                registered_skills_all.pop(agent_name, None)
+
+            if agent_command_names:
+                self._unregister_commands({agent_name: agent_command_names})
+                new_registered_commands = copy.deepcopy(registered_commands)
+                new_registered_commands.pop(agent_name, None)
+                updates["registered_commands"] = new_registered_commands
+
+            agent_skill_names = registered_skills_all.get(agent_name) or []
+            if agent_skill_names or skills_migrated:
+                if agent_skill_names:
+                    self._unregister_skills({agent_name: agent_skill_names}, pack_dir)
+                remaining = {
+                    other_agent: names
+                    for other_agent, names in registered_skills_all.items()
+                    if other_agent != agent_name
+                }
+                updates["registered_skills"] = remaining
+
+            if updates:
+                self.registry.update(pack_id, updates)
+
     def _unregister_commands(self, registered_commands: Dict[str, List[str]]) -> None:
         """Remove previously registered command files from agent directories.
 

tests/integrations/test_integration_subcommand.py

@@ -2281,6 +2281,83 @@ def test_switch_migrates_copilot_skills_extension_commands(self, tmp_path):
         assert "opencode" in git_meta["registered_commands"]
         assert "copilot" not in git_meta["registered_commands"]
 
+    def test_switch_to_not_yet_installed_unregisters_old_preset_artifacts(self, tmp_path):
+        """Switching to a not-yet-installed integration must also clean up
+        the old agent's preset command overrides, mirroring the existing
+        extension cleanup on the same code path (#2948).
+
+        Without this, a preset's command override -- including a custom
+        preset command -- rendered for the previous agent lingers as an
+        orphan once a different, not-yet-installed integration becomes the
+        new active agent.
+        """
+        project = _init_project(tmp_path, "auggie")
+
+        preset_src = tmp_path / "switch-cleanup-preset"
+        (preset_src / "commands").mkdir(parents=True)
+        (preset_src / "commands" / "speckit.specify.md").write_text(
+            "---\ndescription: Custom preset command\n---\nOverridden content\n",
+            encoding="utf-8",
+        )
+        manifest_data = {
+            "schema_version": "1.0",
+            "preset": {
+                "id": "switch-cleanup-preset",
+                "name": "Switch Cleanup Preset",
+                "version": "1.0.0",
+                "description": "Test preset with a custom command override",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "templates": [
+                    {
+                        "type": "command",
+                        "name": "speckit.specify",
+                        "file": "commands/speckit.specify.md",
+                    }
+                ]
+            },
+        }
+        import yaml
+
+        (preset_src / "preset.yml").write_text(yaml.dump(manifest_data), encoding="utf-8")
+
+        result = _run_in_project(project, ["preset", "add", "--dev", str(preset_src)])
+        assert result.exit_code == 0, f"preset add failed: {result.output}"
+
+        auggie_cmd = project / ".augment" / "commands" / "speckit.specify.md"
+        assert auggie_cmd.exists(), "sanity: preset command registered for auggie"
+
+        registry_path = project / ".specify" / "presets" / ".registry"
+        registered = json.loads(registry_path.read_text(encoding="utf-8"))[
+            "presets"
+        ]["switch-cleanup-preset"]["registered_commands"]
+        assert "auggie" in registered, "sanity: auggie tracked before switch"
+
+        # opencode is not yet installed in this project.
+        result = _run_in_project(project, [
+            "integration", "switch", "opencode",
+            "--script", "sh",
+        ])
+        assert result.exit_code == 0, result.output
+
+        assert not auggie_cmd.exists(), (
+            "old agent's preset command override must be removed on switch "
+            "to a not-yet-installed integration, mirroring the existing "
+            "extension cleanup on this same code path (#2948)"
+        )
+
+        opencode_cmd = project / ".opencode" / "commands" / "speckit.specify.md"
+        assert opencode_cmd.exists(), "preset command should be registered for the new agent"
+
+        registered = json.loads(registry_path.read_text(encoding="utf-8"))[
+            "presets"
+        ]["switch-cleanup-preset"]["registered_commands"]
+        assert "auggie" not in registered, (
+            "old agent's tracking must be dropped after switch cleanup"
+        )
+        assert "opencode" in registered
+
     def test_switch_does_not_register_disabled_extensions(self, tmp_path):
         """Disabled extensions should stay disabled and should not migrate commands."""
         project = _init_project(tmp_path, "opencode")