@danmoisan/drm-copilot-mcp 1.0.7 → 1.0.9

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

@@ -23,9 +23,11 @@
         variables.feature-folder);
       - a ci_gate object with conclusion == "success" and a non-empty head_sha.
 
-    The block reason names the specific missing evidence so the caller can
-    remediate. When completion is not asserted, the write is allowed
-    (backward compatibility).
+    When completion evidence is missing the hook emits a PreToolUse JSON
+    response with hookSpecificOutput.permissionDecision='deny' and a reason that
+    names the specific missing evidence so the caller can remediate. When
+    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
@@ -39,6 +41,11 @@
 [CmdletBinding()]
 param()
 
+# 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
+
 function ConvertFrom-CheckpointJson {
     <#
     .SYNOPSIS
@@ -53,6 +60,29 @@ function ConvertFrom-CheckpointJson {
     return $Json | ConvertFrom-Json -ErrorAction Stop
 }
 
+function Get-CheckpointFileContent {
+    <#
+    .SYNOPSIS
+        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.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+}
+
 function Test-IsCheckpointPath {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -149,7 +179,13 @@ function Get-MissingCompletionEvidence {
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
-        $Payload
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     $missing = @()
@@ -158,16 +194,17 @@ function Get-MissingCompletionEvidence {
     if (-not $issueNum -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $issueNum = Get-CheckpointStringValue -Payload $Payload.variables -Name 'issue-num'
     }
-    if (-not $issueNum) {
-        $missing += 'issue-num'
+    if (-not (Test-IsValidIssueNum -Value $issueNum)) {
+        # Name the offending value so sentinel/placeholder inputs are explicit.
+        $missing += "issue-num value '$issueNum' is not a valid issue number (must be digits-only)"
     }
 
     $featureFolder = Get-CheckpointStringValue -Payload $Payload -Name 'feature-folder'
     if (-not $featureFolder -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $featureFolder = Get-CheckpointStringValue -Payload $Payload.variables -Name 'feature-folder'
     }
-    if (-not $featureFolder) {
-        $missing += 'feature-folder'
+    if (-not (Test-IsValidFeatureFolder -Value $featureFolder -FolderExistsCheck $FolderExistsCheck)) {
+        $missing += "feature-folder value '$featureFolder' is not a valid feature folder (must be under docs/features/active/ and exist)"
     }
 
     $ciGate = $null
@@ -188,7 +225,14 @@ function Get-MissingCompletionEvidence {
         }
     }
 
-    if ($issueNum -eq '232') {
+    # PR-gate evidence is required only when the checkpoint's selected route
+    # opts into it via requires_pr_gate in the routing matrix. This replaces the
+    # former issue-number special-casing with route-driven enforcement.
+    $prGateArgs = @{ Payload = $Payload }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $prGateArgs['RoutingMatrixReader'] = $RoutingMatrixReader
+    }
+    if (Test-RouteRequiresPrGate @prGateArgs) {
         $prGate = $null
         if ($null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'pr_gate')) {
             $prGate = $Payload.pr_gate
@@ -213,6 +257,60 @@ function Get-MissingCompletionEvidence {
     return [string[]]$missing
 }
 
+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.
+    .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).
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput,
+
+        [Parameter(Mandatory)]
+        [scriptblock] $CheckpointReader
+    )
+
+    $oldString = $null
+    if ($null -ne $ToolInput -and ($ToolInput.PSObject.Properties.Name -contains 'old_string')) {
+        $oldString = [string]$ToolInput.old_string
+    }
+    if ([string]::IsNullOrEmpty($oldString)) {
+        return $null
+    }
+
+    $newString = ''
+    if ($ToolInput.PSObject.Properties.Name -contains 'new_string') {
+        $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
+    }
+
+    $onDiskText = [string]$onDisk
+    if (-not $onDiskText.Contains($oldString)) {
+        # The old_string is not present, so the patch does not apply here.
+        return $null
+    }
+
+    # Apply the patch in memory using a literal (non-regex) replacement.
+    return $onDiskText.Replace($oldString, $newString)
+}
+
 function Invoke-CompletionConsistencyDecision {
     <#
     .SYNOPSIS
@@ -222,11 +320,20 @@ function Invoke-CompletionConsistencyDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $ToolInputRaw
+        [string] $ToolInputRaw,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $CheckpointReader = { param($Path) Get-CheckpointFileContent -Path $Path },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     if (-not $ToolInputRaw) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     try {
@@ -238,19 +345,25 @@ function Invoke-CompletionConsistencyDecision {
 
     $filePath = $toolInput.file_path
     if (-not $filePath) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $normalized = $filePath -replace '\\', '/'
     if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload. Edit tool: partial new_string is
-    # not reliable without the full target file content, so 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) {
-        return [ordered]@{ decision = 'allow' }
+        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+        if (-not $content) {
+            # No content, and the Edit could not be resolved against on-disk
+            # state (missing file or non-matching patch): defer and allow.
+            return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+        }
     }
 
     try {
@@ -259,26 +372,29 @@ function Invoke-CompletionConsistencyDecision {
     catch {
         # The content itself is not valid JSON. Let downstream tools surface the
         # error rather than blocking with a misleading reason here.
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     if (-not (Test-CompletionAsserted -Payload $payload)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    $missing = Get-MissingCompletionEvidence -Payload $payload
-    if ($missing.Count -eq 0) {
-        return [ordered]@{ decision = 'allow' }
+    $missingArgs = @{ Payload = $payload; FolderExistsCheck = $FolderExistsCheck }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $missingArgs['RoutingMatrixReader'] = $RoutingMatrixReader
     }
-
-    $issueContext = ''
-    if ((Get-CheckpointStringValue -Payload $payload -Name 'issue-num') -eq '232') {
-        $issueContext = ' Issue #232 requires pr_gate evidence and current-head ci_gate evidence.'
+    $missing = Get-MissingCompletionEvidence @missingArgs
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
+    $reason = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', '). A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha; routes whose requires_pr_gate is true must also include pr_gate evidence with a matching head_sha. Supply the missing evidence or remove the completion assertion."
     return [ordered]@{
-        decision = 'block'
-        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', ').$issueContext A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha. Supply the missing evidence or remove the completion assertion."
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $reason
+        }
     }
 }
 
@@ -295,6 +411,6 @@ catch {
     exit 1
 }
 
-$decision | ConvertTo-Json -Compress | Write-Output
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
 exit 0

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

@@ -0,0 +1,163 @@
+<#
+.SYNOPSIS
+    Dot-sourced helper functions for enforce-completion-consistency.ps1.
+
+.DESCRIPTION
+    Provides testable validation helpers used by the completion-consistency
+    PreToolUse hook:
+
+      - Test-IsValidIssueNum: rejects sentinel/placeholder and non-digit issue
+        numbers; accepts digits-only strings.
+      - 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.
+
+    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.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+[CmdletBinding()]
+param()
+
+# Sentinel/placeholder values that must never satisfy a presence check.
+$script:CompletionEvidenceSentinels = @('n/a', 'none', 'tbd')
+
+function Test-IsValidIssueNum {
+    <#
+    .SYNOPSIS
+        Returns $true only for a digits-only issue number.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, a sentinel
+        (n/a, none, tbd; case-insensitive), or contains any non-digit character.
+        Returns $true only when the trimmed value matches ^\d+$.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    # Sentinel placeholders are explicitly rejected even though they are
+    # non-empty strings; the comparison is case-insensitive.
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+    return $trimmed -match '^\d+$'
+}
+
+function Test-IsValidFeatureFolder {
+    <#
+    .SYNOPSIS
+        Returns $true only for a sentinel-free feature folder anchored under
+        docs/features/active/ with a non-empty trailing segment that exists.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, or a sentinel
+        (n/a, none, tbd; case-insensitive). Requires the value to start with
+        'docs/features/active/' and to carry at least one additional non-empty
+        path segment after that prefix. Invokes the injectable FolderExistsCheck
+        scriptblock (default Test-Path -PathType Container) and returns $false
+        when it reports the folder does not exist.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container }
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+
+    $prefix = 'docs/features/active/'
+    $normalized = $trimmed -replace '\\', '/'
+    if (-not $normalized.StartsWith($prefix)) {
+        return $false
+    }
+
+    # Require a non-empty segment after the active/ prefix so the bare prefix is
+    # not accepted as a valid folder.
+    $suffix = $normalized.Substring($prefix.Length).TrimEnd('/')
+    if ([string]::IsNullOrWhiteSpace($suffix)) {
+        return $false
+    }
+
+    return [bool](& $FolderExistsCheck $normalized)
+}
+
+function Test-RouteRequiresPrGate {
+    <#
+    .SYNOPSIS
+        Returns $true when the payload's selected route opts into the PR gate.
+    .DESCRIPTION
+        Resolves the route id from the payload (route_id, falling back to
+        path_selected), looks it up in the routing matrix returned by the
+        injectable RoutingMatrixReader seam, and returns $true only when that
+        route's requires_pr_gate value is the boolean $true. A missing route id,
+        an unknown route, a matrix without routes, or a missing/false
+        requires_pr_gate returns $false. This generalizes the former issue-232
+        special-casing into a route-driven check.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader = {
+            $configPath = Join-Path $PSScriptRoot '../../config/orchestration-routing.json'
+            if (-not (Test-Path -LiteralPath $configPath)) { return $null }
+            Get-Content -LiteralPath $configPath -Raw | ConvertFrom-Json
+        }
+    )
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+
+    # Resolve the selected route id, preferring route_id over path_selected.
+    $routeId = ''
+    if ($Payload.PSObject.Properties.Name -contains 'route_id') {
+        $routeId = ([string]$Payload.route_id).Trim()
+    }
+    if (-not $routeId -and ($Payload.PSObject.Properties.Name -contains 'path_selected')) {
+        $routeId = ([string]$Payload.path_selected).Trim()
+    }
+    if (-not $routeId) {
+        return $false
+    }
+
+    $matrix = & $RoutingMatrixReader
+    if ($null -eq $matrix -or -not ($matrix.PSObject.Properties.Name -contains 'routes')) {
+        return $false
+    }
+    $routes = $matrix.routes
+    if ($null -eq $routes -or -not ($routes.PSObject.Properties.Name -contains $routeId)) {
+        return $false
+    }
+    $route = $routes.$routeId
+    if ($null -eq $route -or -not ($route.PSObject.Properties.Name -contains 'requires_pr_gate')) {
+        return $false
+    }
+    return ([bool]$route.requires_pr_gate -eq $true)
+}