@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.24

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

@@ -0,0 +1,325 @@
+<#
+.SYNOPSIS
+    Green-CI standalone merge branch of the merge gate (issue #997).
+
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1. Invoke-EpicMergeGateDecision calls
+    Get-EpicMergeGateGreenCiDecision after the parallel allow-branch declines and before the
+    standalone authorization branch, so branches 1 to 3 keep their order and behavior. The
+    branch allows a standalone run (neither an epic child nor a parallel item) to merge its own
+    pull request once its per-feature checkpoint records a green S9 gate for that exact pull
+    request and the live pull-request head still equals the head that CI passed on.
+
+    Stages run cheapest first, and only stage D starts a process:
+      A. The item target resolved to one worktree and its per-feature checkpoint records a green
+         standalone S9 gate bound to the explicit PR number (Test-ChildCheckpointGreenCiRecorded).
+      B. No epic or parallel run checkpoint records the PR number (both run targets NoTarget),
+         and no parallel run checkpoint records the item worktree as a parallel item.
+      C. The command is one structural gh pr merge with no chain, wrapper, inline environment
+         prefix, -R or --repo, /pull/ URL selector, or --auto (Get-DocsOnlyMergeShapeViolation),
+         and carries no --admin flag (declined silently).
+      D. gh pr view <PR> --json headRefOid returns a well-formed head (one bounded call).
+      E. The live head equals ci_gate.head_sha, and --match-head-commit, when present, equals it.
+    Stages A to C decline silently, so every existing deny text is unchanged for a non-green
+    case. A stage D or E decline returns a suffix that the gate appends to its deny reason:
+    GREEN_CI_LIVE_HEAD_UNRESOLVED, GREEN_CI_HEAD_STALE, or GREEN_CI_MATCH_HEAD_MISMATCH.
+
+    Residual parallel-exclusion window: the Parallel mode: true marker lives in the Agent
+    delegation prompt and is not in a Bash PreToolUse payload, so this hook cannot see it. The
+    exclusion is layered and best-effort: a run target recording the PR number (layer 1a), a
+    parallel item recording the worktree path (layer 1b), and child-recorded parallel_mode or
+    parallel_slug keys (layer 2), with skill prose as layer 3. A parallel child whose parent has
+    recorded neither the PR number nor the worktree path, and which omits the layer 2 keys, is
+    not excluded mechanically. Like the standalone authorization record, this is a policy-level
+    control, not a cryptographic one. A push after the stage D lookup can also change the head
+    unless the command passes --match-head-commit; the hook does not require the flag.
+
+.NOTES
+    Compatible with PowerShell 7+. This file dot-sources nothing and imports no module. It
+    calls, at run time only, Invoke-DocsOnlyGhExe and Get-DocsOnlyMergeShapeViolation
+    (hook-docs-only-diff.ps1), Test-CommandLineFlag and Get-CommandLineFlagValue (the shared
+    command parser), and Resolve-WorktreeRunTargetByRecord (WorktreeRunResolution.psm1), all of
+    which the gate loads before it calls this file's functions.
+#>
+
+function Test-EpicMergeGateGreenCiObjectId {
+    <#
+    .SYNOPSIS
+        True when a value is a full lowercase hexadecimal object id of 40 or 64 characters.
+    .PARAMETER Value
+        The candidate value; any non-string value returns $false.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()] $Value)
+
+    return ($Value -is [string]) -and ($Value -cmatch '^[0-9a-f]{40}([0-9a-f]{24})?$')
+}
+
+function Test-EpicMergeGateGreenCiNotParallel {
+    <#
+    .SYNOPSIS
+        True when a parsed per-feature checkpoint carries no epic or parallel marker (pure).
+    .DESCRIPTION
+        epic_mode must be absent, JSON null, or JSON false; epic_mode true belongs to branch 1,
+        and any other value (for example the string "false") fails closed. parallel_mode must
+        be absent, JSON null, or JSON false, and parallel_slug must be absent or blank.
+    .PARAMETER Checkpoint
+        The parsed checkpoint object.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)] $Checkpoint)
+
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    # Each marker key passes only when it is absent, JSON null, or the JSON boolean false.
+    foreach ($marker in @('epic_mode', 'parallel_mode')) {
+        if ($props -ccontains $marker -and $null -ne $Checkpoint.$marker -and
+            -not (($Checkpoint.$marker -is [bool]) -and -not $Checkpoint.$marker)) {
+            return $false
+        }
+    }
+    return -not ($props -ccontains 'parallel_slug' -and -not [string]::IsNullOrWhiteSpace([string]$Checkpoint.parallel_slug))
+}
+
+function Test-ChildCheckpointGreenCiRecorded {
+    <#
+    .SYNOPSIS
+        True when a per-feature checkpoint records a green standalone S9 gate for the PR (pure).
+    .DESCRIPTION
+        Every condition must hold: the command names a PR number above zero; the checkpoint
+        carries no epic or parallel marker (Test-EpicMergeGateGreenCiNotParallel);
+        step9_status is exactly "passed"; ci_gate is an object whose conclusion is exactly
+        "success"; pr_gate.pr_number is a JSON integer equal to the command number, with no
+        fallback to a standalone_merge_authorizations record; ci_gate.head_sha is a lowercase
+        40 or 64 character object id; and pr_gate.head_sha, when present and not null, equals
+        ci_gate.head_sha. Comparisons are ordinal, so a case variant fails closed.
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint, or $null when absent or unreadable.
+    .PARAMETER CommandPrNumber
+        The explicit PR number the command names, or $null for a bare command.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()][Nullable[int]] $CommandPrNumber
+    )
+
+    if ($null -eq $CommandPrNumber -or $CommandPrNumber -le 0) { return $false }
+    if ($Checkpoint -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    if (-not (Test-EpicMergeGateGreenCiNotParallel -Checkpoint $Checkpoint)) { return $false }
+    if (-not (($Checkpoint.step9_status -is [string]) -and ($Checkpoint.step9_status -ceq 'passed'))) { return $false }
+
+    $ciGate = $Checkpoint.ci_gate
+    if ($ciGate -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    if (-not (($ciGate.conclusion -is [string]) -and ($ciGate.conclusion -ceq 'success'))) { return $false }
+    if (-not (Test-EpicMergeGateGreenCiObjectId -Value $ciGate.head_sha)) { return $false }
+
+    # The PR binding comes from pr_gate alone; an authorization record must not stand in for a CI result.
+    $prGate = $Checkpoint.pr_gate
+    if ($prGate -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    $recordedNumber = $prGate.pr_number
+    if (-not (($recordedNumber -is [int]) -or ($recordedNumber -is [long])) -or [long]$recordedNumber -ne $CommandPrNumber) { return $false }
+
+    # A recorded PR head must agree with the head CI passed on; null or absent means not recorded.
+    if (@($prGate.PSObject.Properties.Name) -ccontains 'head_sha' -and $null -ne $prGate.head_sha) {
+        return [string]::Equals([string]$prGate.head_sha, [string]$ciGate.head_sha, [System.StringComparison]::Ordinal)
+    }
+    return $true
+}
+
+function Get-EpicMergeGateLivePrHeadSha {
+    <#
+    .SYNOPSIS
+        Return the live head commit of a pull request, or $null on any failure (the live-head seam).
+    .DESCRIPTION
+        Runs gh pr view <PR> --json headRefOid through Invoke-DocsOnlyGhExe, which bounds the
+        call at 7 seconds and never throws. Returns the head only for exit code 0, output that
+        parses to a JSON object, and a well-formed lowercase object id; a non-zero exit
+        (including 124 for a timeout and -1 for a missing root), unparseable output, and a
+        malformed head all return $null. Tests mock this function by name.
+    .PARAMETER PrNumber
+        The pull request number.
+    .PARAMETER WorktreeRoot
+        The directory gh runs in.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][int] $PrNumber,
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot
+    )
+
+    $lookup = Invoke-DocsOnlyGhExe -WorkingRoot $WorktreeRoot -GhArgs @('pr', 'view', [string]$PrNumber, '--json', 'headRefOid')
+    if ($null -eq $lookup -or $lookup.ExitCode -ne 0) { return $null }
+    try {
+        $pr = ConvertFrom-Json -InputObject ([string]$lookup.Output) -ErrorAction Stop
+    }
+    catch {
+        # Unreadable gh output is a lookup failure; the gate fails closed on $null.
+        return $null
+    }
+    if ($pr -isnot [System.Management.Automation.PSCustomObject]) { return $null }
+    if (-not (Test-EpicMergeGateGreenCiObjectId -Value $pr.headRefOid)) { return $null }
+    return [string]$pr.headRefOid
+}
+
+function Test-EpicMergeGateGreenCiHeadAgreement {
+    <#
+    .SYNOPSIS
+        True when the live head equals ci_gate.head_sha and any pinned head equals the live head (pure).
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint carrying ci_gate.head_sha.
+    .PARAMETER LiveHeadSha
+        The live pull-request head, or $null when unresolved.
+    .PARAMETER PinnedHeadSha
+        The --match-head-commit value, or $null when the flag is absent. An empty string means
+        the flag is present without a usable value and fails closed.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()] $LiveHeadSha,
+        [AllowNull()] $PinnedHeadSha
+    )
+
+    if ($null -eq $Checkpoint -or $LiveHeadSha -isnot [string] -or $null -eq $Checkpoint.ci_gate) { return $false }
+    if (-not [string]::Equals($LiveHeadSha, [string]$Checkpoint.ci_gate.head_sha, [System.StringComparison]::Ordinal)) { return $false }
+    if ($null -ne $PinnedHeadSha -and -not [string]::Equals([string]$PinnedHeadSha, $LiveHeadSha, [System.StringComparison]::Ordinal)) { return $false }
+    return $true
+}
+
+function Resolve-EpicMergeGateParallelItemByWorktree {
+    <#
+    .SYNOPSIS
+        Resolve the parallel run whose items[] record a worktree path (layer 1b seam).
+    .DESCRIPTION
+        A one-call seam over Resolve-WorktreeRunTargetByRecord so tests can mock it. Status
+        NoTarget means no parallel checkpoint records the worktree as a parallel item.
+    .PARAMETER WorktreeRoot
+        The item worktree whose per-feature checkpoint was read.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([AllowNull()][AllowEmptyString()][string] $WorktreeRoot)
+
+    return Resolve-WorktreeRunTargetByRecord -Kind parallel -RecordField worktree_path -Value $WorktreeRoot -SessionRoot (Get-Location).Path
+}
+
+function Test-EpicMergeGateGreenCiNoRunRecord {
+    <#
+    .SYNOPSIS
+        True when no epic or parallel run checkpoint records the PR or the item worktree (stage B).
+    .DESCRIPTION
+        Both run targets must have status NoTarget; a resolved or Ambiguous target declines.
+        The worktree lookup declines on any status other than NoTarget, on $null, and on a
+        thrown error, because an unreadable parallel record cannot prove the item is standalone.
+    .PARAMETER EpicTarget
+        The epic run target resolved for the PR number.
+    .PARAMETER ParallelTarget
+        The parallel run target resolved for the PR number.
+    .PARAMETER WorktreeRoot
+        The item worktree root.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget,
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot
+    )
+
+    foreach ($target in @($EpicTarget, $ParallelTarget)) {
+        if ($null -eq $target -or [string]$target.Status -cne 'NoTarget') { return $false }
+    }
+    try {
+        $byWorktree = Resolve-EpicMergeGateParallelItemByWorktree -WorktreeRoot $WorktreeRoot
+    }
+    catch {
+        # A failed lookup cannot show the worktree is not a parallel item, so the stage declines.
+        return $false
+    }
+    return ($null -ne $byWorktree -and [string]$byWorktree.Status -ceq 'NoTarget')
+}
+
+function Get-EpicMergeGateGreenCiDecision {
+    <#
+    .SYNOPSIS
+        Evaluate stages A to E of the green-CI branch and return Allowed and a deny suffix.
+        Stage C declines silently a command that carries --admin.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER CommandPrNumber
+        The explicit PR number, or $null for a bare command.
+    .PARAMETER ChildCheckpoint
+        The parsed per-feature checkpoint the gate read, or $null.
+    .PARAMETER ItemTarget
+        The item target, or $null for a bare command.
+    .PARAMETER EpicTarget
+        The epic run target, or $null for a bare command.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null for a bare command.
+    .PARAMETER SessionRoot
+        The session worktree root, where gh runs.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with Allowed and Suffix.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $CommandText,
+        [AllowNull()][Nullable[int]] $CommandPrNumber,
+        [AllowNull()] $ChildCheckpoint,
+        [AllowNull()] $ItemTarget,
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget,
+        [AllowNull()][AllowEmptyString()][string] $SessionRoot
+    )
+
+    $silent = [ordered]@{ Allowed = $false; Suffix = '' }
+    # Stage A: one resolved item worktree whose checkpoint records a green S9 gate for this PR.
+    if ($null -eq $ItemTarget -or @('SessionRoot', 'OtherWorktree') -cnotcontains [string]$ItemTarget.Status) { return $silent }
+    if (-not (Test-ChildCheckpointGreenCiRecorded -Checkpoint $ChildCheckpoint -CommandPrNumber $CommandPrNumber)) { return $silent }
+    # Stage B: no epic or parallel run records the PR or the item worktree.
+    if (-not (Test-EpicMergeGateGreenCiNoRunRecord -EpicTarget $EpicTarget -ParallelTarget $ParallelTarget -WorktreeRoot ([string]$ItemTarget.WorktreeRoot))) { return $silent }
+    # Stage C: a single structural gh pr merge naming the PR, with no repository or auto override.
+    if ($null -ne (Get-DocsOnlyMergeShapeViolation -CommandText $CommandText -PrNumber $CommandPrNumber)) { return $silent }
+    # --admin bypasses branch protection, so a green checkpoint must not authorize it.
+    if (Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--admin') { return $silent }
+
+    # Stage D: the only process call, made after every pure stage passed.
+    $liveHead = Get-EpicMergeGateLivePrHeadSha -PrNumber $CommandPrNumber -WorktreeRoot $SessionRoot
+    if ($null -eq $liveHead) {
+        return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_LIVE_HEAD_UNRESOLVED)' }
+    }
+
+    # Stage E: a stale checkpoint head is reported before a mismatched --match-head-commit pin.
+    $subcommandPath = @('pr', 'merge')
+    $pinned = $null
+    if (Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--match-head-commit') {
+        $pinned = [string](Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--match-head-commit')
+    }
+    if (Test-EpicMergeGateGreenCiHeadAgreement -Checkpoint $ChildCheckpoint -LiveHeadSha $liveHead -PinnedHeadSha $pinned) {
+        return [ordered]@{ Allowed = $true; Suffix = '' }
+    }
+    if (-not (Test-EpicMergeGateGreenCiHeadAgreement -Checkpoint $ChildCheckpoint -LiveHeadSha $liveHead -PinnedHeadSha $null)) {
+        return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_HEAD_STALE)' }
+    }
+    return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_MATCH_HEAD_MISMATCH)' }
+}

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

