@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.16",
+  "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/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-powershell-batch-budget-route.ps1 → enforce-batch-budget-route.ps1}

@@ -1,19 +1,21 @@
 <#
 .SYNOPSIS
-    Pure route helpers for the PowerShell batch-budget hook.
+    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 enforce-powershell-batch-budget.ps1 and has no
-    entry point. None of the functions reads a file or an environment variable; the
-    checkpoint text is supplied by the caller.
+    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-PowerShellBatchBudgetCheckpoint {
+function ConvertFrom-BatchBudgetCheckpoint {
     <#
     .SYNOPSIS
         Parses orchestrator checkpoint text into a checkpoint object.
@@ -50,7 +52,7 @@ function ConvertFrom-PowerShellBatchBudgetCheckpoint {
     return $null
 }
 
-function Get-PowerShellBatchBudgetSelectedRoute {
+function Get-BatchBudgetSelectedRoute {
     <#
     .SYNOPSIS
         Returns the route selected by an orchestrator checkpoint.
@@ -69,7 +71,7 @@ function Get-PowerShellBatchBudgetSelectedRoute {
         [string] $CheckpointText
     )
 
-    $checkpoint = ConvertFrom-PowerShellBatchBudgetCheckpoint -CheckpointText $CheckpointText
+    $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
     if ($null -eq $checkpoint) {
         return ''
     }
@@ -89,7 +91,7 @@ function Get-PowerShellBatchBudgetSelectedRoute {
     return ''
 }
 
-function Test-PowerShellBatchBudgetLargePathRoute {
+function Test-BatchBudgetLargePathRoute {
     <#
     .SYNOPSIS
         Reports whether an orchestrator checkpoint selects the uncapped large path.
@@ -110,12 +112,12 @@ function Test-PowerShellBatchBudgetLargePathRoute {
     )
 
     try {
-        $checkpoint = ConvertFrom-PowerShellBatchBudgetCheckpoint -CheckpointText $CheckpointText
+        $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
         if ($null -eq $checkpoint) {
             return $false
         }
 
-        $route = Get-PowerShellBatchBudgetSelectedRoute -CheckpointText $CheckpointText
+        $route = Get-BatchBudgetSelectedRoute -CheckpointText $CheckpointText
         if (-not (@('large', 'remediation', 'preparation') -ccontains $route)) {
             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.'

package/resources/claude-customizations/.claude/hooks/enforce-epic-wave-barrier.ps1

@@ -12,8 +12,11 @@
          docs/features/active/<token> path, mirroring
          enforce-prd-feature-before-planner.ps1's Find-PrdFeatureFolderFromPrompt
          technique (longest match wins; a .md-suffixed match uses its parent directory).
-      2. Read artifacts/orchestration/epic-orchestrator-state.json and locate the
-         features[] record whose feature_folder equals the resolved basename.
+      2. Resolve the worktree whose epic checkpoint records the prompt's
+         integration_branch: value (issue #690), deny an unresolved or ambiguous target,
+         then read artifacts/orchestration/epic-orchestrator-state.json beneath that
+         worktree and locate the features[] record whose feature_folder equals the
+         resolved basename.
       3. Look up that feature's depends_on list, and for every dependency, locate its own
          features[] record.
       4. Deny with reason EPIC_WAVE_BARRIER_BLOCKED unless every dependency's merge_status
@@ -26,16 +29,26 @@
     SubagentStop time.
 
 .NOTES
-    Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
-    through an injectable wrapper function so tests can mock the boundary without writing
-    temporary files.
+    Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 (issue #690),
+    imported inside a guard: a failed import is recorded and the decision denies naming
+    the module. Filesystem reads go through an injectable wrapper function so tests can
+    mock the boundary without writing temporary files.
 #>
 [CmdletBinding()]
 param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
-$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:EpicWaveBarrierResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:EpicWaveBarrierResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 $script:EpicModeMarker = 'Epic mode: true'
 
@@ -44,17 +57,39 @@ function Get-EpicWaveBarrierCheckpointContent {
     .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()
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
 
-    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Resolve-EpicWaveBarrierTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose epic checkpoint governs a kickoff (issue #690 seam).
+    .DESCRIPTION
+        Keyed on the prompt's integration_branch: value, with epic_feature_folder: as a
+        cross-check; never on a feature-folder path or the payload cwd.
+    .PARAMETER Prompt
+        The delegation prompt text.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Prompt)
+
+    $signal = Find-WorktreeRunIdentitySignal -Text $Prompt
+    return Resolve-WorktreeEpicTarget -IntegrationBranch $signal.IntegrationBranch -EpicSlug $signal.EpicSlug -SessionRoot (Get-Location).Path
 }
 
 function Find-EpicWaveBarrierFeatureFolderFromPrompt {
@@ -246,6 +281,13 @@ function Invoke-EpicWaveBarrierDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    if ($script:EpicWaveBarrierResolutionImportFailure) {
+        return Get-EpicWaveBarrierBlockDecision -Reason (
+            "EPIC_WAVE_BARRIER_BLOCKED: the worktree-resolution module '$($script:EpicWaveBarrierResolutionImportFailure)' " +
+            'failed to import, so the epic checkpoint that governs this delegation cannot be located; the gate fails closed.')
+    }
+
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
         return Get-EpicWaveBarrierBlockDecision -Reason (
@@ -264,12 +306,18 @@ function Invoke-EpicWaveBarrierDecision {
         return Get-EpicWaveBarrierAllowDecision
     }
 
+    # The epic checkpoint is located by the kickoff's integration branch (issue #690).
+    $target = Resolve-EpicWaveBarrierTarget -Prompt $prompt
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return Get-EpicWaveBarrierBlockDecision -Reason "EPIC_WAVE_BARRIER_BLOCKED: $($target.ReasonCode): $($target.Detail)"
+    }
+
     $featureFolder = Find-EpicWaveBarrierFeatureFolderFromPrompt -Prompt $prompt
     if (-not $featureFolder) {
         return Get-EpicWaveBarrierBlockDecision -Reason 'EPIC_WAVE_BARRIER_BLOCKED: an epic-mode orchestrator delegation must reference the target feature folder in the prompt so its dependency edges can be verified.'
     }
 
-    $checkpointRaw = Get-EpicWaveBarrierCheckpointContent
+    $checkpointRaw = Get-EpicWaveBarrierCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind epic -WorktreeRoot $target.WorktreeRoot)
     $checkpoint = $null
     if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
         try {