Inconsistent feature resolution: check-prerequisites.sh enforces branch name while setup-plan.sh/setup-tasks.sh honor feature.json

[PechiSW]

Summary

Feature-directory resolution is inconsistent across the bundled scripts. check-prerequisites.sh (used by /speckit.implement) enforces the feature-branch name unconditionally, while setup-plan.sh and setup-tasks.sh skip that check when .specify/feature.json pins a valid feature directory. As a result, a valid feature.json lets plan and tasks run on any branch, but /speckit.implement still fails on a branch not named NNN-....

Environment

• Spec Kit CLI: 0.8.18

Detail

scripts/bash/common.sh get_feature_paths resolves the feature directory from, in priority order:

1. SPECIFY_FEATURE_DIRECTORY env var
2. .specify/feature.json feature_directory
3. branch-name prefix lookup

setup-plan.sh and setup-tasks.sh wrap the branch validation with feature_json_matches_feature_dir, e.g. "skip the git branch pattern check when feature.json resolves to the active feature dir". But check-prerequisites.sh calls check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" unconditionally, with no such guard. CURRENT_BRANCH comes from the git branch (unless SPECIFY_FEATURE is set), so feature.json alone does not let /speckit.implement proceed.

Steps to reproduce

1. In a git repo, on a branch not named like NNN-... (e.g. feature/foo), create specs/001-x/{spec,plan,tasks}.md and .specify/feature.json = {"feature_directory":"specs/001-x"}.
2. Run the plan or tasks prerequisite (setup-plan.sh / setup-tasks.sh): passes (feature.json honored).
3. Run check-prerequisites.sh --json --require-tasks: fails with ERROR: Not on a feature branch.

Expected

Consistent resolution. If .specify/feature.json (or SPECIFY_FEATURE_DIRECTORY) pins a valid feature directory, every prerequisite script should accept it.

Actual

check-prerequisites.sh ignores feature.json for the branch gate, so /speckit.implement fails where /speckit.plan and /speckit.tasks succeed.

Suggested fix

Wrap the check_feature_branch call in check-prerequisites.sh with the same feature_json_matches_feature_dir guard used by setup-plan.sh / setup-tasks.sh, so the branch-name check is skipped when feature.json resolves to the active feature directory.

[github-actions]

Bug assessment — check-prereqs-branch-gate: Invalid · severity N/A (already fixed in v0.10.0)

---

Bug Assessment: check-prerequisites branch gate inconsistency

• Slug: check-prereqs-branch-gate
• Created: 2026-06-30
• Source: issue Inconsistent feature resolution: check-prerequisites.sh enforces branch name while setup-plan.sh/setup-tasks.sh honor feature.json #3273
• Verdict: invalid
• Severity: N/A

Report (summarized)

Reporter (@PechiSW) describes an inconsistency between check-prerequisites.sh and setup-plan.sh/setup-tasks.sh when a valid .specify/feature.json is present on a non-standard branch. According to the report:

• setup-plan.sh / setup-tasks.sh skip the branch-name check via a feature_json_matches_feature_dir guard
• check-prerequisites.sh calls check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" unconditionally, ignoring feature.json
• Result: /speckit.plan and /speckit.tasks succeed, but /speckit.implement fails with ERROR: Not on a feature branch

Environment: Spec Kit CLI 0.8.18

Symptom

The described symptom — that check-prerequisites.sh enforces a branch-name pattern even when .specify/feature.json pins a valid feature directory — does not reproduce against the current codebase. The functions and code paths the report references no longer exist.

Reproduction

1. Set up a project on a non-standard branch (e.g., feature/foo) with .specify/feature.json = {"feature_directory":"specs/001-x"} and the required plan.md, tasks.md.
2. Run check-prerequisites.sh --json --require-tasks (the script behind /speckit.implement).
3. Expected (per report): fails with ERROR: Not on a feature branch. Actual (current code): succeeds — no branch check is performed.

Suspected Code Paths

Code paths the report references:

Path	Status
scripts/bash/common.sh → check_feature_branch()	Removed in v0.10.0
scripts/bash/common.sh → feature_json_matches_feature_dir()	Never existed in current codebase
scripts/bash/common.sh → priority-3 branch-name lookup	Removed; priority 3 is now an error, not a branch lookup
scripts/bash/check-prerequisites.sh → check_feature_branch call	Does not exist — only calls get_feature_paths()
extensions/git/scripts/bash/git-common.sh → check_feature_branch()	Exists, but only called from create-new-feature-branch.sh

Key evidence:

• tests/test_timestamp_branches.py:362-368 — TestCoreCommonRemovesGitHelpers explicitly asserts check_feature_branch and has_git are not present in common.sh.
• tests/test_timestamp_branches.py:375-379 — TestFindFeatureDirByPrefixRemoved asserts find_feature_dir_by_prefix is also gone.
• Current get_feature_paths() (common.sh:154–213) resolves via: (1) SPECIFY_FEATURE_DIRECTORY, (2) .specify/feature.json, (3) hard error — no branch name scanning.
• Current check-prerequisites.sh (scripts/bash/check-prerequisites.sh:86–88) only calls get_feature_paths(); performs no branch validation.

Root Cause Hypothesis

The bug was valid at v0.8.18 (released 2026-05-29). At that version, check_feature_branch existed in scripts/bash/common.sh and was called unconditionally from check-prerequisites.sh, while setup-plan.sh had already been updated to honor feature.json (CHANGELOG v0.8.1: "fix(plan): use .specify/feature.json to allow /speckit.plan on custom git branches (#2305)").

The inconsistency was resolved wholesale in v0.10.0 (released 2026-06-09, commit 927f54f) by removing all git operations — including check_feature_branch, has_git, and find_feature_dir_by_prefix — from the core scripts entirely. CHANGELOG entry: "refactor(scripts): remove git operations from core scripts — Remove has_git(), check_feature_branch(), git branch creation from core." The git extension now owns all branch-related logic.

Confidence: high — corroborated by test assertions, commit history, and direct inspection of the current scripts.

Proposed Remediation

None required. The bug no longer exists in the current codebase. The broader v0.10.0 refactoring eliminated the inconsistency more thoroughly than the reporter's suggested targeted fix.

If the reporter is still hitting this on v0.8.18 with installed project scripts: the scripts under .specify/scripts/bash/ may be stale (copied at init time from an older version). Running specify init again to refresh the installed scripts, or upgrading to v0.10.0+, would resolve it.

Files likely to change: None.

Tests to add or update: None — TestCoreCommonRemovesGitHelpers in tests/test_timestamp_branches.py already acts as a regression guard.

Risks & Considerations

• No code change is needed; closing as invalid.
• Users on pre-v0.10.0 with stale installed scripts may still observe the behavior — a migration note could be added to the v0.10.0 release notes or upgrade guide if not already present.

Open Questions

• None. The codebase evidence is conclusive.

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🐛 Assess Bug from Labeled Issue for issue #3273 · 748.9 AIC · ⌖ 13.4 AIC · ⊞ 31.8K · ◷

[mnriem]

Please upgrade to the latest Specify CLI as it has been fixed in 0.10.0