@danmoisan/drm-copilot-mcp 1.1.15 → 1.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/agents/parallel-orchestrator.md

@@ -18,7 +18,9 @@ tools:
   - "Bash(bash .claude/lib/bash/compute-cohorts.sh*)"
   - "Bash(bash .claude/lib/bash/compute-concurrency-batches.sh*)"
   - "Bash(bash .claude/lib/bash/validate-parallel-manifest.sh*)"
+  - "Bash(bash .claude/lib/bash/abandon-parallel-item.sh*)"
   - "Bash(pwsh -NoProfile -File .claude/lib/project-file-merge/Resolve-MergeableConflict.ps1*)"
+  - "Bash(pwsh -NoProfile -NonInteractive -File .claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1*)"
   - "Bash(dotnet tool restore*)"
   - "Bash(dotnet csharpier check *)"
   - "Bash(dotnet build *)"
@@ -94,12 +96,16 @@ batching use `compute-cohorts.sh` and `compute-concurrency-batches.sh` under the
 entry.
 
 The `poetry run` grants remain for the repository-local paths that still need an interpreter. The
-skill's `## Parallel-Level Checkpoint` section now validates through
-`mcp__drm-copilot__validate_orchestration_artifacts`, so exactly one named consumer is left: the
-drift-detection CLI, invoked as `poetry run python -m`. Each grant stays scoped to its own
-`poetry run python` invocation form — not to `poetry run` as a whole — so `pytest`, `black`,
-`ruff`, and every other `poetry run` subcommand remain outside the allowlist. The sibling persona
-`.claude/agents/parallel-planner.md` records the same destination-runtime posture.
+skill's `## Parallel-Level Checkpoint` section validates through
+`mcp__drm-copilot__validate_orchestration_artifacts`, and since issue #763 radius drift detection runs
+through the destination-runtime PowerShell entry point
+`.claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1` and the abandon disposition through the
+bundled entry point `.claude/lib/bash/abandon-parallel-item.sh`, so no skill step names a
+`poetry run` consumer. The two `poetry run python` grants are left unchanged pending a separate
+removal decision. Each grant stays scoped to its own `poetry run python` invocation form — not to
+`poetry run` as a whole — so `pytest`, `black`, `ruff`, and every other `poetry run` subcommand
+remain outside the allowlist. The sibling persona `.claude/agents/parallel-planner.md` records the
+same destination-runtime posture.
 
 ## Startup Protocol
 

package/resources/claude-customizations/.claude/agents/powershell-typed-engineer.md

@@ -1,7 +1,7 @@
 ---
 name: powershell-typed-engineer
 model: sonnet
-description: Project-scoped worker that implements and verifies PowerShell changes within typed repository boundaries. Applies PoshQC format -> PSScriptAnalyzer -> Pester toolchain, the 1-2 production-file direct-mode budget, the 3-production + 3-test per-batch cap, and zero-regression quality gates.
+description: Project-scoped worker that implements and verifies PowerShell changes within typed repository boundaries. Applies PoshQC format -> PSScriptAnalyzer -> Pester toolchain, the 1-3 production-file direct-mode budget with routing to the orchestrated large path above it, and zero-regression quality gates.
 tools:
   - Read
   - Grep
@@ -36,7 +36,7 @@ Language standards and toolchain are defined in `.claude/rules/powershell.md` an
 Follow the phased workflow defined by the preloaded skills:
 
 1. **Policy compliance** — apply `policy-compliance-order` to load mandatory repo policies before any change.
-2. **Routing and scope** — apply `powershell-change-budget-router` to estimate scope and select direct mode (1-2 production files) vs `powershell-orchestrator` escalation. Enforce the 3 production + 3 test per-batch cap in all modes.
+2. **Routing and scope** — apply `powershell-change-budget-router` to estimate scope and select direct mode (1-3 production files) vs large-path escalation through `/orchestrate`. The large path has no production-file cap.
 3. **Plan and baseline** — apply `atomic-plan-contract` for Phase 0 baseline capture and atomic plan structure. Delegate plan authoring to `atomic_planner` when no plan is supplied. Plans must include the proposed script or module structure, minimal DI seams (wrapper > delegate > adapter), Pester scenario-level test strategy, and the external executable wrapper mock strategy.
 4. **Implement in batches** — apply the approved plan. After each batch, run targeted PSScriptAnalyzer on touched files plus targeted Pester, and confirm per-file coverage.
 5. **Final QA gate** — apply `powershell-qa-gate` to run the full toolchain, enforce zero-regression deltas against the baseline, and produce the required reporting block before declaring completion.
