fix(integration): preserve customizations and add regression tests (#2293)

Address Copilot review on #2375:

1. Replace unconditional force=True with hash-aware refresh_managed mode
   in _install_shared_infra. Files whose on-disk hash matches the
   previously recorded manifest hash are refreshed; files whose hash
   has diverged are treated as user customizations and preserved with
   a clear warning. The user can opt back into a full overwrite by
   passing --force to switch.

2. Update --force help text on integration switch so the documented
   semantics include 'overwrite customized shared infrastructure files',
   not just uninstall behavior.

3. Add two CLI-level regression tests:
   - test_switch_refreshes_stale_managed_shared_infra reproduces #2293
     by hashing a stale vendored common.sh into the manifest, then
     asserting it is replaced after switch.
   - test_switch_preserves_user_customized_shared_infra modifies the
     file without updating the manifest hash and asserts the
     customization survives the switch and the warning is emitted.

Author: Quratulain-bilal

src/specify_cli/__init__.py

@@ -724,6 +724,7 @@ def _install_shared_infra(
     tracker: StepTracker | None = None,
     force: bool = False,
     invoke_separator: str = ".",
+    refresh_managed: bool = False,
 ) -> bool:
     """Install shared infrastructure files into *project_path*.
 
@@ -735,9 +736,14 @@ def _install_shared_infra(
     placeholders using *invoke_separator* (``"."`` for markdown agents,
     ``"-"`` for skills agents).
 
-    When *force* is ``True``, existing files are overwritten with the
-    latest bundled versions.  When ``False`` (default), only missing
-    files are added and existing ones are skipped.
+    Overwrite policy:
+
+    * ``force=True``  — overwrite every existing file.
+    * ``refresh_managed=True`` — overwrite only files whose on-disk hash
+      still matches the previously recorded manifest hash (i.e. unmodified
+      files installed by spec-kit). Files with diverging hashes are
+      treated as user customizations and preserved with a warning.
+    * Default — only add missing files; existing ones are skipped.
 
     Returns ``True`` on success.
     """
@@ -747,6 +753,30 @@ def _install_shared_infra(
     core = _locate_core_pack()
     manifest = IntegrationManifest("speckit", project_path, version=get_speckit_version())
 
+    # When refresh_managed is requested, load prior hashes so we only
+    # overwrite files that are still unmodified relative to the previous
+    # install.
+    prior_hashes: dict[str, str] = {}
+    if refresh_managed and not force:
+        try:
+            prior = IntegrationManifest.load("speckit", project_path)
+            prior_hashes = prior.files
+        except (FileNotFoundError, ValueError):
+            prior_hashes = {}
+
+    def _is_managed(rel_posix: str, abs_path: Path) -> bool:
+        """True when the file's current hash matches the recorded one."""
+        expected = prior_hashes.get(rel_posix)
+        if not expected:
+            return False
+        try:
+            from .integrations.manifest import _sha256
+            return _sha256(abs_path) == expected
+        except OSError:
+            return False
+
+    preserved_user_files: list[str] = []
+
     # Scripts
     if core and (core / "scripts").is_dir():
         scripts_src = core / "scripts"
@@ -768,13 +798,21 @@ def _install_shared_infra(
                 if src_path.is_file():
                     rel_path = src_path.relative_to(variant_src)
                     dst_path = dest_variant / rel_path
-                    if dst_path.exists() and not force:
-                        skipped_files.append(str(dst_path.relative_to(project_path)))
+                    rel_posix = dst_path.relative_to(project_path).as_posix()
+                    should_write = (
+                        not dst_path.exists()
+                        or force
+                        or (refresh_managed and _is_managed(rel_posix, dst_path))
+                    )
+                    if not should_write:
+                        if refresh_managed and dst_path.exists() and rel_posix in prior_hashes:
+                            preserved_user_files.append(rel_posix)
+                        else:
+                            skipped_files.append(str(dst_path.relative_to(project_path)))
                     else:
                         dst_path.parent.mkdir(parents=True, exist_ok=True)
                         shutil.copy2(src_path, dst_path)
-                        rel = dst_path.relative_to(project_path).as_posix()
-                        manifest.record_existing(rel)
+                        manifest.record_existing(rel_posix)
 
     # Page templates (not command templates, not vscode-settings.json)
     if core and (core / "templates").is_dir():
@@ -789,16 +827,24 @@ def _install_shared_infra(
         for f in templates_src.iterdir():
             if f.is_file() and f.name != "vscode-settings.json" and not f.name.startswith("."):
                 dst = dest_templates / f.name
-                if dst.exists() and not force:
-                    skipped_files.append(str(dst.relative_to(project_path)))
+                rel_posix = dst.relative_to(project_path).as_posix()
+                should_write = (
+                    not dst.exists()
+                    or force
+                    or (refresh_managed and _is_managed(rel_posix, dst))
+                )
+                if not should_write:
+                    if refresh_managed and dst.exists() and rel_posix in prior_hashes:
+                        preserved_user_files.append(rel_posix)
+                    else:
+                        skipped_files.append(str(dst.relative_to(project_path)))
                 else:
                     content = f.read_text(encoding="utf-8")
                     content = IntegrationBase.resolve_command_refs(
                         content, invoke_separator
                     )
                     dst.write_text(content, encoding="utf-8")
-                    rel = dst.relative_to(project_path).as_posix()
-                    manifest.record_existing(rel)
+                    manifest.record_existing(rel_posix)
 
     if skipped_files:
         console.print(
@@ -812,6 +858,17 @@ def _install_shared_infra(
             "[cyan]specify integration upgrade --force[/cyan]."
         )
 
+    if preserved_user_files:
+        console.print(
+            f"[yellow]⚠[/yellow]  Preserved {len(preserved_user_files)} customized shared "
+            "infrastructure file(s) (hash differs from previous install):"
+        )
+        for f in preserved_user_files:
+            console.print(f"    {f}")
+        console.print(
+            "To overwrite customizations, re-run with [cyan]--force[/cyan]."
+        )
+
     manifest.save()
     return True
 
@@ -2291,7 +2348,7 @@ def integration_uninstall(
 def integration_switch(
     target: str = typer.Argument(help="Integration key to switch to"),
     script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
-    force: bool = typer.Option(False, "--force", help="Force removal of modified files during uninstall"),
+    force: bool = typer.Option(False, "--force", help="Force removal of modified files during uninstall and overwrite customized shared infrastructure files"),
     integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the target integration'),
 ):
     """Switch from the current integration to a different one."""
@@ -2384,10 +2441,19 @@ def integration_switch(
     # Refresh shared infrastructure to the current CLI version. Switching
     # integrations is exactly when stale vendored shared scripts (e.g.
     # update-agent-context.sh that pre-dates the target integration's
-    # supported-agent list) would silently break the new integration, so
-    # always overwrite with the bundled copies. User content lives under
-    # specs/ and is not touched here. See #2293.
-    _install_shared_infra(project_root, selected_script, force=True, invoke_separator=target_integration.effective_invoke_separator(parsed_options))
+    # supported-agent list) would silently break the new integration.
+    #
+    # Use refresh_managed=True so only files that match their previously
+    # recorded hash are overwritten — user customizations are detected via
+    # hash divergence and preserved with a warning. Pass --force to
+    # overwrite customizations as well. See #2293.
+    _install_shared_infra(
+        project_root,
+        selected_script,
+        force=force,
+        refresh_managed=True,
+        invoke_separator=target_integration.effective_invoke_separator(parsed_options),
+    )
     if os.name != "nt":
         ensure_executable_scripts(project_root)
 

tests/integrations/test_integration_subcommand.py

@@ -356,6 +356,66 @@ def test_switch_preserves_shared_infra(self, tmp_path):
         assert shared_script.exists()
         assert shared_script.read_text(encoding="utf-8") == shared_content
 
+    def test_switch_refreshes_stale_managed_shared_infra(self, tmp_path):
+        """Regression for #2293: stale managed shared scripts get refreshed on switch."""
+        import hashlib
+
+        project = _init_project(tmp_path, "claude")
+        shared_script = project / ".specify" / "scripts" / "bash" / "common.sh"
+        bundled_bytes = shared_script.read_bytes()
+
+        # Simulate a stale vendored script: write truncated content as bytes
+        # (write_text would translate \n→\r\n on Windows and break the hash)
+        # and update the speckit manifest hash so the stale copy is treated
+        # as "managed" (installed by spec-kit, not a user customization).
+        stale_bytes = b"#!/usr/bin/env bash\n# stale vendored copy\n"
+        shared_script.write_bytes(stale_bytes)
+
+        manifest_path = project / ".specify" / "integrations" / "speckit.manifest.json"
+        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        manifest_data["files"][".specify/scripts/bash/common.sh"] = (
+            hashlib.sha256(stale_bytes).hexdigest()
+        )
+        manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = runner.invoke(app, [
+                "integration", "switch", "copilot",
+                "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+
+        # Stale managed file should be replaced by the bundled version
+        assert shared_script.read_bytes() == bundled_bytes
+
+    def test_switch_preserves_user_customized_shared_infra(self, tmp_path):
+        """User customizations (hash divergence from manifest) survive switch without --force."""
+        project = _init_project(tmp_path, "claude")
+        shared_script = project / ".specify" / "scripts" / "bash" / "common.sh"
+
+        # User customization: append bytes but do NOT update manifest hash,
+        # so on-disk hash diverges from the recorded one.
+        original = shared_script.read_bytes()
+        custom_bytes = original + b"\n# user customization\n"
+        shared_script.write_bytes(custom_bytes)
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = runner.invoke(app, [
+                "integration", "switch", "copilot",
+                "--script", "sh",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        assert shared_script.read_bytes() == custom_bytes
+        assert "Preserved" in result.output
+
     def test_switch_from_nothing(self, tmp_path):
         """Switch when no integration is installed should just install the target."""
         project = tmp_path / "bare"