@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

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

@@ -6,53 +6,36 @@
     Dot-sourced by enforce-epic-merge-gate.ps1 immediately after the authorization sibling.
     Holds:
 
-    - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
-      $script:EpicMergeGateResolutionImportFailure, and
-      Get-EpicMergeGateImportFailureDecision turns it into a deny, so a missing module
+    - The import guards for WorktreeRunResolution.psm1 and, after it,
+      WorktreeItemResolution.psm1 (issue #850). A failed import is recorded in
+      $script:HookDependencyFailures, and the gate's call to
+      Get-HookDependencyFailureDecision turns it into a deny, so a missing module
       cannot make the gate exit non-zero and fail open.
     - The three checkpoint read seams, relocated from the gate file with their names kept.
       Each takes a mandatory absolute path composed beneath a resolved worktree root.
-    - The session worktree root, used for the child branch and for a bare command.
+    - The session worktree root, used for a bare command.
     - The resolution seam Resolve-EpicMergeGateRunTarget, which locates the epic or
       parallel checkpoint that records the command's pull request number.
+    - The item seam Resolve-EpicMergeGateItemTarget (issue #850), which locates the live
+      worktree whose per-feature checkpoint records the command's pull request number in
+      pr_gate.pr_number or a standalone_merge_authorizations entry.
     - Test-ChildCheckpointPrGateBinding, which binds the command's pull request number to
-      the per-feature checkpoint's pr_gate.pr_number when that field is recorded.
-    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither run branch
-      resolves.
+      the per-feature checkpoint: pr_gate.pr_number must equal it when recorded, and
+      otherwise a positive-integer standalone record must name it (issue #788).
+    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither the item
+      target nor either run branch resolves.
+    - Test-EpicMergeGateNoRecordingTarget, the precondition of the docs-only merge branch:
+      the item, epic, and parallel targets all resolve NoTarget (issue #927).
 
 .NOTES
-    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision from the authorization
-    sibling, dot-sourced by the gate before this file. Mirrored byte-identically under
+    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision and
+    Test-StandalonePositiveJsonInteger from the authorization sibling, dot-sourced by the
+    gate before this file. Mirrored byte-identically under
     extensions/drm-copilot/resources/claude-customizations/.
 #>
 
-# Import guard (issue #690): a failed import denies instead of failing open.
-$script:EpicMergeGateResolutionImportFailure = $null
-try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
-}
-catch {
-    $script:EpicMergeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
-}
-
-function Get-EpicMergeGateImportFailureDecision {
-    <#
-    .SYNOPSIS
-        Returns the deny for a failed worktree-resolution import, or $null.
-    .OUTPUTS
-        System.Collections.Specialized.OrderedDictionary, or $null when the import succeeded.
-    #>
-    [CmdletBinding()]
-    [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param()
-
-    if (-not $script:EpicMergeGateResolutionImportFailure) {
-        return $null
-    }
-    return Get-EpicMergeGateBlockDecision -Reason (
-        "EPIC_MERGE_GATE_BLOCKED: the worktree-resolution module '$($script:EpicMergeGateResolutionImportFailure)' " +
-        'failed to import, so the run checkpoint that governs this merge cannot be located; the gate fails closed.')
-}
+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/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
 
 function Get-ChildOrchestratorCheckpointContent {
     <#
@@ -60,7 +43,7 @@ function Get-ChildOrchestratorCheckpointContent {
         Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
         this function (read seam).
     .PARAMETER Path
-        The absolute checkpoint path composed beneath the session worktree root.
+        The absolute checkpoint path composed beneath the item or session worktree root.
     .OUTPUTS
         System.String or $null
     #>
@@ -117,7 +100,7 @@ function Get-ParallelOrchestratorCheckpointContent {
 function Get-EpicMergeGateSessionWorktreeRoot {
     <#
     .SYNOPSIS
-        Return the worktree root the session runs in (the child branch and bare-command root).
+        Return the worktree root the session runs in (the bare-command root).
     .OUTPUTS
         System.String
     #>
@@ -149,14 +132,35 @@ function Resolve-EpicMergeGateRunTarget {
     return Resolve-WorktreeRunTargetByRecord -Kind $Kind -RecordField pr_number -Value ([string]$PrNumber) -SessionRoot (Get-Location).Path
 }
 
+function Resolve-EpicMergeGateItemTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose per-feature checkpoint records a pull request number (issue #850 seam).
+    .PARAMETER PrNumber
+        The explicit pull request number the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][int] $PrNumber
+    )
+
+    return Resolve-WorktreeItemTargetByPrNumber -PrNumber $PrNumber -SessionRoot (Get-Location).Path
+}
+
 function Test-ChildCheckpointPrGateBinding {
     <#
     .SYNOPSIS
-        True unless the per-feature checkpoint records a pr_gate.pr_number that differs from the command's.
+        True when the per-feature checkpoint binds the command's pull request number (issue #788).
     .DESCRIPTION
-        A bare command, an absent checkpoint, and a checkpoint without pr_gate.pr_number
-        keep today's unbound child-branch decision. When both numbers are present they must
-        parse as integers and be equal.
+        Pure. A bare command is unbound and returns $true. An explicit number requires a
+        checkpoint: when it records pr_gate.pr_number, that value must parse as an integer
+        equal to the number; otherwise a standalone_merge_authorizations entry whose
+        pr_number is a positive JSON integer equal to the number must exist. Every other
+        case returns $false, so a checkpoint that names neither field cannot authorize an
+        explicit-number merge through the child branch.
     .PARAMETER Checkpoint
         Parsed per-feature checkpoint, or $null.
     .PARAMETER CommandPrNumber
@@ -171,30 +175,45 @@ function Test-ChildCheckpointPrGateBinding {
         [AllowNull()][Nullable[int]] $CommandPrNumber
     )
 
-    if ($null -eq $CommandPrNumber -or $null -eq $Checkpoint) {
+    if ($null -eq $CommandPrNumber) {
         return $true
     }
-    if (@($Checkpoint.PSObject.Properties.Name) -notcontains 'pr_gate' -or $null -eq $Checkpoint.pr_gate) {
-        return $true
+    if ($null -eq $Checkpoint) {
+        return $false
     }
-    $prGate = $Checkpoint.pr_gate
-    if (@($prGate.PSObject.Properties.Name) -notcontains 'pr_number' -or $null -eq $prGate.pr_number) {
-        return $true
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    if ($props -contains 'pr_gate' -and $null -ne $Checkpoint.pr_gate -and
+        @($Checkpoint.pr_gate.PSObject.Properties.Name) -contains 'pr_number' -and $null -ne $Checkpoint.pr_gate.pr_number) {
+        $recorded = 0
+        if (-not [int]::TryParse([string]$Checkpoint.pr_gate.pr_number, [ref] $recorded)) {
+            return $false
+        }
+        return ($recorded -eq $CommandPrNumber)
     }
-    $recorded = 0
-    if (-not [int]::TryParse([string]$prGate.pr_number, [ref] $recorded)) {
+    if ($props -notcontains 'standalone_merge_authorizations') {
         return $false
     }
-    return ($recorded -eq $CommandPrNumber)
+    foreach ($entry in @($Checkpoint.standalone_merge_authorizations)) {
+        if ($null -eq $entry -or @($entry.PSObject.Properties.Name) -notcontains 'pr_number') {
+            continue
+        }
+        if ((Test-StandalonePositiveJsonInteger -Value $entry.pr_number) -and [long]$entry.pr_number -eq $CommandPrNumber) {
+            return $true
+        }
+    }
+    return $false
 }
 
 function Get-EpicMergeGateUnresolvedReason {
     <#
     .SYNOPSIS
-        Returns '<code>: <epic detail>; <parallel detail>' when neither run branch resolved, or $null.
+        Returns '<code>: <item detail>; <epic detail>; <parallel detail>' when no target resolved, or $null.
     .DESCRIPTION
-        The ambiguity code wins when either target is Ambiguous. Returns $null when either
-        target is absent (a bare command) or either target resolved.
+        The ambiguity code of the first Ambiguous target among item, epic, and parallel
+        wins; otherwise the item target's code is used. Returns $null when any target is
+        absent (a bare command) or any target resolved.
+    .PARAMETER ItemTarget
+        The item target, or $null.
     .PARAMETER EpicTarget
         The epic run target, or $null.
     .PARAMETER ParallelTarget
@@ -205,17 +224,55 @@ function Get-EpicMergeGateUnresolvedReason {
     [CmdletBinding()]
     [OutputType([string])]
     param(
+        [AllowNull()] $ItemTarget,
         [AllowNull()] $EpicTarget,
         [AllowNull()] $ParallelTarget
     )
 
-    if ($null -eq $EpicTarget -or $null -eq $ParallelTarget) {
+    if ($null -eq $ItemTarget -or $null -eq $EpicTarget -or $null -eq $ParallelTarget) {
         return $null
     }
+    $targets = @($ItemTarget, $EpicTarget, $ParallelTarget)
     $unresolved = @('NoTarget', 'Ambiguous')
-    if ($unresolved -notcontains $EpicTarget.Status -or $unresolved -notcontains $ParallelTarget.Status) {
-        return $null
+    foreach ($target in $targets) {
+        if ($unresolved -notcontains $target.Status) {
+            return $null
+        }
+    }
+    $ambiguous = @($targets | Where-Object { $_.Status -eq 'Ambiguous' })
+    $code = if ($ambiguous.Count -gt 0) { $ambiguous[0].ReasonCode } else { $ItemTarget.ReasonCode }
+    return ('{0}: {1}; {2}; {3}' -f $code, $ItemTarget.Detail, $EpicTarget.Detail, $ParallelTarget.Detail)
+}
+
+function Test-EpicMergeGateNoRecordingTarget {
+    <#
+    .SYNOPSIS
+        True only when the item, epic, and parallel targets all have status NoTarget (issue #927).
+    .DESCRIPTION
+        Pure. That combination means no checkpoint records the command's pull request number,
+        which is the only case the docs-only merge branch evaluates. A $null target (a bare
+        command), an Ambiguous target, and any resolved target return $false.
+    .PARAMETER ItemTarget
+        The item target, or $null.
+    .PARAMETER EpicTarget
+        The epic run target, or $null.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $ItemTarget,
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget
+    )
+
+    foreach ($target in @($ItemTarget, $EpicTarget, $ParallelTarget)) {
+        if ($null -eq $target -or [string]$target.Status -cne 'NoTarget') {
+            return $false
+        }
     }
-    $code = if ($EpicTarget.Status -eq 'Ambiguous') { $EpicTarget.ReasonCode } elseif ($ParallelTarget.Status -eq 'Ambiguous') { $ParallelTarget.ReasonCode } else { $EpicTarget.ReasonCode }
-    return ('{0}: {1}; {2}' -f $code, $EpicTarget.Detail, $ParallelTarget.Detail)
+    return $true
 }

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

@@ -33,15 +33,25 @@
     PR number never satisfies condition 4, and a blanket flag is rejected rather than read.
     Trigger scope: --squash is out of scope for this gate and is allowed on both runtimes.
 
-    Design decision: this gate trusts the on-disk checkpoint rather than shelling out live
-    to gh pr view for a real-time head-SHA check, matching the same non-adversarial,
-    policy-level-not-cryptographic posture already accepted for
-    enforce-pr-author-skill.ps1's own receipt mechanism. It is not a cryptographic control.
+    Design decision: branches 1-4 trust the on-disk checkpoint and never call gh. Issue #927
+    adds a docs-only branch after branch 4 fails, only for an explicit PR number whose item,
+    epic, and parallel targets are all NoTarget (no checkpoint records the PR): it calls
+    Get-DocsOnlyMergeExemption (hook-docs-only-diff.ps1), which runs gh pr view and git in the
+    session worktree and allows the merge when conditions M1-M9 of that file hold. Otherwise
+    the deny gains " (docs-only exemption not applied: <Reason>)", where the reason may be
+    DOCS_ONLY_EXEMPTION_PR_UNRESOLVED. The hook never fetches; --match-head-commit, when
+    present, must equal headRefOid (OD-2). Residual limits: an ambient GH_REPO or GH_HOST is
+    not visible in the command text; gh and git run in the session worktree root, so a cd
+    made by an earlier Bash call is not visible either; and a push after the lookup can
+    change the head unless --match-head-commit is passed. Like the receipt mechanism of
+    enforce-pr-author-skill.ps1, this is a policy-level control, not a cryptographic one.
 
     Issue #690: with an explicit PR number, the epic and parallel checkpoints are read
-    beneath the live worktree whose run checkpoint records that number, and the child
-    branch binds the number to pr_gate.pr_number when the per-feature checkpoint records
-    it. A bare command reads every checkpoint beneath the session worktree.
+    beneath the live worktree whose run checkpoint records that number. Issue #850: with
+    an explicit PR number, the per-feature checkpoint is read beneath the live worktree
+    whose checkpoint records the number in pr_gate.pr_number or a standalone record, and
+    the child branch requires that checkpoint to bind the number (issue #788). A bare
+    command reads every checkpoint beneath the session worktree.
 
 .NOTES
     Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 through the
@@ -57,16 +67,19 @@
 #>
 [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 $_ }
 # Shared command-line parser (issue #545), consumed by the scope filter in
 # Invoke-EpicMergeGateDecision and by Get-EpicMergeGateCommandPrNumber.
-. (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 $_ }
 # Standalone-merge authorization predicates and the two decision-envelope factories (issue #670).
-. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-authorization.ps1' -ErrorRecord $_ }
 # Checkpoint read seams, the import guard, and run-target resolution (issue #690).
-. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-resolution.ps1' -ErrorRecord $_ }
+# Shared docs-only diff classification and the merge-side docs-only exemption (issue #927).
+try { . (Join-Path $PSScriptRoot 'hook-docs-only-diff.ps1') } catch { Add-HookDependencyFailure -Name 'hook-docs-only-diff.ps1' -ErrorRecord $_ }
 
 function ConvertFrom-EpicMergeGateJson {
     <#
@@ -312,10 +325,8 @@ function Invoke-EpicMergeGateDecision {
     )
 
     # A failed worktree-resolution import denies before any other logic (issue #690).
-    $importFailure = Get-EpicMergeGateImportFailureDecision
-    if ($null -ne $importFailure) {
-        return $importFailure
-    }
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_MERGE_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -357,9 +368,17 @@ function Invoke-EpicMergeGateDecision {
     $commandPrNumber = Get-EpicMergeGateCommandPrNumber -CommandText $commandText
     $sessionRoot = Get-EpicMergeGateSessionWorktreeRoot
 
-    # The child merges from its own worktree, so its checkpoint is the session worktree's;
-    # a recorded pr_gate.pr_number must match an explicit command PR number (issue #690).
-    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $sessionRoot))
+    # With an explicit PR number, the per-feature checkpoint is read beneath the live
+    # worktree whose checkpoint records the number in pr_gate.pr_number or a standalone
+    # record (issue #850); an unresolved item target reads none. A bare command reads the
+    # session worktree. The checkpoint read must still bind the number (issue #788).
+    $itemTarget = $null
+    $childRoot = $sessionRoot
+    if ($null -ne $commandPrNumber) {
+        $itemTarget = Resolve-EpicMergeGateItemTarget -PrNumber $commandPrNumber
+        $childRoot = if (@('SessionRoot', 'OtherWorktree') -contains $itemTarget.Status) { $itemTarget.WorktreeRoot } else { $null }
+    }
+    $childCheckpoint = if ($childRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $childRoot)) } else { $null }
     if ((Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) -and
         (Test-ChildCheckpointPrGateBinding -Checkpoint $childCheckpoint -CommandPrNumber $commandPrNumber)) {
         return Get-EpicMergeGateAllowDecision
@@ -396,10 +415,20 @@ function Invoke-EpicMergeGateDecision {
         if ($standalone.Allowed) {
             return Get-EpicMergeGateAllowDecision
         }
-        # When neither run branch resolved, its reason code and detail precede the standalone reason.
-        $unresolved = Get-EpicMergeGateUnresolvedReason -EpicTarget $epicTarget -ParallelTarget $parallelTarget
+        # Docs-only branch (issue #927): evaluated only when no checkpoint records the PR.
+        $docsOnlySuffix = ''
+        if (Test-EpicMergeGateNoRecordingTarget -ItemTarget $itemTarget -EpicTarget $epicTarget -ParallelTarget $parallelTarget) {
+            $docsOnly = Get-DocsOnlyMergeExemption -CommandText $commandText -PrNumber $commandPrNumber -WorktreeRoot $sessionRoot
+            if ($docsOnly.Exempt) {
+                return Get-EpicMergeGateAllowDecision
+            }
+            $docsOnlySuffix = ' (docs-only exemption not applied: ' + $docsOnly.Reason + ')'
+        }
+        # When neither the item target nor a run branch resolved, the reason code and the
+        # three details precede the standalone reason (issue #850).
+        $unresolved = Get-EpicMergeGateUnresolvedReason -ItemTarget $itemTarget -EpicTarget $epicTarget -ParallelTarget $parallelTarget
         $prefix = if ($unresolved) { $unresolved + '; ' } else { '' }
-        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message)
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message + $docsOnlySuffix)
     }
 
     return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number, or a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green". No checkpoint satisfied this gate.'
@@ -447,6 +476,9 @@ function Invoke-EpicMergeGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_MERGE_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_MERGE_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
@@ -456,4 +488,4 @@ if ($entryPointResult.Count -gt 1) {
     $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-exit ([int]$entryPointResult[-1])
+exit ([int]$entryPointResult[-1])

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

@@ -8,45 +8,59 @@
     and the serialized prompt contains the epic-mode kickoff marker "Epic mode: true".
 
     Resolution and decision procedure:
-      1. Resolve the target child feature_folder from the prompt text by scanning for a
-         docs/features/active/<token> path, mirroring
-         enforce-prd-feature-before-planner.ps1's Find-PrdFeatureFolderFromPrompt
-         technique (longest match wins; a .md-suffixed match uses its parent directory).
-      2. Resolve the worktree whose epic checkpoint records the prompt's
-         integration_branch: value (issue #690), deny an unresolved or ambiguous target,
-         then read artifacts/orchestration/epic-orchestrator-state.json beneath that
-         worktree and locate the features[] record whose feature_folder equals the
-         resolved basename.
-      3. Look up that feature's depends_on list, and for every dependency, locate its own
-         features[] record.
-      4. Deny with reason EPIC_WAVE_BARRIER_BLOCKED unless every dependency's merge_status
+      1. Resolve the worktree whose epic checkpoint records the prompt's
+         integration_branch: 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/epic-orchestrator-state.json beneath that worktree
+         and select the target among the candidates with Select-FeatureFolderTarget
+         -DependencyAware: a cited upstream dependency of another cited candidate is
+         pruned, and two or more remaining candidates deny as ambiguous. Neither string
+         length nor prompt position takes part in the selection.
+      4. Locate the target's features[] record and, for every depends_on entry, its own
+         record. An entry resolves through the union index, so an issue number matches
+         issue_num and a folder value matches the normalized feature_folder.
+      5. Deny with reason EPIC_WAVE_BARRIER_BLOCKED unless every dependency's merge_status
          is merged or worktree_removed. A missing/unreadable checkpoint, an unresolved
          target feature_folder, or a missing dependency record also denies (fail-closed).
 
-    This is the per-call deterrent (Layer 1) of the two-layer wave-barrier design; the
-    retrospective backstop (Layer 2) is the wave-barrier ordering invariant inside
-    validate_epic_orchestrator_state_text, enforced separately at epic-orchestrator
-    SubagentStop time.
+    This is the per-call deterrent (Layer 1) of the two-layer wave-barrier design. The
+    retrospective backstop (Layer 2) is the wave-barrier ordering invariant of
+    validate_epic_orchestrator_state_text, run at epic-orchestrator SubagentStop time by
+    validate-orchestrator-output.ps1 through its PowerShell port
+    OrchestratorStateEpicWaveBarrier.psm1, with parity pinned by tests/fixtures/epic_wave_barrier/.
+    The SubagentStop transport and exit-code defect that hook depended on was resolved by epic #904
+    and issue #928: a violation blocks the stop with exit 2 and a stderr reason.
+    The two layers share no code.
 
 .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 WorktreeRunResolution.psm1 (issue #690) and
+    the pure sibling feature-folder-resolution.ps1 (issue #565), each loaded inside a
+    guard: a 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/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 $script:EpicWaveBarrierResolutionImportFailure = $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:EpicWaveBarrierResolutionImportFailure = 'WorktreeRunResolution.psm1'
+    if (-not $script:EpicWaveBarrierResolutionImportFailure) {
+        $script:EpicWaveBarrierResolutionImportFailure = 'feature-folder-resolution.ps1'
+    }
 }
 
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
@@ -95,56 +109,35 @@ function Resolve-EpicWaveBarrierTarget {
 function Find-EpicWaveBarrierFeatureFolderFromPrompt {
     <#
     .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 enforce-prd-feature-before-planner.ps1's
-        Find-PrdFeatureFolderFromPrompt 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)
-    $best = $candidates[0]
-
-    if ($best -match '\.md$') {
-        $best = $best -replace '/[^/]+\.md$', ''
-    }
-
-    return ($best -split '/')[-1]
+    return [string[]]@(Find-FeatureFolderCandidate -Text $Prompt)
 }
 
 function Find-EpicWaveBarrierFeatureRecord {
     <#
     .SYNOPSIS
-        Locate the features[] record whose feature_folder equals the target basename.
+        Locate the features[] record the target basename identifies, through the shared
+        union index (Find-FeatureFolderRecord). A lifecycle-prefixed feature_folder value
+        such as active/<folder> matches its basename; zero or several matches return $null.
     .PARAMETER Checkpoint
         Parsed epic checkpoint, or $null when absent/unreadable.
     .PARAMETER FeatureFolder
@@ -169,17 +162,7 @@ function Find-EpicWaveBarrierFeatureRecord {
         return $null
     }
 
-    # Scan every recorded feature for a feature_folder that equals the target basename.
-    foreach ($feature in @($Checkpoint.features)) {
-        $featureProps = @($feature.PSObject.Properties.Name)
-        if ($featureProps -notcontains 'feature_folder') {
-            continue
-        }
-        if (([string]$feature.feature_folder) -eq $FeatureFolder) {
-            return $feature
-        }
-    }
-    return $null
+    return Find-FeatureFolderRecord -Records @($Checkpoint.features) -Reference $FeatureFolder
 }
 
 function Test-EpicWaveBarrierDependenciesMerged {
@@ -219,9 +202,11 @@ function Test-EpicWaveBarrierDependenciesMerged {
     }
 
     # Every dependency edge must be durably confirmed merged or worktree_removed before
-    # this wave's feature is allowed to start.
-    foreach ($dependencyFolder in $dependsOn) {
-        $dependencyRecord = Find-EpicWaveBarrierFeatureRecord -Checkpoint $Checkpoint -FeatureFolder ([string]$dependencyFolder)
+    # this wave's feature is allowed to start. Each raw entry resolves through the union
+    # index, so an issue-number edge matches issue_num (issue #565).
+    $features = if (@($Checkpoint.PSObject.Properties.Name) -contains 'features') { @($Checkpoint.features) } else { @() }
+    foreach ($dependency in $dependsOn) {
+        $dependencyRecord = Find-FeatureFolderRecord -Records $features -Reference $dependency
         if ($null -eq $dependencyRecord) {
             return $false
         }
@@ -280,11 +265,13 @@ function Invoke-EpicWaveBarrierDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WAVE_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:EpicWaveBarrierResolutionImportFailure) {
         return Get-EpicWaveBarrierBlockDecision -Reason (
-            "EPIC_WAVE_BARRIER_BLOCKED: the worktree-resolution module '$($script:EpicWaveBarrierResolutionImportFailure)' " +
+            "EPIC_WAVE_BARRIER_BLOCKED: the dependency '$($script:EpicWaveBarrierResolutionImportFailure)' " +
             'failed to import, so the epic checkpoint that governs this delegation cannot be located; the gate fails closed.')
     }
 
@@ -312,8 +299,8 @@ function Invoke-EpicWaveBarrierDecision {
         return Get-EpicWaveBarrierBlockDecision -Reason "EPIC_WAVE_BARRIER_BLOCKED: $($target.ReasonCode): $($target.Detail)"
     }
 
-    $featureFolder = Find-EpicWaveBarrierFeatureFolderFromPrompt -Prompt $prompt
-    if (-not $featureFolder) {
+    $candidates = @(Find-EpicWaveBarrierFeatureFolderFromPrompt -Prompt $prompt)
+    if ($candidates.Count -eq 0) {
         return Get-EpicWaveBarrierBlockDecision -Reason 'EPIC_WAVE_BARRIER_BLOCKED: an epic-mode orchestrator delegation must reference the target feature folder in the prompt so its dependency edges can be verified.'
     }
 
@@ -327,6 +314,15 @@ function Invoke-EpicWaveBarrierDecision {
         }
     }
 
+    # The target is selected among the cited candidates (issue #565): a cited upstream
+    # dependency of another candidate is pruned, and an unresolved tie denies.
+    $records = if ($null -ne $checkpoint -and @($checkpoint.PSObject.Properties.Name) -contains 'features') { @($checkpoint.features) } else { @() }
+    $selection = Select-FeatureFolderTarget -Records $records -Candidate $candidates -DependencyAware
+    if ($selection.Status -eq 'Ambiguous') {
+        return Get-EpicWaveBarrierBlockDecision -Reason "EPIC_WAVE_BARRIER_BLOCKED: $($selection.Detail)."
+    }
+    $featureFolder = $selection.Basename
+
     $featureRecord = Find-EpicWaveBarrierFeatureRecord -Checkpoint $checkpoint -FeatureFolder $featureFolder
     if (Test-EpicWaveBarrierDependenciesMerged -Checkpoint $checkpoint -FeatureRecord $featureRecord) {
         return Get-EpicWaveBarrierAllowDecision
@@ -377,5 +373,8 @@ function Invoke-EpicWaveBarrierEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_WAVE_BARRIER_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WAVE_BARRIER_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 exit (Invoke-EpicWaveBarrierEntryPoint)