@danmoisan/drm-copilot-mcp 1.1.24 → 1.1.26

package/resources/claude-customizations/.claude/lib/parallel-admission/ParallelAdmissionPrecedence.psm1

@@ -0,0 +1,508 @@
+<#
+.SYNOPSIS
+    Pure precedence and scheduling-record functions for the parallel surface (issue #1047).
+
+.DESCRIPTION
+    Holds the operator precedence input of /parallel-plan and /parallel-add
+    (`--after`): validation of the precedence[] entries, their normalization into
+    separating conflict edges, the precedence lift over a cohort table, the
+    active-entry resolution and cohort-table check, and the durable scheduling
+    record with its edge-reuse rule.
+
+    A precedence entry {before, after} states that the `after` item must start
+    in a later cohort than the `before` item. It is a separating input, never a
+    `depends_on` key. Every function is pure: no filesystem, subprocess, network,
+    or clock access, and no input is mutated. Rejections throw a message that
+    starts with the rejection code (precedence_unknown_item, precedence_cycle).
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Get-ParallelPrecedenceMapValue {
+    <#
+    .SYNOPSIS
+        Return the value stored under Key in a dictionary, or null when the key or the map is absent.
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    param([AllowNull()][object] $Map, [string] $Key)
+
+    if ($Map -isnot [System.Collections.IDictionary]) { return $null }
+    if (-not $Map.Contains($Key)) { return $null }
+    return $Map[$Key]
+}
+
+function ConvertTo-ParallelPrecedenceKey {
+    <#
+    .SYNOPSIS
+        Convert an item key (integer or decimal-digit string) to Int64, or return null.
+    #>
+    [CmdletBinding()]
+    [OutputType([object], [long])]
+    param([AllowNull()][object] $Value)
+
+    if ($null -eq $Value -or $Value -is [bool]) { return $null }
+    $parsed = [long]0
+    if ($Value -is [string]) {
+        if ($Value -match '^[0-9]+$' -and [long]::TryParse($Value, [ref] $parsed)) { return $parsed }
+        return $null
+    }
+    if ($Value -is [int] -or $Value -is [long] -or $Value -is [int16] -or $Value -is [byte]) { return [long]$Value }
+    return $null
+}
+
+function Get-ParallelPrecedencePair {
+    <#
+    .SYNOPSIS
+        Read precedence entries into [before, after] Int64 pairs.
+
+    .DESCRIPTION
+        Each entry is a dictionary carrying `before` and `after`. An entry whose
+        key is missing or is not an integer throws precedence_unknown_item.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param([AllowNull()][AllowEmptyCollection()][object[]] $Entry = @())
+
+    $pairs = [System.Collections.Generic.List[object]]::new()
+    foreach ($item in @($Entry)) {
+        if ($null -eq $item) { continue }
+        $before = ConvertTo-ParallelPrecedenceKey -Value (Get-ParallelPrecedenceMapValue -Map $item -Key 'before')
+        $after = ConvertTo-ParallelPrecedenceKey -Value (Get-ParallelPrecedenceMapValue -Map $item -Key 'after')
+        if ($null -eq $before -or $null -eq $after) {
+            throw "precedence_unknown_item: a precedence entry must carry integer before and after item keys."
+        }
+        $pairs.Add([long[]]@($before, $after))
+    }
+    return , $pairs.ToArray()
+}
+
+function Get-ParallelPrecedenceOrder {
+    <#
+    .SYNOPSIS
+        Return the item keys in topological precedence order, ties by ascending key.
+
+    .DESCRIPTION
+        Kahn's algorithm over the before -> after pairs. Keys left unvisited lie on
+        a cycle, which throws precedence_cycle naming them.
+    #>
+    [CmdletBinding()]
+    [OutputType([long[]], [System.Object[]])]
+    param([AllowEmptyCollection()][object[]] $Pair = @(), [AllowEmptyCollection()][long[]] $ItemKey = @())
+
+    $keys = [System.Collections.Generic.SortedSet[long]]::new()
+    foreach ($key in @($ItemKey)) { [void]$keys.Add($key) }
+    # The loop variable is not named $pair: variable names are case-insensitive, so it would overwrite $Pair.
+    foreach ($edge in @($Pair)) { [void]$keys.Add($edge[0]); [void]$keys.Add($edge[1]) }
+    $inDegree = @{}
+    $successor = @{}
+    foreach ($key in $keys) { $inDegree[$key] = 0; $successor[$key] = [System.Collections.Generic.SortedSet[long]]::new() }
+    foreach ($edge in @($Pair)) {
+        if ($successor[$edge[0]].Add($edge[1])) { $inDegree[$edge[1]]++ }
+    }
+    $ready = [System.Collections.Generic.SortedSet[long]]::new()
+    foreach ($key in $keys) { if ($inDegree[$key] -eq 0) { [void]$ready.Add($key) } }
+    $order = [System.Collections.Generic.List[long]]::new()
+    while ($ready.Count -gt 0) {
+        $next = $ready.Min
+        [void]$ready.Remove($next)
+        $order.Add($next)
+        foreach ($after in $successor[$next]) {
+            $inDegree[$after]--
+            if ($inDegree[$after] -eq 0) { [void]$ready.Add($after) }
+        }
+    }
+    if ($order.Count -lt $keys.Count) {
+        $cyclic = @($keys | Where-Object { $order -notcontains $_ })
+        throw "precedence_cycle: the precedence entries form a cycle among items $($cyclic -join ', ')."
+    }
+    return , $order.ToArray()
+}
+
+function Test-ParallelPrecedenceInput {
+    <#
+    .SYNOPSIS
+        Validate precedence entries against the run's item keys.
+
+    .DESCRIPTION
+        Throws precedence_unknown_item when an entry names a key that is not an
+        item, and precedence_cycle when an entry pairs an item with itself or the
+        entries form a cycle. Returns true when the entries are valid.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()][AllowEmptyCollection()][object[]] $Entry = @(), [AllowEmptyCollection()][long[]] $ItemKey = @())
+
+    $pairs = Get-ParallelPrecedencePair -Entry $Entry
+    foreach ($pair in $pairs) {
+        foreach ($key in $pair) {
+            if (@($ItemKey) -notcontains $key) { throw "precedence_unknown_item: precedence entry $($pair[0]):$($pair[1]) names item $key, which is not an item of the run." }
+        }
+        if ($pair[0] -eq $pair[1]) { throw "precedence_cycle: precedence entry $($pair[0]):$($pair[1]) pairs an item with itself." }
+    }
+    [void](Get-ParallelPrecedenceOrder -Pair $pairs -ItemKey $ItemKey)
+    return $true
+}
+
+function ConvertTo-ParallelPrecedenceEdge {
+    <#
+    .SYNOPSIS
+        Normalize precedence entries into separating `a:b` edges with a < b.
+
+    .DESCRIPTION
+        Each before/after pair becomes the undirected edge `min:max`, so the
+        cohort coloring always separates the pair. Duplicates are removed and the
+        edges are sorted by (a, b).
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]], [System.Object[]])]
+    param([AllowNull()][AllowEmptyCollection()][object[]] $Entry = @())
+
+    $seen = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal)
+    $edges = [System.Collections.Generic.List[long[]]]::new()
+    foreach ($pair in (Get-ParallelPrecedencePair -Entry $Entry)) {
+        $a = [math]::Min($pair[0], $pair[1])
+        $b = [math]::Max($pair[0], $pair[1])
+        if ($a -eq $b -or -not $seen.Add("${a}:${b}")) { continue }
+        $edges.Add([long[]]@($a, $b))
+    }
+    $sorted = @($edges | Sort-Object -Property @{ Expression = { $_[0] } }, @{ Expression = { $_[1] } })
+    return , [string[]]@($sorted | ForEach-Object { "$($_[0]):$($_[1])" })
+}
+
+function Get-ParallelPrecedenceNeighbor {
+    <#
+    .SYNOPSIS
+        Build the undirected neighbor map of conflict edges plus precedence pairs.
+
+    .DESCRIPTION
+        Edge entries are `a:b` strings of integer keys; a malformed entry throws.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param([AllowEmptyCollection()][string[]] $Edge = @(), [AllowEmptyCollection()][object[]] $Pair = @())
+
+    $neighbor = @{}
+    foreach ($text in @($Edge)) {
+        if ([string]::IsNullOrWhiteSpace($text)) { continue }
+        if ($text -notmatch '^\s*([0-9]+):([0-9]+)\s*$') { throw "Conflict edge '$text' is not of the form <a>:<b>." }
+        Add-ParallelPrecedenceNeighborLink -Neighbor $neighbor -Left ([long]$Matches[1]) -Right ([long]$Matches[2])
+    }
+    foreach ($edgePair in @($Pair)) { Add-ParallelPrecedenceNeighborLink -Neighbor $neighbor -Left $edgePair[0] -Right $edgePair[1] }
+    return $neighbor
+}
+
+function Add-ParallelPrecedenceNeighborLink {
+    <#
+    .SYNOPSIS
+        Record one undirected link in a neighbor map (key to HashSet of keys), in both directions.
+    #>
+    [CmdletBinding()]
+    [OutputType([void])]
+    param([hashtable] $Neighbor, [long] $Left, [long] $Right)
+
+    foreach ($side in @(@($Left, $Right), @($Right, $Left))) {
+        if (-not $Neighbor.ContainsKey($side[0])) { $Neighbor[$side[0]] = [System.Collections.Generic.HashSet[long]]::new() }
+        [void]$Neighbor[$side[0]].Add($side[1])
+    }
+}
+
+function Invoke-ParallelPrecedenceLift {
+    <#
+    .SYNOPSIS
+        Lift unstarted `after` items into later cohorts than their `before` items.
+
+    .DESCRIPTION
+        Visits the cohort items in topological precedence order (ties by ascending
+        key). An unpinned `after` item whose cohort index is not above every
+        `before` index moves to the smallest index at or above both
+        max(before index) + 1 and Floor that holds no conflict neighbor (conflict
+        edges plus precedence pairs, pinned neighbors included). Pinned items
+        never move and unstarted items only move upward, so every cohort stays an
+        independent set and a second application changes nothing. A pinned
+        `after` item that violates its precedence is left in place; the
+        cohort-table check reports it.
+
+    .PARAMETER Cohort
+        The cohort table: one array of item keys per cohort index.
+
+    .PARAMETER Edge
+        Conflict edges as `a:b` strings.
+
+    .PARAMETER Precedence
+        precedence[] entries carrying `before` and `after`.
+
+    .PARAMETER Pinned
+        Item keys that have started and therefore cannot move.
+
+    .PARAMETER Floor
+        The lowest cohort index a moved item may take.
+
+    .OUTPUTS
+        System.Object[] of Int64 arrays, one per cohort; trailing empty cohorts are dropped.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [AllowEmptyCollection()][object[]] $Cohort = @(),
+        [AllowEmptyCollection()][string[]] $Edge = @(),
+        [AllowNull()][AllowEmptyCollection()][object[]] $Precedence = @(),
+        [AllowEmptyCollection()][long[]] $Pinned = @(),
+        [int] $Floor = 0
+    )
+
+    $table = [System.Collections.Generic.List[System.Collections.Generic.SortedSet[long]]]::new()
+    $position = @{}
+    foreach ($members in @($Cohort)) {
+        $set = [System.Collections.Generic.SortedSet[long]]::new()
+        foreach ($member in @($members)) {
+            $key = ConvertTo-ParallelPrecedenceKey -Value $member
+            if ($null -eq $key) { throw "Cohort member '$member' is not an integer item key." }
+            if ($position.ContainsKey($key)) { throw "Item $key appears in more than one cohort." }
+            [void]$set.Add($key)
+            $position[$key] = $table.Count
+        }
+        $table.Add($set)
+    }
+    $itemKey = [long[]]@($position.Keys)
+    [void](Test-ParallelPrecedenceInput -Entry $Precedence -ItemKey $itemKey)
+    $pairs = Get-ParallelPrecedencePair -Entry $Precedence
+    $neighbor = Get-ParallelPrecedenceNeighbor -Edge $Edge -Pair $pairs
+
+    foreach ($key in (Get-ParallelPrecedenceOrder -Pair $pairs -ItemKey $itemKey)) {
+        $before = @($pairs | Where-Object { $_[1] -eq $key } | ForEach-Object { $_[0] })
+        if ($before.Count -eq 0 -or @($Pinned) -contains $key) { continue }
+        $need = (@($before | ForEach-Object { $position[$_] }) | Measure-Object -Maximum).Maximum + 1
+        if ($position[$key] -ge $need) { continue }
+        $target = [math]::Max([int]$need, $Floor)
+        while ($true) {
+            while ($table.Count -le $target) { $table.Add([System.Collections.Generic.SortedSet[long]]::new()) }
+            $blocked = $neighbor.ContainsKey($key) -and @($table[$target] | Where-Object { $neighbor[$key].Contains($_) }).Count -gt 0
+            if (-not $blocked) { break }
+            $target++
+        }
+        [void]$table[$position[$key]].Remove($key)
+        [void]$table[$target].Add($key)
+        $position[$key] = $target
+    }
+    while ($table.Count -gt 0 -and $table[$table.Count - 1].Count -eq 0) { $table.RemoveAt($table.Count - 1) }
+    $result = [System.Collections.Generic.List[object]]::new()
+    foreach ($set in $table) { $result.Add([long[]]@($set)) }
+    return , $result.ToArray()
+}
+
+# A predecessor in one of these merge states, or in state withdrawn, no longer
+# constrains its dependent (decision D6). A blocked predecessor still holds.
+$script:ReleasedMergeStatus = @('merged', 'worktree_removed')
+
+function Get-ParallelActivePrecedence {
+    <#
+    .SYNOPSIS
+        Resolve the precedence entries that still constrain scheduling.
+
+    .DESCRIPTION
+        Each entry's keys are mapped to the item that carries them: an item
+        carries its own issue_num and every key in its combined_issue_nums, so a
+        combined item inherits the union of its members' entries, and a pair
+        inside one combination is dropped. An entry is inactive when its `before`
+        item has merge_status merged or worktree_removed, or state withdrawn; a
+        blocked predecessor holds (D6). A key that resolves to no item throws
+        precedence_unknown_item. Duplicate entries collapse to one.
+
+    .OUTPUTS
+        System.Object[] of pscustomobject {before, after}, sorted by (before, after).
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param([AllowNull()][AllowEmptyCollection()][object[]] $Precedence = @(), [AllowNull()][AllowEmptyCollection()][object[]] $Item = @())
+
+    $owner = @{}
+    $record = @{}
+    foreach ($entry in @($Item)) {
+        $key = ConvertTo-ParallelPrecedenceKey -Value (Get-ParallelPrecedenceMapValue -Map $entry -Key 'issue_num')
+        if ($null -eq $key) { continue }
+        $record[$key] = $entry
+        $owner[$key] = $key
+        foreach ($member in @(Get-ParallelPrecedenceMapValue -Map $entry -Key 'combined_issue_nums')) {
+            $memberKey = ConvertTo-ParallelPrecedenceKey -Value $member
+            if ($null -ne $memberKey) { $owner[$memberKey] = $key }
+        }
+    }
+    $active = [System.Collections.Generic.SortedDictionary[string, object]]::new([System.StringComparer]::Ordinal)
+    foreach ($pair in (Get-ParallelPrecedencePair -Entry $Precedence)) {
+        foreach ($side in $pair) {
+            if (-not $owner.ContainsKey($side)) { throw "precedence_unknown_item: precedence entry $($pair[0]):$($pair[1]) names item $side, which is not an item of the run." }
+        }
+        $before = [long]$owner[$pair[0]]
+        $after = [long]$owner[$pair[1]]
+        if ($before -eq $after) { continue }
+        $predecessor = $record[$before]
+        $mergeStatus = Get-ParallelPrecedenceMapValue -Map $predecessor -Key 'merge_status'
+        $state = Get-ParallelPrecedenceMapValue -Map $predecessor -Key 'state'
+        if ($script:ReleasedMergeStatus -ccontains $mergeStatus -or $state -ceq 'withdrawn') { continue }
+        $active[('{0:D20}:{1:D20}' -f $before, $after)] = [pscustomobject]@{ before = $before; after = $after }
+    }
+    return , [object[]]@($active.Values)
+}
+
+function Test-ParallelPrecedenceCohortTable {
+    <#
+    .SYNOPSIS
+        Check a parallel checkpoint's current-generation cohort table against its active precedence entries.
+
+    .DESCRIPTION
+        For each active entry, the cohort index of the `after` item must be
+        strictly greater than the index of the `before` item within the cohorts
+        whose generation equals recolor_generation. An entry whose item is in no
+        current-generation cohort is not compared. An absent precedence key gives
+        a satisfied table.
+
+    .OUTPUTS
+        pscustomobject with Satisfied, Violation (strings), and Active (the active entries).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([AllowNull()][object] $Checkpoint)
+
+    if ($Checkpoint -isnot [System.Collections.IDictionary]) { throw 'The parallel checkpoint must be a JSON object.' }
+    $active = Get-ParallelActivePrecedence -Precedence @(Get-ParallelPrecedenceMapValue -Map $Checkpoint -Key 'precedence') -Item @(Get-ParallelPrecedenceMapValue -Map $Checkpoint -Key 'items')
+    $generation = Get-ParallelPrecedenceMapValue -Map $Checkpoint -Key 'recolor_generation'
+    $index = @{}
+    foreach ($cohort in @(Get-ParallelPrecedenceMapValue -Map $Checkpoint -Key 'cohorts')) {
+        if ((Get-ParallelPrecedenceMapValue -Map $cohort -Key 'generation') -ne $generation) { continue }
+        $cohortIndex = Get-ParallelPrecedenceMapValue -Map $cohort -Key 'index'
+        foreach ($member in @(Get-ParallelPrecedenceMapValue -Map $cohort -Key 'item_keys')) {
+            $memberKey = ConvertTo-ParallelPrecedenceKey -Value $member
+            if ($null -ne $memberKey) { $index[$memberKey] = [long]$cohortIndex }
+        }
+    }
+    $violation = [System.Collections.Generic.List[string]]::new()
+    foreach ($entry in $active) {
+        if (-not $index.ContainsKey($entry.before) -or -not $index.ContainsKey($entry.after)) { continue }
+        if ($index[$entry.after] -le $index[$entry.before]) {
+            $violation.Add("item $($entry.after) in cohort $($index[$entry.after]) must follow item $($entry.before) in cohort $($index[$entry.before])")
+        }
+    }
+    return [pscustomobject]@{ Satisfied = ($violation.Count -eq 0); Violation = [string[]]$violation.ToArray(); Active = $active }
+}
+
+function ConvertTo-ParallelSchedulingProjection {
+    <#
+    .SYNOPSIS
+        Project each dictionary onto the named keys in ordinal key order; a missing key becomes null.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param([AllowNull()][AllowEmptyCollection()][object[]] $Value = @(), [string[]] $Key)
+
+    $sortedKey = [string[]]@($Key)
+    [Array]::Sort($sortedKey, [System.StringComparer]::Ordinal)
+    $projection = [System.Collections.Generic.List[object]]::new()
+    foreach ($entry in @($Value)) {
+        if ($entry -isnot [System.Collections.IDictionary]) { continue }
+        $row = [ordered]@{}
+        foreach ($name in $sortedKey) { $row[$name] = Get-ParallelPrecedenceMapValue -Map $entry -Key $name }
+        $projection.Add($row)
+    }
+    return , $projection.ToArray()
+}
+
+$script:RecordItemKey = @('issue_num', 'branch_name', 'plan_path', 'plan_hash', 'base_commit', 'preparation_status', 'complexity_band')
+
+function New-ParallelSchedulingRecord {
+    <#
+    .SYNOPSIS
+        Build the durable scheduling record docs/features/parallel/<slug>/parallel-scheduling.json.
+
+    .DESCRIPTION
+        The record carries exactly schema_version, parallel_slug, edges,
+        tolerated_overlaps, precedence, and items. Edges keep a, b, and reason;
+        tolerated overlaps keep a, b, reasons, cost, and benefit; precedence
+        entries keep before, after, source, and recorded_at; items keep
+        issue_num, branch_name, plan_path, plan_hash, base_commit,
+        preparation_status, and complexity_band. Keys are in ordinal order at
+        every level and lists are sorted by their keys, so the same input always
+        yields the same record. The function builds content only; the caller
+        writes and commits it.
+
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure record constructor; no state is changed.')]
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $Slug,
+        [AllowNull()][AllowEmptyCollection()][object[]] $Edge = @(),
+        [AllowNull()][AllowEmptyCollection()][object[]] $ToleratedOverlap = @(),
+        [AllowNull()][AllowEmptyCollection()][object[]] $Precedence = @(),
+        [AllowNull()][AllowEmptyCollection()][object[]] $Item = @()
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Slug)) { throw 'New-ParallelSchedulingRecord requires -Slug.' }
+    $byPair = @(@{ Expression = { [long]$_['a'] } }, @{ Expression = { [long]$_['b'] } })
+    # Each projection is parenthesized so the pipeline enumerates its rows rather than passing the array as one object.
+    $edges = @((ConvertTo-ParallelSchedulingProjection -Value $Edge -Key @('a', 'b', 'reason')) | Sort-Object -Property $byPair)
+    $tolerated = @((ConvertTo-ParallelSchedulingProjection -Value $ToleratedOverlap -Key @('a', 'b', 'reasons', 'cost', 'benefit')) | Sort-Object -Property $byPair)
+    $precedence = @((ConvertTo-ParallelSchedulingProjection -Value $Precedence -Key @('before', 'after', 'source', 'recorded_at')) |
+            Sort-Object -Property @{ Expression = { [long]$_['before'] } }, @{ Expression = { [long]$_['after'] } })
+    $items = @((ConvertTo-ParallelSchedulingProjection -Value $Item -Key $script:RecordItemKey) | Sort-Object -Property @{ Expression = { [long]$_['issue_num'] } })
+    $record = [ordered]@{}
+    $record['edges'] = [object[]]$edges
+    $record['items'] = [object[]]$items
+    $record['parallel_slug'] = $Slug
+    $record['precedence'] = [object[]]$precedence
+    $record['schema_version'] = [long]1
+    $record['tolerated_overlaps'] = [object[]]$tolerated
+    return $record
+}
+
+function Get-ParallelSchedulingRecordReuse {
+    <#
+    .SYNOPSIS
+        Decide whether a re-seed may reuse an item's recorded conflict edges.
+
+    .DESCRIPTION
+        Reuse applies only when the record lists the item and its recorded
+        plan_hash equals the current plan blob hash; the item's recorded edges
+        (those with the item at either end) are then returned. Otherwise the
+        result is a recompute marker with the reason unknown_item or
+        plan_hash_changed.
+
+    .OUTPUTS
+        pscustomobject with action (reuse or recompute), reason, and edges.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([AllowNull()][object] $Record, [long] $IssueNum, [AllowNull()][AllowEmptyString()][string] $CurrentPlanHash)
+
+    $recorded = @(@(Get-ParallelPrecedenceMapValue -Map $Record -Key 'items') | Where-Object {
+            (ConvertTo-ParallelPrecedenceKey -Value (Get-ParallelPrecedenceMapValue -Map $_ -Key 'issue_num')) -eq $IssueNum
+        })
+    if ($recorded.Count -eq 0) {
+        return [pscustomobject]@{ action = 'recompute'; reason = 'unknown_item'; edges = [object[]]@() }
+    }
+    $hash = Get-ParallelPrecedenceMapValue -Map $recorded[0] -Key 'plan_hash'
+    if ([string]::IsNullOrEmpty($CurrentPlanHash) -or [string]$hash -cne $CurrentPlanHash) {
+        return [pscustomobject]@{ action = 'recompute'; reason = 'plan_hash_changed'; edges = [object[]]@() }
+    }
+    $edges = @(@(Get-ParallelPrecedenceMapValue -Map $Record -Key 'edges') | Where-Object {
+            $_ -is [System.Collections.IDictionary] -and (
+                (ConvertTo-ParallelPrecedenceKey -Value $_['a']) -eq $IssueNum -or (ConvertTo-ParallelPrecedenceKey -Value $_['b']) -eq $IssueNum)
+        })
+    return [pscustomobject]@{ action = 'reuse'; reason = 'plan_hash_matches'; edges = [object[]]$edges }
+}
+
+Export-ModuleMember -Function `
+    ConvertTo-ParallelPrecedenceKey, `
+    Get-ParallelPrecedencePair, `
+    Get-ParallelPrecedenceOrder, `
+    Test-ParallelPrecedenceInput, `
+    ConvertTo-ParallelPrecedenceEdge, `
+    Invoke-ParallelPrecedenceLift, `
+    Get-ParallelActivePrecedence, `
+    Test-ParallelPrecedenceCohortTable, `
+    New-ParallelSchedulingRecord, `
+    Get-ParallelSchedulingRecordReuse

