@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

@@ -4,29 +4,30 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 
 # Pure pathspec classifier for the issue #539 orchestration-bookkeeping staging exemption.
 # Extracted to a dot-sourced sibling so this file stays inside the 500-line cap, following
 # the enforce-pr-author-skill.ps1 headroom-split precedent.
-. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-helpers.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-orchestration-preimplementation-gate-helpers.ps1' -ErrorRecord $_ }
 
 # Pure mode dispatch and per-mode readiness predicates for issue #554. A new sibling
 # rather than an addition to the helpers file above, whose header declares a different
 # normative contract and which lacks headroom; leaving that file byte-untouched is the
 # proof the issue #539 exemption is behaviourally unchanged.
-. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-modes.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-modes.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-orchestration-preimplementation-gate-modes.ps1' -ErrorRecord $_ }
 
 # 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')
+try { . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-epic-scope.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-orchestration-preimplementation-gate-epic-scope.ps1' -ErrorRecord $_ }
 
 # 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')
+try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
 
 # Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
 # of these is orchestration bookkeeping, not implementation, so the gate must not
@@ -306,9 +307,8 @@ function Invoke-OrchestrationPreimplementationGateDecision {
         [AllowEmptyString()]
         [string] $ParallelCheckpointRaw
     )
-
-    # A failed worktree-resolution import denies before any other logic (issue #690).
-    $importFailure = Get-OrchestrationGateImportFailureDecision; if ($null -ne $importFailure) { return $importFailure }
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PREIMPLEMENTATION_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -383,11 +383,13 @@ function Invoke-OrchestrationPreimplementationGateDecision {
             $modeCheckpoint = ConvertFrom-CheckpointJson -Json ([string]$modeRaw)
         } catch { $modeCheckpoint = $null }
         $folder = Find-OrchestrationDelegationTargetFolder -Prompt $prompt
-        $issue = Find-OrchestrationDelegationIssueNumber -Prompt $prompt
+        # Only the keyed issue number breaks a tie among cited folders (#565 CR-1); the bare hash form feeds the D3 record lookup only.
+        $issue = Find-OrchestrationDelegationIssueNumber -Prompt $prompt -KeyedOnly
+        $fallbackIssue = Find-OrchestrationDelegationIssueNumber -Prompt $prompt
         $failure = if ($isEpic) {
-            Get-EpicOrchestrationReadinessFailure -Checkpoint $modeCheckpoint -TargetFolder $folder -IssueNumber $issue
+            Get-EpicOrchestrationReadinessFailure -Checkpoint $modeCheckpoint -TargetFolder $folder -IssueNumber $issue -FallbackIssueNumber $fallbackIssue
         } else {
-            Get-ParallelOrchestrationReadinessFailure -Checkpoint $modeCheckpoint -TargetFolder $folder -IssueNumber $issue
+            Get-ParallelOrchestrationReadinessFailure -Checkpoint $modeCheckpoint -TargetFolder $folder -IssueNumber $issue -FallbackIssueNumber $fallbackIssue
         }
         if (-not $failure) { return Get-OrchestrationPreimplementationGateAllowDecision }
         return Get-OrchestrationPreimplementationGateBlockDecision -Reason (
@@ -454,6 +456,9 @@ function Invoke-OrchestrationPreimplementationGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PREIMPLEMENTATION_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PREIMPLEMENTATION_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 # The entry point returns its [int] exit code as the last pipeline element and the
 # decision JSON before it. `exit (<call>)` would capture BOTH into the exit

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

@@ -32,9 +32,10 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 # The two tokens this gate matches on. These are the ONLY places either token literal
 # appears in this file; the seam test extracts the consumer-side values from exactly
 # these two named assignments.
@@ -48,8 +49,8 @@ $script:AbandonBlockedReasonCode = 'PARALLEL_ABANDON_BLOCKED'
 # rather than above them, deliberately: the assignments keep their existing line numbers,
 # so the diff shows no change at either line. Both are still declared before any function
 # body runs, because the file executes top to bottom before any of its functions is called.
-. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
-. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
 
 function Get-ParallelAbandonGateToolInput {
     <#
@@ -314,6 +315,8 @@ function Invoke-ParallelAbandonGateDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'enforce-parallel-abandon-gate:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     # An absent payload carries no command to gate, so there is nothing in scope. This is
     # allow rather than deny because the gate constrains one specific destructive command
@@ -345,6 +348,9 @@ function Invoke-ParallelAbandonGateDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('enforce-parallel-abandon-gate: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'enforce-parallel-abandon-gate:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $decision = Invoke-ParallelAbandonGateDecision -ToolInputRaw (Get-ParallelAbandonGateToolInput)
 

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

@@ -13,24 +13,29 @@
     conflict_edges[], and position is read from the current cohort coloring.
 
     Resolution and decision procedure:
-      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. 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
+      1. Resolve the worktree whose parallel checkpoint records the prompt's
+         parallel_slug: value (issue #690) and deny an unresolved or ambiguous target.
+      2. Collect the cited feature-folder candidates with the shared resolver
+         (feature-folder-resolution.ps1, issue #565): every docs/features/active/<token>
+         path is truncated to its feature-folder segment, so a nested research/ or
+         evidence/ citation names its own folder. No candidate denies.
+      3. Read artifacts/orchestration/parallel-orchestrator-state.json beneath that
+         worktree and select the target among the candidates with
+         Select-FeatureFolderTarget. The canonical issue-number line, when it names exactly
+         one number, breaks a tie among the cited run items; two or more remaining
+         candidates otherwise deny as ambiguous. Neither string length nor prompt position
+         takes part in the selection. Then locate the items[] record whose feature_folder
+         resolves to the selected basename.
+      4. 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.
-      4. Collect every conflict_edges[] neighbor of the target item.
-      5. Deny with reason PARALLEL_COHORT_BARRIER_BLOCKED unless every neighbor that sits
+      5. Collect every conflict_edges[] neighbor of the target item.
+      6. Deny with reason PARALLEL_COHORT_BARRIER_BLOCKED unless every neighbor that sits
          in a strictly prior current-generation cohort has merge_status in
          {merged, worktree_removed}. ci_green does NOT satisfy the barrier: an item whose
          CI is green has not merged, so its worktree is still live and its contention is
          unresolved. Same-cohort and later-cohort neighbors do not block Layer 1.
-      6. A missing or unparseable checkpoint, an unresolved feature-folder token, a
+      7. A missing or unparseable checkpoint, an unresolved feature-folder token, a
          missing items[] record, a target with no current-generation cohort assignment, a
          missing neighbor record, and a missing merge_status all deny (fail-closed).
 
@@ -43,24 +48,33 @@
     SubagentStop time.
 
 .NOTES
-    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.
+    Compatible with PowerShell 7+. Depends on WorktreeItemResolution.psm1 and
+    WorktreeRunResolution.psm1 (issue #690) and the pure sibling
+    feature-folder-resolution.ps1 (issue #565), each loaded inside a guard: the first
+    failure is recorded and the decision denies naming the dependency. Filesystem reads go
+    through an injectable wrapper function so tests can mock the boundary without writing
+    temporary files.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 
-# Import guard (issue #690): a failed import denies instead of failing open.
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 $script:ParallelCohortBarrierResolutionImportFailure = $null
+
+# Shared feature-folder resolution (issue #565). Guarded so a failed dot-source denies
+# rather than failing open; an earlier recorded failure is kept.
 try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+    . (Join-Path $PSScriptRoot 'feature-folder-resolution.ps1')
 }
 catch {
-    $script:ParallelCohortBarrierResolutionImportFailure = 'WorktreeRunResolution.psm1'
+    if (-not $script:ParallelCohortBarrierResolutionImportFailure) {
+        $script:ParallelCohortBarrierResolutionImportFailure = 'feature-folder-resolution.ps1'
+    }
 }
 
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
@@ -68,7 +82,7 @@ $script:ParallelModeMarker = 'Parallel mode: true'
 
 # Dot-source the record-resolution and barrier helpers. Guarded so dot-sourcing this
 # hook in tests loads the helpers too (issue #501 headroom split).
-. (Join-Path $PSScriptRoot 'enforce-parallel-cohort-barrier-helpers.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-parallel-cohort-barrier-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-parallel-cohort-barrier-helpers.ps1' -ErrorRecord $_ }
 
 function Get-ParallelCohortBarrierCheckpointContent {
     <#
@@ -147,43 +161,27 @@ function Get-ParallelCohortBarrierFolderBasename {
 function Find-ParallelCohortBarrierFeatureFolderFromPrompt {
     <#
     .SYNOPSIS
-        Scans a prompt string for docs/features/active/<...> path tokens and returns the
-        longest unique match's basename. Returns $null when no match is found.
+        Returns the distinct feature-folder basenames cited in a prompt, in first-occurrence
+        order. Returns no output when no folder is cited.
     .DESCRIPTION
-        Mirrors the epic wave-barrier hook's technique: forward- or backslash-separated
-        path tokens are accepted, the longest match wins, and a .md-suffixed match resolves
-        to its parent directory before the basename is extracted.
+        Delegates to Find-FeatureFolderCandidate in the shared resolver (issue #565): each
+        docs/features/active/<token> path, in either separator style, is truncated to its
+        feature-folder segment, so a nested research/ or evidence/ citation names its own
+        folder. Selection among several candidates is made by Select-FeatureFolderTarget.
     .PARAMETER Prompt
         The delegation prompt text under evaluation.
     .OUTPUTS
-        System.String or $null
+        System.String[]
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([string[]])]
     param(
         [Parameter(Mandatory)]
         [AllowEmptyString()]
         [string] $Prompt
     )
 
-    if (-not $Prompt) {
-        return $null
-    }
-
-    $pattern = 'docs[\\/]+features[\\/]+active[\\/]+[^\s"''`]+'
-    $matchList = [regex]::Matches($Prompt, $pattern)
-    if ($matchList.Count -eq 0) {
-        return $null
-    }
-
-    $unique = @{}
-    foreach ($m in $matchList) {
-        $normalized = ($m.Value -replace '\\', '/').TrimEnd('/')
-        $unique[$normalized] = $true
-    }
-
-    $candidates = @(@($unique.Keys) | Sort-Object -Property Length -Descending)
-    return (Get-ParallelCohortBarrierFolderBasename -FolderPath $candidates[0])
+    return [string[]]@(Find-FeatureFolderCandidate -Text $Prompt)
 }
 
 function Get-ParallelCohortBarrierAllowDecision {
@@ -230,11 +228,13 @@ function Invoke-ParallelCohortBarrierDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_COHORT_BARRIER_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
-    # A failed worktree-resolution import denies before any other logic (issue #690).
+    # A failed dependency import denies before any other logic (issue #565).
     if ($script:ParallelCohortBarrierResolutionImportFailure) {
         return Get-ParallelCohortBarrierBlockDecision -Reason (
-            "PARALLEL_COHORT_BARRIER_BLOCKED: the worktree-resolution module '$($script:ParallelCohortBarrierResolutionImportFailure)' " +
+            "PARALLEL_COHORT_BARRIER_BLOCKED: the dependency '$($script:ParallelCohortBarrierResolutionImportFailure)' " +
             'failed to import, so the parallel checkpoint that governs this delegation cannot be located; the gate fails closed.')
     }
 
@@ -262,8 +262,8 @@ function Invoke-ParallelCohortBarrierDecision {
         return Get-ParallelCohortBarrierBlockDecision -Reason "PARALLEL_COHORT_BARRIER_BLOCKED: $($target.ReasonCode): $($target.Detail)"
     }
 
-    $featureFolder = Find-ParallelCohortBarrierFeatureFolderFromPrompt -Prompt $prompt
-    if (-not $featureFolder) {
+    $candidates = @(Find-ParallelCohortBarrierFeatureFolderFromPrompt -Prompt $prompt)
+    if ($candidates.Count -eq 0) {
         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.'
     }
 
@@ -277,6 +277,18 @@ function Invoke-ParallelCohortBarrierDecision {
         }
     }
 
+    # The target is selected among the cited candidates (issue #565). The canonical
+    # issue-number line breaks a tie only when it names exactly one number.
+    $records = if ($null -ne $checkpoint -and @($checkpoint.PSObject.Properties.Name) -contains 'items') { @($checkpoint.items) } else { @() }
+    $selectionArguments = @{ Records = $records; Candidate = $candidates }
+    $declared = Find-WorktreeItemIssueSignal -Text $prompt
+    if (@($declared).Count -eq 1) { $selectionArguments['DeclaredIssueNumber'] = [int]@($declared)[0] }
+    $selection = Select-FeatureFolderTarget @selectionArguments
+    if ($selection.Status -eq 'Ambiguous') {
+        return Get-ParallelCohortBarrierBlockDecision -Reason "PARALLEL_COHORT_BARRIER_BLOCKED: $($selection.Detail)."
+    }
+    $featureFolder = $selection.Basename
+
     $itemRecord = Find-ParallelCohortBarrierItemRecord -Checkpoint $checkpoint -FeatureFolder $featureFolder
     if (Test-ParallelCohortBarrierClear -Checkpoint $checkpoint -ItemRecord $itemRecord) {
         return Get-ParallelCohortBarrierAllowDecision
@@ -327,5 +339,8 @@ function Invoke-ParallelCohortBarrierEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PARALLEL_COHORT_BARRIER_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_COHORT_BARRIER_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 exit (Invoke-ParallelCohortBarrierEntryPoint)

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

@@ -8,13 +8,14 @@
     parallel-mode kickoff marker defined in the "Parallel-Mode Kickoff Parameter" section
     of .claude/skills/parallel-orchestrate/SKILL.md, matched byte-for-byte (ordinal).
 
-    Decision procedure: resolve the target item's feature folder from the prompt by scanning
-    for a docs/features/active/<token> path, the shape the parallel kickoff contract emits
-    for exactly this purpose (adapted from enforce-epic-wave-barrier.ps1's
-    Find-EpicWaveBarrierFeatureFolderFromPrompt: longest match wins, a .md-suffixed match
-    uses its parent directory); read the parallel checkpoint and locate the items[] record
-    whose feature_folder basename matches; derive which item keys have an unresolved latest
-    drift event; deny with PARALLEL_DRIFT_GATE_BLOCKED when the resolved item is one of them
+    Decision procedure: collect the cited feature-folder candidates with the shared resolver
+    (feature-folder-resolution.ps1, issue #565), which truncates every docs/features/active/
+    path to its feature-folder segment; read the parallel checkpoint and select the target
+    among the candidates with Select-FeatureFolderTarget, using the canonical issue-number
+    line as a tie-break when it names exactly one number and denying an unresolved tie as
+    ambiguous; locate the items[] record whose feature_folder basename matches the selected
+    basename, which is also the folder the finding probe inspects; derive which item keys
+    have an unresolved latest drift event; deny with PARALLEL_DRIFT_GATE_BLOCKED when the resolved item is one of them
     and no synthetic Blocking finding file dated at or after that item's latest drift event has
     been written. Allowed: a non-feature-review target, a prompt without the marker, a resolved
     latest event, and an unresolved event whose finding file is dated at or after it, so the
@@ -50,8 +51,10 @@
     ambiguous target denies after the subagent and marker filter and before the folder check.
 
 .NOTES
-    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
+    PowerShell 7+. Depends on WorktreeItemResolution.psm1 and WorktreeRunResolution.psm1
+    (issue #690) and the pure sibling feature-folder-resolution.ps1 (issue #565), each
+    loaded inside a guard: the first failure is recorded and the decision denies naming
+    the dependency. Both read
     boundaries -- the checkpoint read and the finding-file existence check -- are injectable
     wrapper functions, so tests mock them without writing temporary files.
 
@@ -65,23 +68,27 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 
-# Import guard (issue #690): a failed import denies instead of failing open.
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 $script:ParallelDriftGateResolutionImportFailure = $null
+
+# Shared feature-folder resolution (issue #565). Guarded so a failed dot-source denies
+# rather than failing open; an earlier recorded failure is kept.
 try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+    . (Join-Path $PSScriptRoot 'feature-folder-resolution.ps1')
 }
 catch {
-    $script:ParallelDriftGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+    if (-not $script:ParallelDriftGateResolutionImportFailure) { $script:ParallelDriftGateResolutionImportFailure = 'feature-folder-resolution.ps1' }
 }
 
 # 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
+try { . (Join-Path $PSScriptRoot 'enforce-parallel-drift-gate-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-parallel-drift-gate-helpers.ps1' -ErrorRecord $_ }
 
 $script:ParallelModeMarker = 'Parallel mode: true'
 $script:ReviewSubagentType = 'feature-review'
@@ -209,32 +216,16 @@ function Test-ParallelDriftFindingPresent {
 function Find-ParallelDriftGateFeatureFolderFromPrompt {
     <#
     .SYNOPSIS
-        Scan a delegation prompt for docs/features/active/<...> path tokens and return the
-        longest unique match's basename, or $null when none is found.
+        Return the distinct feature-folder basenames cited in a delegation prompt, in
+        first-occurrence order, through the shared Find-FeatureFolderCandidate (issue #565).
+        A nested research/ or evidence/ citation names its own folder. No output when no
+        folder is cited; selection among several is made by Select-FeatureFolderTarget.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([string[]])]
     param([Parameter(Mandatory)][AllowEmptyString()][string] $Prompt)
 
-    if (-not $Prompt) {
-        return $null
-    }
-    $matchList = [regex]::Matches($Prompt, 'docs[\\/]+features[\\/]+active[\\/]+[^\s"''`]+')
-    if ($matchList.Count -eq 0) {
-        return $null
-    }
-
-    # Collect distinct normalized tokens so the longest, most specific one can be selected.
-    $unique = @{}
-    foreach ($found in $matchList) {
-        $unique[($found.Value -replace '\\', '/').TrimEnd('/')] = $true
-    }
-
-    $best = @(@($unique.Keys) | Sort-Object -Property Length -Descending)[0]
-    if ($best -match '\.md$') {
-        $best = $best -replace '/[^/]+\.md$', ''
-    }
-    return ($best -split '/')[-1]
+    return [string[]]@(Find-FeatureFolderCandidate -Text $Prompt)
 }
 
 function Find-ParallelDriftGateItemRecord {
@@ -318,11 +309,13 @@ function Invoke-ParallelDriftGateDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_DRIFT_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
-    # A failed worktree-resolution import denies before any other logic (issue #690).
+    # A failed dependency import denies before any other logic (issue #565).
     if ($script:ParallelDriftGateResolutionImportFailure) {
         return Get-ParallelDriftGateBlockDecision -Reason (
-            "PARALLEL_DRIFT_GATE_BLOCKED: the worktree-resolution module '$($script:ParallelDriftGateResolutionImportFailure)' " +
+            "PARALLEL_DRIFT_GATE_BLOCKED: the dependency '$($script:ParallelDriftGateResolutionImportFailure)' " +
             'failed to import, so the parallel checkpoint that governs this review cannot be located; the gate fails closed.')
     }
 
@@ -352,8 +345,8 @@ function Invoke-ParallelDriftGateDecision {
         return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: $($target.ReasonCode): $($target.Detail)"
     }
 
-    $featureFolder = Find-ParallelDriftGateFeatureFolderFromPrompt -Prompt $prompt
-    if (-not $featureFolder) {
+    $candidates = @(Find-ParallelDriftGateFeatureFolderFromPrompt -Prompt $prompt)
+    if ($candidates.Count -eq 0) {
         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.'
     }
 
@@ -367,8 +360,19 @@ function Invoke-ParallelDriftGateDecision {
         }
     }
     if ($null -eq $checkpoint) {
-        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."
+        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 '$($candidates -join ', ')' cannot be verified."
+    }
+
+    # The target is selected among the cited candidates (issue #565). The canonical
+    # issue-number line breaks a tie only when it names exactly one number.
+    $selectionArguments = @{ Records = @($checkpoint.items | Where-Object { $null -ne $_ }); Candidate = $candidates }
+    $declared = Find-WorktreeItemIssueSignal -Text $prompt
+    if (@($declared).Count -eq 1) { $selectionArguments['DeclaredIssueNumber'] = [int]@($declared)[0] }
+    $selection = Select-FeatureFolderTarget @selectionArguments
+    if ($selection.Status -eq 'Ambiguous') {
+        return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: $($selection.Detail)."
     }
+    $featureFolder = $selection.Basename
 
     $item = Find-ParallelDriftGateItemRecord -Checkpoint $checkpoint -FeatureFolder $featureFolder
     if ($null -eq $item -or -not (Test-ParallelDriftGateItemKey -Value $item.issue_num)) {
@@ -440,5 +444,8 @@ function Invoke-ParallelDriftGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PARALLEL_DRIFT_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_DRIFT_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 exit (Invoke-ParallelDriftGateEntryPoint)