[Bug]: Explicit issue target is not validated against persisted feature context

[grafvonb]

Bug Description

Spec Kit’s generated clarification and planning workflows can operate on the wrong feature when an explicit issue target conflicts with the feature persisted in .specify/feature.json.

For example, the user invokes clarification with GitHub issue 285, while .specify/feature.json points to specs/286-tenant-pd-ordering. The prerequisite script resolves feature 286, but the generated workflow does not require comparing that result with the explicit 285 argument before writing files.

This creates a safety risk: specifications or planning artifacts for one feature can be modified while the user believes they are working on another feature.

Steps to Reproduce

1. Create two feature contexts, such as specs/285-semantic-milestones and specs/286-tenant-pd-ordering.

2. Persist feature 286 in .specify/feature.json:

   {"feature_directory":"specs/286-tenant-pd-ordering"}

3. Invoke the clarification workflow with an explicit issue 285 target:

   $speckit-clarify https://github.com/example/project/issues/285

4. Observe that check-prerequisites.sh --json --paths-only resolves specs/286-tenant-pd-ordering.

5. Observe that the generated workflow has no mandatory check comparing issue 285 from the command input with the resolved directory, specification traceability, or persisted feature state.

6. If processing continues, feature 286 may be analyzed or modified even though the user explicitly requested 285.

7. Invoke a chained command such as “run the plan”; the incorrect persisted target continues into the next stage.

Expected Behavior

Before reading or writing feature artifacts, the workflow should extract any explicit issue or feature identity from the command input and compare it with:

• .specify/feature.json
• the resolved FEATURE_DIR
• the feature-directory numeric prefix
• the specification’s issue traceability metadata

If these values disagree, the command should abort without modifying files and display a clear error such as:

ERROR: Feature context mismatch.

Requested target: GitHub issue 285
Active feature: specs/286-tenant-pd-ordering
Persisted by: .specify/feature.json

Run the specify workflow for 285 or explicitly switch the active feature.

Argument-less chained commands should retain the previously established feature target instead of silently switching to another persisted feature.

Actual Behavior

The prerequisite resolver uses .specify/feature.json and returns feature 286. The generated workflow does not mandate validation against the explicit 285 issue argument.

As a result, the agent can continue with feature 286 and modify its clarification or planning artifacts. No target-mismatch error is produced.

Specify CLI Version

1.0.1

AI Agent

Codex CLI

Operating System

macOS 26.6 (Darwin 25.6.0, arm64)

Python Version

Python 3.13.5

Error Logs

$ cat .specify/feature.json
{
  "feature_directory": "specs/286-tenant-pd-ordering"
}

$ .specify/scripts/bash/check-prerequisites.sh --json --paths-only
{
  "BRANCH": "286-tenant-pd-ordering",
  "FEATURE_DIR": ".../specs/286-tenant-pd-ordering",
  "FEATURE_SPEC": ".../specs/286-tenant-pd-ordering/spec.md",
  "IMPL_PLAN": ".../specs/286-tenant-pd-ordering/plan.md",
  "TASKS": ".../specs/286-tenant-pd-ordering/tasks.md"
}

Explicit workflow input:
https://github.com/example/project/issues/285

No error is emitted for the 285 versus 286 mismatch.

Additional Context

The Specify CLI reports Python 3.11.15 as its bundled runtime, while the system python3 --version reports Python 3.13.5.

The resolver’s current priority is:

1. SPECIFY_FEATURE_DIRECTORY
2. .specify/feature.json
3. Error when no feature context exists

An issue URL supplied to a generated Spec Kit command is not part of this resolution or validation process.

This report concerns the safety behavior of generated Spec Kit workflows, not merely the persisted-feature resolver. Resolving from .specify/feature.json is valid when no explicit target is supplied. The defect is allowing an explicit target and persisted target to disagree without a mandatory abort.

A backward-compatible fix could activate target validation only when command input contains a recognizable issue URL, number, numeric feature identifier, or specs/<number>-<slug> path.

[github-actions]

Bug assessment — explicit-issue-feature-mismatch: Valid · severity medium

---

Bug Assessment: Explicit Issue Target Not Validated Against Persisted Feature Context

• Slug: explicit-issue-feature-mismatch
• Created: 2026-09-01T12:25:38Z
• Source: issue [Bug]: Explicit issue target is not validated against persisted feature context #4387
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @grafvonb. When a user invokes a Spec Kit workflow command (e.g., $speckit-clarify) with an explicit GitHub issue URL (issue 285), while .specify/feature.json points to a different feature (286), the prerequisite resolution script returns feature 286 without error. The generated AI workflow has no logic to detect or abort on this mismatch. As a result, the agent silently operates on feature 286 while the user believes they are working on feature 285.

Spec Kit version 1.0.1, Codex CLI agent, macOS 26.6, Python 3.13.5.

Symptom

When an explicit issue URL is passed as $ARGUMENTS to a generated Spec Kit command (e.g., clarify, plan), the command ignores the argument's embedded issue identity and always acts on the feature resolved from .specify/feature.json or SPECIFY_FEATURE_DIRECTORY. No warning or abort is emitted when the two disagree.

Expected: If an explicit issue number/URL is supplied and it conflicts with the persisted active feature, abort with a clear Feature context mismatch error before reading or writing any feature artifacts.

Reproduction

