[Bug]: update-agent-context.sh crashes ("HAS_GIT: unbound variable") when SPECIFY_FEATURE is unset, despite feature.json resolving the feature

[montfort]

Bug Description

The core scripts/bash/update-agent-context.sh (the variant that sources scripts/bash/common.sh) crashes when run without SPECIFY_FEATURE in the environment — even though .specify/feature.json already identifies the active feature and get_feature_paths() resolves FEATURE_DIR from it correctly.

Since 0.11, common.sh::get_current_branch() returns an empty string when SPECIFY_FEATURE is unset (it no longer derives from the git branch). get_feature_paths() emits CURRENT_BRANCH="" and does not export HAS_GIT. Then in update-agent-context.sh::validate_environment():

• it treats empty CURRENT_BRANCH as fatal → ERROR: Unable to determine current feature (a false positive — the feature was resolved via feature.json);
• the next line references HAS_GIT, which was never assigned → under set -u this aborts with HAS_GIT: unbound variable.

Net effect: the after_plan hook (and any manual run) fails and the agent context file (e.g. CLAUDE.md) is not updated.

Steps to Reproduce

1. specify init a project (CLI 0.11.3, --script sh).
2. Run /speckit-specify → creates the feature and writes .specify/feature.json.
3. In a fresh shell without SPECIFY_FEATURE exported: bash .specify/scripts/bash/update-agent-context.sh claude.

Expected Behavior

Since .specify/feature.json already identifies the active feature (as check-prerequisites.sh and get_feature_paths() use), the script should update the agent context without requiring SPECIFY_FEATURE or a git feature branch.

Actual Behavior

ERROR: Unable to determine current feature
.../update-agent-context.sh: line 147: HAS_GIT: unbound variable

Workaround that confirms the cause: SPECIFY_FEATURE=<feature> bash .../update-agent-context.sh claude → exit 0, succeeds.

Suggested Fix

1. Initialize HAS_GIT with a default (or export it from get_feature_paths()) so set -u can't abort on it.
2. Don't treat empty CURRENT_BRANCH as fatal when FEATURE_DIR/feature.json already resolved the feature — gate on feature resolution, not branch (consistent with the 0.11 feature/branch decoupling and with check-prerequisites.sh).

Related

Complements #3067 / PR #3069 (which fix the self-contained extension variant's mtime plan-selection) and the #2887 family (inconsistent feature.json bypass across scripts). This is the core variant (the one that sources common.sh), where the same mismatch produces a hard crash rather than a wrong-plan selection.

Specify CLI Version

0.11.3

AI Agent

Claude Code

[github-actions]

Bug assessment — context-update-has-git: Likely valid, needs reproduction · severity medium

---

Bug Assessment: update-agent-context.sh HAS_GIT unbound variable

• Slug: context-update-has-git
• Created: 2026-06-22
• Source: issue [Bug]: update-agent-context.sh crashes ("HAS_GIT: unbound variable") when SPECIFY_FEATURE is unset, despite feature.json resolving the feature #3076
• Verdict: likely valid, needs reproduction
• Severity: medium

Report (summarized)

Reporter (@montfort) describes a crash in what they call "the core variant" of update-agent-context.sh — the one that sources scripts/bash/common.sh. Since CLI 0.11, get_current_branch() returns an empty string when SPECIFY_FEATURE is unset, and get_feature_paths() no longer emits HAS_GIT. A validate_environment() function then treats empty CURRENT_BRANCH as fatal ("Unable to determine current feature") and a subsequent reference to $HAS_GIT aborts under set -u. The after_plan hook and manual runs both fail; CLAUDE.md (or the equivalent context file) is not updated. The workaround SPECIFY_FEATURE= bash .specify/scripts/bash/update-agent-context.sh claude confirms the cause.

No external URLs to fetch.

Symptom

