fix(extensions): canonicalize hook alias refs and fix docstrings (#2017)

- Hook refs in alias form (ext.cmd) are now lifted to canonical
  speckit.{ext}.cmd so _skill_name_from_command maps them correctly
  in skill-mode invocation; non-dict hook entries are skipped safely
- Validate that 'hooks' is a mapping; raise ValidationError for
  non-dict hooks value instead of AttributeError
- Update _collect_manifest_command_names docstring to reflect that
  aliases now use {extension}.{command}, not speckit.{extension}.{command}
- Fix test docstring to name the concrete alias value used in the test
- Add tests for hook alias canonicalization and non-dict hooks validation

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

Author: iamaeroplane

src/specify_cli/extensions.py

@@ -247,21 +247,39 @@ def _validate(self):
                             "(the 'speckit.' prefix is reserved for core commands)"
                         )
 
-        # Rewrite any hook command references that pointed at a renamed command.
+        # Rewrite any hook command references that pointed at a renamed command,
+        # then canonicalize alias-form refs (e.g. 'ext.cmd') to the canonical
+        # 'speckit.{ext}.cmd' form so hook-invocation skill-name mapping works.
         hooks = self.data.get("hooks", {})
         if not isinstance(hooks, dict):
             raise ValidationError(
                 f"'hooks' must be a mapping, got {type(hooks).__name__}"
             )
         for hook_name, hook_data in hooks.items():
-            if isinstance(hook_data, dict) and hook_data.get("command") in rename_map:
-                old_ref = hook_data["command"]
-                hook_data["command"] = rename_map[old_ref]
+            if not isinstance(hook_data, dict):
+                continue
+            command_ref = hook_data.get("command")
+            if not isinstance(command_ref, str):
+                continue
+
+            # Step 1: apply rename_map (command was auto-corrected during validation).
+            rewritten = rename_map.get(command_ref, command_ref)
+            if rewritten != command_ref:
+                hook_data["command"] = rewritten
                 self.warnings.append(
-                    f"Hook '{hook_name}' referenced renamed command '{old_ref}'; "
-                    f"updated to '{rename_map[old_ref]}'. "
+                    f"Hook '{hook_name}' referenced renamed command '{command_ref}'; "
+                    f"updated to '{rewritten}'. "
                     f"The extension author should update the manifest."
                 )
+                command_ref = rewritten
+
+            # Step 2: if the ref is in alias form '{ext_id}.cmd', lift it to
+            # 'speckit.{ext_id}.cmd' so skill-mode hook invocation renders correctly.
+            parts = command_ref.split('.')
+            if len(parts) == 2 and parts[0] == ext["id"]:
+                canonical = f"speckit.{ext['id']}.{parts[1]}"
+                if EXTENSION_COMMAND_NAME_PATTERN.match(canonical):
+                    hook_data["command"] = canonical
 
     @staticmethod
     def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
@@ -601,7 +619,8 @@ def _collect_manifest_command_names(manifest: ExtensionManifest) -> Dict[str, st
         """Collect command and alias names declared by a manifest.
 
         Performs install-time validation for extension-specific constraints:
-        - commands and aliases must use the canonical `speckit.{extension}.{command}` shape
+        - primary commands must use the canonical `speckit.{extension}.{command}` shape
+        - aliases must use the `{extension}.{command}` shape (no `speckit.` prefix)
         - commands and aliases must use this extension's namespace
         - command namespaces must not shadow core commands
         - duplicate command/alias names inside one manifest are rejected

tests/test_extensions.py

@@ -305,7 +305,7 @@ def test_command_name_mismatched_namespace_not_corrected(self, temp_dir, valid_m
             ExtensionManifest(manifest_path)
 
     def test_alias_valid_two_part_no_prefix(self, temp_dir, valid_manifest_data):
-        """Test that a 'myext.command' alias is accepted as-is with no warning."""
+        """Test that a 'test-ext.hello' alias is accepted as-is with no warning."""
         import yaml
 
         valid_manifest_data["provides"]["commands"][0]["aliases"] = ["test-ext.hello"]
@@ -355,6 +355,36 @@ def test_alias_autocorrect_speckit_three_part(self, temp_dir, valid_manifest_dat
         assert "speckit.test-ext.hello" in manifest.warnings[0]
         assert "test-ext.hello" in manifest.warnings[0]
 
+    def test_hook_alias_ref_canonicalized_to_speckit_form(self, temp_dir, valid_manifest_data):
+        """Hook command refs in alias form are lifted to canonical speckit.ext.cmd form."""
+        import yaml
+
+        # Manifest uses a valid alias but the hook mistakenly references the alias name.
+        valid_manifest_data["provides"]["commands"][0]["aliases"] = ["test-ext.hello"]
+        valid_manifest_data["hooks"]["after_tasks"]["command"] = "test-ext.hello"
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, "w") as f:
+            yaml.dump(valid_manifest_data, f)
+
+        manifest = ExtensionManifest(manifest_path)
+
+        # Hook ref should be lifted to canonical form for skill-mode invocation.
+        assert manifest.hooks["after_tasks"]["command"] == "speckit.test-ext.hello"
+
+    def test_hook_non_dict_value_raises(self, temp_dir, valid_manifest_data):
+        """A non-mapping hooks value raises ValidationError."""
+        import yaml
+
+        valid_manifest_data["hooks"] = ["not", "a", "dict"]
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, "w") as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="'hooks' must be a mapping"):
+            ExtensionManifest(manifest_path)
+
     def test_valid_command_name_has_no_warnings(self, temp_dir, valid_manifest_data):
         """Test that a correctly-named command produces no warnings."""
         import yaml