@@ -46,7 +46,7 @@ For long-running orchestrated runs, apply `powershell-orchestration-state-machin
 
 ## Invocation Modes
 
-- **Direct mode** (default, no directive present): strict 1-2 production PowerShell files cap. If the estimated scope exceeds 2 production files, stop and instruct the caller to invoke `powershell-orchestrator` per `powershell-change-budget-router`.
+- **Direct mode** (default, no directive present): strict 1-3 production PowerShell files cap. If the estimated scope exceeds 3 production files, stop and instruct the caller to invoke `/orchestrate` per `powershell-change-budget-router`.
 - **Orchestrator handoff mode** (request contains the exact line `DIRECTIVE: ORCHESTRATOR HANDOFF MODE`): overall production-file cap is lifted, but execution requires a complete context package (`objective`, `promotion-type`, `issue-num`, `feature-folder`, `issue.md`, `spec.md`, `user-story.md` or `NONE`, research artifact paths, constraints). In this mode the agent is routing/planning-only until `atomic_planner` returns `PREFLIGHT: ALL CLEAR` from the `atomic-executor` validation loop; all implementation and QA execution must occur via delegated `atomic-executor` handoffs.
 
 ## Mode Marker Resolution
@@ -64,8 +64,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 
 Stop implementation and return to the user when:
 
-- the scope estimate exceeds the 2-production-file cap in direct mode,
-- an in-flight batch would exceed the 3-production-file or 3-test-file per-batch cap,
+- the scope estimate exceeds the 3-production-file cap in direct mode,
 - a file is near or would exceed the 500-line limit,
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),

package/resources/claude-customizations/.claude/agents/python-typed-engineer.md

@@ -1,7 +1,7 @@
 ---
 name: python-typed-engineer
 model: sonnet
-description: Project-scoped worker that implements and verifies Python changes within typed repository boundaries. Applies the Black -> Ruff -> Pyright -> Pytest toolchain, the 3-production + 3-test per-batch budget, and zero-regression quality gates.
+description: Project-scoped worker that implements and verifies Python changes within typed repository boundaries. Applies the Black -> Ruff -> Pyright -> Pytest toolchain, the 1-3 production-file direct-mode budget with routing to the orchestrated large path above it, and zero-regression quality gates.
 tools:
   - Read
   - Write
@@ -37,7 +37,7 @@ Language standards and toolchain are defined in `.claude/rules/python.md` and `.
 Follow the phased workflow defined by the preloaded skills:
 
 1. **Policy compliance** — apply `policy-compliance-order` to load mandatory repo policies before any change.
-2. **Routing and scope** — apply `python-change-budget-router` to estimate scope, select small vs large path, and enforce the 3 production + 3 test per-batch cap.
+2. **Routing and scope** — apply `python-change-budget-router` to estimate scope and select direct mode (1-3 production files) or, for more than 3 production files, large-path escalation through `/orchestrate`. The large path has no production-file cap, and test files are not counted toward the routing threshold.
 3. **Plan and baseline** — apply `atomic-plan-contract` for Phase 0 baseline capture and atomic plan structure. Delegate plan authoring to `atomic_planner` when no plan is supplied.
 4. **Implement in batches** — apply the approved plan. After each batch, run targeted Ruff and Pyright on touched files plus targeted Pytest, and confirm per-file coverage.
 5. **Final QA gate** — apply `python-qa-gate` to run the full toolchain, enforce zero-regression deltas against the baseline, and produce the required reporting block before declaring completion.
@@ -58,7 +58,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 
 Stop implementation and return to the user when:
 
-- the scope estimate or an in-flight batch would exceed the 3-production-file cap,
+- the scope estimate exceeds 3 production files in direct mode,
 - a file is near or would exceed the 500-line limit,
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),

package/resources/claude-customizations/.claude/hooks/enforce-batch-budget-route.ps1

