chore: bump version to 0.9.1

.editorconfig

@@ -1,28 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-charset = utf-8
-indent_style = space
-indent_size = 4
-
-[*.{yml,yaml}]
-indent_size = 2
-
-[*.{json,jsonc}]
-indent_size = 2
-
-[*.md]
-indent_size = 2
-trim_trailing_whitespace = false
-
-[*.{sh,bash}]
-indent_size = 4
-
-[*.{ps1,psm1,psd1}]
-indent_size = 4
-
-[Makefile]
-indent_style = tab

CHANGELOG.md

@@ -2,20 +2,6 @@
 
 <!-- insert new changelog below this comment -->
 
-## [0.9.2] - 2026-06-02
-
-### Changed
-
-- Update agent parity governance preset catalog entry (#2777)
-- fix: resolve GitHub release asset API URL for private repo extension downloads (#2792)
-- fix: remove unsupported mode: frontmatter from Copilot skills mode (fixes #2799) (#2819)
-- refactor(integrations): co-locate integration commands in integrations/ domain dir (PR-5/8) (#2720)
-- Update Product Forge extension to v1.6.0 (#2820)
-- feat(workflows): add continue_on_error step field for non-halting failures (#2663)
-- chore: add .editorconfig for consistent code formatting (#2366)
-- fix(shared-infra): record skipped files in speckit.manifest.json (#2483)
-- chore: release 0.9.1, begin 0.9.2.dev0 development (#2818)
-
 ## [0.9.1] - 2026-06-02
 
 ### Changed

docs/community/extensions.md

@@ -79,7 +79,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | Plan Review Gate | Require spec.md and plan.md to be merged via MR/PR before allowing task generation | `process` | Read-only | [spec-kit-plan-review-gate](https://github.com/luno/spec-kit-plan-review-gate) |
 | PR Bridge | Auto-generate pull request descriptions, checklists, and summaries from spec artifacts | `process` | Read-only | [spec-kit-pr-bridge-](https://github.com/Quratulain-bilal/spec-kit-pr-bridge-) |
 | Presetify | Create and validate presets and preset catalogs | `process` | Read+Write | [presetify](https://github.com/mnriem/spec-kit-extensions/tree/main/presetify) |
-| Product Forge | Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
+| Product Forge | Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
 | Product Spec Extension | Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs | `docs` | Read+Write | [spec-kit-product](https://github.com/d0whc3r/spec-kit-product) |
 | Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | `visibility` | Read-only | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
 | Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | `visibility` | Read-only | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |

docs/community/presets.md

@@ -8,7 +8,7 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | Preset | Purpose | Provides | Requires | URL |
 |--------|---------|----------|----------|-----|
 | A11Y Governance | Adds WCAG 2.2 AA accessibility checks, bilingual DE/EN delivery, CEFR-B2 readability, CLI accessibility, and inclusive-content guidance | 9 templates, 3 commands | — | [spec-kit-preset-a11y-governance](https://github.com/hindermath/spec-kit-preset-a11y-governance) |
-| Agent Parity Governance | Keeps shared AI-agent instructions aligned and adds agent-neutral Spec Kit model-routing guidance across project-defined agent guidance surfaces | 9 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
+| Agent Parity Governance | Keeps shared AI-agent instructions aligned across project-defined agent guidance surfaces and documents intentional deviations | 6 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
 | AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
 | Architecture Governance | Adds secure architecture governance: trust boundaries, threat modeling, STRIDE/CAPEC, S-ADRs, Zero Trust applicability, and OWASP SAMM | 11 templates, 3 commands | — | [spec-kit-preset-architecture-governance](https://github.com/hindermath/spec-kit-preset-architecture-governance) |
 | Canon Core | Adapts original Spec Kit workflow to work together with Canon extension | 2 templates, 8 commands | — | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon) |

extensions/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-06-02T00:00:00Z",
+  "updated_at": "2026-06-01T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
   "extensions": {
     "aide": {
@@ -2055,10 +2055,10 @@
     "product-forge": {
       "name": "Product Forge",
       "id": "product-forge",
-      "description": "Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies",
+      "description": "Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model",
       "author": "VaiYav",
-      "version": "1.6.0",
-      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.6.0.zip",
+      "version": "1.5.1",
+      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.5.1.zip",
       "repository": "https://github.com/VaiYav/speckit-product-forge",
       "homepage": "https://github.com/VaiYav/speckit-product-forge",
       "documentation": "https://github.com/VaiYav/speckit-product-forge/blob/main/README.md",
@@ -2068,7 +2068,7 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 31,
+        "commands": 29,
         "hooks": 0
       },
       "tags": [
@@ -2082,7 +2082,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-28T00:00:00Z",
-      "updated_at": "2026-06-02T00:00:00Z"
+      "updated_at": "2026-04-24T15:52:00Z"
     },
     "qa": {
       "name": "QA Testing Extension",

presets/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-05-31T00:00:00Z",
+  "updated_at": "2026-05-28T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
   "presets": {
     "a11y-governance": {
@@ -34,11 +34,11 @@
     "agent-parity-governance": {
       "name": "Agent Parity Governance",
       "id": "agent-parity-governance",
-      "version": "0.2.0",
-      "description": "Keeps shared AI-agent guidance aligned and adds agent-neutral Spec Kit model-routing guidance across declared agent instruction surfaces.",
+      "version": "0.1.0",
+      "description": "Keeps shared AI-agent guidance aligned across a project-defined set of agent instruction surfaces.",
       "author": "Thorsten Hindermann",
       "repository": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
-      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.2.0.zip",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.1.0.zip",
       "homepage": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
       "documentation": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/blob/main/README.md",
       "license": "MIT",
@@ -46,20 +46,18 @@
         "speckit_version": ">=0.8.0"
       },
       "provides": {
-        "templates": 9,
+        "templates": 6,
         "commands": 3
       },
       "tags": [
         "agents",
         "governance",
         "parity",
-        "agent-md",
         "agent-guidance",
-        "model-routing",
         "multi-agent"
       ],
       "created_at": "2026-04-27T00:00:00Z",
-      "updated_at": "2026-05-31T00:00:00Z"
+      "updated_at": "2026-04-27T00:00:00Z"
     },
     "aide-in-place": {
       "name": "AIDE In-Place Migration",

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.9.2"
+version = "0.9.1"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

src/specify_cli/commands/extension.py

@@ -0,0 +1,2 @@
+"""specify extension * commands — placeholder for future extraction."""
+from __future__ import annotations

src/specify_cli/commands/init.py

@@ -151,15 +151,13 @@ def register(app: typer.Typer) -> None:
         # Lazy imports to avoid circular dependency — __init__.py imports this module
         from .. import (
             _install_shared_infra_or_exit,
+            _parse_integration_options,
             _print_cli_warning,
             _update_agent_context_config_file,
+            _write_integration_json,
             ensure_executable_scripts,
             save_init_options,
         )
-        from ..integrations._commands import (
-            _parse_integration_options,
-            _write_integration_json,
-        )
         from ..integration_runtime import with_integration_setting as _with_integration_setting
 
         show_banner()

src/specify_cli/commands/integration.py

@@ -0,0 +1,2 @@
+"""specify integration * commands — placeholder for future extraction."""
+from __future__ import annotations

src/specify_cli/commands/preset.py

@@ -0,0 +1,2 @@
+"""specify preset * commands — placeholder for future extraction."""
+from __future__ import annotations

src/specify_cli/commands/workflow.py

@@ -0,0 +1,2 @@
+"""specify workflow * commands — placeholder for future extraction."""
+from __future__ import annotations

src/specify_cli/extensions.py

@@ -1749,59 +1749,13 @@ class ExtensionCatalog(CatalogStackBase):
         from specify_cli.authentication.http import build_request
         return build_request(url)
 
-    def _open_url(
-        self,
-        url: str,
-        timeout: int = 10,
-        extra_headers: Optional[Dict[str, str]] = None,
-    ):
+    def _open_url(self, url: str, timeout: int = 10):
         """Open a URL with provider-based auth, trying each configured provider.
 
         Delegates to :func:`specify_cli.authentication.http.open_url`.
         """
         from specify_cli.authentication.http import open_url
-        return open_url(url, timeout, extra_headers=extra_headers)
-
-    def _resolve_github_release_asset_api_url(
-        self,
-        download_url: str,
-        timeout: int = 60,
-    ) -> Optional[str]:
-        """Resolve a GitHub release asset URL to its API asset URL."""
-        import urllib.error
-        from urllib.parse import unquote, urlparse
-
-        parsed = urlparse(download_url)
-        parts = [unquote(part) for part in parsed.path.strip("/").split("/")]
-        if (
-            parsed.hostname == "api.github.com"
-            and len(parts) >= 6
-            and parts[:1] == ["repos"]
-            and parts[3:5] == ["releases", "assets"]
-        ):
-            return download_url
-
-        if parsed.hostname != "github.com":
-            return None
-
-        if len(parts) < 6 or parts[2:4] != ["releases", "download"]:
-            return None
-
-        owner, repo, tag = parts[0], parts[1], parts[4]
-        asset_name = "/".join(parts[5:])
-        release_url = f"https://api.github.com/repos/{owner}/{repo}/releases/tags/{tag}"
-
-        try:
-            with self._open_url(release_url, timeout=timeout) as response:
-                release_data = json.loads(response.read())
-        except (urllib.error.URLError, json.JSONDecodeError):
-            return None
-
-        for asset in release_data.get("assets", []):
-            if asset.get("name") == asset_name and asset.get("url"):
-                return str(asset["url"])
-
-        return None
+        return open_url(url, timeout)
 
     def get_active_catalogs(self) -> List[CatalogEntry]:
         """Get the ordered list of active catalogs.
@@ -2201,15 +2155,9 @@ class ExtensionCatalog(CatalogStackBase):
         zip_filename = f"{extension_id}-{version}.zip"
         zip_path = target_dir / zip_filename
 
-        extra_headers = None
-        resolved_download_url = self._resolve_github_release_asset_api_url(download_url)
-        if resolved_download_url:
-            download_url = resolved_download_url
-            extra_headers = {"Accept": "application/octet-stream"}
-
         # Download the ZIP file
         try:
-            with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:
+            with self._open_url(download_url, timeout=60) as response:
                 zip_data = response.read()
 
             zip_path.write_bytes(zip_data)

src/specify_cli/integrations/_commands.py

@@ -1,34 +0,0 @@
-"""specify integration * commands — app objects and register() entry point."""
-from __future__ import annotations
-
-import typer
-
-from .._assets import get_speckit_version  # noqa: F401 — re-exported for monkeypatching in tests
-
-# Re-export helpers used by commands/init.py and tests
-from ._helpers import (  # noqa: F401
-    _cli_error_detail,
-    _cli_phase_label,
-    _parse_integration_options,
-    _write_integration_json,
-)
-
-integration_app = typer.Typer(
-    name="integration",
-    help="Manage coding agent integrations",
-    add_completion=False,
-)
-
-integration_catalog_app = typer.Typer(
-    name="catalog",
-    help="Manage integration catalog sources",
-    add_completion=False,
-)
-integration_app.add_typer(integration_catalog_app, name="catalog")
-
-
-def register(app: typer.Typer) -> None:
-    from . import _install_commands  # noqa: F401 — registers handlers via decorators
-    from . import _migrate_commands  # noqa: F401
-    from . import _query_commands    # noqa: F401
-    app.add_typer(integration_app, name="integration")

src/specify_cli/integrations/_helpers.py

@@ -1,402 +0,0 @@
-"""specify integration helpers — internal utilities shared across command modules."""
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Any
-
-import typer
-
-from .._agent_config import SCRIPT_TYPE_CHOICES
-from .._console import console
-from ..integration_runtime import (
-    invoke_separator_for_integration as _invoke_separator_for_integration,
-    resolve_integration_options as _resolve_integration_options_impl,
-    with_integration_setting as _with_integration_setting,
-)
-from ..integration_state import (
-    INTEGRATION_JSON,
-    INTEGRATION_STATE_SCHEMA,
-    integration_setting as _integration_setting,
-    try_read_integration_json as _try_read_integration_json,
-    write_integration_json as _write_integration_json_file,
-)
-
-
-def _get_speckit_version() -> str:
-    """Return the current Spec Kit version.
-
-    Resolved lazily through ``_commands.get_speckit_version`` so that tests
-    that monkeypatch ``specify_cli.integrations._commands.get_speckit_version``
-    still affect helpers called from the command handlers.
-    """
-    from . import _commands  # noqa: PLC0415 — intentional late import to avoid circular + enable patching
-    return _commands.get_speckit_version()
-
-
-# ---------------------------------------------------------------------------
-# JSON read / write helpers
-# ---------------------------------------------------------------------------
-
-def _read_integration_json(project_root: Path) -> dict[str, Any]:
-    """Load ``.specify/integration.json``. Returns normalized state when present.
-
-    Delegates the parse / schema-guard logic to the shared
-    :func:`_try_read_integration_json` helper so the CLI and workflow engine
-    cannot drift on validation rules. Each error variant is translated into
-    the existing loud-fail UX (console message + ``typer.Exit(1)``).
-    """
-    path = project_root / INTEGRATION_JSON
-    state, error = _try_read_integration_json(project_root)
-    if error is None:
-        return state or {}
-    if error.kind == "decode":
-        console.print(f"[red]Error:[/red] {path} contains invalid JSON or is not valid UTF-8.")
-        console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
-        console.print(f"[dim]Details:[/dim] {error.detail}")
-    elif error.kind == "os":
-        console.print(f"[red]Error:[/red] Could not read {path}.")
-        console.print(f"Please fix file permissions or delete {INTEGRATION_JSON} and retry.")
-        console.print(f"[dim]Details:[/dim] {error.detail}")
-    elif error.kind == "not_object":
-        console.print(
-            f"[red]Error:[/red] {path} must contain a JSON object, got {error.detail}."
-        )
-        console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
-    elif error.kind == "schema_too_new":
-        console.print(
-            f"[red]Error:[/red] {path} uses integration state schema {error.schema}, "
-            f"but this CLI only supports schema {INTEGRATION_STATE_SCHEMA}."
-        )
-        console.print("Please upgrade Spec Kit before modifying integrations.")
-    raise typer.Exit(1)
-
-
-def _write_integration_json(
-    project_root: Path,
-    integration_key: str | None,
-    installed_integrations: list[str] | None = None,
-    integration_settings: dict[str, dict[str, Any]] | None = None,
-) -> None:
-    """Write ``.specify/integration.json`` with legacy-compatible state."""
-    _write_integration_json_file(
-        project_root,
-        version=_get_speckit_version(),
-        integration_key=integration_key,
-        installed_integrations=installed_integrations,
-        settings=integration_settings,
-    )
-
-
-# ---------------------------------------------------------------------------
-# init-options.json helpers
-# ---------------------------------------------------------------------------
-
-def _refresh_init_options_speckit_version(project_root: Path) -> None:
-    """Refresh only the Spec Kit version recorded in init-options.json."""
-    from .. import load_init_options, save_init_options
-    opts = load_init_options(project_root)
-    if not isinstance(opts, dict) or not opts:
-        return
-    opts["speckit_version"] = _get_speckit_version()
-    save_init_options(project_root, opts)
-
-
-def _clear_init_options_for_integration(project_root: Path, integration_key: str) -> None:
-    """Clear active integration keys from init-options.json when they match.
-
-    Also clears ``context_file`` from the agent-context extension config so
-    no stale path is left behind when the integration is uninstalled.
-    """
-    from .. import (
-        _AGENT_CTX_EXT_CONFIG,
-        _update_agent_context_config_file,
-        load_init_options,
-        save_init_options,
-    )
-    opts = load_init_options(project_root)
-    has_legacy_context_keys = ("context_file" in opts) or ("context_markers" in opts)
-    # Remove legacy fields that older versions may have written.
-    opts.pop("context_file", None)
-    opts.pop("context_markers", None)
-
-    if opts.get("integration") == integration_key or opts.get("ai") == integration_key:
-        opts.pop("integration", None)
-        opts.pop("ai", None)
-        opts.pop("ai_skills", None)
-        save_init_options(project_root, opts)
-        # Clear context_file in the extension config if it already exists.
-        # Avoid creating the config (and parent dirs) in projects where the
-        # agent-context extension was never installed.
-        ext_cfg_path = project_root / _AGENT_CTX_EXT_CONFIG
-        if ext_cfg_path.exists():
-            _update_agent_context_config_file(
-                project_root, "", preserve_markers=True
-            )
-    elif has_legacy_context_keys:
-        save_init_options(project_root, opts)
-
-
-def _remove_integration_json(project_root: Path) -> None:
-    """Remove ``.specify/integration.json`` if it exists."""
-    path = project_root / INTEGRATION_JSON
-    if path.exists():
-        path.unlink()
-
-
-# ---------------------------------------------------------------------------
-# Error sentinels
-# ---------------------------------------------------------------------------
-
-_MANIFEST_READ_ERRORS = (ValueError, FileNotFoundError, OSError, UnicodeDecodeError)
-
-
-class _SharedTemplateRefreshError(RuntimeError):
-    """Raised when default integration metadata should not be persisted."""
-
-
-# ---------------------------------------------------------------------------
-# Script type resolution
-# ---------------------------------------------------------------------------
-
-def _normalize_script_type(script_type: str, source: str) -> str:
-    """Normalize and validate a script type from CLI/config sources."""
-    normalized = script_type.strip().lower()
-    if normalized in SCRIPT_TYPE_CHOICES:
-        return normalized
-    console.print(
-        f"[red]Error:[/red] Invalid script type {script_type!r} from {source}. "
-        f"Expected one of: {', '.join(sorted(SCRIPT_TYPE_CHOICES.keys()))}."
-    )
-    raise typer.Exit(1)
-
-
-def _resolve_script_type(project_root: Path, script_type: str | None) -> str:
-    """Resolve the script type from the CLI flag or init-options.json."""
-    from .. import load_init_options
-    if script_type:
-        return _normalize_script_type(script_type, "--script")
-    opts = load_init_options(project_root)
-    saved = opts.get("script")
-    if isinstance(saved, str) and saved.strip():
-        return _normalize_script_type(saved, ".specify/init-options.json")
-    return "ps" if os.name == "nt" else "sh"
-
-
-def _resolve_integration_script_type(
-    project_root: Path,
-    state: dict[str, Any],
-    key: str,
-    script_type: str | None = None,
-) -> str:
-    """Resolve script type for an integration, preferring stored settings."""
-    if script_type:
-        return _normalize_script_type(script_type, "--script")
-
-    stored = _integration_setting(state, key).get("script")
-    if isinstance(stored, str) and stored.strip():
-        return _normalize_script_type(stored, f"{INTEGRATION_JSON} integration_settings.{key}.script")
-
-    return _resolve_script_type(project_root, None)
-
-
-# ---------------------------------------------------------------------------
-# Integration options
-# ---------------------------------------------------------------------------
-
-def _parse_integration_options(integration: Any, raw_options: str) -> dict[str, Any] | None:
-    """Parse --integration-options string into a dict matching the integration's declared options.
-
-    Returns ``None`` when no options are provided.
-    """
-    import shlex
-    parsed: dict[str, Any] = {}
-    tokens = shlex.split(raw_options)
-    declared_options = list(integration.options())
-    declared = {opt.name.lstrip("-"): opt for opt in declared_options}
-    allowed = ", ".join(sorted(opt.name for opt in declared_options))
-    i = 0
-    while i < len(tokens):
-        token = tokens[i]
-        if not token.startswith("-"):
-            console.print(f"[red]Error:[/red] Unexpected integration option value '{token}'.")
-            if allowed:
-                console.print(f"Allowed options: {allowed}")
-            raise typer.Exit(1)
-        name = token.lstrip("-")
-        value: str | None = None
-        # Handle --name=value syntax
-        if "=" in name:
-            name, value = name.split("=", 1)
-        opt = declared.get(name)
-        if not opt:
-            console.print(f"[red]Error:[/red] Unknown integration option '{token}'.")
-            if allowed:
-                console.print(f"Allowed options: {allowed}")
-            raise typer.Exit(1)
-        key = name.replace("-", "_")
-        if opt.is_flag:
-            if value is not None:
-                console.print(f"[red]Error:[/red] Option '{opt.name}' is a flag and does not accept a value.")
-                raise typer.Exit(1)
-            parsed[key] = True
-            i += 1
-        elif value is not None:
-            parsed[key] = value
-            i += 1
-        elif i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
-            parsed[key] = tokens[i + 1]
-            i += 2
-        else:
-            console.print(f"[red]Error:[/red] Option '{opt.name}' requires a value.")
-            raise typer.Exit(1)
-    return parsed or None
-
-
-def _resolve_integration_options(
-    integration: Any,
-    state: dict[str, Any],
-    key: str,
-    raw_options: str | None,
-) -> tuple[str | None, dict[str, Any] | None]:
-    """Resolve raw and parsed options for an integration operation."""
-    return _resolve_integration_options_impl(
-        integration,
-        state,
-        key,
-        raw_options,
-        parse_options=_parse_integration_options,
-    )
-
-
-def _update_init_options_for_integration(
-    project_root: Path,
-    integration: Any,
-    script_type: str | None = None,
-) -> None:
-    """Update init-options.json and the agent-context extension config to
-    reflect *integration* as the active one.
-
-    ``context_file`` and ``context_markers`` are stored in the agent-context
-    extension config (``.specify/extensions/agent-context/agent-context-config.yml``),
-    not in ``init-options.json``.  Existing user-customised markers are
-    always preserved when the config already exists; invalid marker values
-    are silently ignored at runtime by ``_resolve_context_markers()`` which
-    falls back to the class-level defaults.
-    """
-    from .. import (
-        _AGENT_CTX_EXT_CONFIG,
-        _update_agent_context_config_file,
-        load_init_options,
-        save_init_options,
-    )
-    from .base import SkillsIntegration
-    opts = load_init_options(project_root)
-    opts["integration"] = integration.key
-    opts["ai"] = integration.key
-    # Remove legacy fields if they were written by an older version.
-    opts.pop("context_file", None)
-    opts.pop("context_markers", None)
-    opts["speckit_version"] = _get_speckit_version()
-    if script_type:
-        opts["script"] = script_type
-    if isinstance(integration, SkillsIntegration) or getattr(integration, "_skills_mode", False):
-        opts["ai_skills"] = True
-    else:
-        opts.pop("ai_skills", None)
-
-    # Update the agent-context extension config BEFORE init-options.json
-    # so a failure here doesn't leave init-options partially updated.
-    ext_cfg_path = project_root / _AGENT_CTX_EXT_CONFIG
-    if ext_cfg_path.exists():
-        _update_agent_context_config_file(
-            project_root,
-            integration.context_file,
-            preserve_markers=True,
-        )
-    elif integration.context_file:
-        # Extension config doesn't exist yet (extension not installed).
-        # Write defaults so scripts have something to read.
-        _update_agent_context_config_file(
-            project_root,
-            integration.context_file,
-            preserve_markers=False,
-        )
-
-    save_init_options(project_root, opts)
-
-
-# ---------------------------------------------------------------------------
-# Default integration persistence
-# ---------------------------------------------------------------------------
-
-def _set_default_integration(
-    project_root: Path,
-    state: dict[str, Any],
-    key: str,
-    integration: Any,
-    installed_keys: list[str],
-    *,
-    script_type: str | None = None,
-    raw_options: str | None = None,
-    parsed_options: dict[str, Any] | None = None,
-    refresh_templates: bool = True,
-    refresh_templates_force: bool = False,
-    refresh_hint: str | None = None,
-) -> None:
-    """Persist *key* as default and align active runtime metadata."""
-    from .. import _install_shared_infra
-    resolved_script = _resolve_integration_script_type(project_root, state, key, script_type)
-    settings = _with_integration_setting(
-        state,
-        key,
-        integration,
-        script_type=resolved_script,
-        raw_options=raw_options,
-        parsed_options=parsed_options,
-    )
-
-    if refresh_templates:
-        try:
-            _install_shared_infra(
-                project_root,
-                resolved_script,
-                invoke_separator=_invoke_separator_for_integration(
-                    integration, {"integration_settings": settings}, key, parsed_options
-                ),
-                force=refresh_templates_force,
-                refresh_managed=True,
-                refresh_hint=refresh_hint,
-            )
-        except (ValueError, OSError) as exc:
-            raise _SharedTemplateRefreshError(
-                f"Failed to refresh shared infrastructure for '{key}': {exc}"
-            ) from exc
-
-    _write_integration_json(project_root, key, installed_keys, settings)
-    _update_init_options_for_integration(project_root, integration, script_type=resolved_script)
-
-
-def _set_default_integration_or_exit(*args: Any, **kwargs: Any) -> None:
-    try:
-        _set_default_integration(*args, **kwargs)
-    except _SharedTemplateRefreshError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        raise typer.Exit(1)
-
-
-# ---------------------------------------------------------------------------
-# CLI formatting helpers (re-exported from _commands.py)
-# ---------------------------------------------------------------------------
-
-def _cli_error_detail(exc: BaseException) -> str:
-    """Return a compact one-line exception detail for CLI output."""
-    return str(exc).replace("\n", " ").strip() or exc.__class__.__name__
-
-
-def _cli_phase_label(phase: str, target_kind: str, target: str | None = None) -> str:
-    """Format a stable operation label for user-visible diagnostics."""
-    label = f"{phase} {target_kind}".strip()
-    if target:
-        label = f"{label} '{target}'"
-    return label

src/specify_cli/integrations/_install_commands.py

@@ -1,309 +0,0 @@
-"""specify integration install / uninstall command handlers."""
-from __future__ import annotations
-
-import os
-
-import typer
-
-from .._console import console
-from .._utils import _display_project_path
-from ..integration_runtime import (
-    invoke_separator_for_integration as _invoke_separator_for_integration,
-    with_integration_setting as _with_integration_setting,
-)
-from ..integration_state import (
-    dedupe_integration_keys as _dedupe_integration_keys,
-    default_integration_key as _default_integration_key,
-    installed_integration_keys as _installed_integration_keys,
-    integration_settings as _integration_settings,
-)
-from ._commands import integration_app
-from ._helpers import (
-    _MANIFEST_READ_ERRORS,
-    _clear_init_options_for_integration,
-    _cli_error_detail,
-    _cli_phase_label,
-    _get_speckit_version,
-    _read_integration_json,
-    _refresh_init_options_speckit_version,
-    _remove_integration_json,
-    _resolve_integration_options,
-    _resolve_script_type,
-    _set_default_integration_or_exit,
-    _update_init_options_for_integration,
-    _write_integration_json,
-)
-
-
-@integration_app.command("install")
-def integration_install(
-    key: str = typer.Argument(help="Integration key to install (e.g. claude, copilot)"),
-    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
-    force: bool = typer.Option(False, "--force", help="Allow multi-install when integrations are not declared safe"),
-    integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")'),
-):
-    """Install an integration into an existing project."""
-    from . import INTEGRATION_REGISTRY, get_integration
-    from .manifest import IntegrationManifest
-    from .. import _require_specify_project, _install_shared_infra_or_exit
-
-    project_root = _require_specify_project()
-    integration = get_integration(key)
-    if integration is None:
-        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
-        available = ", ".join(sorted(INTEGRATION_REGISTRY.keys()))
-        console.print(f"Available integrations: {available}")
-        raise typer.Exit(1)
-
-    current = _read_integration_json(project_root)
-    default_key = _default_integration_key(current)
-    installed_keys = _installed_integration_keys(current)
-
-    if key in installed_keys:
-        console.print(f"[yellow]Integration '{key}' is already installed.[/yellow]")
-        if default_key == key:
-            console.print("It is already the default integration.")
-        else:
-            console.print(
-                f"To make it the default integration, run "
-                f"[cyan]specify integration use {key}[/cyan]."
-            )
-        console.print(
-            f"To refresh its managed files or options, run "
-            f"[cyan]specify integration upgrade {key}[/cyan]."
-        )
-        console.print("No files were changed.")
-        raise typer.Exit(0)
-
-    if installed_keys and not force:
-        unsafe_keys = []
-        for installed_key in installed_keys:
-            installed_integration = get_integration(installed_key)
-            if not installed_integration or not getattr(installed_integration, "multi_install_safe", False):
-                unsafe_keys.append(installed_key)
-        if unsafe_keys or not getattr(integration, "multi_install_safe", False):
-            console.print(
-                f"[red]Error:[/red] Installed integrations: {', '.join(installed_keys)}."
-            )
-            if default_key:
-                console.print(f"Default integration: [cyan]{default_key}[/cyan].")
-            console.print(
-                "Installing multiple integrations is only automatic when all involved "
-                "integrations are declared multi-install safe."
-            )
-            console.print(
-                f"To replace the default integration, run "
-                f"[cyan]specify integration switch {key}[/cyan]."
-            )
-            console.print(
-                f"To install '{key}' alongside the existing integrations anyway, "
-                "retry the same install command with [cyan]--force[/cyan]."
-            )
-            raise typer.Exit(1)
-
-    selected_script = _resolve_script_type(project_root, script)
-
-    # Build parsed options from --integration-options so the integration
-    # can determine its effective invoke separator before shared infra
-    # is installed.
-    raw_options, parsed_options = _resolve_integration_options(
-        integration, current, key, integration_options
-    )
-
-    # Ensure shared infrastructure is present (safe to run unconditionally;
-    # _install_shared_infra merges missing files without overwriting).
-    infra_integration = integration
-    infra_key = key
-    infra_parsed = parsed_options
-    if default_key:
-        default_integration = get_integration(default_key)
-        if default_integration is not None:
-            infra_integration = default_integration
-            infra_key = default_key
-            _, infra_parsed = _resolve_integration_options(
-                default_integration, current, default_key, None
-            )
-    _install_shared_infra_or_exit(
-        project_root,
-        selected_script,
-        invoke_separator=_invoke_separator_for_integration(
-            infra_integration, current, infra_key, infra_parsed
-        ),
-    )
-    if os.name != "nt":
-        from .. import ensure_executable_scripts
-        ensure_executable_scripts(project_root)
-
-    manifest = IntegrationManifest(
-        integration.key, project_root, version=_get_speckit_version()
-    )
-
-    try:
-        integration.setup(
-            project_root, manifest,
-            parsed_options=parsed_options,
-            script_type=selected_script,
-            raw_options=raw_options,
-        )
-        manifest.save()
-        new_installed = _dedupe_integration_keys([*installed_keys, integration.key])
-        new_default = default_key or integration.key
-        settings = _with_integration_setting(
-            current,
-            integration.key,
-            integration,
-            script_type=selected_script,
-            raw_options=raw_options,
-            parsed_options=parsed_options,
-        )
-        _write_integration_json(project_root, new_default, new_installed, settings)
-        if new_default == integration.key:
-            _update_init_options_for_integration(project_root, integration, script_type=selected_script)
-        else:
-            _refresh_init_options_speckit_version(project_root)
-
-    except Exception as exc:
-        # Attempt rollback of any files written by setup
-        try:
-            integration.teardown(project_root, manifest, force=True)
-        except Exception as rollback_err:
-            # Suppress so the original setup error remains the primary failure
-            from .. import _print_cli_warning
-            _print_cli_warning(
-                "rollback",
-                "integration",
-                key,
-                rollback_err,
-                continuing="The original install failure is still the primary error.",
-            )
-        if installed_keys:
-            _write_integration_json(
-                project_root, default_key, installed_keys, _integration_settings(current)
-            )
-        else:
-            _remove_integration_json(project_root)
-        console.print(
-            f"[red]Error:[/red] Failed to {_cli_phase_label('install', 'integration', key)}: "
-            f"{_cli_error_detail(exc)}"
-        )
-        raise typer.Exit(1)
-
-    name = (integration.config or {}).get("name", key)
-    console.print(f"\n[green]✓[/green] Integration '{name}' installed successfully")
-    if default_key:
-        console.print(f"[dim]Default integration remains:[/dim] [cyan]{default_key}[/cyan]")
-
-
-@integration_app.command("uninstall")
-def integration_uninstall(
-    key: str = typer.Argument(None, help="Integration key to uninstall (default: current integration)"),
-    force: bool = typer.Option(False, "--force", help="Remove files even if modified"),
-):
-    """Uninstall an integration, safely preserving modified files."""
-    from . import get_integration
-    from .manifest import IntegrationManifest
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    current = _read_integration_json(project_root)
-    default_key = _default_integration_key(current)
-    installed_keys = _installed_integration_keys(current)
-
-    if key is None:
-        if not default_key:
-            console.print("[yellow]No integration is currently installed.[/yellow]")
-            raise typer.Exit(0)
-        key = default_key
-
-    if key not in installed_keys:
-        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
-        raise typer.Exit(1)
-
-    integration = get_integration(key)
-
-    manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
-    if not manifest_path.exists():
-        console.print(f"[yellow]No manifest found for integration '{key}'. Nothing to uninstall.[/yellow]")
-        remaining = [installed for installed in installed_keys if installed != key]
-        new_default = default_key if default_key != key else (remaining[0] if remaining else None)
-        if remaining:
-            if default_key == key and new_default and (new_integration := get_integration(new_default)):
-                raw_options, parsed_options = _resolve_integration_options(
-                    new_integration, current, new_default, None
-                )
-                _set_default_integration_or_exit(
-                    project_root,
-                    current,
-                    new_default,
-                    new_integration,
-                    remaining,
-                    raw_options=raw_options,
-                    parsed_options=parsed_options,
-                )
-            else:
-                _write_integration_json(
-                    project_root, new_default, remaining, _integration_settings(current)
-                )
-        else:
-            _remove_integration_json(project_root)
-        if default_key == key:
-            _clear_init_options_for_integration(project_root, key)
-        raise typer.Exit(0)
-
-    try:
-        manifest = IntegrationManifest.load(key, project_root)
-    except _MANIFEST_READ_ERRORS as exc:
-        console.print(f"[red]Error:[/red] Integration manifest for '{key}' is unreadable.")
-        console.print(f"Manifest: {manifest_path}")
-        console.print(
-            f"To recover, delete the unreadable manifest, run "
-            f"[cyan]specify integration uninstall {key}[/cyan] to clear stale metadata, "
-            f"then run [cyan]specify integration install {key}[/cyan] to regenerate."
-        )
-        console.print(f"[dim]Details:[/dim] {exc}")
-        raise typer.Exit(1)
-
-    if not integration:
-        console.print(
-            f"[yellow]Warning:[/yellow] Integration '{key}' not found "
-            "in registry. Falling back to manifest-based cleanup."
-        )
-        removed, skipped = manifest.uninstall(project_root, force=force)
-    else:
-        removed, skipped = integration.teardown(project_root, manifest, force=force)
-
-    remaining = [installed for installed in installed_keys if installed != key]
-    new_default = default_key if default_key != key else (remaining[0] if remaining else None)
-    if remaining:
-        if default_key == key and new_default and (new_integration := get_integration(new_default)):
-            raw_options, parsed_options = _resolve_integration_options(
-                new_integration, current, new_default, None
-            )
-            _set_default_integration_or_exit(
-                project_root,
-                current,
-                new_default,
-                new_integration,
-                remaining,
-                raw_options=raw_options,
-                parsed_options=parsed_options,
-            )
-        else:
-            _write_integration_json(
-                project_root, new_default, remaining, _integration_settings(current)
-            )
-    else:
-        _remove_integration_json(project_root)
-
-    if default_key == key:
-        _clear_init_options_for_integration(project_root, key)
-
-    name = (integration.config or {}).get("name", key) if integration else key
-    console.print(f"\n[green]✓[/green] Integration '{name}' uninstalled")
-    if removed:
-        console.print(f"  Removed {len(removed)} file(s)")
-    if skipped:
-        console.print(f"\n[yellow]⚠[/yellow]  {len(skipped)} modified file(s) were preserved:")
-        for path in skipped:
-            rel = _display_project_path(project_root, path)
-            console.print(f"    {rel}")

src/specify_cli/integrations/_migrate_commands.py

@@ -1,490 +0,0 @@
-"""specify integration switch / upgrade command handlers."""
-from __future__ import annotations
-
-import os
-
-import typer
-
-from .._console import console
-from ..integration_runtime import (
-    invoke_separator_for_integration as _invoke_separator_for_integration,
-    with_integration_setting as _with_integration_setting,
-)
-from ..integration_state import (
-    dedupe_integration_keys as _dedupe_integration_keys,
-    default_integration_key as _default_integration_key,
-    installed_integration_keys as _installed_integration_keys,
-    integration_settings as _integration_settings,
-)
-from ._commands import integration_app
-from ._helpers import (
-    _MANIFEST_READ_ERRORS,
-    _SharedTemplateRefreshError,
-    _clear_init_options_for_integration,
-    _cli_error_detail,
-    _cli_phase_label,
-    _get_speckit_version,
-    _read_integration_json,
-    _refresh_init_options_speckit_version,
-    _remove_integration_json,
-    _resolve_integration_options,
-    _resolve_integration_script_type,
-    _resolve_script_type,
-    _set_default_integration,
-    _set_default_integration_or_exit,
-    _update_init_options_for_integration,
-    _write_integration_json,
-)
-
-
-@integration_app.command("switch")
-def integration_switch(
-    target: str = typer.Argument(help="Integration key to switch to"),
-    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
-    force: bool = typer.Option(False, "--force", help="Force removal of modified files during uninstall of the previous integration"),
-    refresh_shared_infra: bool = typer.Option(False, "--refresh-shared-infra", help="Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved)"),
-    integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the target integration'),
-):
-    """Switch from the current integration to a different one."""
-    from . import INTEGRATION_REGISTRY, get_integration
-    from .manifest import IntegrationManifest
-    from .. import _print_cli_warning, _require_specify_project, _install_shared_infra_or_exit
-
-    project_root = _require_specify_project()
-    target_integration = get_integration(target)
-    if target_integration is None:
-        console.print(f"[red]Error:[/red] Unknown integration '{target}'")
-        available = ", ".join(sorted(INTEGRATION_REGISTRY.keys()))
-        console.print(f"Available integrations: {available}")
-        raise typer.Exit(1)
-
-    current = _read_integration_json(project_root)
-    installed_keys = _installed_integration_keys(current)
-    installed_key = _default_integration_key(current)
-
-    if installed_key == target:
-        if integration_options is not None:
-            console.print(
-                "[red]Error:[/red] --integration-options cannot be used when switching "
-                "to an already installed integration."
-            )
-            console.print(
-                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
-                "to update managed files/options."
-            )
-            raise typer.Exit(1)
-        if force:
-            raw_options, parsed_options = _resolve_integration_options(
-                target_integration, current, target, None
-            )
-            _set_default_integration_or_exit(
-                project_root,
-                current,
-                target,
-                target_integration,
-                installed_keys,
-                raw_options=raw_options,
-                parsed_options=parsed_options,
-                refresh_templates_force=True,
-            )
-            console.print(
-                f"\n[green]✓[/green] Default integration remains [bold]{target}[/bold]; "
-                "shared infrastructure refreshed."
-            )
-            raise typer.Exit(0)
-        console.print(f"[yellow]Integration '{target}' is already the default integration. Nothing to switch.[/yellow]")
-        raise typer.Exit(0)
-
-    if target in installed_keys:
-        if integration_options is not None:
-            console.print(
-                "[red]Error:[/red] --integration-options cannot be used when switching "
-                "to an already installed integration."
-            )
-            console.print(
-                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
-                f"to update managed files/options, then [cyan]specify integration use {target}[/cyan]."
-            )
-            raise typer.Exit(1)
-        raw_options, parsed_options = _resolve_integration_options(
-            target_integration, current, target, None
-        )
-        _set_default_integration_or_exit(
-            project_root,
-            current,
-            target,
-            target_integration,
-            installed_keys,
-            raw_options=raw_options,
-            parsed_options=parsed_options,
-            refresh_templates_force=force,
-        )
-        console.print(f"\n[green]✓[/green] Default integration set to [bold]{target}[/bold].")
-        raise typer.Exit(0)
-
-    selected_script = _resolve_script_type(project_root, script)
-
-    # Phase 1: Uninstall current integration (if any)
-    if installed_key:
-        current_integration = get_integration(installed_key)
-        manifest_path = project_root / ".specify" / "integrations" / f"{installed_key}.manifest.json"
-
-        if current_integration and manifest_path.exists():
-            console.print(f"Uninstalling current integration: [cyan]{installed_key}[/cyan]")
-            try:
-                old_manifest = IntegrationManifest.load(installed_key, project_root)
-            except _MANIFEST_READ_ERRORS as exc:
-                console.print(f"[red]Error:[/red] Could not read integration manifest for '{installed_key}': {manifest_path}")
-                console.print(f"[dim]{exc}[/dim]")
-                console.print(
-                    f"To recover, delete the unreadable manifest at {manifest_path}, "
-                    f"run [cyan]specify integration uninstall {installed_key}[/cyan], then retry."
-                )
-                raise typer.Exit(1)
-            removed, skipped = current_integration.teardown(
-                project_root, old_manifest, force=force,
-            )
-            if removed:
-                console.print(f"  Removed {len(removed)} file(s)")
-            if skipped:
-                console.print(f"  [yellow]⚠[/yellow]  {len(skipped)} modified file(s) preserved")
-        elif not current_integration and manifest_path.exists():
-            # Integration removed from registry but manifest exists — use manifest-only uninstall
-            console.print(f"Uninstalling unknown integration '{installed_key}' via manifest")
-            try:
-                old_manifest = IntegrationManifest.load(installed_key, project_root)
-                removed, skipped = old_manifest.uninstall(project_root, force=force)
-                if removed:
-                    console.print(f"  Removed {len(removed)} file(s)")
-                if skipped:
-                    console.print(f"  [yellow]⚠[/yellow]  {len(skipped)} modified file(s) preserved")
-            except _MANIFEST_READ_ERRORS as exc:
-                console.print(f"[yellow]Warning:[/yellow] Could not read manifest for '{installed_key}': {exc}")
-        else:
-            console.print(f"[red]Error:[/red] Integration '{installed_key}' is installed but has no manifest.")
-            console.print(
-                f"Run [cyan]specify integration uninstall {installed_key}[/cyan] to clear metadata, "
-                f"then retry [cyan]specify integration switch {target}[/cyan]."
-            )
-            raise typer.Exit(1)
-
-        # Unregister extension commands for the old agent so they don't
-        # remain as orphans in the old agent's directory.
-        try:
-            from ..extensions import ExtensionManager
-
-            ext_mgr = ExtensionManager(project_root)
-            ext_mgr.unregister_agent_artifacts(installed_key)
-        except Exception as ext_err:
-            _print_cli_warning(
-                "clean up extension artifacts for",
-                "integration",
-                installed_key,
-                ext_err,
-                continuing="Continuing with integration switch; old extension artifacts may need manual cleanup.",
-            )
-
-        # Clear metadata so a failed Phase 2 doesn't leave stale references
-        installed_keys = [installed for installed in installed_keys if installed != installed_key]
-        _clear_init_options_for_integration(project_root, installed_key)
-        if installed_keys:
-            fallback_key = installed_keys[0]
-            fallback_integration = get_integration(fallback_key)
-            if fallback_integration is not None:
-                raw_options, parsed_options = _resolve_integration_options(
-                    fallback_integration, current, fallback_key, None
-                )
-                _set_default_integration_or_exit(
-                    project_root,
-                    current,
-                    fallback_key,
-                    fallback_integration,
-                    installed_keys,
-                    raw_options=raw_options,
-                    parsed_options=parsed_options,
-                )
-            else:
-                _write_integration_json(
-                    project_root, fallback_key, installed_keys, _integration_settings(current)
-                )
-        else:
-            _remove_integration_json(project_root)
-        current = _read_integration_json(project_root)
-
-    # Build parsed options from --integration-options so the integration
-    # can determine its effective invoke separator before shared infra
-    # is installed.
-    raw_options, parsed_options = _resolve_integration_options(
-        target_integration, current, target, integration_options
-    )
-
-    # Refresh shared infrastructure to the current CLI version. Switching
-    # integrations is exactly when stale vendored shared scripts (e.g.
-    # update-agent-context.sh that pre-dates the target integration's
-    # supported-agent list) would silently break the new integration.
-    #
-    # Use refresh_managed=True so only files that match their previously
-    # recorded hash are overwritten — user customizations are detected via
-    # hash divergence and preserved with a warning. Pass
-    # --refresh-shared-infra to overwrite customizations as well. See #2293.
-    _install_shared_infra_or_exit(
-        project_root,
-        selected_script,
-        force=refresh_shared_infra,
-        refresh_managed=True,
-        invoke_separator=_invoke_separator_for_integration(
-            target_integration, current, target, parsed_options
-        ),
-        refresh_hint=(
-            "To overwrite customizations, re-run with "
-            "[cyan]specify integration switch ... --refresh-shared-infra[/cyan]."
-        ),
-    )
-    if os.name != "nt":
-        from .. import ensure_executable_scripts
-        ensure_executable_scripts(project_root)
-
-    # Phase 2: Install target integration
-    console.print(f"Installing integration: [cyan]{target}[/cyan]")
-    manifest = IntegrationManifest(
-        target_integration.key, project_root, version=_get_speckit_version()
-    )
-
-    try:
-        target_integration.setup(
-            project_root, manifest,
-            parsed_options=parsed_options,
-            script_type=selected_script,
-            raw_options=raw_options,
-        )
-        manifest.save()
-        _set_default_integration(
-            project_root,
-            current,
-            target_integration.key,
-            target_integration,
-            _dedupe_integration_keys([*installed_keys, target_integration.key]),
-            script_type=selected_script,
-            raw_options=raw_options,
-            parsed_options=parsed_options,
-        )
-
-        # Re-register extension commands for the new agent so that
-        # previously-installed extensions are available in the new integration.
-        try:
-            from ..extensions import ExtensionManager
-
-            ext_mgr = ExtensionManager(project_root)
-            ext_mgr.register_enabled_extensions_for_agent(target)
-        except Exception as ext_err:
-            _print_cli_warning(
-                "register extension artifacts for",
-                "integration",
-                target,
-                ext_err,
-                continuing="The integration switch succeeded, but installed extensions may need re-registration.",
-            )
-
-    except Exception as exc:
-        # Attempt rollback of any files written by setup
-        try:
-            target_integration.teardown(project_root, manifest, force=True)
-        except Exception as rollback_err:
-            # Suppress so the original setup error remains the primary failure
-            _print_cli_warning(
-                "rollback",
-                "integration",
-                target,
-                rollback_err,
-                continuing="The original switch failure is still the primary error.",
-            )
-        if installed_keys:
-            fallback_key = installed_keys[0]
-            fallback_integration = get_integration(fallback_key)
-            if fallback_integration is not None:
-                raw_options, parsed_options = _resolve_integration_options(
-                    fallback_integration, current, fallback_key, None
-                )
-                try:
-                    _set_default_integration(
-                        project_root,
-                        current,
-                        fallback_key,
-                        fallback_integration,
-                        installed_keys,
-                        raw_options=raw_options,
-                        parsed_options=parsed_options,
-                    )
-                except _SharedTemplateRefreshError as restore_err:
-                    console.print(
-                        f"[yellow]Warning:[/yellow] Failed to restore default "
-                        f"integration '{fallback_key}': {restore_err}"
-                    )
-            else:
-                _write_integration_json(
-                    project_root, fallback_key, installed_keys, _integration_settings(current)
-                )
-        else:
-            _remove_integration_json(project_root)
-        console.print(
-            f"[red]Error:[/red] Failed to {_cli_phase_label('install', 'integration', target)} "
-            f"during switch: {_cli_error_detail(exc)}"
-        )
-        raise typer.Exit(1)
-
-    name = (target_integration.config or {}).get("name", target)
-    console.print(f"\n[green]✓[/green] Switched to integration '{name}'")
-
-
-@integration_app.command("upgrade")
-def integration_upgrade(
-    key: str | None = typer.Argument(None, help="Integration key to upgrade (default: current integration)"),
-    force: bool = typer.Option(False, "--force", help="Force upgrade even if files are modified"),
-    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
-    integration_options: str | None = typer.Option(None, "--integration-options", help="Options for the integration"),
-):
-    """Upgrade an integration by reinstalling with diff-aware file handling.
-
-    Compares manifest hashes to detect locally modified files and
-    blocks the upgrade unless --force is used.
-    """
-    from . import get_integration
-    from .manifest import IntegrationManifest
-    from .. import _require_specify_project, _install_shared_infra_or_exit, _install_shared_infra
-
-    project_root = _require_specify_project()
-    current = _read_integration_json(project_root)
-    installed_key = _default_integration_key(current)
-    installed_keys = _installed_integration_keys(current)
-
-    if key is None:
-        if not installed_key:
-            console.print("[yellow]No integration is currently installed.[/yellow]")
-            raise typer.Exit(0)
-        key = installed_key
-
-    if key not in installed_keys:
-        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
-        raise typer.Exit(1)
-
-    integration = get_integration(key)
-    if integration is None:
-        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
-        raise typer.Exit(1)
-
-    manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
-    if not manifest_path.exists():
-        console.print(f"[yellow]No manifest found for integration '{key}'. Nothing to upgrade.[/yellow]")
-        console.print(f"Run [cyan]specify integration install {key}[/cyan] to perform a fresh install.")
-        raise typer.Exit(0)
-
-    try:
-        old_manifest = IntegrationManifest.load(key, project_root)
-    except _MANIFEST_READ_ERRORS as exc:
-        console.print(f"[red]Error:[/red] Integration manifest for '{key}' is unreadable: {exc}")
-        raise typer.Exit(1)
-
-    # Detect modified files via manifest hashes
-    modified = old_manifest.check_modified()
-    if modified and not force:
-        console.print(f"[yellow]⚠[/yellow]  {len(modified)} file(s) have been modified since installation:")
-        for rel in modified:
-            console.print(f"    {rel}")
-        console.print("\nUse [cyan]--force[/cyan] to overwrite modified files, or resolve manually.")
-        raise typer.Exit(1)
-
-    selected_script = _resolve_integration_script_type(project_root, current, key, script)
-
-    # Build parsed options from --integration-options so the integration
-    # can determine its effective invoke separator before shared infra
-    # is installed.
-    raw_options, parsed_options = _resolve_integration_options(
-        integration, current, key, integration_options
-    )
-
-    # Ensure shared infrastructure is up to date; --force overwrites existing files.
-    infra_integration = integration
-    infra_key = key
-    infra_parsed = parsed_options
-    if installed_key and installed_key != key:
-        default_integration = get_integration(installed_key)
-        if default_integration is not None:
-            infra_integration = default_integration
-            infra_key = installed_key
-            _, infra_parsed = _resolve_integration_options(
-                default_integration, current, installed_key, None
-            )
-    _install_shared_infra_or_exit(
-        project_root,
-        selected_script,
-        force=force,
-        invoke_separator=_invoke_separator_for_integration(
-            infra_integration, current, infra_key, infra_parsed
-        ),
-    )
-    if os.name != "nt":
-        from .. import ensure_executable_scripts
-        ensure_executable_scripts(project_root)
-
-    # Phase 1: Install new files (overwrites existing; old-only files remain)
-    console.print(f"Upgrading integration: [cyan]{key}[/cyan]")
-    new_manifest = IntegrationManifest(key, project_root, version=_get_speckit_version())
-
-    try:
-        integration.setup(
-            project_root,
-            new_manifest,
-            parsed_options=parsed_options,
-            script_type=selected_script,
-            raw_options=raw_options,
-        )
-        settings = _with_integration_setting(
-            current,
-            key,
-            integration,
-            script_type=selected_script,
-            raw_options=raw_options,
-            parsed_options=parsed_options,
-        )
-        if installed_key == key:
-            try:
-                _install_shared_infra(
-                    project_root,
-                    selected_script,
-                    invoke_separator=_invoke_separator_for_integration(
-                        integration, {"integration_settings": settings}, key, parsed_options
-                    ),
-                    force=force,
-                    refresh_managed=True,
-                )
-            except (ValueError, OSError) as exc:
-                raise _SharedTemplateRefreshError(
-                    f"Failed to refresh shared infrastructure for '{key}': {exc}"
-                ) from exc
-        new_manifest.save()
-        _write_integration_json(project_root, installed_key, installed_keys, settings)
-        if installed_key == key:
-            _update_init_options_for_integration(project_root, integration, script_type=selected_script)
-        else:
-            _refresh_init_options_speckit_version(project_root)
-    except Exception as exc:
-        # Don't teardown — setup overwrites in-place, so teardown would
-        # delete files that were working before the upgrade.  Just report.
-        console.print(f"[red]Error:[/red] Failed to {_cli_phase_label('upgrade', 'integration', key)}.")
-        console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
-        console.print("[yellow]The previous integration files may still be in place.[/yellow]")
-        raise typer.Exit(1)
-
-    # Phase 2: Remove stale files from old manifest that are not in the new one
-    old_files = old_manifest.files
-    new_files = new_manifest.files
-    stale_keys = set(old_files) - set(new_files)
-    if stale_keys:
-        stale_manifest = IntegrationManifest(key, project_root, version="stale-cleanup")
-        stale_manifest._files = {k: old_files[k] for k in stale_keys}
-        stale_removed, _ = stale_manifest.uninstall(project_root, force=True)
-        if stale_removed:
-            console.print(f"  Removed {len(stale_removed)} stale file(s) from previous install")
-
-    name = (integration.config or {}).get("name", key)
-    console.print(f"\n[green]✓[/green] Integration '{name}' upgraded successfully")

src/specify_cli/integrations/_query_commands.py

@@ -1,464 +0,0 @@
-"""specify integration list/use/search/info + catalog list/add/remove command handlers."""
-from __future__ import annotations
-
-import os
-from typing import Optional
-
-import typer
-from rich.table import Table
-
-from .._console import console
-from ..integration_state import (
-    default_integration_key as _default_integration_key,
-    installed_integration_keys as _installed_integration_keys,
-)
-from ._commands import integration_app, integration_catalog_app
-from ._helpers import (
-    _read_integration_json,
-    _resolve_integration_options,
-    _set_default_integration_or_exit,
-)
-
-
-@integration_app.command("list")
-def integration_list(
-    catalog: bool = typer.Option(False, "--catalog", help="Browse full catalog (built-in + community)"),
-):
-    """List available integrations and installed status."""
-    from . import INTEGRATION_REGISTRY
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    current = _read_integration_json(project_root)
-    default_key = _default_integration_key(current)
-    installed_keys = set(_installed_integration_keys(current))
-
-    if catalog:
-        from .catalog import IntegrationCatalog, IntegrationCatalogError
-
-        ic = IntegrationCatalog(project_root)
-        try:
-            entries = ic.search()
-        except IntegrationCatalogError as exc:
-            console.print(f"[red]Error:[/red] {exc}")
-            raise typer.Exit(1)
-
-        if not entries:
-            console.print("[yellow]No integrations found in catalog.[/yellow]")
-            return
-
-        table = Table(title="Integration Catalog")
-        table.add_column("ID", style="cyan")
-        table.add_column("Name")
-        table.add_column("Version")
-        table.add_column("Source")
-        table.add_column("Status")
-        table.add_column("Multi-install Safe")
-
-        for entry in sorted(entries, key=lambda e: e["id"]):
-            eid = entry["id"]
-            cat_name = entry.get("_catalog_name", "")
-            install_allowed = entry.get("_install_allowed", True)
-            if eid == default_key:
-                status = "[green]installed (default)[/green]"
-            elif eid in installed_keys:
-                status = "[green]installed[/green]"
-            elif eid in INTEGRATION_REGISTRY:
-                status = "built-in"
-            elif install_allowed is False:
-                status = "discovery-only"
-            else:
-                status = ""
-            safe = ""
-            if eid in INTEGRATION_REGISTRY:
-                reg_integ = INTEGRATION_REGISTRY[eid]
-                safe = "yes" if getattr(reg_integ, "multi_install_safe", False) else "no"
-            table.add_row(
-                eid,
-                entry.get("name", eid),
-                entry.get("version", ""),
-                cat_name,
-                status,
-                safe,
-            )
-        console.print(table)
-        return
-
-    if not INTEGRATION_REGISTRY:
-        console.print("[yellow]No integrations available.[/yellow]")
-        return
-
-    table = Table(title="Coding Agent Integrations")
-    table.add_column("Key", style="cyan")
-    table.add_column("Name")
-    table.add_column("Status")
-    table.add_column("CLI Required")
-    table.add_column("Multi-install Safe")
-
-    for key in sorted(INTEGRATION_REGISTRY.keys()):
-        integration = INTEGRATION_REGISTRY[key]
-        cfg = integration.config or {}
-        name = cfg.get("name", key)
-        requires_cli = cfg.get("requires_cli", False)
-        if key == default_key:
-            status = "[green]installed (default)[/green]"
-        elif key in installed_keys:
-            status = "[green]installed[/green]"
-        else:
-            status = ""
-        cli_req = "yes" if requires_cli else "no (IDE)"
-        safe = "yes" if getattr(integration, "multi_install_safe", False) else "no"
-        table.add_row(key, name, status, cli_req, safe)
-
-    console.print(table)
-
-    if installed_keys:
-        console.print(f"\n[dim]Default integration:[/dim] [cyan]{default_key or 'none'}[/cyan]")
-        console.print(f"[dim]Installed integrations:[/dim] [cyan]{', '.join(sorted(installed_keys))}[/cyan]")
-    else:
-        console.print("\n[yellow]No integration currently installed.[/yellow]")
-        console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
-
-
-@integration_app.command("use")
-def integration_use(
-    key: str = typer.Argument(help="Installed integration key to make the default"),
-    force: bool = typer.Option(False, "--force", help="Overwrite existing shared infrastructure files, including customizations, while changing the default"),
-):
-    """Set the default integration without uninstalling other integrations."""
-    from . import get_integration
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    current = _read_integration_json(project_root)
-    installed_keys = _installed_integration_keys(current)
-    if key not in installed_keys:
-        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
-        if installed_keys:
-            console.print(f"[yellow]Installed integrations:[/yellow] {', '.join(installed_keys)}")
-        else:
-            console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
-        raise typer.Exit(1)
-
-    integration = get_integration(key)
-    if integration is None:
-        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
-        raise typer.Exit(1)
-
-    raw_options, parsed_options = _resolve_integration_options(integration, current, key, None)
-    _set_default_integration_or_exit(
-        project_root,
-        current,
-        key,
-        integration,
-        installed_keys,
-        raw_options=raw_options,
-        parsed_options=parsed_options,
-        refresh_templates_force=force,
-        refresh_hint=(
-            "To overwrite customizations, re-run with "
-            f"[cyan]specify integration use {key} --force[/cyan]."
-        ),
-    )
-    console.print(f"[green]✓[/green] Default integration set to [bold]{key}[/bold].")
-
-
-# ===== Integration catalog discovery commands =====
-#
-# These commands mirror the workflow catalog CLI shape:
-#   - `search` / `info` for discovery over the active catalog stack
-#   - `catalog list/add/remove` for managing catalog sources
-#
-# They deliberately do NOT add `integration add/remove/enable/disable/
-# set-priority`: integrations are single-active (install / uninstall / switch),
-# not additive like extensions and presets.
-@integration_app.command("search")
-def integration_search(
-    query: Optional[str] = typer.Argument(None, help="Search query (optional)"),
-    tag: Optional[str] = typer.Option(None, "--tag", help="Filter by tag"),
-    author: Optional[str] = typer.Option(None, "--author", help="Filter by author"),
-):
-    """Search for integrations in the active catalog stack."""
-    from . import INTEGRATION_REGISTRY
-    from .catalog import (
-        IntegrationCatalog,
-        IntegrationCatalogError,
-        IntegrationValidationError,
-    )
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    integration_config = _read_integration_json(project_root)
-    installed_key = _default_integration_key(integration_config)
-    catalog = IntegrationCatalog(project_root)
-
-    try:
-        results = catalog.search(query=query, tag=tag, author=author)
-    except IntegrationValidationError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        console.print(
-            "\nTip: Check the configuration file path shown above for invalid catalog configuration "
-            "(for example, .specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml)."
-        )
-        raise typer.Exit(1)
-    except IntegrationCatalogError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        if os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip():
-            console.print(
-                "\nTip: Check the SPECKIT_INTEGRATION_CATALOG_URL environment variable for an invalid "
-                "catalog URL, or unset it to use the configured catalog files "
-                "(.specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml)."
-            )
-        else:
-            console.print("\nTip: The catalog may be temporarily unavailable. Try again later.")
-        raise typer.Exit(1)
-
-    if not results:
-        console.print("\n[yellow]No integrations found matching criteria[/yellow]")
-        if query or tag or author:
-            console.print("\nTry:")
-            console.print("  • Broader search terms")
-            console.print("  • Remove filters")
-            console.print("  • specify integration search (show all)")
-        return
-
-    console.print(f"\n[green]Found {len(results)} integration(s):[/green]\n")
-    for integ in sorted(results, key=lambda e: e.get("id", "")):
-        iid = integ.get("id", "?")
-        name = integ.get("name", iid)
-        version = integ.get("version", "?")
-        console.print(f"[bold]{name}[/bold] ({iid}) v{version}")
-        desc = integ.get("description", "")
-        if desc:
-            console.print(f"  {desc}")
-
-        console.print(f"\n  [dim]Author:[/dim] {integ.get('author', 'Unknown')}")
-        tags = integ.get("tags", [])
-        if isinstance(tags, list) and tags:
-            console.print(f"  [dim]Tags:[/dim] {', '.join(str(t) for t in tags)}")
-
-        cat_name = integ.get("_catalog_name", "")
-        install_allowed = integ.get("_install_allowed", True)
-        if cat_name:
-            if install_allowed:
-                console.print(f"  [dim]Catalog:[/dim] {cat_name}")
-            else:
-                console.print(
-                    f"  [dim]Catalog:[/dim] {cat_name} "
-                    "[yellow](discovery only — not installable)[/yellow]"
-                )
-
-        if iid == installed_key:
-            console.print("\n  [green]✓ Installed[/green] (currently active)")
-        elif iid in INTEGRATION_REGISTRY:
-            console.print(f"\n  [cyan]Install:[/cyan] specify integration install {iid}")
-        elif install_allowed:
-            console.print(
-                "\n  [yellow]Found in catalog.[/yellow] Only built-in integration IDs "
-                "can be installed with 'specify integration install'."
-            )
-        else:
-            console.print(
-                f"\n  [yellow]⚠[/yellow]  Not directly installable from '{cat_name}'."
-            )
-        console.print()
-
-
-@integration_app.command("info")
-def integration_info(
-    integration_id: str = typer.Argument(..., help="Integration ID"),
-):
-    """Show catalog details for a single integration."""
-    from . import INTEGRATION_REGISTRY
-    from .catalog import (
-        IntegrationCatalog,
-        IntegrationCatalogError,
-        IntegrationValidationError,
-    )
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    catalog = IntegrationCatalog(project_root)
-    installed_key = _default_integration_key(_read_integration_json(project_root))
-
-    try:
-        info = catalog.get_integration_info(integration_id)
-    except IntegrationCatalogError as exc:
-        info = None
-        # Keep the live exception so the fallback branch below can give
-        # different guidance for local-config vs. network failures.
-        catalog_error: Optional[IntegrationCatalogError] = exc
-    else:
-        catalog_error = None
-
-    if info:
-        name = info.get("name", integration_id)
-        version = info.get("version", "?")
-        console.print(f"\n[bold cyan]{name}[/bold cyan] ({integration_id}) v{version}")
-        if info.get("description"):
-            console.print(f"  {info['description']}")
-        console.print()
-
-        console.print(f"  [dim]Author:[/dim] {info.get('author', 'Unknown')}")
-        if info.get("license"):
-            console.print(f"  [dim]License:[/dim] {info['license']}")
-
-        tags = info.get("tags", [])
-        if isinstance(tags, list) and tags:
-            console.print(f"  [dim]Tags:[/dim] {', '.join(str(t) for t in tags)}")
-
-        cat_name = info.get("_catalog_name", "")
-        install_allowed = info.get("_install_allowed", True)
-        if cat_name:
-            install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"
-            console.print(f"  [dim]Source catalog:[/dim] {cat_name}{install_note}")
-
-        if info.get("repository"):
-            console.print(f"  [dim]Repository:[/dim] {info['repository']}")
-
-        if integration_id == installed_key:
-            console.print("\n  [green]✓ Installed[/green] (currently active)")
-        elif integration_id in INTEGRATION_REGISTRY:
-            console.print("\n  [dim]Built-in integration (not currently active)[/dim]")
-        return
-
-    if integration_id in INTEGRATION_REGISTRY:
-        integration = INTEGRATION_REGISTRY[integration_id]
-        cfg = integration.config or {}
-        name = cfg.get("name", integration_id)
-        console.print(f"\n[bold cyan]{name}[/bold cyan] ({integration_id})")
-        console.print("  [dim]Built-in integration (not listed in catalog)[/dim]")
-        if integration_id == installed_key:
-            console.print("\n  [green]✓ Installed[/green] (currently active)")
-        if catalog_error:
-            console.print(f"\n[yellow]Catalog unavailable:[/yellow] {catalog_error}")
-        return
-
-    if catalog_error:
-        console.print(f"[red]Error:[/red] Could not query integration catalog: {catalog_error}")
-        if isinstance(catalog_error, IntegrationValidationError):
-            console.print(
-                "\nCheck the configuration file path shown above "
-                "(.specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml), "
-                "or use a built-in integration ID directly."
-            )
-        elif os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip():
-            console.print(
-                "\nCheck whether SPECKIT_INTEGRATION_CATALOG_URL is set correctly and reachable, "
-                "or unset it to use the configured catalog files, or use a built-in integration ID directly."
-            )
-        else:
-            console.print("\nTry again when online, or use a built-in integration ID directly.")
-    else:
-        console.print(f"[red]Error:[/red] Integration '{integration_id}' not found")
-        console.print("\nTry: specify integration search")
-    raise typer.Exit(1)
-
-
-@integration_catalog_app.command("list")
-def integration_catalog_list():
-    """List configured integration catalog sources."""
-    from .catalog import IntegrationCatalog, IntegrationCatalogError
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    catalog = IntegrationCatalog(project_root)
-    env_override = os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip()
-
-    try:
-        if env_override:
-            project_configs = None
-            configs = catalog.get_catalog_configs()
-        else:
-            project_configs = catalog.get_project_catalog_configs()
-            configs = project_configs if project_configs is not None else catalog.get_catalog_configs()
-    except IntegrationCatalogError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        raise typer.Exit(1)
-
-    console.print("\n[bold cyan]Integration Catalog Sources:[/bold cyan]\n")
-    if env_override:
-        console.print(
-            "  SPECKIT_INTEGRATION_CATALOG_URL is set; it supersedes configured catalog files."
-        )
-        console.print(
-            "  Project/user catalog sources are not active while the env override is set.\n"
-        )
-        console.print("[bold]Active catalog source from environment (non-removable here):[/bold]\n")
-    elif project_configs is None:
-        console.print("  No project-level catalog sources configured.\n")
-        console.print("[bold]Active catalog sources (non-removable here):[/bold]\n")
-    else:
-        console.print("[bold]Project catalog sources (removable):[/bold]\n")
-
-    for i, cfg in enumerate(configs):
-        install_status = (
-            "[green]install allowed[/green]"
-            if cfg.get("install_allowed")
-            else "[yellow]discovery only[/yellow]"
-        )
-        raw_name = cfg.get("name")
-        display_name = str(raw_name).strip() if raw_name is not None else ""
-        if not display_name:
-            display_name = f"catalog-{i + 1}"
-        if env_override or project_configs is None:
-            console.print(f"  - [bold]{display_name}[/bold] — {install_status}")
-        else:
-            console.print(f"  [{i}] [bold]{display_name}[/bold] — {install_status}")
-        console.print(f"      {cfg.get('url', '')}")
-        if cfg.get("description"):
-            console.print(f"      [dim]{cfg['description']}[/dim]")
-        console.print()
-
-
-@integration_catalog_app.command("add")
-def integration_catalog_add(
-    url: str = typer.Argument(
-        ...,
-        help=(
-            "Catalog URL to add (HTTPS required, except http://localhost, "
-            "http://127.0.0.1, or http://[::1] for local testing)"
-        ),
-    ),
-    name: Optional[str] = typer.Option(None, "--name", help="Catalog name"),
-):
-    """Add an integration catalog source to the project config."""
-    from .catalog import IntegrationCatalog, IntegrationCatalogError
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    catalog = IntegrationCatalog(project_root)
-
-    # Normalize once here so the success message reflects what was actually
-    # stored. ``IntegrationCatalog.add_catalog`` strips again defensively.
-    normalized_url = url.strip()
-
-    try:
-        catalog.add_catalog(normalized_url, name)
-    except IntegrationCatalogError as exc:
-        # Covers both URL validation (base class) and config-file validation
-        # (IntegrationValidationError subclass).
-        console.print(f"[red]Error:[/red] {exc}")
-        raise typer.Exit(1)
-
-    console.print(f"[green]✓[/green] Catalog source added: {normalized_url}")
-
-
-@integration_catalog_app.command("remove")
-def integration_catalog_remove(
-    index: int = typer.Argument(..., help="Catalog index to remove (from 'catalog list')"),
-):
-    """Remove an integration catalog source by 0-based index."""
-    from .catalog import IntegrationCatalog, IntegrationCatalogError
-    from .. import _require_specify_project
-
-    project_root = _require_specify_project()
-    catalog = IntegrationCatalog(project_root)
-
-    try:
-        removed_name = catalog.remove_catalog(index)
-    except IntegrationCatalogError as exc:
-        console.print(f"[red]Error:[/red] {exc}")
-        raise typer.Exit(1)
-
-    console.print(f"[green]✓[/green] Catalog source '{removed_name}' removed")

src/specify_cli/integrations/copilot/__init__.py

@@ -283,13 +283,58 @@ class CopilotIntegration(IntegrationBase):
         return f"speckit.{template_name}.agent.md"
 
     def post_process_skill_content(self, content: str) -> str:
-        """Inject shared hook guidance into Copilot skill content.
+        """Inject shared hook guidance and Copilot ``mode:`` frontmatter.
 
-        Delegates to :class:`_CopilotSkillsHelper` for shared post-processing.
-        The ``mode:`` frontmatter field is intentionally omitted: VS Code
-        Copilot Agent Skills do not support it (see issue #2799).
+        Inserts ``mode: speckit.<stem>`` before the closing ``---`` so
+        Copilot can associate the skill with its agent mode.
         """
-        return _CopilotSkillsHelper().post_process_skill_content(content)
+        updated = _CopilotSkillsHelper().post_process_skill_content(content)
+        lines = updated.splitlines(keepends=True)
+
+        # Extract skill name from frontmatter to derive the mode value
+        dash_count = 0
+        skill_name = ""
+        for line in lines:
+            stripped = line.rstrip("\n\r")
+            if stripped == "---":
+                dash_count += 1
+                if dash_count == 2:
+                    break
+                continue
+            if dash_count == 1:
+                if stripped.startswith("mode:"):
+                    return updated  # already present
+                if stripped.startswith("name:"):
+                    # Parse: name: "speckit-plan" → speckit.plan
+                    val = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+                    # Convert speckit-plan → speckit.plan
+                    if val.startswith("speckit-"):
+                        skill_name = "speckit." + val[len("speckit-"):]
+                    else:
+                        skill_name = val
+
+        if not skill_name:
+            return updated
+
+        # Inject mode: before the closing --- of frontmatter
+        out: list[str] = []
+        dash_count = 0
+        injected = False
+        for line in lines:
+            stripped = line.rstrip("\n\r")
+            if stripped == "---":
+                dash_count += 1
+                if dash_count == 2 and not injected:
+                    if line.endswith("\r\n"):
+                        eol = "\r\n"
+                    elif line.endswith("\n"):
+                        eol = "\n"
+                    else:
+                        eol = ""
+                    out.append(f"mode: {skill_name}{eol}")
+                    injected = True
+            out.append(line)
+        return "".join(out)
 
     def setup(
         self,

src/specify_cli/integrations/manifest.py

@@ -115,7 +115,6 @@ class IntegrationManifest:
         self.project_root = project_root.resolve()
         self.version = version
         self._files: dict[str, str] = {}  # rel_path → sha256 hex
-        self._recovered_files: set[str] = set()
         self._installed_at: str = ""
 
     # -- Manifest file location -------------------------------------------
@@ -132,9 +131,6 @@ class IntegrationManifest:
 
         Creates parent directories as needed.  Returns the absolute path
         of the written file.
-        If the path was previously marked as recovered via
-        ``record_existing(recovered=True)``, the recovered marker is
-        cleared because the bytes are now produced, not merely observed.
 
         Raises ``ValueError`` if *rel_path* resolves outside the project root.
         """
@@ -148,77 +144,17 @@ class IntegrationManifest:
 
         normalized = abs_path.relative_to(self.project_root).as_posix()
         self._files[normalized] = hashlib.sha256(content).hexdigest()
-        # ``record_file`` writes *produced* content, so any prior
-        # recovered marker for this path is no longer accurate.
-        self._recovered_files.discard(normalized)
         return abs_path
 
-    def record_existing(self, rel_path: str | Path, *, recovered: bool = False) -> None:
-        """Record the hash of an already-existing regular file at *rel_path*.
+    def record_existing(self, rel_path: str | Path) -> None:
+        """Record the hash of an already-existing file at *rel_path*.
 
-        When ``recovered=True``, the path is also marked in the manifest's
-        ``recovered_files`` list to signal that the file's on-disk hash was
-        *observed* during install (because the file already existed and was not
-        overwritten), not *produced* by the install. Future ``refresh_managed``
-        runs should consult ``is_recovered`` before treating the recorded hash
-        as a managed baseline.
-
-        Raises:
-            ValueError: if *rel_path* resolves outside the project root, is
-                a symlink, or is not a regular file. A directory or other
-                non-file path cannot be silently recorded — its hash would
-                be meaningless and ``check_modified``/``uninstall`` would
-                treat the entry as permanently broken.
-            OSError: if the underlying filesystem call (``is_symlink``,
-                ``is_file``, or the file-read used to compute the hash)
-                fails — for example a ``PermissionError`` on the path.
-                Callers should be prepared to handle ``OSError`` (and its
-                subclasses such as ``PermissionError``) in addition to
-                ``ValueError``.
+        Raises ``ValueError`` if *rel_path* resolves outside the project root.
         """
         rel = Path(rel_path)
-        # Cheap lexical pre-check first so absolute / parent-traversal paths
-        # don't trigger a filesystem stat outside the project root before
-        # ``_validate_rel_path`` raises. ``_validate_rel_path`` produces the
-        # canonical error messages used elsewhere.
-        if rel.is_absolute() or ".." in rel.parts:
-            _validate_rel_path(rel, self.project_root)
-            # _validate_rel_path raised for any actually-escaping path. If we reach
-            # here the path normalizes inside root (e.g. ``dir/../file.txt``).
-            # Reject anyway: manifest keys must be canonical so ``check_modified``
-            # and ``uninstall`` cannot key the same file under two paths.
-            raise ValueError(
-                f"Manifest paths must be canonical; '..' segments are not "
-                f"allowed (got {rel})"
-            )
-        # Walk each path component before resolution so a symlinked ancestor
-        # (e.g. ``linked_dir/file.txt`` where ``linked_dir`` is a symlink)
-        # cannot be silently followed by ``_validate_rel_path().resolve()``
-        # down to a target outside the project root. ``_ensure_safe_manifest_directory``
-        # uses the same pattern.
-        _walk = self.project_root
-        for part in rel.parts:
-            _walk = _walk / part
-            if _walk.is_symlink():
-                raise ValueError(
-                    f"Refusing to record symlinked manifest path: {rel} "
-                    f"(symlinked at {_walk.relative_to(self.project_root).as_posix()})"
-                )
         abs_path = _validate_rel_path(rel, self.project_root)
-        if not abs_path.is_file():
-            raise ValueError(
-                f"Manifest path is not a regular file: {rel}"
-            )
         normalized = abs_path.relative_to(self.project_root).as_posix()
         self._files[normalized] = _sha256(abs_path)
-        if recovered:
-            self._recovered_files.add(normalized)
-        else:
-            # ``recovered=False`` means the caller is asserting this path is
-            # managed-baseline now, not merely observed; drop any stale
-            # recovered marker so future is_recovered() queries reflect the
-            # transition. ``discard`` is a no-op when the key is absent.
-            self._recovered_files.discard(normalized)
 
     # -- Querying ---------------------------------------------------------
 
@@ -227,37 +163,6 @@ class IntegrationManifest:
         """Return a copy of the ``{rel_path: sha256}`` mapping."""
         return dict(self._files)
 
-    @property
-    def recovered_files(self) -> set[str]:
-        """Return a copy of the set of paths recorded with ``recovered=True``.
-
-        These entries had their hashes observed (not produced) during install
-        because the file already existed on disk and the install skipped it.
-        Their on-disk bytes may be user customizations — callers that would
-        overwrite based on hash equality (e.g. ``refresh_managed``) MUST check
-        ``is_recovered`` first.
-        """
-        return set(self._recovered_files)
-
-    def is_recovered(self, rel_path: str | Path) -> bool:
-        """Return True if *rel_path* was recorded via ``record_existing(recovered=True)``.
-
-        Input is normalized through the same pipeline as ``record_existing``:
-        absolute paths, paths escaping the project root, AND paths containing
-        ``'..'`` segments are rejected (returned as ``False``). This mirrors
-        ``record_existing``'s canonicalization guard — such paths can never
-        appear as stored keys, so the answer is always ``False``.
-        """
-        rel = Path(rel_path)
-        if rel.is_absolute() or ".." in rel.parts:
-            return False
-        try:
-            abs_path = _validate_rel_path(rel, self.project_root)
-            normalized = abs_path.relative_to(self.project_root).as_posix()
-        except ValueError:
-            return False
-        return normalized in self._recovered_files
-
     def check_modified(self) -> list[str]:
         """Return relative paths of tracked files whose content changed on disk."""
         modified: list[str] = []
@@ -364,11 +269,6 @@ class IntegrationManifest:
             "version": self.version,
             "installed_at": self._installed_at,
             "files": self._files,
-            **(
-                {"recovered_files": sorted(self._recovered_files)}
-                if self._recovered_files
-                else {}
-            ),
         }
         path = self.manifest_path
         content = json.dumps(data, indent=2) + "\n"
@@ -420,20 +320,6 @@ class IntegrationManifest:
         inst._installed_at = data.get("installed_at", "")
         inst._files = files
 
-        recovered = data.get("recovered_files", [])
-        if not isinstance(recovered, list) or not all(
-            isinstance(p, str) for p in recovered
-        ):
-            raise ValueError(
-                f"Integration manifest 'recovered_files' at {path} must be a "
-                "list of string paths"
-            )
-        inst._recovered_files = set(recovered)
-        # Drop any recovered_files entries that don't correspond to tracked
-        # files — defensive against externally-edited or partially-corrupted
-        # manifests. Inconsistent state self-corrects on next save().
-        inst._recovered_files &= set(inst._files.keys())
-
         stored_key = data.get("integration", "")
         if stored_key and stored_key != key:
             raise ValueError(

src/specify_cli/shared_infra.py

@@ -365,23 +365,6 @@ def install_shared_infra(
                                 preserved_user_files.append(rel)
                             else:
                                 skipped_files.append(rel)
-                                # Record the existing-on-disk file in the manifest so a
-                                # fresh manifest run against an already-populated
-                                # ``.specify/`` tree does not silently drop it (#2107).
-                                # ``prior_hashes`` is the function-scope snapshot taken
-                                # at entry, so this membership check is O(1) and avoids
-                                # the repeated ``dict(self._files)`` copy that
-                                # ``manifest.files`` performs on every access.
-                                if dst_path.is_file() and rel not in prior_hashes:
-                                    try:
-                                        manifest.record_existing(rel, recovered=True)
-                                    except (OSError, ValueError) as exc:
-                                        # Tolerate races / permission issues / non-file
-                                        # collisions so one weird path does not abort
-                                        # the whole install.
-                                        console.print(
-                                            f"[yellow]⚠[/yellow]  could not record {rel} in manifest: {exc}"
-                                        )
                             continue
 
                         if not _ensure_or_bucket_dir(dst_path.parent):
@@ -415,23 +398,6 @@ def install_shared_infra(
                         preserved_user_files.append(rel)
                     else:
                         skipped_files.append(rel)
-                        # Record the existing-on-disk template in the manifest so a
-                        # fresh manifest run against an already-populated
-                        # ``.specify/`` tree does not silently drop it (#2107).
-                        # ``prior_hashes`` is the function-scope snapshot taken at
-                        # entry, so this membership check is O(1) and avoids the
-                        # repeated ``dict(self._files)`` copy that ``manifest.files``
-                        # performs on every access.
-                        if dst.is_file() and rel not in prior_hashes:
-                            try:
-                                manifest.record_existing(rel, recovered=True)
-                            except (OSError, ValueError) as exc:
-                                # Tolerate races / permission issues / non-file
-                                # collisions so one weird path does not abort
-                                # the whole install.
-                                console.print(
-                                    f"[yellow]⚠[/yellow]  could not record {rel} in manifest: {exc}"
-                                )
                     continue
 
                 content = src.read_text(encoding="utf-8")
@@ -450,7 +416,7 @@ def install_shared_infra(
 
     if skipped_files:
         console.print(
-            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure path(s) already exist and were not updated:"
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
         )
         for path in skipped_files:
             console.print(f"    {path}")

src/specify_cli/workflows/engine.py

@@ -232,22 +232,6 @@ def _validate_steps(
             step_errors = step_impl.validate(step_config)
             errors.extend(step_errors)
 
-        # Validate optional `continue_on_error` field. The engine honours
-        # this on any step that returns StepStatus.FAILED so the pipeline can route
-        # around the failure via a downstream `if` or `switch` (or a
-        # `gate` that surfaces the failure to the operator via message
-        # interpolation). The field must be a literal boolean —
-        # coercion from truthy strings is deliberately not supported so
-        # authoring mistakes surface at validation time rather than
-        # silently changing run semantics.
-        if "continue_on_error" in step_config:
-            coe = step_config["continue_on_error"]
-            if not isinstance(coe, bool):
-                errors.append(
-                    f"Step {step_id!r}: 'continue_on_error' must be a "
-                    f"boolean, got {type(coe).__name__}."
-                )
-
         # Recursively validate nested steps
         for nested_key in ("then", "else", "steps"):
             nested = step_config.get(nested_key)
@@ -645,10 +629,7 @@ class WorkflowEngine:
 
             # Handle failures
             if result.status == StepStatus.FAILED:
-                # Gate abort (output.aborted) maps to ABORTED status.
-                # Aborts are deliberate operator decisions, so
-                # `continue_on_error` does NOT override them — that flag
-                # is for transient/expected step failures only.
+                # Gate abort (output.aborted) maps to ABORTED status
                 if result.output.get("aborted"):
                     state.status = RunStatus.ABORTED
                     state.append_log(
@@ -657,49 +638,15 @@ class WorkflowEngine:
                             "step_id": step_id,
                         }
                     )
-                    state.save()
-                    return
-
-                # `continue_on_error: true` lets the pipeline route
-                # around the failure instead of halting. The step
-                # result (including exit_code, stderr, status) is
-                # still recorded so a downstream `if` or `switch`
-                # can branch on it (or a `gate` can surface it to the
-                # operator via message interpolation). Log a single,
-                # unambiguous event per failure resolution — either
-                # the run continued past it, or it halted.
-                #
-                # Use identity comparison (`is True`) rather than
-                # truthiness so that only a literal boolean enables
-                # the behaviour, even if validation was skipped.
-                # Validation rejects non-bool values at parse time,
-                # but `WorkflowEngine.execute()` does not auto-validate
-                # (see `WorkflowEngine.load_workflow`, whose docstring
-                # explicitly notes "not yet validated; call
-                # `validate_workflow()` or `engine.validate()`
-                # separately"), so a caller passing an unvalidated
-                # definition could otherwise see truthy non-bool
-                # values like the string `"true"` silently change
-                # run semantics.
-                if step_config.get("continue_on_error") is True:
+                else:
+                    state.status = RunStatus.FAILED
                     state.append_log(
                         {
-                            "event": "step_continue_on_error",
+                            "event": "step_failed",
                             "step_id": step_id,
                             "error": result.error,
                         }
                     )
-                    state.save()
-                    continue
-
-                state.status = RunStatus.FAILED
-                state.append_log(
-                    {
-                        "event": "step_failed",
-                        "step_id": step_id,
-                        "error": result.error,
-                    }
-                )
                 state.save()
                 return
 

tests/integrations/test_integration_claude.py

@@ -3,7 +3,6 @@
 import codecs
 import json
 import os
-from pathlib import Path
 from unittest.mock import patch
 
 import yaml
@@ -578,204 +577,3 @@ class TestClaudeHookCommandNote:
         assert "user-invocable: true" in result
         assert "disable-model-invocation: false" in result
         assert "replace dots" in result
-
-
-class TestSpeckitManifestRecordsSkippedFiles:
-    """Regression test for issue #2107.
-
-    ``install_shared_infra`` must record every shared-infrastructure file
-    under ``.specify/`` in ``speckit.manifest.json``, including files that
-    were *skipped* because they already existed on disk and ``force=False``.
-
-    Before the fix, the skip branches in the scripts and templates loops
-    appended to ``skipped_files`` without calling ``manifest.record_existing``.
-    So when ``install_shared_infra`` ran with a fresh (or lost) manifest
-    against an already-populated ``.specify/`` tree, every file went down the
-    skip path, ``planned_copies`` and ``planned_templates`` stayed empty, and
-    ``manifest.save()`` wrote an empty ``files`` field — leaving the
-    integration believing nothing was installed.
-
-    Reproduction (without the fix) using ``install_shared_infra`` directly:
-
-        install_shared_infra(p, "sh", ..., force=False)   # 1st run → 10 files
-        (p / ".specify/integrations/speckit.manifest.json").unlink()
-        install_shared_infra(p, "sh", ..., force=False)   # 2nd run → 0 files
-                                                          # ^^ BUG: empty
-    """
-
-    def _read_manifest_files(self, project_path: Path) -> dict:
-        manifest_path = (
-            project_path / ".specify" / "integrations" / "speckit.manifest.json"
-        )
-        assert manifest_path.exists(), (
-            f"speckit.manifest.json not written at {manifest_path}"
-        )
-        data = json.loads(manifest_path.read_text(encoding="utf-8"))
-        # ``IntegrationManifest.save`` serialises a ``files`` dict — assert
-        # the schema explicitly so a regression to a different key (e.g.
-        # the internal ``_files`` attribute name) fails loudly instead of
-        # being masked by a silent fallback.
-        assert isinstance(data, dict), (
-            f"manifest root is not a dict, got {type(data).__name__}"
-        )
-        assert "files" in data, (
-            f"manifest missing 'files' key, got keys: {sorted(data.keys())}"
-        )
-        files = data["files"]
-        assert isinstance(files, dict), (
-            f"manifest 'files' is not a dict, got {type(files).__name__}"
-        )
-        return files
-
-    def test_install_shared_infra_records_skipped_files(self, tmp_path):
-        """With ``force=False`` and ``.specify/`` already populated, the
-        manifest must still record every file — the skip branches are not
-        allowed to drop files from the manifest."""
-        from rich.console import Console
-        from specify_cli.shared_infra import install_shared_infra
-
-        # Resolve the project's own packaged sources by walking up from this
-        # test file to the repo root (which contains ``scripts/`` and
-        # ``templates/`` that ``shared_scripts_source`` looks for).
-        repo_root = Path(__file__).resolve().parents[2]
-        console = Console(quiet=True)
-
-        # First run — fresh project, manifest gets populated normally.
-        install_shared_infra(
-            tmp_path,
-            "sh",
-            version="0.0.0",
-            core_pack=None,
-            repo_root=repo_root,
-            console=console,
-            force=False,
-        )
-        first_files = self._read_manifest_files(tmp_path)
-        assert first_files, "first install produced an empty manifest"
-
-        # Simulate a lost manifest while ``.specify/`` is still on disk
-        # (e.g. the manifest was deleted, corrupted, or the layout was
-        # extracted out-of-band).
-        manifest_path = (
-            tmp_path / ".specify" / "integrations" / "speckit.manifest.json"
-        )
-        manifest_path.unlink()
-
-        # Second run — every file already exists, so every iteration takes
-        # the skip branch. With the fix, those files are still recorded.
-        install_shared_infra(
-            tmp_path,
-            "sh",
-            version="0.0.0",
-            core_pack=None,
-            repo_root=repo_root,
-            console=console,
-            force=False,
-        )
-        second_files = self._read_manifest_files(tmp_path)
-        assert second_files, (
-            "speckit.manifest.json files dict is empty after install with "
-            "skipped files (issue #2107) — every file went down the skip "
-            "branch but none were recorded"
-        )
-
-        # The recovered manifest must cover everything the first run tracked.
-        missing = set(first_files) - set(second_files)
-        assert not missing, (
-            f"these files were tracked on the first install but missing after "
-            f"the skipped-files re-install: {sorted(missing)[:5]}"
-        )
-
-    def test_install_shared_infra_handles_directory_at_script_destination(
-        self, tmp_path
-    ):
-        """A non-file (directory) at a script's destination must NOT crash
-        ``install_shared_infra`` and must NOT be recorded in the manifest —
-        the path still appears in the user-visible skipped-paths warning.
-        """
-        from io import StringIO
-        from rich.console import Console
-        from specify_cli.shared_infra import install_shared_infra
-
-        repo_root = Path(__file__).resolve().parents[2]
-        output = StringIO()
-        console = Console(file=output, force_terminal=False, width=200)
-
-        # Pre-create the .specify/scripts/bash tree, then plant a directory
-        # where a script file is expected so the skip branch hits a
-        # non-regular-file path.
-        bash_dir = tmp_path / ".specify" / "scripts" / "bash"
-        bash_dir.mkdir(parents=True)
-        (bash_dir / "common.sh").mkdir()  # collision: dir where file expected
-
-        # Must not crash.
-        install_shared_infra(
-            tmp_path,
-            "sh",
-            version="0.0.0",
-            core_pack=None,
-            repo_root=repo_root,
-            console=console,
-            force=False,
-        )
-
-        files = self._read_manifest_files(tmp_path)
-        assert ".specify/scripts/bash/common.sh" not in files, (
-            "directory at script dst must not be recorded in the manifest"
-        )
-        text = output.getvalue()
-        assert "common.sh" in text, (
-            "directory-at-script-dst path must surface in the skipped warning"
-        )
-
-    def test_install_shared_infra_handles_directory_at_template_destination(
-        self, tmp_path
-    ):
-        """Symmetric coverage for the templates loop: a directory at a
-        template's destination must NOT crash install nor be recorded."""
-        from io import StringIO
-        from rich.console import Console
-        from specify_cli.shared_infra import install_shared_infra
-
-        repo_root = Path(__file__).resolve().parents[2]
-        output = StringIO()
-        console = Console(file=output, force_terminal=False, width=200)
-
-        templates_dir = tmp_path / ".specify" / "templates"
-        templates_dir.mkdir(parents=True)
-
-        src_templates = repo_root / "templates"
-        real_template = next(
-            (
-                p.name
-                for p in src_templates.iterdir()
-                if p.is_file()
-                and not p.name.startswith(".")
-                and p.name != "vscode-settings.json"
-            ),
-            None,
-        )
-        assert real_template, (
-            "no real template found in repo to collide against"
-        )
-        (templates_dir / real_template).mkdir()  # collision
-
-        install_shared_infra(
-            tmp_path,
-            "sh",
-            version="0.0.0",
-            core_pack=None,
-            repo_root=repo_root,
-            console=console,
-            force=False,
-        )
-
-        files = self._read_manifest_files(tmp_path)
-        template_rel = f".specify/templates/{real_template}"
-        assert template_rel not in files, (
-            "directory at template dst must not be recorded in manifest"
-        )
-        text = output.getvalue()
-        assert real_template in text, (
-            "directory-at-template-dst path must surface in the skipped warning"
-        )

tests/integrations/test_integration_copilot.py

@@ -426,8 +426,8 @@ class TestCopilotSkillsMode:
 
     # -- Copilot-specific post-processing ---------------------------------
 
-    def test_post_process_skill_content_does_not_inject_mode(self):
-        """post_process_skill_content() must NOT inject mode: — VS Code Copilot does not support it."""
+    def test_post_process_skill_content_injects_mode(self):
+        """post_process_skill_content() should inject mode: field."""
         copilot = self._make_copilot()
         content = (
             "---\n"
@@ -437,10 +437,10 @@ class TestCopilotSkillsMode:
             "\nBody content\n"
         )
         updated = copilot.post_process_skill_content(content)
-        assert "mode:" not in updated
+        assert "mode: speckit.plan" in updated
 
     def test_post_process_skill_content_injects_hook_note(self):
-        """post_process_skill_content() should inject shared hook guidance but not mode:."""
+        """post_process_skill_content() should inject shared hook guidance."""
         copilot = self._make_copilot()
         content = (
             "---\n"
@@ -451,7 +451,7 @@ class TestCopilotSkillsMode:
         )
         updated = copilot.post_process_skill_content(content)
         assert "replace dots" in updated
-        assert "mode:" not in updated
+        assert "mode: speckit.specify" in updated
 
     def test_post_process_idempotent(self):
         """post_process_skill_content() must be idempotent."""
@@ -467,8 +467,8 @@ class TestCopilotSkillsMode:
         second = copilot.post_process_skill_content(first)
         assert first == second
 
-    def test_skills_do_not_have_mode_in_frontmatter(self, tmp_path):
-        """Generated SKILL.md files must NOT contain mode: — VS Code Copilot does not support it."""
+    def test_skills_have_mode_in_frontmatter(self, tmp_path):
+        """Generated SKILL.md files should have mode: field from post-processing."""
         copilot = self._make_copilot()
         created, _ = self._setup_skills(copilot, tmp_path)
         skill_files = [f for f in created if f.name == "SKILL.md"]
@@ -477,7 +477,11 @@ class TestCopilotSkillsMode:
             content = f.read_text(encoding="utf-8")
             parts = content.split("---", 2)
             fm = yaml.safe_load(parts[1])
-            assert "mode" not in fm, f"{f} frontmatter must not contain unsupported 'mode' field"
+            assert "mode" in fm, f"{f} frontmatter missing 'mode'"
+            # mode should be speckit.<stem>
+            skill_dir_name = f.parent.name
+            stem = skill_dir_name.removeprefix("speckit-")
+            assert fm["mode"] == f"speckit.{stem}"
 
     def test_skills_hook_sections_explain_dotted_command_conversion(self, tmp_path):
         """Generated skills with hook sections should include shared hook guidance."""

tests/integrations/test_integration_subcommand.py

@@ -242,9 +242,9 @@ class TestIntegrationInstall:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli.integrations._commands as _int_cmds
+        import specify_cli
 
-        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "install", "codex",
@@ -898,10 +898,11 @@ class TestIntegrationSwitch:
         assert copilot_git_feature.exists(), "Git extension skill should exist for Copilot skills mode"
         assert not copilot_agent_file.exists(), "Copilot skills mode should not create extension .agent.md files"
 
-        # Verify Copilot skill frontmatter does NOT contain mode: — VS Code Copilot does not support it
+        # Verify Copilot-specific frontmatter: mode field should map from
+        # skill name (speckit-git-feature) back to dot notation (speckit.git-feature)
         skill_content = copilot_git_feature.read_text(encoding="utf-8")
-        assert "mode:" not in skill_content, (
-            "Copilot skill frontmatter must not contain unsupported 'mode' field"
+        assert "mode: speckit.git-feature" in skill_content, (
+            "Copilot skill frontmatter should contain mode mapped from skill name"
         )
 
         registry = json.loads(
@@ -1209,9 +1210,9 @@ class TestIntegrationUpgrade:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli.integrations._commands as _int_cmds
+        import specify_cli
 
-        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "upgrade", "claude",
@@ -1235,9 +1236,9 @@ class TestIntegrationUpgrade:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli.integrations._commands as _int_cmds
+        import specify_cli
 
-        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "upgrade", "claude",
@@ -1471,7 +1472,7 @@ class TestScriptTypeValidation:
 class TestParseIntegrationOptionsEqualsForm:
     def test_equals_form_parsed(self):
         """--commands-dir=./x should be parsed the same as --commands-dir ./x."""
-        from specify_cli.integrations._commands import _parse_integration_options
+        from specify_cli import _parse_integration_options
         from specify_cli.integrations import get_integration
 
         integration = get_integration("generic")

tests/integrations/test_manifest.py

@@ -34,57 +34,6 @@ class TestManifestRecordFile:
         assert m.files["existing.txt"] == _sha256(f)
 
 
-class TestManifestRecordExistingErrors:
-    """Error-case coverage for ``record_existing`` symlink + non-file guards.
-
-    Added in #2483 — Copilot review flagged these as un-tested regressions
-    after the ``is_symlink``/``is_file`` guards were introduced.
-    """
-
-    def test_rejects_symlink_target(self, tmp_path):
-        target = tmp_path / "target.txt"
-        target.write_text("target content", encoding="utf-8")
-        link = tmp_path / "link.txt"
-        link.symlink_to(target)
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match="symlinked"):
-            m.record_existing("link.txt")
-
-    def test_rejects_dangling_symlink(self, tmp_path):
-        # A symlink pointing nowhere should still be rejected before the
-        # ``is_file()`` check (which would itself be False on a dangler).
-        link = tmp_path / "dangler.txt"
-        link.symlink_to(tmp_path / "no-such-target.txt")
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match="symlinked"):
-            m.record_existing("dangler.txt")
-
-    def test_rejects_directory_path(self, tmp_path):
-        (tmp_path / "a_dir").mkdir()
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match="not a regular file"):
-            m.record_existing("a_dir")
-
-    def test_rejects_missing_path(self, tmp_path):
-        # ``is_file()`` is False for non-existent paths too; the same error
-        # surface keeps callers from having to distinguish "missing" from
-        # "wrong kind" — both mean "cannot hash this".
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match="not a regular file"):
-            m.record_existing("never-existed.txt")
-
-    def test_lexical_prevalidation_for_absolute_path(self, tmp_path):
-        # ``record_existing`` must reject absolute paths via the lexical
-        # pre-check, NOT via the filesystem-touching ``is_symlink()`` call.
-        # Verified by passing an absolute path that points to a directory
-        # outside the project root — the canonical "Absolute paths" error
-        # must surface before any stat on the absolute path.
-        m = IntegrationManifest("test", tmp_path)
-        abs_path = "C:\\tmp\\escape.txt" if sys.platform == "win32" else "/tmp/escape.txt"
-        with pytest.raises(ValueError, match="Absolute paths"):
-            m.record_existing(abs_path)
-
-
 class TestManifestPathTraversal:
     def test_record_file_rejects_parent_traversal(self, tmp_path):
         m = IntegrationManifest("test", tmp_path)
@@ -296,160 +245,3 @@ class TestManifestLoadValidation:
         path.write_text("{not valid json", encoding="utf-8")
         with pytest.raises(ValueError, match="invalid JSON"):
             IntegrationManifest.load("bad", tmp_path)
-
-    def test_load_filters_recovered_files_not_in_files(self, tmp_path):
-        # Finding B (Round-9): a recovered_files entry referencing a path
-        # not present in files indicates an internally-inconsistent manifest
-        # (e.g. external edit). load() filters those entries silently so the
-        # manifest self-heals on next save(); is_recovered then returns the
-        # truthful False for the orphan.
-        path = tmp_path / ".specify" / "integrations" / "test.manifest.json"
-        path.parent.mkdir(parents=True)
-        path.write_text(json.dumps({
-            "integration": "test",
-            "files": {"kept.txt": "abc123"},
-            "recovered_files": ["kept.txt", "orphan.txt"],
-        }), encoding="utf-8")
-        m = IntegrationManifest.load("test", tmp_path)
-        assert m.recovered_files == {"kept.txt"}
-        assert m.is_recovered("kept.txt") is True
-        assert m.is_recovered("orphan.txt") is False
-
-
-class TestManifestRecoveredFiles:
-    """Coverage for the ``recovered_files`` channel added in #2483.
-
-    When ``shared_infra`` skips an existing file (because the user already has
-    it on disk) it now records the file with ``recovered=True``. The path
-    appears in ``manifest.recovered_files`` and ``is_recovered(path)`` returns
-    True. ``refresh_managed`` (out of scope for this PR) consults this list
-    before treating the recorded hash as a managed baseline, defending against
-    silent overwrite of user customizations after manifest loss.
-    """
-
-    def test_record_existing_default_is_not_recovered(self, tmp_path):
-        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("f.txt")
-        assert m.is_recovered("f.txt") is False
-        assert m.recovered_files == set()
-
-    def test_record_existing_with_recovered_flag(self, tmp_path):
-        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("f.txt", recovered=True)
-        assert m.is_recovered("f.txt") is True
-        assert m.recovered_files == {"f.txt"}
-        # File still hashed normally so check_modified/uninstall keep working
-        assert m.files["f.txt"] == _sha256(tmp_path / "f.txt")
-
-    def test_recovered_files_round_trips_through_save_load(self, tmp_path):
-        (tmp_path / "a.txt").write_text("aaa", encoding="utf-8")
-        (tmp_path / "b.txt").write_text("bbb", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path, version="9.9")
-        m.record_existing("a.txt", recovered=True)
-        m.record_existing("b.txt")  # not recovered
-        m.save()
-        loaded = IntegrationManifest.load("test", tmp_path)
-        assert loaded.is_recovered("a.txt") is True
-        assert loaded.is_recovered("b.txt") is False
-        assert loaded.recovered_files == {"a.txt"}
-
-    def test_save_omits_empty_recovered_files(self, tmp_path):
-        m = IntegrationManifest("test", tmp_path)
-        m.record_file("f.txt", "x")
-        path = m.save()
-        data = json.loads(path.read_text(encoding="utf-8"))
-        assert "recovered_files" not in data
-
-    def test_load_rejects_non_list_recovered_files(self, tmp_path):
-        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
-        path.parent.mkdir(parents=True)
-        path.write_text(
-            json.dumps({"files": {}, "recovered_files": "not-a-list"}),
-            encoding="utf-8",
-        )
-        with pytest.raises(ValueError, match="recovered_files"):
-            IntegrationManifest.load("bad", tmp_path)
-
-    def test_is_recovered_absolute_path_returns_false(self, tmp_path):
-        # Copilot round-5 finding: passing an absolute path silently returned
-        # False because the stored keys are relative POSIX strings. Round-7
-        # made this explicit: ``is_recovered`` now rejects absolute paths
-        # up front via a lexical ``rel.is_absolute()`` guard and returns
-        # False without calling ``_validate_rel_path`` at all — matching
-        # ``record_existing``'s canonical-key guard so the two methods
-        # agree on which inputs can ever be stored keys.
-        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("f.txt", recovered=True)
-        import sys
-        abs_input = "C:\\tmp\\f.txt" if sys.platform == "win32" else "/tmp/f.txt"
-        assert m.is_recovered(abs_input) is False
-
-    def test_is_recovered_escaping_path_returns_false(self, tmp_path):
-        # A relative path containing ``..`` segments cannot be a stored key:
-        # Round-7 added the same lexical ``".." in rel.parts`` guard to
-        # ``is_recovered`` that ``record_existing`` already enforces, so the
-        # method returns False immediately without reaching
-        # ``_validate_rel_path``. The try/except around ``_validate_rel_path``
-        # remains as defense-in-depth for paths that pass the lexical guard
-        # but still resolve outside the project root via a symlinked
-        # ancestor.
-        m = IntegrationManifest("test", tmp_path)
-        # Don't record anything — the path is impossible to record anyway.
-        assert m.is_recovered("../escape.txt") is False
-
-    def test_record_existing_clears_recovered_when_false(self, tmp_path):
-        # Finding A: re-recording the same path with recovered=False must
-        # drop the prior recovered marker (transition to managed baseline).
-        f = tmp_path / "x.txt"
-        f.write_text("v1", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("x.txt", recovered=True)
-        assert m.is_recovered("x.txt") is True
-        m.record_existing("x.txt", recovered=False)
-        assert m.is_recovered("x.txt") is False
-
-    def test_record_file_clears_recovered(self, tmp_path):
-        # Finding A: record_file writes produced content; the path can no
-        # longer be considered "merely observed" once we wrote bytes.
-        (tmp_path / "y.txt").write_text("observed", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("y.txt", recovered=True)
-        assert m.is_recovered("y.txt") is True
-        m.record_file("y.txt", "produced")
-        assert m.is_recovered("y.txt") is False
-
-    def test_is_recovered_rejects_dotdot_segment(self, tmp_path):
-        # Finding B: record_existing rejects ``..`` segments via the lexical
-        # pre-check; is_recovered must match that behavior and return False
-        # without raising, mirroring the canonicalization guard.
-        (tmp_path / "z.txt").write_text("v1", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        m.record_existing("z.txt", recovered=True)
-        # Same file via dotdot-normalizing path — must be False, not raise.
-        assert m.is_recovered("subdir/../z.txt") is False
-
-
-class TestRecordExistingNewGuards:
-    """Coverage for the two new guards added by Copilot's 2026-05-18 review."""
-
-    def test_rejects_symlinked_ancestor(self, tmp_path):
-        real_dir = tmp_path / "real_dir"
-        real_dir.mkdir()
-        (real_dir / "file.txt").write_text("payload", encoding="utf-8")
-        (tmp_path / "linked_dir").symlink_to(real_dir, target_is_directory=True)
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match="symlinked"):
-            m.record_existing("linked_dir/file.txt")
-
-    def test_rejects_inside_root_dotdot_with_explicit_message(self, tmp_path):
-        # ``dir/../file.txt`` normalizes inside root, so the old "escapes
-        # project root" message was misleading. The new message names the
-        # actual reason: canonicalization.
-        (tmp_path / "dir").mkdir()
-        (tmp_path / "file.txt").write_text("x", encoding="utf-8")
-        m = IntegrationManifest("test", tmp_path)
-        with pytest.raises(ValueError, match=r"canonical|'\.\.' segments"):
-            m.record_existing("dir/../file.txt")

tests/test_commands_package.py

@@ -13,6 +13,12 @@ def test_commands_init_importable():
     assert callable(mod.register)
 
 
+def test_commands_stubs_importable():
+    for name in ("integration", "preset", "extension", "workflow"):
+        mod = importlib.import_module(f"specify_cli.commands.{name}")
+        assert mod is not None
+
+
 def test_agent_config_importable():
     from specify_cli._agent_config import (
         AGENT_CONFIG,

tests/test_extensions.py

@@ -2804,33 +2804,17 @@ class TestExtensionCatalog:
             zf.writestr("extension.yml", "id: test-ext\nname: Test\nversion: 1.0.0\n")
         zip_bytes = zip_buf.getvalue()
 
-        release_response = MagicMock()
-        release_response.read.return_value = json.dumps(
-            {
-                "assets": [
-                    {
-                        "name": "test-ext.zip",
-                        "url": "https://api.github.com/repos/org/repo/releases/assets/1",
-                    }
-                ]
-            }
-        ).encode()
-        release_response.__enter__ = lambda s: s
-        release_response.__exit__ = MagicMock(return_value=False)
+        mock_response = MagicMock()
+        mock_response.read.return_value = zip_bytes
+        mock_response.__enter__ = lambda s: s
+        mock_response.__exit__ = MagicMock(return_value=False)
 
-        asset_response = MagicMock()
-        asset_response.read.return_value = zip_bytes
-        asset_response.__enter__ = lambda s: s
-        asset_response.__exit__ = MagicMock(return_value=False)
-
-        captured = []
+        captured = {}
         mock_opener = MagicMock()
 
         def fake_open(req, timeout=None):
-            captured.append(req)
-            if req.full_url.endswith("/releases/tags/v1"):
-                return release_response
-            return asset_response
+            captured["req"] = req
+            return mock_response
 
         mock_opener.open.side_effect = fake_open
 
@@ -2845,56 +2829,7 @@ class TestExtensionCatalog:
              patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
             catalog.download_extension("test-ext", target_dir=temp_dir)
 
-        assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/tags/v1"
-        assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"
-        assert captured[1].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"
-        assert captured[1].get_header("Authorization") == "Bearer ghp_testtoken"
-        assert captured[1].get_header("Accept") == "application/octet-stream"
-
-    def test_download_extension_accepts_direct_github_rest_asset_url(self, temp_dir, monkeypatch):
-        """download_extension can use a GitHub REST release asset URL directly."""
-        from unittest.mock import patch, MagicMock
-        import zipfile
-        import io
-
-        monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")
-        self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
-        catalog = self._make_catalog(temp_dir)
-
-        zip_buf = io.BytesIO()
-        with zipfile.ZipFile(zip_buf, "w") as zf:
-            zf.writestr("extension.yml", "id: test-ext\nname: Test\nversion: 1.0.0\n")
-        zip_bytes = zip_buf.getvalue()
-
-        asset_response = MagicMock()
-        asset_response.read.return_value = zip_bytes
-        asset_response.__enter__ = lambda s: s
-        asset_response.__exit__ = MagicMock(return_value=False)
-
-        captured = []
-        mock_opener = MagicMock()
-
-        def fake_open(req, timeout=None):
-            captured.append(req)
-            return asset_response
-
-        mock_opener.open.side_effect = fake_open
-
-        ext_info = {
-            "id": "test-ext",
-            "name": "Test Extension",
-            "version": "1.0.0",
-            "download_url": "https://api.github.com/repos/org/repo/releases/assets/1",
-        }
-
-        with patch.object(catalog, "get_extension_info", return_value=ext_info), \
-             patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
-            catalog.download_extension("test-ext", target_dir=temp_dir)
-
-        assert len(captured) == 1
-        assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"
-        assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"
-        assert captured[0].get_header("Accept") == "application/octet-stream"
+        assert captured["req"].get_header("Authorization") == "Bearer ghp_testtoken"
 
 
 

tests/test_workflows.py

@@ -2379,306 +2379,6 @@ steps:
         assert state.step_results["stamp"]["output"]["stdout"].strip() == "explicit-456"
 
 
-# ===== continue_on_error Tests =====
-#
-# Locks the contract documented in workflows/README.md "Error Handling"
-# section: when a step returns `StepResult(status=StepStatus.FAILED, ...)` and
-# `continue_on_error: true` is declared, the engine records the step's
-# `output` (with `exit_code` and `stderr` from the failure) and its
-# `status` (sibling key on `steps.<id>`, not nested under `output`)
-# and continues to the next sibling step instead of halting the run.
-# Gate aborts (`output.aborted`) still halt regardless of the flag.
-# Unhandled exceptions raised out of `step_impl.execute()` are out of
-# scope for this flag — they propagate to `WorkflowEngine.execute()`
-# and abort the run.
-
-
-class TestContinueOnError:
-    """Test the `continue_on_error` step-level field."""
-
-    def test_undeclared_failure_halts_run(self, project_dir):
-        """Default behaviour (no `continue_on_error`): a failing step
-        halts the workflow run with `status == StepStatus.FAILED`.
-
-        Locks the byte-equivalent default — workflows that do not
-        declare the flag must behave exactly as before this feature.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "halt-on-fail"
-  name: "Halt On Fail"
-  version: "1.0.0"
-steps:
-  - id: fail-step
-    type: shell
-    run: "exit 7"
-  - id: after
-    type: shell
-    run: "echo should-not-run"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        assert state.status == RunStatus.FAILED
-        assert "fail-step" in state.step_results
-        assert state.step_results["fail-step"]["output"]["exit_code"] == 7
-        # Subsequent step never executes when the flag is absent.
-        assert "after" not in state.step_results
-
-    def test_declared_and_fired_continues_run(self, project_dir):
-        """`continue_on_error: true` + failing step: the run keeps
-        going, the failed step's result is recorded, and the
-        downstream step runs.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "continue-past-fail"
-  name: "Continue Past Fail"
-  version: "1.0.0"
-steps:
-  - id: flaky-step
-    type: shell
-    run: "exit 42"
-    continue_on_error: true
-  - id: after
-    type: shell
-    run: "echo did-run"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        assert state.status == RunStatus.COMPLETED
-        # Failed step's exit_code is preserved so downstream branching
-        # can inspect it.
-        assert state.step_results["flaky-step"]["output"]["exit_code"] == 42
-        assert state.step_results["flaky-step"]["status"] == "failed"
-        # Downstream step ran successfully.
-        assert state.step_results["after"]["output"]["exit_code"] == 0
-
-    def test_declared_but_step_succeeded_is_noop(self, project_dir):
-        """`continue_on_error: true` on a step that succeeds is a
-        no-op — the flag only changes behaviour on StepStatus.FAILED status.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "flag-but-success"
-  name: "Flag But Success"
-  version: "1.0.0"
-steps:
-  - id: ok-step
-    type: shell
-    run: "echo ok"
-    continue_on_error: true
-  - id: after
-    type: shell
-    run: "echo done"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        assert state.status == RunStatus.COMPLETED
-        assert state.step_results["ok-step"]["status"] == "completed"
-        assert state.step_results["ok-step"]["output"]["exit_code"] == 0
-        assert state.step_results["after"]["output"]["exit_code"] == 0
-
-    def test_if_branch_routes_around_failure(self, project_dir):
-        """End-to-end: `continue_on_error` + `if` cleanly routes around
-        a failure. The recovery branch runs; the success branch does
-        not.
-
-        Mirrors the canonical usage pattern from the original feature
-        discussion in issue #2591.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "route-around"
-  name: "Route Around Failure"
-  version: "1.0.0"
-steps:
-  - id: heavy-thing
-    type: shell
-    run: "exit 1"
-    continue_on_error: true
-  - id: check-result
-    type: if
-    condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
-    then:
-      - id: recovery
-        type: shell
-        run: "echo recovery-ran"
-    else:
-      - id: happy-path
-        type: shell
-        run: "echo happy-path-ran"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        assert state.status == RunStatus.COMPLETED
-        assert "recovery" in state.step_results
-        assert "happy-path" not in state.step_results
-
-    def test_gate_abort_still_halts_with_continue_on_error(
-        self, project_dir, monkeypatch
-    ):
-        """`continue_on_error` does NOT override a deliberate gate
-        abort. `output.aborted` always halts the run with
-        `status == ABORTED`.
-
-        Aborts are explicit operator decisions; continue_on_error
-        is for transient/expected step failures only.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-        from specify_cli.workflows.steps.gate import GateStep
-        from specify_cli.workflows.steps import gate as gate_module
-
-        # Force the gate step into interactive mode and feed a "reject"
-        # choice so the abort path actually runs in the test env
-        # (default behaviour returns StepStatus.PAUSED when stdin is not a TTY).
-        # Swap sys.stdin itself for a stub: setattr on the real
-        # TextIOWrapper's `isatty` method is not assignable under some
-        # runners (e.g. pytest with capture disabled).
-        class _TTYStdin:
-            def isatty(self) -> bool:
-                return True
-
-        monkeypatch.setattr(gate_module.sys, "stdin", _TTYStdin())
-        monkeypatch.setattr(
-            GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
-        )
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "gate-abort-halts"
-  name: "Gate Abort Halts"
-  version: "1.0.0"
-steps:
-  - id: gate-step
-    type: gate
-    message: "Approve?"
-    options: [approve, reject]
-    on_reject: abort
-    continue_on_error: true
-  - id: should-not-run
-    type: shell
-    run: "echo nope"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        assert state.status == RunStatus.ABORTED
-        assert "should-not-run" not in state.step_results
-
-    def test_validation_rejects_non_bool_continue_on_error(self):
-        """`continue_on_error` must be a literal boolean; coerced
-        strings like `"true"` are rejected at validation time so
-        authoring mistakes surface before execution.
-        """
-        from specify_cli.workflows.engine import (
-            WorkflowDefinition,
-            validate_workflow,
-        )
-
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "bad-coe"
-  name: "Bad COE"
-  version: "1.0.0"
-steps:
-  - id: step-one
-    type: shell
-    run: "true"
-    continue_on_error: "true"
-""")
-        errors = validate_workflow(definition)
-        assert any(
-            "continue_on_error" in e and "boolean" in e for e in errors
-        ), errors
-
-    def test_validation_accepts_bool_continue_on_error(self):
-        """Boolean values pass validation cleanly."""
-        from specify_cli.workflows.engine import (
-            WorkflowDefinition,
-            validate_workflow,
-        )
-
-        for value in (True, False):
-            yaml_value = "true" if value else "false"
-            definition = WorkflowDefinition.from_string(f"""
-schema_version: "1.0"
-workflow:
-  id: "good-coe"
-  name: "Good COE"
-  version: "1.0.0"
-steps:
-  - id: step-one
-    type: shell
-    run: "true"
-    continue_on_error: {yaml_value}
-""")
-            errors = validate_workflow(definition)
-            assert errors == [], errors
-
-    def test_engine_ignores_truthy_non_bool_continue_on_error(self, project_dir):
-        """Defense-in-depth: even if a caller bypasses
-        `validate_workflow()` and feeds the engine a definition with
-        `continue_on_error: "true"` (a string), the engine must NOT
-        honour the flag — only a literal boolean enables the
-        behaviour. `WorkflowEngine.execute()` does not auto-validate
-        (the `WorkflowEngine.load_workflow` docstring explicitly
-        notes the definition is "not yet validated; call
-        `validate_workflow()` or `engine.validate()` separately"),
-        so the engine guards against truthy non-bool values itself
-        via an identity check rather than truthiness.
-        """
-        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
-        from specify_cli.workflows.base import RunStatus
-
-        # Bypass `validate_workflow()` — execute() is what would
-        # be called by a caller that skipped validation.
-        definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: "string-coe"
-  name: "String COE"
-  version: "1.0.0"
-steps:
-  - id: fail-step
-    type: shell
-    run: "exit 1"
-    continue_on_error: "true"
-  - id: should-not-run
-    type: shell
-    run: "echo should-not-run"
-""")
-        engine = WorkflowEngine(project_dir)
-        state = engine.execute(definition)
-
-        # String "true" is truthy but not a literal boolean, so the
-        # engine must treat the step as a halting failure.
-        assert state.status == RunStatus.FAILED
-        assert "should-not-run" not in state.step_results
-
-
 # ===== State Persistence Tests =====
 
 class TestRunState:

workflows/README.md

@@ -219,83 +219,6 @@ Aggregate results from fan-out steps:
   output: {}
 ```
 
-## Error Handling
-
-By default, any step that returns `StepResult(status=StepStatus.FAILED, ...)`
-at runtime halts the entire run — most commonly a `shell` or
-`command` step exiting non-zero. Set `continue_on_error: true` on
-a step to record its result and continue to the next sibling step
-instead. When the failure was a non-zero exit, the exit code
-remains available on `steps.<id>.output.exit_code` so a downstream
-`if` or `switch` can branch on it (or a `gate` can surface it to
-the operator via `{{ }}` interpolation in `message`):
-
-```yaml
-- id: heavy-thing
-  type: command
-  integration: claude
-  command: speckit.heavy-thing
-  continue_on_error: true
-
-- id: check-result
-  type: if
-  condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
-  then:
-    - id: review
-      type: gate
-      message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to run the recovery path, or reject to leave the failure recorded and move on."
-      on_reject: skip
-    - id: recover
-      type: if
-      condition: "{{ steps.review.output.choice == 'approve' }}"
-      then:
-        - id: rerun
-          command: speckit.recovery
-  else:
-    - id: next-thing
-      command: speckit.next-thing
-```
-
-A few things worth knowing about that example:
-
-- Both gate options (`approve`, `reject`) return `StepStatus.COMPLETED`;
-  `on_reject: skip` controls only whether the engine aborts on reject
-  (it doesn't, with `skip`) — it does **not** auto-skip subsequent
-  sibling steps in the `then:` list. Downstream branching is the
-  workflow author's responsibility: read
-  `{{ steps.<gate-id>.output.choice }}` in a follow-up `if`, `switch`,
-  or expression, as the `recover` step above does.
-- `on_reject` has three values: `abort` (default — reject → `StepStatus.FAILED`
-  with `output.aborted = True`, halts the run), `skip` (reject →
-  `StepStatus.COMPLETED`, author handles branching as shown), and `retry`
-  (reject → `StepStatus.PAUSED` so the next `specify workflow resume` re-runs
-  the gate).
-- Gates do not automatically re-run the failed step. To express a
-  retry path, either define custom gate options and branch on the
-  choice downstream, or wrap the failing step in your own loop.
-
-**Notes:**
-
-- The field must be a literal boolean (`true` / `false`); coerced
-  strings like `"true"` are rejected at validation time.
-- **Scope: returned failures only.** The flag applies to step results
-  with `status=StepStatus.FAILED`. Unhandled exceptions raised out of a step's
-  `execute()` method are caught one level up by `WorkflowEngine.execute()`,
-  logged as `workflow_failed`, and abort the run regardless of
-  `continue_on_error`. If a step author wants the flag to cover an
-  exceptional path, the step must catch the exception internally and
-  return `StepResult(status=StepStatus.FAILED, ...)` with the failure encoded in
-  `output` (e.g. `exit_code`, `stderr`, or a custom field).
-- Gate aborts (`on_reject: abort` chosen by the operator) always halt
-  the run — `continue_on_error` does not override them. The flag is
-  for transient/expected step failures, not for overriding deliberate
-  operator decisions.
-- Structural validation runs up-front: `specify workflow run` rejects
-  invalid workflow definitions before the run is created, so
-  validation failures never reach this code path.
-- When the flag is omitted, behaviour is byte-equivalent to before
-  this feature.
-
 ## Expressions
 
 Workflow definitions use `{{ expression }}` syntax for dynamic values: