@danmoisan/drm-copilot-mcp 1.0.27 → 1.1.0

package/resources/claude-customizations/.claude/hooks/enforce-mermaid-validation.ps1

@@ -4,9 +4,9 @@
 
 .DESCRIPTION
     This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
-    operation. It reads the tool input from the CLAUDE_TOOL_INPUT environment variable
-    (JSON with 'file_path' plus 'content' for Write, or 'old_string'/'new_string' for
-    Edit) and applies two independent gates:
+    operation. It acquires the hook payload through the shared reader and reads the
+    envelope's nested tool_input ('file_path' plus 'content' for Write, or
+    'old_string'/'new_string' for Edit), then applies two independent gates:
 
       1. Syntax gate. On a Write of a '.mmd'/'.mermaid' file, the whole file is one
          diagram. On a Write of a Markdown file, every fenced ```mermaid block is a
@@ -21,8 +21,8 @@
     Blocking a valid diagram is worse than missing an invalid one, so the hook declines
     to judge rather than rejecting whenever it cannot classify content confidently:
 
-      - empty, absent, or unparseable CLAUDE_TOOL_INPUT: allow;
-      - missing 'file_path', or a path outside the '.mmd'/'.mermaid'/Markdown scope: allow;
+      - missing 'file_path' inside a well-formed tool_input, or a path outside the
+        '.mmd'/'.mermaid'/Markdown scope: allow;
       - the validation module absent from disk: allow;
       - an Edit payload (the syntax check needs the whole file, which an
         old_string/new_string fragment cannot supply): allow;
@@ -32,13 +32,17 @@
       - a fence immediately preceded by '<!-- mermaid-validator: ignore -->': skip that
         block, and only that block.
 
-    DELIBERATE DIVERGENCE FROM enforce-evidence-locations.ps1: that hook throws on
-    malformed CLAUDE_TOOL_INPUT JSON and its entry point exits 1. This hook allows
-    instead. The difference is intentional and must not be "fixed" into a hard failure:
-    a content gate that hard-fails on input it cannot parse converts an unparseable
-    payload into a blocked write, which is the false-positive failure mode this feature
-    exists to avoid. The evidence-location hook gates a path, which is always parseable
-    when present; this hook gates content, which is not.
+    ENVELOPE VERSUS CONTENT (revised by issue #501). The hook now distinguishes two
+    kinds of unreadability that the original note conflated. An ENVELOPE-level anomaly
+    -- empty payload on every transport, unparseable envelope JSON, or a payload with
+    no usable tool_input -- means the PreToolUse contract itself drifted, which is the
+    exact defect #501 fixed and which must fail loudly rather than silently allow; the
+    hook therefore denies. A CONTENT-level judgement remains permissive, and that half
+    of the original note stands unchanged and must not be "fixed" into a hard failure:
+    an Edit fragment, a Markdown file with no fence, an absent validation module, and a
+    diagram the classifier cannot classify all still allow, because blocking a valid
+    diagram is worse than missing an invalid one. The prior blanket allow-on-unparseable
+    made the gate inert against the payload the harness actually sends.
 
     The extension scope check runs before any content scan, so a write outside the
     Mermaid scope pays only the JSON parse.
@@ -55,6 +59,8 @@ param()
 
 Set-StrictMode -Version Latest
 
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
 $script:MermaidModulePath = Join-Path -Path $PSScriptRoot -ChildPath '../lib/mermaid/MermaidValidation.psm1'
 $script:MermaidSkillPointer = 'See .claude/skills/mermaid-diagram/SKILL.md.'
 $script:MermaidSyncPointer = 'Change it through the Mermaid Chart sync workflow in VS Code (Mermaid Chart extension: Sync Diagram with Mermaid, then Review Mermaid Sync) and pull the synced result instead of hand-editing. See .claude/rules/mermaid.md.'
@@ -288,7 +294,7 @@ function Invoke-MermaidValidationDecision {
         business (out of scope, unparseable, or a Markdown file with no fence), which the
         entry point treats as a silent allow.
     .PARAMETER ToolInputRaw
-        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+        The raw JSON hook payload acquired by Read-ClaudeHookRawPayload.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -298,16 +304,18 @@ function Invoke-MermaidValidationDecision {
         [string] $ToolInputRaw
     )
 
-    if ([string]::IsNullOrWhiteSpace($ToolInputRaw)) { return $null }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        # Fail open. See the DELIBERATE DIVERGENCE note in this file's header before
-        # changing this to a throw.
-        return $null
+    # Envelope-level anomaly: fail closed. See the ENVELOPE VERSUS CONTENT note in
+    # this file's header before changing this back to a silent allow.
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return Get-MermaidDenyDecision -Reason (
+            'MERMAID_VALIDATION_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $envelope.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
+    $toolInput = $envelope.Value
+
     $filePath = [string](Get-MermaidToolInputField -InputObject $toolInput -Name 'file_path')
     if ([string]::IsNullOrWhiteSpace($filePath)) { return $null }
 
@@ -362,16 +370,20 @@ function Invoke-MermaidValidationEntryPoint {
         output stream as the JSON, so the caller would consume the JSON instead of
         printing it and the decision would never reach Claude Code.
     .PARAMETER ToolInputRaw
-        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+        The raw JSON hook payload acquired by Read-ClaudeHookRawPayload.
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param(
         [AllowEmptyString()]
         [AllowNull()]
-        [string] $ToolInputRaw = $env:CLAUDE_TOOL_INPUT
+        [string] $ToolInputRaw
     )
 
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = Read-ClaudeHookRawPayload
+    }
+
     $decision = Invoke-MermaidValidationDecision -ToolInputRaw $ToolInputRaw
     if ($null -eq $decision) { return }
 
@@ -383,7 +395,7 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-Invoke-MermaidValidationEntryPoint -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+Invoke-MermaidValidationEntryPoint -ToolInputRaw (Read-ClaudeHookRawPayload)
 
 # Exit 0 on allow and on deny alike: the decision travels in the JSON, never in the
 # exit code.

package/resources/claude-customizations/.claude/hooks/enforce-model-routing-receipt.ps1

@@ -5,7 +5,7 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the Agent (Task) tool. Reads
-    tool input JSON from the CLAUDE_TOOL_INPUT environment variable and the
+    tool input JSON from the the envelope's nested tool_input environment variable and the
     orchestrator checkpoint from artifacts/orchestration/orchestrator-state.json.
 
     The hook enforces presence only: it cannot read the delegate's chosen
@@ -32,6 +32,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 function Get-ModelRoutingCheckpoint {
     <#
     .SYNOPSIS
@@ -118,7 +120,7 @@ function Test-ModelRoutingReceiptPresent {
 function Invoke-ModelRoutingReceiptDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision object.
+        Parses the envelope's nested tool_input and returns an allow-or-block decision object.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -128,21 +130,23 @@ function Invoke-ModelRoutingReceiptDecision {
 
     $allow = [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
 
-    # Empty or absent tool input is not a delegation this hook can gate.
-    if (-not $ToolInputRaw) {
-        return $allow
-    }
-
-    # Malformed tool-input JSON is allowed through gracefully; this hook is a
-    # deterrent, not the authoritative validator.
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return $allow
+    # Envelope-level anomalies fail closed (issue #501): an unreadable envelope means
+    # the PreToolUse contract drifted, which is exactly the condition that made every
+    # gate in this runtime inert, so it must deny rather than pass through.
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = 'MODEL_ROUTING_RECEIPT_BLOCKED: payload anomaly - ' +
+                (Get-ClaudeHookPayloadAnomalyReason -Anomaly $envelope.Anomaly) +
+                '. The gate fails closed on an envelope it cannot read.'
+            }
+        }
     }
 
-    $subagent = [string]$toolInput.subagent_type
+    $subagent = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'subagent_type'
 
     # Only the gated Agent-tool delegates are receipt-checked; any other
     # subagent_type (including orchestrator) passes through.
@@ -169,13 +173,7 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-ModelRoutingReceiptDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-}
-catch {
-    Write-Error $_
-    exit 1
-}
+$decision = Invoke-ModelRoutingReceiptDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
 
 $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -5,6 +5,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
 function ConvertFrom-CheckpointJson {
@@ -164,19 +166,23 @@ function Invoke-OrchestrationPreimplementationGateDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $ToolInputRaw,
+
         [string] $CheckpointRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-OrchestrationPreimplementationGateAllowDecision
-    }
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-orchestration-preimplementation-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-OrchestrationPreimplementationGateBlockDecision -Reason (
+            'PREIMPLEMENTATION_GATE_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
+    $toolInput = $payload.Value
+
     $requiresReadyCheckpoint = $false
     $filePath = Get-StringProperty -Value $toolInput -Name 'file_path'
     if ($filePath) {
@@ -210,16 +216,55 @@ function Invoke-OrchestrationPreimplementationGateDecision {
     return Get-OrchestrationPreimplementationGateBlockDecision -Reason 'PREIMPLEMENTATION_GATE_BLOCKED: Implementation operations require artifacts/orchestration/orchestrator-state.json to contain issue number, feature folder, route metadata, lifecycle readiness, and checkpoint state before implementation begins.'
 }
 
+function Invoke-OrchestrationPreimplementationGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the hook decision and returns the process exit code.
+    .DESCRIPTION
+        Acquires the payload through the shared reader unless the caller supplies
+        one, emits the compact decision JSON, and returns 0. It never returns 1:
+        exit 1 is non-blocking for PreToolUse, so every anomaly is already a deny
+        decision by the time control reaches here. The function does not call exit;
+        the thin tail converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        Optional pre-acquired payload text. When omitted the ReadPayload seam runs.
+    .PARAMETER ReadPayload
+        Seam for payload acquisition, so tests can drive the empty-on-all-transports
+        case without touching a console.
+    .OUTPUTS
+        System.Int32
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
+
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $decision = Invoke-OrchestrationPreimplementationGateDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-OrchestrationPreimplementationGateDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
+# 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
+# expression and emit nothing, so the decision is written explicitly here first.
+$entryPointResult = @(Invoke-OrchestrationPreimplementationGateEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-exit 0
+exit ([int]$entryPointResult[-1])

package/resources/claude-customizations/.claude/hooks/enforce-parallel-abandon-gate.ps1

@@ -5,7 +5,8 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
-    command runs. Reads CLAUDE_TOOL_INPUT, extracts the command text, and matches it
+    command runs. Reads the hook payload through the shared reader, extracts the
+    command text from the envelope's nested tool_input, and matches it
     against the two tokens declared at the top of this file: the abandon disposition
     token and the confirmation marker. A command carrying the abandon disposition token
     without the confirmation marker in the SAME command is denied with reason prefix
@@ -32,6 +33,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 # The two tokens this gate matches on. These are the ONLY places either token literal
 # appears in this file; the seam test extracts the consumer-side values from exactly
 # these two named assignments.
@@ -44,8 +47,8 @@ $script:AbandonBlockedReasonCode = 'PARALLEL_ABANDON_BLOCKED'
 function Get-ParallelAbandonGateToolInput {
     <#
     .SYNOPSIS
-        Read the raw JSON tool payload supplied by Claude Code. Tests mock this
-        function (read seam).
+        Read the raw JSON hook payload through the shared reader (stdin first, then
+        the two environment fallbacks). Tests mock this function (read seam).
     .OUTPUTS
         System.String or $null
     #>
@@ -53,7 +56,7 @@ function Get-ParallelAbandonGateToolInput {
     [OutputType([string])]
     param()
 
-    return $env:CLAUDE_TOOL_INPUT
+    return Read-ClaudeHookRawPayload
 }
 
 function Get-ParallelAbandonNormalizedCommand {
@@ -201,7 +204,7 @@ function Get-ParallelAbandonGateBlockReason {
 function Invoke-ParallelAbandonGateDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the PreToolUse envelope and returns an allow-or-block decision.
     .PARAMETER ToolInputRaw
         The raw JSON tool payload supplied by Claude Code.
     .OUTPUTS
@@ -218,17 +221,16 @@ function Invoke-ParallelAbandonGateDecision {
     # An absent payload carries no command to gate, so there is nothing in scope. This is
     # allow rather than deny because the gate constrains one specific destructive command
     # shape and must not become a blanket Bash block.
-    if (-not $ToolInputRaw) {
-        return Get-ParallelAbandonGateAllowDecision
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-ParallelAbandonGateBlockDecision -Reason (
+            $script:AbandonBlockedReasonCode + ': payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-parallel-abandon-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
-    }
-
-    $normalizedCommand = Get-ParallelAbandonNormalizedCommand -CommandText ([string]$toolInput.command)
+    $commandText = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'command'
+    $normalizedCommand = Get-ParallelAbandonNormalizedCommand -CommandText $commandText
     if (-not (Test-ParallelAbandonCommandInScope -NormalizedCommand $normalizedCommand)) {
         return Get-ParallelAbandonGateAllowDecision
     }
@@ -247,12 +249,7 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-ParallelAbandonGateDecision -ToolInputRaw (Get-ParallelAbandonGateToolInput)
-} catch {
-    Write-Error $_
-    exit 1
-}
+$decision = Invoke-ParallelAbandonGateDecision -ToolInputRaw (Get-ParallelAbandonGateToolInput)
 
 $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 

package/resources/claude-customizations/.claude/hooks/enforce-parallel-cohort-barrier-helpers.ps1

@@ -0,0 +1,278 @@
+<#
+.SYNOPSIS
+    Dot-sourced record-resolution and barrier helpers for enforce-parallel-cohort-barrier.ps1.
+
+.DESCRIPTION
+    Holds the five resolution helpers the Layer 1 parallel cohort barrier uses once a
+    delegation has been identified as a parallel-mode orchestrator call:
+
+      - Find-ParallelCohortBarrierItemRecord: resolves the items[] record for a folder.
+      - Find-ParallelCohortBarrierItemByKey: resolves an items[] record by issue_num.
+      - Find-ParallelCohortBarrierCohortIndex: projects the current-generation coloring.
+      - Get-ParallelCohortBarrierConflictNeighborList: collects conflict-edge neighbours.
+      - Test-ParallelCohortBarrierClear: applies the per-edge barrier rule.
+
+    They are split out of the parent hook, .claude/hooks/enforce-parallel-cohort-barrier.ps1,
+    because that file stood at 499 lines -- one below the 500-line limit -- with no room
+    for the shared payload-reader migration (issue #501). The split is a pure move with no
+    behaviour change; the precedent is .claude/hooks/enforce-parallel-drift-gate-helpers.ps1.
+
+    The helpers read the script-scoped configuration the parent hook assigns
+    ($script:AllowedMergeStatuses), so this file is only ever dot-sourced from that hook
+    and never invoked on its own.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies. Every function is
+    pure: no filesystem, subprocess, network, or wall-clock access.
+#>
+[CmdletBinding()]
+param()
+
+function Find-ParallelCohortBarrierItemRecord {
+    <#
+    .SYNOPSIS
+        Locate the items[] record whose feature_folder resolves to the target basename.
+    .PARAMETER Checkpoint
+        Parsed parallel checkpoint, or $null when absent/unreadable.
+    .PARAMETER FeatureFolder
+        The target feature_folder basename resolved from the prompt.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $FeatureFolder
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($FeatureFolder)) {
+        return $null
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'items') {
+        return $null
+    }
+
+    # Scan every recorded item for a feature_folder whose basename equals the target.
+    foreach ($item in @($Checkpoint.items)) {
+        $itemProps = @($item.PSObject.Properties.Name)
+        if ($itemProps -notcontains 'feature_folder') {
+            continue
+        }
+        $itemBasename = Get-ParallelCohortBarrierFolderBasename -FolderPath ([string]$item.feature_folder)
+        if ($itemBasename -eq $FeatureFolder) {
+            return $item
+        }
+    }
+    return $null
+}
+
+function Find-ParallelCohortBarrierItemByKey {
+    <#
+    .SYNOPSIS
+        Locate the items[] record whose issue_num equals the supplied key.
+    .PARAMETER Checkpoint
+        Parsed parallel checkpoint, or $null when absent/unreadable.
+    .PARAMETER IssueKey
+        The item primary key (issue_num) rendered as a string.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $IssueKey
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
+        return $null
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'items') {
+        return $null
+    }
+
+    foreach ($item in @($Checkpoint.items)) {
+        $itemProps = @($item.PSObject.Properties.Name)
+        if ($itemProps -notcontains 'issue_num') {
+            continue
+        }
+        if (([string]$item.issue_num) -eq $IssueKey) {
+            return $item
+        }
+    }
+    return $null
+}
+
+function Find-ParallelCohortBarrierCohortIndex {
+    <#
+    .SYNOPSIS
+        Return the current-generation cohort index that holds the supplied item key.
+    .DESCRIPTION
+        The cohort projection is restricted to cohorts[] rows whose generation equals the
+        top-level recolor_generation, which is the current coloring. Rows from a superseded
+        generation are ignored. Returns $null when the checkpoint records no
+        recolor_generation, no cohorts, or no current-generation cohort containing the key.
+    .PARAMETER Checkpoint
+        Parsed parallel checkpoint, or $null when absent/unreadable.
+    .PARAMETER IssueKey
+        The item primary key (issue_num) rendered as a string.
+    .OUTPUTS
+        System.Int32 or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $IssueKey
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
+        return $null
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'cohorts' -or $checkpointProps -notcontains 'recolor_generation') {
+        return $null
+    }
+
+    $currentGeneration = [string]$Checkpoint.recolor_generation
+
+    foreach ($cohort in @($Checkpoint.cohorts)) {
+        $cohortProps = @($cohort.PSObject.Properties.Name)
+        if ($cohortProps -notcontains 'index' -or $cohortProps -notcontains 'generation' -or $cohortProps -notcontains 'item_keys') {
+            continue
+        }
+        if (([string]$cohort.generation) -ne $currentGeneration) {
+            continue
+        }
+        $parsedIndex = 0
+        if (-not [int]::TryParse(([string]$cohort.index), [ref] $parsedIndex)) {
+            continue
+        }
+        foreach ($key in @($cohort.item_keys)) {
+            if (([string]$key) -eq $IssueKey) {
+                return $parsedIndex
+            }
+        }
+    }
+    return $null
+}
+
+function Get-ParallelCohortBarrierConflictNeighborList {
+    <#
+    .SYNOPSIS
+        Return the item keys that share a conflict edge with the supplied item key.
+    .PARAMETER Checkpoint
+        Parsed parallel checkpoint, or $null when absent/unreadable.
+    .PARAMETER IssueKey
+        The item primary key (issue_num) rendered as a string.
+    .OUTPUTS
+        System.Object[] holding each neighbor item key rendered as a string.
+    #>
+    [CmdletBinding()]
+    [OutputType([object[]])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $IssueKey
+    )
+
+    $neighborList = @()
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
+        return $neighborList
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'conflict_edges') {
+        return $neighborList
+    }
+
+    # Edges are undirected and canonically normalized to a < b, so both endpoints are
+    # inspected and the opposite endpoint is returned as the neighbor.
+    foreach ($edge in @($Checkpoint.conflict_edges)) {
+        $edgeProps = @($edge.PSObject.Properties.Name)
+        if ($edgeProps -notcontains 'a' -or $edgeProps -notcontains 'b') {
+            continue
+        }
+        $endpointA = [string]$edge.a
+        $endpointB = [string]$edge.b
+        if ($endpointA -eq $IssueKey) {
+            $neighborList += $endpointB
+        } elseif ($endpointB -eq $IssueKey) {
+            $neighborList += $endpointA
+        }
+    }
+    return $neighborList
+}
+
+function Test-ParallelCohortBarrierClear {
+    <#
+    .SYNOPSIS
+        Decision logic: true only when every conflicting neighbor in a strictly prior
+        current-generation cohort has merge_status merged or worktree_removed.
+    .PARAMETER Checkpoint
+        Parsed parallel checkpoint, or $null when absent/unreadable.
+    .PARAMETER ItemRecord
+        The target item's own items[] record, or $null when not found.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        $ItemRecord
+    )
+
+    if ($null -eq $Checkpoint -or $null -eq $ItemRecord) {
+        return $false
+    }
+    $itemProps = @($ItemRecord.PSObject.Properties.Name)
+    if ($itemProps -notcontains 'issue_num') {
+        return $false
+    }
+
+    $targetKey = [string]$ItemRecord.issue_num
+    $targetIndex = Find-ParallelCohortBarrierCohortIndex -Checkpoint $Checkpoint -IssueKey $targetKey
+    if ($null -eq $targetIndex) {
+        # No current-generation cohort assignment: position is unknown, so fail closed.
+        return $false
+    }
+
+    foreach ($neighborKey in @(Get-ParallelCohortBarrierConflictNeighborList -Checkpoint $Checkpoint -IssueKey $targetKey)) {
+        $neighborIndex = Find-ParallelCohortBarrierCohortIndex -Checkpoint $Checkpoint -IssueKey $neighborKey
+        if ($null -eq $neighborIndex) {
+            # Not part of the current coloring, so not a strictly prior cohort neighbor.
+            continue
+        }
+        if ($neighborIndex -ge $targetIndex) {
+            # Same-cohort and later-cohort contention is not a Layer 1 concern.
+            continue
+        }
+        $neighborRecord = Find-ParallelCohortBarrierItemByKey -Checkpoint $Checkpoint -IssueKey $neighborKey
+        if ($null -eq $neighborRecord) {
+            return $false
+        }
+        $neighborProps = @($neighborRecord.PSObject.Properties.Name)
+        if ($neighborProps -notcontains 'merge_status') {
+            return $false
+        }
+        if ($script:AllowedMergeStatuses -notcontains ([string]$neighborRecord.merge_status)) {
+            return $false
+        }
+    }
+    return $true
+}