@danmoisan/drm-copilot-mcp 1.1.15 → 1.1.17

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -19,17 +19,15 @@ Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -
 # proof the issue #539 exemption is behaviourally unchanged.
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-modes.ps1')
 
-# Epic-scope command and path legs (issue #663, decision D2), plus the two per-mode read
-# seams relocated from this file to keep it inside the 500-line cap.
+# Epic-scope command and path legs (issue #663, decision D2), the three checkpoint read
+# seams, the mode deny reason, and the target resolution with its import guard (issue
+# #690), all relocated to this sibling to keep the gate inside the 500-line cap.
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-epic-scope.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'
-
 # Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
 # of these is orchestration bookkeeping, not implementation, so the gate must not
 # require a ready checkpoint before the checkpoint itself can be created. The set is a
@@ -254,17 +252,6 @@ function Test-OrchestrationReady {
     )
 }
 
-function Get-CheckpointContent {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:CheckpointPath)) {
-        return ''
-    }
-    return Get-Content -Raw -LiteralPath $script:CheckpointPath
-}
-
 function Get-OrchestrationPreimplementationGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -295,23 +282,6 @@ function Get-OrchestrationPreimplementationGateBlockDecision {
     }
 }
 
-# Builds a mode-specific deny reason naming the checkpoint actually consulted and the
-# predicate that failed, behind the unchanged PREIMPLEMENTATION_GATE_BLOCKED prefix
-# that downstream reason-matching reads.
-function Get-OrchestrationModeDenyReason {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory)][string] $Mode,
-        [Parameter(Mandatory)][string] $Failure
-    )
-
-    $path = Get-OrchestrationDelegationCheckpointPath -Mode $Mode
-    return ("PREIMPLEMENTATION_GATE_BLOCKED: this $Mode-mode delegation was evaluated against " +
-        "$path, and the failed readiness predicate is '$Failure'. Implementation operations " +
-        'require that checkpoint to satisfy every readiness predicate before implementation begins.')
-}
-
 function Invoke-OrchestrationPreimplementationGateDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -337,6 +307,9 @@ function Invoke-OrchestrationPreimplementationGateDecision {
         [string] $ParallelCheckpointRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    $importFailure = Get-OrchestrationGateImportFailureDecision; if ($null -ne $importFailure) { return $importFailure }
+
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
         return Get-OrchestrationPreimplementationGateBlockDecision -Reason (
@@ -396,9 +369,16 @@ function Invoke-OrchestrationPreimplementationGateDecision {
     if ($mode -eq 'epic' -or $mode -eq 'parallel') {
         $isEpic = ($mode -eq 'epic')
         $injected = if ($isEpic) { 'EpicCheckpointRaw' } else { 'ParallelCheckpointRaw' }
-        $modeRaw = if ($PSBoundParameters.ContainsKey($injected)) {
-            [string]$PSBoundParameters[$injected]
-        } elseif ($isEpic) { Get-EpicCheckpointContent } else { Get-ParallelCheckpointContent }
+        $modePath = ''
+        if ($PSBoundParameters.ContainsKey($injected)) {
+            $modeRaw = [string]$PSBoundParameters[$injected]
+        } else {
+            # The run checkpoint is read beneath the worktree the kickoff identifies (#690).
+            $read = Read-OrchestrationGateCheckpoint -Mode $mode -Prompt $prompt
+            if (-not $read.Resolved) { return Get-OrchestrationPreimplementationGateBlockDecision -Reason $read.DenyReason }
+            $modeRaw = $read.Raw
+            $modePath = $read.Path
+        }
         try {
             $modeCheckpoint = ConvertFrom-CheckpointJson -Json ([string]$modeRaw)
         } catch { $modeCheckpoint = $null }
@@ -411,11 +391,14 @@ function Invoke-OrchestrationPreimplementationGateDecision {
         }
         if (-not $failure) { return Get-OrchestrationPreimplementationGateAllowDecision }
         return Get-OrchestrationPreimplementationGateBlockDecision -Reason (
-            Get-OrchestrationModeDenyReason -Mode $mode -Failure $failure)
+            Get-OrchestrationModeDenyReason -Mode $mode -Failure $failure -CheckpointPath $modePath)
     }
 
+    # Truthiness fall-through is kept: an empty -CheckpointRaw resolves like an unbound one.
     if (-not $CheckpointRaw) {
-        $CheckpointRaw = Get-CheckpointContent
+        $read = Read-OrchestrationGateCheckpoint -Mode 'single-feature' -Prompt $prompt -FilePath $filePath -Command $command
+        if (-not $read.Resolved) { return Get-OrchestrationPreimplementationGateBlockDecision -Reason $read.DenyReason }
+        $CheckpointRaw = $read.Raw
     }
     try {
         $checkpoint = ConvertFrom-CheckpointJson -Json $CheckpointRaw

package/resources/claude-customizations/.claude/hooks/enforce-parallel-abandon-gate.ps1

@@ -25,10 +25,10 @@
     .claude/hooks/enforce-epic-worktree-removal-gate.ps1.
 
     The two token values are declared ONCE EACH below and every match in this file reads
-    those variables rather than repeating a literal. The producer side of the same pair is
-    scripts/dev_tools/parallel_mutation_abandon_cli.py, and
-    tests/scripts/dev_tools/test_parallel_abandon_token_seam.py parses both sides at run
-    time so a rename on one side without the other fails.
+    those variables rather than repeating a literal. The pushed-down producer of the same pair
+    is .claude/lib/bash/abandon-parallel-item.sh (the Python CLI it ports remains the parity
+    reference), and tests/scripts/dev_tools/test_parallel_abandon_token_seam.py parses every
+    side at run time so a rename on one side without the others fails.
 #>
 [CmdletBinding()]
 param()

package/resources/claude-customizations/.claude/hooks/enforce-parallel-cohort-barrier.ps1

@@ -16,8 +16,11 @@
       1. Resolve the target item's feature folder from the prompt text by scanning for a
          docs/features/active/<token> path, mirroring the epic hook's technique
          (longest match wins; a .md-suffixed match uses its parent directory).
-      2. Read artifacts/orchestration/parallel-orchestrator-state.json and locate the
-         items[] record whose feature_folder resolves to the same basename.
+      2. Resolve the worktree whose parallel checkpoint records the prompt's
+         parallel_slug: value (issue #690), deny an unresolved or ambiguous target, then
+         read artifacts/orchestration/parallel-orchestrator-state.json beneath that
+         worktree and locate the items[] record whose feature_folder resolves to the same
+         basename.
       3. Project the cohort coloring to the cohorts[] rows whose generation equals the
          top-level recolor_generation, and read the target item's cohort index from that
          projection.
@@ -40,16 +43,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:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:ParallelCohortBarrierResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:ParallelCohortBarrierResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 $script:ParallelModeMarker = 'Parallel mode: true'
 
@@ -62,17 +75,39 @@ function Get-ParallelCohortBarrierCheckpointContent {
     .SYNOPSIS
         Read the raw JSON text of the parallel 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:ParallelCheckpointPath -PathType Leaf)) {
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Resolve-ParallelCohortBarrierTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose parallel checkpoint governs a kickoff (issue #690 seam).
+    .DESCRIPTION
+        Keyed on the prompt's parallel_slug: value; 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-WorktreeParallelTarget -ParallelSlug $signal.ParallelSlug -SessionRoot (Get-Location).Path
 }
 
 function Get-ParallelCohortBarrierFolderBasename {
@@ -196,6 +231,13 @@ function Invoke-ParallelCohortBarrierDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    if ($script:ParallelCohortBarrierResolutionImportFailure) {
+        return Get-ParallelCohortBarrierBlockDecision -Reason (
+            "PARALLEL_COHORT_BARRIER_BLOCKED: the worktree-resolution module '$($script:ParallelCohortBarrierResolutionImportFailure)' " +
+            'failed to import, so the parallel checkpoint that governs this delegation cannot be located; the gate fails closed.')
+    }
+
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
         return Get-ParallelCohortBarrierBlockDecision -Reason (
@@ -214,12 +256,18 @@ function Invoke-ParallelCohortBarrierDecision {
         return Get-ParallelCohortBarrierAllowDecision
     }
 
+    # The parallel checkpoint is located by the kickoff's parallel_slug (issue #690).
+    $target = Resolve-ParallelCohortBarrierTarget -Prompt $prompt
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return Get-ParallelCohortBarrierBlockDecision -Reason "PARALLEL_COHORT_BARRIER_BLOCKED: $($target.ReasonCode): $($target.Detail)"
+    }
+
     $featureFolder = Find-ParallelCohortBarrierFeatureFolderFromPrompt -Prompt $prompt
     if (-not $featureFolder) {
         return Get-ParallelCohortBarrierBlockDecision -Reason 'PARALLEL_COHORT_BARRIER_BLOCKED: a parallel-mode orchestrator delegation must reference the target item feature folder path (docs/features/active/<folder>) in the prompt so its conflict edges and cohort position can be verified.'
     }
 
-    $checkpointRaw = Get-ParallelCohortBarrierCheckpointContent
+    $checkpointRaw = Get-ParallelCohortBarrierCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind parallel -WorktreeRoot $target.WorktreeRoot)
     $checkpoint = $null
     if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
         try {

package/resources/claude-customizations/.claude/hooks/enforce-parallel-drift-gate.ps1

@@ -45,10 +45,15 @@
     retrospective backstop, is the PARALLEL_DRIFT_GATE_VIOLATION invariant in
     scripts/dev_tools/_parallel_orchestrator_state_drift.py.
 
+    Issue #690: the parallel checkpoint is read beneath the worktree that the prompt's
+    parallel_slug: value resolves to, never beneath the payload cwd. An unresolved or
+    ambiguous target denies after the subagent and marker filter and before the folder check.
+
 .NOTES
-    PowerShell 7+, no module dependencies. Both read boundaries -- the checkpoint read and the
-    finding-file existence check -- are injectable wrapper functions, so tests mock them
-    without writing temporary files.
+    PowerShell 7+. Depends on WorktreeRunResolution.psm1 (issue #690), imported inside a
+    guard: a failed import is recorded and the decision denies naming the module. Both read
+    boundaries -- the checkpoint read and the finding-file existence check -- are injectable
+    wrapper functions, so tests mock them without writing temporary files.
 
     The eight shape-and-derivation helpers this hook calls live in the dot-sourced sibling
     module .claude/hooks/enforce-parallel-drift-gate-helpers.ps1, together with the
@@ -63,12 +68,21 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:ParallelDriftGateResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:ParallelDriftGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
 # Dot-source the shape-and-derivation helpers. Guarded so a missing file produces a clear error
 # and so dot-sourcing this hook in tests loads the helpers too.
 $script:ParallelDriftGateHelpersPath = Join-Path $PSScriptRoot 'enforce-parallel-drift-gate-helpers.ps1'
 . $script:ParallelDriftGateHelpersPath
 
-$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:ParallelModeMarker = 'Parallel mode: true'
 $script:ReviewSubagentType = 'feature-review'
 $script:ActiveFeatureRoot = 'docs/features/active'
@@ -85,15 +99,38 @@ function Get-ParallelDriftGateCheckpointContent {
     .SYNOPSIS
         Read the raw JSON text of the parallel checkpoint, or $null when the file is absent.
         Tests mock this function (checkpoint-read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the resolved worktree root.
     #>
     [CmdletBinding()]
     [OutputType([string])]
-    param()
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
 
-    if (-not (Test-Path -LiteralPath $script:ParallelCheckpointPath -PathType Leaf)) {
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Resolve-ParallelDriftGateTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose parallel checkpoint governs a review delegation (issue #690
+        seam).
+    .DESCRIPTION
+        Keyed on the prompt's parallel_slug: value; 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-WorktreeParallelTarget -ParallelSlug $signal.ParallelSlug -SessionRoot (Get-Location).Path
 }
 
 function Test-ParallelDriftFindingPresent {
@@ -282,6 +319,13 @@ function Invoke-ParallelDriftGateDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    if ($script:ParallelDriftGateResolutionImportFailure) {
+        return Get-ParallelDriftGateBlockDecision -Reason (
+            "PARALLEL_DRIFT_GATE_BLOCKED: the worktree-resolution module '$($script:ParallelDriftGateResolutionImportFailure)' " +
+            'failed to import, so the parallel checkpoint that governs this review cannot be located; the gate fails closed.')
+    }
+
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
         return Get-ParallelDriftGateBlockDecision -Reason (
@@ -302,12 +346,18 @@ function Invoke-ParallelDriftGateDecision {
         return Get-ParallelDriftGateAllowDecision
     }
 
+    # The parallel checkpoint is located by the delegation's parallel_slug (issue #690).
+    $target = Resolve-ParallelDriftGateTarget -Prompt $prompt
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: $($target.ReasonCode): $($target.Detail)"
+    }
+
     $featureFolder = Find-ParallelDriftGateFeatureFolderFromPrompt -Prompt $prompt
     if (-not $featureFolder) {
         return Get-ParallelDriftGateBlockDecision -Reason 'PARALLEL_DRIFT_GATE_BLOCKED: a parallel-mode feature-review delegation must reference the target item feature folder in the prompt so its drift state can be verified.'
     }
 
-    $checkpointRaw = Get-ParallelDriftGateCheckpointContent
+    $checkpointRaw = Get-ParallelDriftGateCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind parallel -WorktreeRoot $target.WorktreeRoot)
     $checkpoint = $null
     if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
         try {
@@ -317,7 +367,7 @@ function Invoke-ParallelDriftGateDecision {
         }
     }
     if ($null -eq $checkpoint) {
-        return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: the parallel checkpoint '$script:ParallelCheckpointPath' is missing or unreadable, so the drift state of '$featureFolder' cannot be verified."
+        return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: the parallel checkpoint 'artifacts/orchestration/parallel-orchestrator-state.json' in worktree '$($target.WorktreeRoot)' is missing or unreadable, so the drift state of '$featureFolder' cannot be verified."
     }
 
     $item = Find-ParallelDriftGateItemRecord -Checkpoint $checkpoint -FeatureFolder $featureFolder

package/resources/claude-customizations/.claude/hooks/enforce-parallel-worktree-removal-gate.ps1

@@ -20,10 +20,15 @@
     opens its own pull request against main, so a removed worktree is unrecoverable work
     unless that item's own merge has been durably confirmed.
 
+    Issue #690: each checkpoint is read beneath the live worktree whose run checkpoint
+    records the removal target under worktree_path. An ambiguous target denies before any
+    allow; when neither kind resolves, the deny names TARGET_WORKTREE_NOT_DERIVABLE.
+
 .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 injectable wrapper functions so tests can
+    mock the boundary without writing temporary files.
 #>
 [CmdletBinding()]
 param()
@@ -39,17 +44,19 @@ Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeM
 # concern now has one implementation.
 . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
-$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:ParallelWorktreeGateResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:ParallelWorktreeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
-# Epic checkpoint location (issue #688). An epic run records per-child state in
-# features[] and never writes the parallel checkpoint, so without this read every
-# merged epic child worktree reached the deny below even though
-# enforce-epic-worktree-removal-gate.ps1 authorized the same call. Both gates run on
-# the same Bash call, so that deny won and epic worktrees could never be removed.
-$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
-# Sanctioned-removal manifest location. Recorded here beside the checkpoint path so
-# every hook-read document this gate consults is named in one place; the module owns
-# the read itself.
+# Sanctioned-removal manifest location. Recorded here so every hook-read document this
+# gate consults is named; the module owns the read itself.
 $script:CleanupWorktreeManifestPath = 'artifacts/orchestration/cleanup-worktrees-manifest.json'
 
 function Get-ParallelWorktreeRemovalGateCheckpointContent {
@@ -57,17 +64,19 @@ function Get-ParallelWorktreeRemovalGateCheckpointContent {
     .SYNOPSIS
         Read the raw JSON text of the parallel 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:ParallelCheckpointPath -PathType Leaf)) {
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
+    return (Get-Content -LiteralPath $Path -Raw)
 }
 
 function Get-ParallelWorktreeRemovalGateEpicCheckpointContent {
@@ -78,18 +87,81 @@ function Get-ParallelWorktreeRemovalGateEpicCheckpointContent {
     .DESCRIPTION
         A separate seam from the parallel checkpoint reader so a test can drive the
         two documents independently: the epic branch must be exercised with the
-        parallel checkpoint absent, present-but-not-covering, and covering.
+        parallel checkpoint absent, present-but-not-covering, and covering. An epic run
+        records per-child state in features[] and never writes the parallel checkpoint,
+        so without this read every merged epic child worktree reached the deny below.
+    .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-ParallelWorktreeGateRunTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose run checkpoint records a worktree path (issue #690 seam).
+    .PARAMETER Kind
+        epic or parallel.
+    .PARAMETER WorktreePath
+        The removal target the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][ValidateSet('epic', 'parallel')][string] $Kind,
+        [AllowNull()][AllowEmptyString()][string] $WorktreePath
+    )
+
+    return Resolve-WorktreeRunTargetByRecord -Kind $Kind -RecordField worktree_path -Value $WorktreePath -SessionRoot (Get-Location).Path
+}
+
+function Read-ParallelWorktreeGateRunCheckpoint {
+    <#
+    .SYNOPSIS
+        Resolve one run kind and read its checkpoint beneath the resolved root.
+    .PARAMETER Kind
+        epic or parallel.
+    .PARAMETER WorktreePath
+        The removal target the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with Target and Checkpoint ($null when
+        unresolved, absent, or unparseable).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][ValidateSet('epic', 'parallel')][string] $Kind,
+        [AllowNull()][AllowEmptyString()][string] $WorktreePath
+    )
+
+    $target = Resolve-ParallelWorktreeGateRunTarget -Kind $Kind -WorktreePath $WorktreePath
+    $checkpoint = $null
+    if ($target.Status -eq 'SessionRoot' -or $target.Status -eq 'OtherWorktree') {
+        $path = Get-WorktreeRunCheckpointPath -Kind $Kind -WorktreeRoot $target.WorktreeRoot
+        $raw = if ($Kind -eq 'parallel') { Get-ParallelWorktreeRemovalGateCheckpointContent -Path $path } else { Get-ParallelWorktreeRemovalGateEpicCheckpointContent -Path $path }
+        if (-not [string]::IsNullOrWhiteSpace($raw)) {
+            try {
+                $checkpoint = $raw | ConvertFrom-Json -ErrorAction Stop
+            } catch {
+                $checkpoint = $null
+            }
+        }
+    }
+    return [pscustomobject]@{
+        Target     = $target
+        Checkpoint = $checkpoint
+    }
 }
 
 function Get-ParallelWorktreeRemovalCommandPath {
@@ -263,6 +335,13 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    if ($script:ParallelWorktreeGateResolutionImportFailure) {
+        return Get-ParallelWorktreeGateBlockDecision -Reason (
+            "PARALLEL_WORKTREE_REMOVAL_BLOCKED: the worktree-resolution module '$($script:ParallelWorktreeGateResolutionImportFailure)' " +
+            'failed to import, so the run checkpoint that governs this removal cannot be located; the gate fails closed.')
+    }
+
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
         return Get-ParallelWorktreeGateBlockDecision -Reason (
@@ -285,15 +364,16 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
 
     $worktreePath = Get-ParallelWorktreeRemovalCommandPath -CommandText $commandText
 
-    $checkpointRaw = Get-ParallelWorktreeRemovalGateCheckpointContent
-    $checkpoint = $null
-    if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
-        try {
-            $checkpoint = $checkpointRaw | ConvertFrom-Json -ErrorAction Stop
-        } catch {
-            $checkpoint = $null
+    # Each run checkpoint is read beneath the worktree that records this path (issue #690),
+    # parallel kind first; an ambiguous target denies before any allow or manifest check.
+    $parallelRead = Read-ParallelWorktreeGateRunCheckpoint -Kind parallel -WorktreePath $worktreePath
+    $epicRead = Read-ParallelWorktreeGateRunCheckpoint -Kind epic -WorktreePath $worktreePath
+    foreach ($read in @($parallelRead, $epicRead)) {
+        if ($read.Target.Status -eq 'Ambiguous') {
+            return Get-ParallelWorktreeGateBlockDecision -Reason "PARALLEL_WORKTREE_REMOVAL_BLOCKED: $($read.Target.ReasonCode): $($read.Target.Detail)"
         }
     }
+    $checkpoint = $parallelRead.Checkpoint
 
     $itemRecord = Find-ParallelWorktreeItemRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $itemRecord) {
@@ -310,15 +390,7 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
     #
     # Fail-closed is preserved: an absent, unreadable, or malformed epic checkpoint parses to
     # $null, which yields no record, which is not allowed.
-    $epicCheckpointRaw = Get-ParallelWorktreeRemovalGateEpicCheckpointContent
-    $epicCheckpoint = $null
-    if (-not [string]::IsNullOrWhiteSpace($epicCheckpointRaw)) {
-        try {
-            $epicCheckpoint = $epicCheckpointRaw | ConvertFrom-Json -ErrorAction Stop
-        } catch {
-            $epicCheckpoint = $null
-        }
-    }
+    $epicCheckpoint = $epicRead.Checkpoint
 
     $featureRecord = Find-ParallelWorktreeItemRecord -Checkpoint $epicCheckpoint -WorktreePath $worktreePath -RecordArrayName 'features'
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $featureRecord) {
@@ -340,7 +412,12 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
         return Get-ParallelWorktreeGateAllowDecision
     }
 
-    return Get-ParallelWorktreeGateBlockDecision -Reason "PARALLEL_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching parallel checkpoint items[] record with merge_status in {merged, worktree_removed}. The checkpoint was unreadable, no matching record was found, or merge_status was not yet safe for removal."
+    # When neither kind resolved, the deny names the resolution reason first (issue #690).
+    $prefix = ''
+    if ($parallelRead.Target.Status -eq 'NoTarget' -and $epicRead.Target.Status -eq 'NoTarget') {
+        $prefix = "PARALLEL_WORKTREE_REMOVAL_BLOCKED: $($parallelRead.Target.ReasonCode): $($parallelRead.Target.Detail). "
+    }
+    return Get-ParallelWorktreeGateBlockDecision -Reason ($prefix + "PARALLEL_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching parallel checkpoint items[] record with merge_status in {merged, worktree_removed}. The checkpoint was unreadable, no matching record was found, or merge_status was not yet safe for removal.")
 }
 
 function Invoke-ParallelWorktreeRemovalGateEntryPoint {