@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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)

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

@@ -7,49 +7,29 @@
     dot-sources. Holds:
 
     - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
-      $script:EpicWorktreeGateResolutionImportFailure, and
-      Get-EpicWorktreeGateImportFailureDecision turns it into a deny, so a missing module
+      $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 two checkpoint read seams, relocated from the gate file with their names kept.
       Each takes a mandatory absolute path composed beneath a resolved worktree root.
     - The resolution seam Resolve-EpicWorktreeGateRunTarget, which locates the epic or
       parallel checkpoint that records the removal target under worktree_path.
-    - Read-EpicWorktreeGateRunCheckpoint, which returns the target and the parsed
-      checkpoint beneath it ($null when the target is unresolved).
+    - Read-EpicWorktreeGateRunCheckpoint, which returns the target, the parsed checkpoint
+      beneath it ($null when the target is unresolved), and the Path it read ($null when
+      the target is unresolved; issue #851).
+    - Find-EpicWorktreeGateParallelItemRecord, which locates the parallel items[] record
+      for the removal target, and Get-EpicWorktreeGateDenyDiagnostics, which builds the
+      diagnostics clause of the final deny from two read results without reading any
+      file (issue #851).
 
 .NOTES
-    PowerShell 7+. Depends on Get-EpicWorktreeGateBlockDecision and
-    ConvertFrom-EpicWorktreeGateJson from the gate file, resolved at call time. Mirrored
-    byte-identically under extensions/drm-copilot/resources/claude-customizations/.
+    PowerShell 7+. Depends on Get-EpicWorktreeGateBlockDecision,
+    ConvertFrom-EpicWorktreeGateJson, and Find-EpicWorktreeFeatureRecord from the gate
+    file, resolved at call time. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
 #>
 
-# Import guard (issue #690): a failed import denies instead of failing open.
-$script:EpicWorktreeGateResolutionImportFailure = $null
-try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
-}
-catch {
-    $script:EpicWorktreeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
-}
-
-function Get-EpicWorktreeGateImportFailureDecision {
-    <#
-    .SYNOPSIS
-        Returns the deny for a failed worktree-resolution import, or $null.
-    .OUTPUTS
-        System.Collections.Specialized.OrderedDictionary, or $null when the import succeeded.
-    #>
-    [CmdletBinding()]
-    [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param()
-
-    if (-not $script:EpicWorktreeGateResolutionImportFailure) {
-        return $null
-    }
-    return Get-EpicWorktreeGateBlockDecision -Reason (
-        "EPIC_WORKTREE_REMOVAL_BLOCKED: the worktree-resolution module '$($script:EpicWorktreeGateResolutionImportFailure)' " +
-        'failed to import, so the run checkpoint that governs this removal cannot be located; the gate fails closed.')
-}
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 
 function Get-EpicWorktreeGateCheckpointContent {
     <#
@@ -121,7 +101,9 @@ function Read-EpicWorktreeGateRunCheckpoint {
     .PARAMETER WorktreePath
         The removal target the command names.
     .OUTPUTS
-        System.Management.Automation.PSCustomObject with Target and Checkpoint ($null when unresolved).
+        System.Management.Automation.PSCustomObject with Target, Checkpoint ($null when
+        unresolved, absent, or unparseable), and Path (the composed absolute checkpoint
+        path, or $null when the target is unresolved).
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
@@ -132,6 +114,7 @@ function Read-EpicWorktreeGateRunCheckpoint {
 
     $target = Resolve-EpicWorktreeGateRunTarget -Kind $Kind -WorktreePath $WorktreePath
     $checkpoint = $null
+    $path = $null
     if ($target.Status -eq 'SessionRoot' -or $target.Status -eq 'OtherWorktree') {
         $path = Get-WorktreeRunCheckpointPath -Kind $Kind -WorktreeRoot $target.WorktreeRoot
         $raw = if ($Kind -eq 'epic') { Get-EpicWorktreeGateCheckpointContent -Path $path } else { Get-EpicWorktreeGateParallelCheckpointContent -Path $path }
@@ -140,5 +123,114 @@ function Read-EpicWorktreeGateRunCheckpoint {
     return [pscustomobject]@{
         Target     = $target
         Checkpoint = $checkpoint
+        Path       = $path
+    }
+}
+
+function Find-EpicWorktreeGateParallelItemRecord {
+    <#
+    .SYNOPSIS
+        Locate the parallel items[] record whose worktree_path matches the target path.
+    .DESCRIPTION
+        Pure. Normalizes both paths exactly as Test-ParallelCheckpointAllowsWorktreeRemoval
+        does (backslash to slash, trailing slash trimmed, PowerShell -eq) and returns the
+        first matching entry (issue #851).
+    .PARAMETER Checkpoint
+        Parsed parallel-orchestrator checkpoint, or $null when absent/unreadable.
+    .PARAMETER WorktreePath
+        The removal target the command names.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $WorktreePath
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $null
+    }
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    if ($props -notcontains 'items' -or $null -eq $Checkpoint.items) {
+        return $null
+    }
+
+    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
+    foreach ($item in @($Checkpoint.items)) {
+        if ($null -eq $item) {
+            continue
+        }
+        $itemProps = @($item.PSObject.Properties.Name)
+        if ($itemProps -notcontains 'worktree_path') {
+            continue
+        }
+        $normalizedItemPath = (([string]$item.worktree_path) -replace '\\', '/').TrimEnd('/')
+        if ($normalizedItemPath -eq $normalizedTarget) {
+            return $item
+        }
+    }
+    return $null
+}
+
+function Get-EpicWorktreeGateDenyDiagnostics {
+    <#
+    .SYNOPSIS
+        Build the diagnostics clause of the final deny from the two read results (issue #851).
+    .DESCRIPTION
+        Pure; reads no file. Names, for each run kind, the target status, the checkpoint
+        path read (or that none was read), and the outcome of the record match: the
+        matched record's merge_status, an absent merge_status, no matching record, an
+        absent or unparseable checkpoint, or not evaluated when no checkpoint was read.
+    .PARAMETER EpicRead
+        The epic read result (Target, Checkpoint, Path).
+    .PARAMETER ParallelRead
+        The parallel read result (Target, Checkpoint, Path).
+    .PARAMETER WorktreePath
+        The removal target the command names.
+    .OUTPUTS
+        System.String
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'The name is fixed by the issue #851 plan contract; the plural noun names the one diagnostics clause it returns.')]
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)] $EpicRead,
+        [Parameter(Mandatory)] $ParallelRead,
+        [AllowNull()][AllowEmptyString()][string] $WorktreePath
+    )
+
+    $parts = foreach ($kind in @('epic', 'parallel')) {
+        $read = if ($kind -eq 'epic') { $EpicRead } else { $ParallelRead }
+        $pathText = if ($null -ne $read.Path) { "checkpoint '$($read.Path)'" } else { 'no checkpoint read' }
+        if ($null -eq $read.Path) {
+            $recordText = 'not evaluated'
+        }
+        elseif ($null -eq $read.Checkpoint) {
+            $recordText = 'checkpoint absent or unparseable'
+        }
+        else {
+            $record = if ($kind -eq 'epic') {
+                Find-EpicWorktreeFeatureRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath
+            }
+            else {
+                Find-EpicWorktreeGateParallelItemRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath
+            }
+            $arrayName = if ($kind -eq 'epic') { 'features' } else { 'items' }
+            $recordText = if ($null -eq $record) {
+                "no matching $arrayName[] record"
+            }
+            elseif (@($record.PSObject.Properties.Name) -contains 'merge_status') {
+                "merge_status '$([string]$record.merge_status)'"
+            }
+            else {
+                'merge_status absent'
+            }
+        }
+        '{0} run {1} ({2}), {3}' -f $kind, $read.Target.Status, $pathText, $recordText
     }
+    return ('Diagnostics: {0}; {1}.' -f $parts[0], $parts[1])
 }

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

@@ -55,6 +55,10 @@
     enforce-epic-worktree-removal-gate-resolution.ps1. An ambiguous target denies before
     any allow; when neither kind resolves, the deny names TARGET_WORKTREE_NOT_DERIVABLE.
 
+    Issues #789 and #851: the final deny carries one leading EPIC_WORKTREE_REMOVAL_BLOCKED
+    token and ends with a diagnostics clause naming each run kind's status, checkpoint
+    path, and matched record; the allow-or-deny decision is unchanged.
+
 .NOTES
     Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 through the
     dot-sourced resolution sibling, whose import guard denies on a failed import.
@@ -63,18 +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 $_ }
 # Sanctioned-removal manifest reader (issue #635), consumed by the manifest branch in
 # Invoke-EpicWorktreeRemovalGateDecision.
-Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeManifest.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeManifest.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'CleanupWorktreeManifest.psm1' -ErrorRecord $_ }
 # Shared command-line parser (issue #545), consumed by the scope filter in
