@danmoisan/drm-copilot-mcp 1.1.25 → 1.1.26

package/resources/codex-and-agents-customizations/.codex/hooks/hook-cleanup-context.ps1

@@ -0,0 +1,343 @@
+<#
+.SYNOPSIS
+    Pure cleanup-context predicates shared by the cleanup legs of the enforcement gates (issue #1026).
+
+.DESCRIPTION
+    The cleanup-merged-worktrees skill writes no per-feature, epic, or parallel checkpoint, so
+    the checkpoint-based gates cannot recognize its writes, commits, delegation, and pull
+    request. Its integrity record is the sanctioned-removal manifest. This file holds the pure
+    decisions the gates' cleanup legs share:
+
+      Test-CleanupManifestText              - the manifest header (tool, schema_version) and,
+                                              with -UtcNow, its freshness and run_id.
+      Test-CleanupConsolidationRelativePath - the allowlist: the repository-relative prefixes
+                                              docs/ and .claude/agent-memory/ (ordinal,
+                                              case-sensitive), plus the pr-author receipt
+                                              artifacts/pr_body_<digits>.receipt.json with
+                                              -AllowReceipt.
+      Find-CleanupConsolidationRecord       - the consolidation worktree, identified by its
+                                              porcelain branch, never by its path.
+      Test-CleanupScratchPath               - the scratch rule: an absolute path outside every
+                                              registered worktree and the session root, under a
+                                              temporary root.
+      Test-CleanupConsolidationBranchLabel  - the delegation label rule of the model-routing leg.
+
+    Every function fails closed: a malformed or ambiguous input answers $false or $null.
+
+    The literals below restate values owned elsewhere: the branch equals
+    CLEANUP_WT_CONSOLIDATION_BRANCH in
+    .claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_actions_lib.sh, and the
+    manifest tool, schema version, and freshness bound equal $script:ExpectedManifestTool,
+    $script:ExpectedManifestSchemaVersion, and $script:ManifestFreshnessBound in
+    .claude/lib/cleanup-manifest/CleanupWorktreeManifest.psm1. The Codex hooks cannot import
+    .claude/lib, so the values are restated here and pinned equal by
+    tests/scripts/claude-hooks/hook-cleanup-context.Parity.Tests.ps1. The names avoid the
+    removal gates' $script:CleanupWorktreeManifestPath.
+
+.NOTES
+    PowerShell 7+. Functions and literals only: no file, process, network, clock, or
+    environment access, no dot-source, and no import. Byte-identical at .claude/hooks,
+    .codex/hooks, and both bundle mirrors under extensions/drm-copilot/resources/.
+#>
+
+$script:CleanupContextBranch = 'documentationandmemories'
+$script:CleanupContextManifestRelativePath = 'artifacts/orchestration/cleanup-worktrees-manifest.json'
+$script:CleanupContextManifestTool = 'cleanup-merged-worktrees'
+$script:CleanupContextManifestSchemaVersion = 1
+$script:CleanupContextFreshnessHours = 24
+
+function Test-CleanupManifestText {
+    <#
+    .SYNOPSIS
+        Return $true when the text is a cleanup manifest with the expected header.
+    .DESCRIPTION
+        The text must parse as a JSON object whose tool is the string cleanup-merged-worktrees
+        (ordinal) and whose schema_version is the integer 1. When -UtcNow is supplied, the
+        manifest must also carry a generated_at that parses, is not after UtcNow, and lies
+        within the freshness bound, and a run_id that is a non-blank string. The generated_at
+        value is read exactly as CleanupWorktreeManifest.psm1 reads it, so the PR and
+        delegation legs agree with the removal gates on freshness.
+    .PARAMETER Raw
+        The manifest text, or $null when no manifest exists.
+    .PARAMETER UtcNow
+        The current UTC time from the caller's clock seam.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Raw,
+        [datetime] $UtcNow
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Raw)) {
+        return $false
+    }
+    try {
+        $manifest = $Raw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return $false
+    }
+    if ($manifest -isnot [System.Management.Automation.PSCustomObject]) {
+        return $false
+    }
+    $names = @($manifest.PSObject.Properties.Name)
+    if ($names -notcontains 'tool' -or $names -notcontains 'schema_version') {
+        return $false
+    }
+    if ($manifest.tool -isnot [string] -or $manifest.tool -cne $script:CleanupContextManifestTool) {
+        return $false
+    }
+    $schemaVersion = $manifest.schema_version
+    if (($schemaVersion -isnot [int] -and $schemaVersion -isnot [long]) -or [long]$schemaVersion -ne $script:CleanupContextManifestSchemaVersion) {
+        return $false
+    }
+    if (-not $PSBoundParameters.ContainsKey('UtcNow')) {
+        return $true
+    }
+
+    if ($names -notcontains 'generated_at' -or $names -notcontains 'run_id') {
+        return $false
+    }
+    $generatedAt = [datetime]::MinValue
+    $styles = [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal
+    if (-not [datetime]::TryParse([string]$manifest.generated_at, [cultureinfo]::InvariantCulture, $styles, [ref] $generatedAt)) {
+        return $false
+    }
+    if ($generatedAt -gt $UtcNow -or ($UtcNow - $generatedAt) -gt [timespan]::FromHours($script:CleanupContextFreshnessHours)) {
+        return $false
+    }
+    return ($manifest.run_id -is [string] -and -not [string]::IsNullOrWhiteSpace($manifest.run_id))
+}
+
+function Test-CleanupConsolidationRelativePath {
+    <#
+    .SYNOPSIS
+        Return $true when a repository-relative path is on the consolidation allowlist.
+    .DESCRIPTION
+        The path must use only the plain characters A-Z a-z 0-9 . _ / -, must not be rooted,
+        must carry no '..' segment, and must start with docs/ or .claude/agent-memory/ under
+        ordinal, case-sensitive comparison with at least one character after the prefix. Any
+        other Markdown path, such as CLAUDE.md or .claude/rules/x.md, is not admitted. With
+        -AllowReceipt the pr-author receipt artifacts/pr_body_<digits>.receipt.json is also
+        admitted; it never enters the staging allowlist.
+    .PARAMETER RelativePath
+        The repository-relative path or operand.
+    .PARAMETER AllowReceipt
+        Admit the pr-author receipt path (Write and Edit leg only).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $RelativePath,
+        [switch] $AllowReceipt
+    )
+
+    $path = [string]$RelativePath
+    if ($path -cnotmatch '^[A-Za-z0-9._/-]+$' -or $path.StartsWith('/')) {
+        return $false
+    }
+    if (@($path -split '/') -contains '..') {
+        return $false
+    }
+    if ($AllowReceipt -and $path -cmatch '^artifacts/pr_body_[0-9]+\.receipt\.json$') {
+        return $true
+    }
+    foreach ($prefix in @('docs/', '.claude/agent-memory/')) {
+        if ($path.Length -gt $prefix.Length -and $path.StartsWith($prefix, [System.StringComparison]::Ordinal)) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Find-CleanupConsolidationRecord {
+    <#
+    .SYNOPSIS
+        Return the registered consolidation worktree record, or $null.
+    .DESCRIPTION
+        Takes the records ConvertFrom-HookTargetWorktreePorcelain emits. The first record (the
+        main worktree stanza), prunable records, and detached records are skipped. The single
+        remaining record whose Branch is ordinal-equal to documentationandmemories is returned;
+        none, or more than one, returns $null. The path is never consulted, because the
+        consolidation path can be overridden by CLEANUP_WT_CONSOLIDATION_PATH.
+    .PARAMETER Record
+        The porcelain records, in listing order.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][AllowEmptyCollection()][object[]] $Record
+    )
+
+    $records = @($Record | Where-Object { $null -ne $_ })
+    $found = [System.Collections.Generic.List[object]]::new()
+    for ($index = 1; $index -lt $records.Count; $index++) {
+        $candidate = $records[$index]
+        if ([bool]$candidate.Prunable -or $null -eq $candidate.Branch) {
+            continue
+        }
+        if ([string]$candidate.Branch -ceq $script:CleanupContextBranch) {
+            $found.Add($candidate)
+        }
+    }
+    if ($found.Count -ne 1) {
+        return $null
+    }
+    return $found[0]
+}
+
+function ConvertTo-CleanupContextPath {
+    <#
+    .SYNOPSIS
+        Normalize a path to forward slashes with one trailing slash removed (bare roots kept).
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Path
+    )
+
+    $normalized = ([string]$Path).Replace('\', '/')
+    if ($normalized.Length -gt 1 -and $normalized.EndsWith('/') -and $normalized -notmatch '^[A-Za-z]:/$') {
+        $normalized = $normalized.Substring(0, $normalized.Length - 1)
+    }
+    return $normalized
+}
+
+function Test-CleanupContextPathUnder {
+    <#
+    .SYNOPSIS
+        Return $true when a normalized path equals a root or lies beneath it (OrdinalIgnoreCase).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string] $Path,
+        [AllowNull()][AllowEmptyString()][string] $Root
+    )
+
+    $normalizedRoot = ConvertTo-CleanupContextPath -Path $Root
+    if ([string]::IsNullOrEmpty($normalizedRoot)) {
+        return $false
+    }
+    if ([string]::Equals($Path, $normalizedRoot, [System.StringComparison]::OrdinalIgnoreCase)) {
+        return $true
+    }
+    $prefix = if ($normalizedRoot.EndsWith('/')) { $normalizedRoot } else { $normalizedRoot + '/' }
+    return $Path.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+function Test-CleanupScratchPath {
+    <#
+    .SYNOPSIS
+        Return $true when a path is a scratch path under a temporary root and outside every worktree.
+    .DESCRIPTION
+        The path must be absolute (drive-rooted or slash-rooted, not UNC), carry no '.' or '..'
+        segment and no surrounding whitespace, lie outside every registered worktree root and
+        outside the session root, and lie under at least one accepted temporary-root spelling.
+        Comparisons use forward-slash normalization and OrdinalIgnoreCase. The rule fails
+        closed when no registered root or no temporary root is supplied, and when any
+        registered worktree root lies under an accepted temporary root, because a path under
+        such a worktree could then be spelled so that it matches no registered root.
+    .PARAMETER Path
+        The Write or Edit file path.
+    .PARAMETER RegisteredRoot
+        Every registered worktree root from the listing, prunable ones included.
+    .PARAMETER SessionRoot
+        The session root.
+    .PARAMETER TemporaryRoot
+        Every accepted spelling of the operating-system temporary root.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Path,
+        [AllowNull()][AllowEmptyCollection()][string[]] $RegisteredRoot,
+        [AllowNull()][AllowEmptyString()][string] $SessionRoot,
+        [AllowNull()][AllowEmptyCollection()][string[]] $TemporaryRoot
+    )
+
+    $raw = [string]$Path
+    if ([string]::IsNullOrEmpty($raw) -or $raw.Trim() -cne $raw) {
+        return $false
+    }
+    $normalized = ConvertTo-CleanupContextPath -Path $raw
+    if ($normalized -notmatch '^([A-Za-z]:/|/(?!/))') {
+        return $false
+    }
+    $segments = @($normalized -split '/')
+    if ($segments -contains '.' -or $segments -contains '..') {
+        return $false
+    }
+    $roots = @($RegisteredRoot | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    $temporary = @($TemporaryRoot | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    if ($roots.Count -eq 0 -or $temporary.Count -eq 0 -or [string]::IsNullOrWhiteSpace($SessionRoot)) {
+        return $false
+    }
+    foreach ($registeredCandidate in $roots) {
+        $normalizedRoot = ConvertTo-CleanupContextPath -Path $registeredCandidate
+        foreach ($temporaryCandidate in $temporary) {
+            if (Test-CleanupContextPathUnder -Path $normalizedRoot -Root $temporaryCandidate) {
+                return $false
+            }
+        }
+        if (Test-CleanupContextPathUnder -Path $normalized -Root $registeredCandidate) {
+            return $false
+        }
+    }
+    if (Test-CleanupContextPathUnder -Path $normalized -Root $SessionRoot) {
+        return $false
+    }
+    foreach ($temporaryCandidate in $temporary) {
+        $normalizedTemporary = ConvertTo-CleanupContextPath -Path $temporaryCandidate
+        if (-not [string]::Equals($normalized, $normalizedTemporary, [System.StringComparison]::OrdinalIgnoreCase) -and
+            (Test-CleanupContextPathUnder -Path $normalized -Root $normalizedTemporary)) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Test-CleanupConsolidationBranchLabel {
+    <#
+    .SYNOPSIS
+        Return $true when a delegation prompt names the consolidation branch by exactly one label.
+    .DESCRIPTION
+        The prompt must contain exactly one 'branch:' label (case-insensitive count), on its own
+        line in the lowercase form 'branch: <value>', with the value ordinal-equal to
+        documentationandmemories, and no --head or --branch token anywhere, so the worktree
+        resolvers that read the first branch signal cannot select a different branch.
+    .PARAMETER PromptText
+        The delegation prompt.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $PromptText
+    )
+
+    $text = [string]$PromptText
+    if ([regex]::Matches($text, '(?i)\bbranch:').Count -ne 1) {
+        return $false
+    }
+    if ([regex]::IsMatch($text, '(?i)(?<![\w-])--(?:head|branch)(?![\w-])')) {
+        return $false
+    }
+    $label = [regex]::Match($text, '(?m)^[ \t]*branch:[ \t]*(?<value>[^\r\n]*?)[ \t]*\r?$')
+    return ($label.Success -and $label.Groups['value'].Value -ceq $script:CleanupContextBranch)
+}

package/resources/codex-and-agents-customizations/pack-manifests/core.json

@@ -57,6 +57,8 @@
     ".codex/hooks/enforce-epic-root-invocation.ps1",
     ".codex/hooks/enforce-epic-wave-barrier.ps1",
     ".codex/hooks/enforce-epic-worktree-removal-gate.ps1",
+    ".codex/hooks/enforce-orchestration-preimplementation-gate-cleanup.ps1",
+    ".codex/hooks/hook-cleanup-context.ps1",
     ".codex/hooks/enforce-orchestration-preimplementation-gate-epic-resolution.ps1",
     ".codex/hooks/enforce-orchestration-preimplementation-gate-epic-scope.ps1",
     ".codex/hooks/enforce-orchestration-preimplementation-gate-helpers.ps1",

package/resources/customizations/.github/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 use Python 3.13.17, Node.js 26.13.0/npm 11.20.0, PowerShell 7.6.9, and Poetry 2.3.2. Shell validation pins shfmt 3.14.1, ShellCheck 0.11.0, and actionlint 1.7.12. Host bootstrap treats manifest versions as minima and preserves equal/newer installations; the container verifier accepts later Python patches within 3.13 and checks the other selected pins.
+
+The devcontainer minor image can lag the Python patch, so both Dockerfiles copy the verified official Python runtime stage and select it and NodeSource ahead of older base-feature shims. Full configuration builds include the selected devcontainer features; a raw Dockerfile image alone does not prove feature-provided commands. Runtime verification uses an isolated Linux virtual environment rather than the host Windows environment.
+
+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.
@@ -50,6 +58,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 +71,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

package/resources/powershell/PoshQC/PoshQC.ScanConfig.psm1

@@ -93,7 +93,9 @@ function Get-PoshQCScanConfigFolder {
         if ([string]::IsNullOrWhiteSpace($folderText)) {
             throw "Scan configuration '$ConfigRelativePath' contains a blank 'test.scanFolders' entry."
         }
-        if ([IO.Path]::IsPathRooted($folderText)) {
+        # Host-independent rule: a drive-qualified entry or one beginning with '/' or '\' is
+        # rejected on every host; the .NET rooted-path test accepts 'C:/x' on Linux and rejects it on Windows.
+        if ($folderText -match '^(?:[A-Za-z]:|[\\/])') {
             throw "Scan configuration '$ConfigRelativePath' entry '$folderText' must be a workspace-relative path, not an absolute path."
         }
         # Reject parent-directory traversal in any path segment.

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

@@ -185,8 +185,9 @@ function Invoke-PoshQCTest {
             # 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 globally so Pester's Describe/It/Mock resolve in test containers. Under the default
+            # $InvokePester trampoline, test code runs in this module's session state, not the global
+            # session state (issue #392; see the $InvokePester comment for the Mock consequence).
             # 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
         },
@@ -286,14 +287,15 @@ function Invoke-PoshQCTest {
         },
         [scriptblock] $InvokePester = {
             param($Config)
-            # Host the Pester run in the global session state so discovered test containers do
-            # not execute inside this module's session state. This makes the bundled entry path
-            # (module pre-imported, then Invoke-PoshQCTest -> Invoke-Pester) match the passing
-            # direct run, and lets BeforeAll module guards in test files safely remove/re-import
-            # same-named modules mid-run without orphaning the run's hosting session state
-            # (issue #392). [scriptblock]::Create builds an unbound scriptblock so the installed
-            # global function is not bound to this module's session state; the try/finally pair
-            # removes the temporary global function so no state leaks between suite invocations.
+            # Run Invoke-Pester through a temporary global function built with [scriptblock]::Create,
+            # so the function itself is not bound to this module's session state (issue #392). The
+            # discovered test code nevertheless runs in this module's session state: a test reports
+            # $ExecutionContext.SessionState.Module as PoshQC here, and $null under a plain
+            # Invoke-Pester run. Consequence: after a test re-imports PoshQC, Mock -ModuleName PoshQC
+            # from test code does not reach the re-imported instance; such a test runs its body in
+            # InModuleScope PoshQC and mocks without -ModuleName (observed in issue #1067). The
+            # try/finally pair removes the temporary global function so no state leaks between suite
+            # invocations.
             $trampoline = [scriptblock]::Create('param($c) Invoke-Pester -Configuration $c')
             $null = New-Item -Path 'function:global:Invoke-PoshQCPesterRun' -Value $trampoline -Force
             try {