1. Create two feature directories: specs/285-semantic-milestones and specs/286-tenant-pd-ordering.
2. Set .specify/feature.json to {"feature_directory": "specs/286-tenant-pd-ordering"}.
3. Run $speckit-clarify https://github.com/example/project/issues/285.
4. Observe that check-prerequisites.sh --json --paths-only resolves FEATURE_DIR to specs/286-tenant-pd-ordering.
5. Observe that the Codex agent (or any other) proceeds with feature 286, modifying its spec.md — no mismatch error is emitted.

Suspected Code Paths

• templates/commands/clarify.md (line 16: $ARGUMENTS) — The template surfaces user arguments to the AI but gives zero instructions to extract an issue number/URL from $ARGUMENTS and compare it to the resolved FEATURE_DIR. The AI simply receives both pieces of data independently with no reconciliation step mandated.
• templates/commands/plan.md (line 20: $ARGUMENTS) — Same absence of argument-vs-feature-dir reconciliation logic.
• scripts/bash/check-prerequisites.sh — The script accepts only flags related to feature resolution and validation of artifact existence; it has no --issue or --expected-feature parameter to enforce cross-checking.
• scripts/bash/common.sh (lines 163–226, get_feature_paths) — Resolution priority is SPECIFY_FEATURE_DIRECTORY → .specify/feature.json → error. Issue URLs passed as workflow arguments are entirely outside this pipeline; they are not an input to get_feature_paths and never compared against its output.
• scripts/python/check_prerequisites.py — Counterpart to the shell script; same absence of issue-target parameter (not reviewed in full but confirmed by template's scripts: frontmatter indicating equivalent behavior).

Root Cause Hypothesis

The template commands (clarify.md, plan.md, and likely analyze.md, converge.md, etc.) were designed around a single active-feature model where the feature is always already established before the command runs. The $ARGUMENTS slot was added later to pass free-form user context to the AI, but the template workflow instructions were never updated to define what the AI must do when $ARGUMENTS contains a recognizable feature identity (issue URL, bare issue number, or specs/NNN-* path). Because the AI only sees a loosely defined role for $ARGUMENTS, it treats the argument as supplementary context rather than as a binding target assertion. There is no guard at either the script layer (which could validate --expected-issue) or the template layer (which could mandate a mismatch abort). Confidence: high — the template source and script source both confirm the absence of any reconciliation step.

Proposed Remediation

Preferred: Add an explicit mismatch-detection step to the affected command templates' workflow instructions. In the "Pre-Execution Checks" section of clarify.md (and analogous templates), after the {SCRIPT} run resolves FEATURE_DIR, mandate the following agent behaviour:

If $ARGUMENTS contains a recognizable issue identity (GitHub issue URL, bare integer, or specs/NNN-* path), extract the numeric issue identifier and compare it against the numeric prefix of the resolved FEATURE_DIR basename. If they differ, abort immediately with a message of the form:

ERROR: Feature context mismatch.
Requested target: GitHub issue <N>
Active feature:   <FEATURE_DIR>
Persisted by:     .specify/feature.json

Run the specify workflow for issue <N>, or switch the active feature first.

Do not read or write any feature artifact until the mismatch is resolved.

This is a template-only change — no script modifications needed for the core fix — making it low-risk and backward-compatible. Commands invoked without an explicit issue argument are unaffected (no $ARGUMENTS → no validation triggered).

Alternative: Add --expected-issue <N> to check-prerequisites.sh (and its Python/PowerShell counterparts) so the script itself errors when FEATURE_DIR's numeric prefix does not match <N>. The template would extract the issue number and pass it to the script. This is a stronger, more deterministic guard (script exits with non-zero before the AI proceeds), but requires coordinated changes to three script variants and all affected templates, with a higher risk of breaking existing automation that calls the script directly without the new flag.

Files likely to change:

• templates/commands/clarify.md (add mismatch-detection step to workflow instructions)
• templates/commands/plan.md (same)
• templates/commands/analyze.md (likely same pattern)
• templates/commands/converge.md (likely same pattern)
• templates/commands/implement.md (review for same pattern)
• Potentially scripts/bash/check-prerequisites.sh, scripts/powershell/check-prerequisites.ps1, scripts/python/check_prerequisites.py if the alternative approach is chosen

Tests to add or update:

• Integration test: invoke the clarify/plan workflow stub with $ARGUMENTS containing an issue URL whose number conflicts with the resolved FEATURE_DIR; assert the workflow output contains the mismatch error string and no feature artifact is modified.
• Unit test for the numeric-prefix extraction helper if one is introduced.
• Regression test: invoke without any $ARGUMENTS and confirm no spurious mismatch error is produced.

Risks & Considerations

• Backward compatibility: Changes are additive — only triggered when $ARGUMENTS contains a recognizable issue identity. Existing use of commands without explicit issue arguments is unaffected.
• AI variability: Template-only fixes rely on the AI following the new instructions correctly. The alternative script-layer fix is more deterministic.
• Chained commands: The report notes that downstream chained commands (e.g., "run the plan") inherit the wrong persisted target. The template fix addresses the first command in a chain; a follow-on task should ensure chained invocations re-check the active feature or carry it explicitly.
• Numeric prefix convention: The fix assumes feature directories follow the NNN-slug naming convention. Projects that deviate would need a fallback path.

Open Questions

• [NEEDS CLARIFICATION: Which additional command templates beyond clarify and plan accept issue URLs in $ARGUMENTS and need the same guard?]
• [NEEDS CLARIFICATION: Should the mismatch error offer an interactive "switch active feature to 285 and continue?" prompt, or always abort?]

---

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

Generated by 🐛 Assess Bug from Labeled Issue for issue #4387 · 155.5 AIC · ⌖ 11 AIC · ⊞ 34.2K · ◷