@danmoisan/drm-copilot-mcp 1.0.27 → 1.1.1

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

@@ -5,8 +5,40 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
+# Pure pathspec classifier for the issue #539 orchestration-bookkeeping staging exemption.
+# Extracted to a dot-sourced sibling so this file stays inside the 500-line cap, following
+# the enforce-pr-author-skill.ps1 headroom-split precedent.
+. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-helpers.ps1')
+
+# The readiness checkpoint this gate reads and names in its block message.
 $script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
+# Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
+# of these is orchestration bookkeeping, not implementation, so the gate must not
+# require a ready checkpoint before the checkpoint itself can be created. The set is a
+# list of repo-relative literals behind a single membership check: no directory prefix,
+# no glob, and no absolute-path entry.
+$script:CheckpointPaths = @(
+    'artifacts/orchestration/orchestrator-state.json'
+    'artifacts/orchestration/parallel-planner-state.json'
+    'artifacts/orchestration/parallel-orchestrator-state.json'
+    'artifacts/orchestration/epic-planner-state.json'
+    'artifacts/orchestration/epic-orchestrator-state.json'
+    'artifacts/orchestration/powershell-orchestrator-state.json'
+    'artifacts/orchestration/csharp-orchestrator-state.json'
+)
+
+# Both markers must appear in the field-scoped prompt for a delegation to qualify as a
+# preparation-mode kickoff. The literals are reused verbatim from
+# .claude/skills/parallel-plan/SKILL.md and .claude/skills/epic-plan/SKILL.md.
+$script:PreparationModeMarkers = @(
+    'Preparation mode: true.'
+    'route_id: preparation.'
+)
+
 function ConvertFrom-CheckpointJson {
     [CmdletBinding()]
     param([Parameter(Mandatory)][string] $Json)
@@ -33,7 +65,13 @@ function Test-FeatureDocumentationOrEvidencePath {
     [OutputType([bool])]
     param([Parameter(Mandatory)][string] $NormalizedPath)
 
-    return $NormalizedPath.StartsWith('docs/features/active/')
+    # The segment anchor (^|/) admits both the repo-relative spelling and an
+    # absolute spelling of the same feature document, which the Write tool
+    # supplies by contract. -cmatch is deliberate and must not be normalized into
+    # -match: String.StartsWith is case-sensitive, so the case-sensitive operator
+    # is what preserves the previous semantics exactly. PowerShell -match is
+    # case-insensitive and would widen this predicate.
+    return $NormalizedPath -cmatch '(^|/)docs/features/active/'
 }
 
 function Test-ImplementationPath {
@@ -44,8 +82,29 @@ function Test-ImplementationPath {
     if (Test-FeatureDocumentationOrEvidencePath -NormalizedPath $NormalizedPath) {
         return $false
     }
-    if ($NormalizedPath -eq $script:CheckpointPath) {
-        return $false
+    # Segment-anchored and end-anchored, so an absolute spelling of a checkpoint is
+    # exempt exactly as its repo-relative spelling already was. -match is
+    # deliberate here and must not be narrowed into -cmatch: -contains was
+    # case-insensitive, so the case-insensitive operator is what preserves the
+    # previous semantics exactly.
+    #
+    # Accepted widening: this also exempts a path OUTSIDE the workspace whose tail
+    # is an artifacts/orchestration/ segment followed by one of the seven names.
+    # Measured exposure in this repository is one matching file, the real
+    # checkpoint; there is no nested or vendored second copy. The same widening is
+    # already accepted for the identical literal in four other hooks. Resolving a
+    # workspace root instead would reintroduce every root-resolution failure mode
+    # (8.3 short names, drive-letter case, symlinks, linked worktrees), and a strip
+    # that failed to match would leave the path absolute and deny, reinstating the
+    # reported defect in a subtler form.
+    #
+    # Known deliberate miss: a path reaching a checkpoint name only through a '..'
+    # hop stays denied. The Write tool does not emit '..' segments, and a
+    # canonicalizer would reintroduce filesystem dependence for no measured gain.
+    foreach ($checkpoint in $script:CheckpointPaths) {
+        if ($NormalizedPath -match ('(^|/)' + [regex]::Escape($checkpoint) + '$')) {
+            return $false
+        }
     }
     return $NormalizedPath -match '\.(py|ps1|psm1|ts|tsx|js|jsx|cs|json|yml|yaml)$'
 }
@@ -68,14 +127,58 @@ function Test-ImplementationCommand {
         '(^|\s)pwsh\s+.*(Invoke-Pester|tests/scripts/)'
     )
 
-    foreach ($pattern in $implementationCommandPatterns) {
-        if ($normalizedCommand -match $pattern) {
-            return $true
+    for ($index = 0; $index -lt $implementationCommandPatterns.Count; $index++) {
+        if ($normalizedCommand -notmatch $implementationCommandPatterns[$index]) {
+            continue
         }
+        # Allow-side only (issue #539). Index 0 is the git staging trigger, whose pattern
+        # text is unchanged. It is the sole leg the orchestration-bookkeeping exemption may
+        # clear, and only when no other implementation pattern matches the same line: the
+        # loop continues rather than returning, so a chained line carrying any non-git
+        # implementation segment still classifies as implementation.
+        if ($index -eq 0 -and (Test-ExemptOrchestrationStagingCommand -CommandText $normalizedCommand)) {
+            continue
+        }
+        return $true
     }
     return $false
 }
 
+function Test-PreparationModeDelegation {
+    <#
+    .SYNOPSIS
+        Identifies an orchestrator delegation that is a preparation-mode kickoff.
+    .DESCRIPTION
+        Returns true only when all three conjuncts hold: the payload is present, the
+        delegated agent is exactly 'orchestrator', and the field-scoped prompt carries
+        both preparation markers. The prompt is read as a named field rather than from
+        the serialized payload so that marker text planted in an unrelated field cannot
+        exempt an implementation delegation.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $ToolInput)
+
+    if ($null -eq $ToolInput) {
+        return $false
+    }
+
+    $subagentType = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'subagent_type'
+    if ($subagentType -ne 'orchestrator') {
+        return $false
+    }
+
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'prompt'
+    foreach ($marker in $script:PreparationModeMarkers) {
+        if (-not $prompt.Contains($marker)) {
+            return $false
+        }
+    }
+    return $true
+}
+
 function Test-ImplementationDelegation {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -85,6 +188,17 @@ function Test-ImplementationDelegation {
         return $false
     }
 
+    try {
+        if (Test-PreparationModeDelegation -ToolInput $ToolInput) {
+            return $false
+        }
+    } catch {
+        # An envelope the field reader cannot probe falls through to the unchanged
+        # whole-payload regex below. An extraction failure must never become an
+        # exemption, so the gate stays closed on the stricter classifier.
+        Write-Debug "Preparation-mode probe failed: $($_.Exception.Message)"
+    }
+
     $payloadText = ($ToolInput | ConvertTo-Json -Depth 20 -Compress)
     return $payloadText -match '(python-typed-engineer|powershell-typed-engineer|typescript-engineer|csharp-typed-engineer|atomic-executor|implementation|execute)'
 }
@@ -164,19 +278,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 +328,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
+}