@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.12

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.")
+}

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

@@ -27,15 +27,34 @@ $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
+# issue #663). Interpolation characters are unresolvable in every quote state, because a
+# double-quoted span still expands them. Redirection characters are unresolvable only
+# outside a quoted span: inside single or double quotes the shell treats `<` and `>` as
+# literal text, so a quoted Co-Authored-By trailer is not a redirection.
+$script:InterpolationCommandCharacters = [char[]]@('$', '`')
+$script:RedirectionCommandCharacters = [char[]]@('>', '<')
 
 # 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
@@ -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 issue #663. Quote state is tracked with the same
+        state machine as Split-OrchestrationCommandLine. An interpolation character (`$` or
+        backtick) answers true in any quote state; a redirection character (`<` or `>`)
+        answers true only outside a quoted span. Backslash escapes are not modelled, so a
+        backslash before any quote character, or anywhere inside a double-quoted span,
+        answers true: the 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 quote moves a span boundary the scan cannot model (issue #663 remediation CR-1).
+    if ($CommandText.Contains('\"') -or $CommandText.Contains("\'")) {
+        return $true
+    }
+
+    $openQuote = [char]0
+
+    # Scan every character once, tracking whether it sits inside a quoted span so that
+    # redirection characters are judged only where the shell would honour them.
+    foreach ($character in $CommandText.ToCharArray()) {
+        if ($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:RedirectionCommandCharacters -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
@@ -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: interpolation anywhere, redirection outside quotes, and unmodelled backslash
+    # escapes are not statically resolvable, so the operand list cannot be trusted.
+    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' }