@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.14

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

@@ -27,24 +27,42 @@ $script:OrchestrationBookkeepingTrees = @(
     'artifacts/orchestration/'
 )
 
-# Characters that make a command line statically unresolvable: shell interpolation and
-# redirection (D4 row 12). Tested across the whole line rather than per operand, because a
-# redirection anywhere in the line moves content the operand list cannot describe.
-$script:UnresolvableCommandCharacters = [char[]]@('$', '`', '>', '<')
+# Characters that make a command line statically unresolvable (D4 row 12, as narrowed by
+# issues #663 and #713): interpolation characters outside single quotes; outside-quote
+# characters (`<`, `>`, and the `#` comment introducer) outside any quote; and typographic
+# quotes (U+2018 to U+201E) anywhere, because a PowerShell host reads them as quotes.
+$script:InterpolationCommandCharacters = [char[]]@('$', '`')
+$script:OutsideQuoteCommandCharacters = [char[]]@('>', '<', '#')
+$script:TypographicQuoteCharacters = [char[]]@(0x2018, 0x2019, 0x201A, 0x201B, 0x201C, 0x201D, 0x201E)
 
 # Wildcards that make an operand a glob (D4 row 15). Only the literal prefix before the
 # first of these is prefix-tested.
 $script:PathspecWildcardCharacters = [char[]]@('*', '?', '[')
 
