@danmoisan/drm-copilot-mcp 1.1.10 → 1.1.12

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

@@ -5,7 +5,7 @@
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
     command runs. Regex-matches gh pr merge with a --merge flag against
-    the envelope's tool_input.command and, when matched, allows the merge only when one of three
+    the envelope's tool_input.command and, when matched, allows the merge only when one of four
     checkpoint-only conditions holds:
 
       1. Child-feature path: artifacts/orchestration/orchestrator-state.json exists,
@@ -19,12 +19,19 @@
          entry whose merge_status == "ci_green". A parallel run always names an explicit PR
          number (each item merges from its own isolated worktree), so a bare command with no
          PR number cannot satisfy this branch.
-
-    Otherwise the command is denied with reason EPIC_MERGE_GATE_BLOCKED. A missing or
-    unreadable checkpoint in any branch fails closed (denies); standalone (non-epic,
-    non-parallel) orchestration never sets epic_mode, populates epic_merge_pr, or writes a
-    parallel checkpoint with route_id == "parallel", so it is structurally prevented from
-    invoking gh pr merge --merge at all.
+      4. Standalone path (issue #670), evaluated last: the command names an explicit PR
+         number and one of the three checkpoints above carries a
+         standalone_merge_authorizations record whose pr_number equals it, whose fields are
+         well formed, and whose session_id equals the live envelope's session_id. The
+         dot-sourced helpers file implements this branch.
+
+    Otherwise the command is denied with reason EPIC_MERGE_GATE_BLOCKED; a denial from
+    condition 4 also carries a standalone reason code after that token. A missing or
+    unreadable checkpoint in any branch fails closed (denies). A standalone (non-epic,
+    non-parallel) run never satisfies conditions 1-3, so its only route to a merge is an
+    explicit, PR-specific, session-bound record under condition 4; a bare command with no
+    PR number never satisfies condition 4, and a blanket flag is rejected rather than read.
+    Trigger scope: --squash is out of scope for this gate and is allowed on both runtimes.
 
     Design decision: this gate trusts the on-disk checkpoint rather than shelling out live
     to gh pr view for a real-time head-SHA check, matching the same non-adversarial,
@@ -35,11 +42,23 @@
     Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
     through injectable wrapper functions so tests can mock the boundary without writing
     temporary files.
+
+    Honest disclosure: the standalone-merge authorization record is a policy-level,
+    auditable declaration and is not a cryptographic or security control. authorized_by is
+    a declaration the hook does not verify. The record is not tamper-proof against a writer
+    inside the authorizing session. The session_id cross-check rejects stale or copied
+    records from other sessions; it does not stop same-session forgery.
 #>
 [CmdletBinding()]
 param()
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# Shared command-line parser (issue #545), consumed by the scope filter in
+# Invoke-EpicMergeGateDecision and by Get-EpicMergeGateCommandPrNumber.
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+# Standalone-merge authorization predicates and the two decision-envelope factories (issue #670).
+. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1')
 
 $script:ChildCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
@@ -128,6 +147,22 @@ function Get-EpicMergeGateCommandPrNumber {
     <#
     .SYNOPSIS
         Extract an explicit PR number argument from a gh pr merge command, or $null.
+    .DESCRIPTION
+        Both spellings are read from the segment that structurally invokes gh pr merge,
+        never from the whole command line. The positional form ("gh pr merge 410 --merge")
+        resolves through Get-CommandLineOperand and takes the first all-digit operand; the
+        flag-led forms ("gh pr merge --merge 410" and "gh pr merge --merge=410") resolve
+        through Get-CommandLineFlagValue. A bare "gh pr merge --merge" yields $null, which
+        the parallel branch treats as fail-closed.
+
+        The deleted unanchored branch scanned the WHOLE command text for the first run of
+        digits once "gh pr merge" appeared anywhere in it, and that failed in both
+        directions. Fail-closed: a leading "cd <path>" whose path carries a timestamp
+        component supplied a digit run that was not a pull request number, so an authorized
+        merge was blocked. False-allow: with authorized item 501 and unauthorized item 777,
+        "cd /repo/worktrees/501 && gh pr merge --merge 777" extracted 501, matched the
+        authorized item, and permitted the merge of PR 777. Taking the number from the
+        matched segment's own operand or flag value closes both directions.
     .PARAMETER CommandText
         The Bash command text under evaluation.
     .OUTPUTS
@@ -140,20 +175,17 @@ function Get-EpicMergeGateCommandPrNumber {
         [string] $CommandText
     )
 
-    # Original form: the PR number appears immediately after "merge"
-    # (e.g. "gh pr merge 410 --merge"). Preserved verbatim so epic-path outcomes
-    # for the forms the epic path uses are unchanged.
-    if ($CommandText -match '(?i)\bgh\s+pr\s+merge\s+(\d+)\b') {
-        return [int]$Matches[1]
+    foreach ($operand in @(Get-CommandLineOperand -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
+        if ($operand -match '^\d+$') {
+            return [int]$operand
+        }
     }
-    # Broadened, additive form: the parallel command places the flag before the
-    # number (e.g. "gh pr merge --merge 410"). Once "gh pr merge" is confirmed,
-    # capture the first standalone run of digits that is not preceded by "-" or a
-    # word character, so a flag token such as "--merge" is not treated as a number
-    # and a bare "gh pr merge --merge" still yields $null.
-    if ($CommandText -match '(?i)\bgh\s+pr\s+merge\b' -and $CommandText -match '(?<![-\w])(\d+)\b') {
-        return [int]$Matches[1]
+
+    $flagValue = Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
+    if ($null -ne $flagValue -and $flagValue -match '^\d+$') {
+        return [int]$flagValue
     }
+
     return $null
 }
 
@@ -307,36 +339,6 @@ function Test-ParallelCheckpointAllowsMerge {
     return $false
 }
 
-function Get-EpicMergeGateAllowDecision {
-    [CmdletBinding()]
-    [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param()
-
-    return [ordered]@{
-        hookSpecificOutput = [ordered]@{
-            hookEventName      = 'PreToolUse'
-            permissionDecision = 'allow'
-        }
-    }
-}
-
-function Get-EpicMergeGateBlockDecision {
-    [CmdletBinding()]
-    [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param(
-        [Parameter(Mandatory)]
-        [string] $Reason
-    )
-
-    return [ordered]@{
-        hookSpecificOutput = [ordered]@{
-            hookEventName            = 'PreToolUse'
-            permissionDecision       = 'deny'
-            permissionDecisionReason = $Reason
-        }
-    }
-}
-
 function Invoke-EpicMergeGateDecision {
     <#
     .SYNOPSIS
@@ -373,8 +375,26 @@ function Invoke-EpicMergeGateDecision {
     }
 
     # Only a gh pr merge invocation carrying --merge is in scope for this gate; every
-    # other Bash command is unaffected.
-    if ($commandText -notmatch '(?i)\bgh\s+pr\s+merge\b' -or $commandText -notmatch '--merge\b') {
+    # other Bash command is unaffected. Both legs are read structurally from the segment
+    # that invokes the command, so a quoted mention of the phrase and a --merge token
+    # belonging to some other segment no longer bring a command into scope.
+    #
+    # The flag leg needs a raw-scan fallback: a wrapper's quoted argument collapses into ONE
+    # token, so a flag inside it is never read as a token, and the token-only read took
+    # bash -c "gh pr merge --merge 688" out of scope. The fallback reads only the segments the
+    # scanner already scans raw, so a masked mention in a non-wrapper segment stays out.
+    $isMergeInvocation = Test-CommandLineInvocation -CommandText $commandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
+    $hasMergeFlag = Test-CommandLineFlag -CommandText $commandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
+    if (-not $hasMergeFlag) {
+        foreach ($segment in @(Read-CommandLineSegment -CommandText $commandText)) {
+            if ((Test-CommandLineSegmentRawScan -Segment $segment) -and
+                $segment.ScanText.IndexOf('--merge', [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
+                $hasMergeFlag = $true
+                break
+            }
+        }
+    }
+    if (-not $isMergeInvocation -or -not $hasMergeFlag) {
         return Get-EpicMergeGateAllowDecision
     }
 
@@ -395,6 +415,17 @@ function Invoke-EpicMergeGateDecision {
         return Get-EpicMergeGateAllowDecision
     }
 
+    # Branch 4, evaluated last and only for an explicit PR number: a PR-specific standalone
+    # authorization record bound to the live session. Its deny keeps the gate token first.
+    if ($null -ne $commandPrNumber) {
+        $envelopeSessionId = [string](Get-ClaudeHookEnvelopeValue -Envelope $payload.Envelope -Name 'session_id')
+        $standalone = Test-StandaloneCheckpointAllowsMerge -Checkpoints @($childCheckpoint, $epicCheckpoint, $parallelCheckpoint) -CommandPrNumber $commandPrNumber -EnvelopeSessionId $envelopeSessionId
+        if ($standalone.Allowed) {
+            return Get-EpicMergeGateAllowDecision
+        }
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $standalone.ReasonCode + ': ' + $standalone.Message)
+    }
+
     return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number, or a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green". No checkpoint satisfied this gate.'
 }
 

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

@@ -60,9 +60,20 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# 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
+# 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')
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
 $script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
+# Sanctioned-removal manifest location. Recorded here beside the two checkpoint paths
+# so every hook-read document this gate consults is named in one place; the module
+# owns the read itself.
+$script:CleanupWorktreeManifestPath = 'artifacts/orchestration/cleanup-worktrees-manifest.json'
 
 function Get-EpicWorktreeGateCheckpointContent {
     <#
@@ -132,6 +143,19 @@ 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
@@ -144,8 +168,14 @@ function Get-EpicWorktreeRemovalCommandPath {
         [string] $CommandText
     )
 
-    if ($CommandText -match '(?i)\bgit\s+worktree\s+remove\s+(?<path>\S+)') {
-        return $Matches['path'].Trim('"''')
+    $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
 }
@@ -344,7 +374,10 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         return Get-EpicWorktreeGateAllowDecision
     }
 
-    if ($commandText -notmatch '(?i)\bgit\s+worktree\s+remove\b') {
+    # Scope filter. The test is structural, so a relocating spelling such as
+    # 'git -C <dir> worktree remove <path>' is now in scope and quoted prose that merely
+    # mentions the phrase is not (issue #545).
+    if (-not (Test-CommandLineInvocation -CommandText $commandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove'))) {
         return Get-EpicWorktreeGateAllowDecision
     }
 
@@ -362,6 +395,22 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         return Get-EpicWorktreeGateAllowDecision
     }
 
+    # Sanctioned-removal manifest branch (issue #635). It runs last, so an
+    # epic-checkpoint-authorized or parallel-checkpoint-authorized removal still allows
+    # at the same decision point it does today and no transcript attribution changes.
+    #
+    # The two coverage tests are PRESENCE tests, deliberately not authorization tests.
+    # A target either checkpoint records at all is excluded from this branch regardless
+    # of that record's merge_status, so a removal no checkpoint authorizes still reaches
+    # the unchanged deny below. That exclusion is the only path by which the manifest
+    # could widen what the gates protect, which is why it is required rather than
+    # advisory, and why it is evaluated before the manifest predicate.
+    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 Get-EpicWorktreeGateBlockDecision -Reason "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."
 }
 

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

@@ -5,8 +5,15 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the Agent (Task) tool. Reads
-    tool input JSON from the the envelope's nested tool_input environment variable and the
-    orchestrator checkpoint from artifacts/orchestration/orchestrator-state.json.
+    tool input JSON from the envelope's nested tool_input, resolves which item the
+    delegation is about, and reads that item's orchestrator checkpoint.
+
+    The item is identified by portable identity only (issue #673): the canonical
+    issue-number line in the delegation prompt, and a branch label. A feature-folder
+    path never selects the worktree, because a merged folder exists in every checkout
+    branched from main. A delegation the gate cannot identify is denied with a named
+    reason code rather than checked against whichever checkpoint occupies the calling
+    process's directory, which is how a sibling item's state used to produce an allow.
 
     The hook enforces presence only: it cannot read the delegate's chosen
     `model` (no `model` field is exposed in the tool input), so it verifies that
@@ -24,7 +31,14 @@
     empty or absent tool input, and malformed tool-input JSON.
 
     The checkpoint read goes through Get-ModelRoutingCheckpoint so tests can
-    inject a synthetic checkpoint without touching disk.
+    inject a synthetic checkpoint without touching disk. Its path is mandatory and
+    carries no default: the caller supplies the absolute path of the resolved
+    worktree's checkpoint, so the gate cannot fall back to a relative location.
+
+    The delegation-identity contract this gate depends on is stated in
+    .claude/skills/orchestrate/SKILL.md under `## Issue Number Consistency`: every
+    delegation prompt to a receipt-gated subagent type carries the canonical issue
+    number line and a `branch:` label naming the item's branch.
 
 .NOTES
     Compatible with PowerShell 7+. Read-only presence-gating deterrent.
@@ -34,6 +48,11 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# Portable-identity resolution (issue #673). Unguarded and fail-closed on purpose: a gate
+# that cannot load its resolver must not degrade into the cwd-relative read it replaces.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop
+# Epic scope (issue #663): a delegation for the epic integration branch is gated against the epic checkpoint.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop
 function Get-ModelRoutingCheckpoint {
     <#
     .SYNOPSIS
@@ -43,7 +62,8 @@ function Get-ModelRoutingCheckpoint {
     [CmdletBinding()]
     [OutputType([object])]
     param(
-        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     if (-not (Test-Path -LiteralPath $CheckpointPath -PathType Leaf)) {
@@ -117,6 +137,66 @@ function Test-ModelRoutingReceiptPresent {
     return $false
 }
 
+function Resolve-ModelRoutingWorktreeTarget {
+    <#
+    .SYNOPSIS
+        Resolve the delegation'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 whichever worktrees exist on the machine running it.
+    .PARAMETER PromptText
+        The delegation prompt, which is the only field scanned for identity.
+    .OUTPUTS
+        The target result object from Resolve-WorktreeItemTarget.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $PromptText
+    )
+
+    return (Resolve-WorktreeItemTarget -Text $PromptText -SessionRoot (Get-Location).Path)
+}
+
+function Get-ModelRoutingTargetCheckpointResolution {
+    <#
+    .SYNOPSIS
+        Resolve the checkpoint path this delegation must be checked against.
+    .DESCRIPTION
+        Maps the four resolution states onto a checkpoint path or a deny reason. The two
+        resolved states share one branch because the path is composed the same way for
+        both: identity selects the worktree, and the checkpoint is read beneath it. The two
+        unresolved states deny, carrying the code the worktree-resolution accessors supply;
+        neither literal appears in this file.
+    .PARAMETER PromptText
+        The delegation prompt to resolve identity from.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with CheckpointPath and Reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $PromptText
+    )
+
+    $target = Resolve-ModelRoutingWorktreeTarget -PromptText $PromptText
+
+    switch ($target.Status) {
+        { $_ -in @('SessionRoot', 'OtherWorktree') } {
+            return [ordered]@{ CheckpointPath = (Get-WorktreeItemCheckpointPath -WorktreeRoot $target.WorktreeRoot); Reason = $null }
+        }
+        default {
+            $reason = "$($target.ReasonCode): $($target.Detail) The model-routing gate will not check this delegation against a checkpoint that may belong to a different item. Put the line 'Canonical issue number for this feature is <N>.' and a 'branch: <item branch>' label in the delegation prompt so the gate can identify the item."
+            return [ordered]@{ CheckpointPath = $null; Reason = $reason }
+        }
+    }
+}
+
 function Invoke-ModelRoutingReceiptDecision {
     <#
     .SYNOPSIS
@@ -154,7 +234,42 @@ function Invoke-ModelRoutingReceiptDecision {
         return $allow
     }
 
-    $checkpoint = Get-ModelRoutingCheckpoint
+    # Identity resolution sits after the scope filter and before the checkpoint read, so a
+    # delegation outside the gated set is still allowed however unresolvable its target is,
+    # and a gated delegation the gate cannot identify is refused rather than answered from
+    # unrelated state. An absent prompt is passed as an empty string, which resolves to no
+    # identity and therefore to the same deny.
+    $prompt = [string](Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt')
+
+    # Decision: a prompt whose branch label equals the epic checkpoint's integration_branch is
+    # epic scope (issue #663), and the receipt is looked up in the epic checkpoint without
+    # running per-feature identity resolution. Any other prompt falls through unchanged.
+    $epicScope = Resolve-EpicScopeCheckpoint -Text $prompt -SessionRoot (Get-Location).Path
+    if ($epicScope.IsEpicScope) {
+        if (Test-ModelRoutingReceiptPresent -Checkpoint $epicScope.Checkpoint -Subagent $subagent) {
+            return $allow
+        }
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = "MODEL_ROUTING_RECEIPT_BLOCKED: cannot delegate to '$subagent' in epic scope before a model_routing_receipts entry for it is recorded in $($epicScope.CheckpointPath); the failed readiness predicate is 'model_routing_receipts'."
+            }
+        }
+    }
+
+    $resolution = Get-ModelRoutingTargetCheckpointResolution -PromptText $prompt
+    if ($resolution.Reason) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = $resolution.Reason
+            }
+        }
+    }
+
+    $checkpoint = Get-ModelRoutingCheckpoint -CheckpointPath $resolution.CheckpointPath
     if (Test-ModelRoutingReceiptPresent -Checkpoint $checkpoint -Subagent $subagent) {
         return $allow
     }

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

@@ -0,0 +1,127 @@
+<#
+.SYNOPSIS
+    Epic-scope command and path legs of the preimplementation gate (issue #663).
+
+.DESCRIPTION
+    Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds two groups of
+    functions:
+
+    - The two per-mode read seams of issue #554 (Get-EpicCheckpointContent and
+      Get-ParallelCheckpointContent), relocated verbatim from the gate file by issue #663
+      so the gate stays inside the 500-line cap. Their names and behaviour are unchanged,
+      so tests that mock or shadow them by name are unaffected.
+    - The epic-scope decision for the command and path legs. A staging command or a
+      Write/Edit call is epic scope when the effective worktree's HEAD (the -C selector
+      worktree when present, otherwise the session root) equals the integration_branch of
+      artifacts/orchestration/epic-orchestrator-state.json. In epic scope the call is
+      decided by the epic command-leg readiness predicate, and under decision D2 an
+      implementation-classified operand is allowed only while a merge is in progress in
+      that worktree. Outside epic scope the decision function returns $null and the gate's
+      single-feature path runs unchanged.
+
+.NOTES
+    PowerShell 7+. Depends on functions the gate defines or dot-sources before any call:
+    Split-OrchestrationCommandLine and ConvertTo-OrchestrationCommandToken (helpers file),
+    Get-OrchestrationDelegationCheckpointPath (modes file), and the gate's allow and block
+    decision constructors. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+#>
+
+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
+
+# 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-OrchestrationEpicScopeSelector {
+    <#
+    .SYNOPSIS
+        Returns the value of a leading `git -C <value>` selector, or $null.
+    .DESCRIPTION
+        Pure. Reads only the first segment of the command line, split and tokenized with
+        the helpers-file parser so quoting is handled exactly as the staging exemption
+        handles it. An unbalanced command line has no decidable selector and returns $null.
+    .PARAMETER Command
+        The full command line.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Command)
+
+    $split = Split-OrchestrationCommandLine -CommandText $Command
+    if (-not $split.Balanced -or @($split.Segments).Count -eq 0) {
+        return $null
+    }
+    $token = @(ConvertTo-OrchestrationCommandToken -Segment ([string]@($split.Segments)[0]).Trim())
+    if ($token.Count -ge 3 -and $token[0] -ceq 'git' -and $token[1] -ceq '-C' -and $token[2]) {
+        return $token[2]
+    }
+    return $null
+}
+
+function Get-OrchestrationEpicScopeDecision {
+    <#
+    .SYNOPSIS
+        Returns the epic-scope decision for an implementation-classified command or path, or $null.
+    .DESCRIPTION
+        Resolves epic scope with worktree-HEAD matching and the command's -C selector. When
+        the call is not epic scope, returns $null so the caller's single-feature path runs
+        unchanged. In epic scope, returns an allow decision when the epic command-leg
+        readiness predicate passes, and otherwise a deny naming the epic checkpoint and the
+        failed conjunct.
+    .PARAMETER Command
+        The Bash command line; empty for a path leg.
+    .PARAMETER FilePath
+        The Write/Edit file path; empty for a command leg.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary, or $null outside epic scope.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Command = '',
+        [AllowNull()][AllowEmptyString()][string] $FilePath = ''
+    )
+
+    # A call carrying neither a command nor a path has no leg to decide.
+    if (-not $Command -and -not $FilePath) {
+        return $null
+    }
+    $selector = if ($Command) { Get-OrchestrationEpicScopeSelector -Command $Command } else { $null }
+    $scope = Resolve-EpicScopeCheckpoint -Text ([string]$Command) -SessionRoot (Get-Location).Path -WorktreeSelector $selector -MatchWorktreeHead
+    if (-not $scope.IsEpicScope) {
+        return $null
+    }
+
+    $failure = Get-EpicCommandLegReadinessFailure -Checkpoint $scope.Checkpoint -MergeInProgress $scope.MergeInProgress
+    if (-not $failure) {
+        return Get-OrchestrationPreimplementationGateAllowDecision
+    }
+    return Get-OrchestrationPreimplementationGateBlockDecision -Reason ("PREIMPLEMENTATION_GATE_BLOCKED: this epic-scope operation was evaluated against $($scope.CheckpointPath), and the failed readiness predicate is '$failure'. Implementation operations in epic scope require that checkpoint to satisfy every readiness predicate, and a production path may be staged or edited only while a merge is in progress.")
+}