fix(extensions): detect cross-command SKILL name collisions in manifest validation

Extend the SKILL output name collision check in ExtensionManifest._validate()
to cover cross-command scenarios: a primary on command A and an alias on command B
that both map to the same SKILL.md directory (e.g. 'speckit.myext.build' and alias
'myext.build' on a different entry both produce 'speckit-myext-build/SKILL.md').

Previously only same-entry collisions were caught. Now a shared dict of seen
SKILL output names is maintained across all commands and aliases, and any
duplicate raises ValidationError with a clear message indicating the claimant.

Adds _skill_output_name() static helper to mirror _compute_output_name logic
for SKILL.md agents without importing the agents module.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: iamaeroplane

src/specify_cli/extensions.py

@@ -192,6 +192,12 @@ def _validate(self):
 
         # Validate commands; track renames so hook references can be rewritten.
         rename_map: Dict[str, str] = {}
+        # Track SKILL output names across all commands+aliases to catch cross-command
+        # collisions. For SKILL.md agents, _compute_output_name strips the 'speckit.'
+        # prefix and hyphenates: 'speckit.myext.build' and alias 'myext.build' on a
+        # *different* command entry both map to 'speckit-myext-build/SKILL.md'.
+        seen_skill_names: Dict[str, str] = {}  # skill_output_name -> description of claimant
+
         for cmd in provides["commands"]:
             if "name" not in cmd or "file" not in cmd:
                 raise ValidationError("Command missing 'name' or 'file'")
@@ -213,6 +219,17 @@ def _validate(self):
                         "must follow pattern 'speckit.{extension}.{command}'"
                     )
 
+            # Register the primary command's SKILL output name.
+            primary_skill = self._skill_output_name(cmd["name"])
+            if primary_skill in seen_skill_names:
+                raise ValidationError(
+                    f"Command '{cmd['name']}' would produce SKILL output name "
+                    f"'{primary_skill}' which is already claimed by "
+                    f"{seen_skill_names[primary_skill]}. "
+                    f"Choose a distinct command name."
+                )
+            seen_skill_names[primary_skill] = f"primary command '{cmd['name']}'"
+
             # Validate and auto-correct alias name formats
             aliases = cmd.get("aliases")
             if aliases is None:
@@ -229,21 +246,22 @@ def _validate(self):
                     )
                 alias_match = EXTENSION_ALIAS_PATTERN.match(alias)
                 if alias_match and alias_match.group(1) != 'speckit':
-                    # Valid 'ext.cmd' form — check it won't collide with the primary
-                    # command's SKILL output name. For SKILL.md agents,
-                    # _compute_output_name strips 'speckit.' so e.g. primary
-                    # 'speckit.myext.run' and alias 'myext.run' both map to
-                    # 'speckit-myext-run', causing the alias write to overwrite
-                    # the primary skill file.
-                    primary = cmd["name"]
-                    if primary.startswith("speckit.") and primary[len("speckit."):] == alias:
-                        skill_name = "speckit-" + alias.replace(".", "-")
+                    # Valid 'ext.cmd' form — check it won't collide with any previously
+                    # seen primary or alias SKILL output name (including its own command's
+                    # primary). For SKILL.md agents, _compute_output_name strips 'speckit.'
+                    # so e.g. primary 'speckit.myext.run' and alias 'myext.run' both map
+                    # to 'speckit-myext-run', causing the alias write to overwrite the
+                    # primary skill file.
+                    alias_skill = self._skill_output_name(alias)
+                    if alias_skill in seen_skill_names:
+                        skill_name = alias_skill
                         raise ValidationError(
-                            f"Alias '{alias}' would collide with primary command "
-                            f"'{primary}' on SKILL.md-based agents (both map to "
-                            f"'{skill_name}'). "
+                            f"Alias '{alias}' on command '{cmd['name']}' would produce "
+                            f"SKILL output name '{skill_name}' which is already claimed by "
+                            f"{seen_skill_names[alias_skill]}. "
                             f"Choose a distinct alias name."
                         )
+                    seen_skill_names[alias_skill] = f"alias '{alias}' on command '{cmd['name']}'"
                 else:
                     corrected = self._try_correct_alias_name(alias, ext["id"])
                     if corrected:
@@ -304,6 +322,16 @@ def _validate(self):
                         f"the canonical command name directly."
                     )
 
+    @staticmethod
+    def _skill_output_name(cmd_name: str) -> str:
+        """Compute the SKILL.md directory name for a command or alias.
+
+        Mirrors the logic in CommandRegistrar._compute_output_name for SKILL.md
+        agents: strip the 'speckit.' prefix (if present) then hyphenate.
+        """
+        short = cmd_name[len("speckit."):] if cmd_name.startswith("speckit.") else cmd_name
+        return "speckit-" + short.replace(".", "-")
+
     @staticmethod
     def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
         """Try to auto-correct a non-conforming primary command name to 'speckit.{ext_id}.command'.

tests/test_extensions.py

@@ -373,7 +373,28 @@ def test_alias_collision_with_primary_skill_name_rejected(self, temp_dir, valid_
         with open(manifest_path, "w") as f:
             yaml.dump(valid_manifest_data, f)
 
-        with pytest.raises(ValidationError, match="would collide with primary command"):
+        with pytest.raises(ValidationError, match="would produce SKILL output name"):
+            ExtensionManifest(manifest_path)
+
+    def test_cross_command_skill_name_collision_rejected(self, temp_dir, valid_manifest_data):
+        """Alias on one command that collides with a primary on a different command is rejected."""
+        import yaml
+
+        # Command A: primary 'speckit.test-ext.hello' → skill 'speckit-test-ext-hello'
+        # Command B: primary 'speckit.test-ext.build' with alias 'test-ext.hello'
+        #            → alias also maps to 'speckit-test-ext-hello' — collision with cmd A.
+        valid_manifest_data["provides"]["commands"][0]["aliases"] = []
+        valid_manifest_data["provides"]["commands"].append({
+            "name": "speckit.test-ext.build",
+            "file": "commands/build.md",
+            "aliases": ["test-ext.hello"],
+        })
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, "w") as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="would produce SKILL output name"):
             ExtensionManifest(manifest_path)
 
     def test_hook_alias_ref_canonicalized_to_speckit_form(self, temp_dir, valid_manifest_data):