chore: bump version to 0.9.3

fix: render script command hints with active agent separator (#2649 )
* fix script command hints for agent separators * Address command hint review feedback * chore: remove whitespace-only PR churn * test: fix PowerShell command hint invocation * fix: preserve hyphens in script command hints * fix: render managed script command hints
2026-07-04 04:45:43 +08:00 · 2026-06-03 21:25:59 +00:00 · 2026-06-03 16:24:13 -05:00 · 2026-06-03 16:02:26 -05:00 · 2026-06-03 14:26:07 -05:00 · 2026-06-03 12:04:54 -05:00
42 changed files with 4699 additions and 205 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,20 @@

 <!-- insert new changelog below this comment -->

+## [0.9.3] - 2026-06-03
+
+### Changed
+
+- fix: render script command hints with active agent separator (#2649)
+- chore(tests): fix ruff lint violations in tests/ (#2827)
+- fix(workflows): validate run_id in RunState.load before touching the … (#2813)
+- feat(cli): implement specify self upgrade (#2475)
+- feat(workflows): allow resume to accept updated workflow inputs (#2815)
+- catalog: rename "superpowers-bridge" to "superspec" (v1.0.1) (#2772)
+- fix(cli): force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError (#2817)
+- fix(plan): clarify quickstart validation guide scope (#2805)
+- chore: release 0.9.2, begin 0.9.3.dev0 development (#2823)
+
 ## [0.9.2] - 2026-06-02

 ### Changed
--- a/README.md
+++ b/README.md
@@ -59,6 +59,24 @@ specify init my-project --integration copilot
 cd my-project
 ```

+To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options.
+
+```bash
+# Check whether a newer release is available (read-only — does not modify anything)
+specify self check
+
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
+
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with your desired release tag)
+specify self upgrade --tag vX.Y.Z[suffix]
+```
+
+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. For `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. `uvx` (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed).
+
 ### 3. Establish project principles

 Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.
@@ -133,7 +151,7 @@ Run `specify integration list` to see all available integrations in your install

 After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration <agent> --integration-options="--skills"` installs agent skills instead of slash-command prompt files.

-#### Core Commands
+### Core Commands

 Essential commands for the Spec-Driven Development workflow:

@@ -146,7 +164,7 @@ Essential commands for the Spec-Driven Development workflow:
 | `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution |
 | `/speckit.implement`     | `speckit-implement`    | Execute all tasks to build the feature according to the plan               |

-#### Optional Commands
+### Optional Commands

 Additional commands for enhanced quality and validation:

--- a/docs/community/extensions.md
+++ b/docs/community/extensions.md
@@ -114,8 +114,8 @@ The following community-contributed extensions are available in [`catalog.commun
 | Staff Review Extension | Staff-engineer-level code review that validates implementation against spec, checks security, performance, and test coverage | `code` | Read-only | [spec-kit-staff-review](https://github.com/arunt14/spec-kit-staff-review) |
 | Status Report | Project status, feature progress, and next-action recommendations for spec-driven workflows | `visibility` | Read-only | [Open-Agent-Tools/spec-kit-status](https://github.com/Open-Agent-Tools/spec-kit-status) |
 | Superpowers Bridge | Orchestrates obra/superpowers skills within the spec-kit SDD workflow across the full lifecycle (clarification, TDD, review, verification, critique, debugging, branch completion) | `process` | Read+Write | [superpowers-bridge](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/superpowers-bridge) |
-| Superpowers Bridge (WangX0111) | Bridges spec-kit with obra/superpowers (brainstorming, TDD, subagent, code-review) into a unified, resumable workflow with graceful degradation and session progress tracking | `process` | Read+Write | [superspec](https://github.com/WangX0111/superspec) |
 | Superpowers Implementation Bridge | Thin orchestrator between Spec Kit (design) and Superpowers (implementation). Cross-agent. | `process` | Read+Write | [speckit-superpowers-bridge](https://github.com/lihan3238/speckit-superpowers-bridge) |
+| Superspec | Bridges spec-kit with obra/superpowers (brainstorming, TDD, subagent, code-review) into a unified, resumable workflow with graceful degradation and session progress tracking | `process` | Read+Write | [superspec](https://github.com/WangX0111/superspec) |
 | Team Assign | Assign tasks.md items to human engineers, split into subtasks, and generate a per-engineer workboard | `process` | Read+Write | [spec-kit-team-assign](https://github.com/tarunkumarbhati/spec-kit-team-assign) |
 | Time Machine | Retroactively apply the full SDD workflow to existing codebases — analyse, spec, and ship feature-by-feature | `process` | Read+Write | [spec-kit-time-machine](https://github.com/teeyo/spec-kit-time-machine) |
 | TinySpec | Lightweight single-file workflow for small tasks — skip the heavy multi-step SDD process | `process` | Read+Write | [spec-kit-tinyspec](https://github.com/Quratulain-bilal/spec-kit-tinyspec) |
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -88,6 +88,8 @@ specify version

 This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.

+**Stay current:** Run `specify self check` periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the [Upgrade Guide](./upgrade.md).
+
 After initialization, you should see the following commands available in your coding agent:

 - `/speckit.specify` - Create specifications
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -28,8 +28,18 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 specify workflow resume <run_id>
 ```

+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `-i` / `--input`    | Updated input values as `key=value` (repeatable)         |
+
 Resumes a paused or failed workflow run from the exact step where it stopped. Useful after responding to a gate step or fixing an issue that caused a failure.

+Supplied `--input` values are merged over the run's stored inputs and re-validated against the workflow's input types, then the blocked step is re-run with the updated values. This lets a run continue with information that only became available after it paused, or with a corrected value after a failure:
+
+```bash
+specify workflow resume <run_id> --input cmd="exit 0"
+```
+
 ## Workflow Status

 ```bash
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -8,8 +8,10 @@

 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
-| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files |
-| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Reinstall/upgrade a pipx-installed CLI to a specific release |
+| **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
+| **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. |
+| **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
+| **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. |
 | **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |
 | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |

@@ -19,12 +21,32 @@

 The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.

-Before upgrading, you can check whether a newer released version is available:
+### Recommended: `specify self upgrade`
+
+The CLI ships with two self-management commands that handle the common case automatically:

 ```bash
+# Check whether a newer release is available (read-only — does not modify anything)
 specify self check
+
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
+
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with the tag you want)
+specify self upgrade --tag vX.Y.Z[suffix]
 ```

+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. The CLI classifies your runtime into one of: `uv tool`, `pipx`, `uvx (ephemeral)`, source checkout, or unsupported. Only `uv tool` and `pipx` are upgraded automatically; for `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work. The other paths print path-specific guidance and exit 0 without touching anything.
+
+Pinned tags must start with `vMAJOR.MINOR.PATCH`. Optional suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms such as `v1.0.0-rc1`, `v0.8.0.dev0`, `v0.8.0+build.42`, or the combination `v1.0.0-rc1+build.42`; branch names, hash refs, `latest`, and bare versions without `v` are rejected.
+
+Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed). If that internal timeout fires, `specify self upgrade` exits 124 and reports that it timed out while waiting for the installer subprocess, including the configured timeout and manual retry command. A real installer exit code 124 is propagated with `Upgrade failed. Installer exit code: 124.`, so scripts should treat exit 124 as ambiguous and inspect the message when they need to distinguish the two cases.
+
+If your installed CLI is older than the release that introduced `specify self upgrade`, use the manual equivalents below. These commands are also useful when you want explicit control over the installer command.
+
 ### If you installed with `uv tool install`

 Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
@@ -54,10 +76,14 @@ pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
 ### Verify the upgrade

 ```bash
+# Confirms the CLI is working and shows installed tools
 specify check
+
+# Confirms the installed version against the latest GitHub release
+specify self check
 ```

-This shows installed tools and confirms the CLI is working. Use `specify version` to confirm which persistent CLI version is currently on your `PATH`.
+`specify check` shows the surrounding tool environment; `specify self check` is read-only and tells you whether you're now on the latest release (`Up to date: X.Y.Z`) or if a newer one became available between releases.

 ---

@@ -186,8 +212,8 @@ Restart your IDE to refresh the command list.
 ### Scenario 1: "I just want new slash commands"

 ```bash
-# Upgrade CLI (if using persistent install)
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+# Upgrade CLI (auto-detects uv tool vs pipx install)
+specify self upgrade

 # Update project files to get new commands
 specify init --here --force --integration copilot
@@ -204,7 +230,7 @@ cp .specify/memory/constitution.md /tmp/constitution-backup.md
 cp -r .specify/templates /tmp/templates-backup

 # 2. Upgrade CLI
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+specify self upgrade

 # 3. Update project
 specify init --here --force --integration copilot
@@ -388,15 +414,19 @@ Only Spec Kit infrastructure files:

 ### "CLI upgrade doesn't seem to work"

-If a command behaves like an older Spec Kit version, first check for local CLI drift:
+If a command behaves like an older Spec Kit version, first ask the CLI itself:

 ```bash
+# Read-only — prints "Up to date: X.Y.Z" or "Update available: X.Y.Z → vY.Z.W"
 specify self check
+
+# Preview the install method, current version, and target tag the upgrade would use
+specify self upgrade --dry-run
 ```

 `specify check` is an offline environment scan; `specify self check` is the CLI version lookup.

-Verify the installation:
+If `self check` shows the wrong version, verify the installation:

 ```bash
 # Check installed tools
--- a/extensions/catalog.community.json
+++ b/extensions/catalog.community.json
@@ -3039,13 +3039,13 @@
      "created_at": "2026-03-30T00:00:00Z",
      "updated_at": "2026-05-24T01:07:34Z"
    },
-    "superpowers-bridge": {
-      "name": "Superpowers Bridge",
-      "id": "superpowers-bridge",
+    "superspec": {
+      "name": "Superspec",
+      "id": "superspec",
      "description": "Bridges spec-kit workflows with obra/superpowers capabilities for brainstorming, TDD, code review, and resumable execution.",
      "author": "WangX0111",
-      "version": "1.0.0",
-      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.0.zip",
+      "version": "1.0.1",
+      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.1.zip",
      "repository": "https://github.com/WangX0111/superspec",
      "homepage": "https://github.com/WangX0111/superspec",
      "documentation": "https://github.com/WangX0111/superspec/blob/main/README.md",
@@ -3070,7 +3070,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-04-22T00:00:00Z",
-      "updated_at": "2026-04-22T00:00:00Z"
+      "updated_at": "2026-05-30T00:00:00Z"
    },
    "sync": {
      "name": "Spec Sync",
@@ -3607,4 +3607,4 @@
      "updated_at": "2026-04-13T00:00:00Z"
    }
  }
-}
+}
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.9.2"
+version = "0.9.3"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
--- a/scripts/bash/check-prerequisites.sh
+++ b/scripts/bash/check-prerequisites.sh
@@ -117,20 +117,20 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
 # Validate required directories and files
 if [[ ! -d "$FEATURE_DIR" ]]; then
    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure." >&2
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
    exit 1
 fi

 if [[ ! -f "$IMPL_PLAN" ]]; then
    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan." >&2
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
    exit 1
 fi

 # Check for tasks.md if required
 if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_TASKS__ first to create the task list." >&2
+    echo "Run $(format_speckit_command tasks "$REPO_ROOT") first to create the task list." >&2
    exit 1
 fi

--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -307,6 +307,83 @@ has_jq() {
    command -v jq >/dev/null 2>&1
 }

+get_invoke_separator() {
+    local repo_root="${1:-$(get_repo_root)}"
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        printf '%s\n' "$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+        return 0
+    fi
+
+    local integration_json="$repo_root/.specify/integration.json"
+    local separator="."
+    local parsed_with_jq=0
+
+    if [[ -f "$integration_json" ]]; then
+        if command -v jq >/dev/null 2>&1; then
+            local jq_separator
+            if jq_separator=$(jq -r '(.default_integration // .integration // "") as $k | if $k == "" then "." else (.integration_settings[$k].invoke_separator // ".") end' "$integration_json" 2>/dev/null); then
+                parsed_with_jq=1
+                case "$jq_separator" in
+                    "."|"-") separator="$jq_separator" ;;
+                esac
+            fi
+        fi
+
+        if [[ "$parsed_with_jq" -eq 0 ]] && command -v python3 >/dev/null 2>&1; then
+            if separator=$(python3 - "$integration_json" <<'PY' 2>/dev/null
+import json
+import sys
+
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        state = json.load(fh)
+    key = state.get("default_integration") or state.get("integration") or ""
+    settings = state.get("integration_settings")
+    separator = "."
+    if isinstance(key, str) and isinstance(settings, dict):
+        entry = settings.get(key)
+        if isinstance(entry, dict) and entry.get("invoke_separator") in {".", "-"}:
+            separator = entry["invoke_separator"]
+    print(separator)
+except Exception:
+    print(".")
+PY
+); then
+                case "$separator" in
+                    "."|"-") ;;
+                    *) separator="." ;;
+                esac
+            else
+                separator="."
+            fi
+        fi
+    fi
+
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    printf '%s\n' "$separator"
+}
+
+format_speckit_command() {
+    local command_name="$1"
+    local repo_root="${2:-$(get_repo_root)}"
+    local separator
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        separator="$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+    else
+        separator=$(get_invoke_separator "$repo_root")
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    fi
+
+    command_name="${command_name#/}"
+    command_name="${command_name#speckit.}"
+    command_name="${command_name#speckit-}"
+    command_name="${command_name//./$separator}"
+
+    printf '/speckit%s%s\n' "$separator" "$command_name"
+}
+
 # Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
 # Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
 json_escape() {
--- a/scripts/bash/setup-tasks.sh
+++ b/scripts/bash/setup-tasks.sh
@@ -35,13 +35,13 @@ fi

 if [[ ! -f "$IMPL_PLAN" ]]; then
    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan." >&2
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
    exit 1
 fi

 if [[ ! -f "$FEATURE_SPEC" ]]; then
    echo "ERROR: spec.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure." >&2
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
    exit 1
 fi

--- a/scripts/powershell/check-prerequisites.ps1
+++ b/scripts/powershell/check-prerequisites.ps1
@@ -89,20 +89,23 @@ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GI
 # Validate required directories and files
 if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
    Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure."
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $specifyCommand first to create the feature structure."
    exit 1
 }

 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
    Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan."
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $planCommand first to create the implementation plan."
    exit 1
 }

 # Check for tasks.md if required
 if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
    Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_TASKS__ first to create the task list."
+    $tasksCommand = Format-SpecKitCommand -CommandName 'tasks' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $tasksCommand first to create the task list."
    exit 1
 }

--- a/scripts/powershell/common.ps1
+++ b/scripts/powershell/common.ps1
@@ -355,6 +355,58 @@ function Test-DirHasFiles {
    }
 }