package/resources/claude-customizations/.claude/rules/parallel-orchestration.md

@@ -60,7 +60,7 @@ Enforced by `validate_parallel_orchestrator_state_text(text, *, require_complete
 
 9. **Blast-radius shape.** Each item's `blast_radius` must be an object carrying `paths`, `modules`, `shared_surfaces`, and `contracts` as lists of non-empty strings, a `source` in `{derived, declared, observed}`, and a non-empty `computed_at` string. `modules`, `shared_surfaces`, and `contracts` may be empty lists.
 
-10. **Prohibited dependency edges.** No object anywhere in the checkpoint may carry a `depends_on` key, and no top-level `depends_on` key may be present. Ordering is expressed only as blast-radius overlap. Presence is an explicit rejection, not mere absence.
+10. **Prohibited dependency edges.** No object anywhere in the checkpoint may carry a `depends_on` key, and no top-level `depends_on` key may be present. Ordering is expressed only as blast-radius overlap and as the operator precedence input declared in `## Prepared-Item Admission (issue #1047)`, which is a separating input and not a dependency key. Presence is an explicit rejection, not mere absence.
 
 11. **Prohibited integration-branch fields.** The checkpoint must not carry `integration_branch` or `epic_merge_pr` at any level. Each parallel item opens its own pull request against `main`, so there is no integration branch and no final integration pull request.
 