@@ -0,0 +1,139 @@
+<#
+.SYNOPSIS
+    Pure route helpers shared by the batch-budget hooks.
+
+.DESCRIPTION
+    Defines the functions that read the selected route from orchestrator checkpoint
+    text and decide whether that checkpoint selects the uncapped orchestrated large
+    path. The file is dot-sourced by the PowerShell and Python batch-budget hooks and
+    has no entry point. The Claude and Codex runtime copies of this file are
+    byte-identical, and a parity test holds them identical. None of the functions
+    reads a file or an environment variable; the checkpoint text is supplied by the
+    caller.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+
+function ConvertFrom-BatchBudgetCheckpoint {
+    <#
+    .SYNOPSIS
+        Parses orchestrator checkpoint text into a checkpoint object.
+    .DESCRIPTION
+        Returns the parsed object only when the text is a JSON object. Null or
+        whitespace text, text that is not parseable JSON, and JSON whose root is not
+        an object all return $null. Performs no file or environment access.
+    .PARAMETER CheckpointText
+        Raw text of the orchestrator checkpoint file.
+    #>
+    [CmdletBinding()]
+    [OutputType([psobject])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $CheckpointText
+    )
+
+    if ([string]::IsNullOrWhiteSpace($CheckpointText)) {
+        return $null
+    }
+
+    try {
+        $parsed = ConvertFrom-Json -InputObject $CheckpointText -ErrorAction Stop
+    } catch {
+        Write-Verbose "Ignoring unparseable orchestrator checkpoint text: $($_.Exception.Message)"
+        return $null
+    }
+
+    if ($parsed -is [System.Management.Automation.PSCustomObject]) {
+        return $parsed
+    }
+
+    return $null
+}
+
+function Get-BatchBudgetSelectedRoute {
+    <#
+    .SYNOPSIS
+        Returns the route selected by an orchestrator checkpoint.
+    .DESCRIPTION
+        Uses route_id when the checkpoint has that key, otherwise path_selected. The
+        value is returned only when it is a non-blank string; every other case,
+        including unparseable text, returns an empty string.
+    .PARAMETER CheckpointText
+        Raw text of the orchestrator checkpoint file.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $CheckpointText
+    )
+
+    $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
+    if ($null -eq $checkpoint) {
+        return ''
+    }
+
+    $propertyNames = @($checkpoint.PSObject.Properties.Name)
+    $rawRoute = $null
+    if ($propertyNames -contains 'route_id') {
+        $rawRoute = $checkpoint.route_id
+    } elseif ($propertyNames -contains 'path_selected') {
+        $rawRoute = $checkpoint.path_selected
+    }
+
+    if ($rawRoute -is [string] -and -not [string]::IsNullOrWhiteSpace($rawRoute)) {
+        return $rawRoute
+    }
+
+    return ''
+}
+
+function Test-BatchBudgetLargePathRoute {
+    <#
+    .SYNOPSIS
+        Reports whether an orchestrator checkpoint selects the uncapped large path.
+    .DESCRIPTION
+        Returns $true only when the checkpoint parses to an object, its selected route
+        is large, remediation, or preparation (case-sensitive), next_step is not
+        complete, and completed_steps does not contain S12_complete. No input causes
+        an exception; any failure returns $false.
+    .PARAMETER CheckpointText
+        Raw text of the orchestrator checkpoint file.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $CheckpointText
+    )
+
+    try {
+        $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
+        if ($null -eq $checkpoint) {
+            return $false
+        }
+
+        $route = Get-BatchBudgetSelectedRoute -CheckpointText $CheckpointText
+        if (-not (@('large', 'remediation', 'preparation') -ccontains $route)) {
+            return $false
+        }
+
+        $propertyNames = @($checkpoint.PSObject.Properties.Name)
+        if ($propertyNames -contains 'next_step' -and $checkpoint.next_step -is [string] -and $checkpoint.next_step -ceq 'complete') {
+            return $false
+        }
+
+        if ($propertyNames -contains 'completed_steps' -and (@($checkpoint.completed_steps) -ccontains 'S12_complete')) {
+            return $false
+        }
+
+        return $true
+    } catch {
+        Write-Verbose "Treating the orchestrator checkpoint as direct mode: $($_.Exception.Message)"
+        return $false
+    }
+}

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