@@ -12,6 +12,8 @@
       1. Child-feature path: artifacts/orchestration/orchestrator-state.json exists,
          epic_mode == true, and step9_status == "passed" (the per-feature orchestrator has
          already run S9 step 6's CI-green gate before attempting its own merge-on-green).
+         Only the JSON boolean true counts as epic mode; a string or number such as "false"
+         does not (issue #1001).
       2. Epic-integration path: artifacts/orchestration/epic-orchestrator-state.json exists,
          epic_merge_pr.ci_gate.conclusion == "success", and, when the command names an
          explicit PR number, that number matches epic_merge_pr.pr_number.
@@ -20,6 +22,11 @@
          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.
+     3b. Green-CI standalone path (issue #997): the command names an explicit PR number, no
+         epic or parallel checkpoint records that number or the item worktree, the per-feature
+         checkpoint records step9_status == "passed", ci_gate.conclusion == "success", and a
+         pr_gate.pr_number equal to it, and the live PR head equals ci_gate.head_sha. The
+         dot-sourced enforce-epic-merge-gate-green-ci.ps1 implements this branch.
       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
@@ -29,15 +36,20 @@
     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.
+    non-parallel) run never satisfies conditions 1-3; it merges through the green-CI branch
+    3b or through an explicit, PR-specific, session-bound record under condition 4. A bare
+    command with no PR number satisfies neither, and a blanket flag is rejected rather than
+    read. A 3b decline after its live-head lookup appends a GREEN_CI_* code to the deny.
     Trigger scope (issue #952): every merge method (--merge/-m, --squash/-s, --rebase/-r), --auto,
     --admin, and a bare gh pr merge are gated alike, because under a merge queue each spelling
     enqueues the pull request; only a pure --disable-auto is out of scope. The predicate and the
     PR selector reader live in enforce-epic-merge-gate-command.ps1.
 
-    Design decision: branches 1-4 trust the on-disk checkpoint and never call gh. Issue #927
+    Design decision: branches 1-4 trust the on-disk checkpoint and never call gh. The green-CI
+    branch makes at most one bounded gh pr view call, only after its pure stages A to C pass.
+    Its parallel exclusion is best-effort: the Parallel mode: true marker is in the delegation
+    prompt, not in a Bash payload, so a parallel child that no checkpoint records yet is not
+    excluded mechanically (residual window; see enforce-epic-merge-gate-green-ci.ps1). Issue #927
     adds a docs-only branch after branch 4 fails, only for an explicit PR number whose item,
     epic, and parallel targets are all NoTarget (no checkpoint records the PR): it calls
     Get-DocsOnlyMergeExemption (hook-docs-only-diff.ps1), which runs gh pr view and git in the
@@ -86,6 +98,8 @@ try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1') } cat
 try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-command.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-command.ps1' -ErrorRecord $_ }
 # Shared docs-only diff classification and the merge-side docs-only exemption (issue #927).
 try { . (Join-Path $PSScriptRoot 'hook-docs-only-diff.ps1') } catch { Add-HookDependencyFailure -Name 'hook-docs-only-diff.ps1' -ErrorRecord $_ }
+# Green-CI standalone merge branch: pure checks, the live-head seam, and the stage orchestrator (issue #997).
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-green-ci.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-green-ci.ps1' -ErrorRecord $_ }
 
 function ConvertFrom-EpicMergeGateJson {
     <#
@@ -143,6 +157,10 @@ function Test-ChildCheckpointAllowsEpicMerge {
     <#
     .SYNOPSIS
         Decision logic for the child-feature checkpoint path (branch 1).
+    .DESCRIPTION
+        Only the JSON boolean true counts as epic mode: epic_mode must be a System.Boolean
+        $true after ConvertFrom-Json. A string or number such as "false", "true", or 1 is not
+        epic mode, so branch 1 declines and later branches decide (issue #1001).
     .PARAMETER Checkpoint
         Parsed child orchestrator checkpoint, or $null when absent/unreadable.
     .OUTPUTS
@@ -159,7 +177,7 @@ function Test-ChildCheckpointAllowsEpicMerge {
         return $false
     }
     $props = @($Checkpoint.PSObject.Properties.Name)
-    if ($props -notcontains 'epic_mode' -or -not [bool]$Checkpoint.epic_mode) {
+    if ($props -notcontains 'epic_mode' -or -not (($Checkpoint.epic_mode -is [bool]) -and $Checkpoint.epic_mode)) {
         return $false
     }
     if ($props -notcontains 'step9_status') {
@@ -376,6 +394,10 @@ function Invoke-EpicMergeGateDecision {
         return Get-EpicMergeGateAllowDecision
     }
 
+    # Branch 3b (issue #997): a standalone run whose checkpoint records a green S9 gate merges its own PR.
+    $greenCi = Get-EpicMergeGateGreenCiDecision -CommandText $commandText -CommandPrNumber $commandPrNumber -ChildCheckpoint $childCheckpoint -ItemTarget $itemTarget -EpicTarget $epicTarget -ParallelTarget $parallelTarget -SessionRoot $sessionRoot
+    if ($greenCi.Allowed) { 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) {
@@ -397,10 +419,10 @@ function Invoke-EpicMergeGateDecision {
         # three details precede the standalone reason (issue #850).
         $unresolved = Get-EpicMergeGateUnresolvedReason -ItemTarget $itemTarget -EpicTarget $epicTarget -ParallelTarget $parallelTarget
         $prefix = if ($unresolved) { $unresolved + '; ' } else { '' }
-        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message + $docsOnlySuffix)
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message + $docsOnlySuffix + $greenCi.Suffix)
     }
 
-    return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: a pull-request merge or merge-queue enqueue (gh pr merge with any method, --auto, or --admin, or a gh api merge or enqueue mutation) 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.'
+    return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: a pull-request merge or merge-queue enqueue (gh pr merge with any method, --auto, or --admin, or a gh api merge or enqueue mutation) 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, a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green", or a standalone per-feature checkpoint (epic_mode absent or false, no parallel marker) with step9_status == "passed", ci_gate.conclusion == "success", pr_gate.pr_number equal to the explicit PR number, and ci_gate.head_sha equal to the live pull-request head. No checkpoint satisfied this gate.'
 }
 
 function Invoke-EpicMergeGateEntryPoint {

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

@@ -21,6 +21,9 @@
       for the removal target, and Get-EpicWorktreeGateDenyDiagnostics, which builds the
       diagnostics clause of the final deny from two read results without reading any
       file (issue #851).
+    - The import guard for WorktreeRunRecordPath.psm1, whose Get-WorktreeRunRecordBaseRoot
+      pairs the main checkout root with a read's own root so a relative recorded
+      worktree_path is compared through the shared matcher (issue #995).
 
 .NOTES
     PowerShell 7+. Depends on Get-EpicWorktreeGateBlockDecision,
@@ -29,6 +32,8 @@
     extensions/drm-copilot/resources/claude-customizations/.
 #>
 
+# Shared recorded-path matcher and main-checkout-root seam (issue #995).
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunRecordPath.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunRecordPath.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 
 function Get-EpicWorktreeGateCheckpointContent {
@@ -132,13 +137,15 @@ function Find-EpicWorktreeGateParallelItemRecord {
     .SYNOPSIS
         Locate the parallel items[] record whose worktree_path matches the target path.
     .DESCRIPTION
-        Pure. Normalizes both paths exactly as Test-ParallelCheckpointAllowsWorktreeRemoval
-        does (backslash to slash, trailing slash trimmed, PowerShell -eq) and returns the
-        first matching entry (issue #851).
+        Pure. Compares through Test-WorktreeRunRecordedPathMatchesTarget, exactly as
+        Test-ParallelCheckpointAllowsWorktreeRemoval does, and returns the first matching
+        entry (issues #851, #995).
     .PARAMETER Checkpoint
         Parsed parallel-orchestrator checkpoint, or $null when absent/unreadable.
     .PARAMETER WorktreePath
         The removal target the command names.
+    .PARAMETER BaseRoot
+        Optional. The roots a relative recorded worktree_path is joined to.
     .OUTPUTS
         System.Object or $null
     #>
@@ -148,7 +155,9 @@ function Find-EpicWorktreeGateParallelItemRecord {
         $Checkpoint,
 
         [AllowNull()]
-        [string] $WorktreePath
+        [string] $WorktreePath,
+
+        [AllowNull()][AllowEmptyCollection()][string[]] $BaseRoot = @()
     )
 
     if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
@@ -159,7 +168,7 @@ function Find-EpicWorktreeGateParallelItemRecord {
         return $null
     }
 
-    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
+    # Scan the items for the first record the shared matcher accepts for the target.
     foreach ($item in @($Checkpoint.items)) {
         if ($null -eq $item) {
             continue
@@ -168,8 +177,7 @@ function Find-EpicWorktreeGateParallelItemRecord {
         if ($itemProps -notcontains 'worktree_path') {
             continue
         }
-        $normalizedItemPath = (([string]$item.worktree_path) -replace '\\', '/').TrimEnd('/')
-        if ($normalizedItemPath -eq $normalizedTarget) {
+        if (Test-WorktreeRunRecordedPathMatchesTarget -RecordedPath ([string]$item.worktree_path) -TargetPath $WorktreePath -BaseRoot $BaseRoot) {
             return $item
         }
     }
@@ -191,6 +199,9 @@ function Get-EpicWorktreeGateDenyDiagnostics {
         The parallel read result (Target, Checkpoint, Path).
     .PARAMETER WorktreePath
         The removal target the command names.
+    .PARAMETER MainRoot
+        Optional. The main checkout root the gate derived; with each read's own root it
+        forms the base roots a relative recorded worktree_path is joined to (issue #995).
     .OUTPUTS
         System.String
     #>
@@ -200,7 +211,8 @@ function Get-EpicWorktreeGateDenyDiagnostics {
     param(
         [Parameter(Mandatory)] $EpicRead,
         [Parameter(Mandatory)] $ParallelRead,
-        [AllowNull()][AllowEmptyString()][string] $WorktreePath
+        [AllowNull()][AllowEmptyString()][string] $WorktreePath,
+        [AllowNull()][AllowEmptyString()][string] $MainRoot
     )
 
     $parts = foreach ($kind in @('epic', 'parallel')) {
@@ -213,11 +225,12 @@ function Get-EpicWorktreeGateDenyDiagnostics {
             $recordText = 'checkpoint absent or unparseable'
         }
         else {
+            $baseRoot = Get-WorktreeRunRecordBaseRoot -MainRoot $MainRoot -Read $read
             $record = if ($kind -eq 'epic') {
-                Find-EpicWorktreeFeatureRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath
+                Find-EpicWorktreeFeatureRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath -BaseRoot $baseRoot
             }
             else {
-                Find-EpicWorktreeGateParallelItemRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath
+                Find-EpicWorktreeGateParallelItemRecord -Checkpoint $read.Checkpoint -WorktreePath $WorktreePath -BaseRoot $baseRoot
             }
             $arrayName = if ($kind -eq 'epic') { 'features' } else { 'items' }
             $recordText = if ($null -eq $record) {

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

@@ -26,8 +26,9 @@
     before either checkpoint is read.
 
     Both branches key on the worktree PATH because the command names a path, and both
-    normalize separators and trim a trailing slash on each side of the comparison, so
-    Windows- and POSIX-style paths compare equal. Path is also why the two branches are
+    compare through Test-WorktreeRunRecordedPathMatchesTarget (issue #995), so Windows-
+    and POSIX-style paths compare equal and a relative record is joined to the main
+    checkout root and the checkpoint's own root. Path is also why the two branches are
     mutually exclusive in practice: an epic run and a parallel run allocate worktrees
     under distinct per-run, per-item paths, so a path recorded in one checkpoint is not a
     path recorded in the other, and adding branch 2 cannot widen what branch 1 authorizes.
@@ -121,6 +122,8 @@ function Find-EpicWorktreeFeatureRecord {
         Parsed epic checkpoint, or $null when absent/unreadable.
     .PARAMETER WorktreePath
         The target worktree path extracted from the command text.
+    .PARAMETER BaseRoot
+        Optional. The roots a relative recorded worktree_path is joined to (issue #995).
     .OUTPUTS
         System.Object or $null
     #>
@@ -130,7 +133,9 @@ function Find-EpicWorktreeFeatureRecord {
         $Checkpoint,
 
         [AllowNull()]
-        [string] $WorktreePath
+        [string] $WorktreePath,
+
+        [AllowNull()][AllowEmptyCollection()][string[]] $BaseRoot = @()
     )
 
     if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
@@ -141,17 +146,14 @@ function Find-EpicWorktreeFeatureRecord {
         return $null
     }
 
-    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
-
-    # Scan every recorded feature for a worktree_path that matches the removal target;
-    # path separators are normalized so Windows- and POSIX-style paths compare equal.
+    # Scan every recorded feature for a worktree_path that names the removal target
+    # through the shared matcher (separator, trailing slash, case rule, relative join).
     foreach ($feature in @($Checkpoint.features)) {
         $featureProps = @($feature.PSObject.Properties.Name)
         if ($featureProps -notcontains 'worktree_path') {
             continue
         }
-        $normalizedFeaturePath = (([string]$feature.worktree_path) -replace '\\', '/').TrimEnd('/')
-        if ($normalizedFeaturePath -eq $normalizedTarget) {
+        if (Test-WorktreeRunRecordedPathMatchesTarget -RecordedPath ([string]$feature.worktree_path) -TargetPath $WorktreePath -BaseRoot $BaseRoot) {
             return $feature
         }
     }
@@ -198,6 +200,8 @@ function Test-ParallelCheckpointAllowsWorktreeRemoval {
         Parsed parallel-orchestrator checkpoint, or $null when absent/unreadable.
     .PARAMETER WorktreePath
         The target worktree path extracted from the command text.
+    .PARAMETER BaseRoot
+        Optional. The roots a relative recorded worktree_path is joined to (issue #995).
     .OUTPUTS
         System.Boolean
     #>
@@ -208,7 +212,9 @@ function Test-ParallelCheckpointAllowsWorktreeRemoval {
         $Checkpoint,
 
         [AllowNull()]
-        [string] $WorktreePath
+        [string] $WorktreePath,
+
+        [AllowNull()][AllowEmptyCollection()][string[]] $BaseRoot = @()
     )
 
     if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
@@ -224,10 +230,8 @@ function Test-ParallelCheckpointAllowsWorktreeRemoval {
         return $false
     }
 
-    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
-
-    # Scan every recorded item for a worktree_path that matches the removal target;
-    # path separators are normalized exactly as the epic branch normalizes them.
+    # Scan every recorded item for a worktree_path that names the removal target through
+    # the same shared matcher the epic branch uses.
     foreach ($item in @($Checkpoint.items)) {
         if ($null -eq $item) {
             continue
@@ -236,8 +240,7 @@ function Test-ParallelCheckpointAllowsWorktreeRemoval {
         if ($itemProps -notcontains 'worktree_path') {
             continue
         }
-        $normalizedItemPath = (([string]$item.worktree_path) -replace '\\', '/').TrimEnd('/')
-        if ($normalizedItemPath -ne $normalizedTarget) {
+        if (-not (Test-WorktreeRunRecordedPathMatchesTarget -RecordedPath ([string]$item.worktree_path) -TargetPath $WorktreePath -BaseRoot $BaseRoot)) {
             continue
         }
         if ($itemProps -notcontains 'merge_status') {
@@ -366,14 +369,19 @@ function Get-EpicWorktreeRemovalTargetDenial {
         }
     }
     $checkpoint = $epicRead.Checkpoint
+    # A relative record is joined to the main checkout root and to the root holding the
+    # checkpoint read (issue #995); the main root is derived once per target.
+    $mainRoot = Get-WorktreeRunMainCheckoutRoot -SessionRoot (Get-Location).Path
+    $epicBaseRoot = Get-WorktreeRunRecordBaseRoot -MainRoot $mainRoot -Read $epicRead
+    $parallelBaseRoot = Get-WorktreeRunRecordBaseRoot -MainRoot $mainRoot -Read $parallelRead
 
-    $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
+    $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath -BaseRoot $epicBaseRoot
     if (Test-EpicWorktreeRemovalAllowed -FeatureRecord $featureRecord) {
         return $null
     }
 
     $parallelCheckpoint = $parallelRead.Checkpoint
-    if (Test-ParallelCheckpointAllowsWorktreeRemoval -Checkpoint $parallelCheckpoint -WorktreePath $worktreePath) {
+    if (Test-ParallelCheckpointAllowsWorktreeRemoval -Checkpoint $parallelCheckpoint -WorktreePath $worktreePath -BaseRoot $parallelBaseRoot) {
         return $null
     }
 
@@ -387,8 +395,8 @@ function Get-EpicWorktreeRemovalTargetDenial {
     # 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
+    if (-not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $checkpoint -RecordArrayName 'features' -WorktreePath $worktreePath -BaseRoot $epicBaseRoot) -and
+        -not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $parallelCheckpoint -RecordArrayName 'items' -WorktreePath $worktreePath -BaseRoot $parallelBaseRoot) -and
         (Test-CleanupWorktreeManifestAuthorizesRemoval -WorktreePath $worktreePath)) {
         return $null
     }
@@ -400,7 +408,7 @@ function Get-EpicWorktreeRemovalTargetDenial {
     if ($epicRead.Target.Status -eq 'NoTarget' -and $parallelRead.Target.Status -eq 'NoTarget') {
         $prefix = "$($epicRead.Target.ReasonCode): $($epicRead.Target.Detail). "
     }
-    $diagnostics = Get-EpicWorktreeGateDenyDiagnostics -EpicRead $epicRead -ParallelRead $parallelRead -WorktreePath $worktreePath
+    $diagnostics = Get-EpicWorktreeGateDenyDiagnostics -EpicRead $epicRead -ParallelRead $parallelRead -WorktreePath $worktreePath -MainRoot $mainRoot
     return Get-EpicWorktreeGateBlockDecision -Reason ('EPIC_WORKTREE_REMOVAL_BLOCKED: ' + $prefix + "git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal. " + $diagnostics)
 }