@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

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

package/resources/claude-customizations/.claude/hooks/enforce-feature-folder-order.ps1

@@ -1,32 +1,59 @@
 <#
 .SYNOPSIS
-    Pre-tool-use hook that blocks writes to a feature folder's plan.md when issue.md,
-    spec.md, or user-story.md are not yet present in that same folder.
+    Pre-tool-use hook that blocks writes to a feature folder's plan file until the
+    prerequisite documents its persisted work mode requires exist in that same folder.
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on Write or Edit operations. Acquires
     the hook payload through the shared reader and reads file_path from the envelope's
-    nested tool_input. When the
-    target file_path matches a feature-folder plan.md path under
-    docs/features/(active|archive)/<folder>/plan.md, the script verifies that
-    each of issue.md, spec.md, and user-story.md exists in the same folder.
-
-    If any of the three sibling files is missing, the script emits a PreToolUse
-    JSON response with hookSpecificOutput.permissionDecision='deny' and exits 0 so
-    Claude Code surfaces the reason. All other paths pass through with
+    nested tool_input. The gate applies to a feature-folder plan file under
+    docs/features/(active|archive)/<folder>/: a literal plan.md or a timestamped
+    plan.<yyyy-MM-ddTHH-mm>.md (issue #568). Other paths pass through with
     permissionDecision='allow'.
 
-    Filesystem reads go through Get-FeatureFolderFileExistence so tests can
-    inject a fake without touching disk.
+    For a plan file, the script reads the folder's issue.md through
+    Get-FeatureFolderIssueContent, resolves the persisted '- Work Mode:' marker with the
+    shared Resolve-FeatureFolderWorkMode, and takes the required set from the shared
+    Get-FeatureFolderPlanPrerequisite:
+      - minor-audit                  -> issue.md
+      - full-bug                     -> issue.md, spec.md
+      - full-feature and legacy full -> issue.md, spec.md, user-story.md
+    A missing, empty, malformed, or unrecognized marker, or an unreadable issue.md,
+    fails closed to the full-feature set. Because issue.md is in every set, an absent
+    issue.md always denies.
+
+    If any required file is missing, the script emits a PreToolUse JSON response with
+    hookSpecificOutput.permissionDecision='deny' whose reason names the plan file, the
+    resolved work mode, and the missing files, and exits 0 so Claude Code surfaces it.
+
+    Filesystem reads go through Get-FeatureFolderFileExistence and
+    Get-FeatureFolderIssueContent so tests can inject fakes without touching disk.
 
 .NOTES
-    Compatible with PowerShell 7+. Read-only validation gate; no state mutation.
+    Compatible with PowerShell 7+. Read-only validation gate; no state mutation. The pure
+    sibling feature-folder-resolution.ps1 (issue #565) is dot-sourced inside a guard: when
+    it cannot be loaded, every plan-file write denies and every other path stays allowed.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+
+# Shared work-mode parser and prerequisite map (issue #565). Guarded so a failed
+# dot-source denies plan writes rather than failing open.
+$script:FeatureFolderOrderResolutionImportFailure = $null
+try {
+    . (Join-Path $PSScriptRoot 'feature-folder-resolution.ps1')
+}
+catch {
+    $script:FeatureFolderOrderResolutionImportFailure = 'feature-folder-resolution.ps1'
+}
 
+# The plan leaf a gated path ends in: plan.md or plan.<yyyy-MM-ddTHH-mm>.md (issue #568).
+$script:FeaturePlanLeafPattern = '/plan(\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2})?\.md$'
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 function Get-FeatureFolderFileExistence {
     <#
     .SYNOPSIS
@@ -44,25 +71,57 @@ function Get-FeatureFolderFileExistence {
     return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
 }
 
+function Get-FeatureFolderIssueContent {
+    <#
+    .SYNOPSIS
+        Reads a feature folder's issue.md, or returns $null when the file is absent or
+        cannot be read. Tests mock this seam; a $null result fails closed to the
+        full-feature prerequisite set.
+    .PARAMETER FeatureFolder
+        Normalized (forward-slash) feature-folder path.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FeatureFolder
+    )
+
+    $issuePath = "$FeatureFolder/issue.md"
+    if (-not (Test-Path -LiteralPath $issuePath -PathType Leaf)) {
+        return $null
+    }
+
+    try {
+        return Get-Content -LiteralPath $issuePath -Raw -ErrorAction Stop
+    }
+    catch {
+        return $null
+    }
+}
+
 function Get-FeatureFolderMissingFile {
     <#
     .SYNOPSIS
-        Returns the list of required sibling files missing alongside plan.md.
+        Returns the list of required sibling files missing alongside the plan file.
     .PARAMETER PlanFilePath
-        Normalized (forward-slash) path to the plan.md target.
+        Normalized (forward-slash) path to the plan.md or plan.<timestamp>.md target.
+    .PARAMETER RequiredFile
+        The prerequisite file names to probe. Defaults to the full-feature set.
     #>
     [CmdletBinding()]
     [OutputType([string[]])]
     param(
         [Parameter(Mandatory)]
-        [string] $PlanFilePath
+        [string] $PlanFilePath,
+
+        [string[]] $RequiredFile = @('issue.md', 'spec.md', 'user-story.md')
     )
 
-    $folder = $PlanFilePath -replace '/plan\.md$', ''
-    $required = @('issue.md', 'spec.md', 'user-story.md')
+    $folder = $PlanFilePath -replace $script:FeaturePlanLeafPattern, ''
     [System.Collections.Generic.List[string]] $missing = [System.Collections.Generic.List[string]]::new()
 
-    foreach ($name in $required) {
+    foreach ($name in $RequiredFile) {
         $siblingPath = "$folder/$name"
         if (-not (Get-FeatureFolderFileExistence -Path $siblingPath)) {
             $missing.Add($name)
@@ -75,7 +134,9 @@ function Get-FeatureFolderMissingFile {
 function Test-IsFeaturePlanPath {
     <#
     .SYNOPSIS
-        Returns $true if the normalized path targets a feature-folder plan.md.
+        Returns $true if the normalized path targets a feature-folder plan.md or a
+        timestamped plan.<yyyy-MM-ddTHH-mm>.md directly inside an active or archive
+        feature folder.
     #>
     [CmdletBinding()]
     [OutputType([bool])]
@@ -84,7 +145,30 @@ function Test-IsFeaturePlanPath {
         [string] $NormalizedPath
     )
 
-    return $NormalizedPath -match '(^|/)docs/features/(active|archive)/[^/]+/plan\.md$'
+    return $NormalizedPath -match '(^|/)docs/features/(active|archive)/[^/]+/plan(\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2})?\.md$'
+}
+
+function Get-FeatureFolderOrderDenyDecision {
+    <#
+    .SYNOPSIS
+        Builds the PreToolUse deny decision carrying the given reason.
+    .PARAMETER Reason
+        The deny reason, beginning with FEATURE_FOLDER_ORDER_BLOCKED:.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
 }
 
 function Invoke-FeatureFolderOrderDecision {
@@ -103,18 +187,15 @@ function Invoke-FeatureFolderOrderDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'FEATURE_FOLDER_ORDER_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
-        return [ordered]@{
-            hookSpecificOutput = [ordered]@{
-                hookEventName            = 'PreToolUse'
-                permissionDecision       = 'deny'
-                permissionDecisionReason = 'FEATURE_FOLDER_ORDER_BLOCKED: payload anomaly - ' +
-                (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
-                '. The gate fails closed on an envelope it cannot read.'
-            }
-        }
+        return Get-FeatureFolderOrderDenyDecision -Reason (
+            'FEATURE_FOLDER_ORDER_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
     $filePath = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'file_path'
@@ -128,19 +209,25 @@ function Invoke-FeatureFolderOrderDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    $missing = Get-FeatureFolderMissingFile -PlanFilePath $normalized
+    $planLeaf = ($normalized -split '/')[-1]
+    if ($script:FeatureFolderOrderResolutionImportFailure) {
+        return Get-FeatureFolderOrderDenyDecision -Reason (
+            "FEATURE_FOLDER_ORDER_BLOCKED: the shared resolver '$($script:FeatureFolderOrderResolutionImportFailure)' " +
+            "failed to load, so the prerequisite documents for $planLeaf cannot be determined; the gate fails closed.")
+    }
+
+    $folder = $normalized -replace $script:FeaturePlanLeafPattern, ''
+    $workMode = Resolve-FeatureFolderWorkMode -IssueContent (Get-FeatureFolderIssueContent -FeatureFolder $folder)
+    $required = @(Get-FeatureFolderPlanPrerequisite -WorkMode $workMode)
+    $missing = @(Get-FeatureFolderMissingFile -PlanFilePath $normalized -RequiredFile $required)
     if ($missing.Count -eq 0) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $list = ($missing -join ', ')
-    return [ordered]@{
-        hookSpecificOutput = [ordered]@{
-            hookEventName            = 'PreToolUse'
-            permissionDecision       = 'deny'
-            permissionDecisionReason = "FEATURE_FOLDER_ORDER_BLOCKED: cannot write plan.md before producing prerequisite documents. Missing in feature folder: $list. Invoke the prd-feature subagent to generate the missing file(s) before authoring plan.md."
-        }
-    }
+    return Get-FeatureFolderOrderDenyDecision -Reason (
+        "FEATURE_FOLDER_ORDER_BLOCKED: cannot write $planLeaf before producing prerequisite documents for work mode '$workMode'. " +
+        "Missing in feature folder: $list. Invoke the prd-feature subagent to generate the missing file(s) before authoring the plan.")
 }
 
 function Invoke-FeatureFolderOrderEntryPoint {
@@ -185,6 +272,9 @@ function Invoke-FeatureFolderOrderEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('FEATURE_FOLDER_ORDER_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'FEATURE_FOLDER_ORDER_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