@@ -0,0 +1,221 @@
+<#
+.SYNOPSIS
+    Checkpoint read seams and run-target resolution for the epic merge gate (issue #690).
+
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1 immediately after the authorization sibling.
+    Holds:
+
+    - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
+      $script:EpicMergeGateResolutionImportFailure, and
+      Get-EpicMergeGateImportFailureDecision turns it into a deny, so a missing module
+      cannot make the gate exit non-zero and fail open.
+    - The three checkpoint read seams, relocated from the gate file with their names kept.
+      Each takes a mandatory absolute path composed beneath a resolved worktree root.
+    - The session worktree root, used for the child branch and for a bare command.
+    - The resolution seam Resolve-EpicMergeGateRunTarget, which locates the epic or
+      parallel checkpoint that records the command's pull request number.
+    - Test-ChildCheckpointPrGateBinding, which binds the command's pull request number to
+      the per-feature checkpoint's pr_gate.pr_number when that field is recorded.
+    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither run branch
+      resolves.
+
+.NOTES
+    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision from the authorization
+    sibling, dot-sourced by the gate before this file. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+#>
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:EpicMergeGateResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:EpicMergeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
+function Get-EpicMergeGateImportFailureDecision {
+    <#
+    .SYNOPSIS
+        Returns the deny for a failed worktree-resolution import, or $null.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary, or $null when the import succeeded.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    if (-not $script:EpicMergeGateResolutionImportFailure) {
+        return $null
+    }
+    return Get-EpicMergeGateBlockDecision -Reason (
+        "EPIC_MERGE_GATE_BLOCKED: the worktree-resolution module '$($script:EpicMergeGateResolutionImportFailure)' " +
+        'failed to import, so the run checkpoint that governs this merge cannot be located; the gate fails closed.')
+}
+
+function Get-ChildOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the session worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-EpicOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the epic checkpoint. Tests mock this function
+        (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the resolved worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-ParallelOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the resolved worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-EpicMergeGateSessionWorktreeRoot {
+    <#
+    .SYNOPSIS
+        Return the worktree root the session runs in (the child branch and bare-command root).
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return (Resolve-WorktreeOperandTarget -Path '' -SessionRoot (Get-Location).Path).WorktreeRoot
+}
+
+function Resolve-EpicMergeGateRunTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose run checkpoint records a pull request number (issue #690 seam).
+    .PARAMETER Kind
+        epic or parallel.
+    .PARAMETER PrNumber
+        The explicit pull request number the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][ValidateSet('epic', 'parallel')][string] $Kind,
+        [Parameter(Mandatory)][int] $PrNumber
+    )
+
+    return Resolve-WorktreeRunTargetByRecord -Kind $Kind -RecordField pr_number -Value ([string]$PrNumber) -SessionRoot (Get-Location).Path
+}
+
+function Test-ChildCheckpointPrGateBinding {
+    <#
+    .SYNOPSIS
+        True unless the per-feature checkpoint records a pr_gate.pr_number that differs from the command's.
+    .DESCRIPTION
+        A bare command, an absent checkpoint, and a checkpoint without pr_gate.pr_number
+        keep today's unbound child-branch decision. When both numbers are present they must
+        parse as integers and be equal.
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint, or $null.
+    .PARAMETER CommandPrNumber
+        The explicit pull request number the command names, or $null.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()][Nullable[int]] $CommandPrNumber
+    )
+
+    if ($null -eq $CommandPrNumber -or $null -eq $Checkpoint) {
+        return $true
+    }
+    if (@($Checkpoint.PSObject.Properties.Name) -notcontains 'pr_gate' -or $null -eq $Checkpoint.pr_gate) {
+        return $true
+    }
+    $prGate = $Checkpoint.pr_gate
+    if (@($prGate.PSObject.Properties.Name) -notcontains 'pr_number' -or $null -eq $prGate.pr_number) {
+        return $true
+    }
+    $recorded = 0
+    if (-not [int]::TryParse([string]$prGate.pr_number, [ref] $recorded)) {
+        return $false
+    }
+    return ($recorded -eq $CommandPrNumber)
+}
+
+function Get-EpicMergeGateUnresolvedReason {
+    <#
+    .SYNOPSIS
+        Returns '<code>: <epic detail>; <parallel detail>' when neither run branch resolved, or $null.
+    .DESCRIPTION
+        The ambiguity code wins when either target is Ambiguous. Returns $null when either
+        target is absent (a bare command) or either target resolved.
+    .PARAMETER EpicTarget
+        The epic run target, or $null.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget
+    )
+
+    if ($null -eq $EpicTarget -or $null -eq $ParallelTarget) {
+        return $null
+    }
+    $unresolved = @('NoTarget', 'Ambiguous')
+    if ($unresolved -notcontains $EpicTarget.Status -or $unresolved -notcontains $ParallelTarget.Status) {
+        return $null
+    }
+    $code = if ($EpicTarget.Status -eq 'Ambiguous') { $EpicTarget.ReasonCode } elseif ($ParallelTarget.Status -eq 'Ambiguous') { $ParallelTarget.ReasonCode } else { $EpicTarget.ReasonCode }
+    return ('{0}: {1}; {2}' -f $code, $EpicTarget.Detail, $ParallelTarget.Detail)
+}

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

@@ -38,10 +38,16 @@
     policy-level-not-cryptographic posture already accepted for
     enforce-pr-author-skill.ps1's own receipt mechanism. It is not a cryptographic control.
 
+    Issue #690: with an explicit PR number, the epic and parallel checkpoints are read
+    beneath the live worktree whose run checkpoint records that number, and the child
+    branch binds the number to pr_gate.pr_number when the per-feature checkpoint records
+    it. A bare command reads every checkpoint beneath the session worktree.
+
 .NOTES
