fix(bob): resolve command-ref separator with project-aware mode before shared-infra refresh (review #3415)

The `use`/`switch` paths refresh shared infrastructure via
`_with_integration_setting()` / `_invoke_separator_for_integration()`,
which previously resolved the invoke separator through
`effective_invoke_separator` / `is_skills_mode` WITHOUT a project_root.
For a pre-PR Bob 1.x project (.bob/commands/ on disk, no stored options),
this defaulted to the skills "-" separator and rewrote rendered
shared-template command refs to /speckit-*, even though ai_skills stayed
false. Thread project_root through effective_invoke_separator, the two
runtime helpers, and every call site so Bob's on-disk legacy detection
governs the separator before shared infra is refreshed.

Add a rendered-shared-template regression test covering `use --force`.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 63f93544-a77f-4f01-bf04-c88806a97dbf

Author: mnriem

src/specify_cli/commands/init.py

@@ -458,6 +458,7 @@ def init(
                     script_type=selected_script,
                     raw_options=integration_options,
                     parsed_options=integration_parsed_options or None,
+                    project_root=project_path,
                 )
                 _write_integration_json(
                     project_path,
@@ -478,7 +479,7 @@ def init(
                     tracker=tracker,
                     force=force,
                     invoke_separator=resolved_integration.effective_invoke_separator(
-                        integration_parsed_options
+                        integration_parsed_options, project_root=project_path
                     ),
                 )
                 tracker.complete(

src/specify_cli/integration_runtime.py

@@ -46,6 +46,7 @@ def with_integration_setting(
     script_type: str | None = None,
     raw_options: str | None = None,
     parsed_options: dict[str, Any] | None = None,
+    project_root: Any = None,
 ) -> dict[str, dict[str, Any]]:
     """Return integration settings with *key* updated."""
     settings = integration_settings(state)
@@ -63,7 +64,9 @@ def with_integration_setting(
     elif raw_options is not None:
         current.pop("parsed_options", None)
 
-    current["invoke_separator"] = integration.effective_invoke_separator(parsed_options)
+    current["invoke_separator"] = integration.effective_invoke_separator(
+        parsed_options, project_root
+    )
     settings[key] = current
     return settings
 
@@ -73,10 +76,11 @@ def invoke_separator_for_integration(
     state: dict[str, Any],
     key: str,
     parsed_options: dict[str, Any] | None = None,
+    project_root: Any = None,
 ) -> str:
     """Resolve the invocation separator for stored/default integration state."""
     if parsed_options is not None:
-        return integration.effective_invoke_separator(parsed_options)
+        return integration.effective_invoke_separator(parsed_options, project_root)
 
     setting = integration_setting(state, key)
     stored_separator = setting.get("invoke_separator")
@@ -85,6 +89,6 @@ def invoke_separator_for_integration(
 
     stored_parsed = setting.get("parsed_options")
     if isinstance(stored_parsed, dict):
-        return integration.effective_invoke_separator(stored_parsed)
+        return integration.effective_invoke_separator(stored_parsed, project_root)
 
-    return integration.effective_invoke_separator(None)
+    return integration.effective_invoke_separator(None, project_root)

src/specify_cli/integrations/_helpers.py

@@ -320,6 +320,7 @@ def _set_default_integration(
         script_type=resolved_script,
         raw_options=raw_options,
         parsed_options=parsed_options,
+        project_root=project_root,
     )
 
     if refresh_templates:
@@ -328,7 +329,8 @@ def _set_default_integration(
                 project_root,
                 resolved_script,
                 invoke_separator=_invoke_separator_for_integration(
-                    integration, {"integration_settings": settings}, key, parsed_options
+                    integration, {"integration_settings": settings}, key, parsed_options,
+                    project_root=project_root,
                 ),
                 force=refresh_templates_force,
                 refresh_managed=True,

src/specify_cli/integrations/_install_commands.py

@@ -127,7 +127,8 @@ def integration_install(
         project_root,
         selected_script,
         invoke_separator=_invoke_separator_for_integration(
-            infra_integration, current, infra_key, infra_parsed
+            infra_integration, current, infra_key, infra_parsed,
+            project_root=project_root,
         ),
     )
     if os.name != "nt":
@@ -155,6 +156,7 @@ def integration_install(
             script_type=selected_script,
             raw_options=raw_options,
             parsed_options=parsed_options,
+            project_root=project_root,
         )
         _write_integration_json(project_root, new_default, new_installed, settings)
         if new_default == integration.key:

src/specify_cli/integrations/_migrate_commands.py

@@ -236,7 +236,8 @@ def integration_switch(
         force=refresh_shared_infra,
         refresh_managed=True,
         invoke_separator=_invoke_separator_for_integration(
-            target_integration, current, target, parsed_options
+            target_integration, current, target, parsed_options,
+            project_root=project_root,
         ),
         refresh_hint=(
             "To overwrite customizations, re-run with "
@@ -415,7 +416,8 @@ def integration_upgrade(
         selected_script,
         force=force,
         invoke_separator=_invoke_separator_for_integration(
-            infra_integration, current, infra_key, infra_parsed
+            infra_integration, current, infra_key, infra_parsed,
+            project_root=project_root,
         ),
     )
     if os.name != "nt":
@@ -441,14 +443,16 @@ def integration_upgrade(
             script_type=selected_script,
             raw_options=raw_options,
             parsed_options=parsed_options,
+            project_root=project_root,
         )
         if installed_key == key:
             try:
                 _install_shared_infra(
                     project_root,
                     selected_script,
                     invoke_separator=_invoke_separator_for_integration(
-                        integration, {"integration_settings": settings}, key, parsed_options
+                        integration, {"integration_settings": settings}, key, parsed_options,
+                        project_root=project_root,
                     ),
                     force=force,
                     refresh_managed=True,

src/specify_cli/integrations/base.py

@@ -160,14 +160,16 @@ def options(cls) -> list[IntegrationOption]:
         return []
 
     def effective_invoke_separator(
-        self, parsed_options: dict[str, Any] | None = None
+        self,
+        parsed_options: dict[str, Any] | None = None,
+        project_root: Path | None = None,
     ) -> str:
         """Return the invoke separator for the given options.
 
         Subclasses whose separator depends on runtime options (e.g.
         Copilot in ``--skills`` mode) should override this method.
-        The default implementation ignores *parsed_options* and returns
-        the class-level ``invoke_separator``.
+        The default implementation ignores *parsed_options* and
+        *project_root* and returns the class-level ``invoke_separator``.
         """
         return self.invoke_separator
 

src/specify_cli/integrations/bob/__init__.py

@@ -171,10 +171,19 @@ def is_skills_mode(
         return True
 
     def effective_invoke_separator(
-        self, parsed_options: dict[str, Any] | None = None
+        self,
+        parsed_options: dict[str, Any] | None = None,
+        project_root: Path | None = None,
     ) -> str:
-        """``"."`` for the legacy commands layout, ``"-"`` for skills."""
-        return "-" if self.is_skills_mode(parsed_options) else "."
+        """``"."`` for the legacy commands layout, ``"-"`` for skills.
+
+        *project_root* lets the ``use`` / ``switch`` / ``upgrade`` path — which
+        refreshes shared infrastructure *before* persisting init-options —
+        detect an already-installed legacy layout, so core command references
+        are rendered with the correct separator instead of defaulting to the
+        skills ``-``.
+        """
+        return "-" if self.is_skills_mode(parsed_options, project_root) else "."
 
     def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
         """Resolve the command-ref separator from a project's persisted mode.

src/specify_cli/integrations/copilot/__init__.py

@@ -122,7 +122,9 @@ class CopilotIntegration(IntegrationBase):
     _skills_mode: bool = False
 
     def effective_invoke_separator(
-        self, parsed_options: dict[str, Any] | None = None
+        self,
+        parsed_options: dict[str, Any] | None = None,
+        project_root: Path | None = None,
     ) -> str:
         """Return ``"-"`` when skills mode is requested, ``"."`` otherwise."""
         if parsed_options and parsed_options.get("skills"):

tests/integrations/test_integration_bob.py

@@ -545,3 +545,80 @@ def test_update_init_options_keeps_skills_project_as_skills(self, tmp_path):
 
         opts = load_init_options(tmp_path)
         assert opts.get("ai_skills") is True
+
+    def test_with_integration_setting_stores_dot_separator_for_legacy(self, tmp_path):
+        """Regression (review #3415): shared-infra refresh on the use/switch
+        path resolves the command-ref separator *before* init-options are
+        rewritten, via ``effective_invoke_separator``.  For an existing
+        ``.bob/commands`` project with no stored options this must resolve to
+        ``"."`` (project-aware), not the skills-layout ``"-"``; otherwise core
+        command references get rewritten to ``/speckit-*``.
+        """
+        from specify_cli.integration_runtime import with_integration_setting
+
+        (tmp_path / ".bob" / "commands").mkdir(parents=True)
+        bob = get_integration("bob")
+
+        # Simulate the use/switch path: no parsed options stored.
+        settings = with_integration_setting(
+            {}, "bob", bob, parsed_options=None, project_root=tmp_path
+        )
+        assert settings["bob"]["invoke_separator"] == ".", (
+            "legacy .bob/commands project must persist the dot separator so "
+            "shared templates render Bob 1.x /speckit.<cmd> references"
+        )
+
+    def test_use_force_keeps_legacy_command_refs_in_shared_templates(self, tmp_path):
+        """End-to-end (review #3415): ``integration use bob --force`` on an
+        existing Bob 1.x project (legacy layout on disk, stored options
+        stripped as a pre-PR install would be) must re-render shared templates
+        with ``/speckit.<cmd>`` (dot), not ``/speckit-<cmd>``.
+        """
+        import json
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        # Create a real legacy Bob project (renders shared templates).
+        target = tmp_path / "proj"
+        runner = CliRunner()
+        result = runner.invoke(app, [
+            "init", str(target), "--integration", "bob",
+            "--integration-options", "--legacy-commands",
+            "--ignore-agent-tools", "--script", "sh",
+        ])
+        assert result.exit_code == 0, f"init failed: {result.output}"
+
+        template = target / ".specify" / "templates" / "plan-template.md"
+        assert template.is_file(), "expected a rendered shared plan template"
+        assert "/speckit.plan" in template.read_text(encoding="utf-8")
+
+        # Simulate a pre-PR Bob 1.x install: no stored options/separator.
+        integ_json = target / ".specify" / "integration.json"
+        data = json.loads(integ_json.read_text(encoding="utf-8"))
+        bob_settings = data["integration_settings"]["bob"]
+        for stale in ("raw_options", "parsed_options", "invoke_separator"):
+            bob_settings.pop(stale, None)
+        integ_json.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+        # Re-activate with --force so shared templates are re-rendered.
+        import os
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(target)
+            result = runner.invoke(
+                app, ["integration", "use", "bob", "--force"]
+            )
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"use failed: {result.output}"
+
+        rendered = template.read_text(encoding="utf-8")
+        assert "/speckit.plan" in rendered, (
+            "legacy Bob project must keep /speckit.plan (dot) after refresh"
+        )
+        assert "/speckit-plan" not in rendered, (
+            "shared templates must not be rewritten to the skills /speckit-plan"
+        )
+        # And the persisted separator must reflect the legacy layout.
+        data = json.loads(integ_json.read_text(encoding="utf-8"))
+        assert data["integration_settings"]["bob"].get("invoke_separator") == "."