chore: Pin Pester 6.0.0 for the repository test suite

instructions/repository-specific.instructions.md

@@ -234,7 +234,11 @@
 
 ## Testing
 
-Tests live in `tests/` and use **Pester 5+** syntax.
+Tests live in `tests/` and run on **Pester 6.0.0** (pinned exactly in `requirements.psd1`;
+see psake/PowerShellBuild#17 for the targeting decision). Write assertions with the classic
+`Should -Be` syntax — valid in both Pester 5 and 6 — rather than the Pester 6-only `Should-*`
+assertion family, so tests remain backportable. The shipped module's own Pester compatibility
+floor (5.0.0 in `Test-PSBuildPester`) is a separate contract and is unchanged.
 
 - Always build the module before running Pester directly — running against source can produce
   incorrect results. Prefer `./build.ps1 -Task Test` over a raw `Invoke-Pester` call.
@@ -262,7 +266,7 @@
 
 - Triggers: manual dispatch, GitHub release published
 - Runs on: `ubuntu-latest`
 - Reads `PSGALLERY_API_KEY` secret, converts to `PSCredential`, runs
   `./build.ps1 -Task Publish -PSGalleryApiKey $cred -Bootstrap`
 
 ## Repo-Specific Conventions
@@ -280,6 +284,9 @@
 - **Script analysis**: PSScriptAnalyzer config is `PowerShellBuild/ScriptAnalyzerSettings.psd1`.
   Default severity threshold for build failure is `Error`. Warnings are reported but don't
   fail the build.
+- **Changelog scope**: `CHANGELOG.md` documents user-facing changes to the shipped module
+  only. Repository-internal changes — development dependencies, CI workflows, this repo's own
+  build scripts, or the test suite — do not get changelog entries.
 - **Spell-checker ignores**: inline comments — `# spell-checker:ignore MAML PSGALLERY`.
 
 ## How Consumers Use This Module
@@ -340,9 +347,9 @@
 | ------------------------- | ---------------------------------------------------- |
 | `$env:BHProjectPath`      | Repository root directory                            |
 | `$env:BHProjectName`      | Module name (from directory structure)               |
 | `$env:BHPSModulePath`     | Path to module source directory                      |
 | `$env:BHPSModuleManifest` | Path to `.psd1` manifest                             |
 | `$env:BHModulePath`       | Same as `BHPSModulePath`                             |
 | `$env:BHBuildSystem`      | Detected CI system (e.g., `GitHubActions`, `Unknown`)|
 | `$env:BHBranchName`       | Current git branch                                   |
 | `$env:BHCommitMessage`    | Latest git commit message                            |

requirements.psd1

@@ -4,7 +4,7 @@
     }
     BuildHelpers     = '2.0.16'
     Pester           = @{
-        Version    = '5.8.0'
+        Version    = '6.0.0'
         Parameters = @{
             SkipPublisherCheck = $true
         }

tests/Help.tests.ps1

@@ -1,4 +1,4 @@
 # Taken with love from @juneb_get_help (https://raw.githubusercontent.com/juneb/PesterTDD/master/Module.Help.Tests.ps1)
 
 BeforeDiscovery {
     function global:FilterOutCommonParams {
@@ -8,7 +8,7 @@
         $params | Where-Object { $_.Name -notin $commonParams } | Sort-Object -Property Name -Unique
     }
 
     $manifest             = Import-PowerShellDataFile -Path $env:BHPSModuleManifest
     $outputDir            = Join-Path -Path $env:BHProjectPath -ChildPath 'Output'
     $outputModDir         = Join-Path -Path $outputDir -ChildPath $env:BHProjectName
     $outputModVerDir      = Join-Path -Path $outputModDir -ChildPath $manifest.ModuleVersion
@@ -44,6 +44,8 @@
         $commandParameters     = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters
         $commandParameterNames = $commandParameters.Name
         $helpLinks             = $commandHelp.relatedLinks.navigationLink.uri
+        $helpParameters        = global:FilterOutCommonParams -Params $commandHelp.Parameters.Parameter
+        $helpParameterNames    = $helpParameters.Name
     }
 
     BeforeAll {
@@ -77,41 +79,50 @@
         ($commandHelp.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty
     }
 
-    It "Help link <_> is valid" -ForEach $helpLinks {
-        (Invoke-WebRequest -Uri $_ -UseBasicParsing).StatusCode | Should -Be '200'
-    }
-
-    Context "Parameter <_.Name>" -Foreach $commandParameters {
-
-        BeforeAll {
-            $parameter         = $_
-            $parameterName     = $parameter.Name
-            $parameterHelp     = $commandHelp.parameters.parameter | Where-Object Name -eq $parameterName
-            $parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() }
-        }
-
-        # Should be a description for every parameter
-        It "Has description" {
-            $parameterHelp.Description.Text | Should -Not -BeNullOrEmpty
-        }
-
-        # Required value in Help should match IsMandatory property of parameter
-        It "Has correct [mandatory] value" {
-            $codeMandatory = $_.IsMandatory.toString()
-            $parameterHelp.Required | Should -Be $codeMandatory
+    # The if guards around the data-driven blocks below skip generation when the
+    # collection is empty. Pester 5 skipped empty -ForEach silently; Pester 6 fails
+    # discovery instead, and these guards keep the v5 behavior on both versions.
+    if ($helpLinks) {
+        It "Help link <_> is valid" -ForEach $helpLinks {
+            (Invoke-WebRequest -Uri $_ -UseBasicParsing).StatusCode | Should -Be '200'
         }
+    }
 
-        # Parameter type in help should match code
-        It "Has correct parameter type" {
-            $parameterHelpType | Should -Be $parameter.ParameterType.Name
+    if ($commandParameters) {
+        Context "Parameter <_.Name>" -Foreach $commandParameters {
+
+            BeforeAll {
+                $parameter         = $_
+                $parameterName     = $parameter.Name
+                $parameterHelp     = $commandHelp.parameters.parameter | Where-Object Name -eq $parameterName
+                $parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() }
+            }
+
+            # Should be a description for every parameter
+            It "Has description" {
+                $parameterHelp.Description.Text | Should -Not -BeNullOrEmpty
+            }
+
+            # Required value in Help should match IsMandatory property of parameter
+            It "Has correct [mandatory] value" {
+                $codeMandatory = $_.IsMandatory.toString()
+                $parameterHelp.Required | Should -Be $codeMandatory
+            }
+
+            # Parameter type in help should match code
+            It "Has correct parameter type" {
+                $parameterHelpType | Should -Be $parameter.ParameterType.Name
+            }
         }
     }
 
-    Context "Test <_> help parameter help for <commandName>" -Foreach $helpParameterNames {
+    if ($helpParameterNames) {
+        Context "Test <_> help parameter help for <commandName>" -Foreach $helpParameterNames {
 
-        # Shouldn't find extra parameters in help.
-        It "finds help parameter in code: <_>" {
-            $_ -in $parameterNames | Should -Be $true
+            # Shouldn't find extra parameters in help.
+            It "finds help parameter in code: <_>" {
+                $_ -in $commandParameterNames | Should -Be $true
+            }
         }
     }
 }