@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/claude-customizations/.claude/hooks/enforce-completion-consistency.ps1

@@ -30,27 +30,29 @@
     hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
     Edit tool calls supply only old_string/new_string (a partial patch). An Edit
-    call is validated by reading the checkpoint at the Edit's
-    targeted file_path through the injectable CheckpointReader seam and
-    applying the old_string -> new_string replacement in memory; the resulting
-    content is then evaluated like a Write. When the patch cannot be resolved
-    (the targeted file is missing or empty, the Edit has no old_string, or the
-    old_string is absent from the targeted content), the call is allowed. For
-    Write calls whose content is not valid JSON, the hook allows the operation
-    and defers to downstream tools to surface the error.
+    call is validated by reading the checkpoint at the Edit's targeted file_path
+    through the injectable CheckpointReader seam and applying the old_string ->
+    new_string replacement in memory; the resulting content is then evaluated
+    like a Write. One occurrence of old_string is replaced unless replace_all is
+    true. The hook fails closed: a missing, empty, or unreadable targeted
+    checkpoint, an absent or empty old_string, zero or ambiguous occurrences of
+    old_string, and a Write with empty content all deny, and the deny reason
+    names the cause. Write content (or patched content) that is not valid JSON
+    is still allowed, and the hook defers to downstream tools to surface the
+    error.
 
 .NOTES
     Compatible with PowerShell 7+. Read-only validation gate.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 # Dot-source the shared validation helpers. Guarded so a missing file produces a
 # clear error and so dot-sourcing this hook in tests loads the helpers too.