@@ -256,6 +256,22 @@ F3 deliberately excludes the kickoff-prompt contract module `scripts/dev_tools/p
 
 F3's `require_ready_for_execution` gate is STRUCTURAL ONLY. It enforces the kickoff-PATH invariant (P9: `kickoff_prompt_path` must equal `artifacts/orchestration/parallel-kickoff-<parallel_slug>.md`) and does not parse or cross-check kickoff CONTENT. The deeper readiness-integrity machinery of the epic surface — git-integrity checks, launch-evidence binding, and kickoff-contract cross-checks — is left to F4, which may layer repository-aware checks behind an additional keyword without changing the schema. F3 likewise does not recompute the cohort coloring (planner invariant P5).
 
+## Prepared-Item Admission (issue #1047)
+
+`/parallel-add` and `/parallel-plan` admit an item at the stage its pushed branch already reached. The decisions are made in code by the admission helper `.claude/lib/parallel-admission/Invoke-ParallelAdmission.ps1` (subcommands `guard-run`, `assess`, `order-cohorts`, `test-cohorts`, `record`, and `reuse-edges`). Every field below is tolerated and not validated: the Python validators and the TypeScript validator port accept it with zero errors, and no enum of `## Enum Ownership (F6/F7/F8 consume, never extend)` changes.
+
+**Tolerated item fields.** A parallel-orchestrator checkpoint item may carry `preparation_status` (`none|research|spec|plan|cleared`, as reported by `assess`), `plan_hash` (the git blob hash of the plan at the item branch head), `base_commit` (the commit the staleness check compares `origin/main` against), and `band_source` (`caller|planner_checkpoint|assessment`). A parallel-planner checkpoint item may carry `plan_hash` and `base_commit`. The planner keeps its ready value `preparation_status: prepared` (invariant P7), which corresponds to the admission stage `cleared`; no second ready value is introduced.
+
+**Precedence input.** Both checkpoints may carry a top-level `precedence[]` list of `{before, after, source, recorded_at}` entries, recorded from the operator's `--after` flags with `source` equal to `operator`. An entry states that the `after` item starts in a later cohort than the `before` item and only after the `before` item has merged. It is a separating input: each pair is passed to the cohort computation as an extra edge, and `order-cohorts` lifts an unstarted `after` item above its `before` item. It is not a `depends_on` key, and invariant 10, P3, and M7 are unchanged. Keys must resolve to items, an item is never paired with itself, and the entries must be acyclic. An entry is inactive once its `before` item has `merge_status` `merged` or `worktree_removed` or `state` `withdrawn`; a `blocked` predecessor still holds its dependent. A combined item inherits the union of its members' entries, and a pair inside one combination is dropped.
+
+**Preparation receipt.** The preparation child writes `<feature folder>/evidence/other/preparation-receipt.<yyyy-MM-ddTHH-mm>.json` before its commit, carrying `schema_version`, `stage`, `research_path`, `spec_path`, `plan_path`, `plan_hash`, `base_commit`, `preflight_status`, and `recorded_at`. The lexicographically greatest receipt name wins, a newer receipt supersedes an older one, and no receipt is deleted. A receipt whose `plan_hash` differs from the current blob hash is downgraded to `plan`.
+
+**Durable scheduling record.** `docs/features/parallel/<slug>/parallel-scheduling.json`, committed on `parallel/<slug>-plan`, carries `schema_version`, `parallel_slug`, `edges[]`, `tolerated_overlaps[]`, `precedence[]`, and `items[]` with `issue_num`, `branch_name`, `plan_path`, `plan_hash`, `base_commit`, `preparation_status`, and `complexity_band`. The planner writes it at seeding and `/parallel-add` rewrites it after each admission; the helper's `record` subcommand prints the content and performs no git write. A re-seed applies the reuse rule through the helper's `reuse-edges` subcommand, which reads the record by ref and reuses an item's recorded edges only when the recorded `plan_hash` equals the current blob hash. The run manifest stays read-only to the orchestrator.
+
+**Admission output signal.** A helper rule rejection exits 1 with one stderr line `PARALLEL_ADMISSION_REJECTED: <code>: <detail>`, where the code is one of `run_closed`, `precedence_cycle`, `precedence_unknown_item`, and `precedence_violated`. This signal is separate from the mutation rejection signal of `## Mutation Rejection Signal (issue #1012)`: a `run_closed` rejection is emitted after a checkpoint exists and emits no mutation rejection signal, and that section's closed code set is unchanged.
+
+**Known gap (Layer 2).** The Python orchestrator-state validator does not check precedence. Precedence is enforced by the helper's `test-cohorts` rejection and by Layer 1 of the cohort barrier hook (`Test-ParallelCohortBarrierClear` in `.claude/hooks/enforce-parallel-cohort-barrier-helpers.ps1`); the retrospective Layer 2 invariant reads `conflict_edges[]` only.
+
 ## Blast-Radius Contention Doctrine (issue #489)
 
 The conflict graph that seeds cohorts is only as good as the evidence that produces its edges. Two

