Skip to content

💫 Toolkit to help you get started with SDD or any other process!

81.6 KB
Raw Blame
"""Tests for mirrored integration CLI behavior in test_command_upgrade.py."""

from __future__ import annotations

import hashlib
import json  # noqa: F401
import os  # noqa: F401
import shutil  # noqa: F401
from pathlib import Path  # noqa: F401

import pytest  # noqa: F401

from specify_cli import app  # noqa: F401
from tests.conftest import strip_ansi  # noqa: F401
from tests.specify_cli.integrations._catalog_helpers import (
    IntegrationCatalogCliTestBase,
    _normalize_cli_output,
)
from tests.specify_cli.integrations._helpers import (
    _copy_project_template,  # noqa: F401
    _init_project,  # noqa: F401
    _integration_list_row_cells,  # noqa: F401
    _move_kilocode_install_to_legacy_layout,  # noqa: F401
    _run_in_project,  # noqa: F401
    _write_invalid_manifest,  # noqa: F401
    runner,  # noqa: F401
)

class TestIntegrationUpgradeDetailed:
    @pytest.mark.parametrize(
        "bad_handler",
        [
            {"command": "speckit.bad.check", "matcher": ["Bash"]},
            {"command": "speckit.bad.check", "timeout": "30"},
        ],
        ids=["matcher-list", "timeout-string"],
    )
    def test_upgrade_skips_invalid_unregistered_extension_events(self, tmp_path, caplog, bad_handler):
        project = _init_project(tmp_path, "claude")
        for ext_id, handler in (
            ("bad", bad_handler),
            ("good", {"command": "speckit.good.check", "matcher": "Bash"}),
        ):
            ext_dir = project / ".specify" / "extensions" / ext_id
            ext_dir.mkdir(parents=True)
            (ext_dir / "extension.yml").write_text(
                json.dumps({"events": {"pre_tool_use": handler}}), encoding="utf-8"
            )

        result = _run_in_project(project, ["integration", "upgrade", "claude", "--force"])

        assert result.exit_code == 0, result.output
        config = json.loads((project / ".claude" / "settings.json").read_text(encoding="utf-8"))
        hooks = config["hooks"]["PreToolUse"]
        commands = [item["command"] for group in hooks for item in group["hooks"]]
        assert any("speckit.good.check" in command for command in commands)
        assert all("speckit.bad.check" not in command for command in commands)
        assert "bad" in caplog.text and "pre_tool_use" in caplog.text

    @pytest.mark.parametrize("integration", ["claude", "copilot", "gemini"])
    @pytest.mark.parametrize("force", [False, True])
    def test_disabling_events_honors_modified_dispatcher_force(self, tmp_path, integration, force):
        from specify_cli.events import install_integration_events
        from specify_cli.integrations import get_integration
        from specify_cli.integrations.manifest import IntegrationManifest

        project = _init_project(tmp_path, integration)
        manifest = IntegrationManifest.load(integration, project)
        install_integration_events(
            get_integration(integration), project, manifest,
            {"pre_tool_use": [{"command": "speckit.x"}]},
        )
        manifest.save()
        dispatcher = project / ".specify/events.py"
        content = b"# User-modified dispatcher\n"
        dispatcher.write_bytes(content)
        args = [
            "integration", "upgrade", integration,
            "--integration-options", "--events false",
        ]
        if force:
            args.append("--force")

        result = _run_in_project(project, args)

        assert result.exit_code == (0 if force else 1), result.output
        if force:
            assert not dispatcher.exists()
            updated = IntegrationManifest.load(integration, project)
            assert ".specify/events.py" not in updated.files
        else:
            assert dispatcher.read_bytes() == content
            assert "modified" in result.output

    def test_upgrade_invalid_manifest_reports_cli_error(self, tmp_path):
        project = _init_project(tmp_path, "claude")
        _write_invalid_manifest(project, "claude")

        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade", "claude"])
        finally:
            os.chdir(old_cwd)
        assert result.exit_code != 0
        assert "manifest" in result.output
        assert "unreadable" in result.output

    def test_upgrade_refreshes_init_options_speckit_version(self, tmp_path, monkeypatch):
        project = _init_project(tmp_path, "claude")
        init_options = project / ".specify" / "init-options.json"
        opts = json.loads(init_options.read_text(encoding="utf-8"))
        opts["speckit_version"] = "0.6.1"
        init_options.write_text(json.dumps(opts), encoding="utf-8")

        import specify_cli.integrations._commands as _int_cmds

        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--force",
        ])

        assert result.exit_code == 0, result.output
        updated = json.loads(init_options.read_text(encoding="utf-8"))
        assert updated["speckit_version"] == "0.8.11"

    def test_upgrade_non_default_refreshes_init_options_version_only(self, tmp_path, monkeypatch):
        project = _init_project(tmp_path, "gemini")
        install = _run_in_project(project, [
            "integration", "install", "claude",
            "--script", "sh",
        ])
        assert install.exit_code == 0, install.output

        init_options = project / ".specify" / "init-options.json"
        opts = json.loads(init_options.read_text(encoding="utf-8"))
        opts["speckit_version"] = "0.6.1"
        init_options.write_text(json.dumps(opts), encoding="utf-8")

        import specify_cli.integrations._commands as _int_cmds

        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--script", "sh",
            "--force",
        ])

        assert result.exit_code == 0, result.output
        updated = json.loads(init_options.read_text(encoding="utf-8"))
        assert updated["speckit_version"] == "0.8.11"
        assert updated["integration"] == "gemini"
        assert updated["ai"] == "gemini"
        assert "context_file" not in updated

    def test_upgrade_does_not_persist_state_when_shared_infra_refresh_fails(self, tmp_path, monkeypatch):
        project = _init_project(tmp_path, "claude")
        int_json = project / ".specify" / "integration.json"
        init_options = project / ".specify" / "init-options.json"
        manifest_path = project / ".specify" / "integrations" / "claude.manifest.json"

        before_state = json.loads(int_json.read_text(encoding="utf-8"))
        before_options = json.loads(init_options.read_text(encoding="utf-8"))
        before_manifest = manifest_path.read_text(encoding="utf-8")

        import specify_cli

        real_install_shared_infra = specify_cli._install_shared_infra
        calls = {"count": 0}

        def fail_refresh(*args, **kwargs):
            calls["count"] += 1
            if calls["count"] == 2:
                raise ValueError("refuse refresh")
            return real_install_shared_infra(*args, **kwargs)

        monkeypatch.setattr(specify_cli, "_install_shared_infra", fail_refresh)

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--force",
        ])

        assert result.exit_code != 0
        assert "Failed to refresh shared infrastructure" in result.output
        assert json.loads(int_json.read_text(encoding="utf-8")) == before_state
        assert json.loads(init_options.read_text(encoding="utf-8")) == before_options
        assert manifest_path.read_text(encoding="utf-8") == before_manifest

    def test_upgrade_default_refreshes_shared_script_refs_for_option_separator_change(self, tmp_path):
        project = _init_project(
            tmp_path, "copilot", integration_options="--commands"
        )
        template = project / ".specify" / "templates" / "plan-template.md"
        managed_script = project / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
        customized_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh"

        assert "/speckit.plan" in template.read_text(encoding="utf-8")
        assert "/speckit.specify" in managed_script.read_text(encoding="utf-8")
        customized_before = customized_script.read_text(encoding="utf-8") + "\n# user customization\n"
        customized_script.write_text(customized_before, encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "copilot",
            "--integration-options", "--skills",
        ])

        assert result.exit_code == 0, result.output
        assert "/speckit-plan" in template.read_text(encoding="utf-8")
        managed_content = managed_script.read_text(encoding="utf-8")
        assert "/speckit-specify" in managed_content
        assert "/speckit.specify" not in managed_content
        assert customized_script.read_text(encoding="utf-8") == customized_before

    def test_upgrade_preserves_historical_copilot_commands_without_options(
        self, tmp_path
    ):
        """A command manifest restores missing files instead of migrating."""
        project = _init_project(
            tmp_path, "copilot", integration_options="--commands"
        )
        state_path = project / ".specify" / "integration.json"
        state = json.loads(state_path.read_text(encoding="utf-8"))
        copilot_settings = state["integration_settings"]["copilot"]
        copilot_settings.pop("raw_options", None)
        copilot_settings.pop("parsed_options", None)
        state_path.write_text(json.dumps(state), encoding="utf-8")

        for path in (project / ".github" / "agents").glob(
            "speckit.*.agent.md"
        ):
            path.unlink()
        for path in (project / ".github" / "prompts").glob(
            "speckit.*.prompt.md"
        ):
            path.unlink()

        result = _run_in_project(
            project,
            ["integration", "upgrade", "copilot", "--script", "sh", "--force"],
        )

        assert result.exit_code == 0, result.output
        assert (
            project / ".github" / "agents" / "speckit.plan.agent.md"
        ).exists()
        assert not (project / ".github" / "skills").exists()
        init_options = json.loads(
            (project / ".specify" / "init-options.json").read_text(
                encoding="utf-8"
            )
        )
        assert init_options.get("ai_skills") is not True

    def test_upgrade_non_default_keeps_default_template_invocations(self, tmp_path):
        project = _init_project(tmp_path, "gemini")
        template = project / ".specify" / "templates" / "plan-template.md"
        script = project / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
        assert "/speckit.plan" in template.read_text(encoding="utf-8")
        assert "/speckit.plan" in script.read_text(encoding="utf-8")

        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            install = runner.invoke(app, [
                "integration", "install", "claude",
                "--script", "sh",
            ], catch_exceptions=False)
            assert install.exit_code == 0, install.output

            result = runner.invoke(app, [
                "integration", "upgrade", "claude",
                "--script", "sh",
                "--force",
            ], catch_exceptions=False)
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0, result.output

        data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
        assert data["integration"] == "gemini"
        assert "/speckit.plan" in template.read_text(encoding="utf-8")
        assert "/speckit.plan" in script.read_text(encoding="utf-8")
        assert "/speckit-plan" not in script.read_text(encoding="utf-8")

    def test_upgrade_migrates_opencode_legacy_dir(self, tmp_path):
        """Upgrade moves OpenCode commands from .opencode/command/ to .opencode/commands/."""
        project = _init_project(tmp_path, "opencode")

        # Simulate a legacy project: rename commands/ back to command/
        canonical = project / ".opencode" / "commands"
        legacy = project / ".opencode" / "command"
        assert canonical.is_dir(), "init should have created .opencode/commands/"
        canonical.rename(legacy)
        assert legacy.is_dir()
        assert not canonical.exists()

        # Patch the manifest to reflect old paths (command/ not commands/)
        manifest_path = project / ".specify" / "integrations" / "opencode.manifest.json"
        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
        patched_files = {}
        for path, info in manifest_data.get("files", {}).items():
            patched_files[path.replace(".opencode/commands/", ".opencode/command/")] = info
        manifest_data["files"] = patched_files
        manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")

        old_commands = sorted(legacy.glob("speckit.*.md"))
        assert len(old_commands) > 0, "Legacy dir should have speckit command files"

        result = _run_in_project(project, [
            "integration", "upgrade", "opencode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, f"upgrade failed: {result.output}"

        # New commands in canonical dir
        assert canonical.is_dir(), ".opencode/commands/ should exist after upgrade"
        new_commands = sorted(canonical.glob("speckit.*.md"))
        assert len(new_commands) > 0, "Commands should exist in .opencode/commands/"

        # Stale files removed from legacy dir (extension-installed commands
        # like agent-context.update may still appear — only check the original
        # core command stems that should have been migrated).
        core_remaining = [
            f for f in legacy.glob("speckit.*.md")
            if "agent-context" not in f.name
        ]
        assert len(core_remaining) == 0, (
            f"Legacy .opencode/command/ should have no core speckit files after upgrade, "
            f"found: {[f.name for f in core_remaining]}"
        )

    def test_upgrade_migrates_kilocode_legacy_dir(self, tmp_path):
        """Upgrade moves Kilo commands from .kilocode/workflows/ to .kilo/commands/."""
        project = _init_project(tmp_path, "kilocode")
        canonical, legacy = _move_kilocode_install_to_legacy_layout(project)

        old_commands = sorted(legacy.glob("speckit.*.md"))
        assert old_commands, "Legacy dir should have speckit command files"

        result = _run_in_project(project, [
            "integration", "upgrade", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, f"upgrade failed: {result.output}"

        assert canonical.is_dir(), ".kilo/commands/ should exist after upgrade"
        new_commands = sorted(canonical.glob("speckit.*.md"))
        assert new_commands, "Commands should exist in .kilo/commands/"

        core_remaining = [
            f for f in legacy.glob("speckit.*.md")
            if "agent-context" not in f.name
        ]
        assert core_remaining == [], (
            "Legacy .kilocode/workflows/ should have no core speckit files "
            f"after upgrade, found: {[f.name for f in core_remaining]}"
        )

    def test_upgrade_migrates_qodercli_extension_commands_to_skills(self, tmp_path):
        """Qoder upgrade retires old extension commands after skills exist."""
        project = _init_project(tmp_path, "qodercli")
        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        skills = project / ".qoder" / "skills"
        commands = project / ".qoder" / "commands"
        commands.mkdir(parents=True)

        manifest_path = (
            project / ".specify" / "integrations" / "qodercli.manifest.json"
        )
        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
        legacy_manifest_files = {}
        for path, info in manifest_data["files"].items():
            skill_path = project / path
            command_name = skill_path.parent.name.replace("speckit-", "speckit.", 1)
            legacy_path = commands / f"{command_name}.md"
            legacy_path.write_bytes(skill_path.read_bytes())
            legacy_manifest_files[
                legacy_path.relative_to(project).as_posix()
            ] = info
        manifest_data["files"] = legacy_manifest_files
        manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")

        registry_path = project / ".specify" / "extensions" / ".registry"
        registry = json.loads(registry_path.read_text(encoding="utf-8"))
        git_metadata = registry["extensions"]["git"]
        registered_commands = git_metadata["registered_commands"]["qodercli"]
        for command_name in registered_commands:
            skill_name = command_name.replace("speckit.", "speckit-", 1).replace(
                ".", "-"
            )
            old_command = commands / f"{command_name}.md"
            old_command.write_bytes(
                (skills / skill_name / "SKILL.md").read_bytes()
            )
        missing_replacement = commands / "speckit.git.missing.md"
        missing_replacement.write_text("# preserve until replaced\n", encoding="utf-8")
        registered_commands.append("speckit.git.missing")
        git_metadata["registered_skills"] = []
        registry_path.write_text(json.dumps(registry), encoding="utf-8")

        shutil.rmtree(skills)
        result = _run_in_project(project, [
            "integration", "upgrade", "qodercli", "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, f"upgrade failed: {result.output}"

        for command_name in registered_commands[:-1]:
            skill_name = command_name.replace("speckit.", "speckit-", 1).replace(
                ".", "-"
            )
            assert (skills / skill_name / "SKILL.md").is_file()
            assert not (commands / f"{command_name}.md").exists()
        assert missing_replacement.is_file(), (
            "a legacy command must remain when no replacement skill was written"
        )

    def test_upgrade_kilocode_legacy_dir_rejects_installed_preset_overrides(
        self, tmp_path
    ):
        """Kilo legacy command-root migration must fail closed with presets."""
        project = _init_project(tmp_path, "kilocode")
        canonical, legacy = _move_kilocode_install_to_legacy_layout(project)

        preset_file = legacy / "speckit.plan.md"
        preset_file.write_text("# preset plan override\n", encoding="utf-8")

        presets_dir = project / ".specify" / "presets"
        presets_dir.mkdir(parents=True, exist_ok=True)
        (presets_dir / ".registry").write_text(
            json.dumps({
                "presets": {
                    "my-preset": {
                        "version": "1.0.0",
                        "enabled": True,
                        "registered_commands": {"kilocode": ["speckit.plan"]},
                        "registered_skills": [],
                    }
                }
            }),
            encoding="utf-8",
        )

        result = _run_in_project(project, [
            "integration", "upgrade", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code != 0, (
            "Kilo legacy command-root migration with presets must be rejected"
        )
        assert "preset" in result.output.lower()
        assert "my-preset" in result.output
        assert ".kilocode/workflows" in strip_ansi(result.output)
        assert ".kilo/commands" in strip_ansi(result.output)
        assert not canonical.exists(), (
            "canonical Kilo commands must not be scaffolded after rejection"
        )
        assert preset_file.read_text(encoding="utf-8") == "# preset plan override\n"

    def test_upgrade_reconciles_kilocode_legacy_extension_artifacts(self, tmp_path):
        """Kilo upgrade moves enabled extension commands to the canonical dir."""
        project = _init_project(tmp_path, "kilocode")
        canonical, legacy = _move_kilocode_install_to_legacy_layout(project)

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"
        assert sorted(legacy.glob("speckit.git.*.md")), (
            "legacy Kilo should render the git extension under .kilocode/workflows"
        )
        assert not canonical.exists()

        result = _run_in_project(project, [
            "integration", "upgrade", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, f"upgrade failed: {result.output}"

        assert sorted(canonical.glob("speckit.git.*.md")), (
            "enabled git extension commands should be recreated in .kilo/commands"
        )
        assert not sorted(legacy.glob("speckit.git.*.md")), (
            "legacy git extension commands should be removed after Kilo upgrade"
        )

        registry_path = project / ".specify" / "extensions" / ".registry"
        registered = json.loads(registry_path.read_text(encoding="utf-8"))[
            "extensions"
        ]["git"]["registered_commands"]
        assert "kilocode" in registered

    def test_upgrade_preserves_disabled_kilocode_legacy_extension_and_user_file(
        self, tmp_path
    ):
        """Legacy reconciliation must not clean disabled or user-owned files."""
        project = _init_project(tmp_path, "kilocode")
        canonical, legacy = _move_kilocode_install_to_legacy_layout(project)

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"
        result = _run_in_project(project, ["extension", "disable", "git"])
        assert result.exit_code == 0, f"extension disable failed: {result.output}"

        disabled_extension_files = sorted(legacy.glob("speckit.git.*.md"))
        assert disabled_extension_files, "disabled extension artifact should remain pre-upgrade"

        user_file = legacy / "speckit.user-owned.md"
        user_file.write_text("# user-owned legacy command", encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, f"upgrade failed: {result.output}"

        assert canonical.is_dir(), ".kilo/commands/ should exist after upgrade"
        assert user_file.read_text(encoding="utf-8") == "# user-owned legacy command"
        for disabled_file in disabled_extension_files:
            assert disabled_file.exists(), (
                "disabled extension artifacts should be preserved during "
                "legacy command-root reconciliation"
            )
        assert not sorted(canonical.glob("speckit.git.*.md")), (
            "disabled extensions must not be re-registered in the canonical dir"
        )

    def test_upgrade_secondary_kilocode_legacy_dir_cleans_commands_without_backfill(
        self, tmp_path
    ):
        """Kilo cleanup stays agent-scoped without inactive extension backfill."""
        project = _init_project(tmp_path, "copilot", integration_options="--skills")
        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        skill = project / ".github" / "skills" / "speckit-git-feature" / "SKILL.md"
        assert skill.exists(), "precondition: active copilot has the git extension skill"

        registry_path = project / ".specify" / "extensions" / ".registry"

        def _git_skills():
            data = json.loads(registry_path.read_text(encoding="utf-8"))
            return data["extensions"]["git"].get("registered_skills", [])

        assert _git_skills(), "precondition: git skills registered for active copilot"

        result = _run_in_project(project, [
            "integration", "install", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, result.output

        canonical, legacy = _move_kilocode_install_to_legacy_layout(project)
        legacy_git_command = legacy / "speckit.git.feature.md"
        legacy_git_command.write_text("# legacy Kilo git command\n", encoding="utf-8")
        registry = json.loads(registry_path.read_text(encoding="utf-8"))
        registry["extensions"]["git"].setdefault("registered_commands", {})[
            "kilocode"
        ] = ["speckit.git.feature"]
        registry_path.write_text(json.dumps(registry), encoding="utf-8")
        assert legacy_git_command.exists(), (
            "precondition: secondary Kilo has a legacy extension command file"
        )

        result = _run_in_project(project, [
            "integration", "upgrade", "kilocode",
            "--script", "sh",
            "--force",
        ])
        assert result.exit_code == 0, result.output

        assert canonical.is_dir(), ".kilo/commands/ should exist after upgrade"
        assert not sorted(canonical.glob("speckit.git.*.md")), (
            "inactive Kilo must wait for use/switch before extension rescaffolding"
        )
        assert not legacy_git_command.exists(), (
            "secondary Kilo legacy extension commands should still be cleaned up"
        )
        registry = json.loads(registry_path.read_text(encoding="utf-8"))
        registered_commands = registry["extensions"]["git"].get(
            "registered_commands", {}
        )
        assert "kilocode" not in registered_commands
        assert skill.exists(), (
            "secondary Kilo legacy cleanup must not delete the active agent's "
            "extension skill"
        )
        assert _git_skills(), (
            "secondary Kilo legacy cleanup must not untrack the active agent's "
            "extension skills in the registry"
        )

    def test_upgrade_bob_skills_migration_preserves_manifest(self, tmp_path):
        """Regression (review #3415, 4724160183, comment 1).

        ``integration upgrade bob --integration-options="--skills"`` migrates a
        legacy Bob 1.x install (``.bob/commands/*.md``) to the skills layout
        (``.bob/skills/speckit-*/SKILL.md``) and stale-removes the old command
        files.  Because that stale-file pass shrinks the tracked set, the
        upgrade's Phase 2 must NOT delete the freshly-saved ``bob.manifest.json``
        — otherwise the migrated project is left untracked and un-upgradeable.
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )

        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"
        manifest_path = (
            project / ".specify" / "integrations" / "bob.manifest.json"
        )
        assert commands.is_dir() and sorted(commands.glob("speckit.*.md"))
        assert not skills.exists()
        assert manifest_path.is_file()

        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, f"migration upgrade failed: {result.output}"

        # Skills layout scaffolded; legacy core command files removed.
        assert skills.is_dir(), ".bob/skills/ must exist after --skills migration"
        assert sorted(skills.glob("speckit-*")), "expected migrated skill dirs"
        core_commands = [
            f for f in commands.glob("speckit.*.md")
            if "agent-context" not in f.name
        ] if commands.exists() else []
        assert core_commands == [], (
            f"legacy core command files should be removed, found: "
            f"{[f.name for f in core_commands]}"
        )

        # The manifest must survive so the project stays tracked/upgradeable.
        assert manifest_path.is_file(), (
            "bob.manifest.json must survive a layout-shrinking migration"
        )
        reupgrade = _run_in_project(project, [
            "integration", "upgrade", "bob", "--script", "sh", "--force",
        ])
        assert reupgrade.exit_code == 0, (
            f"migrated project must remain upgradeable: {reupgrade.output}"
        )

    def test_upgrade_bob_layout_change_reconciles_extension_artifacts(self, tmp_path):
        """Regression (review #3415, 4725829110).

        When a dual-mode agent (Bob) flips layout across an upgrade, the old
        layout's *extension* artifacts must be reconciled — not left orphaned.
        A legacy Bob install renders enabled extensions as ``.bob/commands/``
        command files; migrating to skills via ``--skills`` must remove those
        command files, recreate the extension as ``.bob/skills/`` skills, and
        update the extension registry accordingly (and vice-versa for the
        reverse ``--legacy-commands`` migration).
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"
        registry_path = project / ".specify" / "extensions" / ".registry"

        def _git_registry():
            data = json.loads(registry_path.read_text(encoding="utf-8"))
            g = data["extensions"]["git"]
            return list(g.get("registered_commands", {})), g.get(
                "registered_skills", []
            )

        # Legacy precondition: git renders as command files under .bob/commands.
        assert sorted(commands.glob("speckit.git.*.md")), (
            "legacy Bob should render the git extension as command files"
        )
        assert not list(skills.glob("speckit-git-*")) if skills.exists() else True
        cmds_agents, skill_names = _git_registry()
        assert "bob" in cmds_agents and not skill_names

        # Migrate legacy -> skills.
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, f"--skills migration failed: {result.output}"

        # Old-layout git command files removed; skills recreated.
        assert not sorted(commands.glob("speckit.git.*.md")), (
            "git extension command files must be removed after --skills migration"
        )
        assert sorted(skills.glob("speckit-git-*")), (
            "git extension must be recreated as skills after --skills migration"
        )
        cmds_agents, skill_names = _git_registry()
        assert "bob" not in cmds_agents, (
            "extension registry must drop the stale bob command entry"
        )
        assert skill_names, "extension registry must record the migrated skills"

        # Migrate skills -> legacy: the reverse reconciliation must also hold.
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--legacy-commands",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, (
            f"--legacy-commands migration failed: {result.output}"
        )
        assert not sorted(skills.glob("speckit-git-*")), (
            "git extension skills must be removed after --legacy-commands migration"
        )
        assert sorted(commands.glob("speckit.git.*.md")), (
            "git extension command files must be recreated in legacy layout"
        )
        cmds_agents, skill_names = _git_registry()
        assert "bob" in cmds_agents and not skill_names

    def test_upgrade_layout_change_preserves_extension_artifacts_when_reregistration_fails(
        self, tmp_path
    ):
        """Regression (review 3624075109).

        A layout-changing upgrade must not eagerly unregister the agent's
        extension artifacts before re-registration: the retirement of each
        opposite-mode artifact belongs to
        ``register_enabled_extensions_for_agent``'s deferred toggle cleanup,
        which retires an old artifact only after its replacement in the new
        layout is confirmed. If re-registration cannot rebuild an extension
        (here: its installed manifest is corrupted), the old artifact and its
        registry tracking must survive instead of leaving the extension with
        no artifacts at all.
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )
        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        commands = project / ".bob" / "commands"
        assert sorted(commands.glob("speckit.git.*.md")), (
            "precondition: git extension renders as legacy command files"
        )

        # Corrupt the installed extension manifest so re-registration cannot
        # rebuild the artifacts in the new layout.
        (
            project / ".specify" / "extensions" / "git" / "extension.yml"
        ).write_text("invalid: [", encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, (
            f"upgrade is best-effort about extensions: {result.output}"
        )

        assert sorted(commands.glob("speckit.git.*.md")), (
            "old-layout extension artifacts must survive when their "
            "replacement could not be registered"
        )
        registry_path = project / ".specify" / "extensions" / ".registry"
        data = json.loads(registry_path.read_text(encoding="utf-8"))
        assert "bob" in data["extensions"]["git"].get("registered_commands", {}), (
            "extension registry must keep tracking the surviving artifacts"
        )

    def test_upgrade_active_layout_change_rejected_before_missing_preset_source_can_lose_override(
        self, tmp_path
    ):
        """Regression (review 3623357447).

        Layout-changing upgrades must fail closed even for the active
        integration. Preset rescaffolding is best-effort, so a missing source
        file could otherwise let stale integration cleanup delete the tracked
        old-layout override without creating its replacement.
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )
        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"

        preset_src = tmp_path / "cmd-preset"
        (preset_src / "commands").mkdir(parents=True)
        (preset_src / "commands" / "speckit.plan.md").write_text(
            "---\ndescription: Overridden plan\n---\nOverridden plan content\n",
            encoding="utf-8",
        )
        manifest_data = {
            "schema_version": "1.0",
            "preset": {
                "id": "cmd-preset",
                "name": "Command Preset",
                "version": "1.0.0",
                "description": "Test preset with a command override",
            },
            "requires": {"speckit_version": ">=0.1.0"},
            "provides": {
                "templates": [
                    {
                        "type": "command",
                        "name": "speckit.plan",
                        "file": "commands/speckit.plan.md",
                    }
                ]
            },
        }
        import yaml

        (preset_src / "preset.yml").write_text(
            yaml.dump(manifest_data), encoding="utf-8"
        )
        result = _run_in_project(project, ["preset", "add", "--dev", str(preset_src)])
        assert result.exit_code == 0, f"preset add failed: {result.output}"

        cmd_file = commands / "speckit.plan.md"
        assert "Overridden plan content" in cmd_file.read_text(encoding="utf-8")

        installed_source = (
            project
            / ".specify"
            / "presets"
            / "cmd-preset"
            / "commands"
            / "speckit.plan.md"
        )
        assert installed_source.exists(), "precondition: preset source was installed"
        installed_source.unlink()

        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code != 0, (
            "layout change with tracked preset artifacts must be rejected"
        )
        assert "cmd-preset" in result.output
        assert not skills.exists(), "no skills layout must be scaffolded on rejection"
        assert "Overridden plan content" in cmd_file.read_text(encoding="utf-8"), (
            "tracked old-layout override must remain untouched"
        )

    def test_upgrade_active_layout_change_rejected_with_disabled_preset(
        self, tmp_path
    ):
        """Regression (review 3623779277).

        The post-upgrade rescaffold iterates *enabled* presets only, and a
        disabled preset's artifacts are deliberately frozen until removal
        (``preset disable``). An active-agent layout change must therefore be
        rejected while a disabled preset still owns artifacts for the agent —
        proceeding would delete its old-layout files in stale-manifest
        cleanup, skip recreating them, and leave its registry entries stale.
        Re-enabling does not make a non-transactional layout migration safe.
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )
        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"

        preset_src = tmp_path / "cmd-preset"
        (preset_src / "commands").mkdir(parents=True)
        (preset_src / "commands" / "speckit.plan.md").write_text(
            "---\ndescription: Overridden plan\n---\nOverridden plan content\n",
            encoding="utf-8",
        )
        manifest_data = {
            "schema_version": "1.0",
            "preset": {
                "id": "cmd-preset",
                "name": "Command Preset",
                "version": "1.0.0",
                "description": "Test preset with a command override",
            },
            "requires": {"speckit_version": ">=0.1.0"},
            "provides": {
                "templates": [
                    {
                        "type": "command",
                        "name": "speckit.plan",
                        "file": "commands/speckit.plan.md",
                    }
                ]
            },
        }
        import yaml

        (preset_src / "preset.yml").write_text(
            yaml.dump(manifest_data), encoding="utf-8"
        )
        result = _run_in_project(project, ["preset", "add", "--dev", str(preset_src)])
        assert result.exit_code == 0, f"preset add failed: {result.output}"
        result = _run_in_project(project, ["preset", "disable", "cmd-preset"])
        assert result.exit_code == 0, f"preset disable failed: {result.output}"

        cmd_file = commands / "speckit.plan.md"
        assert "Overridden plan content" in cmd_file.read_text(encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code != 0, (
            "layout change with a disabled preset must be rejected"
        )
        assert "cmd-preset" in result.output
        assert not skills.exists(), "no skills layout must be scaffolded on rejection"
        assert "Overridden plan content" in cmd_file.read_text(encoding="utf-8"), (
            "the disabled preset's command file must be left untouched"
        )

        # Enabled presets are also rejected: rescaffolding can still fail.
        result = _run_in_project(project, ["preset", "enable", "cmd-preset"])
        assert result.exit_code == 0, f"preset enable failed: {result.output}"
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code != 0
        assert "cmd-preset" in result.output
        assert not skills.exists()
        assert "Overridden plan content" in cmd_file.read_text(encoding="utf-8")

    def test_upgrade_secondary_layout_change_rejected_with_presets_installed(
        self, tmp_path
    ):
        """Regression (review #3415, 4726193915; updated for review 3623357447).

        Preset rescaffolding is active-agent-only, so a layout-changing
        ``upgrade`` of a *non-active* integration still cannot reconcile that
        agent's preset artifacts. It must reject the migration with an
        actionable error *before any mutation* when preset overrides are
        installed for that agent. A same-layout upgrade must still succeed.
        """
        project = _init_project(tmp_path, "copilot")
        result = _run_in_project(project, [
            "integration", "install", "bob",
            "--integration-options", "--legacy-commands",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output
        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"
        assert sorted(commands.glob("speckit.*.md"))

        # Simulate a historical preset registration for the non-active bob.
        presets_dir = project / ".specify" / "presets"
        presets_dir.mkdir(parents=True, exist_ok=True)
        (presets_dir / ".registry").write_text(
            json.dumps({
                "presets": {
                    "my-preset": {
                        "version": "1.0.0",
                        "enabled": True,
                        "registered_commands": {"bob": ["speckit.plan"]},
                        "registered_skills": {},
                    }
                }
            }),
            encoding="utf-8",
        )

        # Layout-changing upgrade of the secondary agent is rejected untouched.
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code != 0, (
            "secondary layout change with presets must be rejected"
        )
        assert "preset" in result.output.lower()
        assert "my-preset" in result.output
        assert not skills.exists(), "no skills layout must be scaffolded on rejection"
        assert sorted(commands.glob("speckit.*.md")), (
            "legacy command files must be left untouched on rejection"
        )

        # A same-layout upgrade (no flag) must still succeed with presets present.
        result = _run_in_project(project, [
            "integration", "upgrade", "bob", "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, (
            f"same-layout upgrade must not be blocked by presets: {result.output}"
        )

    def test_upgrade_bob_layout_change_rejected_when_preset_registry_unreadable(
        self, tmp_path
    ):
        """Regression (review #3415, 4744636079).

        The preset guard must fail *closed*: if the preset registry exists but
        cannot be read/parsed (corruption, permissions), the layout-changing
        upgrade must be rejected before any mutation rather than proceeding on
        a false "no presets installed" assumption (which would let ``--force``
        delete preset-overridden command files while their registry state is
        unknown). A genuinely absent registry must still be allowed.
        """
        project = _init_project(
            tmp_path, "bob", integration_options="--legacy-commands"
        )
        commands = project / ".bob" / "commands"
        skills = project / ".bob" / "skills"
        assert sorted(commands.glob("speckit.*.md"))

        # Corrupted (unparseable) registry: exists but cannot be read as JSON.
        presets_dir = project / ".specify" / "presets"
        presets_dir.mkdir(parents=True, exist_ok=True)
        (presets_dir / ".registry").write_text("{ not valid json", encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code != 0, (
            "layout change must be rejected when preset registry is unreadable"
        )
        assert "preset registry" in result.output.lower()
        assert not skills.exists(), "no skills layout may be scaffolded on rejection"
        assert sorted(commands.glob("speckit.*.md")), (
            "legacy command files must be untouched when failing closed"
        )

        # A valid, empty registry must NOT block the migration.
        (presets_dir / ".registry").write_text(
            json.dumps({"presets": {}}), encoding="utf-8"
        )
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, (
            f"valid empty preset registry must not block migration: {result.output}"
        )
        assert skills.exists(), "skills layout should be scaffolded once unblocked"

    def test_upgrade_secondary_bob_layout_change_preserves_active_agent_skills(
        self, tmp_path
    ):
        """Regression (review #3415, 4726347306).

        ``integration upgrade`` supports upgrading a *secondary* (non-active)
        integration. The layout-change extension reconciliation must NOT run
        for a secondary agent: ``unregister_agent_artifacts`` treats the
        unscoped per-extension ``registered_skills`` as belonging to the passed
        agent and, if that agent's skills dir is absent, scans every agent's
        skills dir — which could delete/untrack the *active* agent's extension
        skills. The following re-registration cannot repair that because
        extension skill rendering is active-agent-scoped (#2948).
        """
        # Active agent: copilot in skills mode → git extension renders as skills.
        project = _init_project(tmp_path, "copilot", integration_options="--skills")
        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        skill = project / ".github" / "skills" / "speckit-git-feature" / "SKILL.md"
        assert skill.exists(), "precondition: active copilot has the git extension skill"

        registry_path = project / ".specify" / "extensions" / ".registry"

        def _git_skills():
            data = json.loads(registry_path.read_text(encoding="utf-8"))
            return data["extensions"]["git"].get("registered_skills", [])

        assert _git_skills(), "precondition: git skills registered for active copilot"

        # Add a secondary (non-active) Bob in the legacy commands layout.
        result = _run_in_project(project, [
            "integration", "install", "bob",
            "--integration-options", "--legacy-commands",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        # Flip the *secondary* Bob's layout to skills. copilot stays active.
        result = _run_in_project(project, [
            "integration", "upgrade", "bob",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        # The active agent's extension skill must be untouched on disk and in
        # the registry — the secondary layout change must not reconcile it.
        assert skill.exists(), (
            "secondary Bob layout change must not delete the active agent's "
            "extension skill"
        )
        assert _git_skills(), (
            "secondary Bob layout change must not untrack the active agent's "
            "extension skills in the registry"
        )

    def test_upgrade_preserves_existing_vscode_settings(self, tmp_path):
        """Regression: copilot upgrade must not stale-delete .vscode/settings.json.

        On init the file is created and recorded in the manifest. On upgrade,
        setup() merges into the now-existing file and intentionally stops
        tracking it, so without ``stale_cleanup_exclusions()`` the Phase 2
        stale cleanup would delete it (destroying the user's settings).
        """
        project = _init_project(
            tmp_path, "copilot", integration_options="--commands"
        )
        settings = project / ".vscode" / "settings.json"
        assert settings.is_file(), "init should create .vscode/settings.json"
        before = json.loads(settings.read_text(encoding="utf-8"))
        assert before, "settings.json should contain managed defaults"

        # Simulate a user editing their settings: add a custom key that the
        # integration does not manage.  It must survive the upgrade.
        before["editor.fontSize"] = 17
        settings.write_text(json.dumps(before), encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "copilot",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        assert settings.is_file(), ".vscode/settings.json must survive upgrade"
        after = json.loads(settings.read_text(encoding="utf-8"))
        assert after.get("editor.fontSize") == 17, (
            "user-defined settings must be preserved after upgrade"
        )

    def test_upgrade_restores_executable_bit_on_shared_scripts(self, tmp_path):
        """Regression: scripts refreshed by the managed-refresh step stay +x."""
        if os.name == "nt":
            pytest.skip("POSIX execute bits are not meaningful on Windows")
        project = _init_project(tmp_path, "copilot")
        script = project / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
        assert script.is_file()
        # Simulate a perms-losing install (e.g. wheel extraction dropping +x).
        script.chmod(0o644)
        assert not (script.stat().st_mode & 0o111)

        result = _run_in_project(project, [
            "integration", "upgrade", "copilot",
            "--script", "sh",
        ])
        assert result.exit_code == 0, result.output

        assert script.stat().st_mode & 0o111, (
            "shared .sh scripts must be executable after upgrade"
        )

    def test_upgrade_does_not_backfill_non_active_integration(self, tmp_path):
        """Upgrading a non-active integration must not register extensions for it.

        Maintainer-requested behavior for #2948 (reverses the #2886 upgrade
        back-fill): non-active integrations only receive extension artifacts
        when selected via ``integration use`` / ``switch``. Upgrade of a
        non-active integration refreshes its own files and nothing else.
        """
        project = _init_project(tmp_path, "claude")

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        result = _run_in_project(project, [
            "integration", "install", "codex",
            "--script", "sh",
        ])
        assert result.exit_code == 0, result.output

        registry_path = project / ".specify" / "extensions" / ".registry"
        assert "codex" not in json.loads(registry_path.read_text(encoding="utf-8"))[
            "extensions"
        ]["git"]["registered_commands"]

        result = _run_in_project(project, [
            "integration", "upgrade", "codex",
            "--script", "sh",
        ])
        assert result.exit_code == 0, result.output

        registered = json.loads(registry_path.read_text(encoding="utf-8"))[
            "extensions"
        ]["git"]["registered_commands"]
        assert "codex" not in registered, (
            "upgrade must not back-fill non-active integrations (#2948)"
        )
        assert not (
            project / ".agents" / "skills" / "speckit-git-feature" / "SKILL.md"
        ).exists()

    def test_upgrade_active_integration_reregisters_extensions(self, tmp_path):
        """Upgrading the active integration restores its extension commands.

        The active integration keeps the re-registration pass on upgrade so
        missing or stale extension command files are recreated (#2948 scopes
        the pass to the active integration; #2886 introduced it).
        """
        project = _init_project(tmp_path, "claude")

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        cmd_file = project / ".claude" / "skills" / "speckit-git-feature" / "SKILL.md"
        assert cmd_file.exists(), "precondition: extension command registered"
        cmd_file.unlink()

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--script", "sh",
        ])
        assert result.exit_code == 0, result.output

        assert cmd_file.exists(), (
            "upgrade of the active integration re-registers extension commands"
        )

    def test_upgrade_copilot_skills_restores_extension_skill_over_regenerated_dir(
        self, tmp_path
    ):
        """End-to-end regression for #3849 (upgrade-overwrites-copilot-skills).

        In Copilot skills mode, ``integration upgrade`` runs ``setup()`` — which
        regenerates the core-template skill directories — *before* re-registering
        installed extensions. The extension re-registration then hits the
        ``skill_dir_preexists`` guard in ``_register_extension_skills`` (the skill
        sub-directory exists, courtesy of ``setup()``, but its ``SKILL.md`` has
        not been rewritten with extension content), so pre-fix the extension
        skill was silently left missing — its command content lost even though the
        extension remained installed and registered.

        The fix threads ``force=True`` from ``integration_upgrade()`` down to
        ``_register_extension_skills`` so the guard is bypassed and the extension
        content is re-composed on top of the just-regenerated directory. This test
        exercises the full ``specify integration upgrade`` command path and fails
        without the fix (the skill is never recreated).
        """
        project = _init_project(
            tmp_path, "copilot", integration_options="--skills"
        )

        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        skill_dir = project / ".github" / "skills" / "speckit-git-feature"
        skill_file = skill_dir / "SKILL.md"
        assert skill_file.exists(), (
            "precondition: git extension renders as a Copilot skill"
        )
        original = skill_file.read_text(encoding="utf-8")
        assert "source: extension:git" in original, (
            "precondition: skill carries the git extension ownership marker"
        )

        # Simulate the exact pre-condition the bug depends on: the skill file is
        # gone but its directory survives (as it does once setup() regenerates the
        # core-template layout during upgrade), triggering the skill_dir_preexists
        # skip guard on re-registration.
        skill_file.unlink()
        assert skill_dir.exists() and not skill_file.exists()

        result = _run_in_project(project, [
            "integration", "upgrade", "copilot",
            "--integration-options", "--skills",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        assert skill_file.exists(), (
            "upgrade must restore the extension skill even when its directory "
            "already exists (regression #3849)"
        )
        restored = skill_file.read_text(encoding="utf-8")
        assert "source: extension:git" in restored, (
            "restored skill must contain the git extension content, not a bare "
            "core-template stub"
        )
        assert "# Git Feature Skill" in restored

    def test_upgrade_active_integration_reregisters_presets(self, tmp_path):
        """Upgrading the active integration restores missing preset artifacts."""
        import yaml

        project = _init_project(tmp_path, "claude")
        preset_src = tmp_path / "upgrade-preset"
        (preset_src / "commands").mkdir(parents=True)
        (preset_src / "commands" / "speckit.upgrade-check.md").write_text(
            "---\ndescription: Upgrade check\n---\nPreset upgrade body\n",
            encoding="utf-8",
        )
        manifest = {
            "schema_version": "1.0",
            "preset": {
                "id": "upgrade-preset",
                "name": "Upgrade Preset",
                "version": "1.0.0",
                "description": "Upgrade preset test",
            },
            "requires": {"speckit_version": ">=0.1.0"},
            "provides": {
                "templates": [
                    {
                        "type": "command",
                        "name": "speckit.upgrade-check",
                        "file": "commands/speckit.upgrade-check.md",
                    }
                ]
            },
        }
        (preset_src / "preset.yml").write_text(
            yaml.dump(manifest), encoding="utf-8"
        )

        result = _run_in_project(
            project, ["preset", "add", "--dev", str(preset_src)]
        )
        assert result.exit_code == 0, result.output

        skill_dir = (
            project / ".claude" / "skills" / "speckit-upgrade-check"
        )
        skill_file = skill_dir / "SKILL.md"
        assert "Preset upgrade body" in skill_file.read_text(encoding="utf-8")
        shutil.rmtree(skill_dir)

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--script", "sh",
        ])
        assert result.exit_code == 0, result.output
        assert "Preset upgrade body" in skill_file.read_text(encoding="utf-8")

    def test_upgrade_force_syncs_manifest_hash_for_preset_overridden_skill(
        self, tmp_path
    ):
        """Regression for #4696.

        A preset overriding a core command that renders as a skill
        (e.g. ``speckit.tasks`` for ``codex``/``claude``) is rewritten by
        ``_register_presets_for_agent`` *after* ``new_manifest.save()`` during
        ``integration upgrade --force``. Without a post-registration resync,
        the manifest keeps the base template's hash for that skill file, so
        ``integration status`` immediately reports it as modified and a
        subsequent ``upgrade`` (without ``--force``) is blocked.
        """
        import yaml

        project = _init_project(tmp_path, "claude")

        preset_src = tmp_path / "tasks-preset"
        (preset_src / "commands").mkdir(parents=True)
        (preset_src / "commands" / "speckit.tasks.md").write_text(
            "---\ndescription: Tasks override\n---\nPreset tasks body\n",
            encoding="utf-8",
        )
        manifest = {
            "schema_version": "1.0",
            "preset": {
                "id": "tasks-preset",
                "name": "Tasks Preset",
                "version": "1.0.0",
                "description": "Preset overriding speckit.tasks",
            },
            "requires": {"speckit_version": ">=0.1.0"},
            "provides": {
                "templates": [
                    {
                        "type": "command",
                        "name": "speckit.tasks",
                        "file": "commands/speckit.tasks.md",
                    }
                ]
            },
        }
        (preset_src / "preset.yml").write_text(
            yaml.dump(manifest), encoding="utf-8"
        )

        result = _run_in_project(project, ["preset", "add", "--dev", str(preset_src)])
        assert result.exit_code == 0, result.output

        skill_rel = ".claude/skills/speckit-tasks/SKILL.md"
        skill_file = project / skill_rel
        assert "Preset tasks body" in skill_file.read_text(encoding="utf-8")

        result = _run_in_project(project, [
            "integration", "upgrade", "claude",
            "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        manifest_path = project / ".specify" / "integrations" / "claude.manifest.json"
        recorded_hash = json.loads(manifest_path.read_text(encoding="utf-8"))["files"][skill_rel]
        actual_hash = hashlib.sha256(skill_file.read_bytes()).hexdigest()
        assert recorded_hash == actual_hash, (
            "manifest hash for the preset-overridden skill must match the "
            "file `_register_presets_for_agent` just wrote"
        )

        status_result = _run_in_project(project, ["integration", "status"])
        assert "Integration status: OK" in status_result.output, status_result.output
        assert "Modified managed files: 0" in status_result.output
        assert "managed-files-modified" not in status_result.output

    def test_resync_manifest_warns_on_per_file_failure_and_keeps_going(
        self, tmp_path, capsys
    ):
        """A single file's rehash failure must warn, not vanish silently.

        ``_resync_manifest_after_registration`` best-effort-skips files it
        can't rehash, but a skip that produces no warning leaves the user
        with a stale hash and no signal that the manifest wasn't fully
        synchronized. Rehashing must also continue for the remaining files.
        """
        from specify_cli.integrations._helpers import (
            _resync_manifest_after_registration,
        )
        from specify_cli.integrations.manifest import IntegrationManifest

        project = tmp_path / "proj"
        project.mkdir()
        (project / "ok.md").write_text("ok content\n", encoding="utf-8")
        (project / "bad.md").write_text("bad content\n", encoding="utf-8")

        manifest = IntegrationManifest("claude", project, version="test")
        manifest.record_existing("ok.md")
        manifest.record_existing("bad.md")
        stale_hash = manifest._files["bad.md"]
        manifest.save()

        # Both files' bytes changed on disk after the manifest was saved
        # (simulating registration overwriting them), but only "bad.md"
        # fails to rehash.
        (project / "ok.md").write_text("ok content v2\n", encoding="utf-8")
        (project / "bad.md").write_text("bad content v2\n", encoding="utf-8")

        real_record_existing = IntegrationManifest.record_existing

        def fake_record_existing(self, rel_path, **kwargs):
            if str(rel_path) == "bad.md":
                raise OSError("permission denied")
            return real_record_existing(self, rel_path, **kwargs)

        import unittest.mock as mock

        with mock.patch.object(
            IntegrationManifest, "record_existing", fake_record_existing
        ):
            _resync_manifest_after_registration(
                manifest, "claude", continuing="Continuing."
            )

        captured = strip_ansi(capsys.readouterr().out)
        assert "Warning:" in captured
        assert "bad.md" in captured

        reloaded = json.loads(manifest.manifest_path.read_text(encoding="utf-8"))
        ok_hash = hashlib.sha256(
            (project / "ok.md").read_bytes()
        ).hexdigest()
        assert reloaded["files"]["ok.md"] == ok_hash
        assert reloaded["files"]["bad.md"] == stale_hash

    @pytest.mark.parametrize(
        "unmodified_files",
        [None, {"bad.md", "ok.md"}],
        ids=["upgrade", "use-or-switch-snapshot"],
    )
    def test_resync_manifest_probe_error_does_not_abort_remaining_files(
        self, tmp_path, capsys, unmodified_files
    ):
        """An ``OSError`` from the pre-rehash filesystem probes must warn
        and continue, not abort the whole resync loop.

        ``is_symlink()``/``is_file()`` run before the per-file ``try`` that
        wraps ``record_existing()``. If one of those probes raises (e.g. an
        inaccessible path), it must not jump past the remaining files in
        ``new_manifest.files`` and leave their hashes stale. With
        ``unmodified_files`` (``use`` and installed-target ``switch``, #5078)
        the changed-bytes check also runs per file, inside that ``try``.
        """
        from specify_cli.integrations._helpers import (
            _resync_manifest_after_registration,
        )
        from specify_cli.integrations.manifest import IntegrationManifest

        project = tmp_path / "proj"
        project.mkdir()
        (project / "bad.md").write_text("bad content\n", encoding="utf-8")
        (project / "ok.md").write_text("ok content\n", encoding="utf-8")

        manifest = IntegrationManifest("claude", project, version="test")
        manifest.record_existing("bad.md")
        manifest.record_existing("ok.md")
        manifest.save()

        # Both files' bytes changed on disk after the manifest was saved
        # (simulating registration overwriting them), but "bad.md" fails
        # during the pre-rehash filesystem probe, not during rehashing.
        (project / "bad.md").write_text("bad content v2\n", encoding="utf-8")
        (project / "ok.md").write_text("ok content v2\n", encoding="utf-8")

        real_is_file = Path.is_file

        def fake_is_file(self):
            if self.name == "bad.md":
                raise OSError("permission denied")
            return real_is_file(self)

        import unittest.mock as mock

        with mock.patch.object(Path, "is_file", fake_is_file):
            _resync_manifest_after_registration(
                manifest,
                "claude",
                continuing="Continuing.",
                unmodified_files=unmodified_files,
            )

        captured = strip_ansi(capsys.readouterr().out)
        assert "Warning:" in captured
        assert "bad.md" in captured

        reloaded = json.loads(manifest.manifest_path.read_text(encoding="utf-8"))
        ok_hash = hashlib.sha256((project / "ok.md").read_bytes()).hexdigest()
        assert reloaded["files"]["ok.md"] == ok_hash, (
            "a probe error on an earlier file must not abort rehashing of "
            "the remaining tracked files"
        )

    def test_resync_with_snapshot_skips_files_registration_left_unchanged(
        self, tmp_path
    ):
        """With ``unmodified_files`` only changed bytes are re-recorded (#5078).

        ``record_existing()`` clears a file's recovered marker, so a file
        that registration didn't touch must keep its entry as it was.
        """
        from specify_cli.integrations._helpers import (
            _resync_manifest_after_registration,
        )
        from specify_cli.integrations.manifest import IntegrationManifest

        project = tmp_path / "proj"
        project.mkdir()
        (project / "kept.md").write_text("kept content\n", encoding="utf-8")
        (project / "ok.md").write_text("ok content\n", encoding="utf-8")

        manifest = IntegrationManifest("claude", project, version="test")
        manifest.record_existing("kept.md", recovered=True)
        manifest.record_existing("ok.md")
        manifest.save()
        (project / "ok.md").write_text("ok content v2\n", encoding="utf-8")

        _resync_manifest_after_registration(
            manifest,
            "claude",
            continuing="Continuing.",
            unmodified_files={"kept.md", "ok.md"},
        )

        reloaded = IntegrationManifest.load("claude", project)
        assert reloaded.is_recovered("kept.md")
        ok_hash = hashlib.sha256((project / "ok.md").read_bytes()).hexdigest()
        assert reloaded.files["ok.md"] == ok_hash

    def test_snapshot_follows_check_modified_rules_one_file_at_a_time(
        self, tmp_path, capsys
    ):
        """The snapshot matches ``check_modified()`` for paths in the project.

        A deleted file counts as unmodified, an edited one as modified, and a
        file that can't be probed only drops itself from the snapshot (#5078),
        with a warning, since its hash won't be refreshed.
        """
        import unittest.mock as mock

        from specify_cli.integrations._helpers import (
            _snapshot_manifest_before_registration,
        )
        from specify_cli.integrations.manifest import IntegrationManifest

        project = tmp_path / "proj"
        project.mkdir()
        for name in ("ok.md", "edited.md", "deleted.md", "bad.md"):
            (project / name).write_bytes(f"{name} content\n".encode())

        manifest = IntegrationManifest("claude", project, version="test")
        for name in ("ok.md", "edited.md", "deleted.md", "bad.md"):
            manifest.record_existing(name)
        manifest.save()
        (project / "edited.md").write_bytes(b"user edit\n")
        (project / "deleted.md").unlink()

        real_is_file = Path.is_file

        def fake_is_file(self):
            if self.name == "bad.md":
                raise OSError("permission denied")
            return real_is_file(self)

        with mock.patch.object(Path, "is_file", fake_is_file):
            snapshot, unmodified = _snapshot_manifest_before_registration(
                project, "claude"
            )

        assert snapshot is not None, "one unreadable file must not drop the snapshot"
        assert unmodified == {"ok.md", "deleted.md"}

        captured = strip_ansi(capsys.readouterr().out)
        assert "Warning:" in captured
        assert "'bad.md'" in captured, "an unreadable file was skipped silently"
        assert "edited.md" not in captured, "a user edit is not an error"

    @pytest.mark.parametrize("escape", ["dotdot", "symlinked-parent"])
    def test_snapshot_skips_manifest_paths_outside_the_project(
        self, tmp_path, capsys, escape
    ):
        """Paths that record_existing() rejects stay out of the snapshot.

        They are never hashed either, so the snapshot and the resync's
        changed-bytes check (#5078) can't read a file outside the project.
        """
        import unittest.mock as mock

        from specify_cli.integrations import manifest as manifest_module
        from specify_cli.integrations._helpers import (
            _resync_manifest_after_registration,
            _snapshot_manifest_before_registration,
        )
        from specify_cli.integrations.manifest import IntegrationManifest

        project = tmp_path / "proj"
        project.mkdir()
        outside = tmp_path / "outside"
        outside.mkdir()
        secret = outside / "secret.md"
        secret.write_text("outside project\n", encoding="utf-8")
        (project / "ok.md").write_text("ok content\n", encoding="utf-8")

        if escape == "dotdot":
            escaping_key = "../outside/secret.md"
        else:
            try:
                (project / "outside-link").symlink_to(
                    outside, target_is_directory=True
                )
            except OSError as exc:
                pytest.skip(f"symlinks unavailable: {exc}")
            escaping_key = "outside-link/secret.md"

        manifest = IntegrationManifest("claude", project, version="test")
        manifest.record_existing("ok.md")
        manifest._files[escaping_key] = hashlib.sha256(secret.read_bytes()).hexdigest()
        manifest.save()

        hashed: list[str] = []
        real_sha256 = manifest_module._sha256

        def recording_sha256(path):
            hashed.append(Path(path).name)
            return real_sha256(path)

        with mock.patch.object(manifest_module, "_sha256", recording_sha256):
            snapshot, unmodified = _snapshot_manifest_before_registration(
                project, "claude"
            )
            assert snapshot is not None
            assert unmodified == {"ok.md"}
            assert "secret.md" not in hashed, "the snapshot hashed a path outside the project"
            assert f"'{escaping_key}'" in strip_ansi(capsys.readouterr().out), (
                "a path left out of the snapshot was skipped silently"
            )

            # The resync checks paths itself too, as a new-target switch
            # passes every tracked file.
            _resync_manifest_after_registration(
                snapshot,
                "claude",
                continuing="Continuing.",
                unmodified_files=set(snapshot.files),
            )
            assert "secret.md" not in hashed, "the resync hashed a path outside the project"

    def test_upgrade_non_active_agent_preserves_active_agent_skills(self, tmp_path):
        """Upgrading a non-active agent must not touch the active agent's skills.

        Regression for the #2886 wiring: extension skill rendering is
        active-agent-scoped, so routing upgrade of a *secondary* agent through
        ``register_enabled_extensions_for_agent`` used to re-render the
        *active* skills-mode agent's extension skills as a side effect —
        resurrecting skill files the user had deliberately deleted. The skills
        pass is now gated on the target being the active agent. (Skills parity
        for non-active agents is tracked separately in #2948.)
        """
        # Active agent: copilot in skills mode → git extension renders as skills.
        project = _init_project(tmp_path, "copilot", integration_options="--skills")
        result = _run_in_project(project, ["extension", "add", "git"])
        assert result.exit_code == 0, f"extension add failed: {result.output}"

        skill = project / ".github" / "skills" / "speckit-git-feature" / "SKILL.md"
        assert skill.exists(), "precondition: active copilot has the git extension skill"

        # Add a secondary (non-active) agent; copilot is not multi_install_safe.
        result = _run_in_project(project, [
            "integration", "install", "codex", "--script", "sh", "--force",
        ])
        assert result.exit_code == 0, result.output

        # The user deliberately removes the active agent's git skill.
        shutil.rmtree(skill.parent)
        assert not skill.exists()

        # Upgrading the *non-active* agent must not re-render copilot's skills.
        result = _run_in_project(project, [
            "integration", "upgrade", "codex", "--script", "sh",
        ])
        assert result.exit_code == 0, result.output
        assert not skill.exists(), (
            "upgrading a non-active agent must not resurrect the active agent's "
            "deleted extension skill (#2886)"
        )



class TestIntegrationUpgradeDiagnostics(IntegrationCatalogCliTestBase):
    def test_integration_upgrade_failure_reports_phase_and_target(
        self, tmp_path, monkeypatch
    ):
        from specify_cli.integrations import INTEGRATION_REGISTRY
        from specify_cli.integrations.copilot import CopilotIntegration

        class UpgradeBrokenIntegration(CopilotIntegration):
            key = "upgrade-broken"
            config = dict(CopilotIntegration.config)
            config["name"] = "Upgrade Broken"

            def setup(self, project_root, manifest, **kwargs):
                raise OSError("upgrade exploded\nwith context")

        project = self._make_project(tmp_path)
        monkeypatch.setitem(
            INTEGRATION_REGISTRY, "upgrade-broken", UpgradeBrokenIntegration()
        )

        (project / ".specify" / "integrations").mkdir(parents=True, exist_ok=True)
        (project / ".specify" / "integration.json").write_text(
            json.dumps(
                {
                    "version": 1,
                    "integration": "upgrade-broken",
                    "integrations": ["upgrade-broken"],
                    "integration_settings": {"upgrade-broken": {"script": "sh"}},
                }
            ),
            encoding="utf-8",
        )
        (
            project / ".specify" / "integrations" / "upgrade-broken.manifest.json"
        ).write_text(
            json.dumps(
                {
                    "integration": "upgrade-broken",
                    "version": "0.0.0",
                    "installed_at": "2026-05-16T00:00:00+00:00",
                    "files": {},
                }
            ),
            encoding="utf-8",
        )

        result = self._invoke(["integration", "upgrade", "upgrade-broken"], project)
        normalized = _normalize_cli_output(result.output)

        assert result.exit_code == 1, result.output
        assert "Failed to upgrade integration 'upgrade-broken'" in normalized
        assert "upgrade exploded with context" in normalized
        assert "previous integration files may still be in place" in normalized


class TestIntegrationUpgradeBasic:
    """Test ``specify integration upgrade``."""

    def _init_project(self, tmp_path, integration="copilot"):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = tmp_path / "proj"
        project.mkdir()
        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, [
                "init", "--here",
                "--integration", integration,
                "--script", "sh",
                "--ignore-agent-tools",
            ], catch_exceptions=False)
        finally:
            os.chdir(old)
        assert result.exit_code == 0, result.output
        return project

    def test_upgrade_requires_speckit_project(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        old = os.getcwd()
        try:
            os.chdir(tmp_path)
            result = runner.invoke(app, ["integration", "upgrade"])
        finally:
            os.chdir(old)
        assert result.exit_code != 0
        assert "Not a Spec Kit project" in result.output

    def test_upgrade_no_integration_installed(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = tmp_path / "proj"
        project.mkdir()
        (project / ".specify").mkdir()
        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade"])
        finally:
            os.chdir(old)
        assert result.exit_code == 0
        assert "No integration is currently installed" in result.output

    def test_upgrade_succeeds(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = self._init_project(tmp_path, "copilot")

        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade"], catch_exceptions=False)
        finally:
            os.chdir(old)
        assert result.exit_code == 0
        assert "upgraded successfully" in result.output

    def test_upgrade_blocks_on_modified_files(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = self._init_project(tmp_path, "copilot")

        # Modify a tracked file so the manifest hash won't match
        manifest_path = project / ".specify" / "integrations" / "copilot.manifest.json"
        assert manifest_path.exists(), "Manifest should exist after init"
        manifest_data = json.loads(manifest_path.read_text())
        tracked_files = manifest_data.get("files", {})
        assert tracked_files, "Manifest should track at least one file"
        first_rel = next(iter(tracked_files))
        target_file = project / first_rel
        assert target_file.exists(), f"Tracked file {first_rel} should exist"
        target_file.write_text("MODIFIED CONTENT\n")

        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade"])
        finally:
            os.chdir(old)
        assert result.exit_code != 0
        assert "modified" in result.output.lower()

    def test_upgrade_force_overwrites_modified(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = self._init_project(tmp_path, "copilot")

        # Modify a tracked file
        manifest_path = project / ".specify" / "integrations" / "copilot.manifest.json"
        manifest_data = json.loads(manifest_path.read_text())
        tracked_files = manifest_data.get("files", {})
        assert tracked_files, "Manifest should track at least one file"
        first_rel = next(iter(tracked_files))
        target_file = project / first_rel
        assert target_file.exists(), f"Tracked file {first_rel} should exist"
        target_file.write_text("MODIFIED CONTENT\n")

        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade", "--force"], catch_exceptions=False)
        finally:
            os.chdir(old)
        assert result.exit_code == 0
        assert "upgraded successfully" in result.output

    def test_upgrade_wrong_integration_key(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = self._init_project(tmp_path, "copilot")

        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade", "claude"])
        finally:
            os.chdir(old)
        assert result.exit_code != 0
        assert "not installed" in result.output

    def test_upgrade_no_manifest(self, tmp_path):
        """Upgrade with missing manifest suggests fresh install."""
        from typer.testing import CliRunner
        from specify_cli import app
        runner = CliRunner()
        project = self._init_project(tmp_path, "copilot")

        # Remove manifest
        manifest_path = project / ".specify" / "integrations" / "copilot.manifest.json"
        if manifest_path.exists():
            manifest_path.unlink()

        old = os.getcwd()
        try:
            os.chdir(project)
            result = runner.invoke(app, ["integration", "upgrade"])
        finally:
            os.chdir(old)
        assert result.exit_code == 0
        assert "Nothing to upgrade" in result.output