feat: daily update check + /gstack-upgrade skill (v0.3.4) (garrytan#42)

* feat: add daily update check script + /gstack-upgrade skill

bin/gstack-update-check: pure bash, checks VERSION against remote once/day,
outputs UPGRADE_AVAILABLE or JUST_UPGRADED. Uses ~/.gstack/ for state.

gstack-upgrade/SKILL.md: new skill with inline upgrade flow for all preambles.
Detects global-git, local-git, vendored installs. Shows What's New from CHANGELOG.

browse/test/gstack-update-check.test.ts: 10 test cases covering all branch paths.

* refactor: remove version check from find-browse, simplify to binary locator

Delete checkVersion(), readCache(), writeCache(), fetchRemoteSHA(),
resolveSkillDir(), CacheEntry interface, REPO_URL/CACHE_PATH/CACHE_TTL
constants, and META output from find-browse.ts.

Version checking is now handled by bin/gstack-update-check (previous commit).

* feat: add update check preamble to all 9 skills

Every skill now runs bin/gstack-update-check on invocation. If an upgrade
is available, reads gstack-upgrade/SKILL.md inline upgrade flow.

Also adds AskUserQuestion to 5 skills that lacked it (gstack root, browse,
qa, retro, setup-browser-cookies) and Bash to plan-eng-review.

Simplifies qa and setup-browser-cookies setup blocks (removes META parsing).

* chore: bump version and changelog (v0.3.4)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove unused import + add corrupt cache test

Address pre-landing review findings:
- Remove unused mkdirSync import from gstack-update-check.test.ts
- Add Path I test: corrupt cache file falls through to remote fetch

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: garrytan

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.4 — 2026-03-13
+
+### Added
+- **Daily update check** — all 9 skills now check for new versions once per day via `bin/gstack-update-check` (pure bash, <5ms cached). Prompts user via AskUserQuestion with option to upgrade or defer 24h.
+- **`/gstack-upgrade` skill** — standalone upgrade command that detects install type (global-git, local-git, vendored), upgrades, and shows a "What's New" summary from CHANGELOG
+- **"Just upgraded" confirmation** — after upgrading, the next skill invocation shows "Running gstack v{new} (just updated!)" via `~/.gstack/just-upgraded-from` marker
+- **`AskUserQuestion` added to 5 skills** — gstack (root), browse, qa, retro, setup-browser-cookies now have AskUserQuestion in allowed-tools for upgrade prompts
+- **`Bash` added to plan-eng-review** — enables the update check preamble to run in plan review sessions
+- `browse/test/gstack-update-check.test.ts` — 10 test cases covering all script branch paths with `GSTACK_REMOTE_URL` env var for test isolation
+- `TODOS.md` for tracking deferred work
+
+### Changed
+- **Version check is now one system** — removed SHA-based `checkVersion()` from `browse/src/find-browse.ts` (~120 lines deleted) and `browse/test/find-browse.test.ts` (~100 lines deleted). Replaced by `bin/gstack-update-check` bash script using semver VERSION comparison with 24h cache.
+- Simplified `qa/SKILL.md` and `setup-browser-cookies/SKILL.md` setup blocks — removed old `BROWSE_OUTPUT`/`META` parsing, now use simple `find-browse` call
+- Updated `browse/bin/find-browse` shim comments to reflect simplified role (binary locator only)
+
+### Removed
+- `checkVersion()`, `readCache()`, `writeCache()`, `fetchRemoteSHA()`, `resolveSkillDir()`, `CacheEntry` interface from `browse/src/find-browse.ts`
+- `META:UPDATE_AVAILABLE` protocol from find-browse output
+- Old META-based upgrade instructions from qa and setup-browser-cookies SKILL.md files
+- Legacy `/tmp/gstack-latest-version` cache file (cleaned up by `setup` script)
+
 ## Unreleased — 2026-03-14
 
 ### Changed

SKILL.md

@@ -10,11 +10,21 @@ description: |
 allowed-tools:
   - Bash
   - Read
+  - AskUserQuestion
 
 ---
 <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
 <!-- Regenerate: bun run gen:skill-docs -->
 
+## Update Check (run first)
+
+```bash
+_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD"
+```
+
+If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
+
 # gstack browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command.

SKILL.md.tmpl

@@ -10,9 +10,19 @@ description: |
 allowed-tools:
   - Bash
   - Read
+  - AskUserQuestion
 
 ---
 
+## Update Check (run first)
+
+```bash
+_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD"
+```
+
+If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
+
 # gstack browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command.

TODOS.md

@@ -0,0 +1,12 @@
+# TODOS
+
+## Auto-upgrade mode (zero-prompt)
+
+**What:** Add a `GSTACK_AUTO_UPGRADE=1` env var or `~/.gstack/config` option that skips the AskUserQuestion prompt and upgrades automatically when a new version is detected.
+
+**Why:** Power users and CI environments may want zero-friction upgrades without being asked every time.
+
+**Context:** The current upgrade system (v0.3.4) always prompts via AskUserQuestion. This TODO adds an opt-in bypass. Implementation is ~10 lines in the preamble instructions: check for the env var/config before calling AskUserQuestion, and if set, go straight to the upgrade flow. Depends on the full upgrade system being stable first — wait for user feedback on the prompt-based flow before adding this.
+
+**Effort:** S (small)
+**Priority:** P3 (nice-to-have, revisit after adoption data)

VERSION

@@ -1 +1 @@
-0.3.3
+0.3.4

bin/gstack-update-check

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# gstack-update-check — daily version check for all skills.
+#
+# Output (one line, or nothing):
+#   JUST_UPGRADED <old> <new>       — marker found from recent upgrade
+#   UPGRADE_AVAILABLE <old> <new>   — remote VERSION differs from local
+#   (nothing)                       — up to date or check skipped
+#
+# Env overrides (for testing):
+#   GSTACK_DIR          — override auto-detected gstack root
+#   GSTACK_REMOTE_URL   — override remote VERSION URL
+#   GSTACK_STATE_DIR    — override ~/.gstack state directory
+set -euo pipefail
+
+GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+VERSION_FILE="$GSTACK_DIR/VERSION"
+REMOTE_URL="${GSTACK_REMOTE_URL:-https://raw.githubusercontent.com/garrytan/gstack/main/VERSION}"
+
+# ─── Step 1: Read local version ──────────────────────────────
+LOCAL=""
+if [ -f "$VERSION_FILE" ]; then
+  LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
+fi
+if [ -z "$LOCAL" ]; then
+  exit 0  # No VERSION file → skip check
+fi
+
+# ─── Step 2: Check "just upgraded" marker ─────────────────────
+if [ -f "$MARKER_FILE" ]; then
+  OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
+  rm -f "$MARKER_FILE"
+  mkdir -p "$STATE_DIR"
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  if [ -n "$OLD" ]; then
+    echo "JUST_UPGRADED $OLD $LOCAL"
+  fi
+  exit 0
+fi
+
+# ─── Step 3: Check cache freshness (24h = 1440 min) ──────────
+if [ -f "$CACHE_FILE" ]; then
+  # Cache is fresh if modified within 1440 minutes
+  STALE=$(find "$CACHE_FILE" -mmin +1440 2>/dev/null || true)
+  if [ -z "$STALE" ]; then
+    # Cache is fresh — read it
+    CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+    case "$CACHED" in
+      UP_TO_DATE*)
+        exit 0
+        ;;
+      UPGRADE_AVAILABLE*)
+        # Verify local version still matches cached old version
+        CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
+        if [ "$CACHED_OLD" = "$LOCAL" ]; then
+          echo "$CACHED"
+          exit 0
+        fi
+        # Local version changed (manual upgrade?) — fall through to re-check
+        ;;
+    esac
+  fi
+fi
+
+# ─── Step 4: Slow path — fetch remote version ────────────────
+mkdir -p "$STATE_DIR"
+
+REMOTE=""
+REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
+REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
+
+# Validate: must look like a version number (reject HTML error pages)
+if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9.]+$'; then
+  # Invalid or empty response — assume up to date
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+# Versions differ — upgrade available
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$CACHE_FILE"
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"

