@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

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

@@ -0,0 +1,233 @@
+<#
+.SYNOPSIS
+    Artifact-root resolution and the Check 1 body-path binding for enforce-pr-author-skill.ps1 (issue #850).
+
+.DESCRIPTION
+    Dot-sourced by enforce-pr-author-skill-helpers.ps1 after its module imports. Holds:
+
+    - Resolve-PrAuthorArtifactRoot, which resolves once per call the worktree whose
+      artifacts/ tree the gate reads: the epic checkpoint's worktree under epic scope, or
+      the item worktree identity resolution selects. The PR context summary, the body, and
+      the receipt are composed beneath that root, so a gate running in the session worktree
+      no longer reads another item's artifacts from its own process directory.
+    - Get-PrAuthorBodyPathBindingReason, the Check 1 binding: a relative canonical
+      --body-file value is accepted only when the resolved worktree is the session worktree,
+      because gh reads a relative path from its own process directory; an absolute value is
+      accepted only when it equals the canonical path beneath the resolved root.
+    - Test-PrAuthorBodyPathEqual and Get-PrAuthorEpicArtifactRoot, the pure path helpers.
+    - ConvertTo-PrAuthorBodyNumber, the strict body-number parse (issue #901, #850 note L19).
+
+.NOTES
+    PowerShell 7+. Depends, at call time, on Get-PrAuthorBodyFileValue and
+    Get-PrAuthorTargetCheckpointResolution from the helpers file and on the worktree-resolution
+    modules it imports. It reads no file. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+#>
+[CmdletBinding()]
+param()
+
+function Test-PrAuthorBodyPathEqual {
+    <#
+    .SYNOPSIS
+        Compare two paths: case-insensitive for drive-letter and UNC paths, case-sensitive otherwise.
+    .PARAMETER Left
+        The first path, in either separator style.
+    .PARAMETER Right
+        The second path, in either separator style.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Left,
+        [AllowNull()][AllowEmptyString()][string] $Right
+    )
+
+    $a = ConvertTo-WorktreeResolutionNormalizedPath -Path $Left
+    $b = ConvertTo-WorktreeResolutionNormalizedPath -Path $Right
+    if ($null -eq $a -or $null -eq $b) {
+        return $false
+    }
+    $comparison = if ($a -match '^([A-Za-z]:|//)' -or $b -match '^([A-Za-z]:|//)') {
+        [System.StringComparison]::OrdinalIgnoreCase
+    }
+    else {
+        [System.StringComparison]::Ordinal
+    }
+    return [string]::Equals($a, $b, $comparison)
+}
+
+function Get-PrAuthorEpicArtifactRoot {
+    <#
+    .SYNOPSIS
+        Return the worktree root that holds an epic checkpoint path, or $null.
+    .PARAMETER CheckpointPath
+        The absolute epic checkpoint path the epic-scope resolver composed.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $CheckpointPath
+    )
+
+    $normalized = ConvertTo-WorktreeResolutionNormalizedPath -Path $CheckpointPath
+    $suffix = '/' + (Get-EpicScopeCheckpointRelativePath)
+    if ($null -eq $normalized -or -not $normalized.EndsWith($suffix, [System.StringComparison]::Ordinal)) {
+        return $null
+    }
+    $root = $normalized.Substring(0, $normalized.Length - $suffix.Length)
+    if ($root.Length -eq 0) {
+        return $null
+    }
+    return $root
+}
+
+function Resolve-PrAuthorArtifactRoot {
+    <#
+    .SYNOPSIS
+        Resolve, once per call, the worktree whose artifacts the gate reads (issue #850).
+    .DESCRIPTION
+        Epic scope: the root is the worktree holding the epic checkpoint, and a relative body
+        path is allowed only when that root is the session worktree. Otherwise the item target
+        is resolved by identity; an unresolved target returns its resolution reason unchanged,
+        and a relative body path is allowed only for a SessionRoot target.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with Reason, ArtifactRoot,
+        CheckpointPath, EpicScope, Status, and RelativeBodyAllowed.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    $epicScope = Resolve-EpicScopeCheckpoint -Text $CommandText -SessionRoot (Get-Location).Path
+    if ($null -ne $epicScope -and $epicScope.IsEpicScope) {
+        $root = Get-PrAuthorEpicArtifactRoot -CheckpointPath $epicScope.CheckpointPath
+        $reason = $null
+        $relativeAllowed = $false
+        if ($null -eq $root) {
+            $reason = "ORCHESTRATOR_STATE_PREFLIGHT_FAILED: the epic checkpoint path '$($epicScope.CheckpointPath)' does not end with '$(Get-EpicScopeCheckpointRelativePath)', so the worktree that holds it cannot be derived."
+        }
+        else {
+            $relativeAllowed = Test-PrAuthorBodyPathEqual -Left $root -Right $epicScope.WorktreeRoot
+        }
+        return [ordered]@{
+            Reason              = $reason
+            ArtifactRoot        = $root
+            CheckpointPath      = $epicScope.CheckpointPath
+            EpicScope           = $epicScope
+            Status              = 'Epic'
+            RelativeBodyAllowed = $relativeAllowed
+        }
+    }
+
+    $resolution = Get-PrAuthorTargetCheckpointResolution -CommandText $CommandText
+    $resolved = -not $resolution.Reason
+    return [ordered]@{
+        Reason              = $resolution.Reason
+        ArtifactRoot        = if ($resolved) { ConvertTo-WorktreeResolutionNormalizedPath -Path $resolution.WorktreeRoot } else { $null }
+        CheckpointPath      = $resolution.CheckpointPath
+        EpicScope           = $null
+        Status              = $resolution.Status
+        RelativeBodyAllowed = ($resolved -and $resolution.Status -eq 'SessionRoot')
+    }
+}
+
+function ConvertTo-PrAuthorBodyNumber {
+    <#
+    .SYNOPSIS
+        Parse the <N> of artifacts/pr_body_<N>.md, or return $null.
+    .DESCRIPTION
+        Accepts only ASCII digits that parse as an Int32 and whose canonical invariant spelling
+        equals the input, so a value above Int32.MaxValue, a leading zero, and a non-ASCII
+        decimal digit all return $null instead of throwing or naming a different file.
+    .PARAMETER Digits
+        The digit run captured from the body-file name.
+    .OUTPUTS
+        System.Int32 or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $Digits
+    )
+
+    $number = 0
+    $parsed = [int]::TryParse($Digits, [System.Globalization.NumberStyles]::None, [System.Globalization.CultureInfo]::InvariantCulture, [ref] $number)
+    if (-not $parsed -or $number.ToString([System.Globalization.CultureInfo]::InvariantCulture) -cne $Digits) {
+        return $null
+    }
+    return $number
+}
+
+function Get-PrAuthorBodyPathBindingReason {
+    <#
+    .SYNOPSIS
+        Check 1: bind the --body-file value to the canonical body path beneath the artifact root.
+    .DESCRIPTION
+        Reads the value once through Get-PrAuthorBodyFileValue. A relative
+        artifacts/pr_body_<N>.md (case-sensitive) is accepted only when RelativeBodyAllowed is
+        true; otherwise the deny names the absolute canonical path to pass instead. An absolute
+        value is accepted only when it equals that canonical path under Test-PrAuthorBodyPathEqual.
+        Any other value, including no readable value, denies with the generic text.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER ArtifactRoot
+        The resolved worktree root the artifacts are read beneath.
+    .PARAMETER RelativeBodyAllowed
+        Whether a relative body path is read from the resolved worktree.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with Reason and BodyNumber.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText,
+
+        [Parameter(Mandatory)]
+        [string] $ArtifactRoot,
+
+        [bool] $RelativeBodyAllowed
+    )
+
+    $generic = "PR_BODY_PATH_NONCANONICAL: ``--body-file`` must reference the canonical ``artifacts/pr_body_<N>.md`` file produced by the pr-author skill beneath the target worktree '$ArtifactRoot' (relative only when that worktree is the session worktree). The path supplied does not match."
+    $value = ConvertTo-WorktreeResolutionNormalizedPath -Path (Get-PrAuthorBodyFileValue -CommandText $CommandText)
+    if ($null -eq $value) {
+        return [ordered]@{ Reason = $generic; BodyNumber = $null }
+    }
+
+    if ($value -cmatch '^artifacts/pr_body_(\d+)\.md$') {
+        $number = ConvertTo-PrAuthorBodyNumber -Digits $Matches[1]
+        if ($null -eq $number) {
+            return [ordered]@{ Reason = $generic; BodyNumber = $null }
+        }
+        if (-not $RelativeBodyAllowed) {
+            $canonical = Join-WorktreeResolutionPath -WorktreeRoot $ArtifactRoot -RepoRelativePath "artifacts/pr_body_$number.md"
+            return [ordered]@{
+                Reason     = "PR_BODY_PATH_NONCANONICAL: the target worktree '$ArtifactRoot' is not the session worktree, so gh would read a relative --body-file from the session worktree. Pass the absolute canonical path '$canonical'."
+                BodyNumber = $null
+            }
+        }
+        return [ordered]@{ Reason = $null; BodyNumber = $number }
+    }
+
+    if ($value -match '/artifacts/pr_body_(\d+)\.md$') {
+        $number = ConvertTo-PrAuthorBodyNumber -Digits $Matches[1]
+        if ($null -ne $number) {
+            $canonical = Join-WorktreeResolutionPath -WorktreeRoot $ArtifactRoot -RepoRelativePath "artifacts/pr_body_$number.md"
+            if (Test-PrAuthorBodyPathEqual -Left $value -Right $canonical) {
+                return [ordered]@{ Reason = $null; BodyNumber = $number }
+            }
+        }
+    }
+
+    return [ordered]@{ Reason = $generic; BodyNumber = $null }
+}

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

