fix(setup-windows): auto-reexec under pwsh when running on Windows PowerShell 5.1 (BUG-005)

[mlorentedev]

Summary

• Closes BUG-005 — Windows PowerShell 5.1 silently skipping the Merge-ClaudeSettings template merge introduced by SDD-002 (PR feat(setup): track ai/claude/settings.json template + per-key merge (SDD-002) #51). The function uses ConvertFrom-Json -AsHashtable, a PS 7+ only parameter; on PS 5.1 the wide try/catch misclassifies the ParameterBindingException as a JSON parse error and returns early.
• Adds a preamble at the top of setup-windows.ps1 (right after param()) that detects $PSVersionTable.PSVersion.Major -lt 7. If pwsh (7+) is on PATH, re-execs the script under pwsh with $PSCommandPath @args and exits with the child's exit code. Otherwise fails loud with winget install Microsoft.PowerShell hint + exit 1.
• Windows-only. setup-linux.sh uses bash + jq, no shell-version coupling — verified untouched (negative-parity bats assert locks this in).

Root cause

PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1 resolves PowerShell to Windows PowerShell 5.1 on a stock Windows machine. Merge-ClaudeSettings then calls ConvertFrom-Json -AsHashtable which fails with ParameterBindingException. The function's try { ... } catch { Write-Warn "...not valid JSON..."; return } catches everything and prints the misleading "not valid JSON after placeholder substitution: A parameter cannot be found that matches parameter name 'AsHashtable'" warning. Empirically observed 2026-05-19 in setup output on a Windows 11 22631.6931 admin machine.

Test plan

• 5 new bats asserts in tests/setup-windows.bats (PSVersion detection, pwsh re-exec branch, fail-loud branch + exit 1, BUG-005 cite in inline comment, negative parity on setup-linux.sh)
• Smoke under Windows PowerShell 5.1: first output line is [INFO] Windows PowerShell 5.1.22621.6931 detected; re-executing under pwsh (...) for full feature compatibility (BUG-005). Setup proceeds under pwsh; settings.json merged (1687 bytes, 14 plugins + preserved user customizations); zero AsHashtable warnings.
• Smoke under pwsh 7.6.1 direct: preamble no-op (verified during BUG-004 smoke same day, no [INFO] ... detected line appeared)
• PSScriptAnalyzer clean (4 new PSAvoidUsingWriteHost warnings, style-consistent with existing wrappers; zero new rule classes; zero Errors)
• git diff main..HEAD --stat -- setup-linux.sh empty (Linux untouched)
• CI: GitGuardian, integration (Docker Ubuntu 24.04), lint, lint-powershell, test (bats) — pending CI run

Design decisions (in verification.md)

• Auto re-exec instead of in-place PS 5.1 compatibility — Merge-ClaudeSettings could have been rewritten to convert PSCustomObject to hashtable recursively for PS 5.1 compat (~30 lines of subtle recursion vs ~15 lines of preamble). Chose re-exec because Microsoft is sunsetting Windows PowerShell 5.1 and locking the script to pwsh at the front door lets downstream code freely use modern PS features (ternary, null-conditional, etc.) without future-bug risk.
• Write-Host instead of Write-Info wrapper — the wrapper functions are defined LATER in the script. Preamble runs before any function definition; Write-Host is structurally required. Resulting PSScriptAnalyzer warnings are consistent with the rest of the script.
• @args instead of $PSBoundParameters — current param() is empty; positional @args suffices. Inline comment specifies $PSBoundParameters is the correct forwarding mechanism if named params are added later.
• Don't auto-install pwsh — leaves the install action explicit to the user. Actionable error message is the better UX.

References

• Spec: specs/BUG-005-setup-ps7-reexec/
• Source bug: SDD-002 (PR feat(setup): track ai/claude/settings.json template + per-key merge (SDD-002) #51) introduced Merge-ClaudeSettings with -AsHashtable dependency
• Sibling PR: fix(setup): wrap claude plugin install with .claude.json snapshot/restore guard (BUG-004) #57 (BUG-004 claude-mem-truncate-guard)
• Upstream: PowerShell 7.0 release notes — ConvertFrom-Json -AsHashtable added
• Vault entry: 10_projects/dotfiles/11-tasks.md "BUG-005-setup-ps7-reexec"