-# Invoke-EpicWorktreeRemovalGateDecision and by Get-EpicWorktreeRemovalCommandPath.
-. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
-. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+# Invoke-EpicWorktreeRemovalGateDecision and by Resolve-CommandLineInvocationTarget.
+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 $_ }
 # Checkpoint read seams, the import guard, and run-target resolution (issue #690).
-. (Join-Path $PSScriptRoot 'enforce-epic-worktree-removal-gate-resolution.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-epic-worktree-removal-gate-resolution.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-worktree-removal-gate-resolution.ps1' -ErrorRecord $_ }
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 # Sanctioned-removal manifest location. Recorded here so every hook-read document this
 # gate consults is named; the module owns the read itself.
@@ -108,47 +113,6 @@ function ConvertFrom-EpicWorktreeGateJson {
     }
 }
 
-function Get-EpicWorktreeRemovalCommandPath {
-    <#
-    .SYNOPSIS
-        Extract the target worktree path argument from a git worktree remove command.
-    .DESCRIPTION
-        The operand comes from the segment that structurally invokes git worktree remove,
-        so a 'cd <path> &&' segment chained before the removal contributes nothing and a
-        quoted mention of the phrase resolves to no operand at all. Quotes around the path
-        are already stripped by the tokenizer.
-
-        '--force' is a zero-argument flag, so it never contributes an operand and may be
-        written on either side of the target path. Its presence is read structurally through
-        Test-CommandLineFlag rather than by searching the raw text, so a '--force' spelling
-        that appears inside an unrelated quoted argument cannot change how the operand list
-        is read. When no operand resolves, a present '--force' is reported in its place, so
-        the checkpoint lookup fails closed on a value that matches no recorded worktree_path
-        - the same value the previous raw-text pattern returned for that input.
-    .PARAMETER CommandText
-        The Bash command text under evaluation.
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory)]
-        [string] $CommandText
-    )
-
-    $hasForce = Test-CommandLineFlag -CommandText $CommandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove') -FlagName '--force'
-    $operands = @(Get-CommandLineOperand -CommandText $CommandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove'))
-
-    if ($operands.Count -gt 0) {
-        return $operands[0]
-    }
-    if ($hasForce) {
-        return '--force'
-    }
-    return $null
-}
-
 function Find-EpicWorktreeFeatureRecord {
     <#
     .SYNOPSIS
@@ -331,10 +295,8 @@ function Invoke-EpicWorktreeRemovalGateDecision {
     )
 
     # A failed worktree-resolution import denies before any other logic (issue #690).
-    $importFailure = Get-EpicWorktreeGateImportFailureDecision
-    if ($null -ne $importFailure) {
-        return $importFailure
-    }
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_REMOVAL_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -356,7 +318,43 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         return Get-EpicWorktreeGateAllowDecision
     }
 
