feat(integration): add status reporting (#2674)

* feat(integration): add status reporting

* docs(integration): include status in query command docstring

* fix(integration): handle Windows extended-length paths in status containment

On Windows, os.readlink() (and sometimes Path.resolve()) return paths with
the \\?\ extended-length prefix. Comparing such a target against a plain
project root via Path.relative_to() spuriously fails, so an in-project
dangling symlink was classified as `invalid` instead of `missing` — failing
test_status_treats_dangling_symlink_as_missing and the windows-style variant
on the Windows CI runners.

Centralize the containment check in _is_within_project() and strip the
\\?\ / \\?\UNC\ prefix from both sides before relative_to(). Add portable
regression tests for the prefix-stripping helper and the containment contract.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* test(integration): restore top-level pytest import after rebase

A three-way merge / rebase onto main silently dropped the module-level
`import pytest` from test_integration_subcommand.py: main reorganized the
import block without it (using only a local `import pytest as _pytest`),
while this branch added top-level fixtures and `pytest.skip`/`pytest.raises`
usage. The overlapping import-hunk edits resolved by dropping the import,
breaking collection with `NameError: name 'pytest' is not defined` on every
runner. Re-add the import in the third-party group.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(integration): fix Windows UNC path assertion in status helper test

`test_strip_extended_length_prefix_normalizes_windows_paths` compared the
str() form of the helper's output against a hand-built string. On Windows,
pathlib renders a UNC root with a trailing separator (`\\server\share\`),
so the exact string match failed there (`\\server\share\` != `\\server\share`)
even though `_strip_extended_length_prefix` behaves correctly — the trailing
separator is irrelevant to the `relative_to` containment check it feeds.

Compare Path objects (semantic equality) instead of exact strings so the
assertion holds on both POSIX and Windows. No production code change needed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(integration): make shared-manifest remediation specify --integration

The fallback `_manifest_suggestion` for the shared `speckit` manifest (used
when no usable default integration is recorded) suggested
`specify init --here --force`, which can trigger interactive integration
selection. For CI/agent consumers of `integration status`, surface an
explicit `--integration <key>` placeholder, matching the file's existing
`<key>` suggestion style.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

docs/reference/integrations.md

@@ -126,6 +126,27 @@ specify integration upgrade [<key>]
 
 Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. Detects locally modified files and blocks the upgrade unless `--force` is used. Stale files from the previous install that are no longer needed are removed automatically. Shared templates stay aligned with the default integration even when upgrading a non-default integration.
 
+## Report Integration Status
+
+```bash
+specify integration status
+specify integration status --json
+```
+
+Reports the current project's integration status without changing files. The
+status report includes the default integration, installed integrations,
+multi-install safety, missing managed files, modified managed files, invalid
+manifest paths, shared Spec Kit infrastructure health, unchecked manifests, and
+the target integration for default-sensitive shared templates. The JSON form is
+intended for CI and coding agents that need stable machine-readable status data;
+it also reports the raw recorded integrations and the integration manifests that
+were checked when state repair heuristics differ from the recorded file.
+The command exits 0 when the report status is `ok` or `warning`; it exits 1
+only when the report status is `error`. In JSON output, `multi_install_safe`
+is `null` when no installed integration set can be evaluated, such as when the
+integration state is missing, unreadable, lacks a valid recorded integration
+list, or records no installed integrations.
+
 ## Integration-Specific Options
 
 Some integrations accept additional options via `--integration-options`:

src/specify_cli/integration_state.py

@@ -25,17 +25,14 @@ class IntegrationReadError:
     schema: int | None = None
 
 
-def try_read_integration_json(
+def _read_integration_json_data(
     project_root: Path,
 ) -> tuple[dict[str, Any] | None, IntegrationReadError | None]:
-    """Parse ``.specify/integration.json`` without raising.
+    """Read raw integration state without normalizing or raising.
 
-    Returns ``(normalized_state, None)`` on success, ``(None, None)`` when the
-    file does not exist, or ``(None, error)`` for any parse / validation
-    failure. This is the single low-level reader; both the CLI's loud
-    ``_read_integration_json`` and the workflow engine's silent
-    ``_load_project_integration`` consume it so the schema guard and parse
-    logic cannot drift between them.
+    Returns ``(data, None)`` when the JSON object is readable and supported,
+    ``(None, None)`` when the file is absent, and ``(None, error)`` for parse,
+    schema, encoding, or filesystem failures.
     """
     path = project_root / INTEGRATION_JSON
     # Avoid Path.exists() / Path.is_file() as a pre-check: both return False
@@ -70,9 +67,41 @@ def try_read_integration_json(
         and schema > INTEGRATION_STATE_SCHEMA
     ):
         return None, IntegrationReadError(kind="schema_too_new", schema=schema)
+    return data, None
+
+
+def try_read_integration_json(
+    project_root: Path,
+) -> tuple[dict[str, Any] | None, IntegrationReadError | None]:
+    """Parse ``.specify/integration.json`` without raising.
+
+    Returns ``(normalized_state, None)`` on success, ``(None, None)`` when the
+    file does not exist, or ``(None, error)`` for any parse / validation
+    failure. This helper delegates file I/O and raw JSON validation to
+    ``_read_integration_json_data`` so callers that need raw state can share
+    the same low-level reader instead of duplicating parse logic.
+    """
+    data, error = _read_integration_json_data(project_root)
+    if data is None:
+        return None, error
     return normalize_integration_state(data), None
 
 
+def try_read_integration_json_with_raw(
+    project_root: Path,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None, IntegrationReadError | None]:
+    """Parse ``integration.json`` and return normalized plus raw state.
+
+    Returns ``(normalized_state, raw_state, None)`` when the file is readable,
+    ``(None, None, None)`` when it is absent, and ``(None, None, error)`` for
+    parse, schema, encoding, or filesystem failures.
+    """
+    data, error = _read_integration_json_data(project_root)
+    if data is None:
+        return None, None, error
+    return normalize_integration_state(data), data, None
+
+
 def clean_integration_key(key: Any) -> str | None:
     """Return a stripped integration key, or None for empty/non-string values."""
     if not isinstance(key, str) or not key.strip():

src/specify_cli/integration_status.py

@@ -0,0 +1,663 @@
+"""Read-only status reporting for project integration state."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import stat
+from pathlib import Path
+from typing import Any
+
+from .integration_state import (
+    INTEGRATION_JSON,
+    INTEGRATION_STATE_SCHEMA,
+    IntegrationReadError,
+    default_integration_key,
+    installed_integration_keys,
+    try_read_integration_json_with_raw,
+)
+from .integrations import INTEGRATION_REGISTRY
+from .integrations.manifest import IntegrationManifest
+
+_MANIFEST_READ_ERRORS = (ValueError, OSError)
+_MANIFEST_KEY_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_WINDOWS_RESERVED_MANIFEST_BASENAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+_SHARED_MANIFEST_KEY = "speckit"
+
+
+def _finding(
+    severity: str,
+    code: str,
+    message: str,
+    *,
+    integration: str | None = None,
+    path: str | None = None,
+    suggestion: str | None = None,
+) -> dict[str, str]:
+    item = {
+        "severity": severity,
+        "code": code,
+        "message": message,
+    }
+    if integration:
+        item["integration"] = integration
+    if path:
+        item["path"] = path
+    if suggestion:
+        item["suggestion"] = suggestion
+    return item
+
+
+def _status(findings: list[dict[str, str]]) -> str:
+    if any(item["severity"] == "error" for item in findings):
+        return "error"
+    if findings:
+        return "warning"
+    return "ok"
+
+
+def _with_error_detail(message: str, error: IntegrationReadError) -> str:
+    if error.detail:
+        return f"{message} Detail: {error.detail}"
+    return message
+
+
+def _integration_state_error_message(error: IntegrationReadError) -> str:
+    if error.kind == "decode":
+        return _with_error_detail(
+            f"{INTEGRATION_JSON} contains invalid JSON or is not valid UTF-8.",
+            error,
+        )
+    if error.kind == "os":
+        return _with_error_detail(f"Could not read {INTEGRATION_JSON}.", error)
+    if error.kind == "not_object":
+        return f"{INTEGRATION_JSON} must contain a JSON object, got {error.detail}."
+    if error.kind == "schema_too_new":
+        return (
+            f"{INTEGRATION_JSON} uses integration state schema {error.schema}, "
+            f"which is newer than this CLI supports; supported schema: {INTEGRATION_STATE_SCHEMA}."
+        )
+    return f"Could not inspect {INTEGRATION_JSON}."
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _strip_extended_length_prefix(path: Path) -> Path:
+    """Drop the Windows ``\\\\?\\`` extended-length prefix for path comparison.
+
+    ``os.readlink`` and ``Path.resolve`` can return extended-length paths on
+    Windows (e.g. ``\\\\?\\C:\\proj``). Comparing such a path against a plain
+    ``C:\\proj`` root via :meth:`Path.relative_to` would spuriously fail, so we
+    normalise both sides through this helper before containment checks.
+    """
+    raw = str(path)
+    if raw.startswith("\\\\?\\UNC\\"):
+        return Path("\\\\" + raw[len("\\\\?\\UNC\\"):])
+    if raw.startswith("\\\\?\\"):
+        return Path(raw[len("\\\\?\\"):])
+    return path
+
+
+def _is_within_project(project_root_resolved: Path, candidate: Path) -> bool:
+    """Return ``True`` when *candidate* stays within *project_root_resolved*.
+
+    Both paths are stripped of any Windows extended-length prefix first so that
+    a target produced by ``os.readlink`` (which may be ``\\\\?\\``-prefixed) is
+    still recognised as living inside an unprefixed project root.
+    """
+    try:
+        _strip_extended_length_prefix(candidate).relative_to(
+            _strip_extended_length_prefix(project_root_resolved)
+        )
+    except ValueError:
+        return False
+    return True
+
+
+def _safe_manifest_file(
+    project_root: Path,
+    project_root_resolved: Path,
+    rel: str,
+    *,
+    project_root_is_resolved: bool = True,
+) -> Path | None:
+    rel_path = Path(rel)
+    if rel_path.is_absolute() or ".." in rel_path.parts:
+        return None
+    candidate = project_root / rel_path
+    if not project_root_is_resolved:
+        walk = project_root
+        for part in rel_path.parts[:-1]:
+            walk = walk / part
+            try:
+                if walk.is_symlink():
+                    return None
+            except OSError:
+                return None
+    try:
+        candidate_parent = (
+            candidate.parent.resolve(strict=False)
+            if project_root_is_resolved
+            else candidate.parent.absolute()
+        )
+    except (OSError, RuntimeError):
+        return None
+    if not _is_within_project(project_root_resolved, candidate_parent):
+        return None
+    return candidate
+
+
+def _tracked_symlink_manifest_status(
+    path: Path,
+    project_root_resolved: Path,
+    *,
+    project_root_is_resolved: bool = True,
+) -> str:
+    """Classify a tracked symlink without following it outside the project.
+
+    Manifests store content hashes for regular files, so an existing in-project
+    symlink is still reported as modified. Escaping targets are invalid, and
+    dangling in-project targets are missing.
+    """
+    try:
+        target = path.readlink()
+    except OSError:
+        return "modified"
+
+    target_path = target if target.is_absolute() else path.parent / target
+    try:
+        contained_parent = (
+            target_path.parent.resolve(strict=False)
+            if project_root_is_resolved
+            else target_path.parent.absolute()
+        )
+    except (OSError, RuntimeError):
+        return "invalid"
+    if not _is_within_project(project_root_resolved, contained_parent):
+        return "invalid"
+
+    try:
+        target_path.lstat()
+    except FileNotFoundError:
+        return "missing"
+    except OSError:
+        return "modified"
+    return "modified"
+
+
+def _resolve_project_root_for_status(
+    project_root: Path,
+    findings: list[dict[str, str]],
+) -> tuple[Path, bool]:
+    try:
+        return project_root.resolve(), True
+    except (OSError, RuntimeError) as exc:
+        findings.append(
+            _finding(
+                "warning",
+                "project-root-unresolved",
+                f"Could not fully resolve project root: {exc}",
+                suggestion="Check project path permissions and symlinks before relying on manifest path checks.",
+            )
+        )
+        return project_root.absolute(), False
+
+
+def _is_safe_manifest_key(key: str) -> bool:
+    if key in {"", ".", ".."}:
+        return False
+    if key.endswith("."):
+        return False
+    if _MANIFEST_KEY_RE.fullmatch(key) is None:
+        return False
+    if key.split(".", 1)[0].upper() in _WINDOWS_RESERVED_MANIFEST_BASENAMES:
+        return False
+    if "/" in key or "\\" in key:
+        return False
+    key_path = Path(key)
+    return not key_path.is_absolute() and key_path.name == key
+
+
+def _manifest_file_status(
+    manifest: IntegrationManifest,
+    project_root_resolved: Path,
+    *,
+    project_root_is_resolved: bool = True,
+) -> tuple[list[str], list[str], list[str], list[str]]:
+    missing: list[str] = []
+    modified: list[str] = []
+    invalid: list[str] = []
+    valid: list[str] = []
+
+    for rel, expected_hash in manifest.files.items():
+        path = _safe_manifest_file(
+            manifest.project_root,
+            project_root_resolved,
+            rel,
+            project_root_is_resolved=project_root_is_resolved,
+        )
+        if path is None:
+            invalid.append(rel)
+            continue
+        try:
+            path_stat = path.lstat()
+        except FileNotFoundError:
+            valid.append(rel)
+            missing.append(rel)
+            continue
+        except OSError:
+            valid.append(rel)
+            modified.append(rel)
+            continue
+        is_symlink = stat.S_ISLNK(path_stat.st_mode)
+        if not is_symlink:
+            try:
+                is_symlink = path.is_symlink()
+            except OSError:
+                is_symlink = False
+        if is_symlink:
+            symlink_status = _tracked_symlink_manifest_status(
+                path,
+                project_root_resolved,
+                project_root_is_resolved=project_root_is_resolved,
+            )
+            if symlink_status == "invalid":
+                invalid.append(rel)
+                continue
+            valid.append(rel)
+            if symlink_status == "missing":
+                missing.append(rel)
+                continue
+            modified.append(rel)
+            continue
+        valid.append(rel)
+        if not stat.S_ISREG(path_stat.st_mode):
+            modified.append(rel)
+            continue
+        try:
+            if _sha256_file(path) != expected_hash:
+                modified.append(rel)
+        except OSError:
+            modified.append(rel)
+
+    return missing, modified, invalid, valid
+
+
+def _default_not_installed_from_raw_state(raw_state: dict[str, Any]) -> str | None:
+    if not isinstance(raw_state.get("installed_integrations"), list):
+        return None
+
+    raw_default = default_integration_key(raw_state)
+    raw_installed = installed_integration_keys(raw_state)
+    if raw_default and raw_default not in raw_installed:
+        return raw_default
+    return None
+
+
+def _manifest_summary(
+    manifest_path: Path,
+    project_root: Path,
+    *,
+    readable: bool,
+    tracked_files: int = 0,
+    missing_files: list[str] | None = None,
+    modified_files: list[str] | None = None,
+    invalid_files: list[str] | None = None,
+) -> dict[str, Any]:
+    return {
+        "manifest": manifest_path.relative_to(project_root).as_posix(),
+        "readable": readable,
+        "tracked_files": tracked_files,
+        "missing_files": missing_files or [],
+        "modified_files": modified_files or [],
+        "invalid_files": invalid_files or [],
+    }
+
+
+def _manifest_owner(key: str) -> str:
+    if key == _SHARED_MANIFEST_KEY:
+        return "shared Spec Kit infrastructure"
+    return f"integration '{key}'"
+
+
+def _manifest_suggestion(key: str, default_key: str | None) -> str:
+    if key == _SHARED_MANIFEST_KEY:
+        if default_key and default_key in INTEGRATION_REGISTRY:
+            return f"Run `specify integration upgrade {default_key}` to regenerate shared managed files."
+        return (
+            "Run `specify init --here --force --integration <key>` to regenerate "
+            "shared managed files."
+        )
+    if key not in INTEGRATION_REGISTRY:
+        return (
+            "Upgrade Spec Kit, reinstall with a supported CLI version, "
+            f"or remove the stale integration entry from {INTEGRATION_JSON}."
+        )
+    return f"Run `specify integration upgrade {key}` or reinstall the integration."
+
+
+def build_integration_status_report(project_root: Path) -> dict[str, Any]:
+    """Return a machine-readable integration status report for *project_root*."""
+    findings: list[dict[str, str]] = []
+    project_root_resolved, project_root_is_resolved = _resolve_project_root_for_status(
+        project_root,
+        findings,
+    )
+    state, raw_state, error = try_read_integration_json_with_raw(project_root)
+    if error is not None:
+        findings.append(
+            _finding(
+                "error",
+                "integration-state-unreadable",
+                _integration_state_error_message(error),
+                path=INTEGRATION_JSON,
+                suggestion=f"Fix or delete {INTEGRATION_JSON}, then retry.",
+            )
+        )
+        return _build_report(None, [], findings, {}, None)
+
+    if state is None:
+        findings.append(
+            _finding(
+                "error",
+                "integration-state-missing",
+                f"{INTEGRATION_JSON} is missing.",
+                path=INTEGRATION_JSON,
+                suggestion="Run `specify integration install <key>` to install an integration.",
+            )
+        )
+        return _build_report(None, [], findings, {}, None)
+
+    assert raw_state is not None
+    raw_default_key = default_integration_key(raw_state)
+    raw_installed_value = raw_state.get("installed_integrations")
+    raw_installed_is_list = isinstance(raw_installed_value, list)
+    raw_installed_keys = (
+        installed_integration_keys(raw_state)
+        if raw_installed_is_list
+        else []
+    )
+    default_key = raw_default_key or default_integration_key(state)
+    installed_keys = installed_integration_keys(state)
+    raw_default_not_installed = _default_not_installed_from_raw_state(raw_state)
+    if raw_installed_is_list and raw_default_not_installed and raw_installed_keys:
+        check_installed_keys = raw_installed_keys
+    else:
+        check_installed_keys = installed_keys
+    recorded_installed_keys = raw_installed_keys
+    if "installed_integrations" in raw_state and not raw_installed_is_list:
+        findings.append(
+            _finding(
+                "warning",
+                "installed-integrations-invalid",
+                (
+                    "installed_integrations must be a list, "
+                    f"got {type(raw_installed_value).__name__}."
+                ),
+                path=INTEGRATION_JSON,
+                suggestion=f"Fix {INTEGRATION_JSON}, then retry.",
+            )
+        )
+    if not installed_keys:
+        findings.append(
+            _finding(
+                "warning",
+                "no-installed-integrations",
+                "No installed integrations are recorded.",
+                suggestion="Run `specify integration install <key>` to install one.",
+            )
+        )
+
+    if raw_installed_keys and raw_default_key is None:
+        default_key = None
+        findings.append(
+            _finding(
+                "error",
+                "default-integration-missing",
+                "No default integration is recorded.",
+                suggestion="Run `specify integration use <key>` after choosing an installed integration.",
+            )
+        )
+
+    if raw_default_not_installed:
+        findings.append(
+            _finding(
+                "error",
+                "default-integration-not-installed",
+                (
+                    f"Default integration '{raw_default_not_installed}' is not listed "
+                    "in installed_integrations."
+                ),
+                integration=raw_default_not_installed,
+                suggestion="Run `specify integration use <key>` for an installed integration, or reinstall the default integration.",
+            )
+        )
+
+    known_installed = [key for key in check_installed_keys if key in INTEGRATION_REGISTRY]
+    unknown_installed: list[str] = []
+    for key in check_installed_keys:
+        if key not in INTEGRATION_REGISTRY:
+            unknown_installed.append(key)
+            findings.append(
+                _finding(
+                    "error",
+                    "unknown-integration",
+                    f"Integration '{key}' is installed but is not known to this CLI.",
+                    integration=key,
+                    suggestion=(
+                        "Upgrade Spec Kit, reinstall with a supported CLI version, "
+                        f"or remove the stale integration entry from {INTEGRATION_JSON}."
+                    ),
+                )
+            )
+
+    unsafe = [
+        key for key in known_installed
+        if not getattr(INTEGRATION_REGISTRY[key], "multi_install_safe", False)
+    ]
+    if len(check_installed_keys) > 1:
+        unsafe.extend(unknown_installed)
+
+    if len(check_installed_keys) > 1 and unsafe:
+        findings.append(
+            _finding(
+                "error",
+                "unsafe-multi-install",
+                (
+                    "Installed integrations are not all declared multi-install safe: "
+                    + ", ".join(sorted(unsafe))
+                ),
+                suggestion=(
+                    "Use `specify integration use <key>` to change defaults, "
+                    "or `specify integration switch <key>` only when replacing integrations."
+                ),
+            )
+        )
+
+    manifest_files_by_path: dict[str, list[str]] = {}
+    manifest_summaries: dict[str, dict[str, Any]] = {}
+    attempted_manifest_keys: list[str] = []
+    manifest_keys = list(check_installed_keys)
+    if _SHARED_MANIFEST_KEY not in manifest_keys:
+        manifest_keys.append(_SHARED_MANIFEST_KEY)
+
+    for key in manifest_keys:
+        owner = _manifest_owner(key)
+        if not _is_safe_manifest_key(key):
+            findings.append(
+                _finding(
+                    "error",
+                    "integration-key-invalid",
+                    f"Integration key {key!r} cannot be used as a manifest filename.",
+                    integration=key,
+                    path=INTEGRATION_JSON,
+                    suggestion=f"Fix {INTEGRATION_JSON}, then reinstall the integration.",
+                )
+            )
+            continue
+
+        attempted_manifest_keys.append(key)
+        manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
+        try:
+            manifest = IntegrationManifest.load(
+                key,
+                project_root_resolved,
+                resolve_project_root=False,
+            )
+        except FileNotFoundError:
+            findings.append(
+                _finding(
+                    "error",
+                    "manifest-missing",
+                    f"Manifest for {owner} is missing.",
+                    integration=key,
+                    path=manifest_path.relative_to(project_root).as_posix(),
+                    suggestion=_manifest_suggestion(key, default_key),
+                )
+            )
+            manifest_summaries[key] = _manifest_summary(
+                manifest_path,
+                project_root,
+                readable=False,
+            )
+            continue
+        except _MANIFEST_READ_ERRORS as exc:
+            manifest_summaries[key] = _manifest_summary(
+                manifest_path,
+                project_root,
+                readable=False,
+            )
+            findings.append(
+                _finding(
+                    "error",
+                    "manifest-unreadable",
+                    f"Manifest for {owner} is unreadable: {exc}",
+                    integration=key,
+                    path=manifest_path.relative_to(project_root).as_posix(),
+                    suggestion=_manifest_suggestion(key, default_key),
+                )
+            )
+            continue
+
+        missing, modified, invalid, valid_files = _manifest_file_status(
+            manifest,
+            project_root_resolved,
+            project_root_is_resolved=project_root_is_resolved,
+        )
+        manifest_summaries[key] = _manifest_summary(
+            manifest_path,
+            project_root,
+            readable=True,
+            tracked_files=len(manifest.files),
+            missing_files=missing,
+            modified_files=modified,
+            invalid_files=invalid,
+        )
+
+        for rel in valid_files:
+            manifest_files_by_path.setdefault(rel, []).append(key)
+        if invalid:
+            findings.append(
+                _finding(
+                    "error",
+                    "manifest-paths-invalid",
+                    f"{len(invalid)} unsafe manifest path(s) are recorded for {owner}.",
+                    integration=key,
+                    path=manifest_path.relative_to(project_root).as_posix(),
+                    suggestion=_manifest_suggestion(key, default_key),
+                )
+            )
+        if missing:
+            findings.append(
+                _finding(
+                    "error",
+                    "managed-files-missing",
+                    f"{len(missing)} managed file(s) are missing for {owner}.",
+                    integration=key,
+                    suggestion=_manifest_suggestion(key, default_key),
+                )
+            )
+        if modified:
+            findings.append(
+                _finding(
+                    "warning",
+                    "managed-files-modified",
+                    f"{len(modified)} managed file(s) were modified for {owner}.",
+                    integration=key,
+                    suggestion="Review the changes before running `specify integration upgrade --force`.",
+                )
+            )
+
+    for rel, keys in sorted(manifest_files_by_path.items()):
+        if len(keys) > 1:
+            findings.append(
+                _finding(
+                    "warning",
+                    "managed-file-collision",
+                    f"Managed file '{rel}' is tracked by multiple integrations: {', '.join(sorted(keys))}.",
+                    path=rel,
+                    suggestion="Review the manifests before uninstalling or upgrading these integrations.",
+                )
+            )
+
+    if not raw_installed_is_list or not raw_installed_keys:
+        multi_install_safe = None
+    else:
+        multi_install_safe = not (len(check_installed_keys) > 1 and unsafe)
+    return _build_report(
+        default_key,
+        installed_keys,
+        findings,
+        manifest_summaries,
+        multi_install_safe,
+        manifest_checked_keys=attempted_manifest_keys,
+        recorded_installed_keys=recorded_installed_keys,
+    )
+
+
+def _build_report(
+    default_key: str | None,
+    installed_keys: list[str],
+    findings: list[dict[str, str]],
+    manifests: dict[str, dict[str, Any]],
+    multi_install_safe: bool | None,
+    *,
+    manifest_checked_keys: list[str] | None = None,
+    recorded_installed_keys: list[str] | None = None,
+) -> dict[str, Any]:
+    missing_count = sum(len(item.get("missing_files", [])) for item in manifests.values())
+    modified_count = sum(len(item.get("modified_files", [])) for item in manifests.values())
+    invalid_count = sum(len(item.get("invalid_files", [])) for item in manifests.values())
+    unchecked_count = sum(1 for item in manifests.values() if not item.get("readable", True))
+    return {
+        "status": _status(findings),
+        "default_integration": default_key,
+        "installed_integrations": installed_keys,
+        "recorded_installed_integrations": (
+            installed_keys if recorded_installed_keys is None else recorded_installed_keys
+        ),
+        "manifest_checked_integrations": (
+            installed_keys if manifest_checked_keys is None else manifest_checked_keys
+        ),
+        "multi_install_safe": multi_install_safe,
+        "shared_templates_target_alignment": default_key,
+        "missing_managed_files": missing_count,
+        "modified_managed_files": modified_count,
+        "invalid_manifest_paths": invalid_count,
+        "unchecked_manifests": unchecked_count,
+        "manifests": manifests,
+        "findings": findings,
+    }

src/specify_cli/integrations/_query_commands.py

@@ -1,10 +1,12 @@
-"""specify integration list/use/search/info + catalog list/add/remove command handlers."""
+"""specify integration list/status/use/search/info + catalog list/add/remove command handlers."""
 from __future__ import annotations
 
+import json
 import os
-from typing import Optional
+from typing import Any, Optional
 
 import typer
+from rich.markup import escape as _rich_escape
 from rich.table import Table
 
 from .._console import console
@@ -120,6 +122,86 @@ def integration_list(
         console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
 
 
+def _print_integration_status_report(report: dict[str, Any]) -> None:
+    status = report["status"]
+    status_label = {
+        "ok": "[green]OK[/green]",
+        "warning": "[yellow]WARNING[/yellow]",
+        "error": "[red]ERROR[/red]",
+    }.get(str(status), str(status).upper())
+    installed = report.get("installed_integrations") or []
+    installed_display = ", ".join(_rich_escape(str(item)) for item in installed)
+
+    console.print(f"Integration status: {status_label}")
+    console.print(
+        f"Default integration: {_rich_escape(str(report.get('default_integration') or 'none'))}"
+    )
+    console.print(f"Installed integrations: {installed_display if installed else 'none'}")
+    multi_install_safe = report.get("multi_install_safe")
+    if multi_install_safe is None:
+        multi_install_safe_display = "unknown"
+    else:
+        multi_install_safe_display = "yes" if multi_install_safe else "no"
+    console.print(f"Multi-install safe: {multi_install_safe_display}")
+    console.print(
+        f"Shared templates target alignment: "
+        f"{_rich_escape(str(report.get('shared_templates_target_alignment') or 'none'))}"
+    )
+    console.print(f"Modified managed files: {report.get('modified_managed_files', 0)}")
+    console.print(f"Missing managed files: {report.get('missing_managed_files', 0)}")
+    console.print(f"Invalid manifest paths: {report.get('invalid_manifest_paths', 0)}")
+    console.print(f"Unchecked manifests: {report.get('unchecked_manifests', 0)}")
+
+    findings = report.get("findings") or []
+    if not findings:
+        return
+
+    console.print()
+    console.print("[bold]Findings:[/bold]")
+    for item in findings:
+        severity = item.get("severity", "")
+        severity_label = {
+            "error": "[red]error[/red]",
+            "warning": "[yellow]warning[/yellow]",
+        }.get(severity, severity)
+        prefix = f"- {severity_label} {_rich_escape(str(item.get('code', '')))}"
+        if item.get("integration"):
+            prefix += f" ({_rich_escape(str(item['integration']))})"
+        console.print(
+            f"{prefix}: {_rich_escape(str(item.get('message', '')))}",
+            soft_wrap=True,
+        )
+        if item.get("suggestion"):
+            console.print(
+                f"  Suggestion: {_rich_escape(str(item['suggestion']))}",
+                soft_wrap=True,
+            )
+
+
+@integration_app.command("status")
+def integration_status(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable integration status.",
+    ),
+):
+    """Report the current project's integration status without changing files."""
+    from .. import _require_specify_project
+    from ..integration_status import build_integration_status_report
+
+    project_root = _require_specify_project()
+    report = build_integration_status_report(project_root)
+
+    if json_output:
+        typer.echo(json.dumps(report, indent=2))
+    else:
+        _print_integration_status_report(report)
+
+    if report["status"] == "error":
+        raise typer.Exit(1)
+
+
 @integration_app.command("use")
 def integration_use(
     key: str = typer.Argument(help="Installed integration key to make the default"),

src/specify_cli/integrations/manifest.py

@@ -108,11 +108,23 @@ class IntegrationManifest:
         key:          Integration identifier (e.g. ``"copilot"``).
         project_root: Absolute path to the project directory.
         version:      CLI version string recorded in the manifest.
+        resolve_project_root: Resolve ``project_root`` before using it.
     """
 
-    def __init__(self, key: str, project_root: Path, version: str = "") -> None:
+    def __init__(
+        self,
+        key: str,
+        project_root: Path,
+        version: str = "",
+        *,
+        resolve_project_root: bool = True,
+    ) -> None:
         self.key = key
-        self.project_root = project_root.resolve()
+        self.project_root = (
+            project_root.resolve()
+            if resolve_project_root
+            else project_root.absolute()
+        )
         self.version = version
         self._files: dict[str, str] = {}  # rel_path → sha256 hex
         self._recovered_files: set[str] = set()
@@ -387,12 +399,18 @@ class IntegrationManifest:
         return path
 
     @classmethod
-    def load(cls, key: str, project_root: Path) -> IntegrationManifest:
+    def load(
+        cls,
+        key: str,
+        project_root: Path,
+        *,
+        resolve_project_root: bool = True,
+    ) -> IntegrationManifest:
         """Load an existing manifest from disk.
 
         Raises ``FileNotFoundError`` if the manifest does not exist.
         """
-        inst = cls(key, project_root)
+        inst = cls(key, project_root, resolve_project_root=resolve_project_root)
         path = inst.manifest_path
         try:
             data = json.loads(path.read_text(encoding="utf-8"))

tests/integrations/test_integration_subcommand.py

@@ -2,7 +2,10 @@
 
 import json
 import os
+import shutil
+from pathlib import Path
 
+import pytest
 from typer.testing import CliRunner
 
 from specify_cli import app
@@ -47,6 +50,32 @@ def _write_invalid_manifest(project, key):
     return manifest
 
 
+def _copy_project_template(tmp_path, template):
+    project = tmp_path / "proj"
+    shutil.copytree(template, project)
+    return project
+
+
+@pytest.fixture(scope="module")
+def status_copilot_template(tmp_path_factory):
+    return _init_project(tmp_path_factory.mktemp("status-copilot"), "copilot")
+
+
+@pytest.fixture(scope="module")
+def status_claude_template(tmp_path_factory):
+    return _init_project(tmp_path_factory.mktemp("status-claude"), "claude")
+
+
+@pytest.fixture
+def copilot_project(tmp_path, status_copilot_template):
+    return _copy_project_template(tmp_path, status_copilot_template)
+
+
+@pytest.fixture
+def claude_project(tmp_path, status_claude_template):
+    return _copy_project_template(tmp_path, status_claude_template)
+
+
 def _integration_list_row_cells(output: str, key: str) -> list[str]:
     plain = strip_ansi(output)
     row = next(line for line in plain.splitlines() if line.startswith(f"│ {key}"))
@@ -126,6 +155,823 @@ class TestIntegrationList:
         assert "only supports schema 1" in normalized
 
 
+# ── status ───────────────────────────────────────────────────────────
+
+
+class TestIntegrationStatus:
+    def test_status_requires_speckit_project(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        result = runner.invoke(app, ["integration", "status"])
+        assert result.exit_code != 0
+        assert "Not a spec-kit project" in result.output
+
+    def test_status_reports_healthy_project(self, copilot_project):
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code == 0
+        assert "Integration status: OK" in result.output
+        assert "Default integration: copilot" in result.output
+        assert "Installed integrations: copilot" in result.output
+        assert "Shared templates target alignment: copilot" in result.output
+        assert "Modified managed files: 0" in result.output
+        assert "Missing managed files: 0" in result.output
+
+    def test_status_json_reports_healthy_project(self, copilot_project):
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "ok"
+        assert payload["default_integration"] == "copilot"
+        assert payload["installed_integrations"] == ["copilot"]
+        assert payload["recorded_installed_integrations"] == ["copilot"]
+        assert payload["manifest_checked_integrations"] == ["copilot", "speckit"]
+        assert payload["multi_install_safe"] is True
+        assert payload["shared_templates_target_alignment"] == "copilot"
+        assert "shared_templates_aligned_to" not in payload
+        assert payload["findings"] == []
+
+    def test_status_reports_invalid_integration_json(self, copilot_project):
+        (copilot_project / ".specify" / "integration.json").write_text("{", encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "integration-state-unreadable" in result.output
+        assert "invalid JSON" in result.output
+        assert "Detail:" in result.output
+        assert "Multi-install safe: unknown" in result.output
+        assert "Traceback" not in result.output
+
+    def test_status_json_reports_unknown_multi_install_safety_when_state_unreadable(
+        self,
+        copilot_project,
+    ):
+        (copilot_project / ".specify" / "integration.json").write_text("{", encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "error"
+        assert payload["multi_install_safe"] is None
+        assert payload["manifest_checked_integrations"] == []
+        assert payload["findings"][0]["code"] == "integration-state-unreadable"
+        assert "Detail:" in payload["findings"][0]["message"]
+
+    def test_status_reports_supported_schema_for_newer_integration_state(self, copilot_project):
+        state_path = copilot_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["integration_state_schema"] = 99
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["findings"][0]["code"] == "integration-state-unreadable"
+        assert "schema 99" in payload["findings"][0]["message"]
+        assert "supported schema: 1" in payload["findings"][0]["message"]
+
+    def test_status_reports_missing_integration_json(self, copilot_project):
+        (copilot_project / ".specify" / "integration.json").unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "integration-state-missing" in result.output
+        assert ".specify/integration.json is missing" in result.output
+        assert "Multi-install safe: unknown" in result.output
+
+    def test_status_json_reports_unknown_multi_install_safety_when_state_missing(
+        self,
+        copilot_project,
+    ):
+        (copilot_project / ".specify" / "integration.json").unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "error"
+        assert payload["multi_install_safe"] is None
+        assert payload["manifest_checked_integrations"] == []
+        assert payload["findings"][0]["code"] == "integration-state-missing"
+
+    def test_status_json_reports_no_installed_integrations_as_warning(self, copilot_project):
+        state_path = copilot_project / ".specify" / "integration.json"
+        state_path.write_text(
+            json.dumps({
+                "version": "test",
+                "integration_state_schema": 1,
+                "installed_integrations": [],
+            }),
+            encoding="utf-8",
+        )
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "warning"
+        assert payload["installed_integrations"] == []
+        assert payload["multi_install_safe"] is None
+        assert payload["manifest_checked_integrations"] == ["speckit"]
+        assert payload["findings"][0]["code"] == "no-installed-integrations"
+        assert "speckit" in payload["manifests"]
+        assert payload["manifests"]["speckit"]["readable"] is True
+
+    def test_status_checks_shared_manifest_when_no_integrations_installed(self, copilot_project):
+        state_path = copilot_project / ".specify" / "integration.json"
+        state_path.write_text(
+            json.dumps({
+                "version": "test",
+                "integration_state_schema": 1,
+                "installed_integrations": [],
+            }),
+            encoding="utf-8",
+        )
+        (copilot_project / ".specify" / "integrations" / "speckit.manifest.json").unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "error"
+        assert payload["installed_integrations"] == []
+        assert payload["manifest_checked_integrations"] == ["speckit"]
+        assert payload["unchecked_manifests"] == 1
+        assert any(
+            item["code"] == "no-installed-integrations"
+            for item in payload["findings"]
+        )
+        assert any(
+            item["code"] == "manifest-missing"
+            and item["integration"] == "speckit"
+            for item in payload["findings"]
+        )
+
+    def test_status_json_reports_missing_default_integration_as_error(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state.pop("default_integration", None)
+        state.pop("integration", None)
+        state["installed_integrations"] = ["claude"]
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "error"
+        assert payload["default_integration"] is None
+        assert any(
+            item["code"] == "default-integration-missing"
+            for item in payload["findings"]
+        )
+
+    def test_status_ignores_non_list_raw_installed_integrations(self, copilot_project):
+        state_path = copilot_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state.pop("default_integration", None)
+        state.pop("integration", None)
+        state["installed_integrations"] = "copilot"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "warning"
+        assert payload["installed_integrations"] == []
+        assert payload["recorded_installed_integrations"] == []
+        assert payload["manifest_checked_integrations"] == ["speckit"]
+        assert payload["multi_install_safe"] is None
+        assert [item["code"] for item in payload["findings"]] == [
+            "installed-integrations-invalid",
+            "no-installed-integrations",
+        ]
+
+    def test_status_reports_non_list_raw_installed_integrations_with_default(self, copilot_project):
+        state_path = copilot_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["default_integration"] = "copilot"
+        state["integration"] = "copilot"
+        state["installed_integrations"] = "copilot"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "warning"
+        assert payload["installed_integrations"] == ["copilot"]
+        assert payload["recorded_installed_integrations"] == []
+        assert payload["manifest_checked_integrations"] == ["copilot", "speckit"]
+        assert payload["multi_install_safe"] is None
+        assert [item["code"] for item in payload["findings"]] == [
+            "installed-integrations-invalid",
+        ]
+
+    def test_status_reports_default_integration_not_installed(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["default_integration"] = "codex"
+        state["integration"] = "codex"
+        state["installed_integrations"] = ["claude"]
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["default_integration"] == "codex"
+        assert payload["installed_integrations"] == ["codex", "claude"]
+        assert payload["recorded_installed_integrations"] == ["claude"]
+        assert payload["manifest_checked_integrations"] == ["claude", "speckit"]
+        assert any(
+            item["code"] == "default-integration-not-installed"
+            and "Default integration 'codex' is not listed" in item["message"]
+            for item in payload["findings"]
+        )
+        assert "codex" not in payload["manifests"]
+        assert not any(
+            item["code"] == "manifest-missing" and item.get("integration") == "codex"
+            for item in payload["findings"]
+        )
+
+    def test_status_checks_effective_default_manifest_when_raw_installed_is_empty(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["installed_integrations"] = []
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["installed_integrations"] == ["claude"]
+        assert payload["recorded_installed_integrations"] == []
+        assert payload["manifest_checked_integrations"] == ["claude", "speckit"]
+        assert payload["multi_install_safe"] is None
+        assert payload["manifests"]["claude"]["readable"] is True
+        assert any(
+            item["code"] == "default-integration-not-installed"
+            for item in payload["findings"]
+        )
+
+    def test_status_reports_missing_manifest(self, copilot_project):
+        (copilot_project / ".specify" / "integrations" / "copilot.manifest.json").unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "manifest-missing" in result.output
+        assert "Manifest for integration 'copilot' is missing" in result.output
+
+    def test_status_reports_unreadable_manifest_in_json_summary(self, copilot_project):
+        _write_invalid_manifest(copilot_project, "copilot")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["unchecked_manifests"] == 1
+        assert payload["manifests"]["copilot"]["readable"] is False
+        assert payload["manifests"]["copilot"]["missing_files"] == []
+        assert payload["manifests"]["copilot"]["modified_files"] == []
+
+    def test_status_reports_modified_managed_files_without_failing(self, copilot_project):
+        manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+        tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+        first_rel = next(iter(tracked_files))
+        (copilot_project / first_rel).write_text("MODIFIED CONTENT\n", encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code == 0
+        assert "Integration status: WARNING" in result.output
+        assert "managed-files-modified" in result.output
+        assert "Modified managed files: 1" in result.output
+
+    def test_status_reports_missing_managed_files(self, copilot_project):
+        manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+        tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+        first_rel = next(iter(tracked_files))
+        (copilot_project / first_rel).unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "managed-files-missing" in result.output
+        assert "Missing managed files: 1" in result.output
+
+    def test_status_reports_missing_shared_managed_files(self, copilot_project):
+        shared_file = copilot_project / ".specify" / "scripts" / "bash" / "common.sh"
+        assert shared_file.exists()
+        shared_file.unlink()
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "managed-files-missing" in result.output
+        assert "shared Spec Kit infrastructure" in result.output
+        assert "Missing managed files: 1" in result.output
+
+    def test_status_does_not_use_exists_precheck_for_managed_files(self, tmp_path, monkeypatch):
+        from specify_cli.integration_status import _manifest_file_status
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        project = tmp_path / "proj"
+        project.mkdir()
+        tracked = project / "tracked.md"
+        tracked.write_text("content\n", encoding="utf-8")
+        manifest = IntegrationManifest("test", project, version="test")
+        manifest.record_existing("tracked.md")
+
+        def fail_exists(self):
+            raise AssertionError(f"Path.exists() should not be used for {self}")
+
+        monkeypatch.setattr(Path, "exists", fail_exists)
+
+        missing, modified, invalid, valid = _manifest_file_status(
+            manifest,
+            project.resolve(),
+        )
+
+        assert missing == []
+        assert modified == []
+        assert invalid == []
+        assert valid == ["tracked.md"]
+
+    def test_status_does_not_use_exists_precheck_for_manifest_load(self, copilot_project, monkeypatch):
+        def fail_exists(self):
+            raise AssertionError(f"Path.exists() should not be used for {self}")
+
+        monkeypatch.setattr(Path, "exists", fail_exists)
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "ok"
+        assert payload["manifests"]["copilot"]["readable"] is True
+
+    def test_status_reports_unresolved_project_root_without_crashing(self, copilot_project, monkeypatch):
+        original_resolve = Path.resolve
+        failed = {"done": False}
+
+        def fail_first_project_root_resolve(self, *args, **kwargs):
+            if self == copilot_project and not failed["done"]:
+                failed["done"] = True
+                raise RuntimeError("symlink loop")
+            return original_resolve(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "resolve", fail_first_project_root_resolve)
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["status"] == "warning"
+        assert any(item["code"] == "project-root-unresolved" for item in payload["findings"])
+
+    def test_status_loads_manifests_when_project_root_resolution_keeps_failing(
+        self,
+        copilot_project,
+        monkeypatch,
+    ):
+        original_resolve = Path.resolve
+
+        def fail_project_root_resolve(self, *args, **kwargs):
+            if self == copilot_project:
+                raise RuntimeError("symlink loop")
+            return original_resolve(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "resolve", fail_project_root_resolve)
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code == 0, result.output
+        payload = json.loads(result.output)
+        assert payload["status"] == "warning"
+        assert payload["manifests"]["copilot"]["readable"] is True
+        assert payload["manifests"]["speckit"]["readable"] is True
+        assert any(item["code"] == "project-root-unresolved" for item in payload["findings"])
+
+    def test_status_uses_lexical_manifest_paths_when_project_root_resolution_falls_back(self, tmp_path):
+        from specify_cli.integration_status import _manifest_file_status
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        real_project = tmp_path / "real-project"
+        real_project.mkdir()
+        tracked = real_project / "tracked.md"
+        tracked.write_text("content\n", encoding="utf-8")
+        symlinked_project = tmp_path / "symlinked-project"
+        try:
+            symlinked_project.symlink_to(real_project, target_is_directory=True)
+        except OSError as exc:
+            pytest.skip(f"symlinks unavailable: {exc}")
+
+        manifest = IntegrationManifest("test", real_project, version="test")
+        manifest.record_existing("tracked.md")
+        manifest.project_root = symlinked_project.absolute()
+
+        missing, modified, invalid, valid = _manifest_file_status(
+            manifest,
+            symlinked_project.absolute(),
+            project_root_is_resolved=False,
+        )
+
+        assert missing == []
+        assert modified == []
+        assert invalid == []
+        assert valid == ["tracked.md"]
+
+    def test_status_treats_resolve_runtime_error_as_invalid_path(self, tmp_path, monkeypatch):
+        from specify_cli.integration_status import _manifest_file_status
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        project = tmp_path / "proj"
+        project.mkdir()
+        tracked = project / "tracked.md"
+        tracked.write_text("content\n", encoding="utf-8")
+        manifest = IntegrationManifest("test", project, version="test")
+        manifest.record_existing("tracked.md")
+        project_root_resolved = project.resolve()
+        original_resolve = Path.resolve
+
+        def fail_project_parent_resolve(self, *args, **kwargs):
+            if self == project:
+                raise RuntimeError("symlink loop")
+            return original_resolve(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "resolve", fail_project_parent_resolve)
+
+        missing, modified, invalid, valid = _manifest_file_status(
+            manifest,
+            project_root_resolved,
+        )
+
+        assert missing == []
+        assert modified == []
+        assert invalid == ["tracked.md"]
+        assert valid == []
+
+    def test_status_does_not_mask_runtime_errors_from_manifest_load(self, copilot_project, monkeypatch):
+        from specify_cli import integration_status as status_module
+
+        def fail_load(key, project_root, **kwargs):
+            raise RuntimeError(f"unexpected manifest loader bug for {key}")
+
+        monkeypatch.setattr(status_module.IntegrationManifest, "load", fail_load)
+
+        with pytest.raises(RuntimeError, match="unexpected manifest loader bug"):
+            status_module.build_integration_status_report(copilot_project)
+
+    def test_status_treats_dangling_symlink_as_missing(self, copilot_project):
+        manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+        tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+        first_rel = next(iter(tracked_files))
+        target = copilot_project / first_rel
+        target.unlink()
+        try:
+            target.symlink_to(copilot_project / "missing-target")
+        except OSError as exc:
+            pytest.skip(f"symlinks unavailable: {exc}")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert first_rel in payload["manifests"]["copilot"]["missing_files"]
+        assert first_rel not in payload["manifests"]["copilot"]["modified_files"]
+
+    def test_status_treats_windows_style_dangling_symlink_as_missing(self, tmp_path, monkeypatch):
+        from specify_cli.integration_status import _manifest_file_status
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        project = tmp_path / "proj"
+        project.mkdir()
+        tracked = project / "tracked.md"
+        tracked.write_text("content\n", encoding="utf-8")
+        regular_stat = tracked.lstat()
+
+        manifest = IntegrationManifest("test", project, version="test")
+        manifest.record_existing("tracked.md")
+
+        tracked.unlink()
+        try:
+            tracked.symlink_to(project / "missing-target")
+        except OSError as exc:
+            pytest.skip(f"symlinks unavailable: {exc}")
+
+        original_lstat = Path.lstat
+        original_is_symlink = Path.is_symlink
+
+        def windows_style_lstat(self):
+            if self == tracked:
+                return regular_stat
+            return original_lstat(self)
+
+        def windows_style_is_symlink(self):
+            if self == tracked:
+                return True
+            return original_is_symlink(self)
+
+        monkeypatch.setattr(Path, "lstat", windows_style_lstat)
+        monkeypatch.setattr(Path, "is_symlink", windows_style_is_symlink)
+
+        missing, modified, invalid, valid = _manifest_file_status(
+            manifest,
+            project.resolve(),
+        )
+
+        assert missing == ["tracked.md"]
+        assert modified == []
+        assert invalid == []
+        assert valid == ["tracked.md"]
+
+    def test_strip_extended_length_prefix_normalizes_windows_paths(self):
+        from specify_cli.integration_status import _strip_extended_length_prefix
+
+        # Build the prefixed strings explicitly so the test is meaningful on
+        # every platform (POSIX won't parse backslash separators, but the
+        # helper operates on the string form). Compare Path objects rather than
+        # their str() form: on Windows pathlib renders a UNC root with a
+        # trailing separator (``\\server\share\``), so an exact string match is
+        # brittle, whereas Path equality captures the intended semantics on
+        # both POSIX and Windows.
+        bs = "\\"
+        assert _strip_extended_length_prefix(
+            Path(f"{bs}{bs}?{bs}C:{bs}proj")
+        ) == Path(f"C:{bs}proj")
+        assert _strip_extended_length_prefix(
+            Path(f"{bs}{bs}?{bs}UNC{bs}server{bs}share")
+        ) == Path(f"{bs}{bs}server{bs}share")
+        # Paths without the prefix are returned unchanged.
+        assert _strip_extended_length_prefix(Path("relative/path")) == Path("relative/path")
+
+    def test_is_within_project_tolerates_extended_length_prefix(self):
+        from specify_cli.integration_status import _is_within_project
+
+        # A readlink result on POSIX never carries the prefix, so an in-project
+        # child is contained and an outside path is not. The Windows
+        # prefix-stripping branch is exercised by the dangling-symlink tests on
+        # Windows CI; here we lock in the cross-platform containment contract.
+        root = Path("/tmp/project").resolve()
+        assert _is_within_project(root, root / "child")
+        assert not _is_within_project(root, Path("/tmp/other").resolve())
+
+    def test_status_reports_unsafe_manifest_paths_without_hashing_them(self, tmp_path, copilot_project):
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        (outside / "secret.txt").write_text("outside project\n", encoding="utf-8")
+        link = copilot_project / "outside-link"
+        try:
+            link.symlink_to(outside, target_is_directory=True)
+        except OSError as exc:
+            pytest.skip(f"symlinks unavailable: {exc}")
+
+        manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        manifest_data["files"]["outside-link/secret.txt"] = "wrong"
+        manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["invalid_manifest_paths"] == 1
+        assert "outside-link/secret.txt" in payload["manifests"]["copilot"]["invalid_files"]
+        assert "outside-link/secret.txt" not in payload["manifests"]["copilot"]["modified_files"]
+
+    def test_status_reports_tracked_symlink_target_escape_as_invalid(self, tmp_path, copilot_project, monkeypatch):
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        outside_file = outside / "secret.txt"
+        outside_file.write_text("outside project\n", encoding="utf-8")
+
+        manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+        tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+        first_rel = next(iter(tracked_files))
+        tracked_path = copilot_project / first_rel
+        tracked_path.unlink()
+        try:
+            tracked_path.symlink_to(outside_file)
+        except OSError as exc:
+            pytest.skip(f"symlinks unavailable: {exc}")
+
+        original_stat = Path.stat
+
+        def fail_tracked_symlink_stat(self, *args, **kwargs):
+            follows_symlinks = kwargs.get("follow_symlinks", True)
+            if self == tracked_path and follows_symlinks:
+                raise AssertionError("Path.stat() should not follow tracked symlinks")
+            return original_stat(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "stat", fail_tracked_symlink_stat)
+
+        result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["invalid_manifest_paths"] == 1
+        assert first_rel in payload["manifests"]["copilot"]["invalid_files"]
+        assert first_rel not in payload["manifests"]["copilot"]["modified_files"]
+
+    def test_status_reports_unsafe_multi_install_combination(self, copilot_project):
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        state_path = copilot_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["installed_integrations"] = ["copilot", "claude"]
+        state["default_integration"] = "copilot"
+        state["integration"] = "copilot"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+        IntegrationManifest("claude", copilot_project, version="test").save()
+
+        result = _run_in_project(copilot_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "unsafe-multi-install" in result.output
+        assert "Multi-install safe: no" in result.output
+        assert "specify integration switch <key>" in result.output
+
+    def test_status_treats_unknown_multi_install_as_unsafe(self, claude_project):
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["installed_integrations"] = ["claude", "mystery"]
+        state["default_integration"] = "claude"
+        state["integration"] = "claude"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+        IntegrationManifest("mystery", claude_project, version="test").save()
+
+        result = _run_in_project(claude_project, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "unknown-integration" in result.output
+        assert "unsafe-multi-install" in result.output
+        assert "remove the stale integration entry" in result.output
+        assert "Multi-install safe: no" in result.output
+
+    def test_status_gives_actionable_suggestion_for_unknown_manifest(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["installed_integrations"] = ["mystery"]
+        state["default_integration"] = "mystery"
+        state["integration"] = "mystery"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        manifest_finding = next(
+            item for item in payload["findings"]
+            if item["code"] == "manifest-missing" and item["integration"] == "mystery"
+        )
+        assert "remove the stale integration entry" in manifest_finding["suggestion"]
+        assert "integration upgrade mystery" not in manifest_finding["suggestion"]
+
+    def test_status_rejects_unsafe_integration_keys_before_manifest_lookup(self, tmp_path, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        unsafe_key = "../../../escape"
+        state_path.write_text(
+            json.dumps({
+                "integration": unsafe_key,
+                "default_integration": unsafe_key,
+                "installed_integrations": [unsafe_key],
+            }),
+            encoding="utf-8",
+        )
+        outside_manifest = tmp_path / "escape.manifest.json"
+        outside_manifest.write_text(
+            json.dumps({"integration": unsafe_key, "files": {}}),
+            encoding="utf-8",
+        )
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert unsafe_key not in payload["manifests"]
+        assert payload["manifest_checked_integrations"] == ["speckit"]
+        assert any(
+            item["code"] == "integration-key-invalid"
+            and item["integration"] == unsafe_key
+            for item in payload["findings"]
+        )
+
+    def test_status_rejects_filename_invalid_integration_keys(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        unsafe_key = "bad:key"
+        state_path.write_text(
+            json.dumps({
+                "integration": unsafe_key,
+                "default_integration": unsafe_key,
+                "installed_integrations": [unsafe_key],
+            }),
+            encoding="utf-8",
+        )
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert any(
+            item["code"] == "integration-key-invalid"
+            and item["integration"] == unsafe_key
+            for item in payload["findings"]
+        )
+
+    def test_status_rejects_windows_reserved_integration_keys(self, claude_project):
+        state_path = claude_project / ".specify" / "integration.json"
+        unsafe_key = "CON"
+        state_path.write_text(
+            json.dumps({
+                "integration": unsafe_key,
+                "default_integration": unsafe_key,
+                "installed_integrations": [unsafe_key],
+            }),
+            encoding="utf-8",
+        )
+
+        result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert any(
+            item["code"] == "integration-key-invalid"
+            and item["integration"] == unsafe_key
+            for item in payload["findings"]
+        )
+
+    def test_status_reports_managed_file_collisions(self, claude_project):
+        from specify_cli.integrations.manifest import IntegrationManifest
+
+        state_path = claude_project / ".specify" / "integration.json"
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        state["installed_integrations"] = ["claude", "codex"]
+        state["default_integration"] = "claude"
+        state["integration"] = "claude"
+        state_path.write_text(json.dumps(state), encoding="utf-8")
+
+        claude_manifest = claude_project / ".specify" / "integrations" / "claude.manifest.json"
+        tracked_files = json.loads(claude_manifest.read_text(encoding="utf-8"))["files"]
+        shared_rel = next(iter(tracked_files))
+        codex_manifest = IntegrationManifest("codex", claude_project, version="test")
+        codex_manifest.record_existing(shared_rel)
+        codex_manifest.save()
+
+        result = _run_in_project(claude_project, ["integration", "status"])
+
+        assert result.exit_code == 0
+        assert "managed-file-collision" in result.output
+        assert "Integration status: WARNING" in result.output
+
+    def test_status_json_is_not_rich_rendered(self, tmp_path, monkeypatch):
+        project = tmp_path / "proj"
+        project.mkdir()
+        (project / ".specify").mkdir()
+        (project / ".specify" / "integration.json").write_text(
+            json.dumps({
+                "integration": "[red]x[/red]",
+                "installed_integrations": ["[red]x[/red]"],
+            }),
+            encoding="utf-8",
+        )
+        monkeypatch.chdir(project)
+
+        result = runner.invoke(app, ["integration", "status", "--json"])
+
+        assert result.exit_code != 0
+        payload = json.loads(result.output)
+        assert payload["default_integration"] == "[red]x[/red]"
+        assert payload["installed_integrations"] == ["[red]x[/red]"]
+
+    def test_status_text_escapes_rich_markup_from_project_state(self, tmp_path, monkeypatch):
+        project = tmp_path / "proj"
+        project.mkdir()
+        (project / ".specify").mkdir()
+        (project / ".specify" / "integration.json").write_text(
+            json.dumps({
+                "integration": "[red]x[/red]",
+                "installed_integrations": ["[red]x[/red]"],
+            }),
+            encoding="utf-8",
+        )
+        monkeypatch.chdir(project)
+
+        result = runner.invoke(app, ["integration", "status"])
+
+        assert result.exit_code != 0
+        assert "Default integration: [red]x[/red]" in result.output
+        assert "Installed integrations: [red]x[/red]" in result.output
+
+
 # ── install ──────────────────────────────────────────────────────────