@danmoisan/drm-copilot-mcp 1.1.19 → 1.1.21

package/resources/feature-templates/refactor/plan.yyyy-MM-ddTHH-mm.md

@@ -36,6 +36,17 @@ Evidence accounting rule: record the expected artifact path or location in each
 - [ ] Update docs/tasks/initiative references
 - [ ] Final pass for stray references to old locations
 
+## Pre-Mortem
+
+<!-- One bullet per label; state how the next review or CI run could fail on that dimension and the mitigation, or "not applicable" with the reason. -->
+- Review checklists:
+- Coverage:
+- Mirror parity:
+- File size:
+- Test isolation:
+- CI-only behavior:
+- Evidence:
+
 ## Test Plan
 
 - Unit/Integration: impacted modules and any regression tests for invariants

package/resources/lib/codex-routing/CodexDeployment.psm1

@@ -7,9 +7,9 @@
     `scripts/dev_tools/resolve_codex_deployment.py`. It resolves the exact Codex
     deployment agent, model, and reasoning effort for one delegation from the
     logical agent, the assessed complexity band, the execution context, and the
-    orchestration complexity ceiling. C3 defaults to Terra/high and elevates to
-    Sol/high only for an epic child or a C4 orchestration ceiling; the epic
-    planner and epic orchestrator personas are always forced to Sol/ultra. No
+    orchestration complexity ceiling. C3 defaults to Sol/high and elevates to
+    Astra/high only for an epic child or a C4 orchestration ceiling; the epic
+    planner and epic orchestrator personas are always forced to Astra/ultra. No
     model alias and no silent fallback is accepted.
 
     SINGLE-IMPLEMENTATION RULE. The orchestrator-state U6.X checks
@@ -81,20 +81,20 @@ $script:LOGICAL_AGENT_ALIASES = @{ 'feature-review' = 'feature-reviewer' }
 
 # The per-band deployment profiles (suffix, model, reasoning effort).
 $script:BASE_PROFILES = @{
-    C1 = @{ suffix = 'c1'; model = 'gpt-5.6-luna'; model_reasoning_effort = 'low' }
-    C2 = @{ suffix = 'c2'; model = 'gpt-5.6-terra'; model_reasoning_effort = 'medium' }
-    C3 = @{ suffix = 'c3'; model = 'gpt-5.6-terra'; model_reasoning_effort = 'high' }
-    C4 = @{ suffix = 'c4'; model = 'gpt-5.6-sol'; model_reasoning_effort = 'max' }
+    C1 = @{ suffix = 'c1'; model = 'gpt-6-luna'; model_reasoning_effort = 'low' }
+    C2 = @{ suffix = 'c2'; model = 'gpt-6.1-sol'; model_reasoning_effort = 'medium' }
+    C3 = @{ suffix = 'c3'; model = 'gpt-6.1-sol'; model_reasoning_effort = 'high' }
+    C4 = @{ suffix = 'c4'; model = 'gpt-6-astra'; model_reasoning_effort = 'max' }
 }
 
 # The profile a C3 delegation elevates to when the overlay applies.
-$script:C3_ELEVATED_PROFILE = @{ suffix = 'c3-elevated'; model = 'gpt-5.6-sol'; model_reasoning_effort = 'high' }
+$script:C3_ELEVATED_PROFILE = @{ suffix = 'c3-elevated'; model = 'gpt-6-astra'; model_reasoning_effort = 'high' }
 
 # The personas whose profile is forced regardless of band, context, or ceiling.
 # Their deployment agent is the logical agent itself (empty suffix).
 $script:FORCED_PERSONA_PROFILES = @{
-    'epic-planner'      = @{ suffix = ''; model = 'gpt-5.6-sol'; model_reasoning_effort = 'ultra' }
-    'epic-orchestrator' = @{ suffix = ''; model = 'gpt-5.6-sol'; model_reasoning_effort = 'ultra' }
+    'epic-planner'      = @{ suffix = ''; model = 'gpt-6-astra'; model_reasoning_effort = 'ultra' }
+    'epic-orchestrator' = @{ suffix = ''; model = 'gpt-6-astra'; model_reasoning_effort = 'ultra' }
 }
 
 

