fix(integrations): rename env var to SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS

Renames the env-var hook prefix from `SPECIFY_INTEGRATION_*` to
`SPECKIT_INTEGRATION_*` to match the established codebase
convention for integration-subsystem env vars
(`SPECKIT_INTEGRATION_CATALOG_URL` in `integrations/catalog.py`,
`SPECKIT_COPILOT_ALLOW_ALL_TOOLS` in `integrations/copilot/__init__.py`).

The `SPECIFY_*` prefix is reserved for user-facing
feature-resolution variables (`SPECIFY_FEATURE`,
`SPECIFY_FEATURE_DIRECTORY`); reusing it for integration-subsystem
scoping would introduce a second integration namespace under a
different prefix, confusing operators who already set
`SPECKIT_INTEGRATION_CATALOG_URL`.

Also reverts the unrelated defensive `arg_placeholder` /
`registrar_config is None` guard in
`CopilotIntegration.setup_skills_mode` — it was a drive-by pyright
cleanup mixed into this PR. Every concrete integration sets
`registrar_config` so the guard never fires in practice; the
typing issue belongs in a focused follow-up rather than this
env-var-hook PR.

Updates everywhere the old prefix appeared:
- `IntegrationBase._apply_extra_args_env_var` helper + docstring
- `CopilotIntegration.dispatch_command` inline comment
- All `monkeypatch.setenv(...)` calls in `tests/integrations/test_extra_args.py`
- The autouse fixture scope filter
- Test module docstring

Full suite: 3011 passed, 40 skipped, no regressions.

Addresses Copilot review feedback on #2596.

Author: doquanghuy

src/specify_cli/integrations/base.py

