refactor(scripts): rename SPECIFY_NO_PERSIST to SPECIFY_FEATURE_NO_PERSIST

Per review feedback on #4129, align the env var name with SPECIFY_FEATURE_DIRECTORY
across bash/powershell/python.

Author: chelsealong

docs/reference/core.md

@@ -54,7 +54,7 @@ specify init my-project --integration copilot --preset compliance
 | `SPECIFY_INIT_DIR` | Target a member project from outside its directory (e.g. a monorepo root) without `cd`, for non-interactive / CI use. Set it to the **project root** — the directory *containing* `.specify/` (relative paths resolve against the current directory). The path must exist and contain `.specify/`, otherwise the command errors and does **not** fall back to the current directory. Resolved once in the core root helper (`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell), so it is honored by the core feature scripts (`/speckit.plan`, `/speckit.tasks`, …) and the Git extension's feature-branch creation, which inherit it. The `specify` CLI applies the **same** validation rules to every project-scoped subcommand (`specify integration …`, `specify extension …`, `specify workflow …`, `specify preset …`, and the rest that operate on a `.specify/` project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the `specify` CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands). |
 | `SPECIFY_FEATURE_DIRECTORY` | Override the active feature directory *within* the resolved project (takes precedence over `.specify/feature.json`). Relative paths resolve under the project root. Combine with `SPECIFY_INIT_DIR` to pick both the project and the feature non-interactively. |
 | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. Must be set in the context of the agent prior to using `/speckit.plan` or follow-up commands. |
-| `SPECIFY_NO_PERSIST` | Set to `1` or `true` to stop every core script from writing `.specify/feature.json`, even when it would otherwise persist `SPECIFY_FEATURE_DIRECTORY` on read. Useful when multiple agents run concurrently against the same checkout, each with its own `SPECIFY_FEATURE_DIRECTORY`: without it, each invocation's persist step can overwrite another agent's pinned feature directory. |
+| `SPECIFY_FEATURE_NO_PERSIST` | Set to `1` or `true` to stop every core script from writing `.specify/feature.json`, even when it would otherwise persist `SPECIFY_FEATURE_DIRECTORY` on read. Useful when multiple agents run concurrently against the same checkout, each with its own `SPECIFY_FEATURE_DIRECTORY`: without it, each invocation's persist step can overwrite another agent's pinned feature directory. |
 
 > **Two resolution axes.** `SPECIFY_INIT_DIR` selects the **project** (which directory contains `.specify/`); `SPECIFY_FEATURE_DIRECTORY` / `.specify/feature.json` select the **feature** within that project. They are independent — project first, then feature.
 

scripts/bash/common.sh

@@ -169,11 +169,11 @@ get_feature_paths() {
         no_persist=true
         shift
     fi
-    # SPECIFY_NO_PERSIST is the environment-level equivalent of --no-persist,
+    # SPECIFY_FEATURE_NO_PERSIST is the environment-level equivalent of --no-persist,
     # letting an orchestrator (multi-agent runner, CI matrix) guarantee that no
     # script invocation in the process tree writes .specify/feature.json, even
     # scripts that don't pass --no-persist themselves (#4128).
-    if [[ "${SPECIFY_NO_PERSIST:-}" == "1" || "${SPECIFY_NO_PERSIST:-}" == "true" ]]; then
+    if [[ "${SPECIFY_FEATURE_NO_PERSIST:-}" == "1" || "${SPECIFY_FEATURE_NO_PERSIST:-}" == "true" ]]; then
         no_persist=true
     fi
 

scripts/bash/create-new-feature.sh

@@ -367,8 +367,8 @@ if [ "$DRY_RUN" != true ]; then
     fi
 
     # Persist to .specify/feature.json so downstream commands can find the
-    # feature, unless the orchestrator opted out via SPECIFY_NO_PERSIST (#4129).
-    if [[ "${SPECIFY_NO_PERSIST:-}" != "1" && "${SPECIFY_NO_PERSIST:-}" != "true" ]]; then
+    # feature, unless the orchestrator opted out via SPECIFY_FEATURE_NO_PERSIST (#4129).
+    if [[ "${SPECIFY_FEATURE_NO_PERSIST:-}" != "1" && "${SPECIFY_FEATURE_NO_PERSIST:-}" != "true" ]]; then
         _persist_feature_json "$REPO_ROOT" "$FEATURE_DIR"
     fi
 

scripts/powershell/common.ps1

@@ -166,11 +166,11 @@ function Get-FeaturePathsEnv {
         [switch]$ReturnNullOnError
     )
 
-    # SPECIFY_NO_PERSIST is the environment-level equivalent of -NoPersist,
+    # SPECIFY_FEATURE_NO_PERSIST is the environment-level equivalent of -NoPersist,
     # letting an orchestrator (multi-agent runner, CI matrix) guarantee that no
     # script invocation in the process tree writes .specify/feature.json, even
     # scripts that don't pass -NoPersist themselves (#4128).
-    $noPersist = [bool]$NoPersist -or $env:SPECIFY_NO_PERSIST -eq '1' -or $env:SPECIFY_NO_PERSIST -eq 'true'
+    $noPersist = [bool]$NoPersist -or $env:SPECIFY_FEATURE_NO_PERSIST -eq '1' -or $env:SPECIFY_FEATURE_NO_PERSIST -eq 'true'
 
     $repoRoot = Get-RepoRoot -ReturnNullOnError:$ReturnNullOnError
     if (-not $repoRoot) { return $null }

scripts/powershell/create-new-feature.ps1

@@ -284,8 +284,8 @@ if (-not $DryRun) {
     }
 
     # Persist to .specify/feature.json so downstream commands can find the
-    # feature, unless the orchestrator opted out via SPECIFY_NO_PERSIST (#4129).
-    if ($env:SPECIFY_NO_PERSIST -ne '1' -and $env:SPECIFY_NO_PERSIST -ne 'true') {
+    # feature, unless the orchestrator opted out via SPECIFY_FEATURE_NO_PERSIST (#4129).
+    if ($env:SPECIFY_FEATURE_NO_PERSIST -ne '1' -and $env:SPECIFY_FEATURE_NO_PERSIST -ne 'true') {
         Save-FeatureJson -RepoRoot $repoRoot -FeatureDirectory $featureDir
     }
 

scripts/python/common.py

@@ -139,11 +139,11 @@ def get_feature_paths(
     repo_root = get_repo_root(script_file)
     current_branch = get_current_branch()
 
-    # SPECIFY_NO_PERSIST is the environment-level equivalent of no_persist=True,
+    # SPECIFY_FEATURE_NO_PERSIST is the environment-level equivalent of no_persist=True,
     # letting an orchestrator (multi-agent runner, CI matrix) guarantee that no
     # script invocation in the process tree writes .specify/feature.json, even
     # scripts that don't pass no_persist themselves (#4128).
-    no_persist = no_persist or os.environ.get("SPECIFY_NO_PERSIST", "") in ("1", "true")
+    no_persist = no_persist or os.environ.get("SPECIFY_FEATURE_NO_PERSIST", "") in ("1", "true")
 
     feature_dir_raw = os.environ.get("SPECIFY_FEATURE_DIRECTORY", "")
     if feature_dir_raw:

scripts/python/create_new_feature.py

@@ -408,8 +408,8 @@ def main(argv: list[str] | None = None) -> int:
                 spec_file.touch()
 
         # Persist to .specify/feature.json so downstream commands can find the
-        # feature, unless the orchestrator opted out via SPECIFY_NO_PERSIST (#4129).
-        if os.environ.get("SPECIFY_NO_PERSIST", "") not in ("1", "true"):
+        # feature, unless the orchestrator opted out via SPECIFY_FEATURE_NO_PERSIST (#4129).
+        if os.environ.get("SPECIFY_FEATURE_NO_PERSIST", "") not in ("1", "true"):
             persist_feature_json(repo_root, f"specs/{branch_name}")
 
         # Inform the user how to set feature state in their own shell.

tests/test_specify_no_persist.py

@@ -1,10 +1,10 @@
-"""Tests for SPECIFY_NO_PERSIST, the env-level equivalent of --no-persist (#4128).
+"""Tests for SPECIFY_FEATURE_NO_PERSIST, the env-level equivalent of --no-persist (#4128).
 
 Scripts like setup-plan/setup-tasks call get_feature_paths() without
 --no-persist, so every invocation with SPECIFY_FEATURE_DIRECTORY set
 overwrites .specify/feature.json. In multi-agent setups where several
 processes each set their own SPECIFY_FEATURE_DIRECTORY, this creates a
-write-write race on the shared file. SPECIFY_NO_PERSIST lets an orchestrator
+write-write race on the shared file. SPECIFY_FEATURE_NO_PERSIST lets an orchestrator
 suppress that write across every script invocation without having to patch
 each call site.
 """
@@ -68,7 +68,7 @@ def test_bash_specify_no_persist_suppresses_write(repo: Path) -> None:
     (repo / "specs" / "001-a").mkdir(parents=True)
     env = clean_env()
     env["SPECIFY_FEATURE_DIRECTORY"] = "specs/001-a"
-    env["SPECIFY_NO_PERSIST"] = "1"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "1"
     result = run(bash_cmd(repo, SCRIPT, "--json"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None
@@ -77,7 +77,7 @@ def test_bash_specify_no_persist_suppresses_write(repo: Path) -> None:
 @requires_bash
 def test_bash_specify_no_persist_does_not_clobber_existing_pin(repo: Path) -> None:
     """A second agent's SPECIFY_FEATURE_DIRECTORY must not overwrite the
-    first agent's persisted feature.json when SPECIFY_NO_PERSIST is set."""
+    first agent's persisted feature.json when SPECIFY_FEATURE_NO_PERSIST is set."""
     (repo / "specs" / "001-a").mkdir(parents=True)
     (repo / "specs" / "002-b").mkdir(parents=True)
     env = clean_env()
@@ -87,7 +87,7 @@ def test_bash_specify_no_persist_does_not_clobber_existing_pin(repo: Path) -> No
     assert _feature_json(repo) == {"feature_directory": "specs/001-a"}
 
     env["SPECIFY_FEATURE_DIRECTORY"] = "specs/002-b"
-    env["SPECIFY_NO_PERSIST"] = "1"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "1"
     result = run(bash_cmd(repo, SCRIPT, "--json"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) == {"feature_directory": "specs/001-a"}
@@ -98,7 +98,7 @@ def test_ps_specify_no_persist_suppresses_write(repo: Path) -> None:
     (repo / "specs" / "001-a").mkdir(parents=True)
     env = clean_env()
     env["SPECIFY_FEATURE_DIRECTORY"] = "specs/001-a"
-    env["SPECIFY_NO_PERSIST"] = "true"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "true"
     result = run(ps_cmd(repo, SCRIPT, "-Json"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None
@@ -108,14 +108,14 @@ def test_py_specify_no_persist_suppresses_write(repo: Path) -> None:
     (repo / "specs" / "001-a").mkdir(parents=True)
     env = clean_env()
     env["SPECIFY_FEATURE_DIRECTORY"] = "specs/001-a"
-    env["SPECIFY_NO_PERSIST"] = "1"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "1"
     result = run(py_cmd(repo, SCRIPT, "--json"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None
 
 
 # create-new-feature writes .specify/feature.json directly (not via
-# get_feature_paths()), so it must honor SPECIFY_NO_PERSIST separately.
+# get_feature_paths()), so it must honor SPECIFY_FEATURE_NO_PERSIST separately.
 
 CREATE_SCRIPT = "create-new-feature"
 SPEC_TEMPLATE_BODY = "# Spec Template\n\nBody.\n"
@@ -134,7 +134,7 @@ def _create_feature_repo(tmp_path: Path, name: str = "proj") -> Path:
 def test_bash_create_new_feature_no_persist_suppresses_write(tmp_path: Path) -> None:
     repo = _create_feature_repo(tmp_path)
     env = clean_env()
-    env["SPECIFY_NO_PERSIST"] = "1"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "1"
     result = run(bash_cmd(repo, CREATE_SCRIPT, "--json", "x"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None
@@ -144,7 +144,7 @@ def test_bash_create_new_feature_no_persist_suppresses_write(tmp_path: Path) ->
 def test_ps_create_new_feature_no_persist_suppresses_write(tmp_path: Path) -> None:
     repo = _create_feature_repo(tmp_path)
     env = clean_env()
-    env["SPECIFY_NO_PERSIST"] = "true"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "true"
     result = run(ps_cmd(repo, CREATE_SCRIPT, "-Json", "x"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None
@@ -153,7 +153,7 @@ def test_ps_create_new_feature_no_persist_suppresses_write(tmp_path: Path) -> No
 def test_py_create_new_feature_no_persist_suppresses_write(tmp_path: Path) -> None:
     repo = _create_feature_repo(tmp_path)
     env = clean_env()
-    env["SPECIFY_NO_PERSIST"] = "1"
+    env["SPECIFY_FEATURE_NO_PERSIST"] = "1"
     result = run(py_cmd(repo, CREATE_SCRIPT, "--json", "x"), repo, env)
     assert result.returncode == 0, result.stderr
     assert _feature_json(repo) is None