feat: add check latest option

Author: PascalThuet

docs/reference/core.md

@@ -65,10 +65,15 @@ specify init my-project --integration copilot --branch-numbering timestamp
 
 ```bash
 specify check
+specify check --latest
 ```
 
 Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool.
 
+Use `--latest` to also check whether a newer Spec Kit CLI release is available.
+The latest-version check is opt-in; plain `specify check` stays offline.
+Run `specify check --latest` when a command behaves like an older Spec Kit version or an expected CLI feature is missing.
+
 ## Version Information
 
 ```bash

docs/upgrade.md

@@ -388,6 +388,15 @@ Only Spec Kit infrastructure files:
 
 ### "CLI upgrade doesn't seem to work"
 
+If a command behaves like an older Spec Kit version, first check for local CLI drift:
+
+```bash
+specify check --latest
+```
+
+For CLI-only version checks, `specify self check` reports the same latest-release status.
+Plain `specify check` stays offline; `--latest` opts into the release lookup.
+
 Verify the installation:
 
 ```bash

src/specify_cli/__init__.py

@@ -1113,7 +1113,13 @@ def _display_cmd(name: str) -> str:
     console.print(enhancements_panel)
 
 @app.command()
-def check():
+def check(
+    latest: bool = typer.Option(
+        False,
+        "--latest",
+        help="Also check whether a newer specify-cli release is available.",
+    ),
+):
     """Check that all required tools are installed."""
     show_banner()
     console.print("[bold]Checking for installed tools...[/bold]\n")
@@ -1156,6 +1162,9 @@ def check():
     if not any(agent_results.values()):
         console.print("[dim]Tip: Install a coding agent for the best experience[/dim]")
 
+    if latest:
+        _print_latest_release_check(heading="Specify CLI")
+
 
 def _feature_capabilities() -> dict[str, bool]:
     """Return stable local CLI capability flags for humans and agents."""
@@ -1308,24 +1317,11 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
         return None, "offline or timeout"
 
 
-# ===== Self Commands =====
-self_app = typer.Typer(
-    name="self",
-    help="Manage the specify CLI itself (read-only check and reserved upgrade command).",
-    add_completion=False,
-)
-app.add_typer(self_app, name="self")
-
-@self_app.command("check")
-def self_check() -> None:
-    """Check whether a newer specify-cli release is available. Read-only.
-
-    This command only checks for updates; it does not modify your installation.
-    The reserved (and currently non-destructive) `specify self upgrade` command
-    is the name that a future release will use for actual self-upgrade — its
-    behavior is not implemented in this release and is intentionally out of
-    scope here. See `specify self upgrade --help` for its current status.
-    """
+def _print_latest_release_check(heading: str | None = None) -> None:
+    """Print latest-release status and upgrade guidance for specify-cli."""
+    if heading:
+        console.print()
+        console.print(f"[bold]{heading}[/bold]")
 
     installed = _get_installed_version()
     tag, failure_reason = _fetch_latest_release_tag()
@@ -1365,6 +1361,28 @@ def self_check() -> None:
     console.print(f"[green]Up to date:[/green] {installed}")
 
 
+# ===== Self Commands =====
+self_app = typer.Typer(
+    name="self",
+    help="Manage the specify CLI itself (read-only check and reserved upgrade command).",
+    add_completion=False,
+)
+app.add_typer(self_app, name="self")
+
+@self_app.command("check")
+def self_check() -> None:
+    """Check whether a newer specify-cli release is available. Read-only.
+
+    This command only checks for updates; it does not modify your installation.
+    The reserved (and currently non-destructive) `specify self upgrade` command
+    is the name that a future release will use for actual self-upgrade — its
+    behavior is not implemented in this release and is intentionally out of
+    scope here. See `specify self upgrade --help` for its current status.
+    """
+
+    _print_latest_release_check()
+
+
 @self_app.command("upgrade")
 def self_upgrade() -> None:
     """Reserved command surface for self-upgrade; not implemented in this release.

tests/test_check_tool.py

@@ -7,7 +7,14 @@
 
 from unittest.mock import patch, MagicMock
 
-from specify_cli import check_tool
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli import app, check_tool
+from tests.conftest import strip_ansi
+
+
+runner = CliRunner()
 
 
 class TestCheckToolClaude:
@@ -103,4 +110,89 @@ def fake_which(name):
             return "/usr/bin/kiro" if name == "kiro" else None
 
         with patch("shutil.which", side_effect=fake_which):
-            assert check_tool("kiro-cli") is True
+            assert check_tool("kiro-cli") is True
+
+
+class TestCheckLatest:
+    """`specify check --latest` should opt into release checks."""
+
+    def test_check_without_latest_does_not_fetch_latest_release(self):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch(
+                "specify_cli._fetch_latest_release_tag",
+                side_effect=AssertionError("latest release lookup should not run"),
+            ) as fetch_latest,
+        ):
+            result = runner.invoke(app, ["check"])
+
+        assert result.exit_code == 0
+        fetch_latest.assert_not_called()
+
+    def test_check_latest_reports_update_available(self):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch("specify_cli._get_installed_version", return_value="0.8.2"),
+            patch("specify_cli._fetch_latest_release_tag", return_value=("v0.8.8", None)),
+        ):
+            result = runner.invoke(app, ["check", "--latest"])
+
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "Specify CLI" in output
+        assert "Update available" in output
+        assert "0.8.2" in output
+        assert "0.8.8" in output
+        assert "git+https://github.com/github/spec-kit.git@v0.8.8" in output
+
+    def test_check_latest_reports_up_to_date(self):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch("specify_cli._get_installed_version", return_value="0.8.8"),
+            patch("specify_cli._fetch_latest_release_tag", return_value=("v0.8.8", None)),
+        ):
+            result = runner.invoke(app, ["check", "--latest"])
+
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "Specify CLI" in output
+        assert "Up to date: 0.8.8" in output
+        assert "Update available" not in output
+
+    def test_check_latest_handles_unknown_installed_version(self):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch("specify_cli._get_installed_version", return_value="unknown"),
+            patch("specify_cli._fetch_latest_release_tag", return_value=("v0.8.8", None)),
+        ):
+            result = runner.invoke(app, ["check", "--latest"])
+
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "Specify CLI" in output
+        assert "Current version could not be determined" in output
+        assert "Latest release: 0.8.8" in output
+        assert "git+https://github.com/github/spec-kit.git@v0.8.8" in output
+
+    @pytest.mark.parametrize(
+        "failure_reason",
+        [
+            "offline or timeout",
+            "rate limited (configure ~/.specify/auth.json with a GitHub token)",
+        ],
+    )
+    def test_check_latest_handles_lookup_failure(self, failure_reason):
+        with (
+            patch("specify_cli.check_tool", return_value=True),
+            patch("specify_cli._get_installed_version", return_value="0.8.2"),
+            patch("specify_cli._fetch_latest_release_tag", return_value=(None, failure_reason)),
+        ):
+            result = runner.invoke(app, ["check", "--latest"])
+
+        output = strip_ansi(result.output)
+        normalized = " ".join(output.split())
+        normalized_reason = " ".join(failure_reason.split())
+        assert result.exit_code == 0
+        assert "Specify CLI" in output
+        assert "Installed: 0.8.2" in output
+        assert f"Could not check latest release: {normalized_reason}" in normalized