@danmoisan/drm-copilot-mcp 1.1.25 → 1.1.27

package/resources/claude-customizations/.claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1

@@ -0,0 +1,475 @@
+<#
+.SYNOPSIS
+    Print the TL;DR block and the hourly progress report of an epic.
+
+.DESCRIPTION
+    Reads the epic kickoff and the feature plans from the integration branch (or from a
+    feature worktree when one holds the plan), the epic orchestrator checkpoint, the pull
+    request state of each feature branch, and the weekly quota of the active cswap
+    account, then prints the task progress, the per-feature state, the average and
+    recent velocity, the sample standard deviation, the estimated time remaining, and the
+    weekly quota.
+
+    The pure logic lives in Get-EpicProgressReport.Logic.ps1, which this script
+    dot-sources and which dot-sources the State, Metrics, and Render files. Every I/O call
+    goes through a wrapper function in this script. When gh or cswap is not installed, or
+    prints no parseable output, the report still prints: the pull-request state is empty
+    and the quota is n/a.
+
+    The state file at -StatePath keeps the start instant, the baseline done count, the
+    weekly baseline, and the check-in samples (Unix time and done count). A sample is added
+    when the previous sample is at least 90 seconds old; the recent velocity and its
+    standard deviation are computed from those samples. The state file is read before the
+    first git call. The legacy sample array written by earlier versions is still read.
+
+    This file is the canonical script of the /epic-progress-report skill. The entry-point
+    block at the bottom is skipped when the file is dot-sourced.
+
+.PARAMETER EpicFolder
+    Mandatory. The epic folder name under docs/features/epics/. It is also the epic name
+    printed in the status heading.
+
+.PARAMETER StartUtc
+    Optional. The instant from which elapsed time and average velocity are measured;
+    converted to UTC. A start after the current instant counts as zero elapsed time.
+    Resolution: the passed value, else now when -ResetBaseline is given, else the start
+    stored in the state file. With none of these the script stops with an error before any
+    git call. A passed value is persisted with the next state write.
+
+.PARAMETER EpicIssue
+    The epic issue number printed in the report. Default: the number on the first
+    'Epic issue: #<n>' line of the kickoff file. The script stops with an error when
+    neither this parameter nor the kickoff yields a number.
+
+.PARAMETER IntegrationBranch
+    The branch that holds the kickoff and the plans. Default:
+    origin/epic/<EpicFolder>-integration.
+
+.PARAMETER KickoffPath
+    The repository-relative path of the kickoff file on the integration branch. Default:
+    docs/features/epics/<EpicFolder>/epic-kickoff.md. Only the feature-summary table, whose
+    header's first cell is issue_num or Issue, is read; every other table in the file is ignored.
+    Kickoff text without that header, a feature row with fewer than five cells, and a feature
+    row with a blank plan cell each raise a terminating error.
+
+.PARAMETER RepositoryRoot
+    The repository root in which git runs. Default: the current location.
+
+.PARAMETER CheckpointPath
+    The epic orchestrator checkpoint. Default:
+    artifacts/orchestration/epic-orchestrator-state.json under the repository root.
+
+.PARAMETER StatePath
+    The state file that keeps the start, the baselines, and the check-in samples. Default:
+    .claude/state/epic-progress-<EpicFolder>.json under the repository root, a gitignored
+    location that survives a container stop with the checkout. The directory is created
+    when missing.
+
+.PARAMETER BaselineDone
+    The number of tasks already complete at the start. Resolution: the passed value, else
+    the current done count when -ResetBaseline is given, else the stored value, else 0.
+
+.PARAMETER BaselineWeeklyPct
+    The weekly quota percentage at the start. Resolution: the passed value, else the stored
+    value, else 0. -ResetBaseline does not change it.
+
+.PARAMETER WaveOverheadHours
+    The review and CI hours added per open wave in the wave-parallel estimate.
+    Default: 1.25.
+
+.PARAMETER SampleCap
+    The maximum number of check-in samples kept in the state file. Default: 14.
+
+.PARAMETER Mode
+    TLDR prints the four-line TL;DR block only; Full prints the TL;DR block followed by
+    the full report. Default: Full.
+
+.PARAMETER ResetBaseline
+    Discards every stored sample, sets the start to now (unless -StartUtc is passed) and the
+    baseline done count to the current done count (unless -BaselineDone is passed), adds
+    the first sample, and writes the state file. The weekly baseline is kept.
+
+.PARAMETER PairSamples
+    After the normal sample rule, keeps the newest sample and every second older sample
+    and writes the state file, so the intervals match a doubled cadence. A one-shot
+    command: each run halves the samples again. Cannot be combined with -ResetBaseline.
+
+.EXAMPLE
+    pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -StartUtc 2026-01-05T09:00:00Z -BaselineDone 40 -Mode TLDR
+
+    Prints the TL;DR block for the epic in docs/features/epics/example-epic/, measuring
+    from 09:00 UTC and counting 40 tasks as complete at the start; both values are stored
+    for later runs.
+
+.EXAMPLE
+    pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -EpicIssue 12
+
+    Prints the full report for epic issue 12 with the start and baseline read from the
+    state file.
+
+.EXAMPLE
+    pwsh -NoProfile -File .claude/skills/epic-progress-report/scripts/Get-EpicProgressReport.ps1 -EpicFolder example-epic -ResetBaseline
+
+    Restarts the measurement now after a pause: the stored samples are discarded and the
+    current done count becomes the baseline.
+
+.NOTES
+    The tool is read-only toward the repository and GitHub: it runs only git fetch, git
+    show, git worktree list, and gh pr list, and the only file it writes is the state file
+    at -StatePath (issues #1080 and #1093).
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateNotNullOrEmpty()]
+    [string] $EpicFolder,
+
+    [datetime] $StartUtc,
+
+    [string] $EpicIssue = '',
+
+    [string] $IntegrationBranch = '',
+
+    [string] $KickoffPath = '',
+
+    [string] $RepositoryRoot = '',
+
+    [string] $CheckpointPath = '',
+
+    [string] $StatePath = '',
+
+    [int] $BaselineDone = 0,
+
+    [double] $BaselineWeeklyPct = 0,
+
+    [double] $WaveOverheadHours = 1.25,
+
+    [ValidateRange(1, 100000)]
+    [int] $SampleCap = 14,
+
+    [ValidateSet('TLDR', 'Full')]
+    [string] $Mode = 'Full',
+
+    [switch] $ResetBaseline,
+
+    [switch] $PairSamples
+)
+
+. (Join-Path -Path $PSScriptRoot -ChildPath 'Get-EpicProgressReport.Logic.ps1')
+
+function Invoke-GitExe {
+    <#
+    .SYNOPSIS
+        Run git with the given arguments and return its standard output lines.
+    .PARAMETER GitArgs
+        The git arguments.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory = $true)] [string[]] $GitArgs)
+
+    & git @GitArgs 2>$null
+}
+
+function Invoke-GhExe {
+    <#
+    .SYNOPSIS
+        Run gh with the given arguments and return its standard output lines.
+    .PARAMETER GhArgs
+        The gh arguments.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory = $true)] [string[]] $GhArgs)
+
+    & gh @GhArgs 2>$null
+}
+
+function Invoke-CswapExe {
+    <#
+    .SYNOPSIS
+        Run cswap with the given arguments and return its standard output lines.
+    .PARAMETER CswapArgs
+        The cswap arguments.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory = $true)] [string[]] $CswapArgs)
+
+    & cswap @CswapArgs 2>$null
+}
+
+function Test-EpicProgressCommand {
+    <#
+    .SYNOPSIS
+        Return whether an application of the given name is installed.
+    .PARAMETER Name
+        The application name.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory = $true)] [string] $Name)
+
+    return [bool] (Get-Command -Name $Name -CommandType Application -ErrorAction SilentlyContinue)
+}
+
+function Test-EpicProgressPath {
+    <#
+    .SYNOPSIS
+        Return whether a file exists at the given path; a blank path returns $false.
+    .PARAMETER Path
+        The file path.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory = $true)] [AllowEmptyString()] [string] $Path)
+
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
+    return Test-Path -LiteralPath $Path -PathType Leaf
+}
+
+function Read-EpicProgressFile {
+    <#
+    .SYNOPSIS
+        Return the raw text of a file.
+    .PARAMETER Path
+        The file path.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory = $true)] [string] $Path)
+
+    return Get-Content -LiteralPath $Path -Raw
+}
+
+function Write-EpicProgressState {
+    <#
+    .SYNOPSIS
+        Write the state file content as UTF-8; the only file the report writes.
+    .DESCRIPTION
+        Creates the parent directory (for example .claude/state) when it is missing. Both
+        writes run only inside the ShouldProcess block, so -WhatIf writes nothing.
+    .PARAMETER Path
+        The state file path.
+    .PARAMETER Content
+        The JSON text to write.
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param(
+        [Parameter(Mandatory = $true)] [string] $Path,
+        [Parameter(Mandatory = $true)] [string] $Content
+    )
+
+    if ($PSCmdlet.ShouldProcess($Path, 'Write epic progress state')) {
+        $directory = Split-Path -Path $Path -Parent
+        if ($directory -and -not (Test-Path -LiteralPath $directory -PathType Container)) {
+            $null = New-Item -ItemType Directory -Path $directory -Force
+        }
+        Set-Content -LiteralPath $Path -Value $Content -Encoding utf8
+    }
+}
+
+function Get-EpicProgressUtcNow {
+    <#
+    .SYNOPSIS
+        Return the current UTC instant.
+    #>
+    [CmdletBinding()]
+    [OutputType([datetime])]
+    param()
+
+    return [datetime]::UtcNow
+}
+
+function Get-EpicProgressLastExitCode {
+    <#
+    .SYNOPSIS
+        Return the exit code of the most recent native command ($LASTEXITCODE).
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param()
+
+    return $LASTEXITCODE
+}
+
+function Invoke-EpicProgressReport {
+    <#
+    .SYNOPSIS
+        Gather the report inputs through the I/O seams and return the report lines.
+    .DESCRIPTION
+        Wiring only. Runs git with exactly 'fetch -q origin', 'worktree list --porcelain',
+        and 'show <IntegrationBranch>:<path>'; runs 'gh pr list' only when gh is installed
+        and 'cswap list --json' only when cswap is installed; treats an unparseable
+        checkpoint or state file as empty; reads the state file and resolves the start before
+        the first git call; writes the state file only when the sample set changed or
+        ResetBaseline or PairSamples is given. When 'git fetch -q origin' exits with a non-zero code, writes a warning
+        naming the code and continues with the last fetched state of the integration branch.
+        Returns the TL;DR lines, followed by the Full lines unless Mode is TLDR.
+    .PARAMETER EpicFolder
+        The epic folder name; also the epic name in the status heading.
+    .PARAMETER StartUtc
+        The start instant; when not passed, resolved by Resolve-EpicProgressBaseline.
+    .PARAMETER EpicIssue
+        The epic issue number; blank to read it from the kickoff file.
+    .PARAMETER IntegrationBranch
+        The integration branch; blank for the default.
+    .PARAMETER KickoffPath
+        The kickoff path on the integration branch; blank for the default.
+    .PARAMETER RepositoryRoot
+        The repository root; blank for the current location.
+    .PARAMETER CheckpointPath
+        The epic orchestrator checkpoint path; blank for the default.
+    .PARAMETER StatePath
+        The state file path; blank for the default under .claude/state of the repository root.
+    .PARAMETER BaselineDone
+        The tasks already complete at the start; when not passed, resolved from the reset or the state.
+    .PARAMETER BaselineWeeklyPct
+        The weekly quota percentage at the start; when not passed, resolved from the state.
+    .PARAMETER WaveOverheadHours
+        The hours added per open wave.
+    .PARAMETER SampleCap
+        The maximum number of samples kept.
+    .PARAMETER Mode
+        TLDR or Full.
+    .PARAMETER ResetBaseline
+        Discard the stored samples, restart the baseline now, and write the state.
+    .PARAMETER PairSamples
+        Pair the samples after the sample rule and write the state.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)] [string] $EpicFolder,
+        [datetime] $StartUtc = [datetime]::MinValue,
+        [string] $EpicIssue = '',
+        [string] $IntegrationBranch = '',
+        [string] $KickoffPath = '',
+        [string] $RepositoryRoot = '',
+        [string] $CheckpointPath = '',
+        [string] $StatePath = '',
+        [int] $BaselineDone = 0,
+        [double] $BaselineWeeklyPct = 0,
+        [double] $WaveOverheadHours = 1.25,
+        [ValidateRange(1, 100000)] [int] $SampleCap = 14,
+        [ValidateSet('TLDR', 'Full')] [string] $Mode = 'Full',
+        [switch] $ResetBaseline,
+        [switch] $PairSamples
+    )
+
+    if ($ResetBaseline -and $PairSamples) {
+        throw '-ResetBaseline and -PairSamples cannot be combined: a reset discards the samples that -PairSamples would pair. Run them separately.'
+    }
+
+    $setting = Resolve-EpicProgressSetting -EpicFolder $EpicFolder -EpicIssue $EpicIssue -IntegrationBranch $IntegrationBranch -KickoffPath $KickoffPath -RepositoryRoot $RepositoryRoot -CheckpointPath $CheckpointPath -StatePath $StatePath -CurrentLocation (Get-Location).ProviderPath
+    # The state file is read before the first git call.
+    $stateText = ''
+    if (Test-EpicProgressPath -Path $setting.StatePath) { $stateText = Read-EpicProgressFile -Path $setting.StatePath }
+    $storedState = ConvertFrom-EpicProgressStateText -Text $stateText
+    $nowUtc = (Get-EpicProgressUtcNow).ToUniversalTime()
+    $baseline = Resolve-EpicProgressBaseline -StartUtc $StartUtc -StartUtcPassed:($PSBoundParameters.ContainsKey('StartUtc')) -BaselineDone $BaselineDone -BaselineDonePassed:($PSBoundParameters.ContainsKey('BaselineDone')) -BaselineWeeklyPct $BaselineWeeklyPct -BaselineWeeklyPctPassed:($PSBoundParameters.ContainsKey('BaselineWeeklyPct')) -State $storedState -ResetBaseline:$ResetBaseline -NowUtc $nowUtc
+    # A reset discards every stored sample; the sample rule then adds the first sample (now, done).
+    $priorSamples = $storedState.Samples
+    if ($ResetBaseline) { $priorSamples = [object[]] @() }
+    $null = Invoke-GitExe -GitArgs @('fetch', '-q', 'origin')
+    $fetchExitCode = Get-EpicProgressLastExitCode
+    if ($fetchExitCode -ne 0) {
+        Write-Warning "git fetch -q origin failed with exit code $fetchExitCode; the report uses the last fetched state of $($setting.IntegrationBranch)."
+    }
+    $worktreeLines = @(Invoke-GitExe -GitArgs @('worktree', 'list', '--porcelain'))
+    $worktreeOf = ConvertFrom-EpicProgressWorktreeList -PorcelainLine $worktreeLines
+    $kickoffText = @(Invoke-GitExe -GitArgs @('show', "$($setting.IntegrationBranch):$($setting.KickoffPath)")) -join "`n"
+
+    $epicIssueText = $setting.EpicIssue
+    if ([string]::IsNullOrWhiteSpace($epicIssueText)) { $epicIssueText = Get-EpicProgressIssueFromKickoff -KickoffText $kickoffText }
+    if ([string]::IsNullOrWhiteSpace($epicIssueText)) {
+        throw "The epic issue number could not be resolved: pass -EpicIssue or add an 'Epic issue: #<n>' line to $($setting.KickoffPath) on $($setting.IntegrationBranch)."
+    }
+
+    $checkpointFeature = @{}
+    if (Test-EpicProgressPath -Path $setting.CheckpointPath) {
+        $checkpointText = Read-EpicProgressFile -Path $setting.CheckpointPath
+        if (Test-EpicProgressJsonText -Json $checkpointText) {
+            $checkpoint = ConvertFrom-Json -InputObject $checkpointText
+            $checkpointEntries = @($checkpoint.features)
+            foreach ($checkpointEntry in $checkpointEntries) {
+                if ($null -ne $checkpointEntry -and $null -ne $checkpointEntry.issue_num) { $checkpointFeature["$($checkpointEntry.issue_num)"] = $checkpointEntry }
+            }
+        }
+    }
+
+    $ghInstalled = Test-EpicProgressCommand -Name 'gh'
+    $features = [System.Collections.Generic.List[object]]::new()
+    $rows = @(ConvertFrom-EpicProgressKickoffRow -KickoffText $kickoffText)
+    foreach ($row in $rows) {
+        $checkpointEntry = $checkpointFeature[$row.Issue]
+        $branch = ''
+        $mergeStatus = 'not_started'
+        if ($null -ne $checkpointEntry) {
+            if ($checkpointEntry.branch_name) { $branch = [string] $checkpointEntry.branch_name }
+            if ($checkpointEntry.merge_status) { $mergeStatus = [string] $checkpointEntry.merge_status }
+        }
+        $prState = ''
+        if ($branch -and $ghInstalled) {
+            $prJson = @(Invoke-GhExe -GhArgs @('pr', 'list', '--head', $branch, '--state', 'all', '--json', 'number,state')) -join "`n"
+            $prState = ConvertFrom-EpicProgressPrList -Json $prJson
+        }
+        $planText = $null
+        if ($branch -and $worktreeOf.ContainsKey($branch)) {
+            $livePath = Join-Path -Path $worktreeOf[$branch] -ChildPath $row.PlanPath
+            if (Test-EpicProgressPath -Path $livePath) { $planText = Read-EpicProgressFile -Path $livePath }
+        }
+        if ($null -eq $planText) { $planText = @(Invoke-GitExe -GitArgs @('show', "$($setting.IntegrationBranch):$($row.PlanPath)")) -join "`n" }
+        $count = Get-EpicProgressTaskCount -PlanText $planText
+        $features.Add([pscustomobject]@{
+                Issue = $row.Issue; Wave = $row.Wave; Band = $row.Band; Total = $count.Total; Done = $count.Done
+                State = (Get-EpicProgressFeatureState -MergeStatus $mergeStatus -PrState $prState -Done $count.Done)
+                Phase = (Get-EpicProgressCurrentPhase -PlanText $planText); Pr = $prState
+            })
+    }
+
+    $weeklyPct = [double]::NaN
+    if (Test-EpicProgressCommand -Name 'cswap') {
+        $quotaJson = @(Invoke-CswapExe -CswapArgs @('list', '--json')) -join "`n"
+        $weeklyPct = Get-EpicProgressWeeklyQuota -Json $quotaJson
+    }
+
+    $nowUnixSeconds = [DateTimeOffset]::new($nowUtc).ToUnixTimeSeconds()
+    $done = 0
+    foreach ($record in $features) { $done += $record.Done }
+    $baselineDoneValue = $baseline.BaselineDone
+    if ($baseline.UseCurrentDone) { $baselineDoneValue = $done }
+    $selection = Select-EpicProgressSample -Sample $priorSamples -NowUnixSeconds $nowUnixSeconds -Done $done -SampleCap $SampleCap
+    $currentSamples = $selection.Sample
+    # Pairing is a one-shot rewrite applied after the sample rule (cadence change).
+    if ($PairSamples) { $currentSamples = [object[]] @(Merge-EpicProgressSamplePair -Sample $currentSamples) }
+    if ($selection.Changed -or $ResetBaseline -or $PairSamples) {
+        $startUnixSeconds = [DateTimeOffset]::new($baseline.StartUtc).ToUnixTimeSeconds()
+        $stateJson = ConvertTo-EpicProgressStateJson -StartUnixSeconds $startUnixSeconds -BaselineDone $baselineDoneValue -BaselineWeeklyPct $baseline.BaselineWeeklyPct -Sample $currentSamples
+        Write-EpicProgressState -Path $setting.StatePath -Content $stateJson
+    }
+
+    $summary = Get-EpicProgressSummary -Feature $features.ToArray() -BaselineDone $baselineDoneValue -StartUtc $baseline.StartUtc -NowUtc $nowUtc -Sample $currentSamples -WaveOverheadHours $WaveOverheadHours -WeeklyPct $weeklyPct -BaselineWeeklyPct $baseline.BaselineWeeklyPct -EpicIssue $epicIssueText -EpicName $EpicFolder
+    $lines = [System.Collections.Generic.List[string]]::new()
+    $tldrLines = Get-EpicProgressTldrLine -Summary $summary
+    $lines.AddRange([string[]] $tldrLines)
+    if ($Mode -ne 'TLDR') {
+        $fullLines = Get-EpicProgressFullLine -Summary $summary
+        $lines.AddRange([string[]] $fullLines)
+    }
+    return $lines.ToArray()
+}
+
+# Entry point: skipped when the script is dot-sourced for testing. Git runs in the
+# repository root, so the location is pushed there for the run and restored afterwards.
+if ($MyInvocation.InvocationName -ne '.') {
+    $entryRoot = $RepositoryRoot
+    if ([string]::IsNullOrWhiteSpace($entryRoot)) { $entryRoot = (Get-Location).ProviderPath }
+    Push-Location -LiteralPath $entryRoot
+    try {
+        Invoke-EpicProgressReport @PSBoundParameters
+    } finally {
+        Pop-Location
+    }
+}

