setup-plan.ps1 silently ignores unrecognized positional arguments (setup-tasks.ps1 rejects them)

[kurtvalcorza]

Summary

scripts/powershell/setup-plan.ps1 captures extra positional arguments via ValueFromRemainingArguments but never validates them, so a misspelled or unsupported option is silently ignored and the script reports success. Its sibling setup-tasks.ps1 rejects the same input.

The inconsistency

scripts/powershell/setup-plan.ps1 captures but never checks:

    # Capture extra positional arguments to match Bash/Python behavior.
    [Parameter(ValueFromRemainingArguments = $true)]
    [string[]]$RemainingArgs
)

scripts/powershell/setup-tasks.ps1:20-23 does check:

if ($RemainingArgs.Count -gt 0) {
    [Console]::Error.WriteLine("ERROR: Unknown option '$($RemainingArgs[0])'")
    exit 1
}

Impact

In automation, ./setup-plan.ps1 -Jsonn (or any unsupported positional) proceeds as though no option were passed, creates or reports a plan, and exits 0. The invocation error is masked rather than surfaced — the failure mode setup-tasks.ps1 was explicitly changed to prevent.

Suggested fix

Mirror setup-tasks.ps1: validate after help handling and before any filesystem work, so -Help still wins and exits 0 consistently with the Bash/Python variants.

if ($Help) { ...; exit 0 }

if ($RemainingArgs.Count -gt 0) {
    [Console]::Error.WriteLine("ERROR: Unknown option '$($RemainingArgs[0])'")
    exit 1
}