+function Get-InvokeSeparator {
+    param([string]$RepoRoot = (Get-RepoRoot))
+
+    if ($null -eq $script:SpecKitInvokeSeparatorCache) {
+        $script:SpecKitInvokeSeparatorCache = @{}
+    }
+    if ($script:SpecKitInvokeSeparatorCache.ContainsKey($RepoRoot)) {
+        return $script:SpecKitInvokeSeparatorCache[$RepoRoot]
+    }
+
+    $separator = '.'
+    $integrationJson = Join-Path $RepoRoot '.specify/integration.json'
+    if (Test-Path -LiteralPath $integrationJson -PathType Leaf) {
+        try {
+            $state = Get-Content -LiteralPath $integrationJson -Raw | ConvertFrom-Json
+            $key = if ($state.default_integration) { [string]$state.default_integration } elseif ($state.integration) { [string]$state.integration } else { '' }
+            if ($key -and $state.integration_settings) {
+                $settingProperty = $state.integration_settings.PSObject.Properties[$key]
+                if ($settingProperty) {
+                    $setting = $settingProperty.Value
+                    if ($setting -and ($setting.invoke_separator -eq '.' -or $setting.invoke_separator -eq '-')) {
+                        $separator = [string]$setting.invoke_separator
+                    }
+                }
+            }
+        } catch {
+            $separator = '.'
+        }
+    }
+
+    $script:SpecKitInvokeSeparatorCache[$RepoRoot] = $separator
+    return $separator
+}
+
+function Format-SpecKitCommand {
+    param(
+        [Parameter(Mandatory = $true)][string]$CommandName,
+        [string]$RepoRoot = (Get-RepoRoot)
+    )
+
+    $separator = Get-InvokeSeparator -RepoRoot $RepoRoot
+    $name = $CommandName.TrimStart('/')
+    if ($name.StartsWith('speckit.')) {
+        $name = $name.Substring(8)
+    } elseif ($name.StartsWith('speckit-')) {
+        $name = $name.Substring(8)
+    }
+    $name = $name -replace '\.', $separator
+
+    return "/speckit$separator$name"
+}
+
 # Find a usable Python 3 executable (python3, python, or py -3).
 # Returns the command/arguments as an array, or $null if none found.
 function Get-Python3Command {
--- a/scripts/powershell/setup-tasks.ps1
+++ b/scripts/powershell/setup-tasks.ps1
@@ -28,13 +28,15 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe

 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
    [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
-    [Console]::Error.WriteLine("Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan.")
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $planCommand first to create the implementation plan.")
    exit 1
 }

 if (-not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
    [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")
-    [Console]::Error.WriteLine("Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure.")
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
    exit 1
 }

--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
@@ -2717,6 +2717,22 @@ workflow_catalog_app = typer.Typer(
 workflow_app.add_typer(workflow_catalog_app, name="catalog")


+def _parse_input_values(input_values: list[str] | None) -> dict[str, Any]:
+    """Parse repeated ``key=value`` CLI inputs into a dict.
+
+    Shared by ``workflow run`` and ``workflow resume``. Exits with an error
+    on any entry missing ``=``.
+    """
+    inputs: dict[str, Any] = {}
+    for kv in input_values or []:
+        if "=" not in kv:
+            console.print(f"[red]Error:[/red] Invalid input format: {kv!r} (expected key=value)")
+            raise typer.Exit(1)
+        key, _, value = kv.partition("=")
+        inputs[key.strip()] = value.strip()
+    return inputs
+
+
@workflow_app.command("run")
 def workflow_run(
    source: str = typer.Argument(..., help="Workflow ID or YAML file path"),
@@ -2749,14 +2765,7 @@ def workflow_run(
        raise typer.Exit(1)

    # Parse inputs
-    inputs: dict[str, Any] = {}
-    if input_values:
-        for kv in input_values:
-            if "=" not in kv:
-                console.print(f"[red]Error:[/red] Invalid input format: {kv!r} (expected key=value)")
-                raise typer.Exit(1)
-            key, _, value = kv.partition("=")
-            inputs[key.strip()] = value.strip()
+    inputs = _parse_input_values(input_values)

    console.print(f"\n[bold cyan]Running workflow:[/bold cyan] {definition.name} ({definition.id})")
    console.print(f"[dim]Version: {definition.version}[/dim]\n")
@@ -2787,6 +2796,9 @@ def workflow_run(
@workflow_app.command("resume")
 def workflow_resume(
    run_id: str = typer.Argument(..., help="Run ID to resume"),
+    input_values: list[str] | None = typer.Option(
+        None, "--input", "-i", help="Updated input values as key=value pairs"
+    ),
 ):
    """Resume a paused or failed workflow run."""
    from .workflows.engine import WorkflowEngine
@@ -2795,8 +2807,10 @@ def workflow_resume(
    engine = WorkflowEngine(project_root)
    engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")

+    inputs = _parse_input_values(input_values)
+
    try:
-        state = engine.resume(run_id)
+        state = engine.resume(run_id, inputs or None)
    except FileNotFoundError:
        console.print(f"[red]Error:[/red] Run not found: {run_id}")
        raise typer.Exit(1)
@@ -3323,6 +3337,17 @@ def workflow_catalog_remove(


 def main():
+    # On Windows the default stdout/stderr code page (e.g. cp1252) cannot encode
+    # the Rich banner and box-drawing glyphs, so the CLI crashes with
+    # UnicodeEncodeError whenever output is not a UTF-8 TTY (piped, redirected to
+    # a file, or running under a legacy code page). Force UTF-8 with graceful
+    # replacement so output degrades instead of aborting. No-op on POSIX.
+    if sys.platform == "win32":
+        for _stream in (sys.stdout, sys.stderr):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")
+            except (AttributeError, ValueError, OSError):
+                pass
    app()

 if __name__ == "__main__":
--- a/src/specify_cli/_version.py
+++ b/src/specify_cli/_version.py
--- a/src/specify_cli/shared_infra.py
+++ b/src/specify_cli/shared_infra.py
@@ -3,6 +3,7 @@
 from __future__ import annotations

 import os
+import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -194,6 +195,37 @@ def _write_shared_bytes(
            temp_path.unlink()


+_BASH_FORMAT_COMMAND_RE = re.compile(
+    r"\$\(\s*format_speckit_command\s+(['\"]?)([A-Za-z0-9_.-]+)\1(?:\s+[^)]*)?\)"
+)
+_POWERSHELL_FORMAT_COMMAND_RE = re.compile(
+    r"Format-SpecKitCommand\s+-CommandName\s+(['\"])([A-Za-z0-9_.-]+)\1(?:\s+-RepoRoot\s+[^\r\n]+)?"
+)
+
+
+def _format_speckit_command(command_name: str, separator: str) -> str:
+    name = command_name.strip().lstrip("/")
+    if name.startswith("speckit."):
+        name = name[len("speckit.") :]
+    elif name.startswith("speckit-"):
+        name = name[len("speckit-") :]
+    name = name.replace(".", separator)
+    return f"/speckit{separator}{name}"
+
+
+def _resolve_dynamic_command_refs(content: str, separator: str) -> str:
+    """Render script runtime command helpers for managed shared infra copies."""
+
+    content = _BASH_FORMAT_COMMAND_RE.sub(
+        lambda match: _format_speckit_command(match.group(2), separator),
+        content,
+    )
+    return _POWERSHELL_FORMAT_COMMAND_RE.sub(
+        lambda match: f"'{_format_speckit_command(match.group(2), separator)}'",
+        content,
+    )
+
+
 def refresh_shared_templates(
    project_path: Path,
    *,
@@ -388,6 +420,7 @@ def install_shared_infra(
                            continue
                        content = src_path.read_text(encoding="utf-8")
                        content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                        content = _resolve_dynamic_command_refs(content, invoke_separator)
                        planned_copies.append(
                            (
                                dst_path,
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -281,16 +281,49 @@ def _validate_steps(
 class RunState:
    """Manages workflow run state for persistence and resume."""

+    # ``run_id`` is interpolated into a filesystem path (``runs/<run_id>``)
+    # by both ``save()`` and ``load()``. Constrain it to a charset that
+    # cannot contain path separators (``/`` ``\``), parent-directory
+    # segments (``..``), or NULs — anything that could escape the
+    # ``.specify/workflows/runs/`` directory or be mis-interpreted by the
+    # filesystem. The first-character anchor blocks IDs that start with
+    # ``-`` (which would be mistaken for a CLI flag in error messages
+    # and shell completions).
+    _RUN_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+    @classmethod
+    def _validate_run_id(cls, run_id: str) -> None:
+        """Raise ``ValueError`` if ``run_id`` is not a safe path component.
+
+        This is the single source of truth for what counts as a valid
+        ``run_id``. ``__init__`` calls it to reject malformed IDs at
+        construction time; ``load`` calls it *before* interpolating the
+        ID into a path so a malicious value cannot probe or read files
+        outside ``.specify/workflows/runs/<run_id>/``.
+        """
+        if not isinstance(run_id, str) or not cls._RUN_ID_PATTERN.match(run_id):
+            raise ValueError(
+                f"Invalid run_id {run_id!r}: must be alphanumeric with "
+                "hyphens/underscores only (and must start with an "
+                "alphanumeric character)."
+            )
+
    def __init__(
        self,
        run_id: str | None = None,
        workflow_id: str = "",
        project_root: Path | None = None,
    ) -> None:
-        self.run_id = run_id or str(uuid.uuid4())[:8]
-        if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9_-]*$', self.run_id):
-            msg = f"Invalid run_id {self.run_id!r}: must be alphanumeric with hyphens/underscores only."
-            raise ValueError(msg)
+        # ``run_id is None`` (omitted) → auto-generate. An explicit empty
+        # string is *not* the same as "omitted" and must be validated like
+        # any other caller-provided value — otherwise ``__init__("")``
+        # would silently substitute a UUID while ``load("")`` rejects, and
+        # the two entry points would diverge on the empty-string vector.
+        if run_id is None:
+            self.run_id = str(uuid.uuid4())[:8]
+        else:
+            self.run_id = run_id
+        self._validate_run_id(self.run_id)
        self.workflow_id = workflow_id
        self.project_root = project_root or Path(".")
        self.status = RunStatus.CREATED
@@ -331,7 +364,20 @@ class RunState:

    @classmethod
    def load(cls, run_id: str, project_root: Path) -> RunState:
-        """Load a run state from disk."""
+        """Load a run state from disk.
+
+        Validates ``run_id`` against ``_RUN_ID_PATTERN`` *before* building
+        the lookup path. Without this guard, a caller passing a value like
+        ``../escape`` (e.g. via ``specify workflow resume`` CLI argument)
+        would interpolate path-traversal segments into
+        ``runs_dir`` below, letting ``state_path.exists()`` probe arbitrary
+        paths and ``json.load`` read attacker-planted JSON from outside
+        the project's ``runs/`` directory. ``__init__`` already runs this
+        check on the stored ``state_data["run_id"]``, but that fires
+        *after* the file lookup — too late to prevent the disclosure.
+        Mirrors the precedent in ``agents._ensure_within_directory``.
+        """
+        cls._validate_run_id(run_id)
        runs_dir = project_root / ".specify" / "workflows" / "runs" / run_id
        state_path = runs_dir / "state.json"
        if not state_path.exists():
@@ -507,8 +553,19 @@ class WorkflowEngine:
        state.save()
        return state

-    def resume(self, run_id: str) -> RunState:
-        """Resume a paused or failed workflow run."""
+    def resume(
+        self,
+        run_id: str,
+        inputs: dict[str, Any] | None = None,
+    ) -> RunState:
+        """Resume a paused or failed workflow run.
+
+        When ``inputs`` is provided, the values are merged over the run's
+        persisted inputs and re-resolved through the same typed validation
+        path used by :meth:`execute`, so the resumed step sees updated
+        workflow inputs. Keys not supplied keep their persisted values; an
+        empty/``None`` ``inputs`` leaves the run's inputs unchanged.
+        """
        state = RunState.load(run_id, self.project_root)
        if state.status not in (RunStatus.PAUSED, RunStatus.FAILED):
            msg = f"Cannot resume run {run_id!r} with status {state.status.value!r}."
@@ -524,6 +581,12 @@ class WorkflowEngine:
        else:
            definition = self.load_workflow(state.workflow_id)

+        # Merge any newly-supplied inputs over the persisted ones and
+        # re-validate through the same typing path as the initial run.
+        if inputs:
+            merged = {**state.inputs, **inputs}
+            state.inputs = self._resolve_inputs(definition, merged)
+
        # Restore context
        context = StepContext(
            inputs=state.inputs,
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -147,7 +147,14 @@ Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generate
   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
   - Skip if project is purely internal (build scripts, one-off tools, etc.)

-3. **Agent context update**:
+3. **Create quickstart validation guide** → `quickstart.md`:
+   - Document runnable validation scenarios that prove the feature works end-to-end
+   - Include prerequisites, setup commands, test/run commands, and expected outcomes
+   - Use links or references to contracts and data model details instead of duplicating them
+   - Do not include full implementation code, model/service/controller bodies, migrations, or complete test suites
+   - Keep this artifact as a validation/run guide; implementation details belong in `tasks.md` and the implementation phase
+
+4. **Agent context update**:
   - Update the plan reference between the `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` markers in `__CONTEXT_FILE__` to point to the plan file created in step 1 (the IMPL_PLAN path)

 **Output**: data-model.md, /contracts/*, quickstart.md, updated agent context file
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -81,3 +81,72 @@ def _isolate_auth_config(monkeypatch):
    # Also clear the per-process cache so tests that unset _config_override
    # won't see a previously cached real-file result.
    monkeypatch.setattr(_auth_http, "_config_cache", None)
+
+
+@pytest.fixture
+def clean_environ(monkeypatch):
+    """Strip any real GH_TOKEN / GITHUB_TOKEN from the test environment."""
+    monkeypatch.delenv("GH_TOKEN", raising=False)
+    monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+
+
+def _fake_self_upgrade_argv0(monkeypatch, tmp_path, env_name, path_parts):
+    """Create a fake executable under tmp_path and point sys.argv[0] at it."""
+    monkeypatch.setenv(env_name, str(tmp_path))
+    fake_dir = tmp_path.joinpath(*path_parts)
+    fake_dir.mkdir(parents=True)
+    fake_specify = fake_dir / ("specify.exe" if os.name == "nt" else "specify")
+    fake_specify.write_text("#!/usr/bin/env python\n")
+    fake_specify.chmod(0o755)
+    monkeypatch.setattr("sys.argv", [str(fake_specify)])
+    return fake_specify
+
+
+@pytest.fixture
+def uv_tool_argv0(monkeypatch, tmp_path):
+    """Point sys.argv[0] at a simulated `uv tool` install path under tmp HOME."""
+    if os.name == "nt":
+        return _fake_self_upgrade_argv0(
+            monkeypatch, tmp_path, "LOCALAPPDATA", ("uv", "tools", "specify-cli", "bin")
+        )
+    return _fake_self_upgrade_argv0(
+        monkeypatch,
+        tmp_path,
+        "HOME",
+        (".local", "share", "uv", "tools", "specify-cli", "bin"),
+    )
+
+
+@pytest.fixture
+def pipx_argv0(monkeypatch, tmp_path):
+    """Point sys.argv[0] at a simulated pipx install path under tmp HOME."""
+    if os.name == "nt":
+        return _fake_self_upgrade_argv0(
+            monkeypatch, tmp_path, "LOCALAPPDATA", ("pipx", "venvs", "specify-cli", "bin")
+        )
+    return _fake_self_upgrade_argv0(
+        monkeypatch, tmp_path, "HOME", (".local", "pipx", "venvs", "specify-cli", "bin")
+    )
+
+
+@pytest.fixture
+def uvx_ephemeral_argv0(monkeypatch, tmp_path):
+    """Point sys.argv[0] at a simulated uvx ephemeral-cache path under tmp HOME."""
+    if os.name == "nt":
+        return _fake_self_upgrade_argv0(
+            monkeypatch,
+            tmp_path,
+            "LOCALAPPDATA",
+            ("uv", "cache", "archive-v0", "abc123", "bin"),
+        )
+    return _fake_self_upgrade_argv0(
+        monkeypatch, tmp_path, "HOME", (".cache", "uv", "archive-v0", "abc123", "bin")
+    )
+
+
+@pytest.fixture
+def unsupported_argv0(monkeypatch, tmp_path):
+    """Point sys.argv[0] at a path that does not match any installer prefix."""
+    return _fake_self_upgrade_argv0(
+        monkeypatch, tmp_path, "HOME", ("random", "location", "bin")
+    )
--- a/tests/extensions/git/test_git_extension.py
+++ b/tests/extensions/git/test_git_extension.py
@@ -371,7 +371,7 @@ class TestCreateFeaturePowerShell:
        )
        assert result.returncode == 0, result.stderr
        # pwsh may prefix warnings to stdout; find the JSON line
-        json_line = [l for l in result.stdout.splitlines() if l.strip().startswith("{")]
+        json_line = [ln for ln in result.stdout.splitlines() if ln.strip().startswith("{")]
        assert json_line, f"No JSON in output: {result.stdout}"
        data = json.loads(json_line[-1])
        assert "BRANCH_NAME" in data
--- a/tests/http_helpers.py
+++ b/tests/http_helpers.py
@@ -0,0 +1,15 @@
+"""HTTP test helpers shared by version-related CLI tests."""
+
+import json
+from unittest.mock import MagicMock
+
+
+def mock_urlopen_response(payload: dict) -> MagicMock:
+    """Build a urlopen context-manager mock whose read returns JSON."""
+    body = json.dumps(payload).encode("utf-8")
+    resp = MagicMock()
+    resp.read.return_value = body
+    cm = MagicMock()
+    cm.__enter__.return_value = resp
+    cm.__exit__.return_value = False
+    return cm
--- a/tests/integrations/test_integration_agy.py
+++ b/tests/integrations/test_integration_agy.py
@@ -131,5 +131,5 @@ class TestAgyHookCommandNote:
        )
        result = AgyIntegration._inject_hook_command_note(content)
        lines = result.splitlines()
-        note_line = [l for l in lines if "replace dots" in l][0]
+        note_line = [ln for ln in lines if "replace dots" in ln][0]
        assert note_line.startswith("   "), "Note should preserve indentation"
--- a/tests/integrations/test_integration_base_markdown.py
+++ b/tests/integrations/test_integration_base_markdown.py
@@ -269,10 +269,10 @@ class MarkdownIntegrationTests:
            files.append(f"{cmd_dir}/speckit.{stem}.md")

        # Framework files
-        files.append(f".specify/integration.json")
-        files.append(f".specify/init-options.json")
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
        files.append(f".specify/integrations/{self.KEY}.manifest.json")
-        files.append(f".specify/integrations/speckit.manifest.json")
+        files.append(".specify/integrations/speckit.manifest.json")

        if script_variant == "sh":
            for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
--- a/tests/integrations/test_integration_base_yaml.py
+++ b/tests/integrations/test_integration_base_yaml.py
@@ -152,7 +152,7 @@ class YamlIntegrationTests:
            content = f.read_text(encoding="utf-8")
            # Strip trailing source comment before parsing
            lines = content.split("\n")
-            yaml_lines = [l for l in lines if not l.startswith("# Source:")]
+            yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
            try:
                parsed = yaml.safe_load("\n".join(yaml_lines))
            except Exception as exc:
@@ -183,7 +183,7 @@ class YamlIntegrationTests:
        content = cmd_files[0].read_text(encoding="utf-8")
        # Strip source comment for parsing
        lines = content.split("\n")
-        yaml_lines = [l for l in lines if not l.startswith("# Source:")]
+        yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
        parsed = yaml.safe_load("\n".join(yaml_lines))

        assert "description:" not in parsed["prompt"]
--- a/tests/integrations/test_integration_generic.py
+++ b/tests/integrations/test_integration_generic.py
@@ -185,6 +185,20 @@ class TestGenericIntegration:
        )
        assert "__CONTEXT_FILE__" not in content

+    def test_plan_defines_quickstart_as_validation_guide(self, tmp_path):
+        """The generated plan command should keep quickstart.md out of implementation scope."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        plan_file = tmp_path / ".custom" / "cmds" / "speckit.plan.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+
+        assert "Create quickstart validation guide" in content
+        assert "runnable validation scenarios" in content
+        assert "Do not include full implementation code" in content
+        assert "implementation details belong in `tasks.md` and the implementation phase" in content
+
    def test_implement_loads_constitution_context(self, tmp_path):
        """The generated implement command should load constitution governance context."""
        i = get_integration("generic")
--- a/tests/integrations/test_integration_subcommand.py
+++ b/tests/integrations/test_integration_subcommand.py
@@ -3,7 +3,6 @@
 import json
 import os

-import pytest
 from typer.testing import CliRunner

 from specify_cli import app
--- a/tests/self_upgrade_helpers.py
+++ b/tests/self_upgrade_helpers.py
@@ -0,0 +1,64 @@
+"""Shared fixtures and helpers for `specify self upgrade` tests.
+
+These helpers patch subprocess, PATH lookup, and release-tag resolution so
+the focused test modules stay isolated from the real environment.
+"""
+
+import os
+import subprocess
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli._version import (
+    _InstallMethod,
+    _UpgradePlan,
+    _assemble_installer_argv,
+    _detect_install_method,
+    _verify_upgrade,
+)
+from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response
+
+__all__ = (
+    "SENTINEL_GH_TOKEN",
+    "SENTINEL_GITHUB_TOKEN",
+    "_InstallMethod",
+    "_UpgradePlan",
+    "_assemble_installer_argv",
+    "_completed_process",
+    "_detect_install_method",
+    "_verify_upgrade",
+    "mock_urlopen_response",
+    "requires_posix",
+    "runner",
+    "strip_ansi",
+)
+
+runner = CliRunner()
+
+# Some installer error-path tests create a relative `./uv` fixture, `chdir`
+# into the tmp dir, and assert POSIX executable-bit semantics (chmod / X_OK).
+# None of that maps cleanly onto Windows: `os.access(path, X_OK)` ignores the
+# mode bits, and pytest cannot rmtree a tmp dir that is still the cwd, so the
+# fixtures raise PermissionError during teardown. Skip these on Windows — the
+# realistic absolute-path and bare-PATH-command branches stay covered there.
+requires_posix = pytest.mark.skipif(
+    os.name == "nt",
+    reason="relative-path / executable-bit semantics are POSIX-only",
+)
+
+SENTINEL_GH_TOKEN = "SENTINEL-GH-TOKEN-VALUE"
+SENTINEL_GITHUB_TOKEN = "SENTINEL-GITHUB-TOKEN-VALUE"
+
+
+def _completed_process(
+    returncode: int, stdout: str = "", stderr: str = ""
+) -> subprocess.CompletedProcess:
+    """Build a subprocess.CompletedProcess for installer / verification calls."""
+    return subprocess.CompletedProcess(
+        args=["mocked"],
+        returncode=returncode,
+        stdout=stdout,
+        stderr=stderr,
+    )
--- a/tests/test_authentication.py
+++ b/tests/test_authentication.py
@@ -573,7 +573,9 @@ class TestAuthenticatedHttp:
        mock_opener = MagicMock()
        def fake_open(req, timeout=None):
            captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
            return resp
        mock_opener.open.side_effect = fake_open
        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
@@ -588,7 +590,9 @@ class TestAuthenticatedHttp:
        captured = {}
        def fake_urlopen(req, timeout=None):
            captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
            return resp
        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_urlopen):
            open_url("https://example.com/file.json")
@@ -601,7 +605,9 @@ class TestAuthenticatedHttp:
        captured = {}
        def fake_urlopen(req, timeout=None):
            captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
            return resp
        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_urlopen):
            open_url("https://github.com/org/repo")
@@ -615,12 +621,16 @@ class TestAuthenticatedHttp:
        self._set_config(monkeypatch, [_github_entry()])
        call_count = 0
        def fake_side_effect(req, timeout=None):
-            nonlocal call_count; call_count += 1
+            nonlocal call_count
+            call_count += 1
            if call_count == 1:
                raise urllib.error.HTTPError("url", 401, "Unauthorized", {}, None)
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
            return resp
-        mock_opener = MagicMock(); mock_opener.open.side_effect = fake_side_effect
+        mock_opener = MagicMock()
+        mock_opener.open.side_effect = fake_side_effect
        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener), \
             patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_side_effect):
            open_url("https://github.com/org/repo")
@@ -692,7 +702,6 @@ class TestLoadConfigCaching:
        """_load_config() should call load_auth_config only once per process."""
        from unittest.mock import patch
        from specify_cli.authentication import http as _mod
-        from specify_cli.authentication.config import AuthConfigEntry
        # Allow the real load path (no override)
        monkeypatch.setattr(_mod, "_config_override", None)
        monkeypatch.setattr(_mod, "_config_cache", None)
@@ -825,8 +834,11 @@ class TestFetchLatestReleaseTagDelegation:
        def side_effect(req, timeout=None):
            captured["request"] = req
            body = _json.dumps({"tag_name": "v9.9.9"}).encode()
-            resp = MagicMock(); resp.read.return_value = body
-            cm = MagicMock(); cm.__enter__.return_value = resp; cm.__exit__.return_value = False
+            resp = MagicMock()
+            resp.read.return_value = body
+            cm = MagicMock()
+            cm.__enter__.return_value = resp
+            cm.__exit__.return_value = False
            return cm
        return captured, side_effect

@@ -836,7 +848,8 @@ class TestFetchLatestReleaseTagDelegation:
        monkeypatch.setenv("GH_TOKEN", "forwarded-sentinel")
        self._set_config(monkeypatch, [_github_entry()])
        captured, side_effect = self._capture_request()
-        mock_opener = MagicMock(); mock_opener.open.side_effect = side_effect
+        mock_opener = MagicMock()
+        mock_opener.open.side_effect = side_effect
        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
            _fetch_latest_release_tag()
        assert captured["request"].get_header("Authorization") == "Bearer forwarded-sentinel"
--- a/tests/test_commands_package.py
+++ b/tests/test_commands_package.py
@@ -29,7 +29,7 @@ def test_agent_config_importable():


 def test_agent_config_re_exported_from_init():
-    from specify_cli import AGENT_CONFIG, AI_ASSISTANT_ALIASES, AI_ASSISTANT_HELP, SCRIPT_TYPE_CHOICES
+    from specify_cli import AGENT_CONFIG, SCRIPT_TYPE_CHOICES
    assert isinstance(AGENT_CONFIG, dict)
    assert "sh" in SCRIPT_TYPE_CHOICES

--- a/tests/test_console_imports.py
+++ b/tests/test_console_imports.py
@@ -2,12 +2,7 @@
 from specify_cli import (
    console,
    StepTracker,
-    get_key,
    select_with_arrows,
-    BannerGroup,
-    show_banner,
-    BANNER,
-    TAGLINE,
 )


--- a/tests/test_extension_skills.py
+++ b/tests/test_extension_skills.py
@@ -21,7 +21,6 @@ from pathlib import Path
 from specify_cli.extensions import (
    ExtensionManifest,
    ExtensionManager,
-    ExtensionError,
 )


@@ -241,7 +240,7 @@ class TestExtensionSkillRegistration:
        """Skills should be created when ai_skills is enabled."""
        project_dir, skills_dir = skills_project
        manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
            extension_dir, "0.1.0", register_commands=False
        )

@@ -784,7 +783,7 @@ class TestExtensionSkillEdgeCases:
        )

        manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
            ext_dir, "0.1.0", register_commands=False
        )

@@ -803,7 +802,7 @@ class TestExtensionSkillEdgeCases:
        ext_dir = _create_extension_dir(temp_dir, ext_id="test-ext")

        manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
            ext_dir, "0.1.0", register_commands=False
        )

@@ -819,10 +818,10 @@ class TestExtensionSkillEdgeCases:
        ext_dir_b = _create_extension_dir(temp_dir, ext_id="ext-b")

        manager = ExtensionManager(project_dir)
-        manifest_a = manager.install_from_directory(
+        manager.install_from_directory(
            ext_dir_a, "0.1.0", register_commands=False
        )
-        manifest_b = manager.install_from_directory(
+        manager.install_from_directory(
            ext_dir_b, "0.1.0", register_commands=False
        )

@@ -880,7 +879,7 @@ class TestExtensionSkillEdgeCases:

        manager = ExtensionManager(project_dir)
        # Should not raise
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
            ext_dir, "0.1.0", register_commands=False
        )

--- a/tests/test_self_upgrade_detection.py
+++ b/tests/test_self_upgrade_detection.py
@@ -0,0 +1,887 @@
+"""Detection, argv assembly, and dry-run tests for `specify self upgrade`."""
+
+import importlib.metadata
+import json
+import os
+import subprocess
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    _InstallMethod,
+    _assemble_installer_argv,
+    _completed_process,
+    _detect_install_method,
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+
+class TestDetectionUvTool:
+    """Tier-1 path-prefix detection for uv-tool installs."""
+
+    def test_posix_uv_tool_prefix_matches(self, uv_tool_argv0):
+        method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 1
+        assert "uv/tools/specify-cli" in signals.matched_prefix.replace("\\", "/")
+
+    def test_detection_is_deterministic(self, uv_tool_argv0):
+        a = _detect_install_method()
+        b = _detect_install_method()
+        assert a == b == _InstallMethod.UV_TOOL
+
+    def test_no_argv_match_falls_through_to_unsupported(self, unsupported_argv0):
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version._editable_marker_seen", return_value=False
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_include_signals_false_returns_bare_enum(self, uv_tool_argv0):
+        result = _detect_install_method(include_signals=False)
+        assert isinstance(result, _InstallMethod)
+
+    def test_bare_argv0_is_resolved_via_path_lookup(self, monkeypatch, tmp_path):
+        if os.name == "nt":
+            monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+            fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+        else:
+            monkeypatch.setenv("HOME", str(tmp_path))
+            fake_dir = (
+                tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+            )
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", ["specify"])
+        with patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: str(fake_specify) if name == "specify" else None,
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UV_TOOL
+
+    def test_prefix_match_does_not_accept_sibling_directory(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        fake_dir = tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli2" / "bin"
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", [str(fake_specify)])
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version._editable_marker_seen", return_value=False
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_when_registry_lists_exact_name(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\nother-tool v1.2.3\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 3
+        assert "uv tool list" in signals.installer_registries_consulted
+
+    def test_unresolved_bare_argv0_skips_tier3_registry_detection(self, monkeypatch):
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            return subprocess.CompletedProcess(
+                args=argv,
+                returncode=0,
+                stdout="specify-cli v0.7.6\n",
+                stderr="",
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.installer_registries_consulted == ()
+
+    def test_bare_argv0_missing_path_resolution_allows_tier3_registry_detection(
+        self, monkeypatch, tmp_path
+    ):
+        missing_specify = tmp_path / "missing" / "specify"
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            if name == "specify":
+                return str(missing_specify)
+            if name == "uv":
+                return "uv"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 3
+        assert "uv tool list" in signals.installer_registries_consulted
+
+    def test_missing_relative_argv0_falls_back_to_entrypoint_name_lookup(
+        self, monkeypatch, tmp_path
+    ):
+        if os.name == "nt":
+            monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+            fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+        else:
+            monkeypatch.setenv("HOME", str(tmp_path))
+            fake_dir = (
+                tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+            )
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", ["./bin/specify"])
+
+        def fake_which(name):
+            return str(fake_specify) if name == "specify" else None
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which):
+            method = _detect_install_method()
+
+        assert method == _InstallMethod.UV_TOOL
+
+    def test_tier3_uv_tool_ignores_substring_false_positive(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="my-specify-cli-helper v0.1.0\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_does_not_override_absolute_unsupported_entrypoint(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_does_not_override_resolved_bare_unsupported_entrypoint(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        venv_bin = tmp_path / "venv" / "bin"
+        venv_bin.mkdir(parents=True)
+        fake_specify = venv_bin / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        fake_specify.chmod(0o755)
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            if name == "specify":
+                return str(fake_specify)
+            if name == "uv":
+                return "uv"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.matched_tier is None
+        assert signals.installer_registries_consulted == ()
+
+
+class TestPrefixExpansion:
+    """Path-prefix expansion edge cases."""
+
+    def test_literal_dollar_without_variable_name_is_preserved(self, tmp_path):
+        prefix_path = tmp_path / "specify-$-cache" / "tools" / "specify-cli"
+        prefix = str(prefix_path)
+
+        expanded = specify_cli._version._expand_prefix(prefix)
+
+        assert expanded == prefix_path.resolve()
+
+    def test_unresolved_posix_variable_is_rejected(self):
+        assert specify_cli._version._expand_prefix("$SPECIFY_MISSING/specify-cli/") is None
+
+    def test_absolute_prefix_resolve_oserror_is_rejected(self, tmp_path):
+        prefix = str(tmp_path / "specify-cli")
+
+        with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            assert specify_cli._version._expand_prefix(prefix) is None
+
+
+class TestArgv0Resolution:
+    """Entrypoint path resolution edge cases."""
+
+    def test_absolute_argv0_resolve_oserror_returns_original_path(self, tmp_path):
+        argv0 = tmp_path / "specify"
+
+        with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            assert specify_cli._version._resolved_argv0_path(str(argv0)) == argv0
+
+    def test_path_lookup_resolve_oserror_returns_unresolved_lookup_path(self):
+        with patch(
+            "specify_cli._version.shutil.which", return_value="/broken/specify"
+        ), patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            result = specify_cli._version._resolved_argv0_path("specify")
+
+        # Compare as Path objects: on Windows the same logical path renders
+        # with backslashes, so a raw string compare against the POSIX form
+        # would spuriously fail.
+        assert result == Path("/broken/specify")
+
+
+class TestArgvAssemblyUvTool:
+    """uv-tool installer argv shape."""
+
+    def test_stable_tag_produces_expected_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value="uv"):
+            argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6")
+        assert argv == [
+            "uv",
+            "tool",
+            "install",
+            "specify-cli",
+            "--force",
+            "--from",
+            "git+https://github.com/github/spec-kit.git@v0.7.6",
+        ]
+
+    def test_dev_suffix_tag_embedded_literally(self):
+        with patch("specify_cli._version.shutil.which", return_value="uv"):
+            argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.8.0.dev0")
+        assert "git+https://github.com/github/spec-kit.git@v0.8.0.dev0" in argv
+        assert (
+            "upgrade" not in argv
+        )  # never `uv tool upgrade` — does not accept --tag pinning
+
+    def test_missing_uv_returns_no_installer_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value=None):
+            assert _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6") is None
+
+
+class TestBareUpgradeUvTool:
+    """uv-tool happy path, bare invocation."""
+
+    def test_happy_path_end_to_end(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),  # installer
+                _completed_process(0, stdout="specify 0.7.6\n"),  # verify
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Upgrading specify-cli 0.7.5 → v0.7.6 via uv tool:" in out
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in out
+        assert mock_run.call_count == 2
+        for call in mock_run.call_args_list:
+            assert call.kwargs.get("shell", False) is False
+
+    def test_one_user_action_no_prompt(self, uv_tool_argv0, clean_environ):
+        # The single `invoke` represents the single user action — no prompt.
+        # If a prompt existed, runner.invoke would hang waiting for input.
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+
+
+class TestAlreadyLatestUvTool:
+    """already on latest, no installer launched."""
+
+    def test_already_latest_exits_zero_no_subprocess(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.6"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Already on latest release: v0.7.6" in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_trailing_zero_equivalent_version_reports_latest_not_newer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # Version("1.0") == Version("1.0.0") under packaging even though their
+        # canonical strings differ. The no-op message must use Version equality
+        # so this prints "Already on latest release", not "... or newer".
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="1.0"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release: v1.0.0" in out
+        assert "or newer" not in out
+        assert mock_run.call_count == 0
+
+    def test_dev_build_ahead_of_release_reports_newer_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.7.dev0"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Already on latest release or newer: 0.7.7.dev0" in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_unparseable_current_version_does_not_false_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release" not in out
+        assert "Upgrading specify-cli release-main → v0.7.6 via uv tool:" in out
+        assert mock_run.call_count == 2
+
+    def test_unparseable_resolved_target_fails_before_literal_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 1
+        out = strip_ansi(result.output)
+        assert "not a comparable version" in out
+        assert "release-main" not in out
+        assert "Already on latest release" not in out
+        assert mock_run.call_count == 0
+
+    def test_pinned_older_tag_still_runs_installer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.6"
+        ):
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.5\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v0.7.5"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release" not in out
+        # A pinned older tag is a downgrade and must be labelled as such.
+        assert "Downgrading specify-cli 0.7.6 → v0.7.5 via uv tool:" in out
+        assert "Upgrading specify-cli" not in out
+        assert mock_run.call_count == 2
+
+    def test_pinned_rc_tag_uses_canonical_version_equality_for_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0rc1"
+        ):
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+        assert result.exit_code == 0
+        assert "Already on requested release: v1.0.0-rc1" in strip_ansi(result.output)
+
+
+class TestDryRunUvTool:
+    """--dry-run preview path + --dry-run combined with --tag."""
+
+    def test_dry_run_without_tag_resolves_network_but_no_subprocess(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Dry run — no changes will be made." in out
+        assert "Detected install method: uv tool" in out
+        assert "Current version: 0.7.5" in out
+        assert "Target version: v0.7.6" in out
+        assert "Command that would be executed:" in out
+        assert mock_run.call_count == 0
+
+    def test_dry_run_with_tag_skips_network(self, uv_tool_argv0, clean_environ):
+        # --dry-run with --tag must NOT hit the network.
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ), patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0" in strip_ansi(result.output)
+        mock_urlopen.assert_not_called()
+
+    def test_dry_run_rejects_unparseable_network_tag_before_preview(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response(
+                {"tag_name": "v0.9.0;echo unsafe"}
+            )
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 1
+        assert "not a comparable version" in out
+        assert "v0.9.0;echo unsafe" not in out
+        assert "Command that would be executed:" not in out
+        assert mock_run.call_count == 0
+
+    def test_dry_run_with_missing_uv_flags_unresolved_installer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Command that would be executed: (installer uv not found on PATH)" in out
+        assert "uv tool install" not in out
+        assert mock_run.call_count == 0
+
+
+# ===========================================================================
+# Phase 4 — User Story 2: `pipx` immediate upgrade (P2)
+# ===========================================================================
+
+
+class TestDetectionPipx:
+    """Pipx detection — tier 1 (path) and tier 3 (registry)."""
+
+    def test_posix_pipx_prefix_matches(self, pipx_argv0):
+        method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.PIPX
+        assert signals.matched_tier == 1
+
+    def test_tier3_pipx_when_no_prefix_match_but_registry_lists_it(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.PIPX
+        assert signals.matched_tier == 3
+        assert "pipx list --json" in signals.installer_registries_consulted
+
+    def test_tier3_pipx_does_not_override_absolute_unsupported_entrypoint(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_pipx_ignores_malformed_json_output(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="not json but mentions specify-cli",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_both_uv_tool_and_pipx_match_is_treated_as_unsupported(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            if name == "uv":
+                return "uv"
+            if name == "pipx":
+                return "pipx"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.matched_tier is None
+        assert "uv tool list" in signals.installer_registries_consulted
+        assert "pipx list --json" in signals.installer_registries_consulted
+
+
+class TestEditableInstallMetadata:
+    @pytest.mark.skipif(
+        not hasattr(importlib.metadata, "InvalidMetadataError"),
+        reason=(
+            "importlib.metadata.InvalidMetadataError does not exist on this "
+            "Python; _editable_direct_url_path only catches it when present, so "
+            "fabricating it would exercise a path that cannot fire in production"
+        ),
+    )
+    def test_editable_marker_false_when_metadata_is_invalid(self):
+        invalid_metadata_error = importlib.metadata.InvalidMetadataError
+
+        with patch(
+            "importlib.metadata.distribution",
+            side_effect=invalid_metadata_error("bad metadata"),
+        ):
+            assert specify_cli._version._editable_marker_seen() is False
+            assert specify_cli._version._source_checkout_path() is None
+
+    def test_direct_url_editable_install_marks_source_checkout(self, tmp_path):
+        project_root = tmp_path / "spec-kit"
+        project_root.mkdir()
+        (project_root / ".git").mkdir()
+
+        class FakeDist:
+            files = []
+
+            def read_text(self, name):
+                if name == "direct_url.json":
+                    return json.dumps(
+                        {
+                            "dir_info": {"editable": True},
+                            "url": project_root.as_uri(),
+                        }
+                    )
+                return None
+
+            def locate_file(self, file):
+                return file
+
+        with patch("importlib.metadata.distribution", return_value=FakeDist()):
+            assert specify_cli._version._editable_marker_seen() is True
+            assert specify_cli._version._source_checkout_path() == project_root.resolve()
+
+    def test_editable_marker_false_without_explicit_editable_metadata(self, tmp_path):
+        repo_root = tmp_path / "repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        venv_file = repo_root / ".venv" / "lib" / "python3.13" / "site-packages" / "specify_cli.py"
+        venv_file.parent.mkdir(parents=True)
+        venv_file.write_text("# installed module\n")
+
+        class FakeDist:
+            files = ["specify_cli.py"]
+
+            def read_text(self, name):
+                return None
+
+            def locate_file(self, file):
+                return venv_file
+
+        with patch("importlib.metadata.distribution", return_value=FakeDist()):
+            assert specify_cli._version._editable_marker_seen() is False
+
+
+class TestTagValidationWhitespace:
+    def test_tag_whitespace_is_trimmed_before_validation(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.8.0\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", " v0.8.0 "])
+
+        assert result.exit_code == 0
+        assert "v0.8.0" in strip_ansi(result.output)
+
+
+class TestArgvAssemblyPipx:
+    """pipx installer argv shape — pipx 1.5+ uses positional PACKAGE_SPEC, never `--spec` or `upgrade`."""
+
+    def test_pipx_argv_uses_install_force_positional_not_upgrade(self):
+        with patch("specify_cli._version.shutil.which", return_value="pipx"):
+            argv = _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6")
+        assert argv == [
+            "pipx",
+            "install",
+            "--force",
+            "git+https://github.com/github/spec-kit.git@v0.7.6",
+        ]
+        assert "upgrade" not in argv  # pipx upgrade does not accept arbitrary refs
+        assert "--spec" not in argv  # pipx 1.5+ dropped the --spec flag
+
+    def test_missing_pipx_returns_no_installer_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value=None):
+            assert _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6") is None
+
+
+class TestBareUpgradePipx:
+    """pipx happy path."""
+
+    def test_happy_path(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "via pipx:" in out
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in out
+
+
+class TestDetectionShortCircuit:
+    """Tier-1 path-prefix matches short-circuit before registry checks."""
+
+    def test_pipx_argv0_prefix_short_circuits_before_registry_checks(
+        self,
+        pipx_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="/usr/bin/X"), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            method = _detect_install_method()
+        assert method == _InstallMethod.PIPX
+        mock_run.assert_not_called()
+
+
+class TestDryRunPipx:
+    def test_dry_run_preview_names_pipx(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        assert "Detected install method: pipx" in strip_ansi(result.output)
+        assert mock_run.call_count == 0
--- a/tests/test_self_upgrade_execution.py
+++ b/tests/test_self_upgrade_execution.py
@@ -0,0 +1,542 @@
+"""Installer execution, verification, and error-path tests for `specify self upgrade`."""
+
+import errno
+import subprocess
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    _completed_process,
+    mock_urlopen_response,
+    requires_posix,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 — User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestInstallerMissing:
+    """Installer disappeared between detection and run → exit 3."""
+
+    def test_uv_missing_exits_3(self, uv_tool_argv0, clean_environ):
+        which_results = {"specify": "/usr/local/bin/specify"}
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert "Installer uv not found on PATH; reinstall it and retry." in out
+        assert "Upgrading specify-cli" not in out
+
+    def test_pipx_missing_exits_3(self, pipx_argv0, clean_environ):
+        which_results = {}
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert "Installer pipx not found on PATH" in strip_ansi(result.output)
+
+    def test_absolute_installer_path_does_not_require_path_lookup(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._verify_upgrade", return_value="0.7.6"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(0)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+
+    @requires_posix
+    def test_relative_installer_path_does_not_require_path_lookup(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "uv"
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._verify_upgrade", return_value="0.7.6"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(0)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert mock_run.call_args.args[0][0] == "./uv"
+
+    @requires_posix
+    def test_relative_installer_path_missing_gets_path_specific_message(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        assert (
+            "Installer path ./uv no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+        assert "not found on PATH" not in strip_ansi(result.output)
+
+    def test_resolved_absolute_installer_removed_before_exec_gets_missing_path_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+
+        def fake_run(argv, *args, **kwargs):
+            fake_uv.unlink()
+            raise FileNotFoundError(str(fake_uv))
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: str(fake_uv) if name == "uv" else None,
+        ), patch("specify_cli._version.subprocess.run", side_effect=fake_run), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+
+    def test_absolute_installer_path_not_executable_gets_specific_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o644)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.os.access", return_value=False), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} is not an executable file; fix the path or reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+
+    @requires_posix
+    def test_relative_installer_path_not_executable_gets_path_specific_message(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "uv"
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o644)
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.os.access", return_value=False), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 3
+        assert (
+            "Installer path ./uv is not an executable file; fix the path or reinstall it and retry."
+            in out
+        )
+        assert "Installer ./uv is not executable" not in out
+
+    def test_real_installer_exit_126_is_not_treated_as_invalid_path(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(126)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 126
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 126." in out
+        assert "not an executable file" not in out
+
+    def test_absolute_installer_path_missing_gets_path_specific_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "missing-installer" / "uv"
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+        mock_run.assert_not_called()
+
+    def test_exec_oserror_is_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch(
+            "specify_cli._version.subprocess.run",
+            side_effect=PermissionError("Permission denied"),
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert f"Installer path {fake_uv} is not an executable file" in out
+        assert "not found on PATH" not in out
+
+    def test_bare_invalid_installer_message_does_not_call_it_a_path(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch(
+            "specify_cli._version.subprocess.run",
+            side_effect=PermissionError("Permission denied"),
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert "Installer uv is not executable" in out
+        assert "Installer path uv" not in out
+
+    def test_exec_oserror_errno_is_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        invalid_error = OSError(errno.ENOEXEC, "Exec format error")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch("specify_cli._version.subprocess.run", side_effect=invalid_error):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert f"Installer path {fake_uv} is not an executable file" in out
+        assert "not found on PATH" not in out
+
+    def test_transient_exec_oserror_is_not_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        transient_error = OSError(errno.EMFILE, "Too many open files")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch("specify_cli._version.subprocess.run", side_effect=transient_error):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        # Transient/unknown OSErrors are re-raised rather than mapped to the
+        # invalid-installer exit 3, so the CLI surfaces them as an uncaught
+        # error: exit code 1 with the original OSError preserved.
+        assert result.exit_code == 1
+        assert isinstance(result.exception, OSError)
+
+
+class TestInstallerFailed:
+    """Installer non-zero exit → propagate code, print rollback hint."""
+
+    def test_installer_exit_2_propagates(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]  # installer fails
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 2." in out
+        assert "Try again or run the command manually:" in out
+        assert "git+https://github.com/github/spec-kit.git@v0.7.6" in out
+        assert (
+            "To pin back to the previous version: "
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+        # No verification attempted after a failed installer run.
+        assert mock_run.call_count == 1
+
+    def test_installer_exit_127_propagates(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(127)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 127
+
+    def test_installer_timeout_prints_timeout_specific_message(
+        self, uv_tool_argv0, clean_environ, monkeypatch
+    ):
+        monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "12")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                subprocess.TimeoutExpired(cmd=["uv"], timeout=12)
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 124
+        out = strip_ansi(result.output)
+        assert "Upgrade timed out while waiting for the installer subprocess." in out
+        assert "SPECIFY_UPGRADE_TIMEOUT_SECS=12" in out
+
+    def test_non_finite_timeout_warns_and_runs_without_timeout(
+        self, uv_tool_argv0, clean_environ, monkeypatch
+    ):
+        monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "nan")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Ignoring invalid SPECIFY_UPGRADE_TIMEOUT_SECS='nan'" in strip_ansi(
+            result.output
+        )
+        assert mock_run.call_args_list[0].kwargs["timeout"] is None
+
+    def test_real_installer_exit_124_is_not_treated_as_timeout(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(124)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 124
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 124." in out
+        assert "Upgrade timed out while waiting for the installer subprocess." not in out
+
+    def test_pipx_failure_prints_pipx_rollback_hint(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert (
+            "To pin back to the previous version: pipx install --force "
+            "git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+
+    def test_rollback_hint_accepts_normalizable_stable_snapshot(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="v0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert (
+            "To pin back to the previous version: uv tool install specify-cli --force "
+            "--from git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+        assert "Previous version was not an exact stable release tag" not in out
+
+    def test_prerelease_failure_degrades_rollback_hint_to_releases_page(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0rc1"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Previous version was not an exact stable release tag" in out
+        assert "https://github.com/github/spec-kit/releases" in out
+        assert "git+https://github.com/github/spec-kit.git@v1.0.0rc1" not in out
--- a/tests/test_self_upgrade_guidance.py
+++ b/tests/test_self_upgrade_guidance.py
@@ -0,0 +1,184 @@
+"""Non-upgradable path guidance tests for `specify self upgrade`."""
+
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 5 — User Story 3: non-upgradable path guidance (P3)
+# ===========================================================================
+
+
+class TestUvxEphemeral:
+    """uvx ephemeral path emits exact one-liner, no installer call."""
+
+    def test_uvx_argv0_prints_exact_one_liner_and_exits_zero(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+        expected = (
+            "Running via uvx (ephemeral); the next uvx invocation already "
+            "resolves to latest — no upgrade action needed."
+        )
+        assert expected in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_offline_still_exits_zero_without_tag_resolution(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=AssertionError("non-upgradable uvx path must not hit network"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+        assert "uvx (ephemeral)" in strip_ansi(result.output)
+
+
+class TestSourceCheckout:
+    """Editable install path emits git pull guidance."""
+
+    def test_source_checkout_prints_git_pull_guidance(
+        self,
+        unsupported_argv0,
+        tmp_path,
+        clean_environ,
+    ):
+        fake_tree = tmp_path / "worktree"
+        fake_tree.mkdir()
+        (fake_tree / ".git").mkdir()
+
+        with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+            "specify_cli._version._source_checkout_path", return_value=fake_tree
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert f"Running from a source checkout at {fake_tree}" in out
+        assert "git pull" in out
+        assert "pip install -e ." in out
+        assert mock_run.call_count == 0
+
+    def test_source_checkout_without_path_mentions_checkout_directory(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+            "specify_cli._version._source_checkout_path", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "checkout path could not be detected" in out
+        assert "from your checkout directory" in out
+        assert "(path unavailable)" not in out
+        assert mock_run.call_count == 0
+
+
+class TestUnsupported:
+    """Unsupported path enumerates manual reinstall commands."""
+
+    def test_unsupported_prints_both_reinstall_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Could not identify your install method automatically" in out
+        assert (
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@vX.Y.Z"
+        ) in out
+        assert (
+            "pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z"
+            in out
+        )
+        assert mock_run.call_count == 0
+
+    def test_unsupported_offline_degrades_to_placeholder_manual_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=AssertionError("unsupported guidance should not require network"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Could not identify your install method automatically" in out
+        assert (
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@vX.Y.Z"
+        ) in out
+        assert (
+            "pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z"
+            in out
+        )
+
+
+class TestDryRunNonUpgradablePaths:
+    """--dry-run on non-upgradable paths emits guidance, not preview."""
+
+    def test_dry_run_on_uvx_ephemeral_emits_guidance_not_preview(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Dry run — no changes will be made." not in out
+        assert "uvx (ephemeral)" in out
+
+    def test_dry_run_on_unsupported_emits_manual_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        assert "Could not identify your install method" in strip_ansi(result.output)
--- a/tests/test_self_upgrade_verification.py
+++ b/tests/test_self_upgrade_verification.py
@@ -0,0 +1,649 @@
+"""Verification, resolution, and validation tests for `specify self upgrade`."""
+
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    SENTINEL_GH_TOKEN,
+    SENTINEL_GITHUB_TOKEN,
+    _InstallMethod,
+    _UpgradePlan,
+    _completed_process,
+    _verify_upgrade,
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 — User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestVerificationMismatch:
+    """Installer says 0 but the binary is still the old version → exit 2."""
+
+    def test_installer_ok_but_verify_returns_old_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),  # installer OK
+                _completed_process(0, stdout="specify 0.7.5\n"),  # verify: OLD!
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "resolves to 0.7.5 (expected v0.7.6)" in out
+        assert "The new version may take effect on your next invocation." in out
+
+    def test_verify_nonzero_exit_is_not_treated_as_success(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(1, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "(unknown) (expected v0.7.6)" in out
+
+    def test_verify_accepts_pep440_equivalent_rc_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.9.0"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 1.0.0rc1\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.9.0 → 1.0.0rc1" in strip_ansi(result.output)
+
+    def test_verify_accepts_specify_cli_binary_name_in_version_output(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify-cli version 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in strip_ansi(result.output)
+
+    def test_verify_accepts_capitalized_binary_name_in_version_output(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="Specify, version 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in strip_ansi(result.output)
+
+    def test_verify_rejects_output_without_parseable_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify version unknown\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "(unknown) (expected v0.7.6)" in out
+
+    def test_verify_uses_current_entrypoint_when_not_on_path(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        assert uv_tool_argv0.exists()
+        assert uv_tool_argv0.is_file()
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == str(uv_tool_argv0)
+        assert mock_run.call_args.kwargs["timeout"] == specify_cli._version._VERIFY_TIMEOUT_SECS
+
+    def test_verify_falls_back_to_path_when_current_entrypoint_is_not_executable(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None,
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version.os.access", return_value=False
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+    def test_verify_ignores_python_entrypoint_and_falls_back_to_specify(
+        self,
+        clean_environ,
+        tmp_path,
+    ):
+        fake_python = tmp_path / "python3"
+        fake_python.write_text("#!/bin/sh\n")
+        fake_python.chmod(0o755)
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version.sys.argv", [str(fake_python)]
+        ), patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+    def test_verify_accepts_specify_cli_named_current_entrypoint(
+        self,
+        clean_environ,
+        tmp_path,
+    ):
+        fake_specify_cli = tmp_path / "specify-cli"
+        fake_specify_cli.write_text("#!/bin/sh\n")
+        fake_specify_cli.chmod(0o755)
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch("specify_cli._version.sys.argv", [str(fake_specify_cli)]), patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == str(fake_specify_cli)
+
+
+class TestResolutionFailures:
+    """Pre-installer resolution failure → exit 1, reusing the resolver category strings."""
+
+    def test_offline_exits_1_with_phase1_string(self, uv_tool_argv0, clean_environ):
+        with patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=urllib.error.URLError("nope"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert "Upgrade aborted: offline or timeout" in strip_ansi(result.output)
+
+    def test_rate_limited_exits_1(self, uv_tool_argv0, clean_environ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=403,
+            msg="rate limited",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert (
+            "Upgrade aborted: rate limited (configure ~/.specify/auth.json with a GitHub token)"
+            in strip_ansi(result.output)
+        )
+
+    def test_http_500_exits_1(self, uv_tool_argv0, clean_environ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=500,
+            msg="srv err",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert "Upgrade aborted: HTTP 500" in strip_ansi(result.output)
+
+    @pytest.mark.parametrize(
+        "code, expected",
+        [
+            # 429 (Too Many Requests / secondary rate limit) gets the same
+            # actionable token hint as 403; other statuses surface verbatim.
+            (
+                429,
+                "Upgrade aborted: rate limited (configure ~/.specify/auth.json "
+                "with a GitHub token)",
+            ),
+            (404, "Upgrade aborted: HTTP 404"),
+            (502, "Upgrade aborted: HTTP 502"),
+        ],
+    )
+    def test_http_error_categorization(
+        self, code, expected, uv_tool_argv0, clean_environ
+    ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=code,
+            msg="err",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert expected in strip_ansi(result.output)
+
+    def test_unparseable_resolved_release_tag_exits_1_without_traceback(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 1
+        out = strip_ansi(result.output)
+        assert "resolved release tag is not a comparable version" in out
+        assert "release-main" not in out
+        assert "Traceback" not in out
+        assert mock_run.call_count == 0
+
+
+class TestTagValidation:
+    """--tag regex enforcement."""
+
+    def test_valid_stable_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.7.6"],
+            )
+        assert result.exit_code == 0
+
+    def test_valid_dev_suffix_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0.dev0"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0.dev0" in strip_ansi(result.output)
+
+    def test_valid_rc_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1"],
+            )
+        assert result.exit_code == 0
+
+    def test_valid_beta_dot_tag_uses_pep440_equivalent_for_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0b1"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--tag", "v1.0.0-beta.1"],
+            )
+        assert result.exit_code == 0
+        assert "Already on requested release: v1.0.0-beta.1" in strip_ansi(
+            result.output
+        )
+
+    def test_valid_build_metadata_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0+build.42"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0+build.42" in strip_ansi(result.output)
+
+    def test_uppercase_v_prefix_is_folded_to_lowercase(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # A pasted uppercase `V` prefix is accepted and normalized to `v` so
+        # the git ref matches the canonical lowercase release tag.
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "V0.7.6"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.7.6" in strip_ansi(result.output)
+
+    def test_valid_prerelease_with_build_metadata_tag(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # Prerelease and build-metadata suffixes compose (PEP 440 / semver).
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1+build.42"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v1.0.0-rc1+build.42" in strip_ansi(result.output)
+
+    @pytest.mark.parametrize(
+        "bad_tag",
+        [
+            "latest",
+            "0.7.5",
+            "main",
+            "v7",
+            "",
+            "v1.2.3abc",
+            "v1.2.3...",
+            "v1.2.3++",
+            "v\uff11.2.3",
+            "v1.\u0662.3",
+        ],
+    )
+    def test_invalid_tags_rejected(self, bad_tag, uv_tool_argv0, clean_environ):
+        result = runner.invoke(app, ["self", "upgrade", "--tag", bad_tag])
+        assert result.exit_code == 1
+        output = strip_ansi(result.output)
+        assert "Invalid --tag" in output or "expected vMAJOR.MINOR.PATCH" in output
+
+
+class TestUnknownCurrent:
+    """'unknown' current version renders literally in notice and success message."""
+
+    def test_unknown_current_renders_literal_in_notice(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="unknown"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Upgrading specify-cli unknown → v0.7.6 via uv tool:" in out
+        assert "Upgraded specify-cli: unknown → 0.7.6" in out
+
+    def test_unknown_current_rollback_hint_degrades(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="unknown"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]  # installer fails
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Could not determine the previous version" in out
+        assert "https://github.com/github/spec-kit/releases" in out
+
+
+class TestTokenScrubbing:
+    """GH_TOKEN / GITHUB_TOKEN are stripped from every child env."""
+
+    def test_env_passed_to_subprocess_has_no_github_tokens(
+        self,
+        uv_tool_argv0,
+        monkeypatch,
+    ):
+        monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
+        monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
+        response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli.authentication.http.urllib.request.build_opener"
+        ) as mock_build_opener, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = response
+            mock_build_opener.return_value.open.return_value = response
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            runner.invoke(app, ["self", "upgrade"])
+
+        assert mock_run.call_count >= 1
+        for call in mock_run.call_args_list:
+            env_kwarg = call.kwargs.get("env") or {}
+            assert "GH_TOKEN" not in env_kwarg, f"env leaked GH_TOKEN: {env_kwarg!r}"
+            assert "GITHUB_TOKEN" not in env_kwarg
+            for v in env_kwarg.values():
+                assert SENTINEL_GH_TOKEN not in v
+                assert SENTINEL_GITHUB_TOKEN not in v
+
+    def test_env_scrubbing_is_case_insensitive(
+        self,
+        uv_tool_argv0,
+        monkeypatch,
+    ):
+        monkeypatch.setenv("gh_token", SENTINEL_GH_TOKEN)
+        monkeypatch.setenv("GitHub_Token", SENTINEL_GITHUB_TOKEN)
+        response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli.authentication.http.urllib.request.build_opener"
+        ) as mock_build_opener, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = response
+            mock_build_opener.return_value.open.return_value = response
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            runner.invoke(app, ["self", "upgrade"])
+
+        assert mock_run.call_count >= 1
+        for call in mock_run.call_args_list:
+            env_kwarg = call.kwargs.get("env") or {}
+            assert "gh_token" not in env_kwarg
+            assert "GitHub_Token" not in env_kwarg
+            for v in env_kwarg.values():
+                assert SENTINEL_GH_TOKEN not in v
+                assert SENTINEL_GITHUB_TOKEN not in v
+
+    def test_env_scrubbing_removes_github_token_variants(self, monkeypatch):
+        monkeypatch.setenv("GH_PAT", "gh-pat")
+        monkeypatch.setenv("GH_TOKEN_FILE", "gh-token-file")
+        monkeypatch.setenv("GH_ENTERPRISE_TOKEN", "enterprise-gh")
+        monkeypatch.setenv("GH_ENTERPRISE_SECRET", "enterprise-secret")
+        monkeypatch.setenv("GH_ENTERPRISE_PRIVATE_KEY", "enterprise-key")
+        monkeypatch.setenv("GITHUB_PAT", "github-pat")
+        monkeypatch.setenv("GITHUB_TOKEN_PATH", "github-token-path")
+        monkeypatch.setenv("GITHUB_ENTERPRISE_TOKEN", "enterprise-github")
+        monkeypatch.setenv("GITHUB_API_TOKEN", "api-token")
+        monkeypatch.setenv("GITHUB_APP_PRIVATE_KEY", "app-private-key")
+        monkeypatch.setenv("GITHUB_OAUTH_CLIENT_SECRET", "oauth-secret")
+        monkeypatch.setenv("HOMEBREW_GITHUB_API_TOKEN", "homebrew-token")
+        monkeypatch.setenv("NOTGITHUB_TOKEN", "not-github-kept")
+        monkeypatch.setenv("GHOST_API_TOKEN", "ghost-kept")
+        monkeypatch.setenv("GHIDRA_API_KEY", "ghidra-kept")
+        monkeypatch.setenv("UNRELATED_TOKEN", "kept")
+
+        env = specify_cli._version._scrubbed_env()
+
+        assert "GH_PAT" not in env
+        assert "GH_TOKEN_FILE" not in env
+        assert "GH_ENTERPRISE_TOKEN" not in env
+        assert "GH_ENTERPRISE_SECRET" not in env
+        assert "GH_ENTERPRISE_PRIVATE_KEY" not in env
+        assert "GITHUB_PAT" not in env
+        assert "GITHUB_TOKEN_PATH" not in env
+        assert "GITHUB_ENTERPRISE_TOKEN" not in env
+        assert "GITHUB_API_TOKEN" not in env
+        assert "GITHUB_APP_PRIVATE_KEY" not in env
+        assert "GITHUB_OAUTH_CLIENT_SECRET" not in env
+        assert "HOMEBREW_GITHUB_API_TOKEN" not in env
+        assert env["NOTGITHUB_TOKEN"] == "not-github-kept"
+        assert env["GHOST_API_TOKEN"] == "ghost-kept"
+        assert env["GHIDRA_API_KEY"] == "ghidra-kept"
+        assert env["UNRELATED_TOKEN"] == "kept"
+
+    def test_env_scrubbing_strips_noncredential_github_vars_by_design(
+        self, monkeypatch
+    ):
+        # The scrub is intentionally broad: every GH_/GITHUB_-prefixed name is
+        # removed from the installer subprocess env, including non-credential
+        # context vars. This is a deliberate fail-safe so credential-adjacent
+        # names that lack a recognized suffix (e.g. GH_TOKEN_FILE,
+        # GITHUB_TOKEN_PATH, asserted above) can never leak. The installer
+        # (`uv tool install` / `pipx install` of a public package) does not
+        # consume routing/context vars like GITHUB_REPOSITORY, so nothing the
+        # subprocess needs is lost by stripping them.
+        monkeypatch.setenv("GH_HOST", "github.example.com")
+        monkeypatch.setenv("GH_CONFIG_DIR", "/home/u/.config/gh")
+        monkeypatch.setenv("GITHUB_REPOSITORY", "github/spec-kit")
+        monkeypatch.setenv("GITHUB_WORKSPACE", "/home/runner/work")
+        monkeypatch.setenv("GITHUB_USER", "octocat")
+
+        env = specify_cli._version._scrubbed_env()
+
+        assert "GH_HOST" not in env
+        assert "GH_CONFIG_DIR" not in env
+        assert "GITHUB_REPOSITORY" not in env
+        assert "GITHUB_WORKSPACE" not in env
+        assert "GITHUB_USER" not in env
--- a/tests/test_setup_tasks.py
+++ b/tests/test_setup_tasks.py
@@ -13,8 +13,10 @@ from tests.conftest import requires_bash
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
 SETUP_TASKS_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-tasks.sh"
+CHECK_PREREQ_SH = PROJECT_ROOT / "scripts" / "bash" / "check-prerequisites.sh"
 COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
 SETUP_TASKS_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-tasks.ps1"
+CHECK_PREREQ_PS = PROJECT_ROOT / "scripts" / "powershell" / "check-prerequisites.ps1"
 TASKS_TEMPLATE = PROJECT_ROOT / "templates" / "tasks-template.md"
 
 HAS_PWSH = shutil.which("pwsh") is not None
@@ -30,6 +32,7 @@ def _install_bash_scripts(repo: Path) -> None:
    d.mkdir(parents=True, exist_ok=True)
    shutil.copy(COMMON_SH, d / "common.sh")
    shutil.copy(SETUP_TASKS_SH, d / "setup-tasks.sh")
+    shutil.copy(CHECK_PREREQ_SH, d / "check-prerequisites.sh")
 
 
 def _install_ps_scripts(repo: Path) -> None:
@@ -37,6 +40,7 @@ def _install_ps_scripts(repo: Path) -> None:
    d.mkdir(parents=True, exist_ok=True)
    shutil.copy(COMMON_PS, d / "common.ps1")
    shutil.copy(SETUP_TASKS_PS, d / "setup-tasks.ps1")
+    shutil.copy(CHECK_PREREQ_PS, d / "check-prerequisites.ps1")
 
 
 def _install_core_tasks_template(repo: Path) -> None:
@@ -57,6 +61,25 @@ def _minimal_feature(repo: Path) -> Path:
    (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
    (feat / "plan.md").write_text("# plan\n", encoding="utf-8")
    return feat
+
+
+def _write_integration_state(repo: Path, integration: str = "claude", separator: str = "-") -> None:
+    specify_dir = repo / ".specify"
+    specify_dir.mkdir(parents=True, exist_ok=True)
+    state = {
+        "integration": integration,
+        "default_integration": integration,
+        "installed_integrations": [integration],
+        "integration_settings": {
+            integration: {
+                "invoke_separator": separator,
+            },
+        },
+    }
+    (specify_dir / "integration.json").write_text(
+        json.dumps(state),
+        encoding="utf-8",
+    )
 
 
 def _clean_env() -> dict[str, str]:
@@ -71,6 +94,38 @@ def _clean_env() -> dict[str, str]:
    return env
 
 
+def _run_bash_format_command(repo: Path, command_name: str) -> subprocess.CompletedProcess:
+    script = repo / ".specify" / "scripts" / "bash" / "common.sh"
+    return subprocess.run(
+        ["bash", "-c", 'source "$1"; format_speckit_command "$2" "$PWD"', "bash", str(script), command_name],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+
+def _run_powershell_format_command(repo: Path, command_name: str) -> subprocess.CompletedProcess:
+    script = repo / ".specify" / "scripts" / "powershell" / "common.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    return subprocess.run(
+        [
+            exe,
+            "-NoProfile",
+            "-Command",
+            '& { param($common, $commandName) . $common; Format-SpecKitCommand -CommandName $commandName -RepoRoot (Get-Location).Path }',
+            str(script),
+            command_name,
+        ],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+
 def _git_init(repo: Path) -> None:
    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
    subprocess.run(
@@ -123,7 +178,7 @@ def test_setup_tasks_bash_core_template_resolved(tasks_repo: Path) -> None:
    setup-tasks.sh --json should exit 0 and return an absolute, existing
    TASKS_TEMPLATE path pointing to the core template.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
    script = tasks_repo / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
 
    result = subprocess.run(
@@ -150,7 +205,7 @@ def test_setup_tasks_bash_override_wins(tasks_repo: Path) -> None:
    When an override exists at .specify/templates/overrides/tasks-template.md,
    setup-tasks.sh --json must return the override path, not the core path.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    # Create the override
    overrides_dir = tasks_repo / ".specify" / "templates" / "overrides"
@@ -187,7 +242,7 @@ def test_setup_tasks_bash_extension_wins_over_core(tasks_repo: Path) -> None:
    When an extension template exists, setup-tasks.sh --json must resolve
    tasks-template.md from the extension before falling back to the core path.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    # FIX: real extension layout is .specify/extensions/<id>/templates/<name>.md
    extension_dir = (
@@ -225,7 +280,7 @@ def test_setup_tasks_bash_preset_wins_over_extension(tasks_repo: Path) -> None:
    When both preset and extension templates exist, setup-tasks.sh --json must
    resolve the preset path because presets outrank extensions.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    # FIX: real extension layout is .specify/extensions/<id>/templates/<name>.md
    extension_dir = (
@@ -269,7 +324,7 @@ def test_setup_tasks_bash_preset_priority_order(tasks_repo: Path) -> None:
    When two presets both provide tasks-template.md, the one listed first in
    .specify/presets/.registry wins.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    # resolve_template reads .specify/presets/.registry as a JSON object with a
    # "presets" map where each entry has a numeric "priority" (lower = higher
@@ -329,7 +384,7 @@ def test_setup_tasks_bash_missing_template_errors(tasks_repo: Path) -> None:
    When tasks-template.md is absent from all locations, setup-tasks.sh must
    exit non-zero and print a helpful ERROR message to stderr.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    # Remove the core template so no template exists anywhere
    core = tasks_repo / ".specify" / "templates" / "tasks-template.md"
@@ -345,12 +400,138 @@ def test_setup_tasks_bash_missing_template_errors(tasks_repo: Path) -> None:
        check=False,
        env=_clean_env(),
    )
- 
+
    assert result.returncode != 0
    assert "ERROR" in result.stderr
    assert "tasks-template" in result.stderr
 
 
+@requires_bash
+def test_bash_command_hint_defaults_to_dot_without_integration_json(tasks_repo: Path) -> None:
+    integration_json = tasks_repo / ".specify" / "integration.json"
+    if integration_json.exists():
+        integration_json.unlink()
+
+    result = _run_bash_format_command(tasks_repo, "plan")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.plan"
+
+
+@requires_bash
+def test_bash_command_hint_rejects_invalid_invoke_separator(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "/")
+
+    result = _run_bash_format_command(tasks_repo, "plan")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.plan"
+
+
+@requires_bash
+def test_bash_command_hint_normalizes_mixed_separators(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_bash_format_command(tasks_repo, "/speckit-git.commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.git.commit"
+
+    _write_integration_state(tasks_repo, "claude", "-")
+
+    result = _run_bash_format_command(tasks_repo, "speckit.git-commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit-git-commit"
+
+
+@requires_bash
+def test_bash_command_hint_preserves_hyphens_inside_segments(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_bash_format_command(tasks_repo, "speckit.jira.sync-status")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.jira.sync-status"
+
+
+@requires_bash
+def test_bash_command_hint_caches_invoke_separator_per_process(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "common.sh"
+    dot_state = {
+        "integration": "copilot",
+        "default_integration": "copilot",
+        "installed_integrations": ["copilot"],
+        "integration_settings": {"copilot": {"invoke_separator": "."}},
+    }
+
+    result = subprocess.run(
+        [
+            "bash",
+            "-c",
+            'source "$1"; format_speckit_command plan "$PWD"; printf "%s" "$2" > .specify/integration.json; format_speckit_command tasks "$PWD"',
+            "bash",
+            str(script),
+            json.dumps(dot_state),
+        ],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.splitlines() == ["/speckit-plan", "/speckit-tasks"]
+
+
+@requires_bash
+def test_setup_tasks_bash_uses_invoke_separator_in_plan_hint(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    feat = tasks_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
+
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode != 0
+    assert "Run /speckit-plan first" in result.stderr
+    assert "/speckit.plan" not in result.stderr
+
+
+@requires_bash
+def test_check_prerequisites_bash_uses_invoke_separator_in_tasks_hint(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    _minimal_feature(tasks_repo)
+
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+
+    result = subprocess.run(
+        ["bash", str(script), "--require-tasks"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode != 0
+    assert "Run /speckit-tasks first" in result.stderr
+    assert "/speckit.tasks" not in result.stderr
+
+
@requires_bash
 def test_setup_tasks_bash_passes_custom_branch_when_feature_json_valid(
    tasks_repo: Path,
@@ -413,11 +594,10 @@ def test_setup_tasks_bash_fails_custom_branch_without_feature_json(
        check=False,
        env=_clean_env(),
    )
- 
+
    assert result.returncode != 0
    assert "Not on a feature branch" in result.stderr
 
- 
 # ===========================================================================
 # POWERSHELL TESTS
 # ===========================================================================
@@ -429,7 +609,7 @@ def test_setup_tasks_ps_core_template_resolved(tasks_repo: Path) -> None:
    setup-tasks.ps1 -Json should exit 0 and return an absolute, existing
    TASKS_TEMPLATE path.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
    script = tasks_repo / ".specify" / "scripts" / "powershell" / "setup-tasks.ps1"
    exe = "pwsh" if HAS_PWSH else _POWERSHELL
 
@@ -457,7 +637,7 @@ def test_setup_tasks_ps_override_wins(tasks_repo: Path) -> None:
    When an override exists at .specify/templates/overrides/tasks-template.md,
    setup-tasks.ps1 -Json must return the override path, not the core path.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    overrides_dir = tasks_repo / ".specify" / "templates" / "overrides"
    overrides_dir.mkdir(parents=True, exist_ok=True)
@@ -493,7 +673,7 @@ def test_setup_tasks_ps_missing_template_errors(tasks_repo: Path) -> None:
    When tasks-template.md is absent from all locations, setup-tasks.ps1 must
    exit non-zero and write a helpful error to stderr.
    """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
 
    core = tasks_repo / ".specify" / "templates" / "tasks-template.md"
    core.unlink()
@@ -514,6 +694,87 @@ def test_setup_tasks_ps_missing_template_errors(tasks_repo: Path) -> None:
    assert "tasks-template" in result.stderr.lower() or "tasks-template" in result.stdout.lower()
 
 
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_powershell_command_hint_normalizes_mixed_separators(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_powershell_format_command(tasks_repo, "/speckit-git.commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.git.commit"
+
+    _write_integration_state(tasks_repo, "claude", "-")
+
+    result = _run_powershell_format_command(tasks_repo, "speckit.git-commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit-git-commit"
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_powershell_command_hint_preserves_hyphens_inside_segments(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_powershell_format_command(tasks_repo, "speckit.jira.sync-status")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.jira.sync-status"
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_setup_tasks_ps_uses_invoke_separator_in_plan_hint(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    feat = tasks_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+
+    script = tasks_repo / ".specify" / "scripts" / "powershell" / "setup-tasks.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    output = result.stderr + result.stdout
+    assert result.returncode != 0
+    assert "Run /speckit-plan first" in output
+    assert "/speckit.plan" not in output
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_check_prerequisites_ps_uses_invoke_separator_in_tasks_hint(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    _minimal_feature(tasks_repo)
+
+    script = tasks_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-RequireTasks"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    output = result.stderr + result.stdout
+    assert result.returncode != 0
+    assert "Run /speckit-tasks first" in output
+    assert "/speckit.tasks" not in output
+
+
@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
 def test_setup_tasks_ps_passes_custom_branch_when_feature_json_valid(
    tasks_repo: Path,
@@ -581,4 +842,3 @@ def test_setup_tasks_ps_fails_custom_branch_without_feature_json(
 
    assert result.returncode != 0
    assert "Not on a feature branch" in result.stderr
- 
--- a/tests/test_timestamp_branches.py
+++ b/tests/test_timestamp_branches.py
@@ -923,7 +923,7 @@ class TestDryRun:
        assert re.match(r"^\d{8}-\d{6}-ts-feat$", branch), f"unexpected: {branch}"
        # Verify no side effects
        branches = subprocess.run(
-            ["git", "branch", "--list", f"*ts-feat*"],
+            ["git", "branch", "--list", "*ts-feat*"],
            cwd=git_repo,
            capture_output=True,
            text=True,
--- a/tests/test_upgrade.py
+++ b/tests/test_upgrade.py
@@ -1,14 +1,14 @@
 """Tests for the `specify self` sub-app (`self check` and `self upgrade`).

 Network isolation contract (SC-004 / FR-014): every test that exercises
-`specify self check` or `_fetch_latest_release_tag()` MUST mock
-`urllib.request.urlopen` so no real outbound call ever reaches
-api.github.com. The `self upgrade` stub tests do not need that patch because
-the stub is contractually network-free. Run this module under `pytest-socket`
-(if installed) with `--disable-socket` as an extra safety net.
+`specify self check` or `_fetch_latest_release_tag()` MUST mock the outbound
+urllib path it expects (`urlopen` for unauthenticated requests, `build_opener`
+for authenticated requests) so no real outbound call ever reaches api.github.com.
+Tests for non-network `self upgrade` behavior should keep that contract explicit
+with local mocks. Run this module under `pytest-socket` (if installed) with
+`--disable-socket` as an extra safety net.
 """

-import json
 import urllib.error
 import importlib.metadata
 from unittest.mock import MagicMock, patch
@@ -24,6 +24,7 @@ from specify_cli._version import (
    _normalize_tag,
 )
 from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response

 runner = CliRunner()

@@ -35,16 +36,6 @@ _RATE_LIMITED_REASON = (
 )


-def _mock_urlopen_response(payload: dict) -> MagicMock:
-    body = json.dumps(payload).encode("utf-8")
-    resp = MagicMock()
-    resp.read.return_value = body
-    cm = MagicMock()
-    cm.__enter__.return_value = resp
-    cm.__exit__.return_value = False
-    return cm
-
-
 def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
    return urllib.error.HTTPError(
        url="https://api.github.com/repos/github/spec-kit/releases/latest",
@@ -55,39 +46,6 @@ def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
    )


-class TestSelfUpgradeStub:
-    """Pins the `specify self upgrade` stub output + exit code (contract §3.5, FR-016)."""
-
-    def test_prints_exactly_three_lines_and_exits_zero(self):
-        result = runner.invoke(app, ["self", "upgrade"])
-        assert result.exit_code == 0
-        lines = strip_ansi(result.output).strip().splitlines()
-        assert lines == [
-            "specify self upgrade is not implemented yet.",
-            "Run 'specify self check' to see whether a newer release is available.",
-            "Actual self-upgrade is planned as follow-up work.",
-        ]
-
-    def test_stub_makes_no_network_call(self):
-        # The stub must not hit the network via either urllib path:
-        # unauthenticated requests use urlopen() directly; authenticated ones
-        # go through build_opener(...).open().  Both are patched so that any
-        # accidental network call raises immediately.
-        network_error = AssertionError("stub must not hit the network")
-        with (
-            patch(
-                "specify_cli.authentication.http.urllib.request.urlopen",
-                side_effect=network_error,
-            ),
-            patch(
-                "specify_cli.authentication.http.urllib.request.build_opener",
-                side_effect=network_error,
-            ),
-        ):
-            result = runner.invoke(app, ["self", "upgrade"])
-        assert result.exit_code == 0
-
-
 class TestIsNewer:
    def test_latest_strictly_greater_returns_true(self):
        assert _is_newer("0.8.0", "0.7.4") is True
@@ -151,7 +109,7 @@ class TestUserStory1:
    def test_newer_available_prints_update_and_install_command(self):
        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.9.0"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
        ):
            result = runner.invoke(app, ["self", "check"])
        output = strip_ansi(result.output)
@@ -164,7 +122,7 @@ class TestUserStory1:
    def test_up_to_date_prints_current_only(self):
        with patch("specify_cli._version._get_installed_version", return_value="0.9.0"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.9.0"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
        ):
            result = runner.invoke(app, ["self", "check"])
        output = strip_ansi(result.output)
@@ -176,7 +134,7 @@ class TestUserStory1:
    def test_dev_build_ahead_of_release_is_up_to_date(self):
        with patch("specify_cli._version._get_installed_version", return_value="0.7.5.dev0"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.7.4"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
        ):
            result = runner.invoke(app, ["self", "check"])
        output = strip_ansi(result.output)
@@ -187,26 +145,46 @@ class TestUserStory1:
    def test_unknown_installed_still_prints_latest_and_reinstall(self):
        with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.7.4"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
        ):
            result = runner.invoke(app, ["self", "check"])
        output = strip_ansi(result.output)
        assert result.exit_code == 0
        assert "Current version could not be determined" in output
+        assert "Latest release: v0.7.4" in output
        assert "0.7.4" in output
        assert "git+https://github.com/github/spec-kit.git@v0.7.4" in output
+        assert "specify self upgrade" in output
+        assert "pipx install --force git+https://github.com/github/spec-kit.git@v0.7.4" in output

-    def test_unparseable_tag_routes_to_indeterminate(self):
+    def test_unknown_installed_uses_placeholder_when_latest_tag_is_invalid(self):
+        with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0;echo unsafe"}),
+        ):
+            result = runner.invoke(app, ["self", "check"])
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "Latest release: vX.Y.Z" in output
+        assert "Could not validate latest release tag from GitHub." in output
+        assert "git+https://github.com/github/spec-kit.git@vX.Y.Z" in output
+        assert "v0.9.0;echo unsafe" not in output
+
+    def test_unparseable_tag_reports_validation_failure_without_raw_tag(self):
        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "not-a-version"}),
+            return_value=mock_urlopen_response({"tag_name": "not-a-version"}),
        ):
            result = runner.invoke(app, ["self", "check"])
        output = strip_ansi(result.output)
        assert result.exit_code == 0
        assert "Update available" not in output
-        assert "Up to date" in output
+        assert "Up to date" not in output
+        assert "Could not validate latest release tag from GitHub." in output
+        assert "Latest release: vX.Y.Z" in output
        assert "0.7.4" in output
+        assert "not-a-version" not in output
+        assert "git+https://github.com/github/spec-kit.git@vX.Y.Z" in output


 class TestFailureCategorization:
@@ -306,13 +284,25 @@ class TestUserStory2:
 def _capture_request_via_urlopen():
    captured = {}

-    def _side_effect(req, timeout=None):
+    def _side_effect(req, *args, **kwargs):
        captured["request"] = req
-        return _mock_urlopen_response({"tag_name": "v0.7.4"})
+        return mock_urlopen_response({"tag_name": "v0.7.4"})

    return captured, _side_effect


+def _capture_request_via_auth_opener():
+    captured = {}
+
+    def _side_effect(req, *args, **kwargs):
+        captured["request"] = req
+        return mock_urlopen_response({"tag_name": "v0.7.4"})
+
+    opener = MagicMock()
+    opener.open.side_effect = _side_effect
+    return captured, opener
+
+
 def _inject_github_config(monkeypatch, token_env="GH_TOKEN"):
    from tests.auth_helpers import inject_github_config
    inject_github_config(monkeypatch, token_env)
@@ -323,10 +313,11 @@ class TestUserStory3:
        monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
        monkeypatch.delenv("GITHUB_TOKEN", raising=False)
        _inject_github_config(monkeypatch, token_env="GH_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
            _fetch_latest_release_tag()
        req = captured["request"]
        assert req.get_header("Authorization") == f"Bearer {SENTINEL_GH_TOKEN}"
@@ -335,10 +326,11 @@ class TestUserStory3:
        monkeypatch.delenv("GH_TOKEN", raising=False)
        monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
        _inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
            _fetch_latest_release_tag()
        req = captured["request"]
        assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"
@@ -376,10 +368,11 @@ class TestUserStory3:
        monkeypatch.setenv("GH_TOKEN", "   ")
        monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
        _inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
            _fetch_latest_release_tag()
        req = captured["request"]
        assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"
--- a/tests/test_utils_assets_imports.py
+++ b/tests/test_utils_assets_imports.py
@@ -1,7 +1,6 @@
 """Regression guard: utility and asset symbols importable from specify_cli."""
 from specify_cli import (
-    run_command, check_tool, is_git_repo, init_git_repo,
-    handle_vscode_settings, merge_json_files,
+    check_tool, is_git_repo, merge_json_files,
    get_speckit_version,
    CLAUDE_LOCAL_PATH, CLAUDE_NPM_LOCAL_PATH,
 )
--- a/tests/test_version_imports.py
+++ b/tests/test_version_imports.py
@@ -23,7 +23,6 @@ def test_version_symbols_available_from_star_import():

 def test_version_module_symbols_directly_importable():
    from specify_cli._version import (
-        GITHUB_API_LATEST,
        _fetch_latest_release_tag,
        _get_installed_version,
        _is_newer,
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -2716,6 +2716,112 @@ class TestRunState:
        with pytest.raises(FileNotFoundError):
            RunState.load("nonexistent", project_dir)

+    @pytest.mark.parametrize(
+        "malicious_run_id",
+        [
+            # Parent-directory traversal — the classic path-escape vector.
+            "../escape",
+            "..",
+            "../../etc/passwd",
+            # Embedded path separators — both POSIX and Windows.
+            "foo/bar",
+            "foo\\bar",
+            # Leading non-alphanumeric characters that the existing
+            # pattern's anchor blocks (would be mistaken for CLI flags
+            # or hidden files in shell completions / error messages).
+            ".hidden",
+            "-flag",
+            # NUL byte — some filesystems treat the prefix as a valid
+            # path and silently truncate at the NUL.
+            "foo\x00bar",
+            # Empty string — degenerate case, matches no file but the
+            # validator should reject it before any I/O.
+            "",
+        ],
+    )
+    def test_load_rejects_path_traversal(self, project_dir, malicious_run_id):
+        """``RunState.load`` validates ``run_id`` before touching the
+        filesystem.
+
+        Without this guard, a value like ``../escape`` passed via
+        ``specify workflow resume`` would interpolate path-traversal
+        segments into the lookup path. ``state_path.exists()`` would
+        probe arbitrary paths the process can read (a file-existence
+        oracle) and ``json.load`` would happily parse attacker-planted
+        JSON from outside ``.specify/workflows/runs/``. The check must
+        fire *before* the path is built — ``__init__``'s identical
+        regex on ``state_data["run_id"]`` fires too late.
+        """
+        from specify_cli.workflows.engine import RunState
+
+        # Plant a state.json *outside* the legitimate ``runs/`` directory
+        # at the location ``../escape`` would traverse to, so a missing
+        # guard would surface as a successful load rather than a
+        # ``FileNotFoundError`` (which would be ambiguous with the
+        # not-found case).
+        runs_dir = project_dir / ".specify" / "workflows" / "runs"
+        runs_dir.mkdir(parents=True, exist_ok=True)
+        attacker_dir = project_dir / ".specify" / "workflows" / "escape"
+        attacker_dir.mkdir(exist_ok=True)
+        (attacker_dir / "state.json").write_text(
+            json.dumps(
+                {
+                    "run_id": "pwned",
+                    "workflow_id": "attacker-owned",
+                    "status": "created",
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState.load(malicious_run_id, project_dir)
+
+    @pytest.mark.parametrize(
+        "bad_run_id",
+        [
+            # One vector per category from ``test_load_rejects_path_traversal``
+            # — enough to prove both entry points agree without re-running
+            # the full attack matrix here.
+            "../escape",    # parent-directory traversal
+            "foo/bar",      # embedded path separator
+            ".hidden",      # leading non-alphanumeric
+            "",             # empty / degenerate
+        ],
+    )
+    def test_init_and_load_share_validation(self, project_dir, bad_run_id):
+        """``__init__`` *and* ``load`` reject the same malformed IDs.
+
+        The two entry points must stay in sync — drift would let an ID
+        slip in via one path that the other would reject, producing
+        confusing crashes mid-workflow. The previous version of this
+        test only exercised ``__init__`` and ``_validate_run_id`` (the
+        shared helper), so a regression in ``load`` — e.g. someone
+        deleting the ``cls._validate_run_id(run_id)`` call there — could
+        slip through despite ``__init__`` and the helper staying
+        aligned. We now hit ``load`` directly with the same vector so
+        any drift between the two call sites is caught by this test.
+        """
+        from specify_cli.workflows.engine import RunState
+
+        # ``__init__`` rejects up front.
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState(run_id=bad_run_id)
+
+        # The shared helper rejects the value too (sanity check that the
+        # ``__init__`` rejection came from the validator, not some
+        # unrelated constructor failure).
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState._validate_run_id(bad_run_id)
+
+        # And ``load`` rejects it *before* touching the filesystem. This
+        # is the assertion the previous version was missing: without it,
+        # a regression in ``load`` (e.g. forgetting to call the
+        # validator before building the path) would not be caught even
+        # though ``__init__`` and the helper still agreed.
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState.load(bad_run_id, project_dir)
+
    def test_append_log(self, project_dir):
        from specify_cli.workflows.engine import RunState

@@ -3026,3 +3132,118 @@ steps:
        assert state.status == RunStatus.COMPLETED
        assert "do-plan" in state.step_results
        assert "do-specify" not in state.step_results
+
+
+class TestResumeWithInputs:
+    """Test that `workflow resume` can accept updated workflow inputs."""
+
+    _WF_CMD = """
+schema_version: "1.0"
+workflow:
+  id: "resume-cmd-wf"
+  name: "Resume Cmd WF"
+  version: "1.0.0"
+inputs:
+  cmd:
+    type: string
+    default: "exit 1"
+steps:
+  - id: s
+    type: shell
+    run: "{{ inputs.cmd }}"
+"""
+
+    _WF_NUM = """
+schema_version: "1.0"
+workflow:
+  id: "resume-num-wf"
+  name: "Resume Num WF"
+  version: "1.0.0"
+inputs:
+  count:
+    type: number
+    default: 1
+steps:
+  - id: gate
+    type: gate
+    message: "Review"
+    options: [approve, reject]
+"""
+
+    def _engine(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowEngine
+        return WorkflowEngine(project_dir)
+
+    def test_resume_with_input_reruns_step_with_new_value(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_CMD)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.FAILED  # "exit 1" fails
+
+        resumed = engine.resume(state.run_id, {"cmd": "exit 0"})
+        assert resumed.status == RunStatus.COMPLETED
+        assert resumed.inputs["cmd"] == "exit 0"
+
+    def test_resume_without_input_preserves_inputs(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_CMD)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.FAILED
+
+        resumed = engine.resume(state.run_id)
+        assert resumed.status == RunStatus.FAILED  # still "exit 1"
+        assert resumed.inputs["cmd"] == "exit 1"
+
+    def test_resume_merges_and_coerces_typed_input(self, project_dir):
+        import json as _json
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.PAUSED
+
+        resumed = engine.resume(state.run_id, {"count": "5"})
+        assert resumed.inputs["count"] == 5  # coerced string -> number
+
+        inputs_file = (
+            project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
+        )
+        assert _json.loads(inputs_file.read_text())["inputs"]["count"] == 5
+
+    def test_resume_invalid_typed_input_raises(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        with pytest.raises(ValueError):
+            engine.resume(state.run_id, {"count": "not-a-number"})
+
+    def test_cli_resume_input_invalid_format_errors(self, project_dir):
+        from typer.testing import CliRunner
+        from unittest.mock import patch
+        from specify_cli import app
+        from specify_cli.workflows.engine import WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        state = self._engine(project_dir).execute(definition)
+
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir):
+            result = runner.invoke(
+                app, ["workflow", "resume", state.run_id, "--input", "bogus"]
+            )
+        assert result.exit_code == 1
+        assert "Invalid input format" in result.stdout
Author	SHA1	Message	Date
github-actions[bot]	800fe33f59	chore: bump version to 0.9.3	2026-06-03 21:25:59 +00:00
Pascal THUET	4028c50af8	fix: render script command hints with active agent separator (#2649 ) * fix script command hints for agent separators * Address command hint review feedback * chore: remove whitespace-only PR churn * test: fix PowerShell command hint invocation * fix: preserve hyphens in script command hints * fix: render managed script command hints	2026-06-03 16:24:13 -05:00
darion-yaphet	67fecd357a	chore(tests): fix ruff lint violations in tests/ (#2827 ) Clear pre-existing lint debt flagged by repo-wide `ruff check` (the lint config only scopes src/, so tests/ had drifted). No behavior change. - F401/F541: drop unused imports and redundant f-string prefixes (autofix) - E741: rename ambiguous `l` to `ln` in comprehensions - E702: split semicolon-joined statements onto separate lines - F841: drop unused bindings while keeping the side-effecting calls (_minimal_feature, install_from_directory) Full suite: 3344 passed, 40 skipped. ruff check (repo-wide): clean.	2026-06-03 16:02:26 -05:00
Quratulain-bilal	bb2b49d0ae	fix(workflows): validate run_id in RunState.load before touching the … (#2813 ) * fix(workflows): validate run_id in RunState.load before touching the filesystem ``RunState.load(run_id, project_root)`` interpolates ``run_id`` directly into ``project_root / ".specify" / "workflows" / "runs" / run_id`` and then calls ``state_path.exists()`` and ``json.load`` on the result. The run_id is reachable from user input via ``specify workflow resume <run_id>`` (CLI argument) and via ``SPECKIT_WORKFLOW_RUN_ID`` (env var override on the engine's run path), so a value like ``../escape`` turns ``runs_dir`` into ``.specify/workflows/escape/`` and: * ``state_path.exists()`` becomes a file-existence oracle for any path the process can read. * if a ``state.json`` exists at the traversed location (planted by a malicious dependency, a misconfigured shared workspace, or an older spec-kit version that happened to write there), ``json.load`` parses it and the workflow resumes under the attacker-chosen ``workflow_id`` / step state. * a subsequent ``state.save()`` then writes back to the traversed location, persisting the corruption. ``RunState.__init__`` already validates ``run_id`` against ``r'^[a-zA-Z0-9][a-zA-Z0-9_-]$'`` — but that check runs on ``state_data["run_id"]`` after* ``load`` has already done the file lookup, which is too late to prevent the disclosure. This change extracts the pattern into a class-level constant ``_RUN_ID_PATTERN`` and a single ``_validate_run_id`` classmethod so ``__init__`` and ``load`` cannot drift, then calls the validator at the top of ``load`` before any path is built. Mirrors the precedent in ``src/specify_cli/agents.py::_ensure_within_directory`` (used at line 437 of that file) which guards extension-install paths against the same threat model. Regression tests parametrize 9 traversal vectors (``../escape``, ``..``, ``../../etc/passwd``, ``foo/bar``, ``foo\bar``, ``.hidden``, ``-flag``, ``foo\x00bar``, empty) and plant a malicious ``state.json`` outside ``runs/`` so a missing guard would surface as a successful load rather than the ambiguous ``FileNotFoundError``. A second test asserts ``__init__`` and ``load`` reject the same representative malformed ID, so future changes to one path can't silently drift from the other. * test(workflows): exercise RunState.load in shared-validation test, fix __init__ empty-string asymmetry Copilot's review on this PR pointed out that test_init_and_load_share_validation claimed to verify both entry points share the same validation rules but never actually called RunState.load — only __init__ and the shared _validate_run_id helper. A regression in load (e.g. someone deleting the cls._validate_run_id(run_id) call before the path is built) would slip through even though __init__ and the helper stayed aligned, defeating the whole point of the test. Tightening the test surfaced a real asymmetry the previous version was silently masking: self.run_id = run_id or str(uuid.uuid4())[:8] The truthiness fallback meant RunState(run_id="") silently substituted a UUID and skipped validation, while RunState.load("", project_root) correctly rejected the empty string. The two entry points diverged on the empty-string vector. That is exactly the drift the test name claimed to defend against — and the original test missed it. Changes ------- * engine.py: __init__ now distinguishes run_id is None (caller omitted it → auto-generate UUID) from an empty string (caller provided it → must validate like any other value). Both paths still flow through _validate_run_id, but only the explicit-None case auto-generates. * test_workflows.py: test_init_and_load_share_validation is now parametrized over one representative vector per category from test_load_rejects_path_traversal (parent traversal, embedded separator, leading non-alphanumeric, empty string) and asserts that all three entry points — __init__, _validate_run_id, and load — reject the same input. Adding load to the assertion is the substantive fix Copilot asked for; keeping __init__ and the helper alongside it makes any future drift between the three immediately observable instead of having to read three separate tests. Verification ------------ pytest tests/test_workflows.py — 168 passed (was 165 before the parametrize expansion; __init__ empty-string vector would have failed the new test against the old engine code, confirming the asymmetry was real).	2026-06-03 14:26:07 -05:00
김준호	ac2cb5daf5	feat(cli): implement specify self upgrade (#2475 ) * feat(cli): implement specify self upgrade * fix(cli): normalize self-upgrade prerelease tags * fix(cli): tighten self-upgrade diagnostics * fix(cli): harden self-upgrade verification parsing * fix(cli): sanitize self-check fallback tags * fix(cli): harden self-check release display * fix(cli): validate resolved upgrade tags * fix(cli): tolerate invalid install metadata * test(cli): align upgrade network mocks * fix(cli): respect relative installer paths * fix(cli): tighten upgrade failure handling * fix(cli): align installer path diagnostics * fix(cli): validate release and version output * fix(cli): clarify source checkout guidance * fix(cli): harden upgrade detection helpers * fix(cli): avoid echoing invalid release tags * fix(cli): tolerate argv path resolve failures * chore: remove self-upgrade formatting-only diffs * fix: address self-upgrade review feedback * fix: address self-upgrade review followups * fix: address self-upgrade review edge cases * fix: address self-upgrade review docs * fix: refine self-upgrade review followups * fix: address self-upgrade review cleanup * fix: handle self-upgrade review edge cases * fix: address self-upgrade review nits * fix: address follow-up self-upgrade review * fix: resolve self-upgrade review and Windows CI failures - README: promote "Optional Commands" to ### so it is a sibling of "Core Commands" under "Available Slash Commands" (consistent heading levels; avoids the h2->h4 jump a revert would create). - _version: allow --tag prerelease/dev and build-metadata suffixes to compose (e.g. v1.0.0-rc1+build.42), matching PEP 440 / semver; the Version() check still enforces canonical validity. - tests: compare resolved argv0 as Path objects instead of POSIX strings so the assertion holds on Windows; skip the relative-installer-path executable-bit tests on Windows via a new requires_posix marker (they rely on chmod/X_OK semantics and chdir-into-tmp teardown that do not hold there). Add a combined prerelease+build-metadata tag test. * fix: address second self-upgrade review round - self_check: clarify that the "up to date" branch is reached only for parseable latest tags (the unparseable case returns earlier), so the InvalidVersion fallback assumption is not reintroduced. - self_upgrade: compare target/current as Version instances directly instead of re-parsing the canonical strings through _is_newer; the empty-current case stays explicit via the not-None guard. - tests: document the intentional broad GH_/GITHUB_ env scrub with a test asserting non-credential context vars (GH_HOST, GITHUB_REPOSITORY, …) are stripped from the installer subprocess env — a deliberate fail-safe that also catches credential-adjacent names without a recognized suffix. * fix: address third self-upgrade review round - self_upgrade: unify the no-op short-circuits on packaging Version equality instead of canonical-string equality. Version("1.0") equals Version("1.0.0") but their str() forms differ, so the old check could misreport an equal install as "already on latest release or newer". Both the unpinned and pinned branches now use Version comparison. - self_upgrade: compare the verified version as a parsed Version against the target so a non-version verifier result is a mismatch (exit 2) rather than a coincidental canonical-string match. - resolver: map HTTP 429 (Too Many Requests / secondary rate limit) to the rate-limited category so users get the same actionable token hint as 403. - _is_github_credential_env_key: document the precise (intentionally broad) scrub matching contract in the docstring. - tests: add a trailing-zero Version-equality regression test and a parametrized HTTP-status categorization test (429 -> rate limited; 404/502 -> verbatim). * fix: address fourth self-upgrade review round - self_upgrade: label a pinned target older than the installed version as "Downgrading" rather than "Upgrading" so `--tag <older>` is not mistaken for a forward upgrade. - resolver: drop the unused `typing.Optional` import and annotate the `--tag` option as `str \| None`, consistent with the rest of the module (verified Typer resolves it on the supported Python versions). - _is_github_credential_env_key: add `_PASSWORD` and `_CREDENTIALS` to the recognized credential suffixes and document that only these shapes are scrubbed (not blanket coverage). - tests: assert the precise exit code (1) for the re-raised transient OSError path; skip the InvalidMetadataError test on Pythons where the real exception is absent instead of fabricating it; update the pinned downgrade test to expect the "Downgrading" label. * fix: accept uppercase V prefix in --tag Fold a leading uppercase `V` (a common paste) to the canonical lowercase `v` before validating `--tag`. The remainder of the tag stays case-sensitive on purpose: the validated value is used verbatim as a git ref, which is case-sensitive on GitHub, so rewriting label/build-metadata casing could point at a tag that does not exist. Adds a normalization test.	2026-06-03 12:04:54 -05:00
Huy Do	1732b9b62e	feat(workflows): allow resume to accept updated workflow inputs (#2815 ) `workflow resume` now accepts `--input key=value` (the same flag and parsing as `workflow run`, via a shared `_parse_input_values` helper). Supplied values are merged over the run's persisted inputs and re-resolved through the existing typed-validation path (`_resolve_inputs`), so a resumed/re-run step sees the updated inputs and ill-typed values fail fast. Keys not supplied keep their persisted values; resuming without `--input` is unchanged. Reference docs updated. Distinct from #2405 (file-reference inputs at run time): this is about supplying inputs at resume time, reusing the existing input model. Closes #2812. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 12:04:07 -05:00
WangX	1f9eaf3ff3	catalog: rename "superpowers-bridge" to "superspec" (v1.0.1) (#2772 ) * catalog: rename "superpowers-bridge" to "superspec" (v1.0.1) * fix: address Copilot feedback (sync top-level updated_at, rename docs entry)	2026-06-03 08:36:26 -05:00
Rafael Figuereo	9e05195d24	fix(cli): force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError (#2817 ) On Windows, when stdout/stderr are not a UTF-8 TTY (output piped, redirected to a file, or running under a legacy code page such as cp1252), Rich cannot encode the banner and box-drawing glyphs, so the CLI aborts with a UnicodeEncodeError traceback instead of printing. This breaks basic commands like `specify --help` and `specify version` whenever their output is captured rather than written to an interactive terminal. Reconfigure sys.stdout/sys.stderr to UTF-8 with errors="replace" at the main() entry point on win32 so output degrades gracefully instead of crashing. The change is a no-op on POSIX, is guarded by try/except so it can never make stream setup worse, and lives at the CLI entry point only -- importing specify_cli as a library does not touch global streams. Verified on Windows 11 (cp1252): `specify --help` piped and `specify version` redirected to a file both render correctly and exit 0 without setting PYTHONUTF8 / PYTHONIOENCODING. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-03 08:32:14 -05:00
WOLIKIMCHENG	6d511acfb9	fix(plan): clarify quickstart validation guide scope (#2805 ) Co-authored-by: root <kinsonnee@gmail.com>	2026-06-03 08:07:42 -05:00
Manfred Riem	06c76533cb	chore: release 0.9.2, begin 0.9.3.dev0 development (#2823 ) * chore: bump version to 0.9.2 * chore: begin 0.9.3.dev0 development --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-06-02 17:52:31 -05:00