feat: CLI startup PyPI version check (once per shell session)

- Add _maybe_notify_pypi_update() — checks PyPI on first CLI invocation
- Prints one-liner if outdated: 'specsmith X.Y.Z available (you have ...)'
- 3-second timeout, never blocks CLI, once per shell session via env var
- Skippable with SPECSMITH_NO_AUTO_UPDATE=1

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

.specsmith/chat/chat-2026-04-09T13-18-42.jsonl

@@ -0,0 +1,2 @@
+{"role":"error","text":"[Apr 9, 09:18:43 AM] Agent process ended (exit code 1) — send a message to restart","ts":"2026-04-09T13:18:43.464Z"}
+{"role":"error","text":"specsmith not responding (tried: \"C:\\Users\\trist\\.specsmith\\venv\\Scripts\\specsmith.exe\")\nTo fix:\n  • Ctrl+Shift+P → specsmith: Install or Upgrade\n  • Or set specsmith.executablePath in VS Code settings\n  • On Windows / pip install path:\n    %LOCALAPPDATA%\\Python\\pythoncore-3.12-64\\Scripts\\specsmith.exe","ts":"2026-04-09T13:19:02.885Z"}

scaffold.yml

@@ -6,6 +6,7 @@ platforms:
 - linux
 - macos
 spec_version: 0.3.6
+aee_phase: inception
 description: Applied Epistemic Engineering toolkit for AI-assisted development.
 vcs_platform: github
 branching_strategy: gitflow

src/specsmith/cli.py

@@ -64,6 +64,7 @@ def invoke(self, ctx: click.Context) -> object:
 
         if not skip:
             _maybe_prompt_project_update()
+            _maybe_notify_pypi_update()
 
         return super().invoke(ctx)
 
@@ -125,6 +126,47 @@ def _maybe_prompt_project_update() -> None:
         pass  # Never break the actual command on version check errors
 
 
+def _maybe_notify_pypi_update() -> None:
+    """Check PyPI for a newer specsmith version. Prints one-liner if outdated.
+
+    Runs at most once per shell session (tracked via env var). Uses a 3-second
+    timeout to avoid blocking the CLI. Only checks stable versions.
+    """
+    import os
+
+    session_key = "SPECSMITH_PYPI_CHECKED"
+    if os.environ.get(session_key):
+        return
+    os.environ[session_key] = "1"
+
+    try:
+        import json as _json  # noqa: PLC0415
+        from urllib.request import urlopen  # noqa: PLC0415
+
+        resp = urlopen("https://pypi.org/pypi/specsmith/json", timeout=3)  # noqa: S310
+        data = _json.loads(resp.read())
+        latest = data.get("info", {}).get("version", "")
+        if not latest:
+            return
+
+        # Simple version comparison: split into tuples of ints
+        def _ver(v: str) -> tuple[int, ...]:
+            import re
+
+            clean = re.match(r"(\d+\.\d+\.\d+)", v)
+            return tuple(int(x) for x in clean.group(1).split(".")) if clean else (0,)
+
+        if _ver(latest) > _ver(__version__):
+            console.print(
+                f"  [dim]specsmith [bold]{latest}[/bold] available "
+                f"(you have {__version__}). "
+                f"Run [bold]specsmith self-update[/bold] or "
+                f"[bold]pipx upgrade specsmith[/bold].[/dim]"
+            )
+    except Exception:  # noqa: BLE001
+        pass  # Never block the CLI on network errors
+
+
 @click.group(cls=_AutoUpdateGroup)
 @click.version_option(version=__version__, prog_name="specsmith")
 def main() -> None: