Decide: raise the consumer psake floor to 5.x before 1.0.0

[tablackburn]

Part of #120 (Phase 3 — API improvements). Follow-up to #155 / #161 / #162.

Question

Before 1.0.0 ships: should RequiredModules in PowerShellBuild.psd1 raise the psake floor
from 4.9.0 to 5.0.4, or stay at 4.9.0?

#162 moved this repository's own build toolchain to psake 5.0.4 and deliberately left the
consumer floor at 4.9.0. That split was the right call for the toolchain change, but it
leaves the module supporting two psake majors indefinitely, and 1.0.0 is the cheapest moment
to change a floor — the hard-cut-plus-migration-guide strategy is already locked in for this
release.

Decision recorded so far: keeping 4.9.0 for now (@tablackburn, 2026-08-22). This ticket
is to assess it properly rather than let the status quo win by default.

Framing that matters

RequiredModules = @{ModuleName = 'psake'; ModuleVersion = '4.9.0'} declares a minimum,
not a pin. Consumers already on psake 5.x satisfy it today. So this is not "can consumers use
psake 5" — they can. Raising the floor is a decision to stop supporting psake 4.x.

Assess

For raising to 5.0.4

• One supported psake major means PowerShellBuild/psakeFile.ps1 only has to be correct
  against one task-runner API, and the test matrix only has to prove it against one
• psake 5 surfaces failures that 4.9.x silently absorbed. The break-escape found in psake 5.x spike: assess breakage under psake 5.0.4 (clean bump, no extras) #155 is
  the concrete example: under psake 4 a break escaping a Pester BeforeAll was swallowed,
  under psake 5 it fails the build. A consumer on psake 4 has build failures that do not fail
  their build
• A floor raised at 1.0.0 costs one migration-guide entry; raised at 1.1.0 it costs a major

For staying at 4.9.0

• Nothing in the shipped tasks needs psake 5 — the module works under both today
• Consumers pin psake in CI. Excluding 4.9.x forces a coordinated upgrade on people whose
  builds are working fine
• psake 4.9.1 is what most installs have; the adoption curve for 5.x is young
• The floor can be raised later in a major without ever having claimed support it did not have

Facts to gather before deciding

1. psake 5.0.4's own support floor — its PowerShellVersion and CompatiblePSEditions.
   PowerShellBuild committed to Windows PowerShell 5.1 (Desktop) in [Tracking] PowerShellBuild v1.0.0 roadmap #120. If psake 5 does not
   support Desktop edition, raising the floor contradicts a decision already made and the
   assessment ends there
2. What psake 4 → 5 changes for a consumer's own psakeFile, not just for ours — the
   migration notes reviewed during psake 5.x spike: assess breakage under psake 5.0.4 (clean bump, no extras) #155 are the starting point
3. Whether PowerShellBuild/psakeFile.ps1 has any version-conditional behavior today, or
   whether supporting both majors is currently free
4. PSGallery adoption signal for psake 5.x versus 4.9.x, as a rough proxy for how much
   real-world breakage a raised floor causes

Done when

The decision is recorded here with its rationale, and:

• If raising — a ticket exists for the manifest change plus a migration-guide entry, and it is
  sequenced before the 1.0.0 release
• If keeping — the migration guide says so explicitly, so consumers on psake 4.x know it is a
  supported configuration rather than an oversight

Out of scope

• The psake version this repository builds itself with. That is settled at 5.0.4 by chore: Move the build toolchain to psake 5.0.4 #162 and
  is independent of what consumers are required to have
• RequiredModules floors for BuildHelpers, Pester, or platyPS