@danmoisan/drm-copilot-mcp 1.1.9 → 1.1.11

package/resources/codex-and-agents-customizations/.agents/skills/orchestrate/SKILL.md

@@ -39,6 +39,47 @@ On every invocation, the main session must:
    selected route's required agents, skills, and MCP tools into checkpoint
    state.
 
+## Prepared-State Portable Handoff Intake
+
+Treat a portable prepared-state checkpoint as a resume request, not as a new
+orchestration intake. Before delegation:
+
+1. Validate the portable envelope through the published, workspace-explicit
+   orchestration authority. Require the repository, workspace, branch lineage,
+   issue, feature folder, work mode, scheduler context, capabilities, and exact
+   next transition to match the current checkout. Supply the complete
+   caller-controlled independent expected context on every call to
+   `resolve_orchestration_topology`, `resolve_provider_routing`, and
+   `transition_prepared_orchestration`: `expected_repository_id`,
+   `expected_workspace_root`, `expected_branch`, `expected_source_head_sha`,
+   `allowed_head_relationship`, `expected_issue_number`,
+   `expected_feature_folder`, `expected_work_mode`, `expected_plan_path`, and
+   `expected_plan_sha256`. Derive each value from the destination checkout and
+   the caller's own record. A call that omits a value, or that copies one from
+   the envelope under validation, is rejected before any service invocation.
+2. Prove the plan from the independently expected repository-relative path and
+   raw-byte SHA-256 the caller supplied in `expected_plan_path` and
+   `expected_plan_sha256`. Do not search for another plan, rewrite the path,
+   follow a symlink outside the repository, substitute a newer plan, or read
+   the plan identity from the envelope.
+3. Use `transition_prepared_orchestration` as the only authority permitted to
+   materialize the provider-native destination checkpoint. A dry run may
+   validate and project the destination state but must not archive or replace
+   checkpoint bytes.
+4. Preserve the ordered completed phases and reject any request to replay one
+   of them. Do not rerun promotion, research, feature-document authoring,
+   atomic planning, or preflight when the envelope records them as complete.
+5. Preserve source-provider model, profile, topology, launch, and receipt data
+   as opaque historical evidence. Resolve Codex topology, model routing, and
+   launch evidence only for the first new destination delegation after
+   materialization; never synthesize Codex receipts for source-provider work.
+
+For an ordinary handoff whose recorded next transition is `atomic_execution`,
+resume the exact approved plan through the ordinary Codex atomic-executor path
+at `atomic_execution`. Do not invoke a parent scheduler or rediscover lifecycle
+work. Any contract, authority, plan, replay, or materialization failure returns
+the deterministic blocked result before destination delegation.
+
 ## Epic Entry Boundary
 
 This standalone workflow must not invoke `epic-planner` or `epic-orchestrator`. If intake names

package/resources/codex-and-agents-customizations/.agents/skills/orchestrator-state/SKILL.md

@@ -17,6 +17,47 @@ A hardened snapshot from another repository contains a JSON Schema for the orche
 
 This prohibition is specific to the disqualified foreign schema identified by the `drmoisan.github.io/mix-calculator/` `$id`. A schema whose `$id` is repo-local and whose required-field set and `additionalProperties` policy match this repository's checkpoint contract is not the disqualified foreign artifact; even so, the repository's enforcement mechanism remains the Python validator prose-and-logic above, not an imported schema file.
 
