@danmoisan/drm-copilot-mcp 1.1.17 → 1.1.19

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -2,7 +2,7 @@ default_permissions = ":danger-full-access"
 
 [mcp_servers.drm-copilot]
 command = "npx"
-args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.17"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.19"]
 required = true
 enabled_tools = [
     "collect_commit_context",

package/resources/codex-and-agents-customizations/.codex/hooks/check-powershell-test-purity.ps1

@@ -32,10 +32,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 function Get-PowerShellTestPurityBlockDecision {
     [CmdletBinding()]
@@ -72,6 +73,8 @@ function Invoke-PowerShellTestPurityDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-powershell-test-purity:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return $null
@@ -145,6 +148,9 @@ function Invoke-PowerShellTestPurityDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('check-powershell-test-purity: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-powershell-test-purity:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. A well-formed payload

package/resources/codex-and-agents-customizations/.codex/hooks/check-python-test-purity.ps1

@@ -29,10 +29,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 function Get-PythonTestPurityBlockDecision {
     [CmdletBinding()]
@@ -69,6 +70,8 @@ function Invoke-PythonTestPurityDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-python-test-purity:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return $null
@@ -145,6 +148,9 @@ function Invoke-PythonTestPurityDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('check-python-test-purity: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-python-test-purity:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. A well-formed payload

package/resources/codex-and-agents-customizations/.codex/hooks/codex-epic-child-launch-attestation.ps1

@@ -2,7 +2,7 @@
 
 $contractPath = Join-Path (Split-Path $PSScriptRoot -Parent) 'scripts/epic-child-launch-contract.ps1'
 if (Test-Path -LiteralPath $contractPath -PathType Leaf) {
-    . $contractPath
+    try { . $contractPath } catch { Add-HookDependencyFailure -Name 'epic-child-launch-contract.ps1' -ErrorRecord $_ }
 }
 
 $script:CodexEpicChildContexts = @('epic_preparation_child', 'epic_execution_child')

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-checkpoint-monotonic.ps1

@@ -43,10 +43,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 # The only path this hook governs. On-disk reconstruction of an apply_patch
 # Update is requested for this path alone, so a patch that merely happens to
@@ -214,6 +215,8 @@ function Invoke-CheckpointMonotonicDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'CHECKPOINT_ORDER_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
@@ -312,6 +315,9 @@ function Invoke-CheckpointMonotonicDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('CHECKPOINT_ORDER_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'CHECKPOINT_ORDER_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. Update reconstruction is

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-codex-model-routing.ps1

@@ -4,9 +4,10 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
-. (Join-Path $PSScriptRoot 'codex-authority-store.ps1')
-. (Join-Path $PSScriptRoot 'codex-agent-profile-attestation.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-authority-store.ps1') } catch { Add-HookDependencyFailure -Name 'codex-authority-store.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'codex-agent-profile-attestation.ps1') } catch { Add-HookDependencyFailure -Name 'codex-agent-profile-attestation.ps1' -ErrorRecord $_ }
 
 $script:CodexModelGateRepositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 
@@ -91,6 +92,8 @@ function Invoke-CodexModelRoutingDecision {
         [Parameter(Mandatory)][string] $PayloadRaw,
         [AllowNull()][AllowEmptyString()][string] $AttestationRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_ATTESTATION_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-CodexModelGateJson -Raw $PayloadRaw -Name 'PreToolUse input'
     if ([string]::IsNullOrWhiteSpace($AttestationRaw)) {
@@ -150,6 +153,9 @@ function Get-CodexModelGateDenyDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('MODEL_ROUTING_ATTESTATION_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_ATTESTATION_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-consistency.ps1

@@ -29,32 +29,37 @@
     completion is not asserted, the write is allowed via
     hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
-    Edit tool calls supply only old_string/new_string (a partial patch) and
-    cannot be reliably validated without the full target file content, so they
-    are allowed by this hook, matching enforce-checkpoint-monotonic.ps1. For
-    Write calls whose content is not valid JSON, the hook allows the operation
-    and defers to downstream tools to surface the error.
+    Edit tool calls supply only old_string/new_string (a partial patch). An Edit
+    call is validated by reading the checkpoint at the Edit's targeted file_path
+    through the injectable CheckpointReader seam and applying the old_string ->
+    new_string replacement in memory; the resulting content is then evaluated
+    like a Write. One occurrence of old_string is replaced unless replace_all is
+    true. The hook fails closed: a missing, empty, or unreadable targeted
+    checkpoint, an absent or empty old_string, zero or ambiguous occurrences of
+    old_string, and a Write with empty content all deny, and the deny reason
+    names the cause. Write content or patched content that is not valid JSON is
+    also denied, because the canonical checkpoint is required to stay valid JSON.
 
 .NOTES
     Compatible with PowerShell 7+. Read-only validation gate.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Reuse the adjacent hook's shared checkpoint policy logic. This dot-source is by
 # design, not a copy-paste defect, so the hook is not renamed.
-. (Join-Path $PSScriptRoot 'enforce-checkpoint-monotonic.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-checkpoint-monotonic.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-checkpoint-monotonic.ps1' -ErrorRecord $_ }
 
 # Shared Codex PreToolUse transport. Dot-sourced explicitly rather than relying on
 # the transitive load above, so this hook's transport does not depend on its
 # neighbour's internals. Every transport error it raises names this hook, because
 # the shared parser is called with -HookName 'enforce-completion-consistency'.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 # Dot-source the shared validation helpers. Guarded so a missing file produces a
 # clear error and so dot-sourcing this hook in tests loads the helpers too.
-$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
-. $script:CompletionHelpersPath
+try { . (Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-completion-helpers.ps1' -ErrorRecord $_ }
 
 function ConvertFrom-CheckpointJson {
     <#
@@ -76,9 +81,10 @@ function Get-CheckpointFileContent {
         Reads the on-disk checkpoint content for the read-then-validate Edit path.
     .DESCRIPTION
         Returns the full file text when the path resolves to a file on disk, or
-        $null when the file does not exist. Tests inject a CheckpointReader
-        scriptblock instead of mocking this function so no temporary files are
-        required.
+        $null when the file does not exist. An existing empty file yields an
+        empty string, never $null, so a missing checkpoint and an empty
+        checkpoint stay distinct. Tests inject a CheckpointReader scriptblock
+        instead of mocking this function so no temporary files are required.
     #>
     [CmdletBinding()]
     [OutputType([string])]
@@ -90,7 +96,9 @@ function Get-CheckpointFileContent {
     if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    $text = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    if ($null -eq $text) { return '' }
+    return [string]$text
 }
 
 function Test-IsCheckpointPath {
@@ -270,26 +278,34 @@ function Get-MissingCompletionEvidence {
 function Resolve-EditedCheckpointContent {
     <#
     .SYNOPSIS
-        Returns the patched checkpoint content for an Edit-tool call, or $null
-        when the patch cannot be applied against the on-disk checkpoint.
+        Returns an object with Content and Failure for an Edit-tool call: the
+        patched checkpoint content on success, or a failure cause when the patch
+        cannot be applied against the targeted checkpoint.
     .DESCRIPTION
-        Implements the read-then-validate Edit path. When the tool input carries
-        an old_string (an Edit patch), the on-disk checkpoint is read through the
-        injectable CheckpointReader seam and the old_string -> new_string
-        replacement is applied in memory (no on-disk mutation). Returns $null
-        when there is no old_string, the on-disk file does not exist, or the
-        old_string is not present in the on-disk content, signalling the caller
-        to allow (defer).
+        Implements the read-then-validate Edit path. The checkpoint at the
+        caller-supplied CheckpointPath (the Edit's targeted file_path, passed to
+        the reader unchanged) is read through the injectable CheckpointReader seam
+        and the old_string -> new_string replacement is applied in memory (no
+        on-disk mutation). One occurrence of old_string is replaced unless
+        replace_all is true. Failure is one of no-old_string (absent or empty
+        old_string), checkpoint-unreadable (the reader threw), checkpoint-missing
+        (the reader returned $null), checkpoint-empty (the reader returned an
+        empty string), old_string-not-found, or old_string-ambiguous. Content is
+        $null on failure and Failure is $null on success. The caller denies on
+        any Failure.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([pscustomobject])]
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
         $ToolInput,
 
         [Parameter(Mandatory)]
-        [scriptblock] $CheckpointReader
+        [scriptblock] $CheckpointReader,
+
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     $oldString = $null
@@ -297,7 +313,7 @@ function Resolve-EditedCheckpointContent {
         $oldString = [string]$ToolInput.old_string
     }
     if ([string]::IsNullOrEmpty($oldString)) {
-        return $null
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
     }
 
     $newString = ''
@@ -305,20 +321,46 @@ function Resolve-EditedCheckpointContent {
         $newString = [string]$ToolInput.new_string
     }
 
-    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
-    if ([string]::IsNullOrEmpty([string]$onDisk)) {
-        # The on-disk checkpoint does not exist (or is empty); cannot patch.
-        return $null
+    try {
+        $onDisk = & $CheckpointReader $CheckpointPath
+    }
+    catch {
+        # A reader exception must not escape the gate; report it as a failure cause.
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-unreadable' }
+    }
+    if ($null -eq $onDisk) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-missing' }
     }
 
     $onDiskText = [string]$onDisk
-    if (-not $onDiskText.Contains($oldString)) {
-        # The old_string is not present, so the patch does not apply here.
-        return $null
+    if ($onDiskText.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-empty' }
     }
 
-    # Apply the patch in memory using a literal (non-regex) replacement.
-    return $onDiskText.Replace($oldString, $newString)
+    # Apply the patch in memory; one occurrence unless replace_all is true.
+    $replaceAll = Get-EditReplaceAllFlag -ToolInput $ToolInput
+    return Invoke-SingleOccurrenceEdit -Text $onDiskText -OldString $oldString -NewString $newString -ReplaceAll $replaceAll
+}
+
+function ConvertTo-CompletionDenyDecision {
+    <#
+    .SYNOPSIS
+        Builds the PreToolUse deny decision for the given reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
 }
 
 function Invoke-CompletionConsistencyDecision {
@@ -341,6 +383,8 @@ function Invoke-CompletionConsistencyDecision {
         [Parameter(Mandatory = $false)]
         [scriptblock] $RoutingMatrixReader
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
@@ -363,19 +407,25 @@ function Invoke-CompletionConsistencyDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload directly. Edit tool: no content is
-    # supplied, so read the on-disk checkpoint through the injectable seam and
-    # apply the old_string -> new_string patch in memory (read-then-validate).
-    $content = $toolInput.content
-    if (-not $content) {
-        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+    # Write tool: a present content property is validated directly, and empty
+    # content is denied. Edit tool: no content property is supplied, so read the
+    # targeted checkpoint through the injectable seam and apply the old_string ->
+    # new_string patch in memory (read-then-validate). Any failure cause denies.
+    $cause = $null
+    if ($toolInput.PSObject.Properties.Name -contains 'content') {
+        $content = $toolInput.content
         if (-not $content) {
-            return [ordered]@{ hookSpecificOutput = [ordered]@{
-                    hookEventName = 'PreToolUse'; permissionDecision = 'deny'
-                    permissionDecisionReason = 'COMPLETION_CONSISTENCY_BLOCKED: the canonical checkpoint cannot be deleted, emptied, or replaced through an unresolved patch.'
-                } }
+            $cause = 'write-content-empty'
         }
     }
+    else {
+        $edit = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader -CheckpointPath $filePath
+        $content = $edit.Content
+        $cause = $edit.Failure
+    }
+    if ($cause) {
+        return ConvertTo-CompletionDenyDecision -Reason "COMPLETION_CONSISTENCY_BLOCKED: the canonical checkpoint cannot be deleted, emptied, or replaced through an unresolved patch ($cause)."
+    }
 
     try {
         $payload = ConvertFrom-CheckpointJson -Json $content
@@ -414,6 +464,9 @@ function Invoke-CompletionConsistencyDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('COMPLETION_CONSISTENCY_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # -HookName makes every transport error name this hook rather than the

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-helpers.ps1

@@ -11,6 +11,12 @@
       - Test-IsValidFeatureFolder: rejects sentinel/placeholder feature folders
         and folders not anchored under docs/features/active/<segment>; optionally
         verifies on-disk existence through an injectable scriptblock seam.
+      - Get-EditReplaceAllFlag: returns the boolean value of the replace_all
+        property of an Edit tool input; the string 'true' is honoured and the
+        string 'false' is not.
+      - Invoke-SingleOccurrenceEdit: pure single-occurrence patch of a text;
+        reports a failure cause instead of replacing when old_string is empty,
+        absent, or ambiguous.
 
     This script is dot-sourced by enforce-completion-consistency.ps1. It contains
     no entrypoint logic, so dot-sourcing it in tests has no side effects.
@@ -161,3 +167,102 @@ function Test-RouteRequiresPrGate {
     }
     return ([bool]$route.requires_pr_gate -eq $true)
 }
+
+function Get-EditReplaceAllFlag {
+    <#
+    .SYNOPSIS
+        Returns the boolean value of the replace_all property of an Edit tool input.
+    .DESCRIPTION
+        Returns $false when the tool input is null or has no replace_all property.
+        Returns the value when it is already a boolean. Returns $true for a string
+        whose trimmed, case-insensitive value is 'true'. Returns $false for every
+        other value. No [bool] cast is used because [bool]'false' is $true in
+        PowerShell.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput
+    )
+
+    if ($null -eq $ToolInput -or -not ($ToolInput.PSObject.Properties.Name -contains 'replace_all')) {
+        return $false
+    }
+
+    $value = $ToolInput.replace_all
+    if ($value -is [bool]) {
+        return $value
+    }
+    if ($value -is [string]) {
+        return $value.Trim() -ieq 'true'
+    }
+    return $false
+}
+
+function Invoke-SingleOccurrenceEdit {
+    <#
+    .SYNOPSIS
+        Applies an old_string to new_string patch to a text in memory and reports
+        a failure cause when the patch cannot be applied unambiguously.
+    .DESCRIPTION
+        Pure function with no I/O. Normalizes CRLF to LF in all three strings. An
+        empty OldString yields Failure 'no-old_string'. Zero ordinal occurrences
+        yield Failure 'old_string-not-found'. When ReplaceAll is true every
+        occurrence is replaced by ordinal String.Replace. Otherwise a second
+        ordinal search that starts after the end of the first match yields Failure
+        'old_string-ambiguous' when it finds a match (overlapping candidates are
+        counted once), and no match yields a single splice by Substring. No regular
+        expression is used, so a '$' in NewString stays literal. Returns an object
+        with Content and Failure; Content is $null on failure and Failure is $null
+        on success.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $OldString,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $NewString,
+
+        [Parameter(Mandatory = $false)]
+        [bool] $ReplaceAll = $false
+    )
+
+    $normalizedText = $Text.Replace("`r`n", "`n")
+    $normalizedOld = $OldString.Replace("`r`n", "`n")
+    $normalizedNew = $NewString.Replace("`r`n", "`n")
+
+    if ($normalizedOld.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
+    }
+
+    $comparison = [System.StringComparison]::Ordinal
+    $firstIndex = $normalizedText.IndexOf($normalizedOld, $comparison)
+    if ($firstIndex -lt 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-not-found' }
+    }
+
+    if ($ReplaceAll) {
+        return [pscustomobject]@{ Content = $normalizedText.Replace($normalizedOld, $normalizedNew); Failure = $null }
+    }
+
+    $afterFirst = $firstIndex + $normalizedOld.Length
+    if ($normalizedText.IndexOf($normalizedOld, $afterFirst, $comparison) -ge 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-ambiguous' }
+    }
+
+    $spliced = $normalizedText.Substring(0, $firstIndex) + $normalizedNew + $normalizedText.Substring($afterFirst)
+    return [pscustomobject]@{ Content = $spliced; Failure = $null }
+}

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-child-worktree-binding.ps1

@@ -10,10 +10,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 $contractPath = Join-Path (Split-Path $PSScriptRoot -Parent) 'scripts/epic-child-launch-contract.ps1'
 if (Test-Path -LiteralPath $contractPath -PathType Leaf) {
-    . $contractPath
+    try { . $contractPath } catch { Add-HookDependencyFailure -Name 'epic-child-launch-contract.ps1' -ErrorRecord $_ }
 }
 
 function ConvertFrom-CodexChildGuardJson {
@@ -218,6 +219,8 @@ function Invoke-CodexEpicChildGuardDecision {
         [Parameter(Mandatory)][AllowEmptyString()][string] $ActualSpecSha256,
         [Parameter(Mandatory)][AllowEmptyString()][string] $ActualProfileSha256
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_BINDING_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-CodexChildGuardJson -Raw $PayloadRaw -Name 'PreToolUse input'
     if ([string]::IsNullOrWhiteSpace([string]$Attestation.launch_id)) {
@@ -282,6 +285,9 @@ function Get-CodexChildGuardLiveBranch {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_WORKTREE_BINDING_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_BINDING_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-merge-gate.ps1

@@ -1,15 +1,32 @@
 <#
 .SYNOPSIS
     Gates epic child and integration PR merges behind checkpointed green state.
+
+.DESCRIPTION
+    Docs-only branch (issue #927): after the standalone branch denies an explicit PR number,
+    and only when no checkpoint is present at the repository root (both checkpoint texts are
+    blank; operator decision OD-1, stricter than the Claude per-PR rule), the gate calls
+    Get-DocsOnlyMergeExemption from hook-docs-only-diff.ps1 with the repository root. That
+    function runs gh pr view and git there and allows the merge when its conditions M1-M9
+    hold; otherwise the deny gains " (docs-only exemption not applied: <Reason>)", where the
+    reason may be DOCS_ONLY_EXEMPTION_PR_UNRESOLVED. A blank RepositoryRoot denies at M2
+    before any process starts. 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 repository root, so a cd made by an
+    earlier shell call is not visible either; a push after the lookup can change the head
+    unless --match-head-commit is passed; and the control is policy-level, not cryptographic.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared command-line parser (issue #545). The scope filter and the PR-number resolver below
 # both run against the segment that structurally invokes `gh pr merge`, which is what keeps
 # the two runtimes on one implementation of the same concern.
-. (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 $_ }
+# 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 $_ }
 
 # Reason codes for the standalone-merge authorization branch (issue #670), spelled
 # byte-identically to the Claude helpers file. Each of the four assignments below is the only
@@ -125,8 +142,11 @@ function Invoke-CodexEpicMergeDecision {
     param(
         [Parameter(Mandatory)][string] $PayloadRaw,
         [AllowNull()][AllowEmptyString()][string] $ChildCheckpointRaw,
-        [AllowNull()][AllowEmptyString()][string] $EpicCheckpointRaw
+        [AllowNull()][AllowEmptyString()][string] $EpicCheckpointRaw,
+        [AllowNull()][AllowEmptyString()][string] $RepositoryRoot
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_MERGE_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-CodexMergeJson -Raw $PayloadRaw -Name 'PreToolUse input'
     if ([string]$payload.tool_name -ne 'Bash') {
@@ -172,11 +192,20 @@ function Invoke-CodexEpicMergeDecision {
         if ($verdict.Allowed) {
             return $null
         }
+        # Docs-only branch (issue #927, OD-1): only when no checkpoint is present at the root.
+        $docsOnlySuffix = ''
+        if ([string]::IsNullOrWhiteSpace($ChildCheckpointRaw) -and [string]::IsNullOrWhiteSpace($EpicCheckpointRaw)) {
+            $docsOnly = Get-DocsOnlyMergeExemption -CommandText $command -PrNumber $prNumber -WorktreeRoot $RepositoryRoot
+            if ($docsOnly.Exempt) {
+                return $null
+            }
+            $docsOnlySuffix = ' (docs-only exemption not applied: ' + $docsOnly.Reason + ')'
+        }
         return [ordered]@{
             hookSpecificOutput = [ordered]@{
                 hookEventName            = 'PreToolUse'
                 permissionDecision       = 'deny'
-                permissionDecisionReason = 'EPIC_MERGE_GATE_BLOCKED: ' + $verdict.ReasonCode + ': ' + $verdict.Message
+                permissionDecisionReason = 'EPIC_MERGE_GATE_BLOCKED: ' + $verdict.ReasonCode + ': ' + $verdict.Message + $docsOnlySuffix
             }
         }
     }
@@ -360,6 +389,9 @@ function Test-CodexStandaloneMergeAuthorization {
 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 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()
@@ -368,7 +400,7 @@ try {
     $epicPath = Join-Path $repositoryRoot 'artifacts/orchestration/epic-orchestrator-state.json'
     $childRaw = if (Test-Path -LiteralPath $childPath -PathType Leaf) { Get-Content -Raw -LiteralPath $childPath } else { '' }
     $epicRaw = if (Test-Path -LiteralPath $epicPath -PathType Leaf) { Get-Content -Raw -LiteralPath $epicPath } else { '' }
-    $decision = Invoke-CodexEpicMergeDecision -PayloadRaw $payloadRaw -ChildCheckpointRaw $childRaw -EpicCheckpointRaw $epicRaw
+    $decision = Invoke-CodexEpicMergeDecision -PayloadRaw $payloadRaw -ChildCheckpointRaw $childRaw -EpicCheckpointRaw $epicRaw -RepositoryRoot $repositoryRoot
     if ($null -ne $decision) {
         $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
     }

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-planning-only.ps1

@@ -9,6 +9,7 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 $script:AllowedPreparationMcpTools = @(
     'mcp__drm-copilot__new_potential_entry',
@@ -209,6 +210,8 @@ function Invoke-EpicPlanningOnlyDecision {
         [AllowNull()][AllowEmptyString()][string] $CurrentBranch,
         [string] $RegistryPath = (Join-Path $script:EpicPlanningRepositoryRoot 'config/orchestration-handoff-registry.json')
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_PLANNING_ONLY_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-EpicPlanningJson -Raw $PayloadRaw -Name 'PreToolUse input'
     $attestedPreparation = $EpicExecutionContext -eq 'epic_preparation_child'
@@ -325,6 +328,9 @@ function Get-EpicPlanningCurrentBranch {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_PLANNING_ONLY_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_PLANNING_ONLY_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()