package/resources/claude-customizations/.claude/skills/execution-environment/SKILL.md

@@ -11,6 +11,14 @@ This brief states the environment facts that every researcher, planner, prefligh
 
 Maintenance rule: this brief is updated in the same change that alters any fact it states. It carries no line numbers and no commit identifiers; it cites files, symbols, headings, job names, and test names. The same text is byte-identical in six locations: `.claude/skills/execution-environment/SKILL.md`, `.agents/skills/execution-environment/SKILL.md`, `.github/skills/execution-environment/SKILL.md`, and their bundled copies under `extensions/drm-copilot/resources/`. Where the Claude and Codex runtimes differ, both paths are named (`.claude/hooks/...` and `.codex/hooks/...`).
 
+## Development Toolchain Baseline
+
+The host manifest, both devcontainer Dockerfiles, and development CI select Python 3.13.18, Node.js 26.13.0/npm 11.20.0, PowerShell 7.6.9, and Poetry 2.5.1. Both images use `mcr.microsoft.com/devcontainers/python:3.3.2-3.13-bookworm`, require Git >=2.56.0, and install GitHub CLI 2.103.3, .NET SDK 10.0.403, uv 0.13.7, Claude Code 2.1.318, claude-swap 0.29.0, and Codex 0.166.0. Shell validation pins shfmt 3.14.1, ShellCheck 0.11.0, actionlint 1.7.12, and kcov v43. PowerShell selects Pester 6.2.0 and PSScriptAnalyzer 1.25.0. The images also retain Graphite 1.7.14, GitHub Copilot CLI 0.0.377, Bats, and bashdb. Host bootstrap treats manifest versions as minima and preserves equal/newer installations; the container verifier accepts later Python patches within 3.13 and later Git versions, and checks the other selected pins.
+
+The pinned base supplies Python and Git; image-managed CLI installs take precedence on PATH. Full configuration builds include the selected devcontainer features. Local Docker retains the Docker outside-of-Docker feature; floating Git/GitHub CLI features do not replace image pins. Both configurations run the same shared post-create script and mandatory verifier. Local source is a live host bind mount with four `volume-nocopy` Linux dependency volumes for `.venv` and the root, extension, and MCP `node_modules`; setup prepares only their mount roots. A container-only Git environment override disables the host Windows fsmonitor without changing host configuration. The former workspace volume is retained for recovery. Runtime verification uses the Linux environment rather than host Windows dependencies. Codex includes its native optional package, disables the startup update prompt through root-owned system settings, and uses the file credential store; the image does not populate user authentication state. Python bytecode stays under `/tmp/pycache`.
+
+Python 3.11/3.12 compatibility jobs, consumer package engines, and independent release-publishing runtime pins remain unchanged. The shared version predicate lives in `scripts/bash/container_versions.sh`; `.devcontainer/verify-container.sh` resolves it relative to its own repository location.
+
 ## Tool Routes by Agent
 
 - `atomic-executor` has no PowerShell tool. Its `tools:` list is Read, Grep, Glob, Edit, Write, several `Bash(...)` entries, the four `mcp__drm-copilot__run_poshqc_*` tools, and `mcp__drm-copilot__validate_orchestration_artifacts`. A `(pattern)` suffix on a `tools:` entry admits the bare tool, so the executor has Bash, subject to the repository hooks and the runtime guard described under Command-Text Restrictions.