-    Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
-    through injectable wrapper functions so tests can mock the boundary without writing
-    temporary files.
+    Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 through the
+    dot-sourced enforce-epic-merge-gate-resolution.ps1, whose import guard denies on a
+    failed import. Filesystem reads go through injectable wrapper functions so tests can
+    mock the boundary without writing temporary files.
 
     Honest disclosure: the standalone-merge authorization record is a policy-level,
     auditable declaration and is not a cryptographic or security control. authorized_by is
@@ -59,64 +65,8 @@ Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 # Standalone-merge authorization predicates and the two decision-envelope factories (issue #670).
 . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1')
-
-$script:ChildCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
-$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
-$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
-
-function Get-ChildOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
-        this function (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:ChildCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:ChildCheckpointPath -Raw)
-}
-
-function Get-EpicOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the epic checkpoint. Tests mock this function
-        (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
-}
-
-function Get-ParallelOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
-        this function (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:ParallelCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
-}
+# Checkpoint read seams, the import guard, and run-target resolution (issue #690).
+. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1')
 
 function ConvertFrom-EpicMergeGateJson {
     <#
@@ -361,6 +311,12 @@ function Invoke-EpicMergeGateDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    $importFailure = Get-EpicMergeGateImportFailureDecision
+    if ($null -ne $importFailure) {
+        return $importFailure
+    }
+
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
         return Get-EpicMergeGateBlockDecision -Reason (
@@ -399,18 +355,35 @@ function Invoke-EpicMergeGateDecision {
     }
 
     $commandPrNumber = Get-EpicMergeGateCommandPrNumber -CommandText $commandText
+    $sessionRoot = Get-EpicMergeGateSessionWorktreeRoot
 
-    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent)
-    if (Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) {
+    # The child merges from its own worktree, so its checkpoint is the session worktree's;
+    # a recorded pr_gate.pr_number must match an explicit command PR number (issue #690).
+    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $sessionRoot))
+    if ((Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) -and
+        (Test-ChildCheckpointPrGateBinding -Checkpoint $childCheckpoint -CommandPrNumber $commandPrNumber)) {
         return Get-EpicMergeGateAllowDecision
     }
 
-    $epicCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-EpicOrchestratorCheckpointContent)
+    # A bare command targets the current branch's PR, so it reads the session worktree. An
+    # explicit PR number locates each run checkpoint that records it (issue #690).
+    $epicTarget = $null
+    $parallelTarget = $null
+    $epicRoot = $sessionRoot
+    $parallelRoot = $sessionRoot
+    if ($null -ne $commandPrNumber) {
+        $epicTarget = Resolve-EpicMergeGateRunTarget -Kind epic -PrNumber $commandPrNumber
+        $parallelTarget = Resolve-EpicMergeGateRunTarget -Kind parallel -PrNumber $commandPrNumber
+        $epicRoot = if (@('SessionRoot', 'OtherWorktree') -contains $epicTarget.Status) { $epicTarget.WorktreeRoot } else { $null }
+        $parallelRoot = if (@('SessionRoot', 'OtherWorktree') -contains $parallelTarget.Status) { $parallelTarget.WorktreeRoot } else { $null }
+    }
+
+    $epicCheckpoint = if ($epicRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-EpicOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind epic -WorktreeRoot $epicRoot)) } else { $null }
     if (Test-EpicCheckpointAllowsMerge -Checkpoint $epicCheckpoint -CommandPrNumber $commandPrNumber) {
         return Get-EpicMergeGateAllowDecision
     }
 
-    $parallelCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ParallelOrchestratorCheckpointContent)
+    $parallelCheckpoint = if ($parallelRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-ParallelOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind parallel -WorktreeRoot $parallelRoot)) } else { $null }
     if (Test-ParallelCheckpointAllowsMerge -Checkpoint $parallelCheckpoint -CommandPrNumber $commandPrNumber) {
         return Get-EpicMergeGateAllowDecision
     }
@@ -423,7 +396,10 @@ function Invoke-EpicMergeGateDecision {
         if ($standalone.Allowed) {
             return Get-EpicMergeGateAllowDecision
         }
-        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $standalone.ReasonCode + ': ' + $standalone.Message)
+        # When neither run branch resolved, its reason code and detail precede the standalone reason.
+        $unresolved = Get-EpicMergeGateUnresolvedReason -EpicTarget $epicTarget -ParallelTarget $parallelTarget
+        $prefix = if ($unresolved) { $unresolved + '; ' } else { '' }
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message)
     }
 
     return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number, or a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green". No checkpoint satisfied this gate.'