specify-cli 1.2.2__py3-none-any.whl → 1.2.3__py3-none-any.whl

specify_cli/_install_ignore.py

@@ -0,0 +1,87 @@
+"""Shared source-directory installation filtering for extensions and presets."""
+
+import re
+from pathlib import Path
+from typing import Callable, List, Optional, Set
+
+import pathspec
+
+
+def load_install_ignore(
+    source_dir: Path,
+    ignore_filename: str,
+    validation_error: type[Exception],
+) -> Optional[Callable[[str, List[str]], Set[str]]]:
+    """Load a UTF-8 ignore file as a copytree callback, or return None if absent.
+
+    Match the extension installer's Git-style patterns, including whitespace
+    trimming and backslash normalization. Only the named root ignore file is
+    read; there are no default exclusions except the ignore filename itself.
+    Invalid encoding or patterns raise the caller's domain validation error
+    before copying.
+    Excluded directories are pruned by copytree, so child negations cannot
+    restore files inside them unless the parent directory is also re-included.
+    """
+    ignore_file = source_dir / ignore_filename
+    if not ignore_file.exists():
+        return None
+
+    # Accept UTF-8 with or without the BOM emitted by Windows PowerShell 5.1.
+    # Strip it after decoding so error offsets remain relative to the file.
+    try:
+        raw = ignore_file.read_text(encoding="utf-8").removeprefix("\ufeff")
+    except UnicodeDecodeError as e:
+        raise validation_error(
+            f"{ignore_filename} is not valid UTF-8: {ignore_file} "
+            f"({e.reason} at byte {e.start})"
+        )
+    lines: List[str] = raw.splitlines()
+
+    # Normalise backslashes in patterns so Windows-authored files work
+    normalised: List[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            normalised.append(stripped.replace("\\", "/"))
+        else:
+            # Preserve blanks/comments so pathspec line numbers stay stable
+            normalised.append(line)
+
+    # Always ignore the ignore file itself, even after a negation pattern.
+    normalised.append(ignore_filename)
+
+    try:
+        spec = pathspec.GitIgnoreSpec.from_lines(normalised)
+    except (ValueError, re.error) as e:
+        # Locate the first malformed source rule only on failure. Valid files
+        # compile once; the appended self-exclusion is not a source line.
+        location = ""
+        for line_number, pattern in enumerate(normalised[:len(lines)], start=1):
+            try:
+                pathspec.GitIgnoreSpec.from_lines([pattern])
+            except (ValueError, re.error):
+                location = f" at line {line_number}: {pattern!r}"
+                break
+        raise validation_error(
+            f"Invalid patterns in {ignore_filename}: {ignore_file}{location} ({e})"
+        ) from e
+
+    def _ignore(directory: str, entries: List[str]) -> Set[str]:
+        ignored: Set[str] = set()
+        rel_dir = Path(directory).relative_to(source_dir)
+        for entry in entries:
+            rel_path = str(rel_dir / entry) if str(rel_dir) != "." else entry
+            # Normalise to forward slashes for consistent matching
+            rel_path_fwd = rel_path.replace("\\", "/")
+
+            entry_full = Path(directory) / entry
+            if entry_full.is_dir():
+                # Append '/' so directory-only patterns (e.g. tests/) match
+                if spec.match_file(rel_path_fwd + "/"):
+                    ignored.add(entry)
+            else:
+                if spec.match_file(rel_path_fwd):
+                    ignored.add(entry)
+        return ignored
+
+    return _ignore

specify_cli/command_check.py

@@ -30,7 +30,7 @@ def _check_external_tools(
         args = integration.build_exec_args("test", project_root=project_root)
         tools = [args[0] if args else integration._resolve_executable()]
     if not tools:
-        tracker.skip(key, "IDE-based, no CLI check")
+        tracker.skip(key, "no CLI required")
         return False
     tools = list(dict.fromkeys(tools))
     missing = [tool for tool in tools if shutil.which(tool) is None]
@@ -90,7 +90,7 @@ def check() -> None:
         elif requires_cli:
             agent_results[agent_key] = check_tool(agent_key, tracker=tracker)
         else:
-            tracker.skip(agent_key, "IDE-based, no CLI check")
+            tracker.skip(agent_key, "no CLI required")
             agent_results[agent_key] = False
 
     tracker.add("code", "Visual Studio Code")

specify_cli/command_init.py

@@ -1057,6 +1057,24 @@ def register(app: typer.Typer) -> None:
             steps_lines.append("1. You're already in the project directory!")
             step_num = 2
 
+        if not resolved_integration.list_command_templates():
+            steps_lines.append(
+                f"{step_num}. Choose an integration: [cyan]specify integration list[/cyan]"
+            )
+            steps_lines.append(
+                f"{step_num + 1}. Switch this project to it: [cyan]specify integration switch <key>[/cyan]"
+            )
+            console.print()
+            console.print(
+                Panel(
+                    "\n".join(steps_lines),
+                    title="Next Steps",
+                    border_style="cyan",
+                    padding=(1, 2),
+                )
+            )
+            return
+
         _is_skills_integration = resolved_integration.is_skills_mode(
             integration_parsed_options or None, project_root=project_path
         )

specify_cli/core_pack/extensions/github/README.md

@@ -26,7 +26,7 @@ its configured `--commands-dir` in both commands and skills layouts. Installing
 `speckit-github-taskstoissues/SKILL.md` in skills mode. The core
 `speckit.taskstoissues` command is deprecated but remains available during migration.
 Use this extension's recommended command instead. See
-[integration-specific options](../../docs/reference/integrations.md#integration-specific-options).
+[integration-specific options](../../docs/integrations/cli.md#integration-specific-options).
 
 ## Removal
 
@@ -96,7 +96,7 @@ specify integration upgrade <key>
 Replace `<key>` with the installed integration key, or omit it to upgrade the
 default integration. This refreshes the core command with the deprecation
 warning. If locally modified files block the upgrade, inspect those changes
-before deciding whether to overwrite them. See [Upgrade an Integration](../../docs/reference/integrations.md#upgrade-an-integration).
+before deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration).
 
 To migrate, install the extension and use the namespaced command instead:
 

specify_cli/core_pack/extensions/github/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: github
   name: "GitHub Integration"
-  version: "1.0.2"
+  version: "1.0.3"
   description: "GitHub platform integration for Spec Kit - create GitHub issues from a feature's task list"
   author: spec-kit-core
   repository: https://github.com/github/spec-kit

specify_cli/core_pack/scripts/powershell/check-prerequisites.ps1

@@ -94,7 +94,7 @@ if ($PathsOnly) {
 }
 
 # Validate required directories and files
-if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
+if (-not (Test-Path -LiteralPath $paths.FEATURE_DIR -PathType Container)) {
     [Console]::Error.WriteLine("ERROR: Feature directory not found: $($paths.FEATURE_DIR)")
     $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
@@ -118,7 +118,7 @@ if ((Get-Item -LiteralPath $paths.IMPL_PLAN).Length -eq 0) {
 }
 
 # Check for spec.md if required
-if ($RequireSpec -and -not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
+if ($RequireSpec -and -not (Test-Path -LiteralPath $paths.FEATURE_SPEC -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")
     $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $specifyCommand first to create the feature specification.")
@@ -126,7 +126,7 @@ if ($RequireSpec -and -not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
 }
 
 # Check for tasks.md if required
-if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
+if ($RequireTasks -and -not (Test-Path -LiteralPath $paths.TASKS -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: tasks.md not found in $($paths.FEATURE_DIR)")
     $tasksCommand = Format-SpecKitCommand -CommandName 'tasks' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $tasksCommand first to create the task list.")
@@ -137,18 +137,18 @@ if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
 $docs = @()
 
 # Always check these optional docs
-if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
-if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }
+if (Test-Path -LiteralPath $paths.RESEARCH) { $docs += 'research.md' }
+if (Test-Path -LiteralPath $paths.DATA_MODEL) { $docs += 'data-model.md' }
 
 # Check contracts directory (only if it exists and has files)
-if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) {
+if ((Test-Path -LiteralPath $paths.CONTRACTS_DIR) -and (Get-ChildItem -LiteralPath $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) {
     $docs += 'contracts/'
 }
 
-if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
+if (Test-Path -LiteralPath $paths.QUICKSTART) { $docs += 'quickstart.md' }
 
 # Include tasks.md if requested and it exists
-if ($IncludeTasks -and (Test-Path $paths.TASKS)) {
+if ($IncludeTasks -and (Test-Path -LiteralPath $paths.TASKS)) {
     $docs += 'tasks.md'
 }
 

specify_cli/core_pack/scripts/powershell/common.ps1

@@ -246,7 +246,7 @@ function Get-FeaturePathsEnv {
 
 function Test-FileExists {
     param([string]$Path, [string]$Description)
-    if (Test-Path -Path $Path -PathType Leaf) {
+    if (Test-Path -LiteralPath $Path -PathType Leaf) {
         Write-Output "  [OK] $Description"
         return $true
     } else {
@@ -263,7 +263,7 @@ function Test-DirHasFiles {
     # only contents are subdirectories (e.g. contracts/v1/openapi.yaml) as
     # non-empty like bash check_dir. Filtering out subdirectories would
     # mis-report such a directory as empty.
-    if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Select-Object -First 1)) {
+    if ((Test-Path -LiteralPath $Path -PathType Container) -and (Get-ChildItem -LiteralPath $Path -ErrorAction SilentlyContinue | Select-Object -First 1)) {
         Write-Output "  [OK] $Description"
         return $true
     } else {

specify_cli/core_pack/scripts/powershell/setup-tasks.ps1

@@ -32,14 +32,14 @@ if (-not $paths) {
     exit 1
 }
 
-if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
+if (-not (Test-Path -LiteralPath $paths.IMPL_PLAN -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
     $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $planCommand first to create the implementation plan.")
     exit 1
 }
 
-if (-not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
+if (-not (Test-Path -LiteralPath $paths.FEATURE_SPEC -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")
     $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
@@ -48,12 +48,12 @@ if (-not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
 
 # Build available docs list
 $docs = @()
-if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
-if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }
-if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) {
+if (Test-Path -LiteralPath $paths.RESEARCH) { $docs += 'research.md' }
+if (Test-Path -LiteralPath $paths.DATA_MODEL) { $docs += 'data-model.md' }
+if ((Test-Path -LiteralPath $paths.CONTRACTS_DIR) -and (Get-ChildItem -LiteralPath $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) {
     $docs += 'contracts/'
 }
-if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
+if (Test-Path -LiteralPath $paths.QUICKSTART) { $docs += 'quickstart.md' }
 
 # Resolve tasks template through override stack
 $tasksTemplate = Resolve-Template -TemplateName 'tasks-template' -RepoRoot $paths.REPO_ROOT

specify_cli/core_pack/scripts/python/check_prerequisites.py

@@ -28,7 +28,8 @@ except ImportError:  # pragma: no cover - direct execution from unusual cwd
 
 
 def _json_line(payload: object) -> str:
-    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    # ASCII escapes keep the JSON intact on a legacy Windows stdout code page.
+    return json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n"
 
 
 HELP_TEXT = """Usage: check_prerequisites.py [OPTIONS]

specify_cli/core_pack/scripts/python/resolve_template.py

@@ -50,7 +50,8 @@ def main(argv: list[str] | None = None) -> int:
                     "TEMPLATE_NAME": args.template_name,
                     "TEMPLATE_CONTENT": content,
                 },
-                ensure_ascii=False,
+                # ASCII escapes keep the JSON intact on a legacy Windows stdout code page.
+                ensure_ascii=True,
                 separators=(",", ":"),
             )
         )

specify_cli/core_pack/scripts/python/setup_plan.py

@@ -23,7 +23,8 @@ except ImportError:  # pragma: no cover - direct execution from unusual cwd
 
 
 def _json_line(payload: object) -> str:
-    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    # ASCII escapes keep the JSON intact on a legacy Windows stdout code page.
+    return json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n"
 
 
 def _help_text(argv0: str) -> str:

specify_cli/core_pack/scripts/python/setup_tasks.py

@@ -29,7 +29,8 @@ except ImportError:  # pragma: no cover - direct execution from unusual cwd
 
 
 def _json_line(payload: object) -> str:
-    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    # ASCII escapes keep the JSON intact on a legacy Windows stdout code page.
+    return json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n"
 
 
 def _help_text(argv0: str) -> str:

specify_cli/events/__init__.py

@@ -14,6 +14,7 @@ API, Typer application, and registration.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import logging
 import os
@@ -1232,17 +1233,6 @@ def _shell_quote(value: str, target_os: str) -> str:
     return shlex.quote(value)
 
 
-def _vibe_target_os() -> str:
-    """Quoting target for Vibe hook commands.
-
-    Vibe launches hooks with ``asyncio.create_subprocess_shell`` — the host's
-    native shell: POSIX ``sh`` on Unix, ``cmd.exe`` (%COMSPEC%) on Windows,
-    where POSIX single-quoting is not quoting at all and an interpreter or
-    dispatcher path containing spaces would split.
-    """
-    return "cmd" if os.name == "nt" else "host"
-
-
 def _dispatcher_command(
     integration: IntegrationBase,
     project_root: Path,
@@ -1356,6 +1346,8 @@ def install_integration_events(
     project_root: Path,
     manifest: IntegrationManifest,
     events: ResolvedEvents,
+    *,
+    force: bool = False,
 ) -> list[Path]:
     """Generate dispatcher, merge native config, return created files.
 
@@ -1388,7 +1380,7 @@ def install_integration_events(
     # new manifest no longer claims it and stale cleanup excludes it).
     if not filtered:
         _remove_native_event_hooks(integration, project_root, manifest)
-        _cleanup_shared_dispatcher(integration, project_root, manifest)
+        _cleanup_shared_dispatcher(integration, project_root, manifest, force=force)
         return []
 
     created: list[Path] = []
@@ -1506,51 +1498,29 @@ def install_integration_events(
             created.append(config_path)
 
     elif fmt == "toml-vibe":
-        # Vibe hooks.toml custom merge. Flat [[hooks]] array; Vibe's
-        # HookConfig schema is name/type/command/match/timeout, with type
-        # limited to "pre_tool" | "post_tool" | "post_agent". Hook names must
-        # be unique (Vibe silently drops duplicates by name), so a per-file
-        # counter suffix disambiguates handlers whose commands share a final
-        # segment (e.g. speckit.a.validate vs speckit.b.validate).
-        lines: list[str] = []
-        used_names: set[str] = set()
-        for ev, handlers in filtered.items():
-            native = canonical_to_native[ev]
-            for cfg in handlers:
-                command = cfg.get("command", "")
-                dispatcher_cmd = _dispatcher_command(
-                    integration, project_root, command, ev,
-                    target_os=_vibe_target_os(),
-                    timeout_seconds=cfg.get("timeout", 60),
-                )
-                command_stem = command.split('.')[-1] if command else "unknown"
-                command_stem = re.sub(r'[^A-Za-z0-9_-]+', '-', command_stem) or "unknown"
-                base_name = f"speckit-{native}-{command_stem}"
-                hook_name = base_name
-                suffix = 2
-                while hook_name in used_names:
-                    hook_name = f"{base_name}-{suffix}"
-                    suffix += 1
-                used_names.add(hook_name)
-                lines.append("[[hooks]]")
-                lines.append(f'name = {_toml_quote(hook_name)}')
-                lines.append(f'type = {_toml_quote(native)}')
-                # Vibe's field is `match` (fnmatch glob, or `re:`-prefixed
-                # regex, case-insensitive) and it is only valid on tool
-                # hooks — HookConfig rejects `match` on post_agent. Canonical
-                # matchers are Claude-style regexes ("Edit|Write"), so
-                # non-wildcard matchers are emitted as `re:` patterns.
-                matcher = cfg.get("matcher", "*")
-                if matcher and matcher != "*" and native in ("pre_tool", "post_tool"):
-                    lines.append(f'match = {_toml_quote("re:" + matcher)}')
-                lines.append(f'command = {_toml_quote(dispatcher_cmd)}')
-                lines.append(f'timeout = {_native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER)}')
-                lines.append('speckit_marker = true')
-                lines.append('')
-        # S5: only track when the merge wrote (skips on unreadable file).
-        if _merge_vibe_toml_fragment(config_path, "\n".join(lines)):
-            rel = str(config_path.relative_to(project_root))
-            manifest.record_existing(rel, ownership="partial")
+        # Vibe owns its native TOML schema and its managed-entry boundaries.
+        # Shared events deliberately supplies only dispatcher construction and
+        # manifest handling, keeping this a narrow integration-specific seam.
+        merge_vibe_hooks = getattr(integration, "merge_vibe_event_hooks", None)
+        if not callable(merge_vibe_hooks):
+            raise TypeError("toml-vibe integrations must implement merge_vibe_event_hooks")
+        if merge_vibe_hooks(
+            project_root,
+            filtered,
+            build_dispatcher_command=lambda command, event, target_os, timeout: _dispatcher_command(
+                integration,
+                project_root,
+                command,
+                event,
+                target_os=target_os,
+                timeout_seconds=timeout,
+            ),
+            native_timeout=lambda seconds: _native_timeout(integration, seconds),
+            ensure_safe_destination=_ensure_safe_destination,
+        ):
+            rel = config_path.relative_to(project_root).as_posix()
+            manifest.record_existing(rel)
+            manifest.set_ownership(rel, "partial")
             created.append(config_path)
 
     elif fmt == "json-flat":
@@ -1673,7 +1643,13 @@ def _remove_native_event_hooks(
     elif fmt == "toml":
         _remove_toml_entries(config_path)
     elif fmt == "toml-vibe":
-        _remove_vibe_toml_entries(config_path)
+        remove_vibe_hooks = getattr(integration, "remove_vibe_event_hooks", None)
+        if not callable(remove_vibe_hooks):
+            raise TypeError("toml-vibe integrations must implement remove_vibe_event_hooks")
+        remove_vibe_hooks(
+            project_root,
+            ensure_safe_destination=_ensure_safe_destination,
+        )
     elif fmt in ("json-nested", "json-flat"):
         _remove_json_entries(config_path)
     elif fmt == "json-root-nested":
@@ -1717,51 +1693,74 @@ def _other_event_integrations_reference_dispatcher(
 
 
 def _cleanup_shared_dispatcher(
-    integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest
+    integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest,
+    *,
+    force: bool = False,
 ) -> None:
-    """Drop this integration's manifest claim on the shared dispatcher and
-    delete the file only when no other installed event-capable integration
-    still references it (#10, S3).
-
-    The manifest.remove() runs in both branches (S1): if we retain the file
-    but leave it tracked, the subsequent manifest.uninstall() in teardown()
-    sees the matching hash and deletes the file another integration still
-    depends on. Used by full teardown and by the empty-resolved-map install
-    path so an ``--events false`` upgrade of the last event integration
-    doesn't orphan ``.specify/events.py`` permanently (S3).
-    """
+    """Release this integration's claim; delete only its last managed copy."""
+    from ..integrations.manifest import IntegrationManifest
+
     dispatcher_rel = EVENTS_DISPATCHER_REL
-    # Drop this integration's manifest claim if present. The remove() is
-    # conditional (S1): an upgrade passes a *fresh* manifest that may never
-    # have claimed the dispatcher, so the key may be absent — that's a no-op.
+    owner = manifest
+    # Upgrades emit into a fresh manifest before replacing the installed one.
+    # Only this integration's prior manifest can supply its missing claim.
+    if dispatcher_rel not in owner.files:
+        try:
+            owner = IntegrationManifest.load(integration.key, project_root)
+        except FileNotFoundError:
+            owner = manifest
+        except (OSError, ValueError) as exc:
+            logger.warning(
+                "Could not read prior dispatcher manifest for '%s'; preserving %s: %s",
+                integration.key, project_root / dispatcher_rel, exc,
+            )
+            return
+    expected_hash = owner.files.get(dispatcher_rel)
+    recovered = owner.is_recovered(dispatcher_rel)
+    partial = owner.ownership_modes.get(dispatcher_rel) == "partial"
+
+    # Release even retained claims so manifest-only teardown cannot delete a
+    # user-owned copy or a dispatcher still used by another integration.
     if dispatcher_rel in manifest.files:
         manifest.remove(dispatcher_rel)
-    # S2: run the no-other-references deletion independently of whether the
-    # new manifest currently contains the key. An ``integration upgrade
-    # --events false`` passes a fresh manifest that never recorded the
-    # dispatcher, so gating the deletion on its presence orphans the file the
-    # old on-disk manifest owned — and stale cleanup excludes it (C3). If no
-    # other installed event-capable integration references the dispatcher,
-    # delete it; otherwise leave it for them.
-    if not _other_event_integrations_reference_dispatcher(project_root, integration.key):
-        dispatcher_path = project_root / dispatcher_rel
-        if dispatcher_path.exists():
-            _ensure_safe_destination(dispatcher_path)
-            _unlink_file(dispatcher_path, missing_ok=True)
+    if not expected_hash or recovered or partial:
+        return
+    if _other_event_integrations_reference_dispatcher(project_root, integration.key):
+        return
+    dispatcher_path = project_root / dispatcher_rel
+    if dispatcher_path.exists():
+        _ensure_safe_destination(dispatcher_path)
+        if not force:
+            try:
+                content = dispatcher_path.read_bytes()
+            except OSError as exc:
+                logger.warning("Preserving unreadable dispatcher %s: %s", dispatcher_path, exc)
+                return
+            # Another integration may have regenerated the shared file since
+            # this manifest recorded it. Accept only exact generated LF/CRLF.
+            matches = hashlib.sha256(content).hexdigest() == expected_hash or content in (
+                _EVENTS_DISPATCHER_TEMPLATE.encode("utf-8"),
+                _EVENTS_DISPATCHER_TEMPLATE.replace("\n", "\r\n").encode("utf-8"),
+            )
+            if not matches:
+                logger.warning("Preserving modified dispatcher: %s", dispatcher_path)
+                return
+        _unlink_file(dispatcher_path, missing_ok=True)
 
 
 def remove_integration_events(
-    integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest
+    integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest,
+    *,
+    force: bool = False,
 ) -> None:
     """Remove Specify-authored event entries from native config.
 
-    The shared ``.specify/events.py`` dispatcher is deleted only when no other
-    installed event-capable integration still references it (#10); otherwise
-    it is left in place so multi-install setups don't lose the dispatcher
-    mid-stream.
+    The shared dispatcher is deleted only if this integration owns it and no
+    other installed integration references it. Modified copies require force;
+    unowned or recovered copies are always retained.
     """
     _remove_native_event_hooks(integration, project_root, manifest)
-    _cleanup_shared_dispatcher(integration, project_root, manifest)
+    _cleanup_shared_dispatcher(integration, project_root, manifest, force=force)
 
     # Clean up opencode TS plugin (owned solely by the opencode integration).
     if integration.key == "opencode":
@@ -2208,42 +2207,6 @@ def _merge_toml_fragment(dst: Path, fragment: str) -> bool:
     return True
 
 
-def _merge_vibe_toml_fragment(dst: Path, fragment: str) -> bool:
-    """Merge Specify-owned Vibe TOML hook entries into *dst*, regenerating the file.
-
-    Vibe uses a flat [[hooks]] array with type/matcher/command fields.
-    This removes any existing Specify-marked hooks and appends the new fragment.
-    An unreadable or undecodable pre-existing file aborts the merge instead
-    of discarding the user's bytes, mirroring ``_load_user_json`` (#22).
-    Returns False when skipped so callers avoid tracking the untouched file
-    (S5).
-    """
-    _ensure_safe_destination(dst)
-    existing = ""
-    if dst.exists():
-        try:
-            existing = dst.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError) as exc:
-            logger.warning(
-                "Could not read %s (it may be unreadable or not UTF-8); "
-                "skipping event-config merge to preserve user content.",
-                dst,
-            )
-            logger.debug("Read error detail: %s", exc)
-            return False
-    # Remove existing Specify-marked [[hooks]] blocks
-    # Match [[hooks]] ... speckit_marker = true (with any content in between)
-    existing = re.sub(
-        r'\[\[hooks\]\]\n(?:(?!\[\[hooks\]\]).)*?speckit_marker = true\n*',
-        "",
-        existing,
-        flags=re.DOTALL,
-    )
-    dst.parent.mkdir(parents=True, exist_ok=True)
-    _write_text(dst, existing.rstrip() + "\n\n" + fragment + "\n", encoding="utf-8")
-    return True
-
-
 def _remove_toml_entries(dst: Path) -> bool:
     """Remove Specify-marked TOML entries; delete the file if now empty (#14).
 
@@ -2295,43 +2258,6 @@ def _remove_toml_entries(dst: Path) -> bool:
     return False
 
 
-def _remove_vibe_toml_entries(dst: Path) -> bool:
-    """Remove Specify-marked Vibe TOML hook entries; delete the file if now empty.
-
-    Returns True if the file was deleted (no user content remained).
-    """
-    if not dst.exists():
-        return False
-    _ensure_safe_destination(dst)
-    try:
-        existing = dst.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError) as exc:
-        logger.warning(
-            "Could not read %s (it may be unreadable or not UTF-8); "
-            "skipping event-config cleanup to preserve user content.",
-            dst,
-        )
-        logger.debug("Read error detail: %s", exc)
-        return False
-    # Remove Specify-marked [[hooks]] blocks
-    cleaned = re.sub(
-        r'\[\[hooks\]\]\n(?:(?!\[\[hooks\]\]).)*?speckit_marker = true\n*',
-        "",
-        existing,
-        flags=re.DOTALL,
-    )
-    # If only whitespace/comments remain, the file had no user content
-    stripped = "\n".join(
-        line for line in cleaned.splitlines()
-        if line.strip() and not line.strip().startswith("#")
-    )
-    if not stripped:
-        _unlink_file(dst, missing_ok=True)
-        return True
-    _write_text(dst, cleaned, encoding="utf-8")
-    return False
-
-
 def _merge_copilot_json(dst: Path, new_hooks: dict[str, list]) -> bool:
     """Merge Specify-owned hooks into Copilot's dedicated hooks JSON (#8).