package/resources/powershell/PoshQC/PoshQC.CoverageMerge.psm1

@@ -0,0 +1,163 @@
+<#
+.SYNOPSIS
+Loads CoverageGutters (JaCoCo-structured) XML text into an XmlDocument (issue #953).
+.DESCRIPTION
+Disables external resolution, so the DOCTYPE reference to report.dtd is never fetched, and keeps
+whitespace so the merged report serializes with the layout of the first input.
+.PARAMETER CoverageXml
+The XML text of one coverage report.
+#>
+function ConvertFrom-PoshQCCoverageXml {
+    [CmdletBinding()]
+    [OutputType([System.Xml.XmlDocument])]
+    param(
+        [Parameter(Mandatory)][string] $CoverageXml
+    )
+
+    $document = New-Object System.Xml.XmlDocument
+    $document.XmlResolver = $null
+    $document.PreserveWhitespace = $true
+    $document.LoadXml($CoverageXml)
+    $document
+}
+
+<#
+.SYNOPSIS
+Merges the coverage reports written by the shards of one test run (issue #953).
+.DESCRIPTION
+Takes XML text only (no file I/O). Every report must list the same set of
+package/sourcefile/line-number triples, otherwise the merge throws. For each triple the merged
+line carries ci = max(ci) and mi = (mi + ci of the first report) - max(ci). The LINE and
+INSTRUCTION counters of every sourcefile, every package, and the report are then recomputed
+bottom-up: LINE covered counts lines with ci greater than 0 and LINE missed counts lines with ci
+equal to 0; INSTRUCTION covered is the sum of ci and INSTRUCTION missed is the sum of mi.
+Class and method elements and every counter other than LINE and INSTRUCTION are removed, because they
+cannot be recomputed from merged line hits (CR-8). No coverage threshold is enforced. Returns the merged XML text.
+.PARAMETER CoverageXml
+The XML text of each shard's coverage report; at least one is required.
+#>
+function Merge-PoshQCCoverageReport {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $CoverageXml
+    )
+
+    if ($CoverageXml.Count -lt 1) {
+        throw 'Merge-PoshQCCoverageReport requires at least one coverage report.'
+    }
+
+    $indexLines = {
+        param([System.Xml.XmlDocument] $Document, [int] $Position)
+        $index = New-Object 'System.Collections.Generic.Dictionary[string,System.Xml.XmlElement]' ([System.StringComparer]::Ordinal)
+        foreach ($package in $Document.SelectNodes('/report/package')) {
+            foreach ($sourceFile in $package.SelectNodes('sourcefile')) {
+                foreach ($line in $sourceFile.SelectNodes('line')) {
+                    $key = '{0}|{1}|{2}' -f $package.GetAttribute('name'), $sourceFile.GetAttribute('name'), $line.GetAttribute('nr')
+                    if ($index.ContainsKey($key)) {
+                        throw "Coverage report $Position lists line '$key' more than once."
+                    }
+                    $index.Add($key, $line)
+                }
+            }
+        }
+        , $index
+    }
+
+    $merged = ConvertFrom-PoshQCCoverageXml -CoverageXml $CoverageXml[0]
+    $mergedLines = & $indexLines $merged 1
+    for ($position = 1; $position -lt $CoverageXml.Count; $position++) {
+        $reportNumber = $position + 1
+        $otherLines = & $indexLines (ConvertFrom-PoshQCCoverageXml -CoverageXml $CoverageXml[$position]) $reportNumber
+        if ($otherLines.Count -ne $mergedLines.Count) {
+            throw "Coverage report $reportNumber lists $($otherLines.Count) lines; report 1 lists $($mergedLines.Count)."
+        }
+        foreach ($entry in $otherLines.GetEnumerator()) {
+            $line = $null
+            if (-not $mergedLines.TryGetValue($entry.Key, [ref] $line)) {
+                throw "Coverage report $reportNumber lists line '$($entry.Key)', which report 1 does not list."
+            }
+            $otherCovered = [long] $entry.Value.GetAttribute('ci')
+            $currentCovered = [long] $line.GetAttribute('ci')
+            if ($otherCovered -gt $currentCovered) {
+                $commandTotal = [long] $line.GetAttribute('mi') + $currentCovered
+                $line.SetAttribute('ci', [string] $otherCovered)
+                $line.SetAttribute('mi', [string] ($commandTotal - $otherCovered))
+            }
+        }
+    }
+
+    # Issue #953 (CR-8): class and method elements, and counters other than LINE and INSTRUCTION, cannot be
+    # recomputed from merged line hits and would keep the figures of report 1, so the merged report omits them.
+    foreach ($staleNode in @($merged.SelectNodes("//class | //counter[@type!='LINE' and @type!='INSTRUCTION']"))) {
+        [void] $staleNode.ParentNode.RemoveChild($staleNode)
+    }
+
+    $setCounter = {
+        param([System.Xml.XmlElement] $Node, [string] $Type, [long] $Covered, [long] $Missed)
+        $counter = $Node.SelectSingleNode("counter[@type='$Type']")
+        if ($counter) {
+            $counter.SetAttribute('missed', [string] $Missed)
+            $counter.SetAttribute('covered', [string] $Covered)
+        }
+    }
+    $setTotals = {
+        param([System.Xml.XmlElement] $Node, [long[]] $Totals)
+        & $setCounter $Node 'INSTRUCTION' $Totals[2] $Totals[3]
+        & $setCounter $Node 'LINE' $Totals[0] $Totals[1]
+    }
+
+    # Totals layout: 0 = LINE covered, 1 = LINE missed, 2 = INSTRUCTION covered, 3 = INSTRUCTION missed.
+    $reportTotals = New-Object 'long[]' 4
+    foreach ($package in $merged.DocumentElement.SelectNodes('package')) {
+        $packageTotals = New-Object 'long[]' 4
+        foreach ($sourceFile in $package.SelectNodes('sourcefile')) {
+            $fileTotals = New-Object 'long[]' 4
+            foreach ($line in $sourceFile.SelectNodes('line')) {
+                $lineCovered = [long] $line.GetAttribute('ci')
+                if ($lineCovered -gt 0) { $fileTotals[0]++ } else { $fileTotals[1]++ }
+                $fileTotals[2] += $lineCovered
+                $fileTotals[3] += [long] $line.GetAttribute('mi')
+            }
+            & $setTotals $sourceFile $fileTotals
+            for ($slot = 0; $slot -lt 4; $slot++) { $packageTotals[$slot] += $fileTotals[$slot] }
+        }
+        & $setTotals $package $packageTotals
+        for ($slot = 0; $slot -lt 4; $slot++) { $reportTotals[$slot] += $packageTotals[$slot] }
+    }
+    & $setTotals $merged.DocumentElement $reportTotals
+
+    $merged.OuterXml
+}
+
+<#
+.SYNOPSIS
+Summarizes the report-level LINE counter of a coverage report (issue #953).
+.DESCRIPTION
+Returns covered, missed, total, and percent (rounded to two decimals; 0 when total is 0) from the
+report-level LINE counter. Takes XML text only and enforces no threshold.
+.PARAMETER CoverageXml
+The XML text of one coverage report.
+#>
+function Get-PoshQCCoverageLineSummary {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string] $CoverageXml
+    )
+
+    $document = ConvertFrom-PoshQCCoverageXml -CoverageXml $CoverageXml
+    $counter = $document.SelectSingleNode("/report/counter[@type='LINE']")
+    if (-not $counter) {
+        throw 'The coverage report has no report-level LINE counter.'
+    }
+
+    $covered = [long] $counter.GetAttribute('covered')
+    $missed = [long] $counter.GetAttribute('missed')
+    $total = $covered + $missed
+    [pscustomobject]@{
+        covered = $covered
+        missed  = $missed
+        total   = $total
+        percent = if ($total -gt 0) { [math]::Round(100.0 * $covered / $total, 2) } else { 0 }
+    }
+}

