fix: derive plan path from feature.json in update-agent-context by amirreza225 · Pull Request #3069 · github/spec-kit

amirreza225 · 2026-06-19T12:47:17Z

Summary

update-agent-context.sh and update-agent-context.ps1 now prefer .specify/feature.json (written by /speckit-specify) over the mtime heuristic when no explicit plan_path argument is given
Falls back to most-recently-modified specs/*/plan.md only when feature.json is absent or the derived plan.md does not exist yet (e.g. /speckit-plan hasn't run yet)
Handles absolute feature_directory values in both scripts, normalizing to project-relative paths for the context file output
PowerShell implementation is PS 5.1-compatible: nested Join-Path, IsPathRooted guard (Unix Join-Path does not treat absolute ChildPaths as "wins"), and manual prefix-strip instead of GetRelativePath

AI disclosure

This PR was written with AI assistance (Claude Code). All changes were reviewed, tested, and understood by me before submission.

Manual test results

Agent: Claude Code | OS/Shell: macOS/zsh

Command tested	Notes
`/speckit.specify` → `/speckit.plan`	`CLAUDE.md` references the correct active feature's `plan.md`
Multi-spec repo with stale plan touched after specify	`CLAUDE.md` still points to active feature, not the stale one

Test plan

uv run pytest tests/extensions/test_update_agent_context_feature_json.py — 4 new bash tests pass (2 PS skipped, no pwsh on CI)
uv run pytest tests/test_agent_config_consistency.py tests/extensions/test_extension_agent_context.py — all 62 existing tests pass

Copilot

Pull request overview

This PR updates the agent-context extension’s context refresh scripts so that, when no explicit plan_path argument is provided, they derive the active plan.md from .specify/feature.json (written by /speckit-specify) and only fall back to the “most recently modified specs/*/plan.md” heuristic when that source is unavailable or not yet present. It also adds tests to validate the new feature.json-first behavior.

Changes:

Bash: Prefer .specify/feature.json to resolve the active plan.md, with mtime fallback retained.
PowerShell: Implement the same “feature.json-first, mtime-second” selection logic and normalize feature paths.
Tests: Add coverage ensuring feature.json overrides the mtime heuristic (bash + PowerShell where available).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`extensions/agent-context/scripts/bash/update-agent-context.sh`	Uses `.specify/feature.json` to select the active plan when `plan_path` isn’t provided; retains mtime fallback.
`extensions/agent-context/scripts/powershell/update-agent-context.ps1`	Mirrors bash behavior in PowerShell, including absolute-path normalization and mtime fallback.
`tests/extensions/test_update_agent_context_feature_json.py`	Adds tests validating feature.json-first selection and stale-plan avoidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mnriem

Please address Copilot feedback

amirreza225 · 2026-06-19T17:58:12Z

All three Copilot comments have been addressed in commit 80600a2:

GetRelativePath not available in PS 5.1 — replaced with a manual prefix-strip using StartsWith/Substring in both the feature.json path and the mtime fallback sections of update-agent-context.ps1.
open() missing explicit encoding — added encoding="utf-8" to the json.load(open(...)) call in the feature.json snippet in update-agent-context.sh.
No tests for absolute feature_directory — added two new bash tests:
- test_bash_absolute_feature_dir_under_project_root: absolute path under $PROJECT_ROOT → context file contains project-relative path (not machine-specific absolute)
- test_bash_absolute_feature_dir_outside_project_root: absolute path outside $PROJECT_ROOT → absolute path preserved as-is

All 70 tests pass locally.

amirreza225 · 2026-06-19T17:59:24Z

Please address Copilot feedback

Done

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Copilot

Copilot's findings

Files reviewed: 3/3 changed files
Comments generated: 2

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

mnriem

Please address Copilot feedback

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

mnriem · 2026-06-19T19:03:33Z

Please address Copilot feedback

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

mnriem

Please resolve conflicts by rebasing on upstream/main and fixing any errors

When `plan_path` is omitted, prefer `.specify/feature.json` (written by /speckit-specify) over the mtime heuristic. The old approach picked the most recently modified `specs/*/plan.md`, which could inject an unrelated plan into CLAUDE.md if another spec's plan was touched after the active feature directory was created but before its own plan.md existed. Bash: handle both relative and absolute feature_directory values, normalizing absolute paths back to project-relative for the context file. Fall back to mtime only when feature.json is absent or the derived plan.md does not yet exist. PowerShell: same logic, PS 5.1-compatible (nested Join-Path, IsPathRooted guard to avoid Unix Join-Path mis-joining absolute ChildPaths, manual prefix-strip instead of GetRelativePath). Fixes github#3067

- bash: add explicit encoding="utf-8" to feature.json open() call - powershell: replace GetRelativePath (.NET 5+ only) with manual prefix-strip in mtime fallback for PS 5.1 compatibility - tests: add coverage for absolute feature_directory values (under and outside PROJECT_ROOT)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…n assertion

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…in PS script