@@ -31,7 +39,8 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 
 - PoshQC MCP results carry no output. The summary string is composed from a fixed template before the child process runs (`runPoshQcWorkflow` in `extensions/drm-copilot/src/repo-automation-service.ts`), and `RepoAutomationExecutionResult` has no exit-code or output field. An `ok: true` result proves only that the tool was invoked.
 - Counts, percentages, and findings therefore come from files or direct runs: pass and fail counts from `artifacts/pester/pester-junit.xml`, line coverage from `artifacts/pester/powershell-coverage.xml`, and analyzer findings from a direct `Invoke-ScriptAnalyzer` run with `scripts/powershell/PoshQC/settings/pssa.settings.psd1`.
-- The MCP test tool reads the installed extension's settings. Branch-current Pester runs import `scripts/powershell/PoshQC/PoshQC.psd1` and call `Invoke-PoshQCTest` from a `sh`-launched PowerShell 7. The coverage population is derived by `Invoke-PoshQCTest` from `config/poshqc-coverage.json`; there is no hand-maintained coverage path list.
+- The MCP test tool reads the installed extension's settings. Branch-current Pester runs import `scripts/powershell/PoshQC/PoshQC.psd1` and call `Invoke-PoshQCParallelTest` from a `sh`-launched PowerShell 7. The coverage population is derived by `Invoke-PoshQCTest`, which each shard runs, from `config/poshqc-coverage.json`; there is no hand-maintained coverage path list.
+- `Invoke-PoshQCParallelTest` returns an object whose `ExitCode` is read first, and the launcher exits with that value. Merged JUnit and coverage exist only after a fully green run, and a failed run can leave older merged files in place. Failure detail is under `artifacts/pester/parallel/shard-<i>/`.
 - `Invoke-Pester` without `-EnableExit` (or `Run.Exit`) exits 0 when tests fail; read the JUnit file rather than the exit code of such a run.
 
 ## Batch Budget