@@ -0,0 +1,224 @@
+<#
+.SYNOPSIS
+    Docs-only exemption from the checkpoint preflight of enforce-pr-author-skill.ps1 (issue #901).
+
+.DESCRIPTION
+    Dot-sourced by enforce-pr-author-skill-helpers.ps1. Get-PrAuthorBypassReason calls
+    Get-PrAuthorDocsOnlyExemption only in its non-epic branch and only after
+    Invoke-OrchestratorStatePreflight reports errors. The exemption lets a gh pr create call
+    continue to the receipt checks when the branch changes nothing outside docs/. It fails
+    closed: every condition below must hold, and the first that does not names the sub-code
+    the caller appends to its ORCHESTRATOR_STATE_PREFLIGHT_FAILED denial.
+
+      E1 DOCS_ONLY_EXEMPTION_NOT_CREATE         - the command is a structural gh pr create.
+      E2 DOCS_ONLY_EXEMPTION_CHECKPOINT_PRESENT - no checkpoint file exists at the resolved path.
+      E3 DOCS_ONLY_EXEMPTION_BASE_UNRESOLVED    - exactly one explicit --base, a conservative branch
+                                                  spelling without '..', and no base or repository
+                                                  override: no single-dash token whose letters
+                                                  include B or R (-B, -R, -dB, -Rx), no --repo or
+                                                  --repo= token, and no inline GH_REPO= prefix.
+      E4 DOCS_ONLY_EXEMPTION_BASE_UNRESOLVED    - refs/remotes/origin/<base> resolves to a commit.
+      E5 DOCS_ONLY_EXEMPTION_DIFF_FAILED        - git diff <commit>...HEAD exits 0 without throwing,
+                                                  and non-empty output ends with NUL.
+      E6 DOCS_ONLY_EXEMPTION_EMPTY_DIFF         - the diff lists at least one path.
+      E7 DOCS_ONLY_EXEMPTION_NON_DOCS_PATH      - every path starts with docs/ (ordinal).
+
+    The diff runs with --no-renames so a rename from outside docs/ reports its old path, with -z
+    so no path is quoted, and with --no-relative, --no-color, and --no-ext-diff so repository
+    configuration cannot change the listing.
+
+    Residual limit: a GH_REPO value exported by an earlier shell command or inherited from the
+    session environment is not visible in the command text, so this file cannot detect it.
+
+.NOTES
+    PowerShell 7+. Depends, at call time, on Test-CommandLineInvocation,
+    Get-CommandLineStructuralMatch, and Get-CommandLineFlagValue from the command parsers the
+    helpers file loads. It reads no file content. The git executable runs only through
+    Invoke-PrAuthorDocsOnlyGitExe, the single executable seam, which never throws. Mirrored
+    byte-identically under extensions/drm-copilot/resources/claude-customizations/.
+    Dot-sources hook-docs-only-diff.ps1 (issue #927), whose Get-DocsOnlyDiffTextViolation
+    performs the E5 NUL check and the E6 and E7 path classification.
+#>
+[CmdletBinding()]
+param()
+. (Join-Path $PSScriptRoot 'hook-docs-only-diff.ps1')
+
+function Invoke-PrAuthorDocsOnlyGitExe {
+    <#
+    .SYNOPSIS
+        Run git -C <root> with the given arguments. The single executable seam; tests mock it.
+    .DESCRIPTION
+        Never throws: an uncaught error ends the hook with exit 1, which PreToolUse treats as
+        non-blocking, so a throw here would allow the call. A root that is not an existing
+        directory, or a git that cannot start, returns ExitCode -1. Standard error is discarded
+        so that it is never read as path data.
+    .PARAMETER WorktreeRoot
+        The resolved worktree root git runs in.
+    .PARAMETER GitArgs
+        The git arguments that follow -C <root>.
+    .PARAMETER GitInvoker
+        The scriptblock that runs git; a unit test passes a test-local stand-in so that this
+        body runs without starting a process.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with ExitCode and Output.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot,
+        [Parameter(Mandatory)][string[]] $GitArgs,
+        [ValidateNotNull()][scriptblock] $GitInvoker = { git @args 2>$null }
+    )
+
+    $failure = [pscustomobject]@{ ExitCode = -1; Output = '' }
+    if ([string]::IsNullOrWhiteSpace($WorktreeRoot) -or -not (Test-Path -LiteralPath $WorktreeRoot -PathType Container)) {
+        return $failure
+    }
+    try {
+        $lines = @(& $GitInvoker -C $WorktreeRoot @GitArgs 2>$null)
+        $code = $LASTEXITCODE
+    }
+    catch {
+        return $failure
+    }
+    return [pscustomobject]@{ ExitCode = [int]$code; Output = ($lines -join "`n") }
+}
+
+function Test-PrAuthorDocsOnlyCheckpointPresence {
+    <#
+    .SYNOPSIS
+        Return $true when a checkpoint file exists at the path, and also for a blank path.
+    .DESCRIPTION
+        A blank path cannot prove that no checkpoint exists, so it reports presence (fail closed).
+    .PARAMETER CheckpointPath
+        The absolute checkpoint path identity resolution composed.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $CheckpointPath
+    )
+
+    if ([string]::IsNullOrWhiteSpace($CheckpointPath)) {
+        return $true
+    }
+    return (Test-Path -LiteralPath $CheckpointPath -PathType Leaf)
+}
+
+function Get-PrAuthorDocsOnlyBaseName {
+    <#
+    .SYNOPSIS
+        Return the single explicit --base value of a gh pr create command, or $null.
+    .DESCRIPTION
+        Returns $null when the command is not a structural gh pr create; when a single-dash
+        token has B or R among its letters (-B base and -R repository, alone or clustered as in
+        -dB or -dR); when a token is --repo, starts with --repo=, or starts with GH_REPO=; when
+        --base appears other than exactly once; when its value is missing or dash-leading; when
+        the value is not a conservative branch spelling; or when it contains '..'.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string] $CommandText
+    )
+
+    $subcommandPath = @('pr', 'create')
+    $match = Get-CommandLineStructuralMatch -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath
+    if ($null -eq $match) {
+        return $null
+    }
+    $baseTokenCount = 0
+    foreach ($token in @($match.Segment.Tokens)) {
+        $text = [string]$token
+        if ($text.Length -ge 2 -and $text[0] -eq '-' -and $text[1] -ne '-' -and $text.Substring(1).IndexOfAny([char[]]@('B', 'R')) -ge 0) {
+            return $null
+        }
+        if ($text -eq '--repo' -or $text.StartsWith('--repo=', [System.StringComparison]::OrdinalIgnoreCase) -or $text.StartsWith('GH_REPO=', [System.StringComparison]::OrdinalIgnoreCase)) {
+            return $null
+        }
+        if ($text -eq '--base' -or $text.StartsWith('--base=', [System.StringComparison]::OrdinalIgnoreCase)) {
+            $baseTokenCount++
+        }
+    }
+    if ($baseTokenCount -ne 1) {
+        return $null
+    }
+    $base = Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--base'
+    if ($null -eq $base -or $base -cnotmatch '^[A-Za-z0-9][A-Za-z0-9._/-]*$' -or $base.Contains('..')) {
+        return $null
+    }
+    return $base
+}
+
+function Get-PrAuthorDocsOnlyExemption {
+    <#
+    .SYNOPSIS
+        Decide whether a failed preflight is exempt because the branch changes only docs/.
+    .DESCRIPTION
+        Evaluates E1 to E7 of the file header in order and returns at the first failure.
+        Each git call is wrapped so that a throwing seam denies rather than escapes.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER WorktreeRoot
+        The resolved worktree root the diff is computed in.
+    .PARAMETER CheckpointPath
+        The resolved checkpoint path whose absence E2 requires.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with Exempt and Reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)][string] $CommandText,
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot,
+        [AllowNull()][AllowEmptyString()][string] $CheckpointPath
+    )
+
+    if (-not (Test-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'create'))) {
+        return [ordered]@{ Exempt = $false; Reason = 'DOCS_ONLY_EXEMPTION_NOT_CREATE: only gh pr create is eligible.' }
+    }
+    if (Test-PrAuthorDocsOnlyCheckpointPresence -CheckpointPath $CheckpointPath) {
+        return [ordered]@{ Exempt = $false; Reason = "DOCS_ONLY_EXEMPTION_CHECKPOINT_PRESENT: a checkpoint file exists at '$CheckpointPath', so its preflight governs." }
+    }
+    $base = Get-PrAuthorDocsOnlyBaseName -CommandText $CommandText
+    if ($null -eq $base) {
+        return [ordered]@{ Exempt = $false; Reason = 'DOCS_ONLY_EXEMPTION_BASE_UNRESOLVED: pass exactly one explicit --base <branch>; -B, -R, --repo, a single-dash shorthand cluster containing B or R, and an inline GH_REPO= prefix are not accepted.' }
+    }
+
+    $baseRef = 'refs/remotes/origin/' + $base + '^{commit}'
+    try {
+        $revParse = Invoke-PrAuthorDocsOnlyGitExe -WorktreeRoot $WorktreeRoot -GitArgs @('rev-parse', '--verify', '--quiet', $baseRef)
+    }
+    catch {
+        $revParse = $null
+    }
+    $commit = ''
+    if ($null -ne $revParse) {
+        $commit = ([string]$revParse.Output).Trim()
+    }
+    if ($null -eq $revParse -or $revParse.ExitCode -ne 0 -or $commit -cnotmatch '^[0-9a-f]{40}([0-9a-f]{24})?$') {
+        return [ordered]@{ Exempt = $false; Reason = "DOCS_ONLY_EXEMPTION_BASE_UNRESOLVED: refs/remotes/origin/$base does not resolve to a commit in the target worktree." }
+    }
+
+    try {
+        $diff = Invoke-PrAuthorDocsOnlyGitExe -WorktreeRoot $WorktreeRoot -GitArgs @('diff', '--name-only', '-z', '--no-renames', '--no-color', '--no-ext-diff', '--no-relative', ($commit + '...HEAD'))
+    }
+    catch {
+        $diff = $null
+    }
+    if ($null -eq $diff -or $diff.ExitCode -ne 0) {
+        return [ordered]@{ Exempt = $false; Reason = "DOCS_ONLY_EXEMPTION_DIFF_FAILED: git diff against origin/$base could not be computed." }
+    }
+
+    $violation = Get-DocsOnlyDiffTextViolation -DiffText ([string]$diff.Output) -BaseName $base
+    if ($violation) {
+        return [ordered]@{ Exempt = $false; Reason = $violation }
+    }
+    return [ordered]@{ Exempt = $true; Reason = $null }
+}

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

