@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

@@ -6,53 +6,36 @@
     Dot-sourced by enforce-epic-merge-gate.ps1 immediately after the authorization sibling.
     Holds:
 
-    - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
-      $script:EpicMergeGateResolutionImportFailure, and
-      Get-EpicMergeGateImportFailureDecision turns it into a deny, so a missing module
+    - The import guards for WorktreeRunResolution.psm1 and, after it,
+      WorktreeItemResolution.psm1 (issue #850). A failed import is recorded in
+      $script:HookDependencyFailures, and the gate's call to
+      Get-HookDependencyFailureDecision turns it into a deny, so a missing module
       cannot make the gate exit non-zero and fail open.
     - The three checkpoint read seams, relocated from the gate file with their names kept.
       Each takes a mandatory absolute path composed beneath a resolved worktree root.
-    - The session worktree root, used for the child branch and for a bare command.
+    - The session worktree root, used for a bare command.
     - The resolution seam Resolve-EpicMergeGateRunTarget, which locates the epic or
       parallel checkpoint that records the command's pull request number.
+    - The item seam Resolve-EpicMergeGateItemTarget (issue #850), which locates the live
+      worktree whose per-feature checkpoint records the command's pull request number in
+      pr_gate.pr_number or a standalone_merge_authorizations entry.
     - Test-ChildCheckpointPrGateBinding, which binds the command's pull request number to
-      the per-feature checkpoint's pr_gate.pr_number when that field is recorded.
-    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither run branch
-      resolves.
+      the per-feature checkpoint: pr_gate.pr_number must equal it when recorded, and
+      otherwise a positive-integer standalone record must name it (issue #788).
+    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither the item
+      target nor either run branch resolves.
+    - Test-EpicMergeGateNoRecordingTarget, the precondition of the docs-only merge branch:
+      the item, epic, and parallel targets all resolve NoTarget (issue #927).
 
 .NOTES
-    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision from the authorization
-    sibling, dot-sourced by the gate before this file. Mirrored byte-identically under
+    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision and
+    Test-StandalonePositiveJsonInteger from the authorization sibling, dot-sourced by the
+    gate before this file. Mirrored byte-identically under
     extensions/drm-copilot/resources/claude-customizations/.
 #>
 
-# Import guard (issue #690): a failed import denies instead of failing open.
-$script:EpicMergeGateResolutionImportFailure = $null
-try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
-}
-catch {
-    $script:EpicMergeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
-}
-
-function Get-EpicMergeGateImportFailureDecision {
-    <#
-    .SYNOPSIS
-        Returns the deny for a failed worktree-resolution import, or $null.
-    .OUTPUTS
-        System.Collections.Specialized.OrderedDictionary, or $null when the import succeeded.
-    #>
-    [CmdletBinding()]
-    [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param()
-
-    if (-not $script:EpicMergeGateResolutionImportFailure) {
-        return $null
-    }
-    return Get-EpicMergeGateBlockDecision -Reason (
-        "EPIC_MERGE_GATE_BLOCKED: the worktree-resolution module '$($script:EpicMergeGateResolutionImportFailure)' " +
-        'failed to import, so the run checkpoint that governs this merge cannot be located; the gate fails closed.')
-}
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
 
 function Get-ChildOrchestratorCheckpointContent {
     <#
@@ -60,7 +43,7 @@ function Get-ChildOrchestratorCheckpointContent {
         Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
         this function (read seam).
     .PARAMETER Path
-        The absolute checkpoint path composed beneath the session worktree root.
+        The absolute checkpoint path composed beneath the item or session worktree root.
     .OUTPUTS
         System.String or $null
     #>
@@ -117,7 +100,7 @@ function Get-ParallelOrchestratorCheckpointContent {
 function Get-EpicMergeGateSessionWorktreeRoot {
     <#
     .SYNOPSIS
-        Return the worktree root the session runs in (the child branch and bare-command root).
+        Return the worktree root the session runs in (the bare-command root).
     .OUTPUTS
         System.String
     #>
@@ -149,14 +132,35 @@ function Resolve-EpicMergeGateRunTarget {
     return Resolve-WorktreeRunTargetByRecord -Kind $Kind -RecordField pr_number -Value ([string]$PrNumber) -SessionRoot (Get-Location).Path
 }
 
+function Resolve-EpicMergeGateItemTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose per-feature checkpoint records a pull request number (issue #850 seam).
+    .PARAMETER PrNumber
+        The explicit pull request number the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][int] $PrNumber
+    )
+
+    return Resolve-WorktreeItemTargetByPrNumber -PrNumber $PrNumber -SessionRoot (Get-Location).Path
+}
+
 function Test-ChildCheckpointPrGateBinding {
     <#
     .SYNOPSIS
-        True unless the per-feature checkpoint records a pr_gate.pr_number that differs from the command's.
+        True when the per-feature checkpoint binds the command's pull request number (issue #788).
     .DESCRIPTION
-        A bare command, an absent checkpoint, and a checkpoint without pr_gate.pr_number
-        keep today's unbound child-branch decision. When both numbers are present they must
-        parse as integers and be equal.
+        Pure. A bare command is unbound and returns $true. An explicit number requires a
+        checkpoint: when it records pr_gate.pr_number, that value must parse as an integer
+        equal to the number; otherwise a standalone_merge_authorizations entry whose
+        pr_number is a positive JSON integer equal to the number must exist. Every other
+        case returns $false, so a checkpoint that names neither field cannot authorize an
+        explicit-number merge through the child branch.
     .PARAMETER Checkpoint
         Parsed per-feature checkpoint, or $null.
     .PARAMETER CommandPrNumber
@@ -171,30 +175,45 @@ function Test-ChildCheckpointPrGateBinding {
         [AllowNull()][Nullable[int]] $CommandPrNumber
     )
 
-    if ($null -eq $CommandPrNumber -or $null -eq $Checkpoint) {
+    if ($null -eq $CommandPrNumber) {
         return $true
     }
-    if (@($Checkpoint.PSObject.Properties.Name) -notcontains 'pr_gate' -or $null -eq $Checkpoint.pr_gate) {
-        return $true
+    if ($null -eq $Checkpoint) {
+        return $false
     }
-    $prGate = $Checkpoint.pr_gate
-    if (@($prGate.PSObject.Properties.Name) -notcontains 'pr_number' -or $null -eq $prGate.pr_number) {
-        return $true
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    if ($props -contains 'pr_gate' -and $null -ne $Checkpoint.pr_gate -and
+        @($Checkpoint.pr_gate.PSObject.Properties.Name) -contains 'pr_number' -and $null -ne $Checkpoint.pr_gate.pr_number) {
+        $recorded = 0
+        if (-not [int]::TryParse([string]$Checkpoint.pr_gate.pr_number, [ref] $recorded)) {
+            return $false
+        }
+        return ($recorded -eq $CommandPrNumber)
     }
-    $recorded = 0
-    if (-not [int]::TryParse([string]$prGate.pr_number, [ref] $recorded)) {
+    if ($props -notcontains 'standalone_merge_authorizations') {
         return $false
     }
-    return ($recorded -eq $CommandPrNumber)
+    foreach ($entry in @($Checkpoint.standalone_merge_authorizations)) {
+        if ($null -eq $entry -or @($entry.PSObject.Properties.Name) -notcontains 'pr_number') {
+            continue
+        }
+        if ((Test-StandalonePositiveJsonInteger -Value $entry.pr_number) -and [long]$entry.pr_number -eq $CommandPrNumber) {
+            return $true
+        }
+    }
+    return $false
 }
 
 function Get-EpicMergeGateUnresolvedReason {
     <#
     .SYNOPSIS
-        Returns '<code>: <epic detail>; <parallel detail>' when neither run branch resolved, or $null.
+        Returns '<code>: <item detail>; <epic detail>; <parallel detail>' when no target resolved, or $null.
     .DESCRIPTION
-        The ambiguity code wins when either target is Ambiguous. Returns $null when either
-        target is absent (a bare command) or either target resolved.
+        The ambiguity code of the first Ambiguous target among item, epic, and parallel
+        wins; otherwise the item target's code is used. Returns $null when any target is
+        absent (a bare command) or any target resolved.
+    .PARAMETER ItemTarget
+        The item target, or $null.
     .PARAMETER EpicTarget
         The epic run target, or $null.
     .PARAMETER ParallelTarget
@@ -205,17 +224,55 @@ function Get-EpicMergeGateUnresolvedReason {
     [CmdletBinding()]
     [OutputType([string])]
     param(
+        [AllowNull()] $ItemTarget,
         [AllowNull()] $EpicTarget,
         [AllowNull()] $ParallelTarget
     )
 
-    if ($null -eq $EpicTarget -or $null -eq $ParallelTarget) {
+    if ($null -eq $ItemTarget -or $null -eq $EpicTarget -or $null -eq $ParallelTarget) {
         return $null
     }
+    $targets = @($ItemTarget, $EpicTarget, $ParallelTarget)
     $unresolved = @('NoTarget', 'Ambiguous')
-    if ($unresolved -notcontains $EpicTarget.Status -or $unresolved -notcontains $ParallelTarget.Status) {
-        return $null
+    foreach ($target in $targets) {
+        if ($unresolved -notcontains $target.Status) {
+            return $null
+        }
+    }
+    $ambiguous = @($targets | Where-Object { $_.Status -eq 'Ambiguous' })
+    $code = if ($ambiguous.Count -gt 0) { $ambiguous[0].ReasonCode } else { $ItemTarget.ReasonCode }
+    return ('{0}: {1}; {2}; {3}' -f $code, $ItemTarget.Detail, $EpicTarget.Detail, $ParallelTarget.Detail)
+}
+
+function Test-EpicMergeGateNoRecordingTarget {
+    <#
+    .SYNOPSIS
+        True only when the item, epic, and parallel targets all have status NoTarget (issue #927).
+    .DESCRIPTION
+        Pure. That combination means no checkpoint records the command's pull request number,
+        which is the only case the docs-only merge branch evaluates. A $null target (a bare
+        command), an Ambiguous target, and any resolved target return $false.
+    .PARAMETER ItemTarget
+        The item target, or $null.
+    .PARAMETER EpicTarget
+        The epic run target, or $null.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $ItemTarget,
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget
+    )
+
+    foreach ($target in @($ItemTarget, $EpicTarget, $ParallelTarget)) {
+        if ($null -eq $target -or [string]$target.Status -cne 'NoTarget') {
+            return $false
+        }
     }
-    $code = if ($EpicTarget.Status -eq 'Ambiguous') { $EpicTarget.ReasonCode } elseif ($ParallelTarget.Status -eq 'Ambiguous') { $ParallelTarget.ReasonCode } else { $EpicTarget.ReasonCode }
-    return ('{0}: {1}; {2}' -f $code, $EpicTarget.Detail, $ParallelTarget.Detail)
+    return $true
 }

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

@@ -1,11 +1,12 @@
 <#
 .SYNOPSIS
-    Pre-tool-use hook that gates gh pr merge --merge behind epic-mode checkpoint state.
+    Pre-tool-use hook that gates every pull-request merge or merge-queue enqueue behind checkpoint state.
 
 .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 four
+    command runs. Brings every gh pr merge invocation except a pure --disable-auto, and every gh
+    api merge or enqueue mutation, into scope from the envelope's tool_input.command and, when
+    matched, allows the action only when one of four
     checkpoint-only conditions holds:
 
       1. Child-feature path: artifacts/orchestration/orchestrator-state.json exists,
@@ -31,17 +32,30 @@
     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,
-    policy-level-not-cryptographic posture already accepted for
-    enforce-pr-author-skill.ps1's own receipt mechanism. It is not a cryptographic control.
+    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
+    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
+    session worktree and allows the merge when conditions M1-M9 of that file hold. Otherwise
+    the deny gains " (docs-only exemption not applied: <Reason>)", where the reason may be
+    DOCS_ONLY_EXEMPTION_PR_UNRESOLVED. The hook never fetches; --match-head-commit, when
+    present, must equal headRefOid (OD-2). Residual limits: an ambient GH_REPO or GH_HOST is
+    not visible in the command text; gh and git run in the session worktree root, so a cd
+    made by an earlier Bash call is not visible either; and a push after the lookup can
+    change the head unless --match-head-commit is passed. Like the receipt mechanism of
+    enforce-pr-author-skill.ps1, this is a policy-level control, not a cryptographic one.
 
     Issue #690: with an explicit PR number, the epic and parallel checkpoints are read
-    beneath the live worktree whose run checkpoint records that number, and the child
-    branch binds the number to pr_gate.pr_number when the per-feature checkpoint records
-    it. A bare command reads every checkpoint beneath the session worktree.
+    beneath the live worktree whose run checkpoint records that number. Issue #850: with
+    an explicit PR number, the per-feature checkpoint is read beneath the live worktree
+    whose checkpoint records the number in pr_gate.pr_number or a standalone record, and
+    the child branch requires that checkpoint to bind the number (issue #788). A bare
+    command reads every checkpoint beneath the session worktree.
 
 .NOTES
     Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 through the
@@ -57,16 +71,21 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 # 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')
+try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
 # Standalone-merge authorization predicates and the two decision-envelope factories (issue #670).
-. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-authorization.ps1' -ErrorRecord $_ }
 # Checkpoint read seams, the import guard, and run-target resolution (issue #690).
-. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-resolution.ps1' -ErrorRecord $_ }
+# Merge and enqueue scope predicate and the PR selector reader (issue #952).
+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 $_ }
 
 function ConvertFrom-EpicMergeGateJson {
     <#
@@ -98,21 +117,13 @@ 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.
+        The number is resolved by Get-EpicMergeGateSelectorPrNumber in
+        enforce-epic-merge-gate-command.ps1 (issue #952), from the segment that structurally
+        invokes gh pr merge or gh api and never from the whole command line: value flags are
+        skipped with their values, an all-digit or /pull/<n> URL selector is accepted, and a
+        pulls/<n>/merge path supplies the number for gh api. A command with no resolvable number
+        yields $null, which the parallel and standalone branches treat as fail-closed. No
+        whole-line digit scan exists, so a cd path component can never supply the number.
     .PARAMETER CommandText
         The Bash command text under evaluation.
     .OUTPUTS
@@ -125,18 +136,7 @@ function Get-EpicMergeGateCommandPrNumber {
         [string] $CommandText
     )
 
-    foreach ($operand in @(Get-CommandLineOperand -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
-        if ($operand -match '^\d+$') {
-            return [int]$operand
-        }
-    }
-
-    $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
+    return Get-EpicMergeGateSelectorPrNumber -CommandText $CommandText
 }
 
 function Test-ChildCheckpointAllowsEpicMerge {
@@ -312,10 +312,8 @@ function Invoke-EpicMergeGateDecision {
     )
 
     # A failed worktree-resolution import denies before any other logic (issue #690).
-    $importFailure = Get-EpicMergeGateImportFailureDecision
-    if ($null -ne $importFailure) {
-        return $importFailure
-    }
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_MERGE_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -330,36 +328,26 @@ function Invoke-EpicMergeGateDecision {
         return Get-EpicMergeGateAllowDecision
     }
 
-    # Only a gh pr merge invocation carrying --merge is in scope for this gate; every
-    # 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) {
+    # Scope (issue #952): every gh pr merge invocation except a pure --disable-auto, and every gh api
+    # merge or enqueue mutation, is gated; Test-EpicMergeGateCommandInScope holds the predicate.
+    if (-not (Test-EpicMergeGateCommandInScope -CommandText $commandText)) {
         return Get-EpicMergeGateAllowDecision
     }
 
     $commandPrNumber = Get-EpicMergeGateCommandPrNumber -CommandText $commandText
     $sessionRoot = Get-EpicMergeGateSessionWorktreeRoot
 
-    # The child merges from its own worktree, so its checkpoint is the session worktree's;
-    # a recorded pr_gate.pr_number must match an explicit command PR number (issue #690).
-    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $sessionRoot))
+    # With an explicit PR number, the per-feature checkpoint is read beneath the live
+    # worktree whose checkpoint records the number in pr_gate.pr_number or a standalone
+    # record (issue #850); an unresolved item target reads none. A bare command reads the
+    # session worktree. The checkpoint read must still bind the number (issue #788).
+    $itemTarget = $null
+    $childRoot = $sessionRoot
+    if ($null -ne $commandPrNumber) {
+        $itemTarget = Resolve-EpicMergeGateItemTarget -PrNumber $commandPrNumber
+        $childRoot = if (@('SessionRoot', 'OtherWorktree') -contains $itemTarget.Status) { $itemTarget.WorktreeRoot } else { $null }
+    }
+    $childCheckpoint = if ($childRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $childRoot)) } else { $null }
     if ((Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) -and
         (Test-ChildCheckpointPrGateBinding -Checkpoint $childCheckpoint -CommandPrNumber $commandPrNumber)) {
         return Get-EpicMergeGateAllowDecision
@@ -396,13 +384,23 @@ function Invoke-EpicMergeGateDecision {
         if ($standalone.Allowed) {
             return Get-EpicMergeGateAllowDecision
         }
-        # When neither run branch resolved, its reason code and detail precede the standalone reason.
-        $unresolved = Get-EpicMergeGateUnresolvedReason -EpicTarget $epicTarget -ParallelTarget $parallelTarget
+        # Docs-only branch (issue #927): evaluated only when no checkpoint records the PR.
+        $docsOnlySuffix = ''
+        if (Test-EpicMergeGateNoRecordingTarget -ItemTarget $itemTarget -EpicTarget $epicTarget -ParallelTarget $parallelTarget) {
+            $docsOnly = Get-DocsOnlyMergeExemption -CommandText $commandText -PrNumber $commandPrNumber -WorktreeRoot $sessionRoot
+            if ($docsOnly.Exempt) {
+                return Get-EpicMergeGateAllowDecision
+            }
+            $docsOnlySuffix = ' (docs-only exemption not applied: ' + $docsOnly.Reason + ')'
+        }
+        # When neither the item target nor a run branch resolved, the reason code and the
+        # 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)
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message + $docsOnlySuffix)
     }
 
-    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.'
+    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.'
 }
 
 function Invoke-EpicMergeGateEntryPoint {
@@ -447,6 +445,9 @@ function Invoke-EpicMergeGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_MERGE_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_MERGE_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 # The entry point returns its [int] exit code as the last pipeline element and the
 # decision JSON before it. `exit (<call>)` would capture BOTH into the exit
@@ -456,4 +457,4 @@ if ($entryPointResult.Count -gt 1) {
     $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-exit ([int]$entryPointResult[-1])
+exit ([int]$entryPointResult[-1])