package/resources/powershell/PoshQC/PoshQC.Shard.psm1

@@ -0,0 +1,296 @@
+<#
+.SYNOPSIS
+Selects the test files assigned to one shard (issue #953).
+.DESCRIPTION
+Assigns the files in longest-processing-time order (issue #953, CR-10): heaviest file first, equal weights
+in ordinal path order, each file to the shard with the least assigned weight, then the fewest files, then
+the lowest index, so the shard loads differ by at most the weight of one file. When Weight is omitted every
+file weighs 1, which assigns the files round-robin in ordinal path order. Returns this shard's files in
+input order. Throws when ShardCount is below 1, ShardIndex is outside 1..ShardCount, Weight and TestFile
+differ in length, or a weight is negative (CR-18).
+.PARAMETER TestFile
+Ordered list of test file paths to distribute.
+.PARAMETER ShardIndex
+One-based index of the shard to select.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER Weight
+Optional non-negative weight of each test file (for example its size in bytes), parallel to TestFile.
+#>
+function Get-PoshQCShardSlice {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [long[]] $Weight
+    )
+
+    if ($ShardCount -lt 1) {
+        throw "ShardCount must be at least 1; received $ShardCount."
+    }
+    if ($ShardIndex -lt 1 -or $ShardIndex -gt $ShardCount) {
+        throw "ShardIndex must be between 1 and $ShardCount; received $ShardIndex."
+    }
+    if ($null -eq $Weight) {
+        $Weight = [long[]] (@(1) * $TestFile.Count)
+    }
+    if ($Weight.Count -ne $TestFile.Count) {
+        throw "Weight lists $($Weight.Count) values; TestFile lists $($TestFile.Count) files."
+    }
+    for ($position = 0; $position -lt $Weight.Count; $position++) {
+        if ($Weight[$position] -lt 0) {
+            throw "Weight must not be negative; '$($TestFile[$position])' has weight $($Weight[$position])."
+        }
+    }
+
+    $order = [int[]] @(for ($position = 0; $position -lt $TestFile.Count; $position++) { $position })
+    $heaviestFirst = [System.Comparison[int]] {
+        param([int] $Left, [int] $Right)
+        $byWeight = $Weight[$Right].CompareTo($Weight[$Left])
+        if ($byWeight -ne 0) { return $byWeight }
+        [string]::CompareOrdinal($TestFile[$Left], $TestFile[$Right])
+    }
+    [System.Array]::Sort($order, $heaviestFirst)
+
+    $load = New-Object 'long[]' $ShardCount
+    $fileCount = New-Object 'int[]' $ShardCount
+    $selected = New-Object 'System.Collections.Generic.HashSet[int]'
+    foreach ($position in $order) {
+        $target = 0
+        for ($shard = 1; $shard -lt $ShardCount; $shard++) {
+            if ($load[$shard] -lt $load[$target] -or ($load[$shard] -eq $load[$target] -and $fileCount[$shard] -lt $fileCount[$target])) {
+                $target = $shard
+            }
+        }
+        $load[$target] += $Weight[$position]
+        $fileCount[$target]++
+        if ($target -eq $ShardIndex - 1) {
+            [void] $selected.Add($position)
+        }
+    }
+
+    for ($position = 0; $position -lt $TestFile.Count; $position++) {
+        if ($selected.Contains($position)) {
+            $TestFile[$position]
+        }
+    }
+}
+
+<#
+.SYNOPSIS
+Builds the shard manifest for one shard (issue #953).
+.DESCRIPTION
+Returns an in-memory object with shardIndex, shardCount, all (root-relative forward-slash paths
+of every input file), selected (root-relative paths of this shard's slice), and selectedFullPath
+(the slice as given). Relative paths are computed by case-insensitive removal of the root prefix;
+a path outside the root keeps its forward-slash form.
+.PARAMETER RootPath
+Workspace root that the relative paths are computed against.
+.PARAMETER TestFile
+Ordered list of test file paths to distribute.
+.PARAMETER ShardIndex
+One-based index of the shard.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER Weight
+Optional weight of each test file, passed to Get-PoshQCShardSlice.
+#>
+function New-PoshQCShardManifest {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure in-memory factory that changes no system state.')]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string] $RootPath,
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [long[]] $Weight
+    )
+
+    $sliceArguments = @{ TestFile = $TestFile; ShardIndex = $ShardIndex; ShardCount = $ShardCount }
+    if ($PSBoundParameters.ContainsKey('Weight')) {
+        $sliceArguments['Weight'] = $Weight
+    }
+    $selected = @(Get-PoshQCShardSlice @sliceArguments)
+    $prefix = ($RootPath -replace '\\', '/').TrimEnd('/') + '/'
+    $toRelative = {
+        param([string] $Path)
+        $normalized = $Path -replace '\\', '/'
+        if ($normalized.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+            $normalized.Substring($prefix.Length)
+        } else {
+            $normalized
+        }
+    }
+
+    [pscustomobject]@{
+        shardIndex       = $ShardIndex
+        shardCount       = $ShardCount
+        all              = @($TestFile | ForEach-Object { & $toRelative $_ })
+        selected         = @($selected | ForEach-Object { & $toRelative $_ })
+        selectedFullPath = $selected
+    }
+}
+
+<#
+.SYNOPSIS
+Verifies that a set of shard manifests covers every test file exactly once (issue #953).
+.DESCRIPTION
+Throws unless the shard indices are exactly 1..N once each, every manifest declares shardCount N,
+every 'all' list is identical, the 'selected' lists are pairwise disjoint, and their union sorted
+ordinally equals 'all' sorted ordinally. Returns $true otherwise.
+.PARAMETER ShardManifest
+The manifests produced by New-PoshQCShardManifest, one per shard (for example loaded from JSON).
+#>
+function Test-PoshQCShardCompleteness {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][object[]] $ShardManifest
+    )
+
+    $count = $ShardManifest.Count
+    $indices = @($ShardManifest | ForEach-Object { [int] $_.shardIndex } | Sort-Object)
+    if (($indices -join ',') -ne ((1..$count) -join ',')) {
+        throw "Shard indices '$($indices -join ',')' are not exactly 1..$count."
+    }
+
+    $reference = @($ShardManifest[0].all | ForEach-Object { [string] $_ })
+    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::Ordinal)
+    foreach ($manifest in $ShardManifest) {
+        if ([int] $manifest.shardCount -ne $count) {
+            throw "Shard $($manifest.shardIndex) declares shardCount $($manifest.shardCount); $count manifests were supplied."
+        }
+        $all = @($manifest.all | ForEach-Object { [string] $_ })
+        if (($all -join "`n") -cne ($reference -join "`n")) {
+            throw "Shard $($manifest.shardIndex) reports an 'all' list that differs from shard $($ShardManifest[0].shardIndex)."
+        }
+        foreach ($path in @($manifest.selected | ForEach-Object { [string] $_ })) {
+            if (-not $seen.Add($path)) {
+                throw "Test file '$path' is selected by more than one shard."
+            }
+        }
+    }
+
+    [string[]] $union = @($seen)
+    [string[]] $expected = $reference
+    [System.Array]::Sort($union, [System.StringComparer]::Ordinal)
+    [System.Array]::Sort($expected, [System.StringComparer]::Ordinal)
+    if (($union -join "`n") -cne ($expected -join "`n")) {
+        $missing = @($expected | Where-Object { -not $seen.Contains($_) })
+        throw "The shard selections do not cover every test file; missing or extra entries (missing: $($missing -join ', '))."
+    }
+
+    $true
+}
+
+<#
+.SYNOPSIS
+Verifies that the shard test counts add up to the discovery count (issue #953).
+.DESCRIPTION
+Throws unless the sum of ShardTestCount equals DiscoveryCount. Returns $true otherwise.
+.PARAMETER ShardTestCount
+The test count reported by each shard (for example the JUnit testsuites/@tests value).
+.PARAMETER DiscoveryCount
+The test count reported by a discovery-only Pester pass over every test file.
+#>
+function Test-PoshQCShardTestCount {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][int[]] $ShardTestCount,
+        [Parameter(Mandatory)][int] $DiscoveryCount
+    )
+
+    $sum = 0
+    foreach ($testCount in $ShardTestCount) {
+        $sum += $testCount
+    }
+    if ($sum -ne $DiscoveryCount) {
+        throw "Shard test counts sum to $sum; the discovery pass found $DiscoveryCount tests."
+    }
+
+    $true
+}
+
+<#
+.SYNOPSIS
+Selects this shard's test files for Invoke-PoshQCTest (issue #953).
+.DESCRIPTION
+Weights each enumerated test file with Get-PoshQCShardTestFileWeight (a FileInfo item, as the default
+EnumerateTests seam returns, weighs the UTF-8 size of its text with CRLF counted as LF; CR-19), builds
+the manifest with New-PoshQCShardManifest, and throws when the shard selects no test file (CR-13), so Pester
+never runs with an empty Run.Path. When ShardFileListPath is set, WriteShardFileList receives the path and
+the manifest JSON without selectedFullPath. Returns the full paths of the selected files.
+.PARAMETER RootPath
+Workspace root that the manifest paths are relative to.
+.PARAMETER TestFile
+Enumerated test files: FileInfo items, objects with FullName (and optionally Length), or path strings.
+.PARAMETER ShardIndex
+One-based index of the shard.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER ShardFileListPath
+Optional path that receives the shard manifest JSON.
+.PARAMETER WriteShardFileList
+Seam that writes the manifest JSON; receives the path and the JSON text.
+#>
+function Select-PoshQCShardTestFile {
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][string] $RootPath,
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [string] $ShardFileListPath,
+        [Parameter(Mandatory)][scriptblock] $WriteShardFileList
+    )
+
+    $paths = [string[]] @($TestFile | ForEach-Object { if ($_ -is [string]) { $_ } else { $_.FullName } })
+    $weights = [long[]] @(Get-PoshQCShardTestFileWeight -TestFile $TestFile)
+    $manifest = New-PoshQCShardManifest -RootPath $RootPath -TestFile $paths -ShardIndex $ShardIndex -ShardCount $ShardCount -Weight $weights
+    if (@($manifest.selected).Count -eq 0) {
+        throw "Shard $ShardIndex of $ShardCount selects no test file; $($paths.Count) test files cannot fill $ShardCount shards. Lower the shard count."
+    }
+    if ($ShardFileListPath) {
+        & $WriteShardFileList $ShardFileListPath ($manifest | Select-Object -Property shardIndex, shardCount, all, selected | ConvertTo-Json -Depth 4)
+    }
+    [string[]] $manifest.selectedFullPath
+}
+
+<#
+.SYNOPSIS
+Returns the shard weight of each enumerated test file (issue #953, CR-19).
+.DESCRIPTION
+A FileInfo item weighs the UTF-8 byte count of its text after every CRLF pair is replaced by LF, so a checkout
+with CRLF line endings computes the same weights, and therefore the same shard assignment, as a checkout with
+LF line endings. Another object weighs its Length property when it has one; a plain path string, or an object
+without a Length property, weighs 1. Returns one weight per item, in input order.
+.PARAMETER TestFile
+Enumerated test files: FileInfo items, objects with FullName (and optionally Length), or path strings.
+.PARAMETER ReadTestFileText
+Seam that returns the text of a test file from its full path. Defaults to [System.IO.File]::ReadAllText.
+#>
+function Get-PoshQCShardTestFileWeight {
+    [CmdletBinding()]
+    [OutputType([long[]])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]] $TestFile,
+        [scriptblock] $ReadTestFileText = { param([string] $Path) [System.IO.File]::ReadAllText($Path) }
+    )
+
+    $weights = New-Object 'System.Collections.Generic.List[long]'
+    foreach ($item in $TestFile) {
+        if ($item -is [System.IO.FileInfo]) {
+            $text = [string] (& $ReadTestFileText $item.FullName)
+            $weights.Add([System.Text.Encoding]::UTF8.GetByteCount($text.Replace("`r`n", "`n")))
+        } elseif ($item -isnot [string] -and $null -ne $item.PSObject.Properties['Length']) {
+            $weights.Add([long] $item.Length)
+        } else {
+            $weights.Add(1)
+        }
+    }
+    [long[]] $weights.ToArray()
+}

