@danmoisan/drm-copilot-mcp 1.1.17 → 1.1.19

package/resources/claude-customizations/.claude/hooks/validate-bash.ps1

@@ -37,13 +37,14 @@ param(
     [Parameter(Position = 0, Mandatory = $false)]
     [string]$CommandInput
 )
+$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). Both detectors below run against the segment
 # list rather than against the unsegmented command string, so a dangerous phrase quoted
 # inside a message body is no longer a match and a relocating spelling no longer escapes.
-. (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 $_ }
 
 function Get-BlockedBashPattern {
     [CmdletBinding()]
@@ -417,6 +418,8 @@ function Invoke-ValidateBashDecision {
         [AllowNull()]
         [string] $PositionalInput
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'HOOK_DEPENDENCY_LOAD_FAILED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $commandToCheck = Get-BashCommandToCheck -ToolInputRaw $ToolInputRaw -PositionalInput $PositionalInput
 
@@ -431,6 +434,9 @@ function Invoke-ValidateBashDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('HOOK_DEPENDENCY_LOAD_FAILED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'HOOK_DEPENDENCY_LOAD_FAILED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $toolInputRaw = Read-ClaudeHookRawPayload
 

package/resources/claude-customizations/.claude/hooks/validate-discovery-artifact-gate.ps1

@@ -5,19 +5,24 @@
 
 .DESCRIPTION
     Invoked by the Claude Code SubagentStop hook under the existing broad
-    generic-agent matcher group. The hook reads $env:CLAUDE_HOOK_INPUT JSON
-    containing .output (the terminating subagent's final text), scans that
-    text for discovery-artifact path references via Get-DiscoveryArtifactType,
-    and for each recognized reference (when a required-artifact declaration is
-    present) invokes the discovery validator CLI via
-    Invoke-DiscoveryValidatorExe.
+    generic-agent matcher group. The hook reads the SubagentStop envelope JSON
+    from stdin through the shared envelope helper (subagentstop-envelope.ps1),
+    takes its last_assistant_message field (the terminating subagent's last
+    assistant message), scans that text for discovery-artifact path references
+    via Get-DiscoveryArtifactType, and for each recognized reference (when a
+    required-artifact declaration is present) invokes the discovery validator
+    via Invoke-DiscoveryValidatorExe.
 
     Any referenced artifact that fails validation blocks the subagent's
-    termination: the hook writes an error with a
-    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix and exits with a non-zero code.
-    When no reference fails validation, or when no discovery-artifact path is
-    referenced, or when the required-artifact declaration is absent
-    (fail-open), the hook allows termination.
+    termination: the hook writes the reason with a
+    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix to stderr and exits 2 through the
+    shared envelope helper. An invalid envelope (empty, not valid JSON, not a
+    JSON object, or without a string last_assistant_message) also blocks, with
+    a "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly" reason. The hook
+    allows termination when the last assistant message is blank, when it
+    references no discovery-artifact path, when the required-artifact
+    declaration is absent (fail-open), or when every referenced artifact
+    passes validation.
 
     This hook provides the authoritative, defense-in-depth check of final
     workspace state, regardless of which tool produced the artifact,
@@ -32,9 +37,13 @@
     `Test-Json -SchemaFile` Draft 2020-12 support). Read-only validation gate that
     invokes NO external process: validation runs in-process through
     `.claude/lib/discovery-validation/DiscoveryValidation.psm1` (issue #475).
+    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryValidation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryValidation.psm1' -ErrorRecord $_ }
 
 function Invoke-DiscoveryValidatorExe {
     <#
@@ -179,7 +188,7 @@ function Find-DiscoveryArtifactReference {
     $foundReferences = New-Object System.Collections.Generic.List[string]
     foreach ($token in $tokens) {
         $trimmed = $token.Trim('`', '"', "'", ',', ';', '(', ')', '[', ']')
-        if (Get-DiscoveryArtifactType -Path $trimmed) {
+        if ($trimmed -and (Get-DiscoveryArtifactType -Path $trimmed)) {
             if (-not $foundReferences.Contains($trimmed)) {
                 $foundReferences.Add($trimmed)
             }
@@ -192,35 +201,24 @@ function Find-DiscoveryArtifactReference {
 function Invoke-DiscoveryArtifactGateValidation {
     <#
     .SYNOPSIS
-        Parses CLAUDE_HOOK_INPUT and returns an Ok/Message validation result
-        for a discovery-artifact completion gate.
+        Reads the SubagentStop envelope and returns an Ok/Message validation
+        result for a discovery-artifact completion gate.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload,
+        [AllowNull()] [AllowEmptyString()] [string] $InputText,
 
         [Parameter(Mandatory = $false)]
         [scriptblock] $RequiredArtifactReader = { Get-RequiredDiscoveryArtifactDeclaration }
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
 
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'discovery artifact gate hook: CLAUDE_HOOK_INPUT is empty' }
-    }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "discovery artifact gate hook: CLAUDE_HOOK_INPUT is not valid JSON: $_" }
-    }
-
-    $outputText = ''
-    if ($null -ne $payload -and ($payload.PSObject.Properties.Name -contains 'output')) {
-        $outputText = [string]$payload.output
-    }
-
-    $references = Find-DiscoveryArtifactReference -OutputText $outputText
+    $references = Find-DiscoveryArtifactReference -OutputText $assistantMessage
     if ($references.Count -eq 0) {
         return @{ Ok = $true; Message = $null }
     }
@@ -233,10 +231,10 @@ function Invoke-DiscoveryArtifactGateValidation {
 
     foreach ($reference in $references) {
         $artifactType = Get-DiscoveryArtifactType -Path $reference
-        $result = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
-        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($result.Output)
-        if ($result.ExitCode -ne 0 -or $hasErrorOutput) {
-            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($result.Output)" }
+        $validatorResult = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
+        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($validatorResult['Output'])
+        if ($validatorResult['ExitCode'] -ne 0 -or $hasErrorOutput) {
+            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($validatorResult['Output'])" }
         }
     }
 
@@ -247,11 +245,11 @@ function Invoke-DiscoveryArtifactGateValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('DISCOVERY_ARTIFACT_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 
-$result = Invoke-DiscoveryArtifactGateValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+try { $result = Invoke-DiscoveryArtifactGateValidation }
+catch { Exit-SubagentStopBlock -Message ('DISCOVERY_ARTIFACT_GATE_BLOCKED: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + 'This condition is not repairable by the subagent. Report it to the operator and halt.') }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0

package/resources/claude-customizations/.claude/hooks/validate-executor-output.ps1

@@ -7,7 +7,7 @@
     plan state satisfy the executor's mechanical contract.
 
     Enforced checks:
-      - hook payload is valid JSON and contains non-empty output,
+      - the SubagentStop envelope read from stdin carries a non-empty last_assistant_message,
       - output advertises `plan-path: <path>` (or supported equivalent forms),
       - the advertised plan exists on disk,
       - preflight-only runs return an exact preflight signal and may not claim
@@ -20,17 +20,25 @@
         output includes a PASS or FAIL status line for that language.
 
 .NOTES
-    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
-    termination; exits 1 with an error message to block. Plan file contents are
-    read through Get-PlanFileContent so tests can mock the filesystem boundary
-    without writing temporary files.
+    Reads the SubagentStop envelope from stdin through Read-SubagentStopEnvelope
+    (subagentstop-envelope.ps1); the assistant text comes from the helper's
+    AssistantText. A non-repairable condition blocks once: when StopHookActive is
+    set, the re-entered stop is allowed. Exits 0 to allow termination; a block is
+    written to stderr with exit 2 through Exit-SubagentStopBlock. The dependency
+    guard and the E1 helper are guarded loads: a failure blocks with exit 2,
+    naming the file. Plan file contents are read through Get-PlanFileContent so
+    tests can mock the filesystem boundary without writing temporary files.
+    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
 #>
 
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 Set-StrictMode -Version Latest
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 $ErrorActionPreference = 'Stop'
+$script:SubagentStopReportAndHaltLine = 'This condition is not repairable by the subagent. Report it to the operator and halt.'
 
 function Get-PlanFileContent {
     [CmdletBinding()]
@@ -83,7 +91,7 @@ function Test-IsPreflightPlan {
     [OutputType([bool])]
     param(
         [Parameter(Mandatory = $true)]
-        [string[]] $Lines
+        [AllowEmptyString()] [string[]] $Lines
     )
 
     return @($Lines | Where-Object { $_ -match '(?i)^\s*DIRECTIVE:\s*PREFLIGHT VALIDATION ONLY\s*$' }).Count -gt 0
@@ -94,7 +102,7 @@ function Get-TouchedLanguagesFromPlan {
     [OutputType([string[]])]
     param(
         [Parameter(Mandatory = $true)]
-        [string[]] $Lines
+        [AllowEmptyString()] [string[]] $Lines
     )
 
     $languages = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
@@ -176,54 +184,74 @@ function Test-HasCanonicalBlockedText {
 }
 
 function Invoke-ExecutorOutputValidation {
+    <#
+    .SYNOPSIS
+        Reads the SubagentStop envelope, validates the assistant text, and applies the re-entry policy.
+    #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload
+        [AllowNull()] [AllowEmptyString()] [string] $InputText
     )
 
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'atomic-executor hook: CLAUDE_HOOK_INPUT is empty; cannot validate executor output.' }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { $decision = @{ Ok = $false; Repairable = $false; Message = ('{0} payload anomaly - {1}' -f 'atomic-executor hook:', (Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)) } }
+    else {
+        $agentOutput = $envelope.AssistantText
+        $decision = Get-ExecutorOutputBlockDecision -AgentOutput ([string]$agentOutput)
     }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "atomic-executor hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+    if ($decision.Ok) { return @{ Ok = $true; Message = $null } }
+    if (-not $decision.Repairable) {
+        if ($envelope.StopHookActive) { return @{ Ok = $true; Message = $null } }
+        if (-not $decision.Message.Contains('to the operator and halt.')) { $decision.Message = $decision.Message + "`n" + $script:SubagentStopReportAndHaltLine }
     }
+    return @{ Ok = $false; Message = $decision.Message }
+}
+
+function Get-ExecutorOutputBlockDecision {
+    <#
+    .SYNOPSIS
+        Applies the executor completion checks to the assistant text and returns the block decision.
+    .DESCRIPTION
+        Returns @{ Ok = $true; Message = $null } to allow, or a hashtable with Ok = $false, a
+        Repairable boolean, and Message. Repairable is $false for a non-preflight BLOCKED claim
+        and for a plan with no task checkboxes; every other block is repairable by the subagent.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $AgentOutput
+    )
 
-    $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
-        $agentOutput = $payload.output
-    }
     if ([string]::IsNullOrWhiteSpace($agentOutput)) {
-        return @{ Ok = $false; Message = 'atomic-executor hook: agent output is empty; executor must return plan-path and final completion summary.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: agent output is empty (last_assistant_message carries no text); executor must return plan-path and final completion summary.' }
     }
 
     $planPath = Get-PlanPathFromOutput -AgentOutput $agentOutput
     if ($null -eq $planPath) {
-        return @{ Ok = $false; Message = 'atomic-executor hook: agent output does not advertise a plan-path. Executor must report `plan-path: <path>` per atomic-plan-contract.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: agent output does not advertise a plan-path. Executor must report `plan-path: <path>` per atomic-plan-contract.' }
     }
 
     $file = Get-PlanFileContent -Path $planPath
     if (-not $file.Exists) {
-        return @{ Ok = $false; Message = "atomic-executor hook: executor advertised plan-path '$planPath' but no file exists at that location." }
+        return @{ Ok = $false; Repairable = $true; Message = "atomic-executor hook: executor advertised plan-path '$planPath' but no file exists at that location." }
     }
 
     $isPreflight = Test-IsPreflightPlan -Lines $file.Lines
     if ($isPreflight) {
         if (-not (Test-HasCanonicalBlockedText -AgentOutput $agentOutput)) {
-            return @{ Ok = $false; Message = 'atomic-executor hook: blocked preflight output must include the exact text `BLOCKED at preflight (before [P0-T1])` plus a concrete plan delta.' }
+            return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: blocked preflight output must include the exact text `BLOCKED at preflight (before [P0-T1])` plus a concrete plan delta.' }
         }
         if ($agentOutput -notmatch 'BLOCKED' -and -not (Test-HasPreflightSignal -AgentOutput $agentOutput)) {
-            return @{ Ok = $false; Message = 'atomic-executor hook: preflight output must include `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`.' }
+            return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: preflight output must include `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`.' }
         }
         return @{ Ok = $true; Message = $null }
     }
 
     if ($agentOutput -match 'BLOCKED') {
-        return @{ Ok = $false; Message = 'atomic-executor hook: blocking is permitted only during preflight validation (before [P0-T1]).' }
+        return @{ Ok = $false; Repairable = $false; Message = 'atomic-executor hook: blocking is permitted only during preflight validation (before [P0-T1]).' }
     }
 
     $checkboxLineCount = 0
@@ -243,7 +271,7 @@ function Invoke-ExecutorOutputValidation {
     }
 
     if ($checkboxLineCount -eq 0) {
-        return @{ Ok = $false; Message = "atomic-executor hook: plan file '$planPath' contains no task checkboxes; executor cannot complete against an empty plan." }
+        return @{ Ok = $false; Repairable = $false; Message = "atomic-executor hook: plan file '$planPath' contains no task checkboxes; executor cannot complete against an empty plan." }
     }
 
     if ($uncheckedLineNumbers.Count -gt 0) {
@@ -255,17 +283,17 @@ function Invoke-ExecutorOutputValidation {
         }
         $lineList = ($reported -join ', ')
         $message = "atomic-executor hook: plan file '$planPath' has $($uncheckedLineNumbers.Count) unchecked task(s) at line(s) ${lineList}${suffix}. All `- [ ]` items must be ticked to `- [x]` before termination."
-        return @{ Ok = $false; Message = $message }
+        return @{ Ok = $false; Repairable = $true; Message = $message }
     }
 
     if ($agentOutput -notmatch '(?i)\bAC Status Summary\b') {
-        return @{ Ok = $false; Message = 'atomic-executor hook: completion output must include an `AC Status Summary` section.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: completion output must include an `AC Status Summary` section.' }
     }
 
-    $hasCommandEvidence = $agentOutput -match '(?i)(Commands Run|Command[s]?:|poetry run |npx |pwsh |git |mcp__drm-copilot__)'
+    $hasCommandEvidence = $agentOutput -match '(?i)(Commands Run|Command[s]?:|poetry[ ]run |npx |pwsh |git |mcp__drm-copilot__)'
     $hasStatusEvidence = $agentOutput -match '(?i)\b(PASS|FAIL)\b'
     if (-not $hasCommandEvidence -or -not $hasStatusEvidence) {
-        return @{ Ok = $false; Message = 'atomic-executor hook: completion output must report commands run and pass/fail status results.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-executor hook: completion output must report commands run and pass/fail status results.' }
     }
 
     $missingLanguageStatuses = [System.Collections.Generic.List[string]]::new()
@@ -277,7 +305,7 @@ function Invoke-ExecutorOutputValidation {
 
     if ($missingLanguageStatuses.Count -gt 0) {
         $missingList = $missingLanguageStatuses -join ', '
-        return @{ Ok = $false; Message = "atomic-executor hook: completion output is missing explicit PASS/FAIL toolchain status lines for: $missingList." }
+        return @{ Ok = $false; Repairable = $true; Message = "atomic-executor hook: completion output is missing explicit PASS/FAIL toolchain status lines for: $missingList." }
     }
 
     return @{ Ok = $true; Message = $null }
@@ -287,10 +315,10 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-$result = Invoke-ExecutorOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-executor-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-executor-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
+try { $result = Invoke-ExecutorOutputValidation }
+catch { Exit-SubagentStopBlock -Message ('validate-executor-output: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + $script:SubagentStopReportAndHaltLine) }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0

package/resources/claude-customizations/.claude/hooks/validate-feature-review-coverage-metrics.ps1

@@ -0,0 +1,180 @@
+<#
+.SYNOPSIS
+    Artifact reader and coverage-report parsers for the feature-review coverage hook.
+
+.DESCRIPTION
+    Dot-sourced by validate-feature-review-coverage.ps1. Defines the review-artifact file reader
+    (Get-ArtifactFileContent), the LCOV and JaCoCo line and branch coverage parsers, and the
+    per-language dispatchers that select a coverage report for a changed language.
+
+    The file has no param() block, writes nothing to the output stream, and runs no top-level
+    statement other than function definitions.
+
+.NOTES
+    Requires PowerShell 7+.
+#>
+
+function Get-ArtifactFileContent {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return @{ Exists = $false; Text = $null; Lines = @() }
+    }
+
+    $text = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    $lines = Get-Content -LiteralPath $Path -ErrorAction Stop
+    if ($null -eq $lines) {
+        $lines = @()
+    }
+    elseif ($lines -isnot [array]) {
+        $lines = @($lines)
+    }
+
+    return @{ Exists = $true; Text = $text; Lines = $lines }
+}
+
+function Get-FeatureReviewClaudeMdText {
+    <#
+    .SYNOPSIS
+        Reads the repository's root CLAUDE.md for the coverage-floor lookup (CR-4).
+    .DESCRIPTION
+        Returns a hashtable with Text and ReadError. An absent file yields Text = $null and
+        ReadError = $null, so the caller applies the default floors. A file that exists but
+        cannot be read yields Text = $null and ReadError set to the first line of the
+        exception message, so the caller fails closed. The function never throws.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param()
+
+    try {
+        $file = Get-ArtifactFileContent -Path 'CLAUDE.md'
+        return @{ Text = $file.Text; ReadError = $null }
+    }
+    catch {
+        return @{ Text = $null; ReadError = ([string]$_.Exception.Message -split "`r?`n")[0] }
+    }
+}
+
+function Get-LcovRepoCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    $totalFound = 0
+    $totalHit = 0
+    foreach ($line in $file.Lines) {
+        if ($line.StartsWith('LF:')) {
+            $totalFound += [int]($line.Substring(3))
+        }
+        elseif ($line.StartsWith('LH:')) {
+            $totalHit += [int]($line.Substring(3))
+        }
+    }
+    if ($totalFound -le 0) { return $null }
+    return [math]::Round(($totalHit * 100.0) / $totalFound, 2)
+}
+
+function Get-LcovBranchCoverage {
+    # Parses LCOV branch counters (BRF: branches found, BRH: branches hit) and returns a percent.
+    # LCOV emits one BRF/BRH line per source file in the report; we sum across the file to compute
+    # repo-wide branch coverage. Returns $null when the artifact is absent or when no branch
+    # information is recorded (BRF total = 0).
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    $totalFound = 0
+    $totalHit = 0
+    foreach ($line in $file.Lines) {
+        if ($line.StartsWith('BRF:')) {
+            $totalFound += [int]($line.Substring(4))
+        }
+        elseif ($line.StartsWith('BRH:')) {
+            $totalHit += [int]($line.Substring(4))
+        }
+    }
+    if ($totalFound -le 0) { return $null }
+    return [math]::Round(($totalHit * 100.0) / $totalFound, 2)
+}
+
+function Get-JacocoBranchCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    [xml]$doc = $file.Text
+    $counters = $doc.SelectNodes('//counter[@type="BRANCH"]')
+    if (-not $counters -or $counters.Count -eq 0) { return $null }
+
+    $missed = 0
+    $covered = 0
+    foreach ($counter in $counters) {
+        $missed += [int]$counter.missed
+        $covered += [int]$counter.covered
+    }
+    $total = $missed + $covered
+    if ($total -le 0) { return $null }
+    return [math]::Round(($covered * 100.0) / $total, 2)
+}
+
+function Get-LanguageBranchCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Language)
+
+    switch ($Language) {
+        'TypeScript' { return Get-LcovBranchCoverage -Path 'coverage/lcov.info' }
+        'Python' { return Get-LcovBranchCoverage -Path 'artifacts/python/lcov.info' }
+        'PowerShell' { return Get-JacocoBranchCoverage -Path 'artifacts/pester/powershell-coverage.xml' }
+        'CSharp' { return Get-JacocoBranchCoverage -Path 'artifacts/csharp/coverage.xml' }
+    }
+    return $null
+}
+
+function Get-JacocoRepoCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    [xml]$doc = $file.Text
+    $counters = $doc.SelectNodes('//counter[@type="LINE"]')
+    if (-not $counters -or $counters.Count -eq 0) { return $null }
+
+    $missed = 0
+    $covered = 0
+    foreach ($counter in $counters) {
+        $missed += [int]$counter.missed
+        $covered += [int]$counter.covered
+    }
+    $total = $missed + $covered
+    if ($total -le 0) { return $null }
+    return [math]::Round(($covered * 100.0) / $total, 2)
+}
+
+function Get-LanguageRepoCoverage {
+    [OutputType([Nullable[double]])]
+    param(
+        [string]$Language
+    )
+
+    switch ($Language) {
+        'TypeScript' { return Get-LcovRepoCoverage -Path 'coverage/lcov.info' }
+        'Python' { return Get-LcovRepoCoverage -Path 'artifacts/python/lcov.info' }
+        'PowerShell' { return Get-JacocoRepoCoverage -Path 'artifacts/pester/powershell-coverage.xml' }
+        'CSharp' { return Get-JacocoRepoCoverage -Path 'artifacts/csharp/coverage.xml' }
+    }
+    return $null
+}