@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.17

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

@@ -0,0 +1,144 @@
+<#
+.SYNOPSIS
+    Checkpoint read seams and run-target resolution for the epic worktree-removal gate (issue #690).
+
+.DESCRIPTION
+    Dot-sourced by enforce-epic-worktree-removal-gate.ps1 after its command-parser
+    dot-sources. Holds:
+
+    - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
+      $script:EpicWorktreeGateResolutionImportFailure, and
+      Get-EpicWorktreeGateImportFailureDecision turns it into a deny, so a missing module
+      cannot make the gate exit non-zero and fail open.
+    - The two 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 resolution seam Resolve-EpicWorktreeGateRunTarget, which locates the epic or
+      parallel checkpoint that records the removal target under worktree_path.
+    - Read-EpicWorktreeGateRunCheckpoint, which returns the target and the parsed
+      checkpoint beneath it ($null when the target is unresolved).
+
+.NOTES
+    PowerShell 7+. Depends on Get-EpicWorktreeGateBlockDecision and
+    ConvertFrom-EpicWorktreeGateJson from the gate file, resolved at call time. Mirrored
+    byte-identically under extensions/drm-copilot/resources/claude-customizations/.
+#>
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:EpicWorktreeGateResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:EpicWorktreeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
+function Get-EpicWorktreeGateImportFailureDecision {
+    <#
+    .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:EpicWorktreeGateResolutionImportFailure) {
+        return $null
+    }
+    return Get-EpicWorktreeGateBlockDecision -Reason (
+        "EPIC_WORKTREE_REMOVAL_BLOCKED: the worktree-resolution module '$($script:EpicWorktreeGateResolutionImportFailure)' " +
+        'failed to import, so the run checkpoint that governs this removal cannot be located; the gate fails closed.')
+}
+
+function Get-EpicWorktreeGateCheckpointContent {
+    <#
+    .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-EpicWorktreeGateParallelCheckpointContent {
+    <#
+    .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 Resolve-EpicWorktreeGateRunTarget {
+    <#
+    .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-EpicWorktreeGateRunCheckpoint {
+    <#
+    .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).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][ValidateSet('epic', 'parallel')][string] $Kind,
+        [AllowNull()][AllowEmptyString()][string] $WorktreePath
+    )
+
+    $target = Resolve-EpicWorktreeGateRunTarget -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 'epic') { Get-EpicWorktreeGateCheckpointContent -Path $path } else { Get-EpicWorktreeGateParallelCheckpointContent -Path $path }
+        $checkpoint = ConvertFrom-EpicWorktreeGateJson -Raw $raw
+    }
+    return [pscustomobject]@{
+        Target     = $target
+        Checkpoint = $checkpoint
+    }
+}

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

@@ -50,10 +50,16 @@
     allow for a removal to proceed; this gate keeps the EPIC_WORKTREE_REMOVAL_BLOCKED
     prefix for both of its branches so transcript attribution stays unambiguous.
 
+    Issue #690: each checkpoint is read beneath the live worktree whose run checkpoint
+    records the removal target under worktree_path, located by
+    enforce-epic-worktree-removal-gate-resolution.ps1. 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 through the
+    dot-sourced resolution sibling, 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.
 #>
 [CmdletBinding()]
 param()
@@ -67,50 +73,13 @@ Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeM
 # Invoke-EpicWorktreeRemovalGateDecision and by Get-EpicWorktreeRemovalCommandPath.
 . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