Worth checking the other scripts/powershell/*.ps1 entry points for the same gap — this looks like validation added to setup-tasks.ps1 that wasn't propagated to its siblings.

Version

Reproduced on main @ c0fe0e4 (v0.14.2).

Found by an automated review pass over a vendored copy in a downstream project; verified against upstream main before filing.

[github-actions]

Bug assessment — setup-plan-silent-args: Valid · severity low

---

Bug Assessment: setup-plan.ps1 silently ignores unrecognized positional arguments

• Slug: setup-plan-silent-args
• Created: 2026-07-27T13:39:29Z
• Source: issue setup-plan.ps1 silently ignores unrecognized positional arguments (setup-tasks.ps1 rejects them) #3750
• Verdict: valid
• Severity: low

Report (summarized)

Reported by @kurtvalcorza (v0.14.2, commit c0fe0e4).

scripts/powershell/setup-plan.ps1 declares $RemainingArgs via ValueFromRemainingArguments to capture unknown positional arguments but never checks whether any were passed — so a typo like -Jsonn is silently discarded and the script exits 0 as if everything was fine. Its sibling setup-tasks.ps1 explicitly validates $RemainingArgs and exits 1 with an error message. The reporter also suggests checking other *.ps1 entry points for the same gap.

Symptom

Running ./setup-plan.ps1 -Jsonn (or any unrecognized positional) succeeds silently instead of rejecting the unknown argument with a non-zero exit. Expected behavior (consistent with setup-tasks.ps1 and the Bash/Python variants) is an error message on stderr and exit 1.

Reproduction

1. Clone the repository at main.
2. Navigate to a directory with a valid Spec Kit init (or set the required env vars for Get-FeaturePathsEnv).
3. Run pwsh scripts/powershell/setup-plan.ps1 -Jsonn.
4. Actual: script runs normally, outputs plan paths, exits 0.
5. Expected: ERROR: Unknown option '-Jsonn' on stderr, exit 1.

Suspected Code Paths

• scripts/powershell/setup-plan.ps1:8-11 — $RemainingArgs is captured but never validated; no guard block exists between the $Help check (line 16) and the filesystem work (line 27).
• scripts/powershell/setup-tasks.ps1:20-22 — the correct pattern that is missing from setup-plan.ps1:

  if ($RemainingArgs.Count -gt 0) {
      [Console]::Error.WriteLine("ERROR: Unknown option '$($RemainingArgs[0])'")
      exit 1
  }

• scripts/powershell/create-new-feature.ps1:13 — also uses ValueFromRemainingArguments; does not appear to validate $RemainingArgs either (same potential gap noted by the reporter).
• scripts/powershell/check-prerequisites.ps1 — does not declare $RemainingArgs, unaffected.

Root Cause Hypothesis

The validation block was added to setup-tasks.ps1 (likely during a fix or review pass) but was not back-propagated to setup-plan.ps1. Both scripts have structurally identical parameter blocks but diverged on the post-param guard. Confidence: high — the code is directly inspectable and the discrepancy is unambiguous.

Proposed Remediation

Preferred: Mirror setup-tasks.ps1 in setup-plan.ps1. After the $Help block and before any filesystem work, insert:

if ($RemainingArgs.Count -gt 0) {
    [Console]::Error.WriteLine("ERROR: Unknown option '$($RemainingArgs[0])'")
    exit 1
}

This matches the placement in setup-tasks.ps1 (lines 20-22), preserves the -Help early-exit (exit 0), and is consistent with the Bash and Python variants that reject unknown arguments.

While applying the fix, audit create-new-feature.ps1 for the same gap — it also captures ValueFromRemainingArguments (line 13) and should receive the same guard if it lacks one.

Alternatives:

• Use PowerShell's [CmdletBinding(PositionalBinding=$false)] to make unrecognized positionals a runtime error automatically. Trade-off: changes the error message format and may differ from the wording the other scripts emit — inconsistent UX across the script family.

Files likely to change:

• scripts/powershell/setup-plan.ps1
• scripts/powershell/create-new-feature.ps1 (if same gap confirmed)
• tests/test_setup_plan_python_parity.py (or a new test file) to add a test case for unknown-argument rejection

Tests to add or update:

• Add a parity test asserting that setup-plan.ps1 -Unknownoption exits non-zero and writes to stderr — symmetric with how setup-tasks.ps1 behavior is tested.
• Verify -Help still exits 0 even when a bad argument precedes it (or document ordering behavior).

Risks & Considerations

• Low blast radius: this is a CLI argument-validation gap, not a data-loss or security issue. Scripts invoked with correct arguments are entirely unaffected.
• Automation impact: CI/CD pipelines that accidentally pass a misspelled flag will now fail explicitly rather than silently; this is the desired outcome but callers should be aware.
• No API breakage: the fix only adds a guard; it does not change behavior for valid invocations.

Open Questions

• Does create-new-feature.ps1 also lack the $RemainingArgs validation? (Likely yes based on grep — worth confirming before the fix is merged.)

---

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

Generated by 🐛 Assess Bug from Labeled Issue for issue #3750 · 97.8 AIC · ⌖ 11.1 AIC · ⊞ 32.7K · ◷

[github-actions]

Bug-fix stage blocked — assessment remediation is incorrect

After examining the codebase, the proposed fix (mirroring setup-tasks.ps1's $RemainingArgs rejection) would break existing, intentional behavior and is not the right remediation.

What the investigation found:

• scripts/bash/setup-plan.sh silently ignores unknown arguments — they accumulate in ARGS but ARGS is never validated.
• scripts/python/setup_plan.py explicitly documents this: "Other arguments are accepted and silently ignored, matching setup-plan.sh."
• There is an existing parity test (test_all_variants_ignore_extra_arguments in tests/test_setup_plan_python_parity.py, lines 83–100) that asserts all three variants (bash, powershell, python) return exit code 0 when given a bogus extra argument.

The divergence between setup-plan and setup-tasks is by design, not a bug:

Script family	Unknown arg behavior
setup-plan.* (bash, python, ps1)	Silently ignored (intentional)
setup-tasks.* (bash, ps1)	Rejected, exit 1 (intentional)

Applying the assessment's proposed fix to setup-plan.ps1 would:

1. Break the existing test_all_variants_ignore_extra_arguments parity test.
2. Diverge from the bash and Python siblings it is supposed to mirror.

Recommendation: Re-run the bug-assess stage with this additional context. The issue body's claim that "setup-tasks.ps1 was explicitly changed to prevent" silent ignoring does not mean setup-plan.ps1 should follow — the two scripts have different contracts. The fix-blocked label does not exist in this repository, so no label change is made here.

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

Generated by 🛠️ Fix Bug from Labeled Issue for issue #3750 · 173.2 AIC · ⌖ 10.6 AIC · ⊞ 35K · ◷

[github-actions]

Bug assessment — setup-plan-silent-args: Invalid · not a bug (by-design behavior, existing parity contract)

---

Bug Assessment: setup-plan.ps1 silently ignores unrecognized positional arguments

• Slug: setup-plan-silent-args
• Created: 2026-07-27T18:29:27Z
• Source: issue setup-plan.ps1 silently ignores unrecognized positional arguments (setup-tasks.ps1 rejects them) #3750
• Verdict: invalid
• Severity: n/a

Note: A previous bug-assess run on this issue produced an incorrect verdict of "valid / low severity." The bug-fix stage later discovered the error and flagged it. This re-assessment supersedes the prior one.

Report (summarized)

Reported by @kurtvalcorza (v0.14.2, commit c0fe0e4). The reporter observed that scripts/powershell/setup-plan.ps1 captures unknown positional arguments via $RemainingArgs but never validates them, while scripts/powershell/setup-tasks.ps1 rejects the same input with exit 1. The report characterizes this as an inconsistency and suggests propagating the validation from setup-tasks.ps1 to setup-plan.ps1.

Symptom

setup-plan.ps1 exits 0 when passed an unrecognized argument (e.g. -Jsonn). setup-tasks.ps1 exits 1 in the same situation. The reporter treats the latter as the correct pattern.

Reproduction

1. Run pwsh scripts/powershell/setup-plan.ps1 -Jsonn.
2. Actual: exits 0, outputs plan paths normally.
3. Expected (per report): exits 1 with ERROR: Unknown option.

Suspected Code Paths

• scripts/powershell/setup-plan.ps1:8-11 — $RemainingArgs declared but no rejection guard.
• scripts/powershell/setup-tasks.ps1:20-22 — rejection guard present.
• scripts/bash/setup-plan.sh:7,21 — ARGS array accumulates remaining args; never validated.
• scripts/python/setup_plan.py:38 — explicitly documents: "Other arguments are accepted and silently ignored, matching setup-plan.sh."
• tests/test_setup_plan_python_parity.py:83-100 — parity test test_all_variants_ignore_extra_arguments asserts that all three variants (bash, powershell, python) return exit 0 with a bogus --bogus argument.

Root Cause Hypothesis

There is no defect. The setup-plan script family (bash, powershell, python) intentionally ignores unknown arguments. The setup-tasks family intentionally rejects them. These are different contracts for different scripts:

Script family	Unknown-arg behavior	Evidence
setup-plan.{sh,ps1,py}	Silently ignored (intentional)	setup_plan.py comment; parity test line 94
setup-tasks.{ps1}	Rejected, exit 1 (intentional)	Explicit guard at setup-tasks.ps1:20-22

The divergence the reporter observed is the result of a deliberate design choice, not an oversight. Confidence: high — both the Python source comment and the parity test fixture are unambiguous.

Proposed Remediation

No code change required. The behavior is correct and is locked in by test_all_variants_ignore_extra_arguments. Applying the reporter's suggested fix would:

1. Break the existing parity test at tests/test_setup_plan_python_parity.py:94.
2. Diverge setup-plan.ps1 from its bash and Python siblings, which also silently ignore unknown arguments.

The issue can be closed as "not a bug / by design."

If the silent-ignore contract is itself considered undesirable in a future design review, changing it would require updating all three setup-plan variants and their parity tests simultaneously — that is a separate feature/design decision, not a bug fix.

Risks & Considerations

• Closing as invalid carries no risk to existing behavior.
• If the team later decides to make setup-plan reject unknown args, all three variants and the parity test must change together.

Open Questions

• Should the setup-plan vs. setup-tasks behavioral contract difference be documented (e.g., in a script README or inline comment) to prevent future confusion?

Generated by 🐛 Assess Bug from Labeled Issue for issue #3750 · 130 AIC · ⌖ 10.7 AIC · ⊞ 32.7K · ◷

[mnriem]

As per bug assessment closing this as invalid