fix(cli): soften self-upgrade rollback hints

Author: chordpli

README.md

@@ -104,8 +104,8 @@ specify self upgrade --dry-run
 # Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
 specify self upgrade
 
-# Or pin a specific release tag
-specify self upgrade --tag vX.Y.Z
+# Or pin a specific release tag (replace with your desired release tag)
+specify self upgrade --tag v0.8.6
 ```
 
 Bare `specify self upgrade` executes immediately, matching the `pip install -U` / `uv tool upgrade` / `npm update` convention. `uvx`-ephemeral runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed).

docs/upgrade.md

@@ -9,7 +9,7 @@
 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
 | **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
-| **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z` | Upgrade to a specific release tag instead of the latest stable. |
+| **CLI Tool — pin a version** | `specify self upgrade --tag v0.8.6` | Upgrade to a specific release tag instead of the latest stable. Replace `v0.8.6` with the release tag you want. |
 | **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
 | **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. |
 | **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project. |
@@ -35,8 +35,8 @@ specify self upgrade --dry-run
 # Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
 specify self upgrade
 
-# Or pin a specific release tag
-specify self upgrade --tag vX.Y.Z
+# Or pin a specific release tag (replace with the release tag you want)
+specify self upgrade --tag v0.8.6
 ```
 
 Bare `specify self upgrade` executes immediately, matching the `pip install -U` / `uv tool upgrade` / `npm update` convention. The CLI classifies your runtime into one of: `uv tool`, `pipx`, `uvx (ephemeral)`, source checkout, or unsupported. Only `uv tool` and `pipx` are upgraded automatically; the other paths print path-specific guidance and exit 0 without touching anything.

src/specify_cli/__init__.py

@@ -1753,6 +1753,20 @@ def _canonicalize_version_text(value: str) -> str:
         return normalized
 
 
+def _stable_release_tag_for_version(version_text: str) -> str | None:
+    """Return `vX.Y.Z` only for exact stable release versions."""
+    try:
+        parsed = Version(version_text)
+    except InvalidVersion:
+        return None
+    if parsed.pre or parsed.post or parsed.dev or parsed.local:
+        return None
+    release = parsed.release
+    if len(release) != 3:
+        return None
+    return f"v{release[0]}.{release[1]}.{release[2]}"
+
+
 def _render_argv(argv: list[str]) -> str:
     """Render argv for copy/paste on the current platform."""
     return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
@@ -2425,14 +2439,20 @@ def _rollback_hint(plan: _UpgradePlan) -> str:
             "Could not determine the previous version; "
             "reinstall manually from: https://github.com/github/spec-kit/releases"
         )
+    rollback_tag = _stable_release_tag_for_version(plan.pre_upgrade_snapshot)
+    if rollback_tag is None:
+        return (
+            "Previous version was not an exact stable release tag; "
+            "reinstall manually from: https://github.com/github/spec-kit/releases"
+        )
     if plan.method == _InstallMethod.PIPX:
         return (
             f"To pin back to the previous version: pipx install --force "
-            f"git+https://github.com/github/spec-kit.git@v{plan.pre_upgrade_snapshot}"
+            f"git+https://github.com/github/spec-kit.git@{rollback_tag}"
         )
     return (
         f"To pin back to the previous version: uv tool install specify-cli --force "
-        f"--from git+https://github.com/github/spec-kit.git@v{plan.pre_upgrade_snapshot}"
+        f"--from git+https://github.com/github/spec-kit.git@{rollback_tag}"
     )
 
 

tests/test_self_upgrade.py

@@ -1082,6 +1082,24 @@ def test_pipx_failure_prints_pipx_rollback_hint(self, pipx_argv0, clean_environ)
             "git+https://github.com/github/spec-kit.git@v0.7.5"
         ) in out
 
+    def test_prerelease_failure_degrades_rollback_hint_to_releases_page(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli.shutil.which", return_value="/usr/bin/uv"
+        ), patch("specify_cli.subprocess.run") as mock_run, patch(
+            "specify_cli._get_installed_version", return_value="1.0.0rc1"
+        ):
+            mock_urlopen.return_value = _mock_urlopen_response({"tag_name": "v1.0.0"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Previous version was not an exact stable release tag" in out
+        assert "https://github.com/github/spec-kit/releases" in out
+        assert "git+https://github.com/github/spec-kit.git@v1.0.0rc1" not in out
+
 
 class TestVerificationMismatch:
     """Installer says 0 but the binary is still the old version → exit 2."""