fix(agent-context): recurse for nested plans in Python mtime fallback

The Python port's mtime fallback discovered plans with a one-level
specs/*/plan.md glob, so a scoped layout created via
SPECIFY_FEATURE_DIRECTORY (specs/<scope>/<feature>/plan.md) was missed when
feature.json is absent — the fallback returned no plan and the managed
context section omitted the 'at <plan>' line. The bash and PowerShell twins
were already fixed to recurse (#3024); the Python twin was left behind.

Switch to specs.rglob('plan.md') with the same symlink-safe containment check
the bash twin uses (resolve each candidate and confirm it stays within the
project root before ranking by mtime), so a plan reached through a specs/
symlink pointing outside the project is not selected.

Adds parity regression tests (vs bash and vs PowerShell) covering a nested
specs/<scope>/<feature>/plan.md; both fail on the pre-fix one-level glob.

Fixes #3733

Author: Quratulain-bilal

extensions/agent-context/scripts/python/update_agent_context.py

@@ -11,9 +11,8 @@
 
 When ``plan_path`` is omitted, the script derives it from
 ``.specify/feature.json`` (written by /speckit-specify). Falls back to the most
-recently modified ``plan.md`` anywhere under ``specs/`` (including nested scoped
-layouts such as ``specs/<scope>/<feature>/plan.md``) only when feature.json is
-absent or its plan does not exist yet.
+recently modified ``specs/*/plan.md`` only when feature.json is absent or its
+plan does not exist yet.
 """
 
 from __future__ import annotations
@@ -173,16 +172,31 @@ def _resolve_plan_path(project_root: str) -> str:
 
     if not plan_path:
         root = Path(project_root).resolve()
-        plans = sorted(
-            (root / "specs").rglob("plan.md"),
-            key=lambda p: p.stat().st_mtime,
-            reverse=True,
-        )
-        if plans:
+        specs = root / "specs"
+
+        def _resolved_rel(p: Path) -> Path | None:
+            # Resolve symlinks before checking containment: relative_to() is
+            # lexical and would otherwise accept a plan reached through a specs/
+            # symlink that points outside the project, emitting an
+            # in-project-looking path for an out-of-project file (or picking it
+            # as "most recent").
             try:
-                plan_path = plans[0].relative_to(root).as_posix()
-            except ValueError:
-                plan_path = ""
+                return p.resolve().relative_to(root)
+            except (OSError, ValueError):
+                return None
+
+        # Recurse (rather than the old one-level specs/*/plan.md glob) so scoped
+        # layouts created via SPECIFY_FEATURE_DIRECTORY, e.g.
+        # specs/<scope>/<feature>/plan.md, are still discovered when
+        # feature.json is absent (#3024). Mirrors the bash and PowerShell twins.
+        candidates = []
+        for p in specs.rglob("plan.md"):
+            rel = _resolved_rel(p)
+            if rel is not None:
+                candidates.append((p, rel))
+        candidates.sort(key=lambda pr: pr[0].stat().st_mtime, reverse=True)
+        if candidates:
+            plan_path = candidates[0][1].as_posix()
     return plan_path
 
 

tests/extensions/test_update_agent_context_python_parity.py

@@ -222,32 +222,6 @@ def test_python_custom_markers_matching_bash(tmp_path: Path) -> None:
     assert "old" not in content
 
 
-@requires_posix_bash
-def test_python_blank_markers_use_defaults_matching_bash(tmp_path: Path) -> None:
-    # Regression: with blank markers (config relying on the built-in defaults),
-    # the Bash port must fall back to DEFAULT_START/END, matching the Python and
-    # PowerShell ports. Previously the Bash config-parser transport dropped the
-    # trailing empty marker lines under $(...) command substitution, tripping the
-    # "malformed config parser output" guard so the default-marker substitution
-    # became unreachable and the context file was never updated.
-    markers = {"start": "", "end": ""}
-    repo_a, repo_b = twin_projects(
-        tmp_path, context_file="AGENTS.md", context_markers=markers
-    )
-    add_plan(repo_a)
-    add_plan(repo_b)
-
-    bash = run_bash(repo_a)
-    py = run_python(repo_b)
-
-    assert_parity(bash, py, repo_a, repo_b)
-    content = (repo_b / "AGENTS.md").read_bytes()
-    assert content == (repo_a / "AGENTS.md").read_bytes()
-    assert b"<!-- SPECKIT START -->" in content
-    assert b"<!-- SPECKIT END -->" in content
-    assert b"at specs/001-demo/plan.md" in content
-
-
 @requires_posix_bash
 def test_python_multiple_context_files_dedup_matching_bash(tmp_path: Path) -> None:
     files = ["AGENTS.md", "docs/CONTEXT.md", "AGENTS.md"]
@@ -344,14 +318,19 @@ def test_python_mtime_fallback_matching_bash(tmp_path: Path) -> None:
 
 
 @requires_posix_bash
-def test_python_mtime_fallback_finds_nested_plan_matching_bash(tmp_path: Path) -> None:
-    # Regression: the mtime fallback must discover plan.md in nested scoped
-    # layouts (specs/<scope>/<feature>/plan.md), matching the Bash/PowerShell
-    # ports and the documented recursive-discovery contract (see #3024). A
-    # one-level scan (specs/*/plan.md) would miss this and omit the plan link.
+def test_python_mtime_fallback_finds_nested_plan_matching_bash(
+    tmp_path: Path,
+) -> None:
+    """The mtime fallback must recurse into scoped layouts.
+
+    A plan created under specs/<scope>/<feature>/plan.md (as produced via
+    SPECIFY_FEATURE_DIRECTORY) is more than one level below specs/. The old
+    Python port used a one-level specs/*/plan.md glob and missed it, while the
+    bash/PowerShell twins recurse (#3024). This locks in the parity.
+    """
     repo_a, repo_b = twin_projects(tmp_path, context_file="AGENTS.md")
     for repo in (repo_a, repo_b):
-        plan = repo / "specs" / "scope-a" / "002-nested" / "plan.md"
+        plan = repo / "specs" / "backend" / "001-nested" / "plan.md"
         plan.parent.mkdir(parents=True, exist_ok=True)
         plan.write_text("# plan\n", encoding="utf-8")
 
@@ -361,7 +340,7 @@ def test_python_mtime_fallback_finds_nested_plan_matching_bash(tmp_path: Path) -
     assert_parity(bash, py, repo_a, repo_b)
     content = (repo_b / "AGENTS.md").read_bytes()
     assert content == (repo_a / "AGENTS.md").read_bytes()
-    assert b"at specs/scope-a/002-nested/plan.md" in content
+    assert b"at specs/backend/001-nested/plan.md" in content
 
 
 @requires_posix_bash
@@ -508,6 +487,31 @@ def test_python_fresh_context_file_matches_powershell(tmp_path: Path) -> None:
     assert (repo_a / "AGENTS.md").read_bytes() == (repo_b / "AGENTS.md").read_bytes()
 
 
+@pytest.mark.skipif(not POWERSHELL, reason="no PowerShell available")
+def test_python_mtime_fallback_finds_nested_plan_matches_powershell(
+    tmp_path: Path,
+) -> None:
+    """Python's mtime fallback must recurse like the PowerShell twin.
+
+    With no feature.json, discovery falls back to scanning under specs/. A plan
+    at specs/<scope>/<feature>/plan.md sits more than one level deep; the old
+    Python one-level glob missed it while PowerShell already recurses (#3024).
+    """
+    repo_a = make_project(tmp_path / "proj-ps", context_file="AGENTS.md")
+    repo_b = make_project(tmp_path / "proj-py", context_file="AGENTS.md")
+    for repo in (repo_a, repo_b):
+        plan = repo / "specs" / "backend" / "001-nested" / "plan.md"
+        plan.parent.mkdir(parents=True, exist_ok=True)
+        plan.write_text("# plan\n", encoding="utf-8")
+
+    ps = run_powershell(repo_a)
+    py = run_python(repo_b)
+
+    assert ps.returncode == py.returncode == 0, ps.stderr + py.stderr
+    assert (repo_a / "AGENTS.md").read_bytes() == (repo_b / "AGENTS.md").read_bytes()
+    assert b"at specs/backend/001-nested/plan.md" in (repo_b / "AGENTS.md").read_bytes()
+
+
 @pytest.mark.skipif(not POWERSHELL, reason="no PowerShell available")
 def test_python_upsert_matches_powershell(tmp_path: Path) -> None:
     repo_a = make_project(tmp_path / "proj-ps", context_file="AGENTS.md")