fix: resolve extension commands via manifest file mapping

PresetResolver.resolve_extension_command_via_manifest() consults each
installed extension.yml to find the actual file declared for a command
name, rather than assuming the file is named <cmd_name>.md.  This fixes
_substitute_core_template for extensions like selftest where the manifest
maps speckit.selftest.extension → commands/selftest.md.

Resolution order in _substitute_core_template is now:
  1. resolve_core(cmd_name) — project overrides win, then name-based lookup
  2. resolve_extension_command_via_manifest(cmd_name) — manifest fallback
  3. resolve_core(short_name) — core template short-name fallback

Path traversal guard mirrors the containment check already present in
ExtensionManager to reject absolute paths or paths escaping the extension
root.

Author: kennedy-whytech

src/specify_cli/presets.py

@@ -60,13 +60,22 @@ def _substitute_core_template(
         short_name = short_name[len("speckit."):]
 
     resolver = PresetResolver(project_root)
-    # Try the full command name first so extension commands
-    # (e.g. speckit.git.feature -> extensions/git/commands/speckit.git.feature.md)
-    # are found before falling back to the short name used by core commands
-    # (e.g. specify -> templates/commands/specify.md).
-    # Use resolve_core() to skip installed presets (tier 2), preventing accidental
-    # nesting where another preset's wrap output is mistaken for the real core.
-    core_file = resolver.resolve_core(cmd_name, "command") or resolver.resolve_core(short_name, "command")
+    # Resolution order for the core template:
+    # 1. resolve_core(cmd_name) — covers tier-1 project overrides and tier-3/4
+    #    name-based lookup (file named <cmd_name>.md).  Checked first so that a
+    #    local override always wins, even for extension commands.
+    # 2. resolve_extension_command_via_manifest(cmd_name) — manifest-based tier-3
+    #    fallback for extension commands whose file is named differently from the
+    #    command name (e.g. speckit.selftest.extension → commands/selftest.md).
+    # 3. resolve_core(short_name) — core template fallback using the unprefixed
+    #    name (e.g. specify → templates/commands/specify.md).
+    # resolve_core() skips installed presets (tier 2) to prevent accidental nesting
+    # where another preset's wrap output is mistaken for the real core.
+    core_file = (
+        resolver.resolve_core(cmd_name, "command")
+        or resolver.resolve_extension_command_via_manifest(cmd_name)
+        or resolver.resolve_core(short_name, "command")
+    )
     if core_file is None:
         return body, {}
 
@@ -2134,6 +2143,54 @@ def resolve_core(
         """
         return self.resolve(template_name, template_type, skip_presets=True)
 
+    def resolve_extension_command_via_manifest(self, cmd_name: str) -> Optional[Path]:
+        """Resolve an extension command by consulting installed extension manifests.
+
+        Walks installed extension directories in priority order, loads each
+        extension.yml via ExtensionManifest, and looks up the command by its
+        declared name to find the actual file path.  This is necessary because
+        the manifest's ``provides.commands[].file`` field is authoritative and
+        may differ from the command name
+        (e.g. ``speckit.selftest.extension`` → ``commands/selftest.md``).
+
+        Returns None if no manifest maps the given command name, so the caller
+        can fall back to the name-based lookup.
+        """
+        if not self.extensions_dir.exists():
+            return None
+
+        from .extensions import ExtensionManifest, ValidationError
+
+        for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():
+            ext_dir = self.extensions_dir / ext_id
+            manifest_path = ext_dir / "extension.yml"
+            if not manifest_path.is_file():
+                continue
+            try:
+                manifest = ExtensionManifest(manifest_path)
+            except (ValidationError, Exception):
+                continue
+            for cmd_info in manifest.commands:
+                if cmd_info.get("name") != cmd_name:
+                    continue
+                file_rel = cmd_info.get("file")
+                if not file_rel:
+                    continue
+                # Mirror the containment check in ExtensionManager to guard against
+                # path traversal via a malformed manifest (e.g. file: ../../AGENTS.md).
+                cmd_path = Path(file_rel)
+                if cmd_path.is_absolute():
+                    continue
+                try:
+                    ext_root = ext_dir.resolve()
+                    candidate = (ext_root / cmd_path).resolve()
+                    candidate.relative_to(ext_root)  # raises ValueError if outside
+                except (OSError, ValueError):
+                    continue
+                if candidate.is_file():
+                    return candidate
+        return None
+
     def resolve_with_source(
         self,
         template_name: str,

tests/test_presets.py

@@ -3545,6 +3545,45 @@ def test_extension_command_resolves_via_extension_directory(self, project_dir):
         assert "# Git Feature Core" in result
         assert "{CORE_TEMPLATE}" not in result
 
+    def test_extension_command_resolves_via_manifest_when_filename_differs(self, project_dir):
+        """Extension commands whose filename differs from the command name resolve via extension.yml.
+
+        The selftest extension maps speckit.selftest.extension → commands/selftest.md.
+        Name-based lookup would look for commands/speckit.selftest.extension.md and fail;
+        manifest-based lookup must find the actual file declared in the manifest.
+        """
+        from specify_cli.presets import _substitute_core_template
+        from specify_cli.agents import CommandRegistrar
+
+        ext_dir = project_dir / ".specify" / "extensions" / "selftest"
+        cmd_dir = ext_dir / "commands"
+        cmd_dir.mkdir(parents=True, exist_ok=True)
+
+        # File is named selftest.md, NOT speckit.selftest.extension.md
+        (cmd_dir / "selftest.md").write_text(
+            "---\ndescription: selftest core\n---\n\n# Selftest Core\n"
+        )
+        # Manifest maps the command name to the actual file
+        (ext_dir / "extension.yml").write_text(
+            "schema_version: '1.0'\n"
+            "extension:\n  id: selftest\n  name: Self-Test\n  version: 1.0.0\n"
+            "  description: test\n  author: test\n  repository: https://example.com\n"
+            "  license: MIT\n"
+            "requires:\n  speckit_version: '>=0.2.0'\n"
+            "provides:\n"
+            "  commands:\n"
+            "    - name: speckit.selftest.extension\n"
+            "      file: commands/selftest.md\n"
+            "      description: Selftest command\n"
+        )
+
+        registrar = CommandRegistrar()
+        body = "## Wrapper\n\n{CORE_TEMPLATE}\n"
+        result, _ = _substitute_core_template(body, "speckit.selftest.extension", project_dir, registrar)
+
+        assert "# Selftest Core" in result
+        assert "{CORE_TEMPLATE}" not in result
+
 
 # ===== _replay_wraps_for_command Tests =====