package/resources/powershell/PoshQC/PoshQC.Testing.psm1

@@ -150,6 +150,14 @@ Optional workspace-relative or workspace-contained folders to scan instead of th
 .PARAMETER ResolveCoveragePopulation
 Injectable seam that derives the code-coverage file population from the workspace (issue #527).
 Defaults to Resolve-PoshQCCoveragePopulation.
+.PARAMETER ShardIndex
+One-based shard index; used only when ShardCount is greater than 0 (issue #953).
+.PARAMETER ShardCount
+Number of shards. When greater than 0, Run.Path is set to this shard's size-balanced slice of the test files (Select-PoshQCShardTestFile).
+.PARAMETER ShardFileListPath
+Optional path that receives the shard manifest (shardIndex, shardCount, all, selected) as JSON.
+.PARAMETER WriteShardFileList
+Injectable seam that writes the shard manifest JSON. Defaults to Set-Content.
 #>
 function Invoke-PoshQCTest {
     [CmdletBinding()]
@@ -160,12 +168,19 @@ function Invoke-PoshQCTest {
         [string[]] $ExcludeDirs = $script:DefaultExcludedDirs,
         [string] $KoverageOutputPath,
         [switch] $DisableKoverageCopy,
+        [int] $ShardIndex = 0,
+        [int] $ShardCount = 0,
+        [string] $ShardFileListPath,
+        [scriptblock] $WriteShardFileList = { param([string] $Path, [string] $Json) Set-Content -LiteralPath $Path -Value $Json -Encoding utf8 },
         [scriptblock] $EnsureModule = {
-            param([string] $Name, [string] $ErrorMessage)
-            if (-not (Get-Module -ListAvailable -Name $Name)) { throw $ErrorMessage }
+            param([string] $Name, [string] $ErrorMessage, [string] $MinimumVersion, [string] $MaximumVersion)
+            # Issue #953 (CR-1): only an installed version inside the supported range counts as present, so a host
+            # whose only Pester is 6.x or the inbox 3.4.0 receives the actionable message instead of an import error.
+            if (-not (Get-Module -ListAvailable -FullyQualifiedName @{ ModuleName = $Name; ModuleVersion = $MinimumVersion; MaximumVersion = $MaximumVersion })) { throw $ErrorMessage }
             # Import globally so Pester's Describe/It/Mock resolve in test containers that the
             # default $InvokePester trampoline now hosts in the global session state (issue #392).
-            Import-Module $Name -Global -ErrorAction Stop
+            # Issue #953 (D8, CR-2): -MinimumVersion and -MaximumVersion keep the import inside the supported range.
+            Import-Module $Name -Global -MinimumVersion $MinimumVersion -MaximumVersion $MaximumVersion -ErrorAction Stop
         },
         [scriptblock] $TestPathExists = { param([string] $Path) Test-Path $Path },
         [scriptblock] $LoadSettings = { param([string] $Path) Import-PowerShellDataFile -Path $Path },
@@ -302,7 +317,7 @@ function Invoke-PoshQCTest {
         $Root = [IO.Path]::GetFullPath([IO.Path]::Combine($PWD.ProviderPath, $Root))
     }
 
-    & $EnsureModule 'Pester' "Pester is not installed. Run Install-PoshQCTool (alias Install-PoshQCTools) first."
+    & $EnsureModule 'Pester' "Pester is not installed in the supported range (5.9.0 to 5.99.99). Run Install-PoshQCTool (alias Install-PoshQCTools) first." '5.9.0' '5.99.99'
 
     if (-not (& $TestPathExists $SettingsPath)) {
         throw "Settings not found: $SettingsPath"
@@ -393,6 +408,10 @@ function Invoke-PoshQCTest {
         & $Logger "No Pester test files found under configured paths for root $Root"
         return
     }
+    if ($ShardCount -gt 0) {
+        # Issue #953 (FR-09, CR-10, CR-13): run only this shard's size-balanced slice of the enumerated test files.
+        $config.Run.Path = [string[]] @(Select-PoshQCShardTestFile -RootPath $Root -TestFile @($testFiles) -ShardIndex $ShardIndex -ShardCount $ShardCount -ShardFileListPath $ShardFileListPath -WriteShardFileList $WriteShardFileList)
+    }
 
     $pesterResult = & $InvokePester $config
 

package/resources/powershell/PoshQC/PoshQC.psd1

@@ -16,7 +16,13 @@
         'Invoke-PoshQCAnalyze',
         'Invoke-PoshQCAnalyzeAutofix',
         'Invoke-PoshQCSuite',
-        'Invoke-PoshQCTest'
+        'Invoke-PoshQCTest',
+        'Get-PoshQCShardSlice',
+        'Merge-PoshQCCoverageReport',
+        'Get-PoshQCCoverageLineSummary',
+        'New-PoshQCShardManifest',
+        'Test-PoshQCShardCompleteness',
+        'Test-PoshQCShardTestCount'
     )
     CmdletsToExport      = @()
     VariablesToExport    = @()

package/resources/powershell/PoshQC/PoshQC.psm1

@@ -54,11 +54,16 @@ function Install-PoshQCTool {
 
     $requiredModules = @(
         @{ Name = 'PSScriptAnalyzer'; Version = '1.22.0' },
-        @{ Name = 'Pester'; Version = '5.6.1' }
+        # Issue #953 (D8): UpperBound is exclusive; an installed Pester 6.x does not satisfy the requirement.
+        @{ Name = 'Pester'; Version = '5.9.0'; UpperBound = '6.0.0' }
     )
 
+    # Issue #953 (CR-3): one version-range predicate serves the present check and the post-install check.
+    # Where-Object runs it in this function's scope, so $module is the requirement of the current iteration.
+    $isSupportedVersion = { $_.Version -ge [version]$module.Version -and (-not $module.ContainsKey('UpperBound') -or $_.Version -lt [version]$module.UpperBound) }
+
     foreach ($module in $requiredModules) {
-        $installed = & $FindModule $module.Name | Where-Object { $_.Version -ge [version]$module.Version } | Select-Object -First 1
+        $installed = & $FindModule $module.Name | Where-Object -FilterScript $isSupportedVersion | Select-Object -First 1
         if ($installed) {
             & $Logger "$($module.Name) $($installed.Version) already present."
             continue
@@ -71,8 +76,7 @@ function Install-PoshQCTool {
             throw "Failed to install $($module.Name) $($module.Version): $($_.Exception.Message)"
         }
 
-        $post = & $FindModule $module.Name | Where-Object { $_.Version -ge [version]$module.Version } | Select-Object -First 1
-        if (-not $post) {
+        if (-not (& $FindModule $module.Name | Where-Object -FilterScript $isSupportedVersion | Select-Object -First 1)) {
             throw "Failed to install $($module.Name) $($module.Version)."
         }
         & $Logger "$($module.Name) $($module.Version) installed."
@@ -115,6 +119,8 @@ foreach ($subModuleName in @(
         'PoshQC.ScanConfig.psm1',
         'PoshQC.Coverage.psm1',
         'PoshQC.Analyzer.psm1',
+        'PoshQC.Shard.psm1',
+        'PoshQC.CoverageMerge.psm1',
         'PoshQC.Testing.psm1'
     )) {
     $subModulePath = Join-Path $script:ModuleRoot $subModuleName
@@ -143,6 +149,12 @@ Export-ModuleMember -Function @(
     'Invoke-PoshQCSuite',
     'Invoke-PoshQCTest',
     'Convert-PoshQCCoverageToRelative',
-    'Get-PoshQCScanConfigFolder'
+    'Get-PoshQCScanConfigFolder',
+    'Get-PoshQCShardSlice',
+    'Merge-PoshQCCoverageReport',
+    'Get-PoshQCCoverageLineSummary',
+    'New-PoshQCShardManifest',
+    'Test-PoshQCShardCompleteness',
+    'Test-PoshQCShardTestCount'
 ) -Alias @('Install-PoshQCTools')