+# The single repository selector modelled between the command name and the subcommand: D4
+# row 14 as narrowed by issue #671, the Lexical Absolute-Canonical Selector (LACS) rule in
+# docs/features/active/2026-09-13-preimplementation-gate-worktree-selector-671/spec.md.
+# Compared case-sensitively; no other relocating spelling is modelled.
+$script:OrchestrationSelectorOptionName = '-C'
+
+# Accepted widening (issue #671): a selector naming a nested subdirectory of a worktree
+# passes L1 through L8 lexically yet relocates what a relative operand denotes, so
+# `docs/features/active/X` under `-C <root>/tests/fixtures/resolve_execute_plan_prompt`
+# stages `tests/fixtures/resolve_execute_plan_prompt/docs/features/active/X`. Measured
+# exposure in this repository is seven Markdown test fixtures under the
+# resolve_execute_plan_prompt fixture tree, all of which the gate's file_path leg already
+# classifies as non-implementation. This module stays pure string logic; the epic's F1
+# resolution module composes upstream to close the escape later without a schema change,
+# the same posture D4 row 16 takes toward issue #516.
+
 function Split-OrchestrationCommandLine {
     <#
     .SYNOPSIS
         Splits a command line into segments on chain operators outside quotes.
     .DESCRIPTION
-        Realizes D4 row 13. Quote state is tracked while scanning so a chain operator
-        inside a quoted span does not split. The returned `Balanced` flag reports whether
-        the scan ended outside every quote; unbalanced text is not splittable and the
-        caller denies (D4 rows 11 and 13). Empty and whitespace-only segments are dropped.
+        Realizes D4 row 13. Quote state and POSIX backslash escapes (issue #710) are tracked, so a quoted or
+        escaped chain operator does not split. `Balanced` reports whether the scan ended outside every quote;
+        the caller denies unbalanced text (D4 rows 11 and 13). Empty and whitespace-only segments are dropped.
     .OUTPUTS
         System.Collections.Hashtable with keys `Balanced` (bool) and `Segments` (string[]).
     #>
@@ -55,8 +73,9 @@ function Split-OrchestrationCommandLine {
     $segments = [System.Collections.Generic.List[string]]::new()
     $current = [System.Text.StringBuilder]::new()
     $openQuote = [char]0
-
+    $escaped = $false
     foreach ($character in $CommandText.ToCharArray()) {
+        if ($escaped -or ($character -eq '\' -and $openQuote -ne "'")) { $escaped = -not $escaped; [void]$current.Append($character); continue }
         if ($openQuote -ne [char]0) {
             if ($character -eq $openQuote) {
                 $openQuote = [char]0
@@ -88,6 +107,59 @@ function Split-OrchestrationCommandLine {
     }
 }
 
+function Test-OrchestrationCommandTextUnresolvable {
+    <#
+    .SYNOPSIS
+        Reports whether a command line carries a statically unresolvable character.
+    .DESCRIPTION
+        Realizes D4 row 12 as narrowed by issues #663 and #713, with quote state tracked as in
+        Split-OrchestrationCommandLine. `$` or backtick answers true outside quotes or inside
+        double quotes (single quotes keep it literal); `<`, `>`, or a `#` comment answers true
+        only outside a quoted span. A typographic quote (U+2018 to U+201E), a backslash before
+        any quote character, or a backslash inside a double-quoted span answers true anywhere:
+        a shell may end the span where this scan does not (fail closed).
+    .PARAMETER CommandText
+        The full command line as the shell would receive it.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $CommandText)
+
+    # An escaped or typographic quote moves a span boundary the scan cannot model (#663, #713).
+    if ($CommandText.Contains('\"') -or $CommandText.Contains("\'") -or $CommandText.IndexOfAny($script:TypographicQuoteCharacters) -ge 0) {
+        return $true
+    }
+
+    $openQuote = [char]0
+
+    # Scan every character once, tracking whether it sits inside a quoted span so that
+    # outside-quote characters are judged only where the shell would honour them.
+    foreach ($character in $CommandText.ToCharArray()) {
+        if ($openQuote -ne "'" -and $script:InterpolationCommandCharacters -contains $character) {
+            return $true
+        }
+
+        # Decide by quote state: inside a span only the closing quote matters, and any
+        # backslash inside a double-quoted span is an unmodelled escape; outside a span a
+        # quote opens one and a redirection character is unresolvable.
+        if ($openQuote -ne [char]0) {
+            if ($openQuote -eq '"' -and $character -eq '\') {
+                return $true
+            }
+            if ($character -eq $openQuote) {
+                $openQuote = [char]0
+            }
+        } elseif ($character -eq '"' -or $character -eq "'") {
+            $openQuote = $character
+        } elseif ($script:OutsideQuoteCommandCharacters -contains $character) {
+            return $true
+        }
+    }
+    return $false
+}
+
 function ConvertTo-OrchestrationCommandToken {
     <#
     .SYNOPSIS
@@ -203,6 +275,67 @@ function Test-ExemptOrchestrationOperand {
     return $false
 }
 
+function Test-ExemptOrchestrationSelector {
+    <#
+    .SYNOPSIS
+        Tests the repository selector of one tokenized segment against LACS L1 through L8.
+    .DESCRIPTION
+        Realizes D4 row 14 as narrowed by issue #671 (the Lexical Absolute-Canonical Selector
+        rule in docs/features/active/2026-09-13-preimplementation-gate-worktree-selector-671/spec.md).
+        Returns true only when the segment reads `git -C <value> <subcommand> ...` and the
+        value is decidable from the command text alone: exactly one case-sensitive `-C`, at
+        index 1 (L1, L2); a value at index 2 and the subcommand at index 3 (L3); a
+        drive-lettered or rooted, non-UNC value after separator normalization (L4); no `.` or
+        `..` segment (L5); no wildcard (L6); no colon other than the drive colon (L7); and a
+        non-empty value (L8). Each rejection writes a diagnostic token through Write-Debug.
+        The tokens are not contractual and change no decision.
+        L3 checks only that a non-option token follows the value; the caller
+        Test-ExemptOrchestrationSegmentToken rejects any subcommand other than add or commit.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyCollection()][AllowEmptyString()][string[]] $Token)
+
+    $selector = $script:OrchestrationSelectorOptionName
+    if ($Token.Count -lt 2 -or $Token[1] -cne $selector) {
+        Write-Debug 'PREIMPL_SELECTOR_UNMODELLED_OPTION: the token after the command name is not the -C selector.'
+        return $false
+    }
+    if (@($Token | Where-Object { $_ -ceq $selector }).Count -gt 1) {
+        Write-Debug 'PREIMPL_SELECTOR_REPEATED: the segment carries more than one -C selector.'
+        return $false
+    }
+    if ($Token.Count -lt 4 -or $Token[3].StartsWith('-')) {
+        Write-Debug 'PREIMPL_SELECTOR_MALFORMED: no subcommand immediately follows the selector value.'
+        return $false
+    }
+    $value = $Token[2]
+    if (-not $value) {
+        Write-Debug 'PREIMPL_SELECTOR_MALFORMED: the selector value is empty.'
+        return $false
+    }
+
+    $normalized = $value -replace '\\', '/'
+    $isDriveRooted = $normalized -match '^[A-Za-z]:/'
+    if ($normalized.StartsWith('//') -or -not ($isDriveRooted -or $normalized.StartsWith('/'))) {
+        Write-Debug 'PREIMPL_SELECTOR_NOT_ROOTED: the selector value is relative or UNC.'
+        return $false
+    }
+    $segments = $normalized -split '/'
+    if ($segments -contains '..' -or $segments -contains '.') {
+        Write-Debug 'PREIMPL_SELECTOR_TRAVERSAL: the selector value carries a dot segment.'
+        return $false
+    }
+    $afterDrive = if ($isDriveRooted) { $normalized.Substring(2) } else { $normalized }
+    if ($normalized.IndexOfAny($script:PathspecWildcardCharacters) -ge 0 -or $afterDrive.Contains(':')) {
+        Write-Debug 'PREIMPL_SELECTOR_NOT_LITERAL: the selector value carries a wildcard or a stray colon.'
+        return $false
+    }
+    return $true
+}
+
 function Test-ExemptOrchestrationSegmentToken {
     <#
     .SYNOPSIS
@@ -218,18 +351,27 @@ function Test-ExemptOrchestrationSegmentToken {
     #>
     [CmdletBinding()]
     [OutputType([bool])]
-    param([Parameter(Mandatory)][AllowEmptyCollection()][string[]] $Token)
+    param([Parameter(Mandatory)][AllowEmptyCollection()][AllowEmptyString()][string[]] $Token)
 
     if ($Token.Count -lt 2) {
         return $false
     }
 
-    # Row 14: the command name leads and the subcommand follows immediately. Anything in
-    # between - a relocating option or an env-style prefix - moves the pathspec base and is
-    # rejected here rather than modelled.
+    # Row 14, narrowed by issue #671: the command name leads and the subcommand follows it,
+    # either immediately or after one lexically absolute `-C <value>` selector (LACS L1-L8).
+    # Anything else in between - an unmodelled or unresolvable relocating option, or an
+    # env-style prefix - moves the pathspec base undecidably and is rejected here.
     if ($Token[0] -cne 'git') {
         return $false
     }
+    if ($Token[1] -cne 'add' -and $Token[1] -cne 'commit') {
+        if (-not (Test-ExemptOrchestrationSelector -Token $Token)) {
+            return $false
+        }
+        # Drop the accepted selector and its value so the subcommand is again at index 1
+        # and operand collection below starts at index 2 exactly as before.
+        $Token = @($Token[0]) + @($Token[3..($Token.Count - 1)])
+    }
     $subcommand = $Token[1]
     if ($subcommand -cne 'add' -and $subcommand -cne 'commit') {
         return $false
@@ -251,21 +393,21 @@ function Test-ExemptOrchestrationSegmentToken {
             }
 
             if ($candidate.StartsWith('-')) {
-                # The message option is the only modelled option on either subcommand. Rows
+                # Only the message and trailer options of commit are modelled (issue #713). Rows
                 # 2, 5, 6, 8, and 10 all land here and deny, including a dash-leading
                 # operand supplied without a preceding separator.
                 if ($subcommand -cne 'commit') {
                     return $false
                 }
-                if ($candidate -ceq '-m' -or $candidate -ceq '--message') {
-                    # The message value is the following token and is not a pathspec.
+                if ($candidate -ceq '-m' -or $candidate -ceq '--message' -or $candidate -ceq '--trailer') {
+                    # The message or trailer value is the following token and is not a pathspec.
                     $index += 2
                     if ($index -gt $Token.Count) {
                         return $false
                     }
                     continue
                 }
-                if ($candidate.StartsWith('--message=') -or
+                if ($candidate.StartsWith('--message=') -or $candidate.StartsWith('--trailer=') -or
                     ($candidate.Length -gt 2 -and $candidate.StartsWith('-m'))) {
                     $index++
                     continue
@@ -322,9 +464,9 @@ function Test-ExemptOrchestrationStagingCommand {
         return $false
     }
 
-    # Row 12: interpolation and redirection are not statically resolvable, so the operand
-    # list cannot be trusted to describe what the line actually touches.
-    if ($CommandText.IndexOfAny($script:UnresolvableCommandCharacters) -ge 0) {
+    # Row 12: `$` or backtick outside single quotes, `<`, `>`, or `#` outside quotes, any
+    # typographic quote, and unmodelled backslash escapes make the operand list untrustworthy.
+    if (Test-OrchestrationCommandTextUnresolvable -CommandText $CommandText) {
         return $false
     }
 
@@ -339,11 +481,17 @@ function Test-ExemptOrchestrationStagingCommand {
         return $false
     }
 
-    foreach ($segment in $segments) {
-        $tokens = @(ConvertTo-OrchestrationCommandToken -Segment $segment)
-        if (-not (Test-ExemptOrchestrationSegmentToken -Token $tokens)) {
-            return $false
+    # Fail closed (issue #671): an error raised while classifying any segment is a parse
+    # ambiguity, so it answers false instead of letting the caller continue past it.
+    try {
+        foreach ($segment in $segments) {
+            $tokens = @(ConvertTo-OrchestrationCommandToken -Segment $segment)
+            if (-not (Test-ExemptOrchestrationSegmentToken -Token $tokens)) {
+                return $false
+            }
         }
+    } catch {
+        return $false
     }
     return $true
 }

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

@@ -19,6 +19,10 @@ Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -
 # proof the issue #539 exemption is behaviourally unchanged.
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-modes.ps1')
 
+# Epic-scope command and path legs (issue #663, decision D2), plus the two per-mode read
+# seams relocated from this file to keep it inside the 500-line cap.
+. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-epic-scope.ps1')
+
 # Shared command-line parser (issue #545): per-segment scan text and structural matching.
 . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
@@ -261,33 +265,6 @@ function Get-CheckpointContent {
     return Get-Content -Raw -LiteralPath $script:CheckpointPath
 }
 
-# The two per-mode read seams (issue #554). Each takes its path from the fixed mode
-# table and never from a delegation's own text; an absent file returns an empty
-# string, which the readiness predicate then treats as a deny.
-function Get-EpicCheckpointContent {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    $path = Get-OrchestrationDelegationCheckpointPath -Mode 'epic'
-    if (-not (Test-Path -LiteralPath $path)) {
-        return ''
-    }
-    return Get-Content -Raw -LiteralPath $path
-}
-
-function Get-ParallelCheckpointContent {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    $path = Get-OrchestrationDelegationCheckpointPath -Mode 'parallel'
-    if (-not (Test-Path -LiteralPath $path)) {
-        return ''
-    }
-    return Get-Content -Raw -LiteralPath $path
-}
-
 function Get-OrchestrationPreimplementationGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -377,6 +354,7 @@ function Invoke-OrchestrationPreimplementationGateDecision {
     # default wording they have today.
     $mode = $script:OrchestrationDelegationDefaultMode
     $prompt = ''
+    $command = ''
     $filePath = Get-StringProperty -Value $toolInput -Name 'file_path'
     if ($filePath) {
         $normalized = ([string]$filePath) -replace '\\', '/'
@@ -406,6 +384,15 @@ function Invoke-OrchestrationPreimplementationGateDecision {
             Get-OrchestrationModeDenyReason -Mode $mode -Failure 'declared-checkpoint-path')
     }
 
+    # The command and path legs consult the epic checkpoint first (issue #663). A call that
+    # is not epic scope yields $null and continues to the unchanged single-feature path.
+    if ($filePath -or $command) {
+        $epicDecision = Get-OrchestrationEpicScopeDecision -Command $command -FilePath $filePath
+        if ($null -ne $epicDecision) {
+            return $epicDecision
+        }
+    }
+
     if ($mode -eq 'epic' -or $mode -eq 'parallel') {
         $isEpic = ($mode -eq 'epic')
         $injected = if ($isEpic) { 'EpicCheckpointRaw' } else { 'ParallelCheckpointRaw' }

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

@@ -41,6 +41,12 @@ Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeM
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 $script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
+# Epic checkpoint location (issue #688). An epic run records per-child state in
+# features[] and never writes the parallel checkpoint, so without this read every
+# merged epic child worktree reached the deny below even though
+# enforce-epic-worktree-removal-gate.ps1 authorized the same call. Both gates run on
+# the same Bash call, so that deny won and epic worktrees could never be removed.
+$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
 # Sanctioned-removal manifest location. Recorded here beside the checkpoint path so
 # every hook-read document this gate consults is named in one place; the module owns
 # the read itself.
@@ -64,6 +70,28 @@ function Get-ParallelWorktreeRemovalGateCheckpointContent {
     return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
 }
 
+function Get-ParallelWorktreeRemovalGateEpicCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the epic checkpoint. Tests mock this function
+        (read seam, issue #688).
+    .DESCRIPTION
+        A separate seam from the parallel checkpoint reader so a test can drive the
+        two documents independently: the epic branch must be exercised with the
+        parallel checkpoint absent, present-but-not-covering, and covering.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
+}
+
 function Get-ParallelWorktreeRemovalCommandPath {
     <#
     .SYNOPSIS
@@ -113,11 +141,16 @@ function Get-ParallelWorktreeRemovalCommandPath {
 function Find-ParallelWorktreeItemRecord {
     <#
     .SYNOPSIS
-        Locate the items[] record whose worktree_path matches the target path.
+        Locate the record whose worktree_path matches the target path.
     .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
+        Parsed checkpoint, or $null when absent/unreadable.
     .PARAMETER WorktreePath
         The target worktree path extracted from the command text.
+    .PARAMETER RecordArrayName
+        Name of the record array to scan. Defaults to 'items', the parallel
+        checkpoint's array, so every existing caller is unchanged; the epic branch
+        added for issue #688 passes 'features'. Parameterized rather than duplicated
+        so both topologies share one path-normalization implementation.
     .OUTPUTS
         System.Object or $null
     #>
@@ -127,14 +160,17 @@ function Find-ParallelWorktreeItemRecord {
         $Checkpoint,
 
         [AllowNull()]
-        [string] $WorktreePath
+        [string] $WorktreePath,
+
+        [ValidateNotNullOrEmpty()]
+        [string] $RecordArrayName = 'items'
     )
 
     if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
         return $null
     }
     $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'items') {
+    if ($checkpointProps -notcontains $RecordArrayName) {
         return $null
     }
 
@@ -142,7 +178,7 @@ function Find-ParallelWorktreeItemRecord {
 
     # Scan every recorded item for a worktree_path that matches the removal target;
     # path separators are normalized so Windows- and POSIX-style paths compare equal.
-    foreach ($item in @($Checkpoint.items)) {
+    foreach ($item in @($Checkpoint.$RecordArrayName)) {
         $itemProps = @($item.PSObject.Properties.Name)
         if ($itemProps -notcontains 'worktree_path') {
             continue
@@ -264,6 +300,31 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
         return Get-ParallelWorktreeGateAllowDecision
     }
 
+    # Epic-authorization branch (issue #688). It runs after the parallel allow above and
+    # before the manifest branch below, so neither of those decisions changes. An epic run
+    # records per-child state in the epic checkpoint's features[] array and never writes the
+    # parallel checkpoint, so before this branch every merged epic child worktree fell
+    # through to the deny even though enforce-epic-worktree-removal-gate.ps1 authorized the
+    # same call from that same record. The merge_status predicate is the one already used
+    # for parallel items, so the two topologies cannot drift apart on what counts as safe.
+    #
+    # Fail-closed is preserved: an absent, unreadable, or malformed epic checkpoint parses to
+    # $null, which yields no record, which is not allowed.
+    $epicCheckpointRaw = Get-ParallelWorktreeRemovalGateEpicCheckpointContent
+    $epicCheckpoint = $null
+    if (-not [string]::IsNullOrWhiteSpace($epicCheckpointRaw)) {
+        try {
+            $epicCheckpoint = $epicCheckpointRaw | ConvertFrom-Json -ErrorAction Stop
+        } catch {
+            $epicCheckpoint = $null
+        }
+    }
+
+    $featureRecord = Find-ParallelWorktreeItemRecord -Checkpoint $epicCheckpoint -WorktreePath $worktreePath -RecordArrayName 'features'
+    if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $featureRecord) {
+        return Get-ParallelWorktreeGateAllowDecision
+    }
+
     # Sanctioned-removal manifest branch (issue #635). It runs last, so a
     # checkpoint-authorized removal still allows at the same decision point it does
     # today and no transcript attribution changes.

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill-helpers.ps1

@@ -15,10 +15,13 @@
     payload-reader migration (issue #501) added the module import, the envelope-anomaly
     mapping, and the entry-point seam. The split is a pure move with no behaviour change.
 
-    Both helpers read the script-scoped configuration variables the parent hook assigns
-    ($script:PrContextArtifactPath, $script:OrchestratorStateCheckpointPath) and call the
-    parent hook's injectable read seams, so this file is only ever dot-sourced from that
-    hook and never invoked on its own.
+    Both helpers read the script-scoped configuration the parent hook declares and call the
+    parent hook's injectable read seams, so this file is only ever dot-sourced from that hook
+    and never invoked on its own. $script:PrContextArtifactPath is a process-directory-relative
+    artifact path and stays one. $script:OrchestratorStateCheckpointPath is different after
+    issue #673: the parent declares it null, and Get-PrAuthorBypassReason assigns it the
+    absolute checkpoint path of the worktree identity resolution selected, so every later
+    reader receives one resolved path rather than deriving its own.
 
 .NOTES
     Compatible with PowerShell 7+. No external module dependencies.
@@ -30,6 +33,92 @@ param()
 # so this file keeps working when a test dot-sources it directly.
 . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+# Worktree target resolution (issue #687). The checkpoint this gate validates must belong to
+# the item the call is about. Reading a session-root-relative path made that the item whose
+# worktree happened to occupy the session root, so in a parallel or epic topology the gate
+# could return allow on the strength of a sibling item's state -- a false green, which is
+# worse than a false denial because it reports success for a lifecycle it never checked.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeResolution.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeTargetResolution.psm1') -Force -ErrorAction Stop
+# Portable-identity resolution (issue #673). A path signal cannot select a worktree: a merged
+# feature folder exists in every checkout branched from main, so it places a call in many at
+# once. The item is identified by its canonical issue number and its branch instead.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop
+# Epic scope (issue #663): the epic integration pull request is gated against the epic checkpoint.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeReadiness.psm1') -Force -ErrorAction Stop
+
+function Resolve-PrAuthorWorktreeTarget {
+    <#
+    .SYNOPSIS
+        Resolve the call's target worktree. Tests mock this function (resolution seam).
+    .DESCRIPTION
+        A seam rather than a direct call because the resolver reads real git state: the
+        worktree list, each registration's branch, and the filesystem. A test that drove it
+        directly would depend on the machine's live worktrees and would pass or fail
+        according to what other sessions happen to have checked out, which the repository's
+        determinism policy forbids. Mocking here lets a test state the resolution outcome it
+        is exercising and nothing else.
+    .OUTPUTS
+        The target result object from Resolve-WorktreeItemTarget.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    return (Resolve-WorktreeItemTarget -Text $CommandText -SessionRoot (Get-Location).Path)
+}
+
+function Get-PrAuthorTargetCheckpointResolution {
+    <#
+    .SYNOPSIS
+        Resolve the checkpoint path this call must be validated against.
+    .DESCRIPTION
+        Resolves the target worktree from the command text by portable identity and maps the
+        four resolution states onto a checkpoint path or a deny reason:
+
+          SessionRoot   -> that worktree's own checkpoint, composed absolutely.
+          OtherWorktree -> that worktree's own checkpoint, composed the same way.
+          NoTarget      -> deny, carrying the code Get-WorktreeResolutionNoTargetReasonCode
+                           returns. pr-author passes --head on every gh pr create, so a call
+                           reaching here omitted the explicit target; the remedy is to supply
+                           it, never to fall back to whichever checkpoint occupies the
+                           session root.
+          Ambiguous     -> deny, carrying the code
+                           Get-WorktreeResolutionAmbiguityReasonCode returns.
+
+        The two resolved states share one branch because the path is now composed the same
+        way for both: identity selects the worktree, and the checkpoint is read beneath it.
+        A session-root result is not a special case, it is the case where identity happened
+        to select the worktree the process is already running in.
+
+        Returning a deny for the two unresolved states is what keeps the gate honest: it
+        refuses to answer rather than answering from unrelated state. Neither reason-code
+        literal appears in this file; both come from the accessors named above.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with CheckpointPath and Reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    $target = Resolve-PrAuthorWorktreeTarget -CommandText $CommandText
+
+    switch ($target.Status) {
+        { $_ -in @('SessionRoot', 'OtherWorktree') } {
+            return [ordered]@{ CheckpointPath = (Get-WorktreeItemCheckpointPath -WorktreeRoot $target.WorktreeRoot); Reason = $null }
+        }
+        default {
+            $reason = "$($target.ReasonCode): $($target.Detail) The pr-author gate will not validate this call against the session root's checkpoint, because that checkpoint may belong to a different item. Pass --head <branch> on the gh pr create command so the call names its own target."
+            return [ordered]@{ CheckpointPath = $null; Reason = $reason }
+        }
+    }
+}
 
 function Test-PrAuthorReceiptVerification {
     <#
@@ -55,6 +144,12 @@ function Test-PrAuthorReceiptVerification {
         with Write access to artifacts/ can replace the body file and the receipt together.
     .PARAMETER CommandText
         The Bash command text containing the --body-file argument.
+    .PARAMETER CheckpointPath
+        The absolute checkpoint path identity resolution selected, passed through to check 6
+        so that check reads the resolved worktree's checkpoint rather than deriving its own.
+    .PARAMETER EpicScope
+        Optional. The epic-scope result Get-PrAuthorBypassReason resolved (issue #663), passed
+        through to check 6 so the call is resolved once; $null outside epic scope.
     .OUTPUTS
         System.String or $null
     #>
@@ -62,7 +157,13 @@ function Test-PrAuthorReceiptVerification {
     [OutputType([string])]
     param(
         [Parameter(Mandatory)]
-        [string] $CommandText
+        [string] $CommandText,
+
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath,
+
+        [AllowNull()]
+        [object] $EpicScope
     )
 
     # Check 1: the --body-file argument must match the canonical artifacts/pr_body_<N>.md pattern.
@@ -133,7 +234,7 @@ function Test-PrAuthorReceiptVerification {
     }
 
     # Check 6: under epic_mode, gh pr create must carry a matching --base override.
-    $epicBaseBranchReason = Test-EpicBaseBranchOverride -CommandText $CommandText
+    $epicBaseBranchReason = Test-EpicBaseBranchOverride -CommandText $CommandText -CheckpointPath $CheckpointPath -EpicScope $EpicScope
     if ($epicBaseBranchReason) {
         return $epicBaseBranchReason
     }
@@ -234,13 +335,36 @@ function Get-PrAuthorBypassReason {
         return "PR_CONTEXT_MISSING: ``$script:PrContextArtifactPath`` is absent. Run ``mcp__drm-copilot__collect_pr_context`` before creating or editing the PR body."
     }
 
+    # Epic scope (issue #663): when the call's --head equals the epic checkpoint's
+    # integration_branch, the integration pull request is gated by the epic PR-creation
+    # readiness predicate on artifacts/orchestration/epic-orchestrator-state.json, and no
+    # per-feature checkpoint is resolved or read. Resolved once; check 6 reuses the result.
+    $epicScope = $null
+    if ($hasBodyFile -and $ContextExists) {
+        $epicScope = Resolve-EpicScopeCheckpoint -Text $CommandText -SessionRoot (Get-Location).Path
+    }
+
     # Orchestrator-state preflight: runs inside this same PreToolUse hook (so it cannot be
     # bypassed by invoking gh pr create/edit directly) before receipt verification.
-    if ($hasBodyFile -and $ContextExists) {
-        $preflightResult = Invoke-OrchestratorStatePreflight -CheckpointPath $script:OrchestratorStateCheckpointPath
+    if ($null -ne $epicScope -and $epicScope.IsEpicScope) {
+        $failure = Get-EpicPrCreationReadinessFailure -Checkpoint $epicScope.Checkpoint -HeadBranch $epicScope.Branch
+        if ($failure) {
+            return "ORCHESTRATOR_STATE_PREFLIGHT_FAILED: this epic-scope pull request was evaluated against $($epicScope.CheckpointPath), and the failed readiness predicate is '$failure'."
+        }
+        $script:OrchestratorStateCheckpointPath = $epicScope.CheckpointPath
+    } elseif ($hasBodyFile -and $ContextExists) {
+        $resolution = Get-PrAuthorTargetCheckpointResolution -CommandText $CommandText
+        if ($resolution.Reason) {
+            return $resolution.Reason
+        }
+        # Assigned once here and read by every later consumer, so the preflight, the receipt
+        # verifier, and the epic base-branch check cannot disagree about which item is gated.
+        $script:OrchestratorStateCheckpointPath = $resolution.CheckpointPath
+        $checkpointPath = $script:OrchestratorStateCheckpointPath
+        $preflightResult = Invoke-OrchestratorStatePreflight -CheckpointPath $checkpointPath
         if ($preflightResult.HasErrors) {
             $preflightSummary = if ([string]::IsNullOrWhiteSpace($preflightResult.ErrorText)) {
-                "checkpoint missing at $script:OrchestratorStateCheckpointPath"
+                "checkpoint missing at $checkpointPath"
             } else {
                 $preflightResult.ErrorText
             }
@@ -250,7 +374,7 @@ function Get-PrAuthorBypassReason {
 
     # Receipt verification: extends, and does not replace, the previously-allowed path.
     if ($hasBodyFile -and $ContextExists) {
-        $receiptReason = Test-PrAuthorReceiptVerification -CommandText $CommandText
+        $receiptReason = Test-PrAuthorReceiptVerification -CommandText $CommandText -CheckpointPath $script:OrchestratorStateCheckpointPath -EpicScope $epicScope
         if ($receiptReason) {
             return $receiptReason
         }