chore: bump version to 0.12.1

* chore: align CI Python matrix with devguide release lifecycle

Run the pytest matrix only on the bugfix (maintenance) releases — 3.13
and 3.14 — instead of 3.11/3.12/3.13, and point the ruff lint job at the
latest interpreter (3.14). The supported floor stays at requires-python
>= 3.11 (oldest non-EOL security release): older security versions are
supported by claim and fixed reactively rather than gated on a wide
per-commit matrix. Also add macos-latest to the OS matrix so macOS
regressions are caught.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: make bash scripts portable to bash 3.2 (macOS system /bin/bash)

Adding macos-latest to the CI matrix surfaced two pre-existing bash 3.2
incompatibilities (macOS ships bash 3.2 as /bin/bash):

1. update-agent-context.sh embedded Python heredocs inside $(...) command
   substitution. bash 3.2 mis-parses an apostrophe in a heredoc body
   nested in $(...), failing with "unexpected EOF while looking for
   matching `''". Removed the apostrophes from the affected $()-nested
   heredoc body and documented the constraint to prevent regressions.

2. create-new-feature-branch.sh and create-new-feature.sh used the
   bash 4+ ${word^^} uppercase parameter expansion, which errors as a
   "bad substitution" on bash 3.2 and caused short uppercase acronyms
   (e.g. "GO") to be dropped from derived branch names. Replaced with a
   portable `tr '[:lower:]' '[:upper:]'` pipeline.

Verified the full test suite passes under bash 3.2.57 and shellcheck
(--severity=error) is clean.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: address review feedback on bash 3.2 portability changes

- create-new-feature.sh: replace the non-portable `\b...\b` grep
  word-boundary (BSD grep treats `\b` as a backspace, so the acronym
  branch could silently fail) with `grep -qw`, matching its twin
  create-new-feature-branch.sh, and pipe the description via
  `printf '%s'` instead of `echo`.
- create-new-feature-branch.sh: switch the acronym check to
  `printf '%s'` as well so both twins are identical and avoid `echo`
  on user-provided text.
- update-agent-context.sh: reword the apostrophe-free self-seeding
  comment to be clearer and less easy to misread.

Verified under bash 3.2.57 (full bash-script suite green) and
shellcheck --severity=error.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/workflows/test.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Run ruff check
         run: uvx ruff check src/
@@ -30,8 +30,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest]
-        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.13", "3.14"]
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

CHANGELOG.md

@@ -2,6 +2,36 @@
 
 <!-- insert new changelog below this comment -->
 
+## [0.12.1] - 2026-06-30
+
+### Changed
+
+- chore: align CI Python matrix with devguide lifecycle + fix bash 3.2 portability (#3244)
+- fix: stop check-prerequisites --paths-only from writing feature.json (#3025) (#3190)
+- docs: document integration catalog subcommands (#3206)
+- fix(scripts): use ASCII [OK] marker in initialize-repo.sh (parity with PowerShell twin) (#3231)
+- docs: document integration `search`/`info`/`scaffold` subcommands (#3174) (#3194)
+- docs: remove Cursor from `specify check` agent list (#3178) (#3193)
+- fix(goose): repoint install_url and docs to goose-docs.ai (#3171) (#3215)
+- fix(scripts): route 'Plan template not found' per --json in setup-plan.ps1 (parity with bash) (#3241)
+- fix(bundle): send command errors to stderr so --json stdout stays parseable (#3235)
+- chore: release 0.12.0, begin 0.12.1.dev0 development (#3243)
+
+## [0.12.0] - 2026-06-29
+
+### Changed
+
+- feat: make agent-context extension a full opt-in (#3097)
+- docs(workflows): add the built-in 'init' step type to the Step Types table (#3234)
+- fix(workflows): gate validate() must not crash on non-string options (#3233)
+- fix(workflows): make pipe-filter detection quote-aware in expressions (#3232)
+- fix(workflows): reject a fan-in wait_for that names an unknown step at validation (#3225)
+- fix(scripts): warn when spec template is missing in create-new-feature.ps1 (parity with bash) (#3230)
+- fix(scripts): count subdirectory-only dirs as non-empty in PowerShell (parity with bash) (#3137)
+- fix(scripts): drop HAS_GIT from PowerShell git-extension output (parity with bash) (#3195)
+- Update Product Spec Extension to v1.0.1 (#3226)
+- chore: release 0.11.10, begin 0.11.11.dev0 development (#3240)
+
 ## [0.11.10] - 2026-06-29
 
 ### Changed

README.md

@@ -406,7 +406,7 @@ specify init . --force --integration copilot
 specify init --here --force --integration copilot
 ```
 
