[Bug]: get_feature_paths emits empty CURRENT_BRANCH when SPECIFY_FEATURE unset, despite feature context via SPECIFY_FEATURE_DIRECTORY/feature.json

[athemelis]

Bug Description

get_current_branch() returns empty when no explicit feature/branch is set, and get_feature_paths still prints CURRENT_BRANCH= (empty) even though the feature directory is resolvable from SPECIFY_FEATURE_DIRECTORY or .specify/feature.json. Downstream scripts/agents that expect a non-empty identifier get misleading output.

Steps to Reproduce

1. Resolve feature context via SPECIFY_FEATURE_DIRECTORY or .specify/feature.json, without SPECIFY_FEATURE set.
2. Run check-prerequisites.sh --paths-only (or call get_feature_paths).
3. Inspect CURRENT_BRANCH in the output.

Expected Behavior

A usable identifier (e.g. the feature-directory basename) when there's no branch context.

Actual Behavior

CURRENT_BRANCH is emitted empty.

Specify CLI Version

0.11.0

AI Agent

GitHub Copilot

Operating System

macOS Tahoe 26.5.1

Python Version

3.11.15 (uv-managed standalone CPython, cpython-3.11-macos-aarch64-none — uv installs specify under its own Python, not the system CLT 3.9.6 or Homebrew 3.13/3.14)

Error Logs

none (silent; misleading empty value)

Additional Context

File: .specify/scripts/bash/common.sh (get_current_branch, get_feature_paths). Suggested fix: fall back to the basename of FEATURE_DIR when current_branch is empty. Sibling issues: agent-context scoped layout; feature.json write side-effect.

[github-actions]

Bug assessment — feature-paths-empty-branch: Valid · severity medium

---

Bug Assessment: get_feature_paths emits empty CURRENT_BRANCH

• Slug: feature-paths-empty-branch
• Created: 2026-06-17T22:06:35Z
• Source: issue [Bug]: get_feature_paths emits empty CURRENT_BRANCH when SPECIFY_FEATURE unset, despite feature context via SPECIFY_FEATURE_DIRECTORY/feature.json #3026
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @athemelis on Specify CLI 0.11.0 (macOS, Python 3.11). When a feature context is resolved via SPECIFY_FEATURE_DIRECTORY or .specify/feature.json — without SPECIFY_FEATURE being set — get_feature_paths() in scripts/bash/common.sh successfully resolves FEATURE_DIR but emits an empty CURRENT_BRANCH. Downstream scripts and agents that rely on a non-empty identifier receive misleading empty output. No error is raised; the silent empty value is the entire symptom.

Symptom

get_feature_paths() outputs CURRENT_BRANCH= (empty) even when the feature directory was successfully resolved from SPECIFY_FEATURE_DIRECTORY or .specify/feature.json. Expected: a usable non-empty identifier, such as the basename of the resolved feature directory.

Reproduction

1. Create a spec-kit project with a feature directory (e.g. specs/my-feature).
2. Set SPECIFY_FEATURE_DIRECTORY=specs/my-feature without setting SPECIFY_FEATURE.
3. Run ./scripts/bash/check-prerequisites.sh --paths-only.
4. Observe BRANCH: in the output — the value after the colon is empty.

Alternatively: write {"feature_directory": "specs/my-feature"} to .specify/feature.json and repeat steps 3–4 without either env var set.

Suspected Code Paths

• scripts/bash/common.sh:46–55 — get_current_branch(): returns $SPECIFY_FEATURE or unconditionally returns empty. The code comment explicitly states "caller must handle this via feature.json in get_feature_paths()", but that handling was never implemented.
• scripts/bash/common.sh:121–164 — get_feature_paths(): calls get_current_branch() at line 123 (before the feature dir is resolved), then emits the result unchanged at line 155 (printf 'CURRENT_BRANCH=%q\n' "$current_branch"). No fallback to basename "$feature_dir" is applied after the directory is resolved.
• scripts/powershell/common.ps1:41–51 — Get-CurrentBranch: parallel PowerShell implementation; same issue — returns "" when $env:SPECIFY_FEATURE is absent, and Get-FeaturePathsEnv (line 105) stores it in CURRENT_BRANCH without a post-resolution fallback.
• scripts/bash/check-prerequisites.sh:104–110 — --paths-only output path: prints BRANCH: $CURRENT_BRANCH, which surfaces the empty value to the user.
• scripts/bash/setup-plan.sh:31–33 — also evals get_feature_paths() output and uses $CURRENT_BRANCH downstream in JSON output.

