check_update.sh: direction-less version compare + stale 24h cache produce backwards "update available" banners

[fflory]

What happened

On 2026-07-02 the SessionStart hook (.claude-plugin/check_update.sh) displayed:

Installed:  v0.1.13
Available:  v0.1.12

i.e. it urged an "upgrade" to an older version. The live remote VERSION on main was already 0.1.13 — no update existed.

Root cause (two interacting issues)

1. Direction-less compare — the banner fires on any string mismatch, not just a real upgrade:

   # check_update.sh, line 51
   if [ -n "$remote_ver" ] && [ "$remote_ver" != "$local_ver" ]; then

2. Stale cache — ~/.ai-dev-kit/.update-check is trusted for 24h. Ours held REMOTE_VERSION=0.1.12 from a fetch made shortly before main's VERSION moved to 0.1.13. After a local update to 0.1.13, every session for the rest of the cache TTL compared fresh-local against stale-remote and produced the backwards banner. (rm ~/.ai-dev-kit/.update-check clears it.)

A local version can legitimately be ahead of the cached remote for up to 24h after any upgrade — so this reproduces for anyone who updates within the cache window.

Suggested fix

• Only fire when remote is strictly newer, e.g.:

  newest=$(printf '%s\n%s\n' "$local_ver" "$remote_ver" | sort -V | tail -1)
  if [ "$newest" = "$remote_ver" ] && [ "$remote_ver" != "$local_ver" ]; then

• Optionally: invalidate/refresh the cache when local_ver is newer than the cached remote, since that state proves the cache is stale.

Aware this file is on death row

#548 retires .claude-plugin/ (including this script) after the #547 soak — if that lands soon, feel free to close this as overtaken. Two notes while the window is open:

• During the soak, every user who upgrades will hit the backwards banner for up to 24h (the buggy compare ships in the same window that generates version churn).
• retire .claude-plugin/: a-d-k stops being a Claude Code plugin #548's test plan explicitly does not garbage-collect the SessionStart hook entry that install.sh previously wrote into existing users' ~/.claude/settings.json — once the script is deleted, those users get a dangling hook (bash: .../check_update.sh: No such file or directory) at every session start until they remove it by hand. A note in the release/migration docs would help.

Environment: global install (install.sh --global), macOS, ai-dev-kit 0.1.13.