fix(agent-context): require yaml-capable updater python

Author: AustinZ21

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

@@ -26,18 +26,31 @@ if [[ ! -f "$EXT_CONFIG" ]]; then
   exit 0
 fi
 
-# Locate a suitable Python interpreter (SPECKIT_PYTHON, then python3, then python).
+# Locate a Python 3 interpreter with PyYAML available.
 _python=""
-if [[ -n "${SPECKIT_PYTHON:-}" ]]; then
-  _python="$SPECKIT_PYTHON"
-elif command -v python3 >/dev/null 2>&1; then
-  _python="python3"
-elif command -v python >/dev/null 2>&1 && python --version 2>&1 | grep -q "^Python 3"; then
-  _python="python"
-fi
+_python_candidates=()
+[[ -n "${SPECKIT_PYTHON:-}" ]] && _python_candidates+=("$SPECKIT_PYTHON")
+_python_candidates+=("python3" "python")
+for _candidate in "${_python_candidates[@]}"; do
+  if command -v "$_candidate" >/dev/null 2>&1 \
+    && "$_candidate" - <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml  # noqa: F401
+except ImportError:
+    sys.exit(1)
+sys.exit(0 if sys.version_info[0] == 3 else 1)
+PY
+  then
+    _python="$_candidate"
+    break
+  fi
+done
+unset _candidate _python_candidates
 
-if [[ -z "$_python" ]] || ! "$_python" --version 2>&1 | grep -q "^Python 3"; then
-  echo "agent-context: Python 3 not found on PATH; skipping update." >&2
+if [[ -z "$_python" ]]; then
+  echo "agent-context: Python 3 with PyYAML not found on PATH; skipping update." >&2
+  echo "  To resolve: pip install pyyaml (or install it into the environment used by python3)." >&2
   exit 0
 fi
 _case_insensitive_context_files=0

extensions/agent-context/scripts/powershell/update-agent-context.ps1

@@ -142,9 +142,9 @@ if ($null -eq $Options) {
     $pythonCandidates += @('python3', 'python')
     foreach ($candidate in $pythonCandidates) {
         if (Get-Command $candidate -ErrorAction SilentlyContinue) {
-            # Verify it is Python 3
-            $verOut = & $candidate --version 2>&1
-            if ($verOut -match 'Python 3') {
+            # Verify it is Python 3 with PyYAML available.
+            $null = & $candidate -c "import sys; import yaml; sys.exit(0 if sys.version_info[0] == 3 else 1)" 2>$null
+            if ($LASTEXITCODE -eq 0) {
                 $pythonCmd = $candidate
                 break
             }

tests/extensions/test_extension_agent_context.py

@@ -180,19 +180,34 @@ def _ensure_test_python_on_path(project_root: Path) -> Path:
     return shim_dir
 
 
-def _bundled_script_env(project_root: Path, *, for_bash: bool = False) -> dict[str, str]:
+def _bundled_script_env(
+    project_root: Path,
+    *,
+    for_bash: bool = False,
+    speckit_python: str | None = None,
+) -> dict[str, str]:
     env = os.environ.copy()
     shim_dir = _ensure_test_python_on_path(project_root)
     env["PATH"] = str(shim_dir) + os.pathsep + env.get("PATH", "")
     env["SPECKIT_PYTHON"] = (
-        _bash_posix_path(Path(sys.executable)) if for_bash else sys.executable
+        speckit_python
+        if speckit_python is not None
+        else (_bash_posix_path(Path(sys.executable)) if for_bash else sys.executable)
     )
     return env
 
 
-def _run_bash_agent_context_script(project_root: Path) -> subprocess.CompletedProcess:
+def _run_bash_agent_context_script(
+    project_root: Path,
+    *,
+    speckit_python: str | None = None,
+) -> subprocess.CompletedProcess:
     script = EXT_DIR / "scripts" / "bash" / "update-agent-context.sh"
-    env = _bundled_script_env(project_root, for_bash=True)
+    env = _bundled_script_env(
+        project_root,
+        for_bash=True,
+        speckit_python=speckit_python,
+    )
     if os.name == "nt":
         root = _bash_posix_path(project_root)
         script_path = _bash_posix_path(script)
@@ -242,6 +257,30 @@ def _run_powershell_agent_context_script(project_root: Path) -> subprocess.Compl
     )
 
 
+def _run_powershell_agent_context_script_with_env(
+    project_root: Path,
+    *,
+    speckit_python: str,
+) -> subprocess.CompletedProcess:
+    script = EXT_DIR / "scripts" / "powershell" / "update-agent-context.ps1"
+    env = _bundled_script_env(project_root, speckit_python=speckit_python)
+    return subprocess.run(
+        [
+            POWERSHELL,
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            str(script),
+        ],
+        cwd=project_root,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+
+
 class TestContextMarkerResolution:
     def test_defaults_when_ext_config_missing(self, tmp_path):
         i = _CtxIntegration()
@@ -737,6 +776,25 @@ def test_bash_script_deduplicates_context_files_in_order(self, tmp_path):
         assert output.count("agent-context: updated CLAUDE.md") == 1
         assert "agent-context: updated agents.md" not in output
 
+    @requires_bash
+    def test_bash_script_falls_back_from_invalid_speckit_python(self, tmp_path):
+        project = tmp_path / "project"
+        project.mkdir()
+        _install_agent_context_config(
+            project,
+            context_file="AGENTS.md",
+            context_files=["AGENTS.md"],
+        )
+
+        result = _run_bash_agent_context_script(
+            project,
+            speckit_python="/definitely/missing/python",
+        )
+
+        assert result.returncode == 0, result.stderr + result.stdout
+        assert "agent-context: updated AGENTS.md" in (result.stderr + result.stdout)
+        assert (project / "AGENTS.md").exists()
+
     @pytest.mark.skipif(POWERSHELL is None, reason="PowerShell not available")
     def test_powershell_script_rejects_backslash_context_files(self, tmp_path):
         project = tmp_path / "project"
@@ -774,6 +832,25 @@ def test_powershell_script_deduplicates_context_files_in_order(self, tmp_path):
         assert output.count("agent-context: updated CLAUDE.md") == 1
         assert "agent-context: updated agents.md" not in output
 
+    @pytest.mark.skipif(POWERSHELL is None, reason="PowerShell not available")
+    def test_powershell_script_falls_back_from_invalid_speckit_python(self, tmp_path):
+        project = tmp_path / "project"
+        project.mkdir()
+        _install_agent_context_config(
+            project,
+            context_file="AGENTS.md",
+            context_files=["AGENTS.md"],
+        )
+
+        result = _run_powershell_agent_context_script_with_env(
+            project,
+            speckit_python=str(project / "missing-python"),
+        )
+
+        assert result.returncode == 0, result.stderr + result.stdout
+        assert "agent-context: updated AGENTS.md" in (result.stderr + result.stdout)
+        assert (project / "AGENTS.md").exists()
+
     @pytest.mark.skipif(
         POWERSHELL is None or os.name != "nt",
         reason="Windows PowerShell junction test requires Windows",