@danmoisan/drm-copilot-mcp 1.1.10 → 1.1.12

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.
@@ -26,6 +29,97 @@
 [CmdletBinding()]
 param()
 
+# Shared command-line parser (issue #545). Dot-sourced here as well as from the parent hook
+# 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 {
     <#
     .SYNOPSIS
@@ -50,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
     #>
@@ -57,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.
@@ -128,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
     }
@@ -166,16 +272,43 @@ function Get-PrAuthorBypassReason {
         [bool] $ContextExists
     )
 
-    # Only act on gh pr create or gh pr edit subcommands.
-    $isPrCreate = $CommandText -match '(?i)\bgh\s+pr\s+create\b'
-    $isPrEdit = $CommandText -match '(?i)\bgh\s+pr\s+edit\b'
+    # Only act on gh pr create or gh pr edit subcommands. The test is structural: a segment
+    # must INVOKE gh with the subcommand path, so quoted prose that merely mentions the
+    # phrase no longer triggers the gate, and a relocating spelling that carries a gh global
+    # option between the command word and the subcommand now does.
+    $isPrCreate = Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'create')
+    $isPrEdit = Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'edit')
 
     if (-not $isPrCreate -and -not $isPrEdit) {
         return $null
     }
 
-    $hasBodyFile = $CommandText -match '(?i)--body-file\b'
-    $hasInlineBody = $CommandText -match '(?i)--body(?!-file)\b'
+    # Flag presence comes from the matched segment's tokens. Exact token comparison is what
+    # keeps '--body' from matching '--body-file'; the previous negative lookahead expressed
+    # the same distinction over raw text.
+    $subcommandPath = if ($isPrCreate) { @('pr', 'create') } else { @('pr', 'edit') }
+    $hasBodyFile = Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--body-file'
+    $hasInlineBody = Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--body'
+
+    # Raw-scan fallback for a wrapper-led, live-substitution, or unbalanced segment. A
+    # wrapper's quoted argument collapses into ONE token, so both flags read absent there and
+    # the gh pr edit no-body branch below allowed bash -c "gh pr edit 42 --body 'x'". The
+    # --body-file test runs first and wins, so a --body-file carried inside a wrapper is never
+    # misread as an inline body. That ordering restores the pre-parser routing, in which one
+    # whole-text --body-file match set $hasBodyFile for exactly this input.
+    if (-not $hasBodyFile -and -not $hasInlineBody) {
+        $comparison = [System.StringComparison]::OrdinalIgnoreCase
+        foreach ($segment in @(Read-CommandLineSegment -CommandText $CommandText)) {
+            if (-not (Test-CommandLineSegmentRawScan -Segment $segment)) {
+                continue
+            }
+            if ($segment.ScanText.IndexOf('--body-file', $comparison) -ge 0) {
+                $hasBodyFile = $true
+            } elseif ($segment.ScanText.IndexOf('--body', $comparison) -ge 0) {
+                $hasInlineBody = $true
+            }
+        }
+    }
 
     # Case A: gh pr create OR gh pr edit with inline --body (not --body-file). Evaluated before the
     # gh pr edit no-body allow short-circuit so inline-body edits are blocked, not allowed.
@@ -202,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
             }
@@ -218,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
         }

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill.epic-base-branch.ps1

@@ -9,25 +9,35 @@
     structural extraction only: no logic, decision behavior, or reason-string wording changed.
 #>
 