browse/SKILL.md

@@ -10,11 +10,21 @@ description: |
 allowed-tools:
   - Bash
   - Read
+  - AskUserQuestion
 
 ---
 <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
 <!-- Regenerate: bun run gen:skill-docs -->
 
+## Update Check (run first)
+
+```bash
+_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD"
+```
+
+If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
+
 # browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.

browse/SKILL.md.tmpl

@@ -10,9 +10,19 @@ description: |
 allowed-tools:
   - Bash
   - Read
+  - AskUserQuestion
 
 ---
 
+## Update Check (run first)
+
+```bash
+_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD"
+```
+
+If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
+
 # browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.

browse/bin/find-browse

@@ -1,11 +1,11 @@
 #!/bin/bash
 # Shim: delegates to compiled find-browse binary, falls back to basic discovery.
-# The compiled binary adds version checking and META signal support.
+# The compiled binary handles git root detection for workspace-local installs.
 DIR="$(cd "$(dirname "$0")/.." && pwd)/dist"
 if test -x "$DIR/find-browse"; then
   exec "$DIR/find-browse" "$@"
 fi
-# Fallback: basic discovery (no version check)
+# Fallback: basic discovery
 ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
 if [ -n "$ROOT" ] && test -x "$ROOT/.claude/skills/gstack/browse/dist/browse"; then
   echo "$ROOT/.claude/skills/gstack/browse/dist/browse"

browse/src/find-browse.ts