-The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi, Oh My Pi, Forge, Goose, Mistral Vibe, or ZCode installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
+The CLI will check that your selected agent's CLI tool is installed (for integrations that require a CLI), such as Claude Code, Gemini CLI, Qwen Code, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi Coding Agent, Oh My Pi, Forge, Goose, Mistral Vibe, or ZCode. If you don't have the required tool installed, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
 
 ```bash
 specify init <project_name> --integration copilot --ignore-agent-tools

docs/reference/integrations.md

@@ -19,7 +19,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Forge](https://forgecode.dev/)                                                      | `forge`          |                                                                                                                                           |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli)                            | `gemini`         |                                                                                                                                           |
 | [GitHub Copilot](https://code.visualstudio.com/)                                     | `copilot`        |                                                                                                                                           |
-| [Goose](https://block.github.io/goose/)                                              | `goose`          | Uses YAML recipe format in `.goose/recipes/`                                                                                              |
+| [Goose](https://goose-docs.ai/)                                                      | `goose`          | Uses YAML recipe format in `.goose/recipes/`                                                                                              |
 | [Hermes](https://github.com/NousResearch/hermes-agent)                               | `hermes`         | Skills-based integration; installs skills globally into `~/.hermes/skills/`                                                                |
 | [IBM Bob](https://www.ibm.com/products/bob)                                          | `bob`            | IDE-based agent                                                                                                                           |
 | [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart)                                 | `iflow`          |                                                                                                                                           |
@@ -54,6 +54,27 @@ Shows all available integrations, which one is currently installed, and whether
 When multiple integrations are installed, the list marks the default integration separately from the other installed integrations.
 The list also shows whether each built-in integration is declared multi-install safe.
 
+## Search Available Integrations
+
+```bash
+specify integration search [query]
+```
+
+| Option     | Description        |
+| ---------- | ------------------ |
+| `--tag`    | Filter by tag      |
+| `--author` | Filter by author   |
+
+Searches the active catalog stack for integrations matching the query. Without a query, lists all available integrations. Must be run inside a Spec Kit project.
+
+## Integration Info
+
+```bash
+specify integration info <integration_id>
+```
+
+Shows catalog details for a single integration, including its description, author, license, tags, source catalog, repository (when available), and whether it is currently active. Must be run inside a Spec Kit project.
+
 ## Install an Integration
 
 ```bash
@@ -152,6 +173,47 @@ is `null` when no installed integration set can be evaluated, such as when the
 integration state is missing, unreadable, lacks a valid recorded integration
 list, or records no installed integrations.
 
+## Catalog Management
+
+Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order.
+
+### List Catalogs
+
+```bash
+specify integration catalog list
+```
+
+Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable.
+
+### Add a Catalog
+
+```bash
+specify integration catalog add <url>
+```
+
+| Option          | Description                   |
+| --------------- | ----------------------------- |
+| `--name <name>` | Optional name for the catalog |
+
+Adds a custom catalog URL to the project's `.specify/integration-catalogs.yml`. The URL must use HTTPS (except `http://localhost`, `http://127.0.0.1`, or `http://[::1]` for local testing).
+
+### Remove a Catalog
+
+```bash
+specify integration catalog remove <index>
+```
+
+Removes a project catalog source by its 0-based index in `catalog list`.
+
+### Catalog Resolution Order
+
+Catalogs are resolved in this order (first match wins):
+
+1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs
+2. **Project config** — `.specify/integration-catalogs.yml`
+3. **User config** — `~/.specify/integration-catalogs.yml`
+4. **Built-in defaults** — official catalog + community catalog
+
 ## Integration-Specific Options
 
 Some integrations accept additional options via `--integration-options`:
@@ -167,6 +229,18 @@ Example:
 specify integration install generic --integration-options="--commands-dir .myagent/cmds"
 ```
 
+## Scaffold a New Integration
+
+```bash
+specify integration scaffold <key>
+```
+
+Creates a minimal built-in integration package and a matching test skeleton in the Spec Kit repository, then prints the next steps for wiring it up. Run this command from the Spec Kit repository root. The `<key>` must be lowercase kebab-case (for example, `my-agent`).
+
+| Option   | Description                                                       |
+| -------- | ---------------------------------------------------------------- |
+| `--type` | Scaffold template to use: `markdown` (default), `skills`, `toml`, or `yaml` |
+
 ## FAQ
 
 ### Can I install multiple integrations in the same project?

extensions/agent-context/scripts/bash/update-agent-context.sh

@@ -59,6 +59,13 @@ case "$(uname -s 2>/dev/null || true)" in
 esac
 
 # Parse extension config once; emit context files as JSON, followed by marker strings.
+#
+# NOTE (bash 3.2 / macOS portability): the embedded Python heredocs below run
+# inside $(...) command substitution. bash 3.2 (the system /bin/bash on macOS)
+# mis-parses a single-quote/apostrophe in a heredoc body nested in $(...),
+# failing with "unexpected EOF while looking for matching `''". Keep these
+# $(...)-nested heredoc bodies free of apostrophes (use double quotes in Python
+# string literals and avoid contractions in comments).
 if ! _raw_opts="$("$_python" - "$EXT_CONFIG" "$_case_insensitive_context_files" "$PROJECT_ROOT" <<'PY'
 import json
 import sys
@@ -113,11 +120,11 @@ if isinstance(raw_files, list):
 if not context_files:
     add_context_file(get_str(data, "context_file"))
 if not context_files:
-    # Self-seed: the agent-context extension owns its lifecycle, so when its
-    # own config declares no target it derives one from the active integration
-    # recorded in init-options.json, using the extension's OWN bundled mapping
-    # (agent-context-defaults.json). This is independent of the Specify CLI by
-    # design — nothing here imports specify_cli.
+    # Self-seed: the agent-context extension manages its own lifecycle, so when
+    # its config declares no target, it derives one from the active integration
+    # recorded in init-options.json, mapped through the bundled
+    # agent-context-defaults.json file. This is independent of the Specify CLI
+    # by design; nothing here imports specify_cli.
     project_root = sys.argv[3] if len(sys.argv) > 3 else "."
     integration_key = ""
     try:
@@ -144,7 +151,7 @@ if not context_files:
         except Exception:
             print(
                 "agent-context: unable to read %s; cannot self-seed the context "
-                "file. Set 'context_file' in the extension config." % defaults_path,
+                "file. Set context_file in the extension config." % defaults_path,
                 file=sys.stderr,
             )
             mapping = {}
@@ -152,7 +159,7 @@ if not context_files:
         if not context_files:
             print(
                 "agent-context: no default context file is known for integration "
-                "'%s'. Set 'context_file' in the extension config to choose one."
+                "%s. Set context_file in the extension config to choose one."
                 % integration_key,
                 file=sys.stderr,
             )

extensions/git/scripts/bash/create-new-feature-branch.sh

