@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

package/resources/claude-customizations/.claude/hooks/enforce-mermaid-validation.ps1

@@ -56,10 +56,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 Set-StrictMode -Version Latest
 
-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 $_ }
 
 $script:MermaidModulePath = Join-Path -Path $PSScriptRoot -ChildPath '../lib/mermaid/MermaidValidation.psm1'
 $script:MermaidSkillPointer = 'See .claude/skills/mermaid-diagram/SKILL.md.'
@@ -303,6 +304,8 @@ function Invoke-MermaidValidationDecision {
         [AllowNull()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MERMAID_VALIDATION_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     # Envelope-level anomaly: fail closed. See the ENVELOPE VERSUS CONTENT note in
     # this file's header before changing this back to a silent allow.
@@ -394,6 +397,9 @@ function Invoke-MermaidValidationEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('MERMAID_VALIDATION_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MERMAID_VALIDATION_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 Invoke-MermaidValidationEntryPoint -ToolInputRaw (Read-ClaudeHookRawPayload)
 

package/resources/claude-customizations/.claude/hooks/enforce-model-routing-receipt.ps1

@@ -45,14 +45,15 @@
 #>
 [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 $_ }
 # Portable-identity resolution (issue #673). Unguarded and fail-closed on purpose: a gate
 # that cannot load its resolver must not degrade into the cwd-relative read it replaces.
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
 # Epic scope (issue #663): a delegation for the epic integration branch is gated against the epic checkpoint.
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'EpicScopeResolution.psm1' -ErrorRecord $_ }
 function Get-ModelRoutingCheckpoint {
     <#
     .SYNOPSIS
@@ -207,6 +208,8 @@ function Invoke-ModelRoutingReceiptDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_RECEIPT_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $allow = [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
 
@@ -287,6 +290,9 @@ function Invoke-ModelRoutingReceiptDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('MODEL_ROUTING_RECEIPT_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_RECEIPT_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $decision = Invoke-ModelRoutingReceiptDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
 

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

@@ -6,9 +6,9 @@
     Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds four groups of
     functions:
 
-    - 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
+    - The import guards for the worktree-resolution modules (issue #690). A failed import
+      is recorded in $script:HookDependencyFailures, and the gate's call to
+      Get-HookDependencyFailureDecision 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
@@ -31,44 +31,22 @@
 .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. Imports WorktreeItemResolution.psm1 and WorktreeRunResolution.psm1
-    before EpicScopeResolution.psm1, so the nested import inside EpicScopeResolution reuses
-    the same module instance. Mirrored byte-identically under
+    Get-OrchestrationDelegationCheckpointPath (modes file), the gate's allow and block
+    decision constructors, and, through the targets file this file dot-sources (issue #738),
+    Read-CommandLineSegment, Get-CommandLineGlobalOption, and Get-CommandLineInvocation
+    (loaded by the gate's dot-source of hook-command-invocation.ps1). 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 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
-
-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.')
-}
+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 $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'EpicScopeResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeReadiness.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'EpicScopeReadiness.psm1' -ErrorRecord $_ }
+# Per-segment target resolution for the epic-scope decision (issue #738).
+. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-targets.ps1')
 
 # 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
@@ -242,11 +220,13 @@ function Get-OrchestrationEpicScopeDecision {
     .SYNOPSIS
         Returns the epic-scope decision for an implementation-classified command or path, or $null.
     .DESCRIPTION
-        Resolves epic scope with worktree-HEAD matching and the command's -C selector. When
-        the call is not epic scope, returns $null so the caller's single-feature path runs
-        unchanged. In epic scope, returns an allow decision when the epic command-leg
-        readiness predicate passes, and otherwise a deny naming the epic checkpoint and the
-        failed conjunct.
+        Resolves the target of every command segment and path (issue #738) with
+        Get-OrchestrationCommandTarget, then the epic scope of the session root and of each
+        target with worktree-HEAD matching. When neither is epic scope, returns $null so the
+        caller's single-feature path runs unchanged. In epic scope, denies an unresolvable,
+        ambiguous, or out-of-scope target, and otherwise evaluates the epic command-leg
+        readiness predicate against every target: the first failure denies (the session-root
+        wording is unchanged), and no failure allows.
     .PARAMETER Command
         The Bash command line; empty for a path leg.
     .PARAMETER FilePath
@@ -265,15 +245,23 @@ function Get-OrchestrationEpicScopeDecision {
     if (-not $Command -and -not $FilePath) {
         return $null
     }
-    $selector = if ($Command) { Get-OrchestrationEpicScopeSelector -Command $Command } else { $null }
-    $scope = Resolve-EpicScopeCheckpoint -Text ([string]$Command) -SessionRoot (Get-Location).Path -WorktreeSelector $selector -MatchWorktreeHead
-    if (-not $scope.IsEpicScope) {
+    $epicScopeSessionRoot = (Get-Location).Path
+    $epicScopeText = [string]$Command
+    $targetResult = Get-OrchestrationCommandTarget -Command $epicScopeText -FilePath @($FilePath) -SessionRoot $epicScopeSessionRoot
+    $scopeResolver = {
+        param([string] $Selector)
+        Resolve-EpicScopeCheckpoint -Text $epicScopeText -SessionRoot $epicScopeSessionRoot -WorktreeSelector $Selector -MatchWorktreeHead
+    }
+    $verdict = Resolve-OrchestrationEpicTargetVerdict -SessionRoot $epicScopeSessionRoot -TargetResult $targetResult -ScopeResolver $scopeResolver
+    $outcome = Resolve-OrchestrationEpicTargetOutcome -Verdict $verdict -ReadinessFailure {
+        param($Scope)
+        Get-EpicCommandLegReadinessFailure -Checkpoint $Scope.Checkpoint -MergeInProgress $Scope.MergeInProgress
+    }
+    if ($outcome.Outcome -eq 'none') {
         return $null
     }
-
-    $failure = Get-EpicCommandLegReadinessFailure -Checkpoint $scope.Checkpoint -MergeInProgress $scope.MergeInProgress
-    if (-not $failure) {
-        return Get-OrchestrationPreimplementationGateAllowDecision
+    if ($outcome.Outcome -eq 'deny') {
+        return Get-OrchestrationPreimplementationGateBlockDecision -Reason $outcome.Reason
     }
-    return Get-OrchestrationPreimplementationGateBlockDecision -Reason ("PREIMPLEMENTATION_GATE_BLOCKED: this epic-scope operation was evaluated against $($scope.CheckpointPath), and the failed readiness predicate is '$failure'. Implementation operations in epic scope require that checkpoint to satisfy every readiness predicate, and a production path may be staged or edited only while a merge is in progress.")
+    return Get-OrchestrationPreimplementationGateAllowDecision
 }

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

@@ -9,6 +9,11 @@
     tree? Every parse ambiguity answers false, so the caller's pre-change deny is the
     fallback for every unmodeled form.
 
+    Shell-agnostic parsing (issue #735): the shell that executes a hooked command is
+    undetermined per command, so every shape whose meaning differs between a POSIX shell
+    and PowerShell denies - a backslash anywhere, and { } , ( ) @ outside quotes. Evidence:
+    research/research.2026-10-08T14-00.md (Q1) in the issue #732 feature folder.
+
     The normative contract is the D4 fail-closed rule table in
     docs/features/active/2026-08-24-preimplementation-gate-blocks-planner-integration-commits-539/spec.md.
     Rule-table row numbers are cited inline against the code that realizes them.
@@ -28,15 +33,15 @@ $script:OrchestrationBookkeepingTrees = @(
 )
 
 # Characters that make a command line statically unresolvable (D4 row 12, as narrowed by
-# issues #663 and #713): interpolation characters outside single quotes; outside-quote
-# characters (`<`, `>`, and the `#` comment introducer) outside any quote; and typographic
-# quotes (U+2018 to U+201E) anywhere, because a PowerShell host reads them as quotes.
+# issues #663, #713, #732, and #735): interpolation characters outside single quotes;
+# outside-quote characters (`<`, `>`, the `#` comment introducer, and the shell-divergent
+# `{ } , ( ) @`) outside any quote; and typographic quotes (U+2018 to U+201E) anywhere.
 $script:InterpolationCommandCharacters = [char[]]@('$', '`')
-$script:OutsideQuoteCommandCharacters = [char[]]@('>', '<', '#')
+$script:OutsideQuoteCommandCharacters = [char[]]@('>', '<', '#', '{', '}', ',', '(', ')', '@')
 $script:TypographicQuoteCharacters = [char[]]@(0x2018, 0x2019, 0x201A, 0x201B, 0x201C, 0x201D, 0x201E)
 
-# Wildcards that make an operand a glob (D4 row 15). Only the literal prefix before the
-# first of these is prefix-tested.
+# Wildcards a selector value may not carry (LACS L6). An operand carrying one fails the
+# operand allowlist (issue #732).
 $script:PathspecWildcardCharacters = [char[]]@('*', '?', '[')
 
 # The single repository selector modelled between the command name and the subcommand: D4
@@ -112,12 +117,12 @@ function Test-OrchestrationCommandTextUnresolvable {
     .SYNOPSIS
         Reports whether a command line carries a statically unresolvable character.
     .DESCRIPTION
-        Realizes D4 row 12 as narrowed by issues #663 and #713, with quote state tracked as in
-        Split-OrchestrationCommandLine. `$` or backtick answers true outside quotes or inside
-        double quotes (single quotes keep it literal); `<`, `>`, or a `#` comment answers true
-        only outside a quoted span. A typographic quote (U+2018 to U+201E), a backslash before
-        any quote character, or a backslash inside a double-quoted span answers true anywhere:
-        a shell may end the span where this scan does not (fail closed).
+        Realizes D4 row 12 as narrowed by issues #663, #713, #732, and #735, with quote state
+        tracked as in Split-OrchestrationCommandLine. `$` or backtick answers true outside
+        quotes or inside double quotes (single quotes keep it literal); `<`, `>`, `#`, and
+        `{ } , ( ) @` answer true only outside a quoted span. A typographic quote (U+2018 to
+        U+201E) or a backslash answers true anywhere, because POSIX shells and PowerShell read
+        them differently and the executing shell is undetermined (fail closed).
     .PARAMETER CommandText
         The full command line as the shell would receive it.
     .OUTPUTS
@@ -127,8 +132,8 @@ function Test-OrchestrationCommandTextUnresolvable {
     [OutputType([bool])]
     param([Parameter(Mandatory)][AllowEmptyString()][string] $CommandText)
 
-    # An escaped or typographic quote moves a span boundary the scan cannot model (#663, #713).
-    if ($CommandText.Contains('\"') -or $CommandText.Contains("\'") -or $CommandText.IndexOfAny($script:TypographicQuoteCharacters) -ge 0) {
+    # A backslash or typographic quote is read differently by POSIX shells and PowerShell (#735).
+    if ($CommandText.Contains('\') -or $CommandText.IndexOfAny($script:TypographicQuoteCharacters) -ge 0) {
         return $true
     }
 
@@ -141,13 +146,9 @@ function Test-OrchestrationCommandTextUnresolvable {
             return $true
         }
 
-        # Decide by quote state: inside a span only the closing quote matters, and any
-        # backslash inside a double-quoted span is an unmodelled escape; outside a span a
-        # quote opens one and a redirection character is unresolvable.
+        # Decide by quote state: inside a span only the closing quote matters; outside a
+        # span a quote opens one and an outside-quote character is unresolvable.
         if ($openQuote -ne [char]0) {
-            if ($openQuote -eq '"' -and $character -eq '\') {
-                return $true
-            }
             if ($character -eq $openQuote) {
                 $openQuote = [char]0
             }
@@ -222,9 +223,10 @@ function Test-ExemptOrchestrationOperand {
     .SYNOPSIS
         Tests one pathspec operand against the five exempt orchestration trees.
     .DESCRIPTION
-        Realizes D4 rows 3, 9, 15, 16, 17, and 18. Backslashes normalize to forward slashes
-        before the prefix test (row 18); pathspec magic, absolute spellings, parent-directory
-        segments, and globs whose literal prefix escapes the exempt set all deny.
+        Realizes D4 rows 3, 9, 15, 16, and 17 as narrowed by issues #732 and #735. An operand
+        is exempt only when it matches the plain ASCII allowlist A-Z a-z 0-9 . _ / - (which
+        excludes pathspec magic, drive letters, backslashes, globs, braces, and non-ASCII
+        look-alikes), is not rooted, carries no '..' segment, and starts with an exempt tree.
     .OUTPUTS
         System.Boolean
     #>
@@ -232,43 +234,14 @@ function Test-ExemptOrchestrationOperand {
     [OutputType([bool])]
     param([Parameter(Mandatory)][AllowEmptyString()][string] $Operand)
 
-    if (-not $Operand) {
-        return $false
-    }
-
-    # Row 3b and row 9: any leading colon is pathspec magic, which can escape or invert the
-    # tree scope, so no colon-led operand is ever resolvable by a prefix test.
-    if ($Operand.StartsWith(':')) {
+    if ($Operand -cnotmatch '^[A-Za-z0-9._/-]+$' -or $Operand.StartsWith('/')) {
         return $false
     }
-
-    # Row 18: separator normalization precedes every prefix comparison below.
-    $normalized = $Operand -replace '\\', '/'
-
-    # Row 16: rooted, drive-lettered, and UNC spellings all deny; the exempt prefixes stay
-    # repo-relative (this is the posture issue #516 later composes with).
-    if ($normalized.StartsWith('/')) {
+    if (($Operand -split '/') -contains '..') {
         return $false
     }
-    if ($normalized -match '^[A-Za-z]:') {
-        return $false
-    }
-
-    # Rows 15c and 17: any parent-directory component escapes the prefix.
-    if (($normalized -split '/') -contains '..') {
-        return $false
-    }
-
-    # Row 15: only the literal prefix before the first wildcard is prefix-tested, so a glob
-    # whose wildcard occupies or truncates an ancestor segment cannot pass.
-    $literalPrefix = $normalized
-    $wildcardIndex = $normalized.IndexOfAny($script:PathspecWildcardCharacters)
-    if ($wildcardIndex -ge 0) {
-        $literalPrefix = $normalized.Substring(0, $wildcardIndex)
-    }
-
     foreach ($tree in $script:OrchestrationBookkeepingTrees) {
-        if ($literalPrefix.StartsWith($tree)) {
+        if ($Operand.StartsWith($tree)) {
             return $true
         }
     }
@@ -444,7 +417,7 @@ function Test-ExemptOrchestrationStagingCommand {
         command line splits cleanly into segments and EVERY segment parses as a complete,
         recognized staging or integration invocation carrying at least one pathspec operand,
         with every operand resolving inside one of the five exempt orchestration-bookkeeping
-        trees after balanced-quote stripping and separator normalization.
+        trees after balanced-quote stripping.
 
         The all-segments reading is deliberate and fail-closed: a chained line denies unless
         each of its segments is independently a recognized all-exempt invocation, so a
@@ -464,8 +437,8 @@ function Test-ExemptOrchestrationStagingCommand {
         return $false
     }
 
-    # Row 12: `$` or backtick outside single quotes, `<`, `>`, or `#` outside quotes, any
-    # typographic quote, and unmodelled backslash escapes make the operand list untrustworthy.
+    # Row 12: `$` or backtick outside single quotes, `< > # { } , ( ) @` outside quotes, and
+    # any typographic quote or backslash make the operand list untrustworthy (#732, #735).
     if (Test-OrchestrationCommandTextUnresolvable -CommandText $CommandText) {
         return $false
     }

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

@@ -17,16 +17,30 @@
 
     PURITY. This file is pure string and object logic, with no filesystem,
     process, network, or environment access: it opens no file, probes no path,
-    issues no web request, launches no executable, and imports no module. Every
-    readiness predicate accepts an ALREADY-PARSED checkpoint object, or $null; the
-    per-mode read seams live in the main gate hook. It is a new sibling rather than
-    an addition to the issue #539 helpers file, whose header declares a different
-    normative contract and which lacks headroom under the 500-line cap; leaving
-    that file byte-untouched is the proof the #539 exemption is unchanged.
+    issues no web request, launches no executable, and imports no module. It
+    dot-sources one pure sibling, feature-folder-resolution.ps1 (issue #565),
+    inside a guard: a failure sets a modes-local flag, and the target finder and
+    the readiness predicates then fail closed. Every readiness predicate accepts
+    an ALREADY-PARSED checkpoint object, or $null; the per-mode read seams live
+    in the main gate hook. It is a new sibling rather than an addition to the
+    issue #539 helpers file, whose header declares a different normative
+    contract and which lacks headroom under the 500-line cap; leaving that file
+    byte-untouched is the proof the #539 exemption is unchanged.
 #>
 [CmdletBinding()]
 param()
 
+# Shared pure feature-folder resolution (issue #565). Guarded: a failed dot-source
+# sets the modes-local flag, so the target finder returns nothing and the readiness
+# predicates name feature-folder-resolution-import instead of failing open.
+$script:OrchestrationFeatureFolderResolutionImportFailure = $null
+try {
+    . (Join-Path $PSScriptRoot 'feature-folder-resolution.ps1')
+}
+catch {
+    $script:OrchestrationFeatureFolderResolutionImportFailure = 'feature-folder-resolution.ps1'
+}
+
 # --- Constant table 1: the fixed mode table --------------------------------------
 # Markers are reused verbatim from shipped contracts and hooks; do not invent them.
 # The trailing-period asymmetry is deliberate: preparation markers are matched WITH
@@ -215,39 +229,18 @@ function Test-OrchestrationImplementationAgent {
 function Find-OrchestrationDelegationTargetFolder {
     <#
     .SYNOPSIS
-        Resolves the target feature-folder basename out of a delegation prompt,
-        reusing the wave-barrier technique in shape: scan for slash-separated
-        docs/features/active/ tokens, longest unique match wins, a Markdown match
-        resolves to its parent, and the basename is returned. $null when no token
-        resolves, which the caller treats as a deny.
+        Returns 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 or the shared resolver failed to load; the
+        readiness predicates select among several candidates.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([string[]])]
     param([AllowNull()][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 = [ordered]@{}
-    foreach ($item in $matchList) { $unique[$item.Value] = $true }
-    $candidates = @(@($unique.Keys) | Sort-Object -Property Length -Descending)
-    $best = [string]$candidates[0]
-
-    # Sentence punctuation trails a bare path token in every shipped kickoff
-    # contract. A trailing period is stripped only when it does not form the
-    # Markdown extension the next branch depends on.
-    $best = $best.TrimEnd(',', ';', ':')
-    while ($best.EndsWith('.') -and -not $best.EndsWith('.md')) {
-        $best = $best.Substring(0, $best.Length - 1)
-    }
-    if ($best -match '\.md$') { $best = $best -replace '[\\/][^\\/]+\.md$', '' }
-
-    $basename = Get-OrchestrationModeFolderBasename -Path $best
-    if (-not $basename) { return $null }
-    return $basename
+    if ($script:OrchestrationFeatureFolderResolutionImportFailure) { return }
+    return [string[]]@(Find-FeatureFolderCandidate -Text $Prompt)
 }
 
 function Find-OrchestrationDelegationIssueNumber {
@@ -259,16 +252,19 @@ function Find-OrchestrationDelegationIssueNumber {
         form; $null when neither resolves. Accepted widening: a bare hash form such
         as a pull-request reference can supply a number that is not the target's,
         which widens the SEARCH only - an unmatched number yields no record and
-        denies, so deny-by-default is preserved.
+        denies, so deny-by-default is preserved. -KeyedOnly returns the keyed form
+        or $null and never the bare hash form: the readiness tie-break among cited
+        candidates consumes only that value (issue #565, spec R4 and R6).
     #>
     [CmdletBinding()]
     [OutputType([string])]
-    param([AllowNull()][AllowEmptyString()][string] $Prompt)
+    param([AllowNull()][AllowEmptyString()][string] $Prompt, [switch] $KeyedOnly)
 
     if (-not $Prompt) { return $null }
 
     $keyed = [regex]::Match($Prompt, 'issue(?:[_-]?num(?:ber)?|\s+number)\s*[:=]\s*#?(\d+)', 'IgnoreCase')
     if ($keyed.Success) { return $keyed.Groups[1].Value }
+    if ($KeyedOnly) { return $null }
     $hashForm = [regex]::Match($Prompt, '(?:^|\s)#(\d+)\b')
     if ($hashForm.Success) { return $hashForm.Groups[1].Value }
     return $null
@@ -374,14 +370,18 @@ function Get-EpicOrchestrationReadinessFailure {
         merged nor worktree_removed. The epic_manifest_path conjunct deliberately
         tightens relative to validate_epic_orchestrator_state.py, whose
         required-key set omits it, but is not stricter than the producing skill's
-        contract, which mandates it; a false deny names the failed conjunct.
+        contract, which mandates it; a false deny names the failed conjunct. The
+        target is selected among the cited folders with dependency pruning (issue
+        #565); an unresolved tie fails as target-ambiguous.
+        Only the keyed -IssueNumber breaks a tie; -FallbackIssueNumber feeds D3 only.
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
         [Parameter(Mandatory)][AllowNull()] $Checkpoint,
-        [AllowNull()][AllowEmptyString()][string] $TargetFolder,
-        [AllowNull()][AllowEmptyString()][string] $IssueNumber
+        [AllowNull()][AllowEmptyCollection()][AllowEmptyString()][string[]] $TargetFolder,
+        [AllowNull()][AllowEmptyString()][string] $IssueNumber,
+        [AllowNull()][AllowEmptyString()][string] $FallbackIssueNumber
     )
 
     if ($null -eq $Checkpoint) { return 'checkpoint-absent' }
@@ -400,7 +400,13 @@ function Get-EpicOrchestrationReadinessFailure {
     }
     $features = Get-OrchestrationModeCollection -Value $Checkpoint -Name 'features'
     if ($features.Count -eq 0) { return 'features' }
-    $record = Find-OrchestrationModeRecord -Records $features -TargetFolder $TargetFolder -IssueNumber $IssueNumber
+    if ($script:OrchestrationFeatureFolderResolutionImportFailure) { return 'feature-folder-resolution-import' }
+    $selectionArguments = @{ Records = $features; Candidate = @($TargetFolder | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }); DependencyAware = $true }
+    $declared = 0
+    if ($IssueNumber -match '^\d+$' -and [int]::TryParse($IssueNumber, [ref]$declared)) { $selectionArguments['DeclaredIssueNumber'] = $declared }
+    $selection = Select-FeatureFolderTarget @selectionArguments
+    if ($selection.Status -eq 'Ambiguous') { return 'target-ambiguous: ' + ($selection.Remaining -join ', ') }
+    $record = Find-OrchestrationModeRecord -Records $features -TargetFolder $selection.Basename -IssueNumber $(if ($IssueNumber -or @($selection.Remaining).Count -gt 0) { $IssueNumber } else { $FallbackIssueNumber })
     if ($null -eq $record) { return 'target-record' }
     if (Test-OrchestrationModeTerminalMergeStatus -Record $record) { return 'merge_status' }
     return ''
@@ -415,7 +421,7 @@ function Test-EpicOrchestrationReady {
     [OutputType([bool])]
     param(
         [Parameter(Mandatory)][AllowNull()] $Checkpoint,
-        [AllowNull()][AllowEmptyString()][string] $TargetFolder,
+        [AllowNull()][AllowEmptyCollection()][AllowEmptyString()][string[]] $TargetFolder,
         [AllowNull()][AllowEmptyString()][string] $IssueNumber
     )
 
@@ -433,14 +439,18 @@ function Get-ParallelOrchestrationReadinessFailure {
         parallel_manifest_path; present and non-empty items; the resolved target
         present as a record in items; and that record's merge_status neither merged
         nor worktree_removed. It consumes the parallel item-state and merge-status
-        member sets and adds no member to either.
+        member sets and adds no member to either. The target is selected among the
+        cited folders, with the issue number as a tie-break (issue #565); an
+        unresolved tie fails as target-ambiguous.
+        Only the keyed -IssueNumber breaks a tie; -FallbackIssueNumber feeds D3 only.
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
         [Parameter(Mandatory)][AllowNull()] $Checkpoint,
-        [AllowNull()][AllowEmptyString()][string] $TargetFolder,
-        [AllowNull()][AllowEmptyString()][string] $IssueNumber
+        [AllowNull()][AllowEmptyCollection()][AllowEmptyString()][string[]] $TargetFolder,
+        [AllowNull()][AllowEmptyString()][string] $IssueNumber,
+        [AllowNull()][AllowEmptyString()][string] $FallbackIssueNumber
     )
 
     if ($null -eq $Checkpoint) { return 'checkpoint-absent' }
@@ -455,7 +465,13 @@ function Get-ParallelOrchestrationReadinessFailure {
     }
     $items = Get-OrchestrationModeCollection -Value $Checkpoint -Name 'items'
     if ($items.Count -eq 0) { return 'items' }
-    $record = Find-OrchestrationModeRecord -Records $items -TargetFolder $TargetFolder -IssueNumber $IssueNumber
+    if ($script:OrchestrationFeatureFolderResolutionImportFailure) { return 'feature-folder-resolution-import' }
+    $selectionArguments = @{ Records = $items; Candidate = @($TargetFolder | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }) }
+    $declared = 0
+    if ($IssueNumber -match '^\d+$' -and [int]::TryParse($IssueNumber, [ref]$declared)) { $selectionArguments['DeclaredIssueNumber'] = $declared }
+    $selection = Select-FeatureFolderTarget @selectionArguments
+    if ($selection.Status -eq 'Ambiguous') { return 'target-ambiguous: ' + ($selection.Remaining -join ', ') }
+    $record = Find-OrchestrationModeRecord -Records $items -TargetFolder $selection.Basename -IssueNumber $(if ($IssueNumber -or @($selection.Remaining).Count -gt 0) { $IssueNumber } else { $FallbackIssueNumber })
     if ($null -eq $record) { return 'target-record' }
     if (Test-OrchestrationModeTerminalMergeStatus -Record $record) { return 'merge_status' }
     return ''
@@ -470,7 +486,7 @@ function Test-ParallelOrchestrationReady {
     [OutputType([bool])]
     param(
         [Parameter(Mandatory)][AllowNull()] $Checkpoint,
-        [AllowNull()][AllowEmptyString()][string] $TargetFolder,
+        [AllowNull()][AllowEmptyCollection()][AllowEmptyString()][string[]] $TargetFolder,
         [AllowNull()][AllowEmptyString()][string] $IssueNumber
     )