@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.17

package/resources/claude-customizations/.claude/lib/parallel-drift/ParallelDriftHalt.psm1

@@ -0,0 +1,388 @@
+<#
+.SYNOPSIS
+    Halt selection and input shape guards for parallel radius-drift detection.
+
+.DESCRIPTION
+    Destination-runtime PowerShell port (issue #763) of the halt-selection half of
+    parallel drift detection. It ports select_halted_item and _start_rank from
+    scripts/dev_tools/parallel_drift_halt.py, the halted_item_keys selection from
+    scripts/dev_tools/parallel_drift_detection_cli.py, and the guards
+    require_item_key, require_text, require_paths, require_enum_member,
+    as_item_key, and canonical_pair from scripts/dev_tools/_parallel_drift_shape.py.
+    The Python modules remain the repository authority and the parity reference.
+
+    Every function is pure: no filesystem, subprocess, network, or clock access,
+    and no input is mutated. A guard failure throws with a message naming the
+    offending field. Booleans are never accepted where an integer is required,
+    matching the Python reference, which rejects bool although it subclasses int.
+    A function that returns an array uses the unary comma so a one-element or
+    empty array is not unrolled; it declares both the array type and
+    System.Object[] as output types.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Integer runtime types a deserialized checkpoint value may carry. Boolean is
+# deliberately absent, so a boolean in an integer slot is malformed.
+$script:IntegerTypeName = @('System.Int16', 'System.Int32', 'System.Int64', 'System.Byte',
+    'System.SByte', 'System.UInt16', 'System.UInt32', 'System.UInt64')
+
+function Test-ParallelDriftIntegerValue {
+    <#
+    .SYNOPSIS
+        Report whether a value is a non-boolean integer.
+    .PARAMETER Value
+        Any deserialized value.
+    .OUTPUTS
+        System.Boolean.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()][object] $Value)
+
+    return ($null -ne $Value) -and ($script:IntegerTypeName -contains $Value.GetType().FullName)
+}
+
+function Format-ParallelDriftValue {
+    <#
+    .SYNOPSIS
+        Render a value for an error message; null renders as None, as in Python.
+    .PARAMETER Value
+        Any value.
+    .OUTPUTS
+        System.String.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([AllowNull()][object] $Value)
+
+    if ($null -eq $Value) { return 'None' }
+    return [string]$Value
+}
+
+function ConvertTo-ParallelDriftSortedDistinct {
+    <#
+    .SYNOPSIS
+        Deduplicate and ordinally sort a string collection.
+    .DESCRIPTION
+        Port of the tuple(sorted(set(...))) idiom. Ordinal comparison matches
+        Python's code-point ordering; culture-sensitive sorting would not.
+    .PARAMETER Entry
+        The validated entries.
+    .OUTPUTS
+        System.String[]. Always an array, including when empty.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]], [System.Object[]])]
+    param([Parameter(Mandatory = $true)][AllowEmptyCollection()][string[]] $Entry)
+
+    $unique = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal)
+    # Collapse duplicates before sorting so each path appears once.
+    foreach ($item in $Entry) { [void]$unique.Add($item) }
+    $sorted = [System.Collections.Generic.List[string]]::new($unique)
+    $sorted.Sort([System.StringComparer]::Ordinal)
+    return , [string[]]$sorted.ToArray()
+}
+
+function Assert-ParallelDriftItemKey {
+    <#
+    .SYNOPSIS
+        Require an issue_num primary key: a positive, non-boolean integer.
+    .DESCRIPTION
+        Port of require_item_key.
+    .PARAMETER Value
+        The candidate key.
+    .PARAMETER FieldName
+        Field label rendered into the error message.
+    .OUTPUTS
+        System.Int64. The validated key.
+    #>
+    [CmdletBinding()]
+    [OutputType([long])]
+    param(
+        [Parameter(Mandatory = $true)][AllowNull()][object] $Value,
+        [Parameter(Mandatory = $true)][string] $FieldName
+    )
+
+    if (-not (Test-ParallelDriftIntegerValue -Value $Value) -or [long]$Value -le 0) {
+        throw "$FieldName must be a positive integer issue_num; found: $(Format-ParallelDriftValue -Value $Value)."
+    }
+    return [long]$Value
+}
+
+function Assert-ParallelDriftText {
+    <#
+    .SYNOPSIS
+        Require a string that carries at least one non-space character.
+    .DESCRIPTION
+        Port of require_text.
+    .PARAMETER Value
+        The candidate string.
+    .PARAMETER FieldName
+        Field label rendered into the error message.
+    .OUTPUTS
+        System.String. The validated value, unchanged.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][AllowNull()][AllowEmptyString()][object] $Value,
+        [Parameter(Mandatory = $true)][string] $FieldName
+    )
+
+    if ($Value -isnot [string] -or [string]::IsNullOrWhiteSpace($Value)) {
+        throw "$FieldName must be a non-empty string; found: $(Format-ParallelDriftValue -Value $Value)."
+    }
+    return $Value
+}
+
+function Assert-ParallelDriftPathList {
+    <#
+    .SYNOPSIS
+        Require a collection of non-blank repository paths.
+    .DESCRIPTION
+        Port of require_paths. A bare string is rejected rather than iterated,
+        because iterating one would treat each character as a path. A blank or
+        non-string entry is rejected rather than dropped, because dropping it
+        would narrow the compared set and under-report drift.
+    .PARAMETER Value
+        The candidate collection.
+    .PARAMETER FieldName
+        Field label rendered into the error messages.
+    .PARAMETER AllowEmpty
+        Accept an empty collection. It is not accepted for escaped paths, where
+        emptiness means there was no drift.
+    .OUTPUTS
+        System.String[]. The entries deduplicated and ordinally sorted.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]], [System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)][AllowNull()][AllowEmptyCollection()][object] $Value,
+        [Parameter(Mandatory = $true)][string] $FieldName,
+        [switch] $AllowEmpty
+    )
+
+    if ($Value -is [string]) {
+        throw "$FieldName must be a collection of paths, not a single string; found: '$Value'."
+    }
+    if ($Value -isnot [System.Collections.IEnumerable] -or $Value -is [System.Collections.IDictionary]) {
+        throw "$FieldName must be a collection of paths; found: $(Format-ParallelDriftValue -Value $Value)."
+    }
+
+    $entry = [System.Collections.Generic.List[string]]::new()
+    # Validate every entry before normalizing so an error names the offending value.
+    foreach ($item in $Value) {
+        if ($item -isnot [string] -or [string]::IsNullOrWhiteSpace($item)) {
+            throw "$FieldName entries must be non-empty strings; found: $(Format-ParallelDriftValue -Value $item)."
+        }
+        $entry.Add($item)
+    }
+    if ($entry.Count -eq 0 -and -not $AllowEmpty) {
+        throw "$FieldName must not be empty."
+    }
+    return , (ConvertTo-ParallelDriftSortedDistinct -Entry $entry.ToArray())
+}
+
+function Assert-ParallelDriftEnumMember {
+    <#
+    .SYNOPSIS
+        Require a member of a fixed vocabulary.
+    .DESCRIPTION
+        Port of require_enum_member. Matching is case-sensitive.
+    .PARAMETER Value
+        The candidate member.
+    .PARAMETER Vocabulary
+        The permitted members.
+    .PARAMETER FieldName
+        Field label rendered into the error message.
+    .OUTPUTS
+        System.String. The validated member, unchanged.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][AllowNull()][object] $Value,
+        [Parameter(Mandatory = $true)][string[]] $Vocabulary,
+        [Parameter(Mandatory = $true)][string] $FieldName
+    )
+
+    if ($Value -isnot [string] -or $Vocabulary -cnotcontains $Value) {
+        throw "$FieldName must be one of $($Vocabulary -join ', '); found: $(Format-ParallelDriftValue -Value $Value)."
+    }
+    return $Value
+}
+
+function ConvertTo-ParallelDriftItemKey {
+    <#
+    .SYNOPSIS
+        Read a value as an item key without throwing.
+    .DESCRIPTION
+        Port of as_item_key.
+    .PARAMETER Value
+        Any deserialized checkpoint value.
+    .OUTPUTS
+        System.Int64, or $null when the value is not a positive, non-boolean integer.
+    #>
+    [CmdletBinding()]
+    [OutputType([long])]
+    param([AllowNull()][object] $Value)
+
+    if ((Test-ParallelDriftIntegerValue -Value $Value) -and [long]$Value -gt 0) {
+        return [long]$Value
+    }
+    return $null
+}
+
+function Get-ParallelDriftCanonicalPair {
+    <#
+    .SYNOPSIS
+        Normalize two item keys into the canonical a < b edge identity.
+    .DESCRIPTION
+        Port of canonical_pair, so an edge recorded in either order has one identity.
+    .PARAMETER First
+        One item key.
+    .PARAMETER Second
+        The other item key.
+    .OUTPUTS
+        System.Int64[]. The two keys in ascending order.
+    #>
+    [CmdletBinding()]
+    [OutputType([long[]], [System.Object[]])]
+    param([Parameter(Mandatory = $true)][long] $First, [Parameter(Mandatory = $true)][long] $Second)
+
+    if ($First -lt $Second) { return , [long[]]@($First, $Second) }
+    return , [long[]]@($Second, $First)
+}
+
+function Get-ParallelDriftStartRank {
+    <#
+    .SYNOPSIS
+        Render a start marker as the comparable rank halt selection maximizes.
+    .DESCRIPTION
+        Port of _start_rank plus the ItemStart construction checks. The rank is
+        (Unknown, Timestamp, ItemKey); Unknown is 1 when no usable timestamp
+        exists, which ranks an item of unknown start above every timestamped
+        item and so makes the timestamped item earlier-started.
+    .PARAMETER Start
+        A hashtable carrying ItemKey and WorktreeCreatedAt (null, blank, or a
+        timestamp string).
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with Unknown, Timestamp, ItemKey.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([Parameter(Mandatory = $true)][System.Collections.IDictionary] $Start)
+
+    $itemKey = Assert-ParallelDriftItemKey -Value $Start['ItemKey'] -FieldName 'ItemStart.item_key'
+    $timestamp = $Start['WorktreeCreatedAt']
+    if ($null -ne $timestamp -and $timestamp -isnot [string]) {
+        throw "ItemStart.worktree_created_at must be a string or None; found: $timestamp."
+    }
+    if ([string]::IsNullOrWhiteSpace($timestamp)) {
+        return [pscustomobject]@{ Unknown = 1; Timestamp = ''; ItemKey = $itemKey }
+    }
+    return [pscustomobject]@{ Unknown = 0; Timestamp = $timestamp; ItemKey = $itemKey }
+}
+
+function Select-ParallelDriftHaltedItem {
+    <#
+    .SYNOPSIS
+        Return the issue_num of the later-started item of a pair.
+    .DESCRIPTION
+        Port of select_halted_item: argmax over (start unknown, ordinal start
+        timestamp, item key). Equal timestamps halt the larger key; a start
+        present on exactly one item makes that item earlier-started; both
+        unknown falls through to the item-key tie-break.
+    .PARAMETER First
+        One start marker.
+    .PARAMETER Second
+        The other start marker.
+    .OUTPUTS
+        System.Int64. The halted item key.
+    #>
+    [CmdletBinding()]
+    [OutputType([long])]
+    param(
+        [Parameter(Mandatory = $true)][System.Collections.IDictionary] $First,
+        [Parameter(Mandatory = $true)][System.Collections.IDictionary] $Second
+    )
+
+    $left = Get-ParallelDriftStartRank -Start $First
+    $right = Get-ParallelDriftStartRank -Start $Second
+    if ($left.ItemKey -eq $right.ItemKey) {
+        throw "select_halted_item requires two distinct items; the pair names one item twice (item_key $($left.ItemKey))."
+    }
+
+    # Compare the ranks field by field in priority order; the larger rank is halted.
+    $order = $left.Unknown.CompareTo($right.Unknown)
+    if ($order -eq 0) { $order = [string]::CompareOrdinal($left.Timestamp, $right.Timestamp) }
+    if ($order -eq 0) { $order = $left.ItemKey.CompareTo($right.ItemKey) }
+    if ($order -gt 0) { return $left.ItemKey }
+    return $right.ItemKey
+}
+
+function Get-ParallelDriftHaltedItemKey {
+    <#
+    .SYNOPSIS
+        Select the halted item of every newly conflicting pair, never the drifter.
+    .DESCRIPTION
+        Port of halted_item_keys. The drifting key is dropped from each pair's
+        candidates before the comparator runs, because halting the drifting item
+        would deadlock the remediation that resolves the drift. A canonical pair
+        holds two distinct keys, so one or two candidates remain: one is halted
+        directly, two go through Select-ParallelDriftHaltedItem.
+    .PARAMETER Item
+        The checkpoint's item records, read for issue_num and worktree_created_at.
+        Every record's start marker is validated, as the Python reference does.
+    .PARAMETER Pair
+        The canonical newly conflicting pairs, each a two-element key array.
+    .PARAMETER DriftingItemKey
+        The issue_num of the item whose diff escaped; never returned.
+    .OUTPUTS
+        System.Int64[]. The halted keys, deduplicated and ascending; always an array.
+    #>
+    [CmdletBinding()]
+    [OutputType([long[]], [System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)][AllowEmptyCollection()][object[]] $Item,
+        [Parameter(Mandatory = $true)][AllowEmptyCollection()][object[]] $Pair,
+        [Parameter(Mandatory = $true)][long] $DriftingItemKey
+    )
+
+    if ($Pair.Count -eq 0) { return , [long[]]@() }
+
+    $start = @{}
+    # Build and validate one start marker per item so a pair resolves by key lookup.
+    foreach ($record in $Item) {
+        $marker = @{ ItemKey = $record['issue_num']; WorktreeCreatedAt = $record['worktree_created_at'] }
+        $rank = Get-ParallelDriftStartRank -Start $marker
+        $start[$rank.ItemKey] = $marker
+    }
+
+    $halted = [System.Collections.Generic.SortedSet[long]]::new()
+    # Apply the rule to each pair independently; the set collapses an item that is
+    # the halted member of several pairs.
+    foreach ($entry in $Pair) {
+        $candidate = @($entry | Where-Object { $_ -ne $DriftingItemKey })
+        if ($candidate.Count -eq 1) {
+            [void]$halted.Add([long]$candidate[0])
+        } else {
+            [void]$halted.Add((Select-ParallelDriftHaltedItem -First $start[[long]$candidate[0]] -Second $start[[long]$candidate[1]]))
+        }
+    }
+    return , [long[]]@($halted)
+}
+
+Export-ModuleMember -Function `
+    Assert-ParallelDriftItemKey, `
+    Assert-ParallelDriftText, `
+    Assert-ParallelDriftPathList, `
+    Assert-ParallelDriftEnumMember, `
+    ConvertTo-ParallelDriftItemKey, `
+    Get-ParallelDriftCanonicalPair, `
+    Get-ParallelDriftStartRank, `
+    Select-ParallelDriftHaltedItem, `
+    Get-ParallelDriftHaltedItemKey

package/resources/claude-customizations/.claude/lib/worktree-resolution/EpicScopeResolution.psm1

@@ -8,22 +8,26 @@
     for one gated call, whether the call is an operation of that epic and, if so, returns
     the absolute path and parsed content of the governing epic checkpoint.
 
-    A call is epic scope only when the session root's epic checkpoint parses, carries
-    route_id "epic" and a non-empty integration_branch, and that branch equals either the
-    call's branch signal (--head, --branch, or a branch: label) or, for a command or path
-    leg, the HEAD branch of the effective worktree (the -C selector worktree when present,
-    otherwise the session root). A command or path leg ignores any text branch signal, so
-    its merge probe inspects the worktree it operates on. Anything else is not epic scope,
-    so the caller's existing per-feature resolution runs unchanged.
-
-    The checkpoint path is always composed from the resolved session root and is never
-    read from command or prompt text (the issue #554 posture and the issue #673
-    invariant). Exactly one checkpoint read happens per resolution.
+    A call is epic scope only when the epic checkpoint governing the matched branch parses,
+    carries route_id "epic" and a non-empty integration_branch, and that branch equals the
+    matched branch. The matched branch is the call's branch signal (--head, --branch, or a
+    branch: label) or, for a command or path leg, the HEAD branch of the effective worktree
+    (the -C selector worktree when present, otherwise the session root). A command or path
+    leg ignores any text branch signal, so its merge probe inspects the worktree it operates
+    on. Anything else is not epic scope, so the caller's existing per-feature resolution
+    runs unchanged.
+
+    The checkpoint is located by Resolve-WorktreeEpicTarget (WorktreeRunResolution.psm1,
+    issue #690) keyed on the matched branch: the live worktree whose epic checkpoint records
+    that integration branch. Its path is never composed from the session root and never read
+    from command or prompt text (the issue #554 posture and the issue #673 invariant). An
+    unresolved target is not epic scope; an ambiguous one is not epic scope with reason
+    target-worktree-ambiguous. Exactly one checkpoint read happens per resolution.
 
 .NOTES
     PowerShell 7+. Every filesystem contact passes through the exported seams of the
-    sibling WorktreeResolution.psm1, so tests model any topology by mocking those seams
-    inside this module and create no file. No subprocess, no network, no clock read, and
+    sibling WorktreeResolution.psm1 and WorktreeRunResolution.psm1, so tests model any
+    topology by mocking those seams inside this module and create no file. No subprocess, no network, no clock read, and
     no environment read. Mirrored byte-identically under
     extensions/drm-copilot/resources/claude-customizations/.
     AUTHORITY: PowerShell-authoritative. The epic readiness predicates have no Python reference implementation, and no enforcement hook invokes Python (issue #663, D5).
@@ -35,6 +39,7 @@ $ErrorActionPreference = 'Stop'
 
 Import-Module (Join-Path $PSScriptRoot 'WorktreeResolution.psm1') -ErrorAction Stop
 Import-Module (Join-Path $PSScriptRoot 'WorktreeTargetResolution.psm1') -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot 'WorktreeRunResolution.psm1') -ErrorAction Stop
 
 # The one definition of the epic checkpoint location relative to a worktree root.
 $script:EpicCheckpointRelativePath = 'artifacts/orchestration/epic-orchestrator-state.json'
@@ -278,10 +283,13 @@ function Resolve-EpicScopeCheckpoint {
         Returns an object with IsEpicScope, CheckpointPath, Checkpoint, WorktreeRoot,
         Branch, MergeInProgress, and Reason. The first matching step decides: no branch
         signal without head matching (no-branch-signal, and no checkpoint read); an
-        unresolvable session root (session-root-unresolved); an absent or unparseable epic
-        checkpoint (epic-checkpoint-absent-or-unparseable); a route_id other than epic
-        (route_id); an empty integration_branch (integration_branch); an unresolvable
-        selector (selector-unresolved); a branch that does not match (branch-mismatch).
+        unresolvable session root (session-root-unresolved); an unresolvable selector
+        (selector-unresolved); no candidate branch (branch-mismatch); no worktree whose epic
+        checkpoint records the candidate branch (epic-checkpoint-absent-or-unparseable); more
+        than one such worktree (target-worktree-ambiguous); an absent or unparseable epic
+        checkpoint at the resolved root (epic-checkpoint-absent-or-unparseable); a route_id
+        other than epic (route_id); an empty integration_branch (integration_branch); a
+        branch that does not match (branch-mismatch).
     .PARAMETER Text
         The command or prompt text; only its branch signal is read.
     .PARAMETER SessionRoot
@@ -319,20 +327,8 @@ function Resolve-EpicScopeCheckpoint {
     if ($null -eq $root) {
         return (New-EpicScopeResult -IsEpicScope $false -Reason 'session-root-unresolved')
     }
-    $path = Join-WorktreeResolutionPath -WorktreeRoot $root -RepoRelativePath (Get-EpicScopeCheckpointRelativePath)
-    $checkpoint = ConvertFrom-EpicScopeCheckpointText -Text (Get-EpicScopeCheckpointText -Path $path)
-    if ($null -eq $checkpoint) {
-        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'epic-checkpoint-absent-or-unparseable')
-    }
-    if ([string](Get-EpicScopePropertyValue -InputObject $checkpoint -Name 'route_id') -cne $script:EpicRouteId) {
-        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'route_id')
-    }
-    $integrationBranch = [string](Get-EpicScopePropertyValue -InputObject $checkpoint -Name 'integration_branch')
-    if ([string]::IsNullOrWhiteSpace($integrationBranch)) {
-        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'integration_branch')
-    }
 
-    # Decide the matched branch. A command or path leg (-MatchWorktreeHead) matches the
+    # Decide the candidate branch. A command or path leg (-MatchWorktreeHead) matches the
     # effective worktree's HEAD, the selector worktree taking precedence, and ignores any
     # text branch signal so the merge probe inspects the worktree the call operates on
     # (issue #663 remediation CR-2); otherwise the explicit branch signal decides.
@@ -344,11 +340,36 @@ function Resolve-EpicScopeCheckpoint {
             $effectiveRoot = Find-WorktreeResolutionRoot -Path $WorktreeSelector
         }
         if ($null -eq $effectiveRoot) {
-            return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'selector-unresolved')
+            return (New-EpicScopeResult -IsEpicScope $false -Reason 'selector-unresolved')
         }
         $candidate = Get-EpicScopeWorktreeHeadBranch -WorktreeRoot $effectiveRoot
     }
-    if ($null -eq $candidate -or $candidate -cne $integrationBranch) {
+    if ($null -eq $candidate) {
+        return (New-EpicScopeResult -IsEpicScope $false -Reason 'branch-mismatch')
+    }
+
+    # Locate the governing checkpoint by the candidate branch (issue #690), never by
+    # composing it from the session root.
+    $target = Resolve-WorktreeEpicTarget -IntegrationBranch $candidate -SessionRoot $root
+    if ($target.Status -eq 'NoTarget') {
+        return (New-EpicScopeResult -IsEpicScope $false -Reason 'epic-checkpoint-absent-or-unparseable')
+    }
+    if ($target.Status -eq 'Ambiguous') {
+        return (New-EpicScopeResult -IsEpicScope $false -Reason 'target-worktree-ambiguous')
+    }
+    $path = Join-WorktreeResolutionPath -WorktreeRoot $target.WorktreeRoot -RepoRelativePath (Get-EpicScopeCheckpointRelativePath)
+    $checkpoint = ConvertFrom-EpicScopeCheckpointText -Text (Get-EpicScopeCheckpointText -Path $path)
+    if ($null -eq $checkpoint) {
+        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'epic-checkpoint-absent-or-unparseable')
+    }
+    if ([string](Get-EpicScopePropertyValue -InputObject $checkpoint -Name 'route_id') -cne $script:EpicRouteId) {
+        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'route_id')
+    }
+    $integrationBranch = [string](Get-EpicScopePropertyValue -InputObject $checkpoint -Name 'integration_branch')
+    if ([string]::IsNullOrWhiteSpace($integrationBranch)) {
+        return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'integration_branch')
+    }
+    if ($candidate -cne $integrationBranch) {
         return (New-EpicScopeResult -IsEpicScope $false -CheckpointPath $path -Reason 'branch-mismatch')
     }
 

package/resources/claude-customizations/.claude/lib/worktree-resolution/WorktreeItemResolution.psm1

@@ -213,11 +213,25 @@ function Get-WorktreeItemLiveRoot {
     return , [string[]] $live.ToArray()
 }
 
-# Private: convert a resolved root and session path into a result, labelling it
-# SessionRoot or OtherWorktree so that test is written once, as the sibling normalisation
-# constructor does. The ConvertTo verb is deliberate: a New- verb is state-changing to
-# PSScriptAnalyzer and this function changes nothing.
 function ConvertTo-WorktreeItemResolvedResult {
+    <#
+    .SYNOPSIS
+        Convert a resolved root and session path into a SessionRoot or OtherWorktree result.
+    .DESCRIPTION
+        Labels the result SessionRoot when the root is the session's own worktree and
+        OtherWorktree otherwise, so that test is written once. Exported for issue #690 so
+        the run resolver shares this one labelling definition rather than a second copy.
+        The ConvertTo verb is deliberate: a New- verb is state-changing to PSScriptAnalyzer
+        and this function changes nothing.
+    .PARAMETER WorktreeRoot
+        The resolved worktree root.
+    .PARAMETER SessionRoot
+        The calling process's path.
+    .PARAMETER Detail
+        A prose clause safe to append to a gate's deny reason.
+    .PARAMETER Branch
+        Optional. The branch signal that produced the target.
+    #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param(
@@ -389,4 +403,5 @@ Export-ModuleMember -Function `
     Get-WorktreeItemCheckpointText, `
     Get-WorktreeItemCheckpointIssue, `
     Get-WorktreeItemLiveRoot, `
+    ConvertTo-WorktreeItemResolvedResult, `
     Resolve-WorktreeItemTarget