@@ -141,16 +141,16 @@ def build_exec_args(
         return None
 
     def _apply_extra_args_env_var(self, args: list[str]) -> None:
-        """Append `SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS` env-var value to *args*.
+        """Append `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` env-var value to *args*.
 
         Operators can inject extra CLI flags into the spawned agent
         subprocess by setting an env var named for the integration key,
-        e.g. `SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions"`.
+        e.g. `SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions"`.
         The `INTEGRATION` segment scopes the variable to this subsystem
         so it does not collide with other Spec Kit env-var namespaces.
         Hyphens in the integration key are replaced with underscores
         and the key is uppercased
-        (e.g. `kiro-cli` → `SPECIFY_INTEGRATION_KIRO_CLI_EXTRA_ARGS`).
+        (e.g. `kiro-cli` → `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`).
 
         Useful in CI / non-interactive contexts where the spawned agent
         needs flags that change its prompt-handling behaviour.
@@ -161,7 +161,7 @@ def _apply_extra_args_env_var(self, args: list[str]) -> None:
         See issue #2595.
         """
         env_name = (
-            f"SPECIFY_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS"
+            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS"
         )
         extra = os.environ.get(env_name, "").strip()
         if not extra:

src/specify_cli/integrations/copilot/__init__.py

@@ -218,7 +218,7 @@ def dispatch_command(
             prompt = args or ""
 
         cli_args = [_copilot_executable(), "-p", prompt]
-        # Honour SPECIFY_INTEGRATION_COPILOT_EXTRA_ARGS for real workflow
+        # Honour SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS for real workflow
         # runs.  `dispatch_command` builds cli_args inline rather than
         # going through `build_exec_args`, so the hook must be invoked
         # here too — otherwise the env var is silently ignored.
@@ -374,11 +374,7 @@ def _setup_default(
         created: list[Path] = []
 
         script_type = opts.get("script_type", "sh")
-        arg_placeholder = (
-            self.registrar_config.get("args", "$ARGUMENTS")
-            if self.registrar_config
-            else "$ARGUMENTS"
-        )
+        arg_placeholder = self.registrar_config.get("args", "$ARGUMENTS")
 
         # 1. Process and write command files as .agent.md
         for src_file in templates:

tests/integrations/test_extra_args.py

@@ -1,4 +1,4 @@
-"""Tests for the per-integration `SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS` env-var hook.
+"""Tests for the per-integration `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` env-var hook.
 
 The hook is implemented in `IntegrationBase._apply_extra_args_env_var`
 and wired into every concrete `build_exec_args` —
@@ -128,10 +128,10 @@ class _TomlAgentStub(TomlIntegration):
 
 @pytest.fixture(autouse=True)
 def _clean_extra_args_env(monkeypatch):
-    """Strip any leaked SPECIFY_INTEGRATION_*_EXTRA_ARGS from the test
+    """Strip any leaked SPECKIT_INTEGRATION_*_EXTRA_ARGS from the test
     env so a developer's shell setting doesn't pollute results."""
     for key in list(os.environ):
-        if key.startswith("SPECIFY_INTEGRATION_") and key.endswith(
+        if key.startswith("SPECKIT_INTEGRATION_") and key.endswith(
             "_EXTRA_ARGS"
         ):
             monkeypatch.delenv(key, raising=False)
@@ -151,7 +151,7 @@ def test_env_var_set_flag_inserted_before_model_and_output_format(
     monkeypatch,
 ):
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
     )
     args = _ClaudeStub().build_exec_args("hello prompt", model="sonnet")
     assert args == [
@@ -168,7 +168,7 @@ def test_env_var_set_flag_inserted_before_model_and_output_format(
 
 def test_env_var_multi_token_parsed_via_shlex(monkeypatch):
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS",
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
         "--dangerously-skip-permissions --max-turns 3",
     )
     args = _ClaudeStub().build_exec_args("p")
@@ -189,36 +189,36 @@ def test_malformed_quoting_raises_actionable_value_error(monkeypatch):
     error naming the offending env var and showing the invalid value,
     rather than crashing workflow dispatch with a bare shlex traceback."""
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS",
+        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
         '--flag "unterminated',
     )
     with pytest.raises(ValueError) as excinfo:
         _ClaudeStub().build_exec_args("p")
     msg = str(excinfo.value)
-    assert "SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS" in msg
+    assert "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS" in msg
     assert "--flag \"unterminated" in msg
 
 
 def test_env_var_empty_or_whitespace_is_noop(monkeypatch):
     """An env var set to '' or '   ' is treated as unset."""
-    monkeypatch.setenv("SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS", "   ")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "   ")
     args = _ClaudeStub().build_exec_args("p")
     assert args == ["claude", "-p", "p", "--output-format", "json"]
 
 
 def test_other_integration_env_var_ignored(monkeypatch):
-    """`SPECIFY_INTEGRATION_GEMINI_EXTRA_ARGS` set must NOT leak into
+    """`SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS` set must NOT leak into
     Claude's argv (per-integration scoping)."""
-    monkeypatch.setenv("SPECIFY_INTEGRATION_GEMINI_EXTRA_ARGS", "--gemini-only-flag")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS", "--gemini-only-flag")
     args = _ClaudeStub().build_exec_args("p")
     assert args == ["claude", "-p", "p", "--output-format", "json"]
 
 
 def test_key_normalization_hyphen_to_underscore_uppercase(monkeypatch):
-    """`kiro-cli` key looks up `SPECIFY_INTEGRATION_KIRO_CLI_EXTRA_ARGS`
+    """`kiro-cli` key looks up `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`
     (hyphens replaced with underscores, then uppercased)."""
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_KIRO_CLI_EXTRA_ARGS", "--some-kiro-flag"
+        "SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS", "--some-kiro-flag"
     )
     args = _KiroCliStub().build_exec_args("p")
     assert args == [
@@ -234,7 +234,7 @@ def test_key_normalization_hyphen_to_underscore_uppercase(monkeypatch):
 def test_requires_cli_false_returns_none(monkeypatch):
     """`requires_cli: False` short-circuits to None — the env-var
     hook is never reached and no argv is built."""
-    monkeypatch.setenv("SPECIFY_INTEGRATION_NO_CLI_EXTRA_ARGS", "--should-not-appear")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_NO_CLI_EXTRA_ARGS", "--should-not-appear")
     assert _NoCliStub().build_exec_args("p") is None
 
 
@@ -254,7 +254,7 @@ def test_markdown_integration_base_honours_extra_args(monkeypatch):
     `build_exec_args` — must honour the env var via the base
     implementation. Covers the most common integration pattern."""
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_MD_AGENT_EXTRA_ARGS", "--debug --max-tokens 100"
+        "SPECKIT_INTEGRATION_MD_AGENT_EXTRA_ARGS", "--debug --max-tokens 100"
     )
     args = _MarkdownAgentStub().build_exec_args("p")
     assert args == [
@@ -274,7 +274,7 @@ def test_toml_integration_base_honours_extra_args(monkeypatch):
     `build_exec_args` — must honour the env var via the base
     implementation. Covers Gemini/Tabnine-style integrations."""
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_TOML_AGENT_EXTRA_ARGS", "--yolo"
+        "SPECKIT_INTEGRATION_TOML_AGENT_EXTRA_ARGS", "--yolo"
     )
     args = _TomlAgentStub().build_exec_args("p", model="gemini-pro")
     # TomlIntegration uses `-m` for model (vs Markdown's `--model`).
@@ -304,7 +304,7 @@ def test_toml_integration_base_honours_extra_args(monkeypatch):
 def test_codex_integration_honours_extra_args(monkeypatch):
     from specify_cli.integrations.codex import CodexIntegration
 
-    monkeypatch.setenv("SPECIFY_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
     args = CodexIntegration().build_exec_args("p", model="gpt-5")
     assert args == [
         "codex",
@@ -321,15 +321,15 @@ def test_codex_integration_honours_extra_args(monkeypatch):
 def test_devin_integration_honours_extra_args(monkeypatch):
     from specify_cli.integrations.devin import DevinIntegration
 
-    monkeypatch.setenv("SPECIFY_INTEGRATION_DEVIN_EXTRA_ARGS", "--no-confirm")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_DEVIN_EXTRA_ARGS", "--no-confirm")
     args = DevinIntegration().build_exec_args("p")
     assert args == ["devin", "-p", "p", "--no-confirm"]
 
 
 def test_opencode_integration_honours_extra_args(monkeypatch):
     from specify_cli.integrations.opencode import OpencodeIntegration
 
-    monkeypatch.setenv("SPECIFY_INTEGRATION_OPENCODE_EXTRA_ARGS", "--quiet")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--quiet")
     args = OpencodeIntegration().build_exec_args("p")
     assert args == [
         "opencode",
@@ -349,13 +349,13 @@ def test_opencode_extra_args_cannot_clobber_prompt_derived_command(
     repeated-flag CLI semantics (last value typically takes precedence).
 
     Locks against the regression where an operator setting
-    ``SPECIFY_INTEGRATION_OPENCODE_EXTRA_ARGS="--command malicious"`` could redirect
+    ``SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS="--command malicious"`` could redirect
     a slash-prefixed prompt to a different command.
     """
     from specify_cli.integrations.opencode import OpencodeIntegration
 
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_OPENCODE_EXTRA_ARGS", "--command operator-override"
+        "SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--command operator-override"
     )
     args = OpencodeIntegration().build_exec_args("/speckit body text")
     # Prompt-derived "--command speckit" appears AFTER the
@@ -383,7 +383,7 @@ def test_copilot_integration_honours_extra_args(monkeypatch):
     # Disable --yolo so the argv shape stays deterministic.
     monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
+        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
     )
     args = CopilotIntegration().build_exec_args("p")
     # `_copilot_executable()` returns "copilot.cmd" on Windows and
@@ -431,7 +431,7 @@ class _Result:
 
 def test_copilot_dispatch_command_includes_extra_args(monkeypatch):
     """Locks the bypass fix: `CopilotIntegration.dispatch_command`
-    must honour `SPECIFY_INTEGRATION_COPILOT_EXTRA_ARGS`, not just `build_exec_args`.
+    must honour `SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS`, not just `build_exec_args`.
     """
     import subprocess
 
@@ -441,7 +441,7 @@ def test_copilot_dispatch_command_includes_extra_args(monkeypatch):
     monkeypatch.setattr(subprocess, "run", capture)
     monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
     monkeypatch.setenv(
-        "SPECIFY_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
+        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
     )
 
     CopilotIntegration().dispatch_command(
@@ -469,7 +469,7 @@ def test_codex_dispatch_command_includes_extra_args(monkeypatch):
 
     capture = _RunCapture()
     monkeypatch.setattr(subprocess, "run", capture)
-    monkeypatch.setenv("SPECIFY_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
+    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
 
     CodexIntegration().dispatch_command(
         "speckit.plan", args="body", stream=False