+## Portable Handoff Projection Invariants
+
+A provider-native destination checkpoint materialized from the portable handoff
+contract must retain the following linkage:
+
+- `provider`, `checkpoint_expression`, and `destination_projector` identify the
+  destination expression and selected adapter.
+- `plan-path` and `next_step` equal the portable envelope's exact plan path and
+  recorded lifecycle transition. The destination must not rediscover a plan or
+  replace either value from local convention.
+- `portable_handoff` retains the handoff ID, envelope SHA-256, latest history
+  entry SHA-256, adapter identity, source validator, identity and binding
+  fields, source checkpoint/archive facts, exact plan proof, lifecycle,
+  capabilities, and scheduler context.
+- Historical source receipts remain opaque references under
+  `portable_handoff.source.expression.historical_receipts`. They must not be
+  rewritten as destination-provider receipts.
+- `destination_evidence` starts as `pending_first_delegation` with an empty
+  receipt list. Destination routing, topology, model, and receipts may be
+  recorded only for the first new delegation after checkpoint materialization.
+
+The portable lifecycle permits only the registered state transitions:
+`legacy_v1` to migration, `preparation_complete` to
+`prepared_to_atomic_execution`, `validated` to destination materialization,
+`materialized` to `atomic_execution`, and a bounded scheduled-child return from
+an authorized child execution phase. An attempted replay of a completed phase
+is invalid.
+
+A failed contract, binding, capability, authority, plan, replay, dirty-worktree,
+candidate, archive, or replacement check must produce the deterministic blocked
+result and leave the source checkpoint authoritative. A blocked result must
+retain the primary `HANDOFF_*` code and affected paths where applicable; it must
+not record a completed transition or destination delegation.
+
+For parallel and epic children, `return_to_scheduler` accepts only a result
+whose run, item, parent checkpoint path/hash, scheduler owner, child execution
+owner, return contract, plan hash, child checkpoint hash, and result hash match
+the envelope. The child may return that bounded result but may not assume
+cohort or wave ordering, barriers, fan-in, integration, cleanup, or parent
+completion authority.
+
 ## Scope and Backward Compatibility
 
 These invariants apply only when the checkpoint contains a top-level `remediation_loop` with a `cycles` array. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive.

package/resources/codex-and-agents-customizations/.agents/skills/repo-automation-adapter/SKILL.md

@@ -50,6 +50,32 @@ Use these semantic MCP tools when the corresponding operation is required:
 - `run_poshqc_analyze`
 - `run_poshqc_analyze_autofix`
 - `run_poshqc_test`
+- `resolve_orchestration_topology`
+- `resolve_provider_routing`
+- `transition_prepared_orchestration`
+
+## Independent Expected Context for Portable Handoff Tools
+
+The three portable prepared-orchestration tools bind a handoff to one specific
+destination checkout. Every call to `resolve_orchestration_topology`,
+`resolve_provider_routing`, and `transition_prepared_orchestration` must carry
+the complete caller-controlled independent expected context:
+
+- `expected_repository_id`
+- `expected_workspace_root`
+- `expected_branch`
+- `expected_source_head_sha`
+- `allowed_head_relationship`
+- `expected_issue_number`
+- `expected_feature_folder`
+- `expected_work_mode`
+- `expected_plan_path`
+- `expected_plan_sha256`
+
+Derive each value from the destination checkout and the caller's own record.
+The envelope under validation is never the source of the values it is
+validated against. A call that omits a value, or that copies one from the
+envelope, is rejected before the service is invoked.
 
 Legacy VS Code command IDs are historical source material only and must not be invoked:
 

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -2,7 +2,7 @@ default_permissions = ":danger-full-access"
 
 [mcp_servers.drm-copilot]
 command = "npx"