-$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
-. $script:CompletionHelpersPath
+try { . (Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-completion-helpers.ps1' -ErrorRecord $_ }
 
 function ConvertFrom-CheckpointJson {
     <#
@@ -72,9 +74,10 @@ function Get-CheckpointFileContent {
         Reads the on-disk checkpoint content for the read-then-validate Edit path.
     .DESCRIPTION
         Returns the full file text when the path resolves to a file on disk, or
-        $null when the file does not exist. Tests inject a CheckpointReader
-        scriptblock instead of mocking this function so no temporary files are
-        required.
+        $null when the file does not exist. An existing empty file yields an
+        empty string, never $null, so a missing checkpoint and an empty
+        checkpoint stay distinct. Tests inject a CheckpointReader scriptblock
+        instead of mocking this function so no temporary files are required.
     #>
     [CmdletBinding()]
     [OutputType([string])]
@@ -86,7 +89,9 @@ function Get-CheckpointFileContent {
     if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    $text = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    if ($null -eq $text) { return '' }
+    return [string]$text
 }
 
 function Test-IsCheckpointPath {
@@ -266,20 +271,24 @@ function Get-MissingCompletionEvidence {
 function Resolve-EditedCheckpointContent {
     <#
     .SYNOPSIS
-        Returns the patched checkpoint content for an Edit-tool call, or $null
-        when the patch cannot be applied against the on-disk checkpoint.
+        Returns an object with Content and Failure for an Edit-tool call: the
+        patched checkpoint content on success, or a failure cause when the patch
+        cannot be applied against the targeted checkpoint.
     .DESCRIPTION
-        Implements the read-then-validate Edit path. When the tool input carries
-        an old_string (an Edit patch), the checkpoint at the caller-supplied
-        CheckpointPath (the Edit's targeted file_path) is read through the
-        injectable CheckpointReader seam and the old_string -> new_string
-        replacement is applied in memory (no on-disk mutation). Returns $null
-        when there is no old_string, the targeted file does not exist or is empty, or the
-        old_string is not present in the on-disk content, signalling the caller
-        to allow (defer).
+        Implements the read-then-validate Edit path. The checkpoint at the
+        caller-supplied CheckpointPath (the Edit's targeted file_path, passed to
+        the reader unchanged) is read through the injectable CheckpointReader seam
+        and the old_string -> new_string replacement is applied in memory (no
+        on-disk mutation). One occurrence of old_string is replaced unless
+        replace_all is true. Failure is one of no-old_string (absent or empty
+        old_string), checkpoint-unreadable (the reader threw), checkpoint-missing
+        (the reader returned $null), checkpoint-empty (the reader returned an
+        empty string), old_string-not-found, or old_string-ambiguous. Content is
+        $null on failure and Failure is $null on success. The caller denies on
+        any Failure.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([pscustomobject])]
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
@@ -297,7 +306,7 @@ function Resolve-EditedCheckpointContent {
         $oldString = [string]$ToolInput.old_string
     }
     if ([string]::IsNullOrEmpty($oldString)) {
-        return $null
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
     }
 
     $newString = ''
@@ -305,20 +314,46 @@ function Resolve-EditedCheckpointContent {
         $newString = [string]$ToolInput.new_string
     }
 
-    $onDisk = & $CheckpointReader $CheckpointPath
-    if ([string]::IsNullOrEmpty([string]$onDisk)) {
-        # The on-disk checkpoint does not exist (or is empty); cannot patch.
-        return $null
+    try {
+        $onDisk = & $CheckpointReader $CheckpointPath
+    }
+    catch {
+        # A reader exception must not escape the gate; report it as a failure cause.
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-unreadable' }
+    }
+    if ($null -eq $onDisk) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-missing' }
     }
 
     $onDiskText = [string]$onDisk
-    if (-not $onDiskText.Contains($oldString)) {
-        # The old_string is not present, so the patch does not apply here.
-        return $null
+    if ($onDiskText.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-empty' }
     }
 
-    # Apply the patch in memory using a literal (non-regex) replacement.
-    return $onDiskText.Replace($oldString, $newString)
+    # Apply the patch in memory; one occurrence unless replace_all is true.
+    $replaceAll = Get-EditReplaceAllFlag -ToolInput $ToolInput
+    return Invoke-SingleOccurrenceEdit -Text $onDiskText -OldString $oldString -NewString $newString -ReplaceAll $replaceAll
+}
+
+function ConvertTo-CompletionDenyDecision {
+    <#
+    .SYNOPSIS
+        Builds the PreToolUse deny decision for the given reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
 }
 
 function Invoke-CompletionConsistencyDecision {
@@ -341,6 +376,8 @@ function Invoke-CompletionConsistencyDecision {
         [Parameter(Mandatory = $false)]
         [scriptblock] $RoutingMatrixReader
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
@@ -366,18 +403,25 @@ function Invoke-CompletionConsistencyDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload directly. Edit tool: no content is
-    # supplied, so read the on-disk checkpoint through the injectable seam and
-    # apply the old_string -> new_string patch in memory (read-then-validate).
-    $content = Get-ClaudeHookToolInputString -ToolInput $toolInput -Name 'content'
-    if (-not $content) {
-        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader -CheckpointPath $filePath
+    # Write tool: a present content property is validated directly, and empty
+    # content is denied. Edit tool: no content property is supplied, so read the
+    # targeted checkpoint through the injectable seam and apply the old_string ->
+    # new_string patch in memory (read-then-validate). Any failure cause denies.
+    $cause = $null
+    if ($toolInput.PSObject.Properties.Name -contains 'content') {
+        $content = Get-ClaudeHookToolInputString -ToolInput $toolInput -Name 'content'
         if (-not $content) {
-            # No content, and the Edit could not be resolved against on-disk
-            # state (missing file or non-matching patch): defer and allow.
-            return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+            $cause = 'write-content-empty'
         }
     }
+    else {
+        $edit = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader -CheckpointPath $filePath
+        $content = $edit.Content
+        $cause = $edit.Failure
+    }
+    if ($cause) {
+        return ConvertTo-CompletionDenyDecision -Reason "COMPLETION_CONSISTENCY_BLOCKED: the canonical checkpoint cannot be deleted, emptied, or replaced through an unresolved patch ($cause)."
+    }
 
     try {
         $payload = ConvertFrom-CheckpointJson -Json $content
@@ -411,12 +455,33 @@ function Invoke-CompletionConsistencyDecision {
     }
 }
 
+function Invoke-CompletionConsistencyEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads the payload and returns the gate decision, failing closed when the read or evaluation throws
+        (issue #903, #736 O-4).
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param([scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload })
+
+    try {
+        return Invoke-CompletionConsistencyDecision -ToolInputRaw ([string](& $ReadPayload))
+    }
+    catch {
+        return ConvertTo-CompletionDenyDecision -Reason "COMPLETION_CONSISTENCY_BLOCKED: the gate could not evaluate the payload ($($_.Exception.Message)) and fails closed."
+    }
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('COMPLETION_CONSISTENCY_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
-$decision = Invoke-CompletionConsistencyDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
+$decision = Invoke-CompletionConsistencyEntryPoint
 
 $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 

package/resources/claude-customizations/.claude/hooks/enforce-completion-helpers.ps1

@@ -11,6 +11,12 @@
       - Test-IsValidFeatureFolder: rejects sentinel/placeholder feature folders
         and folders not anchored under docs/features/active/<segment>; optionally
         verifies on-disk existence through an injectable scriptblock seam.
+      - Get-EditReplaceAllFlag: returns the boolean value of the replace_all
+        property of an Edit tool input; the string 'true' is honoured and the
+        string 'false' is not.
+      - Invoke-SingleOccurrenceEdit: pure single-occurrence patch of a text;
+        reports a failure cause instead of replacing when old_string is empty,
+        absent, or ambiguous.
 
     This script is dot-sourced by enforce-completion-consistency.ps1. It contains
     no entrypoint logic, so dot-sourcing it in tests has no side effects.
@@ -161,3 +167,102 @@ function Test-RouteRequiresPrGate {
     }
     return ([bool]$route.requires_pr_gate -eq $true)
 }
+
+function Get-EditReplaceAllFlag {
+    <#
+    .SYNOPSIS
+        Returns the boolean value of the replace_all property of an Edit tool input.
+    .DESCRIPTION
+        Returns $false when the tool input is null or has no replace_all property.
+        Returns the value when it is already a boolean. Returns $true for a string
+        whose trimmed, case-insensitive value is 'true'. Returns $false for every
+        other value. No [bool] cast is used because [bool]'false' is $true in
+        PowerShell.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput
+    )
+
+    if ($null -eq $ToolInput -or -not ($ToolInput.PSObject.Properties.Name -contains 'replace_all')) {
+        return $false
+    }
+
+    $value = $ToolInput.replace_all
+    if ($value -is [bool]) {
+        return $value
+    }
+    if ($value -is [string]) {
+        return $value.Trim() -ieq 'true'
+    }
+    return $false
+}
+
+function Invoke-SingleOccurrenceEdit {
+    <#
+    .SYNOPSIS
+        Applies an old_string to new_string patch to a text in memory and reports
+        a failure cause when the patch cannot be applied unambiguously.
+    .DESCRIPTION
+        Pure function with no I/O. Normalizes CRLF to LF in all three strings. An
+        empty OldString yields Failure 'no-old_string'. Zero ordinal occurrences
+        yield Failure 'old_string-not-found'. When ReplaceAll is true every
+        occurrence is replaced by ordinal String.Replace. Otherwise a second
+        ordinal search that starts after the end of the first match yields Failure
+        'old_string-ambiguous' when it finds a match (overlapping candidates are
+        counted once), and no match yields a single splice by Substring. No regular
+        expression is used, so a '$' in NewString stays literal. Returns an object
+        with Content and Failure; Content is $null on failure and Failure is $null
+        on success.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $OldString,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $NewString,
+
+        [Parameter(Mandatory = $false)]
+        [bool] $ReplaceAll = $false
+    )
+
+    $normalizedText = $Text.Replace("`r`n", "`n")
+    $normalizedOld = $OldString.Replace("`r`n", "`n")
+    $normalizedNew = $NewString.Replace("`r`n", "`n")
+
+    if ($normalizedOld.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
+    }
+
+    $comparison = [System.StringComparison]::Ordinal
+    $firstIndex = $normalizedText.IndexOf($normalizedOld, $comparison)
+    if ($firstIndex -lt 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-not-found' }
+    }
+
+    if ($ReplaceAll) {
+        return [pscustomobject]@{ Content = $normalizedText.Replace($normalizedOld, $normalizedNew); Failure = $null }
+    }
+
+    $afterFirst = $firstIndex + $normalizedOld.Length
+    if ($normalizedText.IndexOf($normalizedOld, $afterFirst, $comparison) -ge 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-ambiguous' }
+    }
+
+    $spliced = $normalizedText.Substring(0, $firstIndex) + $normalizedNew + $normalizedText.Substring($afterFirst)
+    return [pscustomobject]@{ Content = $spliced; Failure = $null }
+}

package/resources/claude-customizations/.claude/hooks/enforce-discovery-artifact-gate.ps1

@@ -32,9 +32,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryValidation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryValidation.psm1' -ErrorRecord $_ }
 function Invoke-DiscoveryValidatorExe {
     <#
     .SYNOPSIS
@@ -164,6 +166,8 @@ function Invoke-DiscoveryArtifactGateDecision {
         [Parameter(Mandatory = $false)]
         [scriptblock] $RequiredArtifactReader = { Get-RequiredDiscoveryArtifactDeclaration }
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
@@ -224,6 +228,9 @@ function Invoke-DiscoveryArtifactGateDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('DISCOVERY_ARTIFACT_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $decision = Invoke-DiscoveryArtifactGateDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
 

package/resources/claude-customizations/.claude/hooks/enforce-epic-invocation-origin.ps1

@@ -42,9 +42,10 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 $script:GatedSubagentTypes = @('epic-planner', 'epic-orchestrator', 'parallel-planner', 'parallel-orchestrator')
 $script:ParallelSubagentTypes = @('parallel-planner', 'parallel-orchestrator')
 $script:ProhibitedCallerAgentType = 'orchestrator'
@@ -214,6 +215,8 @@ function Invoke-EpicInvocationOriginDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_INVOCATION_ORIGIN_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     # The envelope carries both halves: the caller's agent_type at the root and the
     # delegation target's subagent_type inside tool_input.
@@ -272,6 +275,9 @@ function Invoke-EpicInvocationOriginDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_INVOCATION_ORIGIN_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_INVOCATION_ORIGIN_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $decision = Invoke-EpicInvocationOriginDecision -HookInputRaw (Read-ClaudeHookRawPayload)
 

package/resources/claude-customizations/.claude/hooks/enforce-epic-merge-gate-command.ps1

@@ -0,0 +1,190 @@
+<#
+.SYNOPSIS
+    Scope predicate and pull-request selector reader for the epic merge gate (issue #952).
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1 on both runtimes; this file is byte-identical in
+    .claude/hooks and .codex/hooks. Under a merge queue every gh pr merge spelling (--merge, -m,
+    --squash, -s, --rebase, -r, --auto, --admin, or no method flag) adds the pull request to the
+    queue, and the gh api mutations enqueuePullRequest, enablePullRequestAutoMerge, and
+    mergePullRequest and the REST pulls/<n>/merge endpoint also reach the base branch. All of
+    them are in scope. A gh pr merge whose only action flag is --disable-auto is out of scope.
+
+    Pure string logic only: no disk, process, network, clock, or environment access. The file
+    dot-sources and imports nothing; it consumes Get-CommandLineInvocation and
+    Get-CommandLineStructuralMatch, which the gate loads from hook-command-invocation.ps1 first.
+
+    Known limitation (issue #952 code review CR-5): the gh api scope reads the command text
+    only. A GraphQL mutation supplied from a file (gh api graphql -F query=@mutation.graphql,
+    or gh api --input payload.json) is not visible to this text-based scope and is not gated.
+#>
+
+# gh pr merge flags that perform or schedule a merge. Any of them keeps a command in scope even
+# when it also carries --disable-auto.
+$script:EpicMergeGateActionFlags = @('--merge', '-m', '--squash', '-s', '--rebase', '-r', '--auto', '--admin')
+
+# gh pr merge flags, including the inherited --repo, that consume the following token as a value.
+$script:EpicMergeGateValueFlags = @('-b', '--body', '-F', '--body-file', '-t', '--subject', '-A', '--author-email', '--match-head-commit', '-R', '--repo')
+
+# GraphQL mutations that merge, enqueue, or schedule the merge of a pull request.
+$script:EpicMergeGateMutationNames = @('enqueuePullRequest', 'enablePullRequestAutoMerge', 'mergePullRequest')
+
+# The REST merge endpoint path; group 1 is the pull-request number.
+$script:EpicMergeGateRestMergePattern = '(?:^|/)pulls/(\d+)/merge(?:$|[^\w-])'
+
+function Get-EpicMergeGateFlagName {
+    <#
+    .SYNOPSIS
+        Return the flag name of a dash-led token without any '=value' suffix.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Token)
+
+    $split = $Token.IndexOf('=')
+    if ($split -gt 0) { return $Token.Substring(0, $split) }
+    return $Token
+}
+
+function ConvertFrom-EpicMergeGateSelector {
+    <#
+    .SYNOPSIS
+        Convert a gh pr merge selector to a pull-request number, or $null.
+    .DESCRIPTION
+        Accepts an all-digit selector or a URL whose path ends in /pull/<n>. A branch-name
+        selector carries no number and yields $null.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Selector)
+
+    $digits = $null
+    if ($Selector -match '^\d+$') {
+        $digits = $Selector
+    } elseif ($Selector -match '/pull/(\d+)/?(?:[?#].*)?$') {
+        $digits = $Matches[1]
+    }
+    $number = 0
+    if ($null -ne $digits -and [int]::TryParse($digits, [ref] $number)) { return $number }
+    return $null
+}
+
+function Test-EpicMergeGateDisableAutoOnly {
+    <#
+    .SYNOPSIS
+        Report whether a Structural gh pr merge match carries --disable-auto and no action flag.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][pscustomobject] $Match)
+
+    $tokens = [string[]]@($Match.Segment.Tokens)
+    $hasDisableAuto = $false
+    for ($index = $Match.OperandIndex; $index -lt $tokens.Count; $index++) {
+        $name = Get-EpicMergeGateFlagName -Token $tokens[$index]
+        if ($script:EpicMergeGateActionFlags -ccontains $name) { return $false }
+        if ($name -ceq '--disable-auto') { $hasDisableAuto = $true }
+    }
+    return $hasDisableAuto
+}
+
+function Test-EpicMergeGateApiMutationText {
+    <#
+    .SYNOPSIS
+        Report whether gh api text names a merge or enqueue mutation or the REST merge endpoint.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $Text)
+
+    if ([string]::IsNullOrEmpty($Text)) { return $false }
+    foreach ($name in $script:EpicMergeGateMutationNames) {
+        if ($Text.IndexOf($name, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) { return $true }
+    }
+    return [regex]::IsMatch($Text, $script:EpicMergeGateRestMergePattern)
+}
+
+function Test-EpicMergeGateCommandInScope {
+    <#
+    .SYNOPSIS
+        Report whether a command line is a gated merge or enqueue action (issue #952).
+    .DESCRIPTION
+        True for any gh pr merge match, Structural or Indeterminate, unless the match is Structural
+        and its only action flag is --disable-auto; true for any gh api match whose tokens name a
+        merge or enqueue mutation or a pulls/<n>/merge path. Text that only mentions these words
+        produces no match and stays out of scope. An Indeterminate gh pr merge match stays in scope
+        (fail closed).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
+        if ($match.Status -ne 'Structural' -or -not (Test-EpicMergeGateDisableAutoOnly -Match $match)) { return $true }
+    }
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        if (Test-EpicMergeGateApiMutationText -Text (@($match.Segment.Tokens) -join ' ')) { return $true }
+    }
+    return $false
+}
+
+function Get-EpicMergeGateSelectorPrNumber {
+    <#
+    .SYNOPSIS
+        Resolve the pull-request number of a gated merge or enqueue command, or $null.
+    .DESCRIPTION
+        For gh pr merge, only the first Structural match is read. Value flags are skipped with
+        their values, other flags are skipped, an equals-joined --merge=<digits> yields its
+        digits (an equals-joined value that is not a number is skipped like any other flag),
+        and the first non-flag token (or the token after a bare '--') is the selector.
+        For gh api, the number comes from a pulls/<n>/merge token. Any other command yields
+        $null, which the gate handles through its no-number branches.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    $match = Get-CommandLineStructuralMatch -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
+    if ($null -ne $match) {
+        $tokens = [string[]]@($match.Segment.Tokens)
+        $index = $match.OperandIndex
+        while ($index -lt $tokens.Count) {
+            $token = $tokens[$index]
+            if ($token -ceq '--') {
+                if ($index + 1 -lt $tokens.Count) { return ConvertFrom-EpicMergeGateSelector -Selector $tokens[$index + 1] }
+                return $null
+            }
+            if ($token.StartsWith('-') -and $token.Length -gt 1) {
+                $name = Get-EpicMergeGateFlagName -Token $token
+                if ($name -ceq '--merge' -and $token.Length -gt $name.Length) {
+                    $equalsNumber = ConvertFrom-EpicMergeGateSelector -Selector $token.Substring($name.Length + 1)
+                    if ($null -ne $equalsNumber) { return $equalsNumber }
+                }
+                $index += if ($script:EpicMergeGateValueFlags -ccontains $token) { 2 } else { 1 }
+                continue
+            }
+            return ConvertFrom-EpicMergeGateSelector -Selector $token
+        }
+        return $null
+    }
+
+    foreach ($apiMatch in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        foreach ($token in @($apiMatch.Segment.Tokens)) {
+            $rest = [regex]::Match([string]$token, $script:EpicMergeGateRestMergePattern)
+            $number = 0
+            if ($rest.Success -and [int]::TryParse($rest.Groups[1].Value, [ref] $number)) { return $number }
+        }
+    }
+    return $null
+}