@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner-helpers.ps1

@@ -10,13 +10,16 @@
     cap as target resolution grows.
 
     The file declares no file-scope parameter block, no requires directive, and no
-    entrypoint. Apart from its function declarations,
-    its only file-scope statement is the resolution-module import
-    that follows this block, which brings in issue #669's path normalisation and
-    ambiguity reason code. That import is deliberately unguarded, for the same
-    reason the parent hook's is: a resolution module that cannot be loaded is
-    itself the target-not-resolvable state, so letting the failure surface fails
-    the gate closed rather than degrading it to a permissive path.
+    entrypoint. Apart from its function declarations, its file-scope statements are
+    the resolution-module import that follows this block, which brings in issue
+    #669's path normalisation and ambiguity reason code, and the guarded dot-source
+    of the pure shared resolver feature-folder-resolution.ps1 (issue #565), which
+    owns the single work-mode parser. The module import is deliberately unguarded,
+    for the same reason the parent hook's is: a resolution module that cannot be
+    loaded is itself the target-not-resolvable state, so letting the failure surface
+    fails the gate closed rather than degrading it to a permissive path. A failed
+    dot-source of the shared resolver makes Resolve-PrdFeatureWorkMode return $null,
+    which the planner gate's deny-on-unknown branch treats as an unreadable marker.
 .NOTES
     Compatible with PowerShell 7+. Read-only resolution logic.
 #>
@@ -24,7 +27,17 @@
 # Issue #669 owns path normalisation and the ambiguity reason code. The import is
 # unguarded for the same reason the parent's is: a resolution module that cannot be
 # loaded is itself the target-not-resolvable state.
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeResolution.psm1') -Force
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeResolution.psm1') -Force -ErrorAction Stop
+
+# Shared work-mode parser (issue #565). Guarded so a failed dot-source fails closed
+# through the planner gate's deny-on-unknown branch.
+$script:PrdFeatureFolderResolutionImportFailure = $null
+try {
+    . (Join-Path $PSScriptRoot 'feature-folder-resolution.ps1')
+}
+catch {
+    $script:PrdFeatureFolderResolutionImportFailure = 'feature-folder-resolution.ps1'
+}
 
 function Resolve-PrdFeatureWorkMode {
     <#
@@ -36,7 +49,10 @@ function Resolve-PrdFeatureWorkMode {
         Recognizes minor-audit, full-feature, full-bug, and the legacy full
         marker (normalized to full-feature), mirroring the regex convention
         used by scripts/dev_tools/prompt_mode_contract.py so both runtimes
-        agree on what counts as a valid marker line.
+        agree on what counts as a valid marker line. Delegates to the single
+        shared parser, Resolve-FeatureFolderWorkMode (issue #565), with an empty
+        -UnresolvedMode so an unresolved marker still returns $null here; a
+        failed dot-source of the shared resolver also returns $null.
     #>
     [CmdletBinding()]
     [OutputType([string])]
@@ -45,20 +61,15 @@ function Resolve-PrdFeatureWorkMode {
         [string] $IssueContent
     )
 
-    if ([string]::IsNullOrWhiteSpace($IssueContent)) {
+    if ($script:PrdFeatureFolderResolutionImportFailure) {
         return $null
     }
 
-    $match = [regex]::Match($IssueContent, '(?im)^-\s*Work Mode:\s*(minor-audit|full-feature|full-bug|full)\s*$')
-    if (-not $match.Success) {
+    $mode = Resolve-FeatureFolderWorkMode -IssueContent $IssueContent -UnresolvedMode ''
+    if (-not $mode) {
         return $null
     }
-
-    $rawMode = $match.Groups[1].Value
-    if ($rawMode -eq 'full') {
-        return 'full-feature'
-    }
-    return $rawMode
+    return $mode
 }
 
 function Get-PrdFeatureRequiredFile {

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner.ps1

@@ -98,9 +98,10 @@
 #>
 [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 $_ }
 # Issue #669 owns worktree location and path normalisation; issue #673 owns the
 # portable-identity resolution this gate now selects a worktree with. Both imports are
 # unguarded on purpose: a resolution module that cannot be loaded is itself the
@@ -108,9 +109,9 @@ Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -
 # a permissive path. Both are required rather than one: the absolute-path join the probe
 # step below calls is exported only by the first, because a module whose exports are pinned
 # by an explicit list does not re-export a sibling's functions to its own importer.
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeTargetResolution.psm1') -Force
-Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force
-. (Join-Path $PSScriptRoot 'enforce-prd-feature-before-planner-helpers.ps1')
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeTargetResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeTargetResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'enforce-prd-feature-before-planner-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-prd-feature-before-planner-helpers.ps1' -ErrorRecord $_ }
 function Get-PrdFeatureFileExistence {
     <#
     .SYNOPSIS
@@ -316,6 +317,8 @@ function Invoke-PrdFeatureBeforePlannerDecision {
         [AllowNull()]
         [object] $ResolvedTarget
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PRD_FEATURE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $envelope.IsValid) {
@@ -469,6 +472,9 @@ function Invoke-PrdFeatureBeforePlannerDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PRD_FEATURE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PRD_FEATURE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $decision = Invoke-PrdFeatureBeforePlannerDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
 

package/resources/claude-customizations/.claude/hooks/enforce-promotion-mcp-only.ps1

@@ -28,15 +28,16 @@
 #>
 [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). Every forbidden-token scan and both `gh`
 # expressions below run against each segment's clause-ordered scan text, and the
 # structural matcher reaches the relocating `gh` spellings adjacency cannot.
-. (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 $_ }
 
 $script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drm-copilot MCP promotion tools instead.'
 
@@ -112,9 +113,12 @@ function Get-PromotionBypassReason {
     }
 
     # `gh issue create` and `gh issue new` are direct bypasses of the MCP
-    # promotion path. Tolerate any flags after the subcommand.
+    # promotion path. Tolerate any flags after the subcommand. The adjacency
+    # expression reads the masked text, so a quoted mention is not a match; wrapper
+    # payloads and substitution bodies are covered by the structural check below
+    # (issue #824).
     foreach ($segment in $segments) {
-        if ($segment.ScanText -match '(?i)\bgh\s+issue\s+(?:create|new)\b') {
+        if ($segment.MaskedText -match '(?i)\bgh\s+issue\s+(?:create|new)\b') {
             return (Get-PromotionMcpOnlyGhIssueBlockedReason)
         }
     }
@@ -227,6 +231,8 @@ function Invoke-PromotionMcpOnlyDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PROMOTION_MCP_ONLY_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -291,6 +297,9 @@ function Invoke-PromotionMcpOnlyEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PROMOTION_MCP_ONLY_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PROMOTION_MCP_ONLY_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

package/resources/claude-customizations/.claude/hooks/enforce-python-batch-budget.ps1

@@ -57,10 +57,11 @@
 #>
 [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
-. (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1')
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-batch-budget-route.ps1' -ErrorRecord $_ }
 
 function Test-PythonBatchBudgetPathInRoot {
     <#
@@ -280,6 +281,8 @@ function Invoke-PythonBatchBudgetDecision {
         [AllowEmptyString()]
         [string] $ObservedRoute = ''
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PYTHON_LARGE_PATH_REQUIRED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $normalized = $FilePath -replace '\\', '/'
     if ($normalized -notmatch '\.py$') {
@@ -477,6 +480,9 @@ function Invoke-PythonBatchBudgetEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PYTHON_LARGE_PATH_REQUIRED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PYTHON_LARGE_PATH_REQUIRED:'
+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