@@ -50,6 +59,8 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 - Hooks for an isolated subagent run inside the subagent's worktree with that worktree's hook scripts, which are `main`'s copies. A hook change on a branch is not exercised by isolated subagents until it merges.
 - Hook behavior on a branch is therefore proven by Pester suites, not by a live subagent run. A live check of a branch hook needs a non-isolated delegation from the item worktree.
 - The batch-budget hooks evaluate the checkpoint of the target worktree that `Resolve-HookTargetWorktree` resolves for the edited file, so an edit made from a coordinating session into an item worktree is evaluated against the item worktree's checkpoint. The preimplementation gate (#1010) resolves the file path of a Write or Edit call and the `-C` values and absolute operands of `git add` and `git commit` through the same resolver, and denies when the worktree listing fails or names no worktree; its delegation checks still resolve by portable identity. The PR authoring gate (#1011) resolves the branch that a `gh pr create` or `gh pr edit` command names (`--head`, `--branch`, or a `branch:` label) through the same resolver when the command carries no canonical issue number line, and otherwise keeps its portable-identity and current-branch resolution. The other gates that read `artifacts/orchestration/orchestrator-state.json` are unchanged and still use the root that holds the hook script.
+- Cleanup legs (#1026): a `cleanup-merged-worktrees` run writes no checkpoint, so the preimplementation gate (`.claude/hooks/enforce-orchestration-preimplementation-gate-cleanup.ps1` and its `.codex/hooks/` twin), the PR-authoring gate (`.claude/hooks/enforce-pr-author-skill.cleanup.ps1`), and the model-routing gate (`.claude/hooks/enforce-model-routing-receipt.ps1`) carry allow-side cleanup legs, evaluated only where each gate would otherwise deny, that share the pure predicates of `hook-cleanup-context.ps1`. The legs admit a Write of the session-root manifest `artifacts/orchestration/cleanup-worktrees-manifest.json` with valid content (an Edit stays denied), Write or Edit of paths under `docs/` or `.claude/agent-memory/` and of the pr-author receipt inside the consolidation worktree on branch `documentationandmemories`, `git -C <consolidation root> add` and `commit` of those paths, `Agent(pr-author)` with `branch: documentationandmemories`, and `gh pr create --head documentationandmemories --base main` while a fresh valid manifest exists at the session root and the pushed `refs/remotes/origin/documentationandmemories` resolves to the same commit as the consolidation worktree `HEAD`. A preimplementation-gate denial appends a cleanup sub-code (`Cleanup leg not applied`) only after a cleanup leg has identified the consolidation worktree as the target and a later condition fails; a call rejected by a prefilter keeps the unchanged deny text even when its target is the consolidation worktree, as does every other call.
+- Scratch rule (#1026): the preimplementation gate allows a Write or Edit of an absolute local path that lies outside every registered worktree and the session root and under a temporary root, read through the seam `Get-OrchestrationGateTemporaryRoot` (the long-name `GetTempPath()` value and the `TEMP`, `TMP`, and `TMPDIR` values, which can carry the 8.3 short-name spelling). The rule fails closed when any registered worktree lies under a temporary root.
 - Enforcement hooks do not invoke Python; bash is preferred and PowerShell is acceptable (`tests/scripts/claude-runtime/enforcement-hooks-no-python-invocation.Tests.ps1`).
 
 ## MCP Surfaces Run the Installed Extension
@@ -61,14 +72,14 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 ## CI Shape and Required Checks
 
 - `.github/workflows/ci.yml` triggers on `push` to `main` and `development`, on `pull_request` to `main`, `development`, and `epic/**`, on `workflow_dispatch`, and on `merge_group` (`types: [checks_requested]`, added by issue #952), with no path filters. When the merge queue on `main` is enabled, every required check is produced by a `merge_group` run of `ci.yml` as well as by the pull-request run; `.github/workflows/README.md` (`## Triggers`) records the trigger set.
-- Jobs in `ci.yml` and their check names: `Change scope` (job `changes`, the change-scope decision below); `CI full run` (job `full-run-marker`, which runs only on a full run, marks that run as a valid base for later decisions, and is not a required check); `quality-checks7 / Code Quality & Tests (<python-version>)` on Python 3.11, 3.12, and 3.13 (`_quality-checks.yml`: Black check, Ruff, Pyright, the Codex generator `--check`, the tier classification, and Pytest on every version; Pytest with line and branch coverage and the coverage-threshold check on the JSON report totals run on 3.13 only); `security-scan / Security Scanning` (its `safety check` step carries `continue-on-error: true` and does not fail the check); `docs-validation / Documentation Validation`; `build-check / Build Package`; `shell-coverage / Shell Coverage (Bats + kcov)`; `drm-copilot-extension-tests / drm-copilot Extension Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `root-typescript-tests / Root TypeScript Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `NPM Audit Gate / npm audit (<manifest>)` (the calling job carries the name `NPM Audit Gate`); and the `poshqc` group below.
+- Jobs in `ci.yml` and their check names: `Change scope` (job `changes`, the change-scope decision below); `CI full run` (job `full-run-marker`, which runs only on a full run, marks that run as a valid base for later decisions, and is not a required check); `quality-checks7 / Code Quality & Tests (<python-version>)` on Python 3.11, 3.12, and 3.13 (`_quality-checks.yml`: Black check, Ruff, Pyright, the Codex generator `--check`, the tier classification, and Pytest on every version; Pytest with line and branch coverage and the coverage-threshold check on the JSON report totals run on 3.13 only); `security-scan / Security Scanning` (its `safety check` step carries `continue-on-error: true` and does not fail the check); `docs-validation / Documentation Validation`; `build-check / Build Package`; `shell-coverage / Shell Coverage (Bats + kcov)`; `drm-copilot-extension-tests / drm-copilot Extension Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `root-typescript-tests / Root TypeScript Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `NPM Audit Gate / npm audit (<manifest>)` (the calling job carries the name `NPM Audit Gate`); the `poshqc` group below; and `CI Required Gate` (job `ci-required-gate`, issue #1074), which needs every other `ci.yml` job, runs under `if: always()` on `ubuntu-latest`, and passes `toJSON(needs)` to `scripts/ci/Invoke-CiRequiredGate.ps1`. The gate is green on a full run only when every needed job is `success`, and on a docs-only run only when `CI full run`, `root-typescript-tests`, and `NPM Audit Gate` are `success` or `skipped` and every other needed job is `success`; a `failure`, `cancelled`, or unknown result, a `Change scope` result other than `success`, and unreadable input are red. `tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1` pins its `needs:` set against the other job ids of `ci.yml`.
 - PowerShell CI (`_poshqc.yml`): `poshqc / PowerShell QC static` (format and analyze on `windows-latest`); the shard matrix `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3` (`Invoke-PoshQCTest -ShardIndex -ShardCount` over the scan folders of `config/poshqc-scan.json`, with coverage, on `windows-latest`); the aggregator `poshqc / PowerShell QC`, which requires the static and shard jobs to succeed, verifies shard completeness against a Pester discovery count, and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)`, which runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest` with coverage disabled. A new test file under a scanned folder is assigned to a shard automatically and is counted by the completeness check.
 - Change-scope decision (issue #962): the `Change scope` job runs `scripts/ci/Invoke-CiChangeScope.ps1` and publishes the job output `code`. The decision is `code=false` (docs-only) only on a `pull_request` event from this repository, through one of two comparisons. Green-run base: every file changed since the newest successful `ci.yml` run on the pull-request branch whose `CI full run` job succeeded, and whose head commit is present and an ancestor of the current head, is on the allowlist `config/ci-docs-only-paths.json`; the reason is `DOCS_ONLY_SINCE_<green head sha>`. Merge-base fallback (issue #973): when the green-run step ends with no earlier full green run (`NO_FULL_GREEN_RUN`), a missing base (`BASE_NOT_PRESENT`), or a non-ancestor base (`BASE_NOT_ANCESTOR`), and the pull request's base ref is exactly `main`, the script computes `git merge-base` of the payload base SHA (`BASE_SHA`, from `github.event.pull_request.base.sha`; the base ref arrives as `BASE_REF`) and the head, lists the files changed since that merge base with the same diff arguments, and decides `DOCS_ONLY_SINCE_MERGE_BASE_<merge base sha>` when every changed file is allowlisted. Both comparisons run the diff with rename detection off, so both the old and the new path of a rename are classified. A path is allowlisted when it starts with `docs/features/active/`, `docs/features/archive/`, `docs/features/completed/`, `docs/features/epics/`, `docs/features/parallel/`, `docs/features/potential/`, or `docs/research/`, does not start with `docs/features/templates/` or `docs/features/potential/template.md`, and ends in `.md`, `.txt`, `.log`, `.json`, or `.xml`; the allowlist file itself is not allowlisted. Every other case is a full run (`code=true`): `push`, `merge_group`, and `workflow_dispatch` events, a fork pull request, unreadable run or job data, no earlier full green run or a missing or non-ancestor base when the base ref is not `main`, a merge base that cannot be resolved (`MERGE_BASE_UNRESOLVED`, for example a blank base SHA or a base commit missing from the checkout), a failed ancestry check, an empty diff, any path outside the allowlist, and any error. The decision step carries `continue-on-error: true` and the callers compare the output with `!= 'false'`, so a failed or missing decision also gives a full run.
-- Docs-only behavior (`code=false`): `ci.yml` passes `run-heavy: false` to `_quality-checks.yml`, `_security-scan.yml`, `_build-check.yml`, `_poshqc.yml`, `_shell-coverage.yml`, and `_drm-copilot-extension-tests.yml`. Each required job still starts under its full-run check name with every step skipped, so every required context reports `success` without running its suite. In `_poshqc.yml` the aggregator `poshqc / PowerShell QC` runs with every step gated, and `poshqc / PowerShell QC static`, the shard jobs, and `poshqc / PowerShell hook suites (Linux)` are skipped at job level. `docs-validation / Documentation Validation` runs in full. `root-typescript-tests`, `NPM Audit Gate`, and `CI full run` are skipped at job level. A `success` on a docs-only commit is therefore not evidence that the heavy suites pass for that commit; that evidence is the newest run whose `CI full run` job succeeded.
+- Docs-only behavior (`code=false`): `ci.yml` passes `run-heavy: false` to `_quality-checks.yml`, `_security-scan.yml`, `_build-check.yml`, `_poshqc.yml`, `_shell-coverage.yml`, and `_drm-copilot-extension-tests.yml`. Each job that runs with its steps gated still starts under its full-run check name with every step skipped, so it reports `success` without running its suite. In `_poshqc.yml` the aggregator `poshqc / PowerShell QC` runs with every step gated, and `poshqc / PowerShell QC static`, the shard jobs, and `poshqc / PowerShell hook suites (Linux)` are skipped at job level. `docs-validation / Documentation Validation` runs in full. `root-typescript-tests`, `NPM Audit Gate`, and `CI full run` are skipped at job level. Eight currently required contexts therefore never report on a docs-only run: `poshqc / PowerShell QC shard 1`, `poshqc / PowerShell QC shard 2`, `poshqc / PowerShell QC shard 3`, `root-typescript-tests / Root TypeScript Tests (ubuntu-latest)`, `root-typescript-tests / Root TypeScript Tests (windows-latest)`, `NPM Audit Gate / npm audit (.)`, `NPM Audit Gate / npm audit (extensions/drm-copilot)`, and `NPM Audit Gate / npm audit (packages/mcp-server)`, so a docs-only head stays blocked under the 20-context ruleset. `CI Required Gate` passes on a docs-only run, because it accepts `skipped` for exactly those skipped callers. A `success` on a docs-only commit is therefore not evidence that the heavy suites pass for that commit; that evidence is the newest run whose `CI full run` job succeeded.
 - A commit that changes any path outside the allowlist (any code, workflow, configuration, script, test, or customization file) runs the full set of jobs, and its `CI full run` job marks it as a base for later docs-only decisions. A standalone `workflow_dispatch` of a reusable workflow, or a caller that omits `run-heavy`, also runs in full. `.github/workflows/README.md` (`## Change-Scope Decision (Issue #962)`) records the reason codes and the per-context behavior table.
-- Required contexts of ruleset 15241672, confirmed by the orchestrator through `gh api` on 2026-10-16: `drm-copilot-extension-tests / drm-copilot Extension Tests (ubuntu-latest)`, `drm-copilot-extension-tests / drm-copilot Extension Tests (windows-latest)`, `docs-validation / Documentation Validation`, `poshqc / PowerShell QC`, `shell-coverage / Shell Coverage (Bats + kcov)`, `security-scan / Security Scanning`, `quality-checks7 / Code Quality & Tests (3.11)`, `quality-checks7 / Code Quality & Tests (3.12)`, `quality-checks7 / Code Quality & Tests (3.13)`, `build-check / Build Package`.
-- Refresh rule: a change that renames a job, adds or removes a matrix entry, or changes the ruleset refreshes this list in the same change, and the orchestrator re-confirms the contexts with a read-only `gh api repos/drmoisan/drm-copilot/rulesets/15241672` call before relying on them.
-- Skipped-check semantics: a job skipped by an `if:` condition reports success to a required check; a workflow that does not run at all reports nothing, which leaves the required check pending.
+- Required contexts of ruleset 15241672, read through a read-only `gh api` call on 2026-11-04 (20 contexts, each with `integration_id` 15368): `drm-copilot-extension-tests / drm-copilot Extension Tests (ubuntu-latest)`, `drm-copilot-extension-tests / drm-copilot Extension Tests (windows-latest)`, `docs-validation / Documentation Validation`, `poshqc / PowerShell QC`, `shell-coverage / Shell Coverage (Bats + kcov)`, `security-scan / Security Scanning`, `quality-checks7 / Code Quality & Tests (3.11)`, `quality-checks7 / Code Quality & Tests (3.12)`, `quality-checks7 / Code Quality & Tests (3.13)`, `build-check / Build Package`, `NPM Audit Gate / npm audit (extensions/drm-copilot)`, `NPM Audit Gate / npm audit (.)`, `NPM Audit Gate / npm audit (packages/mcp-server)`, `root-typescript-tests / Root TypeScript Tests (ubuntu-latest)`, `root-typescript-tests / Root TypeScript Tests (windows-latest)`, `poshqc / PowerShell QC shard 1`, `poshqc / PowerShell QC shard 2`, `poshqc / PowerShell QC shard 3`, `poshqc / PowerShell QC static`, `poshqc / PowerShell hook suites (Linux)`. After the owner's post-merge ruleset edit (issue #1074 runbook), the single required context is `CI Required Gate` (`integration_id` 15368), and the individual job contexts remain visible but are no longer required.
+- Refresh rule: a change that renames a job, adds or removes a `ci.yml` job or a matrix entry, or changes the ruleset refreshes this list in the same change, and the orchestrator re-confirms the contexts with a read-only `gh api repos/drmoisan/drm-copilot/rulesets/15241672` call before relying on them. A new `ci.yml` job must also be added to the `needs:` list of `ci-required-gate`; `tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1` fails until it is.
+- Skipped-check semantics: a job skipped by an `if:` condition reports success to a required check; a workflow that does not run at all reports nothing, which leaves the required check pending. A matrix job skipped at job level reports no expanded context (its matrix name is never expanded), and a reusable-workflow caller skipped in `ci.yml` reports no nested contexts, so each such required context stays pending.
 - A pull request into a branch other than `main`, `development`, or `epic/**` gets no CI run; dispatch `ci.yml` manually for it.
 
 ## CI-Only Failure Classes
@@ -78,7 +89,7 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 - `_shell-coverage.yml` checks out at depth one, so `origin/main` does not exist in that job; no test may diff against it.
 - The Linux hook-suite job runs `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on a case-sensitive file system: use `Join-Path`, forward-slash relative paths, exact file-name case, and no drive letters or backslash literals.
 - The `.gitattributes` rule `* text=auto eol=lf` normalizes line endings on checkout, so a CRLF fixture committed as text is not CRLF in CI.
-- Shard and single-process Pester runs expose module-scope import visibility and leaked state that per-suite local runs hide.
+- Files in one shard share a process, so a leak surfaces when shard contents change.
 
 ## Contract Tests That Pin Mirrored Files
 
@@ -95,6 +106,7 @@ Run these after editing any mirrored or bundled file; each is under `tests/scrip
 - `test_push_down_issue_824_follow_ups.py`: pushed rules and skills name no consuming product.
 - `test_typescript_toolchain_instruction_contracts.py`: no reference to another test framework, and every backticked npm script token in the pinned mirrors exists in the root `package.json`.
 - `tests/scripts/claude-runtime/claude-architecture-doc.Tests.ps1` and `tests/scripts/claude-runtime/hook-dependency-guard-completeness.Tests.ps1`: agent tool names in the architecture document and the guarded dot-source pattern in hooks.
+- `tests/scripts/claude-runtime/parallel-gate-wording.Tests.ps1`: per-file required and forbidden gate wording in the mirrored skills, agents, and templates, and the sweep of those surfaces for removed test-suite baseline wording.
 
 ## Preflight Defect Classes the Validator Cannot See
 
@@ -125,6 +137,7 @@ These pass every validator rule and are found only by reading the plan against t
 - Python: measure a module with `--cov=<dotted.module>`, `--cov-branch`, `--cov-report=term-missing`, and `--cov-report=json:<path>`; read branch figures from the JSON report.
 - TypeScript: a new production file needs its own entry in the `coverageThreshold` map of `extensions/drm-copilot/jest.config.cjs`; Jest runs through `node run-jest.cjs` in `extensions/drm-copilot/`.
 - PowerShell: per-file line coverage is read from `artifacts/pester/powershell-coverage.xml` written by the self-hosted PoshQC module.
+- Per-file figures are read from the single gate run, and no earlier figure is compared.
 - File size follows three tiers for production, test, and reusable script files, counted in logical lines (a trailing terminator adds no line): at 500 lines look for a logical split (guidance); at 700 lines split more aggressively, and reviewers report a non-blocking Warning (advisory); above 800 lines a split is enforced regardless of logical separability (hard limit; exactly 800 passes). The hard limit is enforced by `tests/scripts/ci/FileSizePolicy.RepoGate.Tests.ps1` in the existing PowerShell shards against `config/file-size-baseline.json`, where legacy files above 800 may shrink (with the entry tightened) or stay equal but may not grow, and by the PreToolUse hook `.claude/hooks/enforce-file-size-limit.ps1` (`.codex/hooks/enforce-file-size-limit.ps1`). New logic in a file near a tier goes into a new module and a new test file. Markdown is exempt.
 
 ## Test Runtime
@@ -134,17 +147,19 @@ These pass every validator rule and are found only by reading the plan against t
 - Fix repeated production work first. An immutable structure, such as a schema registry that is rebuilt and re-verified on every call, is built once per owning instance. This speeds up the runtime as well as the tests.
 - Second, build an expensive immutable fixture once per session and hand each test its own copy wherever a test could mutate it, so test independence is unchanged.
 - Parallel workers reduce wall-clock time only: they are capped by the slowest test and leave the cost in the product.
-- pytest: pass `-n auto` (pytest-xdist) on the command line of the CI step `Run tests with Pytest` and of the parallel VS Code tasks, never in `addopts`, because the VS Code Test Explorer keys results to the wrong file when `addopts` carries it. `-n auto` counts physical cores, so a runner can start fewer workers than it has vCPUs; measure it against an explicit count such as `-n 4` before keeping it. pytest-cov combines the worker coverage into one report, and the serial `poetry run pytest` command remains the isolation reference.
-- Pester: Pester 5 has no in-process parallel mode, so parallel Pester runs are process-per-shard: `Invoke-PoshQCTest -ShardIndex -ShardCount` on the CI runners and `Invoke-PoshQCParallelTest` locally. Read the per-file `time` of the JUnit `testsuite` elements before changing the shard count or the weights in `config/poshqc-shard-weights.json`.
+- pytest: pass `-n auto` (pytest-xdist) on the command line of the CI step `Run tests with Pytest` and of the parallel VS Code tasks, never in `addopts`, because the VS Code Test Explorer keys results to the wrong file when `addopts` carries it. `-n auto` counts physical cores, so a runner can start fewer workers than it has vCPUs; measure it against an explicit count such as `-n 4` before keeping it. pytest-cov combines the worker coverage into one report.
+- Pester: parallel validation uses separate Pester 6 processes: `Invoke-PoshQCTest -ShardIndex -ShardCount` on the CI runners and `Invoke-PoshQCParallelTest` locally. Read the per-file `time` of the JUnit `testsuite` elements before changing the shard count or the weights in `config/poshqc-shard-weights.json`.
 - A candidate fix can be measured before the tree is edited by loading a pytest plugin module from `SCRATCH` with `-p <module>` and `PYTHONPATH`.
 
 ## Test Isolation Checks
 
 - Tests create no temporary files; file and transcript reads go through injected seams with in-memory content.
-- Before review, run each isolation check and record it under `<FEATURE>/evidence/regression-testing/`:
-  - a seeded shuffled Jest run (`node run-jest.cjs --randomize --seed=<n>` in `extensions/drm-copilot/`) with the seed recorded;
-  - a reversed-order run of the new or changed Python test modules in one process;
-  - a seeded shuffled file-order run of the touched Pester suites in one process, with at least three seeds and each seed and its file order recorded;
-  - a fresh single-process Pester run over `tests/scripts`, which is the CI shape;
-  - in addition to the serial runs, a concurrent-shard Pester run through `Invoke-PoshQCParallelTest` and a `pytest -n auto` run, both with zero failures.
-- An order dependence found by any run is fixed on both sides: the suite that leaves state behind (globals, functions, environment variables, mocks, imported modules, script-scope state) and the suite that assumes prior state. Every seed is then re-run.
+- The test gates are parallel:
+  - the Pester gate is one `Invoke-PoshQCParallelTest` run;
+  - the pytest gate is one `pytest -n auto` run;
+  - Jest runs through its normal parallel workers.
+- Each gate reaches zero failures and is re-run only after a fix.
+- A focused run of one test file to debug a specific failure is debugging only; it is never a gate or evidence.
+- Serial tasks remain for debugging one failure and are not gates.
+- A leak found by a gate is fixed on both sides: the suite that leaves state behind (globals, functions, environment variables, mocks, imported modules, script-scope state) and the suite that assumes prior state.
+- The parallel gates govern where a policy file names a toolchain test command.