@@ -288,7 +288,7 @@ generate_branch_name() {
         if ! echo "$word" | grep -qiE "$stop_words"; then
             if [ ${#word} -ge 3 ]; then
                 meaningful_words+=("$word")
-            elif echo "$description" | grep -qw -- "${word^^}"; then
+            elif printf '%s' "$description" | grep -qw -- "$(printf '%s' "$word" | tr '[:lower:]' '[:upper:]')"; then
                 meaningful_words+=("$word")
             fi
         fi

extensions/git/scripts/bash/initialize-repo.sh

@@ -51,4 +51,4 @@ _git_out=$(git init -q 2>&1) || { echo "[specify] Error: git init failed: $_git_
 _git_out=$(git add . 2>&1) || { echo "[specify] Error: git add failed: $_git_out" >&2; exit 1; }
 _git_out=$(git commit --allow-empty -q -m "$COMMIT_MSG" 2>&1) || { echo "[specify] Error: git commit failed: $_git_out" >&2; exit 1; }
 
-echo "✓ Git repository initialized" >&2
+echo "[OK] Git repository initialized" >&2

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.11.11.dev0"
+version = "0.12.1"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 readme = "README.md"
 requires-python = ">=3.11"

scripts/bash/check-prerequisites.sh

@@ -78,8 +78,14 @@ done
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
-# Get feature paths
-_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+# Get feature paths.
+# In --paths-only mode this is pure resolution, so pass --no-persist to opt out
+# of the feature.json write side effect (issue #3025).
+if $PATHS_ONLY; then
+    _paths_output=$(get_feature_paths --no-persist) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+else
+    _paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+fi
 eval "$_paths_output"
 unset _paths_output
 

scripts/bash/common.sh

@@ -152,6 +152,15 @@ _persist_feature_json() {
 }
 
 get_feature_paths() {
+    # Read-only callers (e.g. check-prerequisites.sh --paths-only) pass
+    # --no-persist so pure path resolution never writes .specify/feature.json,
+    # which would dirty the working tree or overwrite a pinned value (issue #3025).
+    local no_persist=false
+    if [[ "${1:-}" == "--no-persist" ]]; then
+        no_persist=true
+        shift
+    fi
+
     # Split decl/assignment so a SPECIFY_INIT_DIR validation failure in
     # get_repo_root propagates as a hard error instead of being masked by `local`.
     local repo_root
@@ -168,8 +177,11 @@ get_feature_paths() {
         feature_dir="$SPECIFY_FEATURE_DIRECTORY"
         # Normalize relative paths to absolute under repo root
         [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
-        # Persist to feature.json so future sessions without the env var still work
-        _persist_feature_json "$repo_root" "$SPECIFY_FEATURE_DIRECTORY"
+        # Persist to feature.json so future sessions without the env var still
+        # work — unless the caller opted out for read-only resolution (#3025).
+        if [[ "$no_persist" != true ]]; then
+            _persist_feature_json "$repo_root" "$SPECIFY_FEATURE_DIRECTORY"
+        fi
     elif [[ -f "$repo_root/.specify/feature.json" ]]; then
         local _fd
         _fd=$(read_feature_json_feature_directory "$repo_root")

scripts/bash/create-new-feature.sh

@@ -152,7 +152,7 @@ generate_branch_name() {
         if ! echo "$word" | grep -qiE "$stop_words"; then
             if [ ${#word} -ge 3 ]; then
                 meaningful_words+=("$word")
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
+            elif printf '%s' "$description" | grep -qw -- "$(printf '%s' "$word" | tr '[:lower:]' '[:upper:]')"; then
                 # Keep short words if they appear as uppercase in original (likely acronyms)
                 meaningful_words+=("$word")
             fi

scripts/powershell/check-prerequisites.ps1

@@ -56,8 +56,14 @@ EXAMPLES:
 # Source common functions
 . "$PSScriptRoot/common.ps1"
 
-# Get feature paths
-$paths = Get-FeaturePathsEnv
+# Get feature paths.
+# In -PathsOnly mode this is pure resolution, so pass -NoPersist to opt out of
+# the feature.json write side effect (issue #3025).
+if ($PathsOnly) {
+    $paths = Get-FeaturePathsEnv -NoPersist
+} else {
+    $paths = Get-FeaturePathsEnv
+}
 
 # If paths-only mode, output paths and exit (no validation)
 if ($PathsOnly) {

scripts/powershell/common.ps1

@@ -143,6 +143,13 @@ function Save-FeatureJson {
 }
 
 function Get-FeaturePathsEnv {
+    # Read-only callers (e.g. check-prerequisites.ps1 -PathsOnly) pass -NoPersist
+    # so pure path resolution never writes .specify/feature.json, which would
+    # dirty the working tree or overwrite a pinned value (issue #3025).
+    param(
+        [switch]$NoPersist
+    )
+
     $repoRoot = Get-RepoRoot
     $currentBranch = Get-CurrentBranch
 
@@ -157,8 +164,11 @@ function Get-FeaturePathsEnv {
         if (-not [System.IO.Path]::IsPathRooted($featureDir)) {
             $featureDir = Join-Path $repoRoot $featureDir
         }
-        # Persist to feature.json so future sessions without the env var still work
-        Save-FeatureJson -RepoRoot $repoRoot -FeatureDirectory $env:SPECIFY_FEATURE_DIRECTORY
+        # Persist to feature.json so future sessions without the env var still
+        # work - unless the caller opted out for read-only resolution (#3025).
+        if (-not $NoPersist) {
+            Save-FeatureJson -RepoRoot $repoRoot -FeatureDirectory $env:SPECIFY_FEATURE_DIRECTORY
+        }
     } elseif (Test-Path $featureJson) {
         $featureJsonRaw = Get-Content -LiteralPath $featureJson -Raw
         try {

scripts/powershell/setup-plan.ps1

@@ -48,7 +48,14 @@ if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
             Write-Output "Copied plan template to $($paths.IMPL_PLAN)"
         }
     } else {
-        Write-Warning "Plan template not found"
+        # Match the bash twin's wording and stream routing (stderr in -Json so
+        # stdout stays pure JSON, stdout otherwise), consistent with the sibling
+        # "Copied plan template" message above.
+        if ($Json) {
+            [Console]::Error.WriteLine("Warning: Plan template not found")
+        } else {
+            Write-Output "Warning: Plan template not found"
+        }
         # Create a basic plan file if template doesn't exist
         New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
     }

src/specify_cli/_console.py

@@ -34,6 +34,10 @@ TAGLINE = "GitHub Spec Kit - Spec-Driven Development Toolkit"
 
 console = Console(highlight=False)
 
+# Stderr-bound console for error/diagnostic output, so human-facing messages
+# never contaminate stdout (which carries machine-readable ``--json`` payloads).
+err_console = Console(stderr=True, highlight=False)
+
 class StepTracker:
     """Track and render hierarchical steps without emojis, similar to Claude Code tree output.
     Supports live auto-refresh via an attached refresh callback.

src/specify_cli/commands/bundle/__init__.py

@@ -13,7 +13,7 @@ from pathlib import Path
 
 import typer
 
-from ..._console import console
+from ..._console import console, err_console
 from ...bundler import BundlerError
 from ...bundler.lib.project import (
     active_integration,
@@ -41,7 +41,9 @@ bundle_app.add_typer(bundle_catalog_app, name="catalog")
 
 def _fail(message: str) -> None:
     """Print an actionable error to stderr and exit non-zero."""
-    console.print(f"[red]Error:[/red] {message}", style=None)
+    # Use the stderr console so the error never lands on stdout, which under
+    # ``--json`` carries the machine-readable payload and must stay parseable.
+    err_console.print(f"[red]Error:[/red] {message}", style=None)
     raise typer.Exit(code=1)
 
 

src/specify_cli/integrations/goose/__init__.py

@@ -1,4 +1,4 @@
-"""Goose integration — Block's open source AI agent."""
+"""Goose integration — open source AI agent (Agentic AI Foundation)."""
 
 from ..base import YamlIntegration
 
@@ -9,7 +9,7 @@ class GooseIntegration(YamlIntegration):
         "name": "Goose",
         "folder": ".goose/",
         "commands_subdir": "recipes",
-        "install_url": "https://block.github.io/goose/docs/getting-started/installation",
+        "install_url": "https://goose-docs.ai/docs/getting-started/installation",
         "requires_cli": True,
     }
     registrar_config = {

tests/contract/test_bundle_cli.py

@@ -62,6 +62,21 @@ def test_commands_outside_project_fail_with_guidance(tmp_path: Path, monkeypatch
     assert "Spec Kit project" in result.output
 
 
+def test_fail_writes_error_to_stderr_not_stdout(capsys):
+    """_fail must write to stderr, not stdout: every bundle command routes errors
+    through it, and under --json the error would otherwise corrupt the JSON payload
+    that consumers read from stdout."""
+    import typer
+
+    from specify_cli.commands.bundle import _fail
+
+    with pytest.raises(typer.Exit):
+        _fail("something broke")
+    captured = capsys.readouterr()
+    assert "something broke" in captured.err
+    assert "something broke" not in captured.out
+
+
 def test_search_works_without_a_project(tmp_path: Path, monkeypatch):
     # Discovery commands fall back to the built-in/user catalog stack and must
     # not require a Spec Kit project (matches README/quickstart examples).

tests/extensions/git/test_git_extension.py

@@ -233,6 +233,10 @@ class TestInitializeRepoBash:
         result = _run_bash("initialize-repo.sh", project)
         assert result.returncode == 0, result.stderr
 
+        # Success marker is the full ASCII "[OK] ..." line (matching the PowerShell
+        # twin and the sibling auto-commit scripts), not a Unicode checkmark.
+        assert "[OK] Git repository initialized" in result.stderr, result.stderr
+
         # Verify git repo exists
         assert (project / ".git").exists()
 

tests/test_check_prerequisites_paths_only.py

@@ -163,6 +163,66 @@ def test_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
     assert result.stdout.strip() == ""
 
 
+@requires_bash
+def test_paths_only_does_not_persist_feature_json(prereq_repo: Path) -> None:
+    """--paths-only must not rewrite feature.json even when the env override
+    differs from the pinned value (#3025).
+
+    Path resolution is read-only, so it must never dirty the working tree or
+    overwrite the persisted feature directory.
+    """
+    pinned = "specs/001-my-feature"
+    (prereq_repo / "specs" / "001-my-feature").mkdir(parents=True, exist_ok=True)
+    (prereq_repo / "specs" / "002-other").mkdir(parents=True, exist_ok=True)
+    _write_feature_json(prereq_repo, pinned)
+    fj = prereq_repo / ".specify" / "feature.json"
+    before = fj.read_text(encoding="utf-8")
+
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    env = _clean_env()
+    env["SPECIFY_FEATURE_DIRECTORY"] = "specs/002-other"
+    result = subprocess.run(
+        ["bash", str(script), "--json", "--paths-only"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env,
+    )
+    assert result.returncode == 0, result.stderr
+    # The override is honored in the output...
+    data = json.loads(result.stdout)
+    assert "002-other" in data["FEATURE_DIR"]
+    # ...but the pinned file on disk is untouched.
+    assert fj.read_text(encoding="utf-8") == before
+
+
+@requires_bash
+def test_normal_mode_still_persists_feature_json(prereq_repo: Path) -> None:
+    """Without --paths-only, the env override is still persisted to feature.json,
+    so the --no-persist opt-out does not regress normal write behavior (#3025)."""
+    (prereq_repo / "specs" / "001-my-feature").mkdir(parents=True, exist_ok=True)
+    feat = prereq_repo / "specs" / "002-other"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "plan.md").write_text("# plan\n", encoding="utf-8")
+    _write_feature_json(prereq_repo, "specs/001-my-feature")
+    fj = prereq_repo / ".specify" / "feature.json"
+
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    env = _clean_env()
+    env["SPECIFY_FEATURE_DIRECTORY"] = "specs/002-other"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env,
+    )
+    assert result.returncode == 0, result.stderr
+    assert json.loads(fj.read_text(encoding="utf-8"))["feature_directory"] == "specs/002-other"
+
+
 # ── PowerShell tests ──────────────────────────────────────────────────────
 
 
@@ -283,3 +343,64 @@ def test_ps_missing_tasks_error_goes_to_stderr(prereq_repo: Path) -> None:
     assert "tasks.md not found" in result.stderr
     assert "tasks.md not found" not in result.stdout
     assert result.stdout.strip() == ""
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")
+def test_ps_paths_only_does_not_persist_feature_json(prereq_repo: Path) -> None:
+    """-PathsOnly must not rewrite feature.json even when the env override
+    differs from the pinned value (#3025)."""
+    pinned = "specs/001-my-feature"
+    (prereq_repo / "specs" / "001-my-feature").mkdir(parents=True, exist_ok=True)
+    (prereq_repo / "specs" / "002-other").mkdir(parents=True, exist_ok=True)
+    _write_feature_json(prereq_repo, pinned)
+    fj = prereq_repo / ".specify" / "feature.json"
+    before = fj.read_text(encoding="utf-8")
+
+    script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _WINDOWS_POWERSHELL
+    env = _clean_env()
+    env["SPECIFY_FEATURE_DIRECTORY"] = "specs/002-other"
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json", "-PathsOnly"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env,
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "002-other" in data["FEATURE_DIR"]
+    assert fj.read_text(encoding="utf-8") == before
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")
+def test_ps_normal_mode_still_persists_feature_json(prereq_repo: Path) -> None:
+    """Without -PathsOnly, the env override is still persisted to feature.json,
+    so the -NoPersist opt-out does not regress normal write behavior (#3025).
+
+    Symmetric to the bash test_normal_mode_still_persists_feature_json guard:
+    asserts the default path still persists and that -NoPersist is not passed
+    unconditionally.
+    """
+    (prereq_repo / "specs" / "001-my-feature").mkdir(parents=True, exist_ok=True)
+    feat = prereq_repo / "specs" / "002-other"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "plan.md").write_text("# plan\n", encoding="utf-8")
+    _write_feature_json(prereq_repo, "specs/001-my-feature")
+    fj = prereq_repo / ".specify" / "feature.json"
+
+    script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _WINDOWS_POWERSHELL
+    env = _clean_env()
+    env["SPECIFY_FEATURE_DIRECTORY"] = "specs/002-other"
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env,
+    )
+    assert result.returncode == 0, result.stderr
+    assert json.loads(fj.read_text(encoding="utf-8"))["feature_directory"] == "specs/002-other"

tests/test_setup_plan_no_overwrite.py

@@ -246,3 +246,27 @@ def test_ps_setup_plan_copied_message_on_stderr_in_json_mode(plan_repo: Path) ->
     data = json.loads(result.stdout)
     assert "IMPL_PLAN" in data
     assert "Copied plan template" in result.stderr
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")
+def test_ps_setup_plan_template_not_found_warning_matches_bash(plan_repo: Path) -> None:
+    """When no plan template resolves, -Json mode must emit 'Warning: Plan template
+    not found' on stderr (matching the bash twin's wording and stream routing) while
+    keeping stdout pure JSON. Before the fix the PowerShell script used Write-Warning,
+    producing a different 'WARNING:' prefix on the warning stream instead."""
+    # Remove the template the fixture installs so resolution finds nothing.
+    (plan_repo / ".specify" / "templates" / "plan-template.md").unlink()
+    script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
+    exe = "pwsh" if HAS_PWSH else _WINDOWS_POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "IMPL_PLAN" in data
+    assert "Warning: Plan template not found" in result.stderr