Running bash .specify/scripts/bash/update-agent-context.sh claude in a shell without SPECIFY_FEATURE exported exits with ERROR: Unable to determine current feature followed by .../update-agent-context.sh: line 147: HAS_GIT: unbound variable, even though .specify/feature.json already identifies the active feature.

Reproduction

1. Run specify init <project> --script sh with CLI 0.11.3 (or have a legacy project installation).
2. Run /speckit-specify → creates feature and writes .specify/feature.json.
3. Open a fresh shell without SPECIFY_FEATURE exported.
4. Run bash .specify/scripts/bash/update-agent-context.sh claude.

[NEEDS CLARIFICATION: Step 4 cannot succeed on a fresh 0.11.3 init because the file .specify/scripts/bash/update-agent-context.sh does not exist in that path — see root cause below. The reporter may be using a legacy project installation.]

Suspected Code Paths

• scripts/bash/common.sh:79–88 — get_current_branch() returns empty string when SPECIFY_FEATURE is unset; documented as intentional (caller resolves via feature.json).
• scripts/bash/common.sh:154–201 — get_feature_paths() outputs CURRENT_BRANCH='' (line 192) when branch is empty and does not emit HAS_GIT. The HAS_GIT variable only appears in extensions/git/scripts/bash/create-new-feature-branch.sh (lines 263–270).
• extensions/agent-context/scripts/bash/update-agent-context.sh (200 lines) — The only update-agent-context.sh that exists in the 0.11.3 source tree. It does not source common.sh, has no validate_environment(), and never references HAS_GIT.
• src/specify_cli/shared_infra.py:378–433 — install_shared_infra() copies files from scripts/bash/ to .specify/scripts/bash/. Since scripts/bash/update-agent-context.sh is absent from the source tree, it is not installed on fresh 0.11.3 inits.
• CONTRIBUTING.md:170 — Stale: still lists update-agent-context.sh as a script sourced by common.sh; this script was removed at commit fc3d124 ("fix: replace shell-based context updates with marker-based upsert").

Root Cause Hypothesis

Confidence: medium.

The "core variant" scripts/bash/update-agent-context.sh was removed from the repository in a previous refactor (commit fc3d124) and replaced by the self-contained extension variant at extensions/agent-context/scripts/bash/update-agent-context.sh. That replacement script does not source common.sh and has no validate_environment() or HAS_GIT dependency.

However, users who initialized a project with a pre-refactor CLI version will still have the old update-agent-context.sh at .specify/scripts/bash/update-agent-context.sh. When they later upgrade the CLI (and specify integration use or specify init --here refreshes common.sh in .specify/scripts/bash/common.sh), the new common.sh no longer exports HAS_GIT. The old script, still present because it is no longer in the source tree and therefore not overwritten or deleted, then sources the new common.sh, runs validate_environment(), and crashes on the unset $HAS_GIT variable under set -u. This is a stale-file regression specific to legacy installations post-upgrade. The stated reproduction steps (fresh specify init with 0.11.3) would not create the crash because .specify/scripts/bash/update-agent-context.sh simply doesn't exist in a fresh install.

Proposed Remediation

Preferred: During install_shared_infra (and the migration path in _migrate_commands.py), detect and remove the stale .specify/scripts/bash/update-agent-context.sh (and its PowerShell counterpart) that may remain from pre-refactor installations. The removal should be recorded in the shared-infra manifest so it is idempotent and auditable. A targeted [CHANGELOG] entry should note the automatic cleanup.

Additionally, clean up the stale reference to update-agent-context.sh in CONTRIBUTING.md line 170 to prevent future confusion.

Alternatives:

• Add a no-op stub scripts/bash/update-agent-context.sh that prints a migration notice and exits 0. This would stop the crash without relying on detection/deletion logic, but would silently succeed without updating the context file — worse user experience than failing loudly.
• Document in the upgrade guide that users with pre-refactor projects should manually remove .specify/scripts/bash/update-agent-context.sh. Low engineering cost but places burden on users.

