[Bug]: check-prerequisites.ps1 writes errors to stdout, corrupting --json output

[Quratulain-bilal]

Bug Description

the powershell check-prerequisites.ps1 writes its validation errors and run-hints with Write-Output, which goes to stdout. this script is normally run with -Json and the agent parses its stdout as json. when validation fails (e.g. plan.md is missing), the error text lands on stdout instead of json, so the consumer gets something like ERROR: plan.md not found ... where it expects a json object, and parsing breaks.

the bash counterpart doesn't have this - it sends the same errors to stderr (>&2), keeping stdout clean. the sibling powershell scripts are also fine: setup-tasks.ps1 and common.ps1's Get-FeaturePathsEnv both use [Console]::Error.WriteLine. only check-prerequisites.ps1 is the odd one out.

Steps to Reproduce

1. in a spec-kit project with a feature dir but no plan.md, run:
   pwsh .specify/scripts/powershell/check-prerequisites.ps1 -Json
2. capture stdout only (e.g. redirect stderr away).
3. observe stdout contains the error string instead of json.

compare with bash:
bash .specify/scripts/bash/check-prerequisites.sh --json - stdout stays empty, the error goes to stderr.

Expected Behavior

errors and run-hints go to stderr; stdout only ever carries the json (or the documented text payload). both shells behave the same.

Actual Behavior

the six error/hint lines (check-prerequisites.ps1 lines 86, 88, 93, 95, 101, 103 on main) use Write-Output, so they go to stdout and pollute the -Json output.

Additional Context

suggested fix: switch those six lines to [Console]::Error.WriteLine, matching the bash script and the other powershell scripts. small diff.

note: i used an ai assistant to help investigate and write this up.

[github-actions]

Bug assessment — check-prerequisites-stderr: Valid · severity medium

---

Bug Assessment: check-prerequisites.ps1 writes errors to stdout

• Slug: check-prerequisites-stderr
• Created: 2026-06-23T16:08:34Z
• Source: issue [Bug]: check-prerequisites.ps1 writes errors to stdout, corrupting --json output #3122
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @Quratulain-bilal. When check-prerequisites.ps1 is run with the -Json flag and validation fails (missing feature directory, missing plan.md, or missing tasks.md), the error messages and run-hint lines land on stdout rather than stderr. Because callers parse stdout as JSON, the error strings corrupt the JSON payload and cause parse failures. The bash counterpart (check-prerequisites.sh) correctly uses >&2 for the same messages, as do sibling PowerShell scripts (setup-tasks.ps1, common.ps1).

Symptom

When validation fails, check-prerequisites.ps1 -Json emits plain-text error strings to stdout (e.g. ERROR: plan.md not found in ...) instead of to stderr, causing callers that parse stdout as JSON to receive invalid JSON. The bash script and sibling PowerShell scripts do not share this flaw.

Reproduction

1. In a spec-kit project that has a feature directory but no plan.md, run:

   pwsh .specify/scripts/powershell/check-prerequisites.ps1 -Json 2>/dev/null
   

2. Observe that stdout contains ERROR: plan.md not found in ... — not valid JSON.
3. Compare with bash .specify/scripts/bash/check-prerequisites.sh --json 2>/dev/null — stdout is empty; the error goes to stderr only.

Trigger variations (three distinct validation paths):

• Feature directory missing → lines 86–89 fire.
• plan.md missing → lines 93–96 fire.
• tasks.md missing (with -RequireTasks) → lines 101–104 fire.

Suspected Code Paths

• scripts/powershell/check-prerequisites.ps1:86 — Write-Output "ERROR: Feature directory not found: ..." should be [Console]::Error.WriteLine(...)
• scripts/powershell/check-prerequisites.ps1:88 — Write-Output "Run $specifyCommand ..." should be [Console]::Error.WriteLine(...)
• scripts/powershell/check-prerequisites.ps1:93 — Write-Output "ERROR: plan.md not found ..." should be [Console]::Error.WriteLine(...)
• scripts/powershell/check-prerequisites.ps1:95 — Write-Output "Run $planCommand ..." should be [Console]::Error.WriteLine(...)
• scripts/powershell/check-prerequisites.ps1:101 — Write-Output "ERROR: tasks.md not found ..." should be [Console]::Error.WriteLine(...)
• scripts/powershell/check-prerequisites.ps1:103 — Write-Output "Run $tasksCommand ..." should be [Console]::Error.WriteLine(...)

For reference, scripts/powershell/setup-tasks.ps1:23,25,30,32 and scripts/powershell/common.ps1:49,58,167,177,181 already use [Console]::Error.WriteLine(...) correctly — confirming the project's established pattern.

Root Cause Hypothesis

The six error/hint Write-Output calls were likely written without the -Json consumer use-case in mind, or were copied before the project settled on [Console]::Error.WriteLine as the stderr idiom. Because Write-Output in PowerShell always writes to the success (stdout) stream, any caller that only reads stdout to parse JSON receives the error text as the entire payload. Confidence: high — the defective lines are directly visible in the file and the bash parity confirms the intent.

Proposed Remediation

Preferred: Replace all six Write-Output calls in the three validation blocks (lines 86, 88, 93, 95, 101, 103) with [Console]::Error.WriteLine(...), exactly matching the pattern already used in setup-tasks.ps1 and common.ps1. This is a six-line, mechanical substitution with no logic changes.

Example for the first block:

# Before
Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
$specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
Write-Output "Run $specifyCommand first to create the feature structure."

# After
[Console]::Error.WriteLine("ERROR: Feature directory not found: $($paths.FEATURE_DIR)")
$specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
[Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")

Alternatives:

• Use Write-Error — works, but Write-Error produces a formatted error record which may include extra decoration in some hosts; [Console]::Error.WriteLine emits a clean string matching the bash style.
• Use $Host.UI.WriteErrorLine(...) — also writes to stderr cleanly, but [Console]::Error.WriteLine is already the established pattern here and is host-independent.

Files likely to change:

• scripts/powershell/check-prerequisites.ps1 (6 one-line edits)
• tests/test_check_prerequisites_paths_only.py (tighten the existing test at line 228 to assert errors appear on result.stderr and not on result.stdout, rather than checking the combined string)

Tests to add or update:

• test_ps_normal_mode_still_validates_branch (and equivalents for the plan.md and tasks.md paths): currently checks result.stdout + result.stderr for the error string (line 228). Add assertions that result.stdout is empty (or valid JSON) and result.stderr contains the error — matching the bash parity tests.
• Add new test cases for -Json -RequireTasks with a missing tasks.md on PowerShell, verifying stdout is either empty or valid JSON on failure.

Risks & Considerations

• Minimal blast radius: the change is purely cosmetic from the caller's perspective — error messages already cause a non-zero exit code, so callers that only check the exit code are unaffected. Only callers that also parse stdout are impacted (which is exactly the -Json use case this fixes).
• No API breakage: the JSON schema on the success path is unchanged.
• Parity verification: after the fix, running both check-prerequisites.sh --json and check-prerequisites.ps1 -Json under the same failure conditions should produce identical routing: error to stderr, empty/absent stdout.
• No migration or security concern: pure script fix with no data model or auth changes.

Open Questions

None — the report is well-supported by the code.

---

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

Generated by 🐛 Assess Bug from Labeled Issue for issue #3122 · 138.6 AIC · ⌖ 13.6 AIC · ⊞ 31.7K · ◷