msd-core/gsd-core/workflows/update.md

Check for GSD updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

Detect the installed GSD version, scope, runtime, and config dir.

First, derive PREFERRED_CONFIG_DIR and PREFERRED_RUNTIME from the invoking prompt's execution_context path — this is the one input only the workflow knows:

• If the path contains /gsd-core/workflows/update.md, strip that suffix and store the remainder as PREFERRED_CONFIG_DIR.
• Infer PREFERRED_RUNTIME from the path: /.codex/ -> codex; /.gemini/antigravity-ide/, /.gemini/antigravity-cli/, /.gemini/antigravity/, /.agent/ -> antigravity (.agent is the local Antigravity install dir; see bin/install.js getDirName('antigravity'), #503); /.gemini/ -> gemini; /.config/kilo/ or /.kilo/ -> kilo; /.config/opencode/ or /.opencode/ -> opencode; otherwise claude.

Then resolve the install context via the deterministic projection (#498). Do NOT re-derive scope, runtime, or version by hand — update-context owns that cascade in tested code (gsd-core/bin/lib/update-context.cjs), the same way check-latest-version owns the package name (#2992):

# Resolve gsd-tools.cjs WITHOUT yet knowing GSD_DIR. The running workflow lives
# at <PREFERRED_CONFIG_DIR>/gsd-core/workflows/update.md, so its sibling
# bin/gsd-tools.cjs is the authoritative tool for THIS install. Fall back to a
# global copy, then to gsd-tools on PATH.
GSD_TOOLS=""
for cand in \
  "$PREFERRED_CONFIG_DIR/gsd-core/bin/gsd-tools.cjs" \
  "$HOME/.claude/gsd-core/bin/gsd-tools.cjs"; do
  if [ -n "$cand" ] && [ -f "$cand" ]; then GSD_TOOLS="$cand"; break; fi
done
# Last resort: the gsd-tools shim on PATH — resolved to its absolute path and
# invoked via the variable (never a bare `gsd-tools` command; see #2851).
if [ -z "$GSD_TOOLS" ] && command -v gsd-tools >/dev/null 2>&1; then
  GSD_TOOLS="$(command -v gsd-tools)"
fi

UC=""
if [ -n "$GSD_TOOLS" ]; then
  case "$GSD_TOOLS" in
    *.cjs) UC="$(node "$GSD_TOOLS" update-context --config-dir "$PREFERRED_CONFIG_DIR" --runtime "$PREFERRED_RUNTIME" --json 2>/dev/null)" ;;
    *)     UC="$("$GSD_TOOLS" update-context --config-dir "$PREFERRED_CONFIG_DIR" --runtime "$PREFERRED_RUNTIME" --json 2>/dev/null)" ;;
  esac
fi

if [ -n "$UC" ]; then
  INSTALLED_VERSION="$(printf '%s' "$UC" | jq -r '.installedVersion')"
  INSTALL_SCOPE="$(printf '%s' "$UC" | jq -r '.scope')"
  TARGET_RUNTIME="$(printf '%s' "$UC" | jq -r '.runtime')"
  GSD_DIR="$(printf '%s' "$UC" | jq -r '.gsdDir')"
else
  # No tool resolvable / projection failed -> treat as a fresh install.
  INSTALLED_VERSION="0.0.0"
  INSTALL_SCOPE="UNKNOWN"
  TARGET_RUNTIME="claude"
  GSD_DIR=""
fi

echo "$INSTALLED_VERSION"
echo "$INSTALL_SCOPE"
echo "$TARGET_RUNTIME"
echo "$GSD_DIR"

Parse output:

• Line 1 = installed version (0.0.0 means unknown version)
• Line 2 = install scope (LOCAL, GLOBAL, or UNKNOWN)
• Line 3 = target runtime (claude, opencode, gemini, kilo, codex, antigravity)
• Line 4 = resolved GSD config dir (e.g. /Users/me/.claude, /Users/me/.gemini); empty if scope is UNKNOWN. Capture this as GSD_DIR and pass it to subsequent steps so they don't re-derive the runtime path.
• If scope is UNKNOWN, proceed to install using the --claude --global fallback.