package/resources/claude-customizations/.claude/settings.json

@@ -11,6 +11,7 @@
       "Bash(bash .claude/lib/bash/mutate-parallel-run.sh*)",
       "Bash(bash .claude/lib/bash/remove-parallel-item.sh*)",
       "Bash(bash .claude/lib/bash/validate-parallel-manifest.sh*)",
+      "Bash(pwsh -NoProfile -NonInteractive -File .claude/lib/parallel-admission/Invoke-ParallelAdmission.ps1*)",
       "Read",
       "Edit(docs/**)",
       "Edit(artifacts/**)",

package/resources/claude-customizations/.claude/skills/atomic-plan-contract/SKILL.md

@@ -248,7 +248,7 @@ Rules:
 - **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
 - **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
 - **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
-- **Name the runner and job for a Pester acceptance criterion.** In `.github/workflows/_poshqc.yml`, the Pester suites run with coverage on `windows-latest` in the shard jobs `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3`; `poshqc / PowerShell QC` is the aggregating required check, which requires the static and shard jobs to succeed and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. The execution-environment brief's `## CI Shape and Required Checks` section is the authoritative description of this shape. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
+- **Name the runner and job for a Pester acceptance criterion.** In `.github/workflows/_poshqc.yml`, the Pester suites run with coverage on `windows-latest` in the shard jobs `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3`; `poshqc / PowerShell QC` is the aggregating check, whose result `CI Required Gate` requires, and it requires the static and shard jobs to succeed and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. The execution-environment brief's `## CI Shape and Required Checks` section is the authoritative description of this shape. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
 - **Do not assert a fixed-string search literal that contains a backslash.** Git for Windows grep 3.0 reads a doubled backslash in a `grep -F` pattern as one backslash, so the same check returns a different count locally than on a CI runner and cannot pass in both places. Assert a backslash-free substring of the literal, a named test, or a hash or byte-identity check instead.
 
 ## Plan-Path Continuity Contract (Mandatory)