@@ -19,18 +19,49 @@
     Block cases:
       Case A - gh pr create or gh pr edit with --body (inline, no --body-file): blocked.
       Case B - gh pr create with neither --body nor --body-file: blocked.
-      Case C - gh pr create or gh pr edit with --body-file but context artifact absent: blocked.
+      Case C - gh pr create or gh pr edit with --body-file but context artifact absent beneath
+               the resolved worktree: blocked.
       Preflight - --body-file/context present: orchestrator-state checkpoint must pass
                   --require-pr-creation-ready before receipt verification runs, else blocked.
-      Receipt - preflight passed: the SHA-256 receipt is verified in five ordered checks
-                (Section below). The first failing check blocks.
+      Docs-only - issue #901: when the preflight fails, gh pr create proceeds to receipt
+                  verification only when every condition holds: no checkpoint file exists
+                  beneath the resolved worktree; the command carries exactly one explicit
+                  --base <branch> and no base or repository override (issue #927: no
+                  single-dash token whose letters include B or R, such as -B, -R, or -dB; no
+                  --repo or --repo= token; no inline GH_REPO= prefix); refs/remotes/origin/<branch>
+                  resolves to a commit; git diff --name-only -z --no-renames <commit>...HEAD
+                  exits 0, ends its non-empty output with NUL, and lists at least one path; and
+                  every listed path starts with docs/ (ordinal, case-sensitive). Otherwise the
+                  deny keeps ORCHESTRATOR_STATE_PREFLIGHT_FAILED and appends one sub-code:
+                    DOCS_ONLY_EXEMPTION_NOT_CREATE         - gh pr edit is never exempt.
+                    DOCS_ONLY_EXEMPTION_CHECKPOINT_PRESENT - a checkpoint file exists.
+                    DOCS_ONLY_EXEMPTION_BASE_UNRESOLVED    - no single explicit --base, a base or
+                                                             repository override is present, or
+                                                             the base does not resolve on origin.
+                    DOCS_ONLY_EXEMPTION_DIFF_FAILED        - the diff exits non-zero, throws, or
+                                                             returns output not ending with NUL.
+                    DOCS_ONLY_EXEMPTION_EMPTY_DIFF         - the diff lists no path.
+                    DOCS_ONLY_EXEMPTION_NON_DOCS_PATH      - a listed path is outside docs/.
+                  The exemption never applies under epic scope.
+      Receipt - preflight passed or docs-only exemption applied: the SHA-256 receipt is
+                verified in the ordered checks (Section below). The first failing check blocks.
 
     Receipt verification decision order on the --body-file-with-context path:
       PR_BODY_PATH_NONCANONICAL -> PR_AUTHOR_RECEIPT_MISSING -> PR_AUTHOR_RECEIPT_NUMBER_MISMATCH
       -> PR_AUTHOR_RECEIPT_HASH_MISMATCH -> PR_AUTHOR_RECEIPT_STALE -> allow.
 