-    $worktreePath = Get-EpicWorktreeRemovalCommandPath -CommandText $commandText
+    # Issue #824: the removal targets are derived structurally from every invocation.
+    # A target that cannot be derived denies before any checkpoint is read, and every
+    # derived target must be authorized on its own.
+    $resolution = Resolve-CommandLineInvocationTarget -CommandText $commandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove')
+    if ($resolution.Status -eq 'NoMatch') {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+    if ($resolution.Status -ne 'Targets') {
+        return Get-EpicWorktreeGateBlockDecision -Reason 'EPIC_WORKTREE_REMOVAL_BLOCKED: TARGET_WORKTREE_NOT_DERIVABLE: the git worktree remove target cannot be derived from the command text. No checkpoint can authorize this removal.'
+    }
+    foreach ($target in @($resolution.Targets)) {
+        $denial = Get-EpicWorktreeRemovalTargetDenial -WorktreePath $target
+        if ($null -ne $denial) {
+            return $denial
+        }
+    }
+    return Get-EpicWorktreeGateAllowDecision
+}
+
+function Get-EpicWorktreeRemovalTargetDenial {
+    <#
+    .SYNOPSIS
+        Evaluate one derived removal target and return its deny decision, or $null when authorized.
+    .DESCRIPTION
+        Holds the per-path authorization cascade (epic checkpoint, parallel checkpoint,
+        sanctioned-removal manifest) for a single worktree path (issue #824).
+    .PARAMETER WorktreePath
+        One removal target derived by Resolve-CommandLineInvocationTarget.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $WorktreePath
+    )
 
     # Each run checkpoint is read beneath the worktree that records this path (issue #690);
     # an ambiguous target denies before any allow or manifest evaluation.
@@ -371,12 +369,12 @@ function Invoke-EpicWorktreeRemovalGateDecision {
 
     $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
     if (Test-EpicWorktreeRemovalAllowed -FeatureRecord $featureRecord) {
-        return Get-EpicWorktreeGateAllowDecision
+        return $null
     }
 
     $parallelCheckpoint = $parallelRead.Checkpoint
     if (Test-ParallelCheckpointAllowsWorktreeRemoval -Checkpoint $parallelCheckpoint -WorktreePath $worktreePath) {
-        return Get-EpicWorktreeGateAllowDecision
+        return $null
     }
 
     # Sanctioned-removal manifest branch (issue #635). It runs last, so an
@@ -392,15 +390,18 @@ function Invoke-EpicWorktreeRemovalGateDecision {
     if (-not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $checkpoint -RecordArrayName 'features' -WorktreePath $worktreePath) -and
         -not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $parallelCheckpoint -RecordArrayName 'items' -WorktreePath $worktreePath) -and
         (Test-CleanupWorktreeManifestAuthorizesRemoval -WorktreePath $worktreePath)) {
-        return Get-EpicWorktreeGateAllowDecision
+        return $null
     }
 
     # When neither kind resolved, the deny names the resolution reason first (issue #690).
+    # The gate token leads once and a diagnostics clause for this target closes the text
+    # (issues #789, #851).
     $prefix = ''
     if ($epicRead.Target.Status -eq 'NoTarget' -and $parallelRead.Target.Status -eq 'NoTarget') {
-        $prefix = "EPIC_WORKTREE_REMOVAL_BLOCKED: $($epicRead.Target.ReasonCode): $($epicRead.Target.Detail). "
+        $prefix = "$($epicRead.Target.ReasonCode): $($epicRead.Target.Detail). "
     }
-    return Get-EpicWorktreeGateBlockDecision -Reason ($prefix + "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal.")
+    $diagnostics = Get-EpicWorktreeGateDenyDiagnostics -EpicRead $epicRead -ParallelRead $parallelRead -WorktreePath $worktreePath
+    return Get-EpicWorktreeGateBlockDecision -Reason ('EPIC_WORKTREE_REMOVAL_BLOCKED: ' + $prefix + "git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal. " + $diagnostics)
 }
 
 function Invoke-EpicWorktreeRemovalGateEntryPoint {
@@ -445,6 +446,9 @@ function Invoke-EpicWorktreeRemovalGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_WORKTREE_REMOVAL_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_REMOVAL_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-evidence-locations.ps1

@@ -41,8 +41,9 @@
 #>
 [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 $_ }
 
 function Test-EvidenceLocationForbidden {
     <#
@@ -150,6 +151,8 @@ function Invoke-EvidenceLocationDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EVIDENCE_LOCATION_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -211,6 +214,9 @@ function Invoke-EvidenceLocationEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EVIDENCE_LOCATION_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EVIDENCE_LOCATION_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