Fix command-token-hyphen-gap: add verbatim token form for hyphenated command names

Apply the remediation from the bug assessment on issue #4198.
Extends resolve_command_refs() with a new verbatim token form
__SPECKIT_COMMAND(speckit.agent-context.update)__ that carries the
command ID verbatim. Dots are replaced by the invoke_separator; hyphens
within segments are preserved (and collapse naturally to the separator
when separator is '-'). The existing uppercase __SPECKIT_COMMAND_NAME__
form is unchanged.

Refs #4198

Assisted-by: GitHub Copilot (model: claude-sonnet-4.6, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: github-actions[bot]

src/specify_cli/integrations/base.py

@@ -620,25 +620,42 @@ def install_scripts(
     def resolve_command_refs(
         content: str, separator: str = ".", prefix: str = "/"
     ) -> str:
-        """Replace ``__SPECKIT_COMMAND_<NAME>__`` placeholders with invocations.
+        """Replace ``__SPECKIT_COMMAND_*__`` placeholders with invocations.
 
-        Each placeholder encodes a command name in upper-case with
+        Two forms are supported:
+
+        **Uppercase form** — encodes a command name in upper-case with
         underscores (e.g. ``__SPECKIT_COMMAND_PLAN__``,
-        ``__SPECKIT_COMMAND_GIT_COMMIT__``).  The replacement uses
+        ``__SPECKIT_COMMAND_GIT_COMMIT__``).  Each underscore is replaced by
         *separator* to join the segments:
 
         * ``separator="."`` → ``/speckit.plan``, ``/speckit.git.commit``
         * ``separator="-"`` → ``/speckit-plan``, ``/speckit-git-commit``
 
+        **Verbatim form** — carries the canonical command ID verbatim inside
+        parentheses (e.g. ``__SPECKIT_COMMAND(speckit.agent-context.update)__``).
+        This form correctly handles command names that contain hyphens, which
+        the uppercase form cannot represent unambiguously.  The canonical dots
+        are replaced by *separator*; hyphens within a segment are kept as-is
+        (they become *separator* when *separator* is ``"-"``):
+
+        * ``separator="."`` → ``/speckit.agent-context.update``
+        * ``separator="-"`` → ``/speckit-agent-context-update``
+
         *prefix* defaults to ``"/"`` but may be ``"$"`` for agents whose
         native skills invocation uses dollar-prefixed chat commands.
         """
+
+        def _replace(m: re.Match) -> str:
+            if m.group(1) is not None:
+                # Uppercase form: replace underscores with separator.
+                return prefix + "speckit" + separator + m.group(1).lower().replace("_", separator)
+            # Verbatim form: replace dots with separator; hyphens are kept.
+            return prefix + m.group(2).replace(".", separator)
+
         return re.sub(
-            r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__",
-            lambda m: prefix
-            + "speckit"
-            + separator
-            + m.group(1).lower().replace("_", separator),
+            r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__|__SPECKIT_COMMAND\(([^)]+)\)__",
+            _replace,
             content,
         )
 

tests/integrations/test_base.py

@@ -410,6 +410,45 @@ def test_placeholder_with_digits(self):
         result = IntegrationBase.resolve_command_refs(text, ".")
         assert result == "/speckit.v2.plan"
 
+    # -- Verbatim form tests --------------------------------------------------
+
+    def test_verbatim_dot_separator_with_hyphen(self):
+        """Verbatim form correctly handles a hyphen in command name with dot separator."""
+        text = "__SPECKIT_COMMAND(speckit.agent-context.update)__"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "/speckit.agent-context.update"
+
+    def test_verbatim_hyphen_separator_with_hyphen(self):
+        """Verbatim form correctly handles a hyphen in command name with hyphen separator."""
+        text = "__SPECKIT_COMMAND(speckit.agent-context.update)__"
+        result = IntegrationBase.resolve_command_refs(text, "-")
+        assert result == "/speckit-agent-context-update"
+
+    def test_verbatim_dollar_prefix(self):
+        text = "__SPECKIT_COMMAND(speckit.agent-context.update)__"
+        result = IntegrationBase.resolve_command_refs(text, "-", "$")
+        assert result == "$speckit-agent-context-update"
+
+    def test_verbatim_simple_command_no_hyphens(self):
+        """Verbatim form works for commands without hyphens too."""
+        text = "__SPECKIT_COMMAND(speckit.git.commit)__"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "/speckit.git.commit"
+
+    def test_verbatim_and_uppercase_mixed(self):
+        """Both forms can coexist in the same string."""
+        text = "__SPECKIT_COMMAND_PLAN__ and __SPECKIT_COMMAND(speckit.agent-context.update)__"
+        result = IntegrationBase.resolve_command_refs(text, ".")
+        assert result == "/speckit.plan and /speckit.agent-context.update"
+
+    def test_uppercase_form_unaffected_by_verbatim_support(self):
+        """Regression: existing uppercase form still works correctly."""
+        text = "__SPECKIT_COMMAND_AGENT_CONTEXT_UPDATE__"
+        result_dot = IntegrationBase.resolve_command_refs(text, ".")
+        result_hyphen = IntegrationBase.resolve_command_refs(text, "-")
+        assert result_dot == "/speckit.agent.context.update"
+        assert result_hyphen == "/speckit-agent-context-update"
+
 
 class TestResolvePythonInterpreter:
     def test_returns_python_on_path(self, monkeypatch):