@@ -1,28 +1,14 @@
 /**
- * find-browse — locate the gstack browse binary + check for updates.
+ * find-browse — locate the gstack browse binary.
  *
  * Compiled to browse/dist/find-browse (standalone binary, no bun runtime needed).
- *
- * Output protocol:
- *   Line 1: /path/to/binary              (always present)
- *   Line 2+: META:<TYPE> <json-payload>   (optional, 0 or more)
- *
- * META types:
- *   META:UPDATE_AVAILABLE — local binary is behind origin/main
- *
- * All version checks are best-effort: network failures, missing files, and
- * cache errors degrade gracefully to outputting only the binary path.
+ * Outputs the absolute path to the browse binary on stdout, or exits 1 if not found.
  */
 
 import { existsSync } from 'fs';
-import { readFileSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { join } from 'path';
 import { homedir } from 'os';
 
-const REPO_URL = 'https://github.com/garrytan/gstack.git';
-const CACHE_PATH = '/tmp/gstack-latest-version';
-const CACHE_TTL = 14400; // 4 hours in seconds
-
 // ─── Binary Discovery ───────────────────────────────────────────
 
 function getGitRoot(): string | null {
@@ -55,114 +41,6 @@ export function locateBinary(): string | null {
   return null;
 }
 
-// ─── Version Check ──────────────────────────────────────────────
-
-interface CacheEntry {
-  sha: string;
-  timestamp: number;
-}
-
-function readCache(): CacheEntry | null {
-  try {
-    const content = readFileSync(CACHE_PATH, 'utf-8').trim();
-    const parts = content.split(/\s+/);
-    if (parts.length < 2) return null;
-    const sha = parts[0];
-    const timestamp = parseInt(parts[1], 10);
-    if (!sha || isNaN(timestamp)) return null;
-    // Validate SHA is hex
-    if (!/^[0-9a-f]{40}$/i.test(sha)) return null;
-    return { sha, timestamp };
-  } catch {
-    return null;
-  }
-}
-
-function writeCache(sha: string, timestamp: number): void {
-  try {
-    writeFileSync(CACHE_PATH, `${sha} ${timestamp}\n`);
-  } catch {
-    // Cache write failure is non-fatal
-  }
-}
-
-function fetchRemoteSHA(): string | null {
-  try {
-    const proc = Bun.spawnSync(['git', 'ls-remote', REPO_URL, 'refs/heads/main'], {
-      stdout: 'pipe',
-      stderr: 'pipe',
-      timeout: 10_000, // 10s timeout
-    });
-    if (proc.exitCode !== 0) return null;
-    const output = proc.stdout.toString().trim();
-    const sha = output.split(/\s+/)[0];
-    if (!sha || !/^[0-9a-f]{40}$/i.test(sha)) return null;
-    return sha;
-  } catch {
-    return null;
-  }
-}
-
-function resolveSkillDir(binaryPath: string): string | null {
-  const home = homedir();
-  const globalPrefix = join(home, '.claude', 'skills', 'gstack');
-  if (binaryPath.startsWith(globalPrefix)) return globalPrefix;
-
-  // Workspace-local: binary is at $ROOT/.claude/skills/gstack/browse/dist/browse
-  // Skill dir is $ROOT/.claude/skills/gstack
-  const parts = binaryPath.split('/.claude/skills/gstack/');
-  if (parts.length === 2) return parts[0] + '/.claude/skills/gstack';
-
-  return null;
-}
-
-export function checkVersion(binaryDir: string): string | null {
-  // Read local version
-  const versionFile = join(binaryDir, '.version');
-  let localSHA: string;
-  try {
-    localSHA = readFileSync(versionFile, 'utf-8').trim();
-  } catch {
-    return null; // No .version file → skip check
-  }
-  if (!localSHA) return null;
-
-  const now = Math.floor(Date.now() / 1000);
-
-  // Check cache
-  let remoteSHA: string | null = null;
-  const cache = readCache();
-  if (cache && (now - cache.timestamp) < CACHE_TTL) {
-    remoteSHA = cache.sha;
-  }
-
-  // Fetch from remote if cache miss
-  if (!remoteSHA) {
-    remoteSHA = fetchRemoteSHA();
-    if (remoteSHA) {
-      writeCache(remoteSHA, now);
-    }
-  }
-
-  if (!remoteSHA) return null; // Offline or error → skip check
-
-  // Compare
-  if (localSHA === remoteSHA) return null; // Up to date
-
-  // Determine skill directory for update command
-  const binaryPath = join(binaryDir, 'browse');
-  const skillDir = resolveSkillDir(binaryPath);
-  if (!skillDir) return null;
-
-  const payload = JSON.stringify({
-    current: localSHA.slice(0, 8),
-    latest: remoteSHA.slice(0, 8),
-    command: `cd ${skillDir} && git stash && git fetch origin && git reset --hard origin/main && ./setup`,
-  });
-
-  return `META:UPDATE_AVAILABLE ${payload}`;
-}
-
 // ─── Main ───────────────────────────────────────────────────────
 
 function main() {
@@ -173,9 +51,6 @@ function main() {
   }
 
   console.log(bin);
-
-  const meta = checkVersion(dirname(bin));
-  if (meta) console.log(meta);
 }
 
 main();