Root Cause Hypothesis

get_current_branch() was written with the explicit design contract (documented in the code comment) that its caller, get_feature_paths(), would supply a fallback identifier once the feature directory is known. That fallback was never implemented. As a result, CURRENT_BRANCH is always empty unless SPECIFY_FEATURE is set, making the function contract silently broken for the SPECIFY_FEATURE_DIRECTORY/feature.json resolution paths. Confidence: high — the code path is straightforward and the comment in get_current_branch() names the exact function responsible for the missing fallback.

Proposed Remediation

Preferred: In get_feature_paths() in scripts/bash/common.sh, add a fallback immediately after the feature directory is fully resolved (after line 150, before the printf block at line 154):

# Fall back to feature directory basename when no explicit feature/branch name set
[[ -z "$current_branch" ]] && current_branch="$(basename "$feature_dir")"

Apply the equivalent fix in scripts/powershell/common.ps1 in Get-FeaturePathsEnv, after $featureDir is set and before the return hash-table is constructed (around line 143):

if (-not $currentBranch) {
    $currentBranch = Split-Path $featureDir -Leaf
}

This is a minimal, low-risk change that precisely matches the intent documented in get_current_branch()'s own comment and the reporter's suggested fix.

Alternatives:

• Implement the fallback inside get_current_branch() itself by accepting the feature directory as an argument. Trade-off: changes the function signature, breaking the clean separation of concerns; more invasive.
• Emit a warning when CURRENT_BRANCH is empty but continue. Trade-off: doesn't fix the root cause, only adds noise.

Files likely to change:

• scripts/bash/common.sh (primary fix — get_feature_paths(), line ~154)
• scripts/powershell/common.ps1 (parallel fix — Get-FeaturePathsEnv)
• tests/test_timestamp_branches.py (new test cases in TestFeatureDirectoryResolution)

Tests to add or update:

• In TestFeatureDirectoryResolution: add a test asserting that CURRENT_BRANCH equals basename(FEATURE_DIR) when SPECIFY_FEATURE is unset but SPECIFY_FEATURE_DIRECTORY is set.
• In TestFeatureDirectoryResolution: add a parallel test for the feature.json resolution path.
• Confirm the existing test test_env_var in TestGetCurrentBranch (line 349) still passes — it should, since SPECIFY_FEATURE takes priority.

Risks & Considerations

• Low breakage risk: The fallback only activates when current_branch is empty, so workflows that set SPECIFY_FEATURE are unaffected.
• Basename may not be a git branch name: If the feature directory is e.g. specs/20260617-120000-my-feat, the basename 20260617-120000-my-feat is a reasonable identifier but not necessarily a real branch. Downstream consumers that call git rev-parse "$CURRENT_BRANCH" could fail silently — but they likely do already with an empty value.
• PowerShell parity: Both bash and PowerShell versions must be fixed together to keep behavior consistent across platforms.
• No migration or API change needed: CURRENT_BRANCH is shell-eval output, not a public Python API.

Open Questions

• [NEEDS CLARIFICATION: Should the fallback also apply when SPECIFY_FEATURE_DIRECTORY is a bare directory name with no meaningful basename (e.g., . or /)?]
• [NEEDS CLARIFICATION: The issue mentions "agent-context scoped layout" and "feature.json write side-effect" as sibling issues — are those tracked separately, or should they be folded into this fix?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #3026 · 283.2 AIC · ⌖ 13.4 AIC · ⊞ 31.2K · ◷