Files likely to change:

• src/specify_cli/shared_infra.py — add stale-file removal logic for update-agent-context.sh / update-agent-context.ps1 in .specify/scripts/bash/ and .specify/scripts/powershell/.
• src/specify_cli/integrations/_migrate_commands.py — extend migration to remove stale core-variant scripts.
• CONTRIBUTING.md — remove stale update-agent-context.sh from the common.sh dependents list (line 170).
• docs/upgrade.md — add a note about the stale file for users upgrading from pre-0.11 installations (optional but recommended).

Tests to add or update:

• Test in tests/integrations/test_cli.py or a new tests/test_stale_script_migration.py: given a project with a pre-existing .specify/scripts/bash/update-agent-context.sh, verify that running install_shared_infra removes it and records the removal in the manifest.
• Test that after migration the file is absent and no crash occurs when running a fresh update-agent-context.sh from the extension path.

Risks & Considerations

• Removal may surprise users who customized the old script: The hash-based preservation logic in install_shared_infra normally protects user-modified files; the stale-removal code should warn if the file's hash diverges from the last-known managed hash before deleting.
• No data loss risk: The old script only writes to the agent context file (CLAUDE.md, etc.); it does not modify specs or tasks.
• PowerShell parity: The same issue likely affects .specify/scripts/powershell/update-agent-context.ps1 for Windows users; remediation should cover both variants.
• Scope limited to legacy installs: Fresh 0.11.3 (and later) installations are unaffected; the stale script simply isn't there.

Open Questions

• [NEEDS CLARIFICATION: Can the reporter confirm whether this was a fresh specify init on 0.11.3 or an upgrade of an existing pre-refactor project? The reproduction steps say "specify init a project (CLI 0.11.3)" but the crash path .specify/scripts/bash/update-agent-context.sh is only present in legacy installations.]
• [NEEDS CLARIFICATION: Does running specify integration use <agent> on the affected project (to trigger install_shared_infra) resolve the crash, confirming the stale-file theory?]

Posted by GitHub Copilot (model: claude-sonnet-4.6) on behalf of the bug-assess workflow.

Generated by 🐛 Assess Bug from Labeled Issue for issue #3076 · 540.5 AIC · ⌖ 25.1 AIC · ⊞ 31.7K · ◷

[mnriem]

Thanks for the detailed report. Before we treat this as a core-script bug, I think the diagnosis points somewhere else and I'd like to confirm one thing.

The crash path you hit — .specify/scripts/bash/update-agent-context.sh that sources common.sh, calls get_feature_paths(), treats empty CURRENT_BRANCH as fatal, and references HAS_GIT under set -u — describes a script that no longer exists in the current tree:

1. The core update-agent-context.sh was removed/refactored (fix: replace shell-based context updates with marker-based upsert #2259) and the functionality was extracted into the bundled agent-context extension (Extract agent context updates into bundled agent-context extension #2546). Core scripts/bash/ now only ships check-prerequisites.sh, common.sh, create-new-feature.sh, setup-plan.sh, and setup-tasks.sh.

2. HAS_GIT is no longer part of the core SDD flow. Git became opt-in at v0.10.0 (feat: make git extension opt-in and remove --no-git at v0.10.0 #2873), and HAS_GIT now lives exclusively inside the Git extension (extensions/git/scripts/.../create-new-feature-branch.{sh,ps1}). Core common.sh::get_current_branch() is feature.json-based and never sets or emits HAS_GIT.

3. The replacement updater already behaves the way your "Expected Behavior" describes. extensions/agent-context/scripts/bash/update-agent-context.sh does not source common.sh and never touches SPECIFY_FEATURE, CURRENT_BRANCH, HAS_GIT, or git — it reads agent-context-config.yml and selects the most-recent specs/*/plan.md. So it updates the context file without requiring SPECIFY_FEATURE or a git branch.

Because both the Git-opt-in change and the agent-context extraction predate 0.11.3, a fresh specify init on 0.11.3 doesn't ship the crashing script. That makes this look like a stale legacy file left over from a pre-refactor project rather than a defect in current core logic — and the suggested fixes (initialize HAS_GIT, gate on feature resolution instead of branch) would patch a script that has already been deleted and re-fix a git/branch coupling that the opt-in refactor already removed.

Could you confirm: was the affected project a fresh specify init on 0.11.3, or an upgrade of a project that was originally initialized on a pre-refactor version? And does running specify integration use <agent> (which triggers install_shared_infra) change the behavior?

If it is an upgraded project, the right fix is to clean up the stale .specify/scripts/bash/update-agent-context.sh (and its PowerShell counterpart) on upgrade — there's currently no stale-file removal for it in shared_infra.py — rather than reintroducing HAS_GIT/branch handling into the core path.

[montfort]

Thanks both — your diagnosis is correct, and I owe a correction on my repro.

This was an upgraded project, not a fresh init. Sentinel was first initialized 2026-05-19 on a pre-refactor CLI, then upgraded over time (…→0.11.1→0.11.3). My reproduction step said "specify init on 0.11.3", which is wrong — a fresh 0.11.3 init doesn't ship the crashing script, exactly as you note. Apologies for the misleading repro.

Confirming the stale-file state in the affected repo:

• .specify/scripts/bash/update-agent-context.sh is present (30 KB, dated from the original 2026-05-19 init). It still sources common.sh (L53), has validate_environment() (L143), and references HAS_GIT (L147/159) under set -u.
• .specify/scripts/bash/ holds 6 scripts — the 5 you list plus this orphan.
• The extension replacement (.specify/extensions/agent-context/scripts/bash/update-agent-context.sh, 6.6 KB, self-contained) is also present.

Your second question — does re-installation clean it up? I tested all three flows on the affected repo. None removes the stale file:

Command	Removes stale?	Side effect
integration use claude	❌ no	re-touches the 5 managed scripts (0 content change)
integration upgrade claude	❌ no	inline agent-context update rewrote CLAUDE.md, dropping our specific plan reference (specs/005-…/plan.md → generic) + deprecation notice
integration upgrade claude --force	❌ no	same as above

Two extra signals worth flagging: (1) the legacy inline agent-context update degrades the context file (it overwrote a specific plan path with the generic placeholder), and (2) the CLI itself prints "Inline agent-context updates during integration setup will be disabled in v0.12.0… moved to the bundled agent-context extension". Both reinforce that the orphan core script + inline path are legacy.

So this is squarely a stale-file regression on legacy installs post-upgrade, and the fix you propose is the right one (remove the orphan update-agent-context.sh / .ps1 during install_shared_infra + migration, plus the CONTRIBUTING.md:170 stale reference) — not re-introducing HAS_GIT/branch handling into a deleted script. Happy to validate a candidate fix against this repo as a fixture.

[mnriem]

Can you spearhead the PR?

[montfort]

Done — opened #3098.

It applies the same stale-removal that integration_upgrade already does, to install_shared_infra: manifest-tracked scripts the current bundle no longer ships are removed — hash-safe (managed copies only; user-customized, symlinked, and recovered entries preserved), guarded so a missing/empty source can't trigger mass deletion, and the safe-destination check prevents unlinking through a symlinked ancestor. Adds a small IntegrationManifest.remove(), 2 unit tests, and drops the stale update-agent-context.sh reference in CONTRIBUTING.md.

Validated locally: ruff clean, full suite 4176 passed, plus a manual CLI repro (inject a manifest-tracked legacy update-agent-context.sh → specify init --here --force → "Removed 1 obsolete shared script(s)", orphan gone from disk + manifest, common.sh intact). I left the CHANGELOG entry out pending your preference (noted in the PR).