-$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
-$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
+# Checkpoint read seams, the import guard, and run-target resolution (issue #690).
+. (Join-Path $PSScriptRoot 'enforce-epic-worktree-removal-gate-resolution.ps1')
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
-# Sanctioned-removal manifest location. Recorded here beside the two checkpoint paths
-# 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-EpicWorktreeGateCheckpointContent {
-    <#
-    .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-EpicWorktreeGateParallelCheckpointContent {
-    <#
-    .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)
-}
-
 function ConvertFrom-EpicWorktreeGateJson {
     <#
     .SYNOPSIS
@@ -361,6 +330,12 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    $importFailure = Get-EpicWorktreeGateImportFailureDecision
+    if ($null -ne $importFailure) {
+        return $importFailure
+    }
+
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
         return Get-EpicWorktreeGateBlockDecision -Reason (
@@ -383,14 +358,23 @@ function Invoke-EpicWorktreeRemovalGateDecision {
 
     $worktreePath = Get-EpicWorktreeRemovalCommandPath -CommandText $commandText
 
-    $checkpoint = ConvertFrom-EpicWorktreeGateJson -Raw (Get-EpicWorktreeGateCheckpointContent)
+    # Each run checkpoint is read beneath the worktree that records this path (issue #690);
+    # an ambiguous target denies before any allow or manifest evaluation.
+    $epicRead = Read-EpicWorktreeGateRunCheckpoint -Kind epic -WorktreePath $worktreePath
+    $parallelRead = Read-EpicWorktreeGateRunCheckpoint -Kind parallel -WorktreePath $worktreePath
+    foreach ($read in @($epicRead, $parallelRead)) {
+        if ($read.Target.Status -eq 'Ambiguous') {
+            return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: $($read.Target.ReasonCode): $($read.Target.Detail)"
+        }
+    }
+    $checkpoint = $epicRead.Checkpoint
 
     $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
     if (Test-EpicWorktreeRemovalAllowed -FeatureRecord $featureRecord) {
         return Get-EpicWorktreeGateAllowDecision
     }
 
-    $parallelCheckpoint = ConvertFrom-EpicWorktreeGateJson -Raw (Get-EpicWorktreeGateParallelCheckpointContent)
+    $parallelCheckpoint = $parallelRead.Checkpoint
     if (Test-ParallelCheckpointAllowsWorktreeRemoval -Checkpoint $parallelCheckpoint -WorktreePath $worktreePath) {
         return Get-EpicWorktreeGateAllowDecision
     }
@@ -411,7 +395,12 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         return Get-EpicWorktreeGateAllowDecision
     }
 
-    return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal."
+    # When neither kind resolved, the deny names the resolution reason first (issue #690).
+    $prefix = ''
+    if ($epicRead.Target.Status -eq 'NoTarget' -and $parallelRead.Target.Status -eq 'NoTarget') {
+        $prefix = "EPIC_WORKTREE_REMOVAL_BLOCKED: $($epicRead.Target.ReasonCode): $($epicRead.Target.Detail). "
+    }
+    return Get-EpicWorktreeGateBlockDecision -Reason ($prefix + "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal.")
 }
 
 function Invoke-EpicWorktreeRemovalGateEntryPoint {

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

@@ -1,60 +1,212 @@
 <#
 .SYNOPSIS
-    Epic-scope command and path legs of the preimplementation gate (issue #663).
+    Epic-scope legs, checkpoint read seams, and target resolution of the preimplementation gate.
 
 .DESCRIPTION
-    Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds two groups of
+    Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds four groups of
     functions:
 
-    - The two per-mode read seams of issue #554 (Get-EpicCheckpointContent and
-      Get-ParallelCheckpointContent), relocated verbatim from the gate file by issue #663
-      so the gate stays inside the 500-line cap. Their names and behaviour are unchanged,
-      so tests that mock or shadow them by name are unaffected.
-    - The epic-scope decision for the command and path legs. A staging command or a
-      Write/Edit call is epic scope when the effective worktree's HEAD (the -C selector
-      worktree when present, otherwise the session root) equals the integration_branch of
-      artifacts/orchestration/epic-orchestrator-state.json. In epic scope the call is
-      decided by the epic command-leg readiness predicate, and under decision D2 an
-      implementation-classified operand is allowed only while a merge is in progress in
-      that worktree. Outside epic scope the decision function returns $null and the gate's
-      single-feature path runs unchanged.
+    - The import guard for the worktree-resolution modules (issue #690). A failed import
+      is recorded in $script:OrchestrationGateResolutionImportFailure, and
+      Get-OrchestrationGateImportFailureDecision turns that record into a deny, so a
+      missing module cannot make the gate exit non-zero and fail open.
+    - The three checkpoint read seams, Get-CheckpointContent, Get-EpicCheckpointContent,
+      and Get-ParallelCheckpointContent. Each takes a mandatory absolute path, so no
+      read binds to the calling process's directory. Get-CheckpointContent and
+      Get-OrchestrationModeDenyReason were relocated here from the gate file by issue #690
+      to keep the gate inside the 500-line cap.
+    - The target resolution of issue #690. Resolve-OrchestrationGateTarget selects the
+      worktree whose checkpoint governs the call from portable identity only: the
+      integration_branch: value for an epic delegation, the parallel_slug: value for a
+      parallel delegation, the file_path or git -C operand for the path and command legs,
+      and the canonical issue-number line and branch: label for a single-feature
+      delegation. Read-OrchestrationGateCheckpoint reads the checkpoint beneath the
+      resolved root, or returns the deny for an unresolved target.
+    - The epic-scope decision for the command and path legs (issue #663). A staging
+      command or a Write/Edit call is epic scope when the effective worktree's HEAD equals
+      the integration branch of the epic checkpoint that Resolve-EpicScopeCheckpoint
+      locates. Outside epic scope the decision function returns $null and the gate's
+      single-feature path runs.
 
 .NOTES
     PowerShell 7+. Depends on functions the gate defines or dot-sources before any call:
     Split-OrchestrationCommandLine and ConvertTo-OrchestrationCommandToken (helpers file),
     Get-OrchestrationDelegationCheckpointPath (modes file), and the gate's allow and block
-    decision constructors. Mirrored byte-identically under
+    decision constructors. Imports WorktreeItemResolution.psm1 and WorktreeRunResolution.psm1
+    before EpicScopeResolution.psm1, so the nested import inside EpicScopeResolution reuses
+    the same module instance. Mirrored byte-identically under
     extensions/drm-copilot/resources/claude-customizations/.
 #>
 
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop
+# Import guard (issue #690). Each worktree-resolution import is attempted in order; the
+# first failure is recorded by file name and the decision function denies on it.
+$script:OrchestrationGateResolutionImportFailure = $null
+foreach ($resolutionModule in @('WorktreeItemResolution.psm1', 'WorktreeRunResolution.psm1', 'EpicScopeResolution.psm1')) {
+    try {
+        Import-Module (Join-Path $PSScriptRoot "../lib/worktree-resolution/$resolutionModule") -Force -ErrorAction Stop
+    }
+    catch {
+        if (-not $script:OrchestrationGateResolutionImportFailure) { $script:OrchestrationGateResolutionImportFailure = $resolutionModule }
+    }
+}
 Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeReadiness.psm1') -Force -ErrorAction Stop
 
-# The two per-mode read seams (issue #554). Each takes its path from the fixed mode
-# table and never from a delegation's own text; an absent file returns an empty
-# string, which the readiness predicate then treats as a deny.
+function Get-OrchestrationGateImportFailureDecision {
+    <#
+    .SYNOPSIS
+        Returns the deny for a failed worktree-resolution import, or $null.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary, or $null when every import succeeded.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    if (-not $script:OrchestrationGateResolutionImportFailure) {
+        return $null
+    }
+    return Get-OrchestrationPreimplementationGateBlockDecision -Reason (
+        "PREIMPLEMENTATION_GATE_BLOCKED: the worktree-resolution module '$($script:OrchestrationGateResolutionImportFailure)' " +
+        'failed to import, so the checkpoint that governs this call cannot be located; the gate fails closed.')
+}
+
+# The three checkpoint read seams. Each takes the absolute path composed beneath a
+# resolved worktree root; an absent file returns an empty string, which the readiness
+# predicate then treats as a deny.
+function Get-CheckpointContent {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path)) {
+        return ''
+    }
+    return Get-Content -Raw -LiteralPath $Path
+}
+
 function Get-EpicCheckpointContent {
     [CmdletBinding()]
     [OutputType([string])]
-    param()
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
 
-    $path = Get-OrchestrationDelegationCheckpointPath -Mode 'epic'
-    if (-not (Test-Path -LiteralPath $path)) {
+    if (-not (Test-Path -LiteralPath $Path)) {
         return ''
     }
-    return Get-Content -Raw -LiteralPath $path
+    return Get-Content -Raw -LiteralPath $Path
 }
 
 function Get-ParallelCheckpointContent {
     [CmdletBinding()]
     [OutputType([string])]
-    param()
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
 
-    $path = Get-OrchestrationDelegationCheckpointPath -Mode 'parallel'
-    if (-not (Test-Path -LiteralPath $path)) {
+    if (-not (Test-Path -LiteralPath $Path)) {
         return ''
     }
-    return Get-Content -Raw -LiteralPath $path
+    return Get-Content -Raw -LiteralPath $Path
+}
+
+# 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. A resolved absolute path is named when known.
+function Get-OrchestrationModeDenyReason {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][string] $Mode,
+        [Parameter(Mandatory)][string] $Failure,
+        [AllowNull()][AllowEmptyString()][string] $CheckpointPath = ''
+    )
+
+    $path = if ($CheckpointPath) { $CheckpointPath } else { 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 Resolve-OrchestrationGateTarget {
+    <#
+    .SYNOPSIS
+        Resolves the worktree whose checkpoint governs a gated call (issue #690 seam).
+    .DESCRIPTION
+        An epic delegation is keyed on integration_branch: (with epic_feature_folder: as a
+        cross-check), a parallel delegation on parallel_slug:, a path leg on its file_path
+        operand, a command leg on its git -C selector (none means the session root), and a
+        single-feature delegation on its canonical issue-number line and branch: label.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][string] $Mode,
+        [AllowNull()][AllowEmptyString()][string] $Prompt = '',
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $sessionRoot = (Get-Location).Path
+    if ($Mode -eq 'epic' -or $Mode -eq 'parallel') {
+        $signal = Find-WorktreeRunIdentitySignal -Text $Prompt
+        if ($Mode -eq 'epic') {
+            return Resolve-WorktreeEpicTarget -IntegrationBranch $signal.IntegrationBranch -EpicSlug $signal.EpicSlug -SessionRoot $sessionRoot
+        }
+        return Resolve-WorktreeParallelTarget -ParallelSlug $signal.ParallelSlug -SessionRoot $sessionRoot
+    }
+    if ($FilePath) {
+        return Resolve-WorktreeOperandTarget -Path $FilePath -SessionRoot $sessionRoot
+    }
+    if ($Command) {
+        return Resolve-WorktreeOperandTarget -Path (Get-OrchestrationEpicScopeSelector -Command $Command) -SessionRoot $sessionRoot
+    }
+    return Resolve-WorktreeItemTarget -Text $Prompt -SessionRoot $sessionRoot
+}
+
+function Read-OrchestrationGateCheckpoint {
+    <#
+    .SYNOPSIS
+        Reads the checkpoint beneath the resolved target worktree, or returns the deny reason.
+    .DESCRIPTION
+        Resolved is $false, with DenyReason set, when the target is NoTarget or Ambiguous.
+        Otherwise Raw holds the checkpoint text (empty when absent) and Path its absolute
+        path. Only Status, WorktreeRoot, ReasonCode, and Detail are read from the target.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][string] $Mode,
+        [AllowNull()][AllowEmptyString()][string] $Prompt = '',
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $target = Resolve-OrchestrationGateTarget -Mode $Mode -Prompt $Prompt -FilePath $FilePath -Command $Command
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return [pscustomobject]@{
+            Resolved   = $false
+            Raw        = ''
+            Path       = $null
+            DenyReason = ("PREIMPLEMENTATION_GATE_BLOCKED: $($target.ReasonCode): the target worktree of this $Mode call " +
+                "could not be resolved: $($target.Detail). Implementation operations require an identifiable target " +
+                'worktree whose checkpoint is ready.')
+        }
+    }
+
+    $kind = if ($Mode -eq 'epic' -or $Mode -eq 'parallel') { $Mode } else { 'item' }
+    $path = Get-WorktreeRunCheckpointPath -Kind $kind -WorktreeRoot $target.WorktreeRoot
+    $raw = switch ($kind) {
+        'epic' { Get-EpicCheckpointContent -Path $path }
+        'parallel' { Get-ParallelCheckpointContent -Path $path }
+        default { Get-CheckpointContent -Path $path }
+    }
+    return [pscustomobject]@{
+        Resolved   = $true
+        Raw        = [string]$raw
+        Path       = $path
+        DenyReason = $null
+    }
 }
 
 function Get-OrchestrationEpicScopeSelector {

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()