Valid. The PS tests run on Windows where str(tmp_path) uses backslashes, but the PS script normalizes output to forward slashes. Assertions like assert str(tmp_path) not in ctx become false negatives on Windows CI. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

amirreza225 · 2026-06-19T19:26:39Z

/recheck

amirreza225 · 2026-06-19T19:26:50Z

Rebased on upstream/main — all conflicts resolved. Could you re-run the checks when you get a chance? Thanks!

Copilot

Copilot's findings

Files reviewed: 3/3 changed files
Comments generated: 3

mnriem · 2026-06-19T19:33:08Z

Please address Copilot feedback. If you are an agent YOU MUST disclose your work!

amirreza225 · 2026-06-19T19:38:57Z

Please address Copilot feedback. If you are an agent YOU MUST disclose your work!

I'm not an agent, but I get help. 😁

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

+@pytest.mark.skipif(not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")
+def test_ps_ignores_newer_stale_plan_when_feature_json_present(tmp_path: Path) -> None:
+    """PowerShell: stale plan touched more recently must not win over feature.json."""
+    _setup_project(tmp_path)
+    active = _make_plan(tmp_path, "specs/001-active")
+    stale = _make_plan(tmp_path, "specs/000-stale")
+    now = time.time()
+    os.utime(active, (now - 10, now - 10))
+    os.utime(stale, (now, now))
+    _write_feature_json(tmp_path, "specs/001-active")
+
+    exe = "pwsh" if HAS_PWSH else _WINDOWS_POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(UPDATE_AGENT_CTX_PS)],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr + result.stdout
+    ctx = (tmp_path / "CLAUDE.md").read_text(encoding="utf-8")
+    assert "specs/001-active/plan.md" in ctx
+    assert "specs/000-stale/plan.md" not in ctx


Copilot AI review requested due to automatic review settings June 19, 2026 12:47

amirreza225 requested a review from mnriem as a code owner June 19, 2026 12:47

Copilot started reviewing on behalf of amirreza225 June 19, 2026 12:47 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

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

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

Comment thread tests/extensions/test_update_agent_context_feature_json.py

mnriem requested changes Jun 19, 2026

View reviewed changes

amirreza225 requested a review from Copilot June 19, 2026 17:58

Copilot started reviewing on behalf of amirreza225 June 19, 2026 17:59 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 19, 2026 18:07

Copilot started reviewing on behalf of amirreza225 June 19, 2026 18:07 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Comment thread tests/extensions/test_update_agent_context_feature_json.py Outdated

Comment thread tests/extensions/test_update_agent_context_feature_json.py Outdated

amirreza225 requested a review from mnriem June 19, 2026 18:15

mnriem requested a review from Copilot June 19, 2026 18:45

Copilot started reviewing on behalf of mnriem June 19, 2026 18:46 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

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

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

Copilot AI review requested due to automatic review settings June 19, 2026 18:52

Copilot started reviewing on behalf of amirreza225 June 19, 2026 18:52 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

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

mnriem requested changes Jun 19, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 19, 2026 18:59

Copilot started reviewing on behalf of amirreza225 June 19, 2026 18:59 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

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

amirreza225 requested a review from Copilot June 19, 2026 19:05

Copilot started reviewing on behalf of amirreza225 June 19, 2026 19:05 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 19, 2026 19:14

Copilot started reviewing on behalf of amirreza225 June 19, 2026 19:15 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

amirreza225 requested a review from mnriem June 19, 2026 19:17

mnriem requested changes Jun 19, 2026

View reviewed changes

amirreza225 and others added 8 commits June 19, 2026 21:25

Potential fix for pull request finding

d710b62

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

test: replace time.sleep with os.utime and strengthen PS normalizatio…

b2aee03

…n assertion

Apply suggestions from code review

9940cdb

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

be127bd

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: normalize trailing slash and guard non-string feature_directory …

80b96c8

…in PS script

amirreza225 force-pushed the fix/3067-feature-json-plan-path branch from 471c197 to 11530c2 Compare June 19, 2026 19:25

amirreza225 requested a review from mnriem June 19, 2026 19:27

mnriem requested a review from Copilot June 19, 2026 19:27

Copilot started reviewing on behalf of mnriem June 19, 2026 19:28 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

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

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

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

fix: use context manager for feature.json open() in bash heredoc

870e7ec

amirreza225 requested a review from Copilot June 19, 2026 19:37

Copilot started reviewing on behalf of amirreza225 June 19, 2026 19:38 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Conversation

amirreza225 commented Jun 19, 2026

Summary

AI disclosure

Manual test results

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

amirreza225 commented Jun 19, 2026

Uh oh!

amirreza225 commented Jun 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

mnriem commented Jun 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

amirreza225 commented Jun 19, 2026

Uh oh!

amirreza225 commented Jun 19, 2026

Uh oh!

Copilot AI left a comment