+    Issue #850: the context summary, the body, and the receipt are read beneath the worktree
+    the call resolves to (the item worktree, or the epic checkpoint's worktree under epic
+    scope), not beneath the process directory, so a gate running in the session worktree
+    validates the artifacts of the item it gates.
+
 .NOTES
-    Compatible with PowerShell 7+. No external module dependencies.
+    Compatible with PowerShell 7+. Dependencies are in-repository only: hook-dependency-guard.ps1,
+    the HookPayload, OrchestratorState, and OrchestratorStateUnconditional modules, and the
+    epic-base-branch and helpers siblings; the helpers load the command parsers, the
+    worktree-resolution modules, and the artifact-root and docs-only siblings.
+    No PowerShell Gallery module is required.
+    The docs-only exemption runs the git executable at call time (issue #901).
 
     Enforcement strength: the SHA-256 receipt is a policy-level integrity check that binds the
     PR body bytes to the receipt the pr-author agent wrote. It is not a cryptographic or security
@@ -42,28 +73,34 @@
 #>
 [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 $_ }
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
 # 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
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorState.psm1' -ErrorRecord $_ }
 
 function Get-PrContextArtifactExistence {
     <#
     .SYNOPSIS
         Wrapper around Test-Path for the PR context artifact. Tests mock this function.
+    .PARAMETER Path
+        The absolute path of artifacts/pr_context.summary.txt beneath the resolved worktree.
     .OUTPUTS
         System.Boolean
     #>
     [CmdletBinding()]
     [OutputType([bool])]
-    param()
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
 
-    return [bool](Test-Path -LiteralPath $script:PrContextArtifactPath)
+    return [bool](Test-Path -LiteralPath $Path)
 }
 
 function Get-PrBodyFileBytes {
@@ -75,7 +112,8 @@ function Get-PrBodyFileBytes {
         This is the injectable boundary for body-file bytes in tests; no test writes the body file
         to disk. The bytes are hashed inline by the receipt verification function.
     .PARAMETER BodyFilePath
-        The relative path to the PR body file (for example artifacts/pr_body_5.md).
+        The absolute path to the PR body file beneath the resolved worktree (for example
+        <worktree>/artifacts/pr_body_5.md).
     .OUTPUTS
         System.Byte[] or $null
     #>
@@ -103,7 +141,8 @@ function Get-PrAuthorReceiptContent {
         or $null when the receipt file is absent. This is the injectable boundary for receipt
         content in tests; no test writes the receipt file to disk.
     .PARAMETER ReceiptFilePath
-        The relative path to the receipt file (for example artifacts/pr_body_5.receipt.json).
+        The absolute path to the receipt file beneath the resolved worktree (for example
+        <worktree>/artifacts/pr_body_5.receipt.json).
     .OUTPUTS
         System.String or $null
     #>
@@ -129,25 +168,32 @@ function Get-PrContextSummaryLastWriteUtc {
         Returns the LastWriteTimeUtc of artifacts/pr_context.summary.txt, or $null when the file is
         absent. The staleness check compares the receipt's created_at against this value; both are
         artifact metadata, so no wall-clock seam is required.
+    .PARAMETER Path
+        The absolute path of artifacts/pr_context.summary.txt beneath the resolved worktree.
     .OUTPUTS
         System.DateTime or $null
     #>
     [CmdletBinding()]
     [OutputType([datetime])]
-    param()
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
 
-    if (-not (Test-Path -LiteralPath $script:PrContextArtifactPath)) {
+    if (-not (Test-Path -LiteralPath $Path)) {
         return $null
     }
 
-    return (Get-Item -LiteralPath $script:PrContextArtifactPath).LastWriteTimeUtc
+    return (Get-Item -LiteralPath $Path).LastWriteTimeUtc
 }
 
-. (Join-Path $PSScriptRoot 'enforce-pr-author-skill.epic-base-branch.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-pr-author-skill.epic-base-branch.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-pr-author-skill.epic-base-branch.ps1' -ErrorRecord $_ }
 
 # Dot-source the receipt-verification and bypass-reason helpers. Guarded so dot-sourcing this
 # hook in tests loads the helpers too (issue #501 headroom split).
-. (Join-Path $PSScriptRoot 'enforce-pr-author-skill-helpers.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-pr-author-skill-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-pr-author-skill-helpers.ps1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateUnconditional.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateUnconditional.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorState.psm1' -ErrorRecord $_ }
 
 function Invoke-PrAuthorSkillDecision {
     <#
@@ -168,6 +214,8 @@ function Invoke-PrAuthorSkillDecision {
         [AllowEmptyString()]
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PR_AUTHOR_SKILL_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -182,8 +230,7 @@ function Invoke-PrAuthorSkillDecision {
         return Get-PrAuthorSkillAllowDecision
     }
 
-    $contextExists = Get-PrContextArtifactExistence
-    $reason = Get-PrAuthorBypassReason -CommandText $commandText -ContextExists $contextExists
+    $reason = Get-PrAuthorBypassReason -CommandText $commandText
 
     if ($reason) {
         return Get-PrAuthorSkillBlockDecision -Reason $reason
@@ -242,8 +289,6 @@ function Test-PrAuthorBypassRequired {
         Return $true when a Bash command requires the pr-author skill to run first.
     .PARAMETER CommandText
         The Bash command text extracted from the envelope's tool_input.
-    .PARAMETER ContextExists
-        Whether artifacts/pr_context.summary.txt currently exists on disk.
     .OUTPUTS
         System.Boolean
     #>
@@ -251,13 +296,10 @@ function Test-PrAuthorBypassRequired {
     [OutputType([bool])]
     param(
         [Parameter(Mandatory)]
-        [string] $CommandText,
-
-        [Parameter(Mandatory)]
-        [bool] $ContextExists
+        [string] $CommandText
     )
 
-    return ($null -ne (Get-PrAuthorBypassReason -CommandText $CommandText -ContextExists $ContextExists))
+    return ($null -ne (Get-PrAuthorBypassReason -CommandText $CommandText))
 }
 
 function Invoke-PrAuthorSkillEntryPoint {
@@ -302,6 +344,9 @@ function Invoke-PrAuthorSkillEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PR_AUTHOR_SKILL_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PR_AUTHOR_SKILL_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