-args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.9"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.11"]
 required = true
 enabled_tools = [
     "collect_commit_context",

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-merge-gate.ps1

@@ -5,6 +5,12 @@
 [CmdletBinding()]
 param()
 
+# Shared command-line parser (issue #545). The scope filter and the PR-number resolver below
+# both run against the segment that structurally invokes `gh pr merge`, which is what keeps
+# the two runtimes on one implementation of the same concern.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+
 function ConvertFrom-CodexMergeJson {
     [CmdletBinding()]
     param([AllowNull()][AllowEmptyString()][string] $Raw, [Parameter(Mandatory)][string] $Name, [switch] $Optional)
@@ -26,13 +32,37 @@ function ConvertFrom-CodexMergeJson {
 }
 
 function Get-CodexMergeCommandPrNumber {
+    <#
+    .SYNOPSIS
+        Resolve the explicit pull-request number of a gh pr merge invocation, or $null.
+    .DESCRIPTION
+        The number is taken from the segment that structurally invokes `gh pr merge` and
+        from nowhere else: the positional spelling through Get-CommandLineOperand, the
+        flag-led and equals-joined spellings through Get-CommandLineFlagValue. A leading
+        `cd <path>` segment contributes no operand and no flag value, so no digit run
+        outside the merge segment can be mistaken for a pull-request number.
+
+        This copy has never carried the Claude copy's unanchored whole-text digit scan and
+        deliberately does not acquire one. No regular expression matching a bare digit run
+        is introduced here; the only pattern below anchors an all-digit token end to end.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
     [CmdletBinding()]
     [OutputType([int])]
     param([Parameter(Mandatory)][string] $Command)
 
-    if ($Command -match '(?i)\bgh\s+pr\s+merge\s+(\d+)\b') {
-        return [int]$Matches[1]
+    foreach ($operand in @(Get-CommandLineOperand -CommandText $Command -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
+        if ($operand -match '^\d+$') {
+            return [int]$operand
+        }
+    }
+
+    $flagValue = Get-CommandLineFlagValue -CommandText $Command -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
+    if ($null -ne $flagValue -and $flagValue -match '^\d+$') {
+        return [int]$flagValue
     }
+
     return $null
 }
 
@@ -95,7 +125,23 @@ function Invoke-CodexEpicMergeDecision {
         return $null
     }
     $command = [string]$payload.tool_input.command
-    if ($command -notmatch '(?i)\bgh\s+pr\s+merge\b' -or $command -notmatch '(?i)--merge\b') {
+    # Both legs are read structurally from the segment that invokes the command, so a
+    # quoted mention of the phrase no longer brings a command into scope. The flag leg needs
+    # a raw-scan fallback: a wrapper's quoted argument collapses into ONE token, so a flag
+    # inside it is never read as a token, and the token-only read took
+    # bash -c "gh pr merge --merge 688" out of scope.
+    $isMergeInvocation = Test-CommandLineInvocation -CommandText $command -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
+    $hasMergeFlag = Test-CommandLineFlag -CommandText $command -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
+    if (-not $hasMergeFlag) {
+        foreach ($segment in @(Read-CommandLineSegment -CommandText $command)) {
+            if ((Test-CommandLineSegmentRawScan -Segment $segment) -and
+                $segment.ScanText.IndexOf('--merge', [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
+                $hasMergeFlag = $true
+                break
+            }
+        }
+    }
+    if (-not $isMergeInvocation -or -not $hasMergeFlag) {
         return $null
     }
 

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-planning-only.ps1

@@ -16,8 +16,13 @@ $script:AllowedPreparationMcpTools = @(
     'mcp__drm-copilot__potential_to_issue',
     'mcp__drm-copilot__new_active_feature_folder',
     'mcp__drm-copilot__resolve_atomic_plan_prompt',
-    'mcp__drm-copilot__resolve_execute_hard_lock_prompt',
-    'mcp__drm-copilot__validate_orchestration_artifacts'
+    'mcp__drm-copilot__resolve_execute_hard_lock_prompt'
+)
+$script:PreparationSemanticMcpIds = @(
+    'drm-copilot.validate_orchestration_artifacts',
+    'drm-copilot.resolve_orchestration_topology',
+    'drm-copilot.resolve_provider_routing',
+    'drm-copilot.transition_prepared_orchestration'
 )
 
 function ConvertFrom-EpicPlanningJson {
@@ -41,6 +46,47 @@ function ConvertFrom-EpicPlanningJson {
     }
 }
 
+function Get-EpicPlanningRegisteredMcpTool {
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][string] $RegistryPath,
+        [Parameter(Mandatory)][string[]] $SemanticIds
+    )
+
+    if (-not (Test-Path -LiteralPath $RegistryPath -PathType Leaf)) {
+        throw "EPIC_PLANNING_ONLY_BLOCKED: semantic MCP registry '$RegistryPath' does not exist."
+    }
+    $registry = ConvertFrom-EpicPlanningJson `
+        -Raw (Get-Content -Raw -LiteralPath $RegistryPath) `
+        -Name 'semantic MCP registry'
+    $registered = [System.Collections.Generic.List[string]]::new()
+    foreach ($semanticId in $SemanticIds) {
+        $property = $registry.semantic_tools.PSObject.Properties[$semanticId]
+        if ($null -eq $property) {
+            throw "EPIC_PLANNING_ONLY_BLOCKED: semantic MCP id '$semanticId' is not registered."
+        }
+        $entry = $property.Value
+        $operation = $semanticId.Substring($semanticId.LastIndexOf('.') + 1)
+        if ([string]$entry.operation -ne $operation) {
+            throw "EPIC_PLANNING_ONLY_BLOCKED: semantic MCP id '$semanticId' has an invalid operation."
+        }
+        foreach ($alias in @($entry.transport_aliases)) {
+            $escapedOperation = [regex]::Escape($operation)
+            if ([string]$alias -notmatch "^mcp__(?:drm-copilot|drm_copilot)__$escapedOperation`$") {
+                throw "EPIC_PLANNING_ONLY_BLOCKED: semantic MCP id '$semanticId' has an invalid transport alias."
+            }
+            $registered.Add([string]$alias)
+        }
+    }
+    return [string[]]($registered | Sort-Object -Unique)
+}
+
+$script:EpicPlanningRepositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+$script:AllowedPreparationSemanticMcpTools = @(Get-EpicPlanningRegisteredMcpTool `
+        -RegistryPath (Join-Path $script:EpicPlanningRepositoryRoot 'config/orchestration-handoff-registry.json') `
+        -SemanticIds $script:PreparationSemanticMcpIds)
+
 function Get-EpicPlanningDenyDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -223,11 +269,9 @@ function Invoke-EpicPlanningOnlyDecision {
         return Get-EpicPlanningDenyDecision -Reason 'the Bash command is outside the preparation read, branch, commit, push, or validator allowlist.'
     }
 
-    if ($toolName -like 'mcp__*' -and $toolName -notlike 'mcp__drm-copilot__*') {
-        return Get-EpicPlanningDenyDecision -Reason "MCP tool '$toolName' is not part of the repository-scoped preparation surface."
-    }
-
-    if ($toolName -like 'mcp__drm-copilot__*') {
+    $allowedRepositoryMcp = $script:AllowedPreparationMcpTools -contains $toolName
+    $allowedSemanticMcp = $script:AllowedPreparationSemanticMcpTools -contains $toolName
+    if ($allowedRepositoryMcp -or $allowedSemanticMcp) {
         if ($attestedPreparation) {
             $workspaceRoot = [string]$payload.tool_input.workspace_root
             if ([string]::IsNullOrWhiteSpace($workspaceRoot) -or
@@ -236,10 +280,11 @@ function Invoke-EpicPlanningOnlyDecision {
                 return Get-EpicPlanningDenyDecision -Reason 'preparation MCP calls require workspace_root equal to the attested session cwd.'
             }
         }
-        if ($script:AllowedPreparationMcpTools -contains $toolName) {
-            return $null
-        }
-        return Get-EpicPlanningDenyDecision -Reason "MCP tool '$toolName' is outside the preparation lifecycle and validator allowlist."
+        return $null
+    }
+
+    if ($toolName -like 'mcp__*') {
+        return Get-EpicPlanningDenyDecision -Reason "MCP tool '$toolName' is outside the registered preparation lifecycle and semantic allowlist."
     }
 
     return Get-EpicPlanningDenyDecision -Reason "tool '$toolName' is not classified for preparation mode."
@@ -273,7 +318,7 @@ if ($MyInvocation.InvocationName -eq '.') {
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()
-    $repositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+    $repositoryRoot = $script:EpicPlanningRepositoryRoot
     $checkpointPath = Join-Path $repositoryRoot 'artifacts/orchestration/orchestrator-state.json'
     $checkpointRaw = if (Test-Path -LiteralPath $checkpointPath -PathType Leaf) {
         Get-Content -Raw -LiteralPath $checkpointPath

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-worktree-removal-gate.ps1

@@ -5,6 +5,12 @@
 [CmdletBinding()]
 param()
 
+# Shared command-line parser (issue #545). The scope filter and the operand extractor below
+# both run against the segment that structurally invokes `git worktree remove`, which is what
+# keeps the two runtimes on one implementation of the same concern.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+
 $script:SafeWorktreeStatuses = @('merged', 'worktree_removed')
 
 function ConvertFrom-CodexWorktreeJson {
@@ -28,18 +34,35 @@ function ConvertFrom-CodexWorktreeJson {
 }
 
 function Get-CodexWorktreeRemovalPath {
+    <#
+    .SYNOPSIS
+        Extract the target worktree path from a git worktree remove command.
+    .DESCRIPTION
+        The operand comes from the segment that structurally invokes git worktree remove, so
+        a chained 'cd <path> &&' segment contributes nothing and a quoted mention of the
+        phrase resolves to no operand. The tokenizer strips balanced double and single
+        quotes, which is what the previous pattern's `double` and `single` alternatives did.
+
+        The previous pattern accepted '--force' only immediately after 'remove'. That
+        spelling is preserved and the trailing spelling now works too, because '--force' is a
+        zero-argument flag that never contributes an operand wherever it is written. Its
+        presence is read structurally through Test-CommandLineFlag rather than by a raw-text
+        search. The empty-string-on-miss contract is unchanged: callers test `if ($target)`.
+    .OUTPUTS
+        System.String
+    #>
     [CmdletBinding()]
     [OutputType([string])]
     param([Parameter(Mandatory)][AllowEmptyString()][string] $Command)
 
-    $pattern = '(?i)\bgit\s+worktree\s+remove(?:\s+--force)?\s+(?:"(?<double>[^"]+)"|''(?<single>[^'']+)''|(?<bare>\S+))'
-    if ($Command -notmatch $pattern) {
-        return ''
+    $hasForce = Test-CommandLineFlag -CommandText $Command -CommandWord 'git' -SubcommandPath @('worktree', 'remove') -FlagName '--force'
+    $operands = @(Get-CommandLineOperand -CommandText $Command -CommandWord 'git' -SubcommandPath @('worktree', 'remove'))
+
+    if ($operands.Count -gt 0) {
+        return [string]$operands[0]
     }
-    foreach ($name in @('double', 'single', 'bare')) {
-        if ($Matches[$name]) {
-            return [string]$Matches[$name]
-        }
+    if ($hasForce) {
+        return '--force'
     }
     return ''
 }
@@ -97,7 +120,10 @@ function Invoke-CodexWorktreeRemovalDecision {
         return $null
     }
     $command = [string]$payload.tool_input.command
-    if ($command -notmatch '(?i)\bgit\s+worktree\s+remove\b') {
+    # Scope filter. Structural, so a relocating spelling such as
+    # 'git -C <dir> worktree remove <path>' is in scope and quoted prose that merely mentions
+    # the phrase is not (issue #545).
+    if (-not (Test-CommandLineInvocation -CommandText $command -CommandWord 'git' -SubcommandPath @('worktree', 'remove'))) {
         return $null
     }
     $target = Get-CodexWorktreeRemovalPath -Command $command

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -20,6 +20,9 @@ param()
 # normative contract and which lacks headroom; leaving that file byte-untouched is the
 # proof the issue #539 exemption is behaviourally unchanged.
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-modes.ps1')
+# Shared command-line parser (issue #545): per-segment scan text and structural matching.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 
 # The readiness checkpoint this gate reads and names in its block message.
 $script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
@@ -151,9 +154,11 @@ function Test-ImplementationCommand {
         '(^|\s)npx\s+(prettier|eslint|tsc|jest)\b',
         '(^|\s)pwsh\s+.*(Invoke-Pester|tests/scripts/)'
     )
+    $scanText = @(Read-CommandLineSegment -CommandText $normalizedCommand).ScanText
+    $isStaging = @('add', 'commit').Where({ Test-CommandLineInvocation -CommandText $normalizedCommand -CommandWord 'git' -SubcommandPath @($_) }).Count -gt 0
 
     for ($index = 0; $index -lt $implementationCommandPatterns.Count; $index++) {
-        if ($normalizedCommand -notmatch $implementationCommandPatterns[$index]) {
+        if (-not (($scanText | Where-Object { $_ -match $implementationCommandPatterns[$index] }) -or ($index -eq 0 -and $isStaging))) {
             continue
         }
         # Allow-side only (issue #539). Index 0 is the git staging trigger, whose pattern

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-promotion-mcp-only.ps1

@@ -29,6 +29,12 @@
 [CmdletBinding()]
 param()
 
+# Shared command-line parser (issue #545). Every forbidden-token scan and both `gh`
+# expressions below run against each segment's clause-ordered scan text, and the
+# structural matcher reaches the relocating `gh` spellings adjacency cannot.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+
 $script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drm-copilot MCP promotion tools instead.'
 
 $script:PromotionMcpOnlyGhIssueBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct GitHub issue creation via `gh` bypasses the approved drm-copilot MCP promotion path (`mcp__drm-copilot__new_potential_entry` -> `mcp__drm-copilot__potential_to_issue` -> `mcp__drm-copilot__new_active_feature_folder`). Use those MCP tools instead.'
@@ -88,15 +94,34 @@ function Get-PromotionBypassReason {
         'new_active_feature_folder'
     )
 
-    foreach ($token in $forbiddenTokens) {
-        if ($CommandText.IndexOf($token, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
-            return (Get-PromotionMcpOnlyBlockedReason)
+    # Issue #545: the scan text of a segment is its raw text only when the segment is
+    # wrapper-led, carries a live substitution, or could not be balanced; otherwise
+    # quoted spans and attached heredoc bodies are masked. A promotion tool name that
+    # appears only as a JSON receipt value is therefore a mention, not an invocation.
+    $segments = @(Read-CommandLineSegment -CommandText $CommandText)
+
+    foreach ($segment in $segments) {
+        foreach ($token in $forbiddenTokens) {
+            if ($segment.ScanText.IndexOf($token, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
+                return (Get-PromotionMcpOnlyBlockedReason)
+            }
         }
     }
 
     # `gh issue create` and `gh issue new` are direct bypasses of the MCP
     # promotion path. Tolerate any flags after the subcommand.
-    if ($CommandText -match '(?i)\bgh\s+issue\s+(?:create|new)\b') {
+    foreach ($segment in $segments) {
+        if ($segment.ScanText -match '(?i)\bgh\s+issue\s+(?:create|new)\b') {
+            return (Get-PromotionMcpOnlyGhIssueBlockedReason)
+        }
+    }
+
+    # The adjacency-requiring expression above cannot see a relocating spelling, in
+    # which a `gh` global option such as --repo or -R sits between the command word
+    # and its subcommand (D10). The structural matcher absorbs those options and
+    # reads the subcommand path positionally, so both spellings classify.
+    if ((Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('issue', 'create')) -or
+        (Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('issue', 'new'))) {
         return (Get-PromotionMcpOnlyGhIssueBlockedReason)
     }
 
@@ -104,10 +129,12 @@ function Get-PromotionBypassReason {
     # explicit POST method is supplied. `gh api` defaults to GET, so we only
     # block when -X POST or --method POST is present, to avoid false positives
     # on issue read operations. Use a single regex with lookaheads against the
-    # whole command string.
+    # scan text of one segment.
     $ghApiIssuesPostPattern = '(?i)(?=.*\bgh\s+api\b)(?=.*repos/[^/\s]+/[^/\s]+/issues(?:\b|/[^/\s]*$))(?=.*(?:-X\s+POST|--method\s+POST))'
-    if ($CommandText -match $ghApiIssuesPostPattern) {
-        return (Get-PromotionMcpOnlyGhIssueBlockedReason)
+    foreach ($segment in $segments) {
+        if ($segment.ScanText -match $ghApiIssuesPostPattern) {
+            return (Get-PromotionMcpOnlyGhIssueBlockedReason)
+        }
     }
 
     return $null