@pareto4/pp-core 1.5.0

package/pp-core/workflows/update.md

@@ -0,0 +1,501 @@
+<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 `/pp-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/`, `/.agents/` or `/.agent/` -> `antigravity` (`.agents` is the canonical local Antigravity install dir (#791); `.agent` is the legacy form (#503); see bin/install.js `getDirName('antigravity')`); `/.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 (`pp-core/bin/lib/update-context.cjs`), the same way `check-latest-version` owns the package name (#2992):
+
+```bash
+# Resolve pp-tools.cjs WITHOUT yet knowing GSD_DIR. The running workflow lives
+# at <PREFERRED_CONFIG_DIR>/pp-core/workflows/update.md, so its sibling
+# bin/pp-tools.cjs is the authoritative tool for THIS install. Fall back to a
+# global copy, then to pp-tools on PATH.
+GSD_TOOLS=""
+for cand in \
+  "$PREFERRED_CONFIG_DIR/pp-core/bin/pp-tools.cjs" \
+  "$HOME/.claude/pp-core/bin/pp-tools.cjs"; do
+  if [ -n "$cand" ] && [ -f "$cand" ]; then GSD_TOOLS="$cand"; break; fi
+done
+# Last resort: the pp-tools shim on PATH — resolved to its absolute path and
+# invoked via the variable (never a bare `pp-tools` command; see #2851).
+if [ -z "$GSD_TOOLS" ] && command -v pp-tools >/dev/null 2>&1; then
+  GSD_TOOLS="$(command -v pp-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/pp-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=@pareto4/pp-core@{TAG} -- pp-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 /pp: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/pp-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/pp-changelog-$$.md"
+curl -fsSL "https://gitlab.com/pareto4/pp-core/-/raw/main/CHANGELOG.md" -o "$CHANGELOG_TMP" 2>/dev/null \
+  || wget -qO "$CHANGELOG_TMP" "https://gitlab.com/pareto4/pp-core/-/raw/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
+- `pp-core/` will be wiped and replaced
+- `agents/pp-*` 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 `pp-` ✓
+- Custom hooks ✓
+- Your CLAUDE.md files ✓
+
+If you've modified any GSD files directly, they'll be automatically backed up to `pp-local-patches/` and can be reapplied with `/pp: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 `pp-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 `pp-tools.cjs query detect-custom-files`
+or the bundled `pp-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/pp-user-files-backup/` before the
+installer wipes the directories:
+
+```bash
+BACKUP_DIR="$RUNTIME_DIR/pp-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 pp-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=@pareto4/pp-core@"$TAG" -- pp-core "$RUNTIME_FLAG" --local
+```
+
+**If GLOBAL install:**
+```bash
+npx -y --package=@pareto4/pp-core@"$TAG" -- pp-core "$RUNTIME_FLAG" --global
+```
+
+**If UNKNOWN install:**
+```bash
+npx -y --package=@pareto4/pp-core@"$TAG" -- pp-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/pp-update-check"*.json
+  fi
+done
+
+for dir in .claude .config/opencode .opencode .gemini/antigravity-ide .gemini/antigravity-cli .gemini/antigravity .agents .agent .gemini .config/kilo .kilo .codex .cursor .codeium/windsurf .augment .trae .qwen .hermes .codebuddy .cline; do
+  rm -f "./$dir/cache/pp-update-check"*.json
+  rm -f "$HOME/$dir/cache/pp-update-check"*.json
+done
+
+# Clear the shared tool-agnostic cache written by pp-check-update.js hook (#2784).
+# The hook uses ~/.cache/gsd/pp-update-check.json (legacy) or a per-package name
+# like pp-update-check-pareto4-pp-core.json; the glob clears all variants so the
+# statusline stops showing the stale "⬆ /pp:update" indicator after update.
+rm -f "$HOME/.cache/gsd/pp-update-check"*.json
+```
+
+The SessionStart hook (`pp-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://gitlab.com/pareto4/pp-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 pp-local-patches/backup-meta.json in the config directory.
+
+**If patches found:**
+
+```
+Local patches were backed up before the update.
+Run `/pp: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>