@therocketcode/gsd-core 1.4.0

package/gsd-core/workflows/update.md

@@ -0,0 +1,496 @@
+<purpose>
+Check for GSD updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="get_installed_version">
+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):
+
+```bash
+# 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).
+</step>
+
+<step name="parse_update_channel">
+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`:
+
+```bash
+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`.
+</step>
+
+<step name="check_latest_version">
+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):
+
+```bash
+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):
+
+```text
+Couldn't check for updates (reason: {LATEST_REASON}, exit: {LATEST_STATUS}).
+
+To update manually: `npx -y --package=@therocketcode/gsd-core@{TAG} -- gsd-core --global`
+```
+
+Exit.
+</step>
+
+<step name="compare_versions">
+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.
+</step>
+
+<step name="show_changes_and_confirm">
+**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):
+
+```bash
+CHANGELOG_TMP="/tmp/gsd-changelog-$$.md"
+curl -fsSL "https://raw.githubusercontent.com/TheRocketCodeMX/gsd-core/main/CHANGELOG.md" -o "$CHANGELOG_TMP" 2>/dev/null \
+  || wget -qO "$CHANGELOG_TMP" "https://raw.githubusercontent.com/TheRocketCodeMX/gsd-core/main/CHANGELOG.md" 2>/dev/null
+
+EXTRACT_JSON=$(node "$GSD_DIR/gsd-core/scripts/changeset/cli.cjs" extract \
+  --from "$INSTALLED_VERSION" \
+  --to "$LATEST_VERSION" \
+  --changelog "$CHANGELOG_TMP" \
+  --json 2>/dev/null)
+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_DIR/gsd-core/scripts/changeset/cli.cjs" extract \
+    --from "$INSTALLED_VERSION" \
+    --to "$LATEST_VERSION" \
+    --changelog "$CHANGELOG_TMP" 2>/dev/null || echo "(changelog unavailable)")
+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.
+</step>
+
+<step name="backup_custom_files">
+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`:
+
+```bash
+# 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`:
+
+```bash
+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:
+
+```bash
+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.
+</step>
+
+<step name="run_update">
+Run the update using the install type detected in step 1:
+
+Build runtime flag from step 1:
+```bash
+RUNTIME_FLAG="--$TARGET_RUNTIME"
+```
+
+**If LOCAL install:**
+```bash
+npx -y --package=@therocketcode/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --local
+```
+
+**If GLOBAL install:**
+```bash
+npx -y --package=@therocketcode/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --global
+```
+
+**If UNKNOWN install:**
+```bash
+npx -y --package=@therocketcode/gsd-core@"$TAG" -- gsd-core --claude --global
+```
+
+Capture output. If install fails, show error and exit.
+
+Clear the update cache so statusline indicator disappears:
+
+```bash
+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-therocketcode-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.
+</step>
+
+<step name="display_result">
+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/TheRocketCodeMX/gsd-core/blob/main/CHANGELOG.md)
+```
+</step>
+
+
+<step name="check_local_patches">
+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.
+</step>
+</process>
+
+<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>

package/gsd-core/workflows/validate-phase.md

@@ -0,0 +1,181 @@
+<purpose>
+Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
+</purpose>
+
+<required_reading>
+@~/.claude/gsd-core/references/ui-brand.md
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-nyquist-auditor — Validates verification coverage
+</available_agent_types>
+
+<process>
+
+## 0. Initialize
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_AUDITOR=$(gsd_run query agent-skills gsd-nyquist-auditor)
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
+
+```bash
+AUDITOR_MODEL=$(gsd_run query resolve-model gsd-nyquist-auditor --raw)
+NYQUIST_CFG=$(gsd_run query config-get workflow.nyquist_validation --raw --default true)
+```
+
+If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /gsd:settings."
+
+Display banner: `GSD > VALIDATE PHASE {N}: {name}`
+
+## 1. Detect Input State
+
+```bash
+VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+```
+
+- **State A** (`VALIDATION_FILE` non-empty): Audit existing
+- **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} ${GSD_WS} first."
+
+## 2. Discovery
+
+### 2a. Read Phase Artifacts
+
+Read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.
+
+### 2b. Build Requirement-to-Task Map
+
+Per task: `{ task_id, plan_id, wave, requirement_ids, has_automated_command }`
+
+### 2c. Detect Test Infrastructure
+
+State A: Parse from existing VALIDATION.md Test Infrastructure table.
+State B: Filesystem scan:
+
+```bash
+find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
+find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40
+```
+
+### 2d. Cross-Reference
+
+Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
+
+## 3. Gap Analysis
+
+Classify each requirement:
+
+| Status | Criteria |
+|--------|----------|
+| COVERED | Test exists, targets behavior, runs green |
+| PARTIAL | Test exists, failing or incomplete |
+| MISSING | No test found |
+
+Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
+
+No gaps → skip to Step 6, set `nyquist_compliant: true`.
+
+## 4. Present Gap Plan
+
+
+**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.
+Call AskUserQuestion with gap table and options:
+1. "Fix all gaps" → Step 5
+2. "Skip — mark manual-only" → add to Manual-Only, Step 6
+3. "Cancel" → exit
+
+## 5. Spawn gsd-nyquist-auditor
+
+Print: `◆ Spawning nyquist auditor... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
+```
+Agent(
+  prompt="Read ~/.claude/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
+    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
+    "<gaps>{gap list}</gaps>" +
+    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
+    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>" +
+    "${AGENT_SKILLS_AUDITOR}",
+  subagent_type="gsd-nyquist-auditor",
+  model="{AUDITOR_MODEL}",
+  description="Fill validation gaps for Phase {N}"
+)
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
+Handle return:
+- `## GAPS FILLED` → record tests + map updates, Step 6
+- `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
+- `## ESCALATE` → move all to manual-only, Step 6
+
+## 6. Generate/Update VALIDATION.md
+
+**State B (create):**
+1. Read template from `~/.claude/gsd-core/templates/VALIDATION.md`
+2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
+3. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
+
+**State A (update):**
+1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
+2. Append audit trail:
+
+```markdown
+## Validation Audit {date}
+| Metric | Count |
+|--------|-------|
+| Gaps found | {N} |
+| Resolved | {M} |
+| Escalated | {K} |
+```
+
+## 7. Commit
+
+```bash
+git add {test_files}
+git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
+
+gsd_run query commit "docs(phase-${PHASE}): add/update validation strategy"
+```
+
+## 8. Results + Routing
+
+**Compliant:**
+```
+GSD > PHASE {N} IS NYQUIST-COMPLIANT
+All requirements have automated verification.
+▶ Next: /gsd:audit-milestone ${GSD_WS}
+```
+
+**Partial:**
+```
+GSD > PHASE {N} VALIDATED (PARTIAL)
+{M} automated, {K} manual-only.
+▶ Retry: /gsd:validate-phase {N} ${GSD_WS}
+```
+
+Display `/clear` reminder.
+
+</process>
+
+<success_criteria>
+- [ ] Nyquist config checked (exit if disabled)
+- [ ] Input state detected (A/B/C)
+- [ ] State C exits cleanly
+- [ ] PLAN/SUMMARY files read, requirement map built
+- [ ] Test infrastructure detected
+- [ ] Gaps classified (COVERED/PARTIAL/MISSING)
+- [ ] User gate with gap table
+- [ ] Auditor spawned with complete context
+- [ ] All three return formats handled
+- [ ] VALIDATION.md created or updated
+- [ ] Test files committed separately
+- [ ] Results with routing presented
+</success_criteria>