+# Shared command-line parser (issue #545). Dot-sourced here as well as from the parent hook
+# 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')
+
 function Get-PrAuthorCheckpointContent {
     <#
     .SYNOPSIS
         Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock this
         function (read seam) for the epic-mode base-branch override check.
     .DESCRIPTION
-        Returns the raw text content of artifacts/orchestration/orchestrator-state.json, or
-        $null when the file is absent. This is the injectable boundary for checkpoint content
-        used by Test-EpicBaseBranchOverride; no test writes the checkpoint file to disk.
+        Returns the raw text content of the checkpoint at the supplied path, or $null when the
+        file is absent. This is the injectable boundary for checkpoint content used by
+        Test-EpicBaseBranchOverride; no test writes the checkpoint file to disk.
+
+        The path is mandatory and carries no default (issue #673). A relative default was the
+        second of this feature's three bindings: it made check 6 read whichever checkpoint
+        occupied the process directory even when target resolution had already selected a
+        different worktree, so the epic verdict could come from an unrelated item.
     .PARAMETER CheckpointPath
-        The relative path to the per-feature orchestrator checkpoint.
+        The absolute path of the checkpoint belonging to the resolved worktree.
     .OUTPUTS
         System.String or $null
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
-        [Parameter(Mandatory = $false)]
-        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     if (-not (Test-Path -LiteralPath $CheckpointPath)) {
@@ -52,6 +62,13 @@ function Test-EpicBaseBranchOverride {
         unchanged.
     .PARAMETER CommandText
         The Bash command text under evaluation.
+    .PARAMETER CheckpointPath
+        The absolute checkpoint path identity resolution selected, passed straight through to
+        the read seam so this check and the orchestrator-state preflight read one file.
+    .PARAMETER EpicScope
+        Optional. The epic-scope result gate 1 resolved (issue #663). When it reports epic
+        scope, the integration pull request must pass --base main and the per-feature
+        checkpoint seam is not read; $null keeps the per-feature epic_mode rule unchanged.
     .OUTPUTS
         System.String or $null
     #>
@@ -59,16 +76,35 @@ function Test-EpicBaseBranchOverride {
     [OutputType([string])]
     param(
         [Parameter(Mandatory)]
-        [string] $CommandText
+        [string] $CommandText,
+
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath,
+
+        [AllowNull()]
+        [object] $EpicScope
     )
 
     # The epic-mode base-branch override only constrains gh pr create; gh pr edit does not
     # re-target the base branch, so non-create commands are out of scope for this check.
-    if ($CommandText -notmatch '(?i)\bgh\s+pr\s+create\b') {
+    # The test is structural, so a quoted mention of the phrase is out of scope and a
+    # relocating spelling carrying a gh global option is in scope (issue #545).
+    if (-not (Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'create'))) {
+        return $null
+    }
+
+    # Epic scope (issue #663): the epic's own integration pull request targets main. The
+    # scope object comes from gate 1, so the epic checkpoint is not read a second time and
+    # the per-feature checkpoint is not consulted.
+    if ($null -ne $EpicScope -and $EpicScope.IsEpicScope) {
+        $epicBaseValue = Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'create') -FlagName '--base'
+        if ($null -eq $epicBaseValue -or $epicBaseValue -cne 'main') {
+            return "EPIC_BASE_BRANCH_MISMATCH: this epic-scope gh pr create was evaluated against $($EpicScope.CheckpointPath); the integration pull request must pass --base main."
+        }
         return $null
     }
 
-    $checkpointRaw = Get-PrAuthorCheckpointContent
+    $checkpointRaw = Get-PrAuthorCheckpointContent -CheckpointPath $CheckpointPath
     if ([string]::IsNullOrWhiteSpace($checkpointRaw)) {
         return $null
     }
@@ -96,7 +132,11 @@ function Test-EpicBaseBranchOverride {
         return "EPIC_BASE_BRANCH_MISMATCH: checkpoint has epic_mode == true but no ``epic_context.integration_branch`` is recorded; ``gh pr create`` cannot be verified against the required ``--base`` value."
     }
 
-    if ($CommandText -cnotmatch [regex]::Escape("--base $integrationBranch")) {
+    # The --base value is taken from the matched segment's tokens, so a chained segment that
+    # happens to carry a --base token contributes nothing here. The comparison stays
+    # case-sensitive, as the previous -cnotmatch form was, because a branch name is.
+    $baseValue = Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'create') -FlagName '--base'
+    if ($null -eq $baseValue -or $baseValue -cne $integrationBranch) {
         return "EPIC_BASE_BRANCH_MISMATCH: ``gh pr create`` must pass ``--base $integrationBranch`` (``epic_context.integration_branch``) under ``epic_mode``; the command does not carry a matching ``--base`` argument."
     }
 

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

@@ -46,7 +46,9 @@ param()
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
-$script:OrchestratorStateCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+# Null until the resolution step assigns the absolute path of the resolved worktree's
+# checkpoint (issue #673); a relative default here was the process-directory binding.
+$script:OrchestratorStateCheckpointPath = $null
 
 Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force