update-context reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so CWD=$HOME does not misdetect as LOCAL), env-var overrides (CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR, KILO_CONFIG, XDG_CONFIG_HOME, CODEX_HOME, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in tests/issue-498-update-context.test.cjs.

If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install.

If VERSION file missing (version resolves to 0.0.0): report the installed version as Unknown and proceed to install (treated as 0.0.0 for comparison).

Determine the release channel from `$ARGUMENTS`. This selects which npm dist-tag the entire update flow targets — `latest` (stable) by default, or `next` (the RC channel established by ADR #660) when the user opts in with `--next`/`--rc`:

case " $ARGUMENTS " in
  *" --next "*|*" --rc "*)
    TAG="next"
    CHANNEL_LABEL="next (RC)"
    ;;
  *)
    TAG="latest"
    CHANNEL_LABEL="latest (stable)"
    ;;
esac

TAG is restricted to latest/next by check-latest-version.cjs (it rejects any other value with exit 2), so no arbitrary dist-tag can leak through. Omitting --next/--rc reproduces the prior behavior exactly: TAG=latest.

Check npm for latest version via the deterministic script. **Do NOT run `npm view` or `npm search` directly** — the package name must come from the script, not from a free choice at execution time. (#2992: LLM-driven prescriptions of npm package names produced wrong-package queries; moving the package name into a script constant closes that gap.)

The GSD_DIR value emitted by get_installed_version (line 4) resolves to the runtime-specific config dir (~/.claude/, ~/.gemini/, ~/.codex/, etc.), so the script invocation works for every runtime — not just Claude. If GSD_DIR is empty (scope UNKNOWN), skip this step and go directly to install.

LATEST_RESULT is a JSON document with the documented shape { ok: bool, version: string, reason: string, detail?: string }. Parse via jq ONLY when the script actually ran. When GSD_DIR is empty (scope UNKNOWN), skip the check entirely and seed the parsed fields with their no-op values so downstream logic does not mistake an unset LATEST_RESULT for a failed network check (#2993 CR feedback):

if [ -z "$GSD_DIR" ]; then
  # No install detected — fall through to install step; version-check is skipped.
  LATEST_RESULT=""
  LATEST_STATUS=0
  LATEST_OK=false
  LATEST_VERSION=""
  LATEST_REASON="no_install_detected"
else
  LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json --tag "$TAG" 2>/dev/null)"
  LATEST_STATUS=$?
  # #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT
  # is empty and piping it to `jq` produces a parse error on stderr while
  # leaving LATEST_OK / LATEST_REASON as empty strings. Fail the check with a
  # meaningful reason instead of a blank diagnostic.
  if [ -n "$LATEST_RESULT" ]; then
    LATEST_OK="$(printf '%s' "$LATEST_RESULT" | jq -r '.ok // false')"
    LATEST_VERSION="$(printf '%s' "$LATEST_RESULT" | jq -r '.version // empty')"
    LATEST_REASON="$(printf '%s' "$LATEST_RESULT" | jq -r '.reason // empty')"
  else
    LATEST_OK=false
    LATEST_VERSION=""
    LATEST_REASON="script_not_found_or_node_unavailable"
  fi
fi

If LATEST_OK is not true (or LATEST_STATUS is non-zero):

Couldn't check for updates (reason: {LATEST_REASON}, exit: {LATEST_STATUS}).

To update manually: `npx -y --package=@opengsd/gsd-core@{TAG} -- gsd-core --global`

Exit.

Compare installed vs latest:

Only when TAG=next (the user passed --next/--rc), prepend a channel banner so they know they are leaving the stable line — add this line immediately after the **Latest:** line in whichever output block renders:

Channel: {CHANNEL_LABEL}

On the default stable channel (TAG=latest), do NOT add a channel line — the output must match the prior stable behavior exactly.

When TAG=next, the "latest" value is the release candidate published under @next (e.g. 1.4.0-rc.1). Apply standard semver precedence for prereleases (1.4.0-rc.1 is newer than 1.3.1 but older than the final 1.4.0). Do NOT treat an -rc.N suffix as a dev install or as "behind" — offer it as an available update.

If installed == latest:

## GSD Update

**Installed:** X.Y.Z
**Latest:** X.Y.Z

You're already on the latest version.

Exit.

If installed > latest:

## GSD Update

**Installed:** X.Y.Z
**Latest:** A.B.C

You're ahead of the latest release — this looks like a dev install.

If you see a "⚠ dev install — re-run installer to sync hooks" warning in
your statusline, your hook files are older than your VERSION file. Fix it
by re-running the local installer from your dev branch:

    node bin/install.js --global --claude

Running /gsd:update would install the npm release (A.B.C) and downgrade
your dev version — do NOT use it to resolve this warning.

Exit.

**If update available**, fetch and show what's new BEFORE updating:

1. Fetch changelog from GitHub raw URL and save to a temp file, e.g. /tmp/gsd-changelog-$$.md.
2. Extract entries between installed and latest versions using the deterministic range helper (fix for #3496 — do NOT use ad-hoc grep/awk extraction which silently skips intermediate versions):

CHANGELOG_TMP="/tmp/gsd-changelog-$$.md"
curl -fsSL "https://raw.githubusercontent.com/open-gsd/gsd-core/main/CHANGELOG.md" -o "$CHANGELOG_TMP" 2>/dev/null \
  || wget -qO "$CHANGELOG_TMP" "https://raw.githubusercontent.com/open-gsd/gsd-core/main/CHANGELOG.md" 2>/dev/null

GSD_CHANGESET_CLI="$GSD_DIR/scripts/changeset/cli.cjs"
if [ ! -f "$GSD_CHANGESET_CLI" ]; then
  CHANGELOG_PREVIEW="(Changelog CLI not found at $GSD_CHANGESET_CLI — reinstall GSD to restore preview. Update will still proceed.)"
else
  EXTRACT_JSON=$(node "$GSD_CHANGESET_CLI" extract \
    --from "$INSTALLED_VERSION" \
    --to "$LATEST_VERSION" \
    --changelog "$CHANGELOG_TMP" \
    --json 2>&1)
  EXTRACT_EXIT=$?

  if [ "$EXTRACT_EXIT" -eq 2 ]; then
    # Exit 2 = no releases in range (e.g. versions are equal or changelog is sparse)
    CHANGELOG_PREVIEW="No changelog updates between v${INSTALLED_VERSION} and v${LATEST_VERSION}."
  elif [ "$EXTRACT_EXIT" -ne 0 ] || [ -z "$EXTRACT_JSON" ]; then
    CHANGELOG_PREVIEW="(Could not extract changelog — update will still proceed)"
  else
    # Re-run without --json to get the human-readable markdown for display
    CHANGELOG_PREVIEW=$(node "$GSD_CHANGESET_CLI" extract \
      --from "$INSTALLED_VERSION" \
      --to "$LATEST_VERSION" \
      --changelog "$CHANGELOG_TMP" 2>/dev/null || echo "(changelog unavailable)")
  fi
fi
# Clean up temp changelog now that both extract runs are done
rm -f "$CHANGELOG_TMP"

3. Display preview and ask for confirmation, using $CHANGELOG_PREVIEW from the extract step above:

## GSD Update Available

**Installed:** {INSTALLED_VERSION}
**Latest:** {LATEST_VERSION}

### What's New
────────────────────────────────────────────────────────────

{CHANGELOG_PREVIEW}

────────────────────────────────────────────────────────────

⚠️  **Note:** The installer performs a clean install of GSD folders:
- `commands/gsd/` will be wiped and replaced
- `gsd-core/` will be wiped and replaced
- `agents/gsd-*` files will be replaced

(Paths are relative to detected runtime install location:
global: `~/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, `~/.config/kilo/`, or `~/.codex/`
local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, `./.kilo/`, or `./.codex/`)

Your custom files in other locations are preserved:
- Custom commands not in `commands/gsd/` ✓
- Custom agents not prefixed with `gsd-` ✓
- Custom hooks ✓
- Your CLAUDE.md files ✓

If you've modified any GSD files directly, they'll be automatically backed up to `gsd-local-patches/` and can be reapplied with `/gsd:update --reapply` after the update.

Text mode (workflow.text_mode: true in config or --text flag): Set TEXT_MODE=true if --text is present in $ARGUMENTS OR text_mode from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where AskUserQuestion is not available. Use AskUserQuestion:

• Question: "Proceed with update?"
• Options:
  • "Yes, update now"
  • "No, cancel"

If user cancels: Exit.

Before running the installer, detect and back up any user-added files inside GSD-managed directories. These are files that exist on disk but are NOT listed in `gsd-file-manifest.json` — i.e., files the user added themselves that the installer does not know about and will delete during the wipe.

Do not use bash path-stripping (${filepath#$RUNTIME_DIR/}) or node -e require() inline — those patterns fail when $RUNTIME_DIR is unset and the stripped relative path may not match manifest key format, which causes CUSTOM_COUNT=0 even when custom files exist (bug #1997). Use gsd-tools.cjs query detect-custom-files or the bundled gsd-tools.cjs detect-custom-files path — both resolve paths reliably with Node.js path.relative().

First, resolve the config directory (RUNTIME_DIR) from the install scope detected in get_installed_version:

# RUNTIME_DIR is the resolved config directory (e.g. ~/.config/opencode, ~/.gemini).
# get_installed_version emits it as GSD_DIR (LOCAL or GLOBAL install dir, or empty
# when scope is UNKNOWN). Empty RUNTIME_DIR skips the backup below.
RUNTIME_DIR="$GSD_DIR"

If RUNTIME_DIR is empty or does not exist, skip this step (no config dir to inspect).

Otherwise run detect-custom-files:

CUSTOM_JSON=''
if [ -f "$GSD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
  CUSTOM_JSON=$(node "$GSD_TOOLS" detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
fi
if [ -z "$CUSTOM_JSON" ]; then
  CUSTOM_JSON='{"custom_files":[],"custom_count":0}'
fi
CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")

If CUSTOM_COUNT > 0:

Back up each custom file to $RUNTIME_DIR/gsd-user-files-backup/ before the installer wipes the directories:

BACKUP_DIR="$RUNTIME_DIR/gsd-user-files-backup"
mkdir -p "$BACKUP_DIR"

# Parse custom_files array from CUSTOM_JSON and copy each file
node - "$RUNTIME_DIR" "$BACKUP_DIR" "$CUSTOM_JSON" <<'JSEOF'
const [,, runtimeDir, backupDir, customJson] = process.argv;
const { custom_files } = JSON.parse(customJson);
const fs = require('fs');
const path = require('path');
for (const relPath of custom_files) {
  const src = path.join(runtimeDir, relPath);
  const dst = path.join(backupDir, relPath);
  if (!fs.existsSync(src)) continue;

  try {
    fs.mkdirSync(path.dirname(dst), { recursive: true });
    fs.copyFileSync(src, dst);
    console.log('  Backed up: ' + relPath);
  } catch (err) {
    const code = err && err.code ? String(err.code) : 'ERROR';
    console.log('  Skipped (non-fatal): ' + relPath + ' [' + code + ']');
  }
}
JSEOF

Then inform the user:

⚠️  Found N custom file(s) inside GSD-managed directories.
    These have been backed up to gsd-user-files-backup/ before the update.
    Restore them after the update if needed.

If CUSTOM_COUNT == 0: No user-added files detected. Continue to install.

Run the update using the install type detected in step 1:

Build runtime flag from step 1:

RUNTIME_FLAG="--$TARGET_RUNTIME"

If LOCAL install:

npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --local

If GLOBAL install:

npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --global

If UNKNOWN install:

npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core --claude --global

Capture output. If install fails, show error and exit.

Clear the update cache so statusline indicator disappears:

expand_home() {
  case "$1" in
    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
    *) printf '%s\n' "$1" ;;
  esac
}

# Clear update cache across preferred, env-derived, and default runtime directories
CACHE_DIRS=()
if [ -n "$PREFERRED_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$PREFERRED_CONFIG_DIR")" )
fi
if [ -n "$CLAUDE_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$CLAUDE_CONFIG_DIR")" )
fi
if [ -n "$GEMINI_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$GEMINI_CONFIG_DIR")" )
fi
if [ -n "$KILO_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$KILO_CONFIG_DIR")" )
elif [ -n "$KILO_CONFIG" ]; then
  CACHE_DIRS+=( "$(dirname "$(expand_home "$KILO_CONFIG")")" )
elif [ -n "$XDG_CONFIG_HOME" ]; then
  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/kilo" )
fi
if [ -n "$OPENCODE_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$OPENCODE_CONFIG_DIR")" )
elif [ -n "$OPENCODE_CONFIG" ]; then
  CACHE_DIRS+=( "$(dirname "$(expand_home "$OPENCODE_CONFIG")")" )
elif [ -n "$XDG_CONFIG_HOME" ]; then
  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/opencode" )
fi
if [ -n "$CODEX_HOME" ]; then
  CACHE_DIRS+=( "$(expand_home "$CODEX_HOME")" )
fi
if [ -n "$CURSOR_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$CURSOR_CONFIG_DIR")" )
fi
if [ -n "$WINDSURF_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$WINDSURF_CONFIG_DIR")" )
fi
if [ -n "$AUGMENT_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$AUGMENT_CONFIG_DIR")" )
fi
if [ -n "$TRAE_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$TRAE_CONFIG_DIR")" )
fi
if [ -n "$QWEN_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$QWEN_CONFIG_DIR")" )
fi
if [ -n "$HERMES_HOME" ]; then
  CACHE_DIRS+=( "$(expand_home "$HERMES_HOME")" )
fi
if [ -n "$CODEBUDDY_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$CODEBUDDY_CONFIG_DIR")" )
fi
if [ -n "$CLINE_CONFIG_DIR" ]; then
  CACHE_DIRS+=( "$(expand_home "$CLINE_CONFIG_DIR")" )
fi

for dir in "${CACHE_DIRS[@]}"; do
  if [ -n "$dir" ]; then
    rm -f "$dir/cache/gsd-update-check"*.json
  fi
done

for dir in .claude .config/opencode .opencode .gemini/antigravity-ide .gemini/antigravity-cli .gemini/antigravity .agent .gemini .config/kilo .kilo .codex .cursor .codeium/windsurf .augment .trae .qwen .hermes .codebuddy .cline; do
  rm -f "./$dir/cache/gsd-update-check"*.json
  rm -f "$HOME/$dir/cache/gsd-update-check"*.json
done

# Clear the shared tool-agnostic cache written by gsd-check-update.js hook (#2784).
# The hook uses ~/.cache/gsd/gsd-update-check.json (legacy) or a per-package name
# like gsd-update-check-opengsd-gsd-core.json; the glob clears all variants so the
# statusline stops showing the stale "⬆ /gsd:update" indicator after update.
rm -f "$HOME/.cache/gsd/gsd-update-check"*.json

The SessionStart hook (gsd-check-update.js) writes to the detected runtime's cache directory, so preferred/env-derived paths and default paths must all be cleared to prevent stale update indicators.

Format completion message (changelog was already shown in confirmation step):

╔═══════════════════════════════════════════════════════════╗
║  GSD Updated: v1.5.10 → v1.5.15                           ║
╚═══════════════════════════════════════════════════════════╝

⚠️  Restart your runtime to pick up the new commands.

[View full changelog](https://github.com/open-gsd/gsd-core/blob/main/CHANGELOG.md)

After update completes, check if the installer detected and backed up any locally modified files:

Check for gsd-local-patches/backup-meta.json in the config directory.

If patches found:

Local patches were backed up before the update.
Run `/gsd:update --reapply` to merge your modifications into the new version.

If no patches: Continue normally.

<success_criteria>

• Installed version read correctly
• Latest version checked via npm
• Update skipped if already current
• Changelog fetched and displayed BEFORE update
• Clean install warning shown
• User confirmation obtained
• Update executed successfully
• Restart reminder shown </success_criteria>