chore: Move the build toolchain to psake 5.0.4

[tablackburn]

Summary

• Move this repository's build toolchain from psake 4.9.0 to 5.0.4 in requirements.psd1
• Guard the Set-BuildEnvironment call in tests/Manifest.tests.ps1, without which psake 5.x
  fails the whole test container and the suite silently loses 12 tests
• Deliberately no changelog or migration-guide entry — nothing here is user-facing

Two files, +7 −2. Scope and shape come from the #155 spike, which found this is a single small
PR rather than a chain. Closes #161.

What did not change, deliberately

The manifest's RequiredModules floor stays at psake 4.9.0. PowerShellBuild's task
definitions are unchanged and run on both majors — task names, task dependencies, and the
$PSBPreference contract are identical under 5.0.4 — so raising the floor would force an
upgrade on consumers for no functional gain. This mirrors the Pester decision recorded in #120
(RequiredModules stayed at 5.6.1 for the same reason).

No changelog or migration-guide entry. requirements.psd1 is this repository's own build
toolchain, not anything a consumer touches, and because the manifest floor is unchanged,
upgrading PowerShellBuild 0.8.x → 1.0.0 does not move anyone to psake 5.x. The psake 5.x
behavior differences are triggered by upgrading psake, and
psake's own v4 → v5 guide
is their proper home. If a later change raises the manifest floor to psake 5.x, that change
adds the migration entry, where it will be correct. (Recorded as the "Changelog and guide
scope" decision on #120.)

Also out of scope, per #155: psake 5.x's Version 5 declaration and Properties @{} hashtable
syntax are available but not adopted here, and none of the #117 extras (task caching, LLM
output, Format-PSBuildResult) come along.

The test guard

tests/Manifest.tests.ps1 called Set-BuildEnvironment -Force in BeforeAll. BuildHelpers'
Get-BuildVariable uses break inside switch blocks, and that break can unwind out of the
block. psake 4.9.x's task invocation absorbs it; psake 5.x's does not, so Pester fails the
entire container (pester/Pester#2669) and the
suite silently drops from 428 to 418 passing.

build.ps1 calls Set-BuildEnvironment -Force unconditionally before Invoke-psake
(build.ps1:56), so by the time this BeforeAll runs the variables are already set and the
second call is redundant. Guarding on that makes it short-circuit during a build, so the
escaping break never fires. The complete change to tests/Manifest.tests.ps1:

BeforeAll {
    # Only call Set-BuildEnvironment when the build variables are not already present.
    # build.ps1 sets them before Invoke-psake, so inside a build this is a no-op; standalone
    # Pester runs still get them. Calling it unconditionally lets an escaping 'break' from
    # BuildHelpers' Get-BuildVariable switch blocks unwind out of this BeforeAll, which
    # psake 4.9.x absorbs but psake 5.x does not -- Pester then fails the whole container.
    if (-not $env:BHProjectName) { Set-BuildEnvironment -Force }
    ...

build.ps1 itself is not modified by this PR. A dummy enclosing loop does not absorb the
break — tested and rejected.

This interaction is not documented upstream. It stays recorded where it is actionable: the
comment above, and the full spike findings in #155. Worth reporting to BuildHelpers separately.

Test Plan

• Full suite under psake 5.0.4 — 428 passed / 0 failed
• Full suite under psake 4.9.1 — 428 passed / 0 failed (backs the "consumers are not
  forced to upgrade" claim; the manifest still allows 4.9.x)
• Standalone Invoke-Pester on tests/Manifest.tests.ps1 with a cleared environment —
  10 passed / 0 failed, so the guard does not break out-of-build runs
• CI green on all legs, including CI / Run Tests (Windows PowerShell 5.1) — the one
  thing that could not be verified locally, since the spike ran on pwsh 7.6.5/Windows only
  and 5.1 is a supported v1.0.0 floor
• All four breaking changes in psake's v4 → v5 guide checked against this repo; none apply
  (default.ps1 auto-detection — we pass -buildFile explicitly; the psake.ps1/psake.cmd
  launchers — we use Import-Module + Invoke-psake; .NET Framework < 4.0 and the
  $framework global — unused)

Each local run used an isolated module root prepended to PSModulePath so exactly one psake
version was resolvable — verified for Start-Job children too, since build.tests.ps1 and
IBTasks.tests.ps1 spawn child builds.

To reproduce the failure this fixes, revert tests/Manifest.tests.ps1 and run the suite under
psake 5.x: Manifest.tests.ps1 fails as a container and the count drops to 418.

Breaking Changes

None. The consumer-facing surface — RequiredModules, task names, task dependencies, and the
$PSBPreference contract — is untouched.

Reviewer notes

• Please squash-merge. The branch has three commits including a docs entry that was added
  and then removed once we settled that this change is not user-facing. The net diff is the two
  files above; the intermediate history is not worth keeping.
• Known coverage gap: the manifest claims psake ≥ 4.9.0 support, but CI now exercises only
  5.0.4. The psake-4 result above was measured locally, not in CI. Continuously testing that
  claim needs a side-by-side matrix like requirements.pester-matrix.psd1. Not added here — it
  is scope beyond psake 5.x migration: bump the pin to 5.0.4 and record the behavior change #161, and it is raised on [Tracking] PowerShellBuild v1.0.0 roadmap #120 as open fog rather than decided inside this PR.

Spike evidence: #155. Part of #120.

[Copilot]

Pull request overview

Updates the repository’s build/test toolchain to use psake 5.0.4 while keeping the module manifest’s consumer minimum at psake 4.9.0, and documents the resulting consumer-visible behavior changes for psake 5.x adopters.

Changes:

• Bump the pinned build dependency in requirements.psd1 from psake 4.9.0 to 5.0.4.
• Add a guard in tests/Manifest.tests.ps1 to avoid calling Set-BuildEnvironment when BuildHelpers variables are already present.
• Document psake 5.x behavioral differences in the migration guide and record the bump in the changelog.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
requirements.psd1	Pins psake to 5.0.4 for this repo’s build/tooling dependency set.
tests/Manifest.tests.ps1	Guards Set-BuildEnvironment in BeforeAll to avoid a psake 5.x container-failing edge case.
docs/migration-v0.8-to-v1.0.md	Adds a migration entry explaining psake 5.x behavior changes and mitigations.
CHANGELOG.md	Adds an Unreleased note describing the toolchain bump and links to migration guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Test Results

    4 files  ±0    696 suites  ±0   3m 23s ⏱️ -18s
  436 tests ±0    434 ✅ ±0   2 💤 ±0  0 ❌ ±0 
1 748 runs  ±0  1 701 ✅ ±0  47 💤 ±0  0 ❌ ±0 

Results for commit f9dfeef. ± Comparison against base commit f726f48.

♻️ This comment has been updated with latest results.

[tablackburn]

CI is green on every leg, including CI / Run Tests (Windows PowerShell 5.1) (3m21s).

That was the one thing this PR could not verify locally — the #155 spike and my local runs were pwsh 7.6.5 on Windows only, and Windows PowerShell 5.1 is a supported v1.0.0 floor. psake 5.0.4 works on 5.1, so the last open question about the psake bump is settled and I have cleared it from #120's fog.

The other reviewer note stands and is a genuine judgement call for you: CI now exercises only psake 5.0.4 while the manifest still claims psake >= 4.9.0. Both majors passed 428/0 locally, but that compatibility is no longer continuously tested. Raised on #120 as fog rather than decided here.