@danmoisan/drm-copilot-mcp 1.1.9 → 1.1.11

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadiusConflict.psm1

@@ -0,0 +1,290 @@
+<#
+.SYNOPSIS
+    Mechanically-mergeable path exclusion and the shared overlap helpers.
+
+.DESCRIPTION
+    Destination-runtime PowerShell mirror of
+    scripts/dev_tools/_blast_radius_mergeable.py (config_mergeable_paths,
+    matches_mergeable_path, exclude_mergeable_paths), plus the two overlap helpers
+    the relation calls (ports of _smallest_path_overlap and _smallest_common,
+    relocated here from BlastRadius.psm1).
+
+    The mergeable path class names the project-file shapes whose overlap a merge
+    step can reconcile without re-delegating the work (issue #643). Two items
+    touching the same .csproj are not genuinely in contention, so the class is
+    removed from both radii immediately before the relation compares them.
+
+    Parity notes for maintainers:
+      - The exclusion is applied ONLY inside Test-BlastRadiusConflict and changes
+        no radius record: a radius still lists every project file it cited, so
+        drift detection and validation see the paths they saw before this key.
+      - The key is optional and fail-closed: an absent mergeable_paths key and an
+        empty list both exclude nothing and reproduce pre-change behaviour.
+      - Every comparison is ordinal, matching the Python mirror's str equality.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusConfig.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusNormalization.psm1') -Force -ErrorAction Stop
+
+# Truth-table key naming the class, declared as a constant so the reader, its
+# tests, and the Python mirror all name one string rather than a literal.
+$script:ConfigMergeablePathKey = 'mergeable_paths'
+
+# Prefix making a configured pattern match at any depth. It is stripped in the
+# third matching step so a root-level file can satisfy it (Test-MergeablePath).
+$script:AnyDepthPrefix = '**/'
+
+# Separator used in an overlapping-pair detail string. The pair is ordered
+# ordinally before formatting so the detail is identical in both argument orders.
+$script:PairDetailSeparator = ' ~ '
+
+
+function Get-ConfigMergeablePath {
+    <#
+    .SYNOPSIS
+        Read the mechanically-mergeable path list from the truth table.
+
+    .DESCRIPTION
+        Port of config_mergeable_paths. The entries name project-file shapes,
+        normally anchored globs such as **/*.csproj (issue #643).
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json. Only the mergeable_paths key is read.
+
+    .OUTPUTS
+        System.Object[]. Entries sorted and deduplicated by the underlying reader.
+        A config with no mergeable_paths key yields an empty array.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config
+    )
+
+    return @(Get-ConfigStringList -Config $Config -Key $script:ConfigMergeablePathKey)
+}
+
+function Test-MergeablePath {
+    <#
+    .SYNOPSIS
+        Report whether one radius entry belongs to the mergeable path class.
+
+    .DESCRIPTION
+        Port of matches_mergeable_path. Three comparisons apply in order. The
+        first two are the read-by-mandate rules, delegated to Test-MandateRead
+        rather than restated: ordinal equality, the only rule that can settle a
+        glob entry, then glob containment for a concrete entry only. The third is
+        specific to this class, because an anchored pattern requires a separator
+        and so excludes a root-level file; retesting a concrete entry with the
+        anchor removed admits packages.config at the repository root.
+
+    .PARAMETER Entry
+        One radius paths entry: a concrete repository-relative path or a glob.
+
+    .PARAMETER MergeablePath
+        Configured patterns from Get-ConfigMergeablePath. An empty collection
+        matches nothing.
+
+    .OUTPUTS
+        System.Boolean. True when the entry belongs to the mergeable class and is
+        therefore excluded from the comparison. A glob entry is never mergeable
+        unless it equals a configured pattern character for character.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Entry,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $MergeablePath
+    )
+
+    # Steps one and two are the mandate-read rules verbatim, reused rather than
+    # duplicated: a divergence would silently split two exclusions that share a
+    # vocabulary.
+    if (Test-MandateRead -Entry $Entry -MandateRead $MergeablePath) {
+        return $true
+    }
+
+    # A glob entry that did not match exactly is left alone. Only a concrete path
+    # reaches the anchor-stripping step.
+    if (Test-GlobEntry -Entry $Entry) {
+        return $false
+    }
+
+    # Retest against each anchored pattern with its anchor removed, which is the
+    # only way a root-level file can satisfy an anchored pattern.
+    foreach ($pattern in $MergeablePath) {
+        if (-not $pattern.StartsWith($script:AnyDepthPrefix, [System.StringComparison]::Ordinal)) {
+            continue
+        }
+
+        $stripped = $pattern.Substring($script:AnyDepthPrefix.Length)
+        # A stripped pattern that still carries a wildcard is a glob and is
+        # matched as one; a wildcard-free remainder can only be compared for
+        # ordinal equality.
+        if (Test-GlobEntry -Entry $stripped) {
+            if (Test-GlobMatch -Pattern $stripped -Candidate $Entry) {
+                return $true
+            }
+        } elseif ([string]::Equals($stripped, $Entry, [System.StringComparison]::Ordinal)) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-NonMergeablePathEntry {
+    <#
+    .SYNOPSIS
+        Drop every mechanically-mergeable entry from a collection of paths.
+
+    .DESCRIPTION
+        Port of exclude_mergeable_paths. The caller passes the content by value,
+        so the radius record is never rewritten; only the contention comparison
+        sees the filtered collection.
+
+    .PARAMETER Entry
+        Radius paths entries to filter. An empty collection is accepted.
+
+    .PARAMETER MergeablePath
+        Configured patterns from Get-ConfigMergeablePath. An empty collection
+        excludes nothing, so the returned content equals the input.
+
+    .OUTPUTS
+        System.Object[]. Surviving entries, deduplicated and ordinally sorted.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Entry,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $MergeablePath
+    )
+
+    $survivor = [System.Collections.Generic.List[string]]::new()
+    foreach ($candidate in $Entry) {
+        # Deduplication and ordering are the sorter's job, matching the Python
+        # port's set-then-sorted construction.
+        if (-not (Test-MergeablePath -Entry $candidate -MergeablePath $MergeablePath)) {
+            $survivor.Add($candidate)
+        }
+    }
+
+    return @(Get-OrdinalSortedEntry -Entry $survivor.ToArray())
+}
+
+function Get-SmallestPathOverlap {
+    <#
+    .SYNOPSIS
+        Return the ordinally smallest overlapping path pair, or $null.
+
+    .DESCRIPTION
+        Port of _smallest_path_overlap. Each overlapping pair is ordered before
+        it is recorded, so the minimum is taken over a set that does not depend
+        on argument order; that is what makes the reported detail symmetric.
+
+    .PARAMETER PathA
+        First radius path collection. An empty collection is accepted.
+
+    .PARAMETER PathB
+        Second radius path collection. An empty collection is accepted.
+
+    .OUTPUTS
+        System.String. The smallest joined pair, or $null when nothing overlaps.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathA,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathB
+    )
+
+    $detail = [System.Collections.Generic.List[string]]::new()
+    foreach ($entryA in $PathA) {
+        foreach ($entryB in $PathB) {
+            if (-not (Test-EntryOverlap -EntryA $entryA -EntryB $entryB)) {
+                continue
+            }
+            $ordered = if ([string]::CompareOrdinal($entryA, $entryB) -le 0) {
+                @($entryA, $entryB)
+            } else {
+                @($entryB, $entryA)
+            }
+            $detail.Add($ordered -join $script:PairDetailSeparator)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $detail.ToArray())
+}
+
+function Get-SmallestCommonEntry {
+    <#
+    .SYNOPSIS
+        Return the ordinally smallest entry present in both collections.
+
+    .DESCRIPTION
+        Port of _smallest_common. Two empty collections share nothing, so the
+        result is $null and the level contributes no reason.
+
+    .PARAMETER Left
+        First collection. An empty collection is accepted.
+
+    .PARAMETER Right
+        Second collection. An empty collection is accepted.
+
+    .OUTPUTS
+        System.String. The smallest common entry, or $null when there is none.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Left,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Right
+    )
+
+    $rightSet = [System.Collections.Generic.HashSet[string]]::new($Right, [StringComparer]::Ordinal)
+    $common = [System.Collections.Generic.List[string]]::new()
+    foreach ($entry in $Left) {
+        if ($rightSet.Contains($entry)) {
+            $common.Add($entry)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $common.ToArray())
+}
+
+Export-ModuleMember -Function `
+    Get-ConfigMergeablePath, `
+    Test-MergeablePath, `
+    Get-NonMergeablePathEntry, `
+    Get-SmallestPathOverlap, `
+    Get-SmallestCommonEntry

package/resources/claude-customizations/.claude/lib/cleanup-manifest/CleanupWorktreeManifest.psm1

@@ -0,0 +1,415 @@
+<#
+.SYNOPSIS
+    Sanctioned-removal manifest reader for the two worktree-removal gate hooks
+    (issue #635).
+
+.DESCRIPTION
+    The cleanup-merged-worktrees skill records each per-worktree removal it has
+    triaged, together with the verdict and the evidence behind that verdict, in a
+    manifest document. This module owns reading that document and deciding whether
+    a given removal target is authorized by it. Both PreToolUse gate hooks consume
+    the decision; neither re-implements the parse.
+
+    Vocabulary. Two script-scope constants carry the narrow allow-sets the
+    predicate is written against, following the $script:AllowedMergeStatuses
+    precedent the two gate hooks already use. The removal-disposition set holds
+    exactly SAFE_TO_DELETE. The authorized-branch-state set holds exactly
+    NOT_MERGED and HAS_UNIQUE_RESIDUALS, which are the two states the skill
+    permanently forbids adding to the cleanup script's apply-mode allowlist and are
+    therefore the durable residual this manifest exists to serve.
+
+    Fail-closed posture. Every malformation resolves to a null parsed object or a
+    false predicate result. The module raises nothing on a malformed manifest, so a
+    hook consuming it always reaches its own unchanged deny path rather than
+    throwing.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies, no subprocess,
+    and no network. The single filesystem read and the single wall-clock read each
+    sit behind an injectable seam so tests drive them without writing a temporary
+    file. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Repo-relative location of the sanctioned-removal manifest. Kept as a script-scope
+# constant so the read seam is the only function that names the path.
+$script:CleanupWorktreeManifestPath = 'artifacts/orchestration/cleanup-worktrees-manifest.json'
+
+# The only removal disposition that authorizes anything. Deliberately a
+# single-member set rather than a bare string comparison, so a widening of the set
+# is a visible edit to a named constant that a test pins.
+$script:AllowedRemovalDispositions = @('SAFE_TO_DELETE')
+
+# The branch states a manifest record may authorize a removal for. PROTECTED_CURRENT
+# is never authorized, and the three merged states are excluded because the cleanup
+# script's deterministic path owns them.
+$script:AuthorizedBranchStates = @('NOT_MERGED', 'HAS_UNIQUE_RESIDUALS')
+
+# The step-5 verdicts that may authorize a removal. Derived from the skill's
+# five-member verdict vocabulary -- DEAD_ONE_OFF, ALREADY_SOLVED_ELSEWHERE,
+# STALE_OR_CONTRADICTED, GENUINELY_NEW, STILL_RELEVANT -- with the two
+# preserve-implying members removed, because the skill classifies both as content
+# that must be preserved before the worktree is deleted. Recorded as the authorized
+# subset rather than as the vocabulary plus an exclusion list, so a verdict added to
+# the vocabulary later is not authorized by silence.
+$script:AuthorizedRemovalVerdicts = @('DEAD_ONE_OFF', 'ALREADY_SOLVED_ELSEWHERE', 'STALE_OR_CONTRADICTED')
+
+# The self-identifying discriminator and the contract version this module reads.
+$script:ExpectedManifestTool = 'cleanup-merged-worktrees'
+$script:ExpectedManifestSchemaVersion = 1
+
+# Freshness bound. artifacts/ is gitignored, so a stale manifest persists after its
+# run ends, and cleanup targets are ordinary long-lived worktree paths rather than
+# session-stamped ones, which makes a stale collision materially re-matchable.
+$script:ManifestFreshnessBound = [timespan]::FromHours(24)
+
+function Get-CleanupWorktreeManifestContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the sanctioned-removal manifest. Tests mock this
+        function (read seam).
+    .DESCRIPTION
+        The only filesystem read in this module. An absent manifest is an ordinary
+        state rather than an error, so the function returns $null instead of
+        throwing and the caller resolves it to a non-authorizing parse.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:CleanupWorktreeManifestPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:CleanupWorktreeManifestPath -Raw)
+}
+
+function Get-CleanupWorktreeManifestUtcNow {
+    <#
+    .SYNOPSIS
+        Read the current UTC time. Tests mock this function (clock seam).
+    .DESCRIPTION
+        The only wall-clock read in this module. Freshness evaluation calls it once
+        per predicate evaluation, so a mocked value governs the whole comparison and
+        no test depends on real elapsed time.
+    .OUTPUTS
+        System.DateTime
+    #>
+    [CmdletBinding()]
+    [OutputType([datetime])]
+    param()
+
+    return [datetime]::UtcNow
+}
+
+function ConvertTo-CleanupWorktreeManifestNormalizedPath {
+    <#
+    .SYNOPSIS
+        Normalize a worktree path so both sides of a comparison share one spelling.
+    .DESCRIPTION
+        Replaces backslashes with forward slashes, then trims a single trailing
+        slash. Applied to the command target and to every recorded worktree_path,
+        so a trailing-slash target, a Windows-separator target, and a recorded
+        POSIX path all compare equal.
+    .PARAMETER Path
+        The raw path to normalize, or $null.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Path
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Path)) {
+        return ''
+    }
+    return ($Path -replace '\\', '/').TrimEnd('/')
+}
+
+function Find-CleanupWorktreeManifestRemovalRecord {
+    <#
+    .SYNOPSIS
+        Locate the removals[] record whose worktree_path matches the removal target.
+    .DESCRIPTION
+        Parses the manifest text behind a fail-closed try/catch: unparseable text
+        yields $null rather than a throw, matching the gate hooks' conventions.
+        Scanning stops at the FIRST normalized path match, so two records sharing a
+        path resolve on the first, following the parallel-branch precedent in the
+        epic gate. A record with no worktree_path key is skipped and the scan
+        continues.
+    .PARAMETER Raw
+        Raw manifest text, or $null when the manifest does not exist.
+    .PARAMETER WorktreePath
+        The removal target extracted from the command text.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Raw,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $WorktreePath
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Raw) -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $null
+    }
+
+    try {
+        $manifest = $Raw | ConvertFrom-Json
+    } catch {
+        $manifest = $null
+    }
+    if ($null -eq $manifest) {
+        return $null
+    }
+
+    $manifestProperties = @($manifest.PSObject.Properties.Name)
+    if ($manifestProperties -notcontains 'removals') {
+        return $null
+    }
+
+    $normalizedTarget = ConvertTo-CleanupWorktreeManifestNormalizedPath -Path $WorktreePath
+
+    foreach ($record in @($manifest.removals)) {
+        if ($null -eq $record) {
+            continue
+        }
+        $recordProperties = @($record.PSObject.Properties.Name)
+        if ($recordProperties -notcontains 'worktree_path') {
+            continue
+        }
+        $normalizedRecordPath = ConvertTo-CleanupWorktreeManifestNormalizedPath -Path ([string]$record.worktree_path)
+        if ($normalizedRecordPath -eq $normalizedTarget) {
+            return $record
+        }
+    }
+    return $null
+}
+
+function Test-CleanupWorktreeManifestAuthorizesRemoval {
+    <#
+    .SYNOPSIS
+        Decide whether the sanctioned-removal manifest authorizes removing a
+        worktree.
+    .DESCRIPTION
+        Evaluates conditions 1 through 9 of the specification's allow predicate in
+        order: parse, tool and schema version, freshness against the injected
+        clock, removals present and non-empty, first normalized path match, removal
+        disposition, evidence, verdict, and branch state. Conditions 1 through 4
+        are evaluated before the path scan so an absent or malformed manifest costs
+        one existence test and returns to the caller's deny path.
+
+        The function returns a boolean and raises nothing: every malformation
+        resolves to $false. It never reads the preserved_files array, which belongs
+        to a different consumer and must not influence any gate decision.
+
+        Condition 10, checkpoint exclusion, is NOT evaluated here. It is the
+        caller's obligation, because the two gate hooks own the checkpoint seams.
+    .PARAMETER WorktreePath
+        The removal target extracted from the command text.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $WorktreePath
+    )
+
+    if ([string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $false
+    }
+
+    # Condition 1 -- the manifest exists, is readable, and parses as JSON.
+    $raw = Get-CleanupWorktreeManifestContent
+    if ([string]::IsNullOrWhiteSpace($raw)) {
+        return $false
+    }
+    try {
+        $manifest = $raw | ConvertFrom-Json
+    } catch {
+        $manifest = $null
+    }
+    if ($null -eq $manifest) {
+        return $false
+    }
+    $manifestProperties = @($manifest.PSObject.Properties.Name)
+
+    # Condition 2 -- the self-identifying discriminator and the contract version.
+    if ($manifestProperties -notcontains 'tool' -or $manifestProperties -notcontains 'schema_version') {
+        return $false
+    }
+    if ($manifest.tool -isnot [string] -or $manifest.tool -cne $script:ExpectedManifestTool) {
+        return $false
+    }
+    $schemaVersion = $manifest.schema_version
+    if ($schemaVersion -isnot [int] -and $schemaVersion -isnot [long]) {
+        return $false
+    }
+    if ([long]$schemaVersion -ne [long]$script:ExpectedManifestSchemaVersion) {
+        return $false
+    }
+
+    # Condition 3 -- freshness, measured against the injected clock only.
+    if ($manifestProperties -notcontains 'generated_at') {
+        return $false
+    }
+    $generatedAt = [datetime]::MinValue
+    $parseStyles = [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal
+    $isTimestampParsed = [datetime]::TryParse(
+        [string]$manifest.generated_at,
+        [cultureinfo]::InvariantCulture,
+        $parseStyles,
+        [ref] $generatedAt)
+    if (-not $isTimestampParsed) {
+        return $false
+    }
+    $utcNow = Get-CleanupWorktreeManifestUtcNow
+    if ($generatedAt -gt $utcNow) {
+        return $false
+    }
+    if (($utcNow - $generatedAt) -gt $script:ManifestFreshnessBound) {
+        return $false
+    }
+
+    # Condition 4 -- removals is present, is an array, and is non-empty.
+    if ($manifestProperties -notcontains 'removals') {
+        return $false
+    }
+    $removals = $manifest.removals
+    if ($null -eq $removals -or $removals -isnot [System.Collections.IList]) {
+        return $false
+    }
+    if (@($removals).Count -lt 1) {
+        return $false
+    }
+
+    # Condition 5 -- the first record whose normalized path matches the target.
+    $record = Find-CleanupWorktreeManifestRemovalRecord -Raw $raw -WorktreePath $WorktreePath
+    if ($null -eq $record) {
+        return $false
+    }
+    $recordProperties = @($record.PSObject.Properties.Name)
+
+    # Condition 6 -- the removal disposition is in the single-member allowed set.
+    if ($recordProperties -notcontains 'removal_disposition') {
+        return $false
+    }
+    if ($script:AllowedRemovalDispositions -cnotcontains ([string]$record.removal_disposition)) {
+        return $false
+    }
+
+    # Condition 7 -- the evidence justification is a present, non-empty string.
+    if ($recordProperties -notcontains 'evidence') {
+        return $false
+    }
+    if ($record.evidence -isnot [string] -or [string]::IsNullOrWhiteSpace($record.evidence)) {
+        return $false
+    }
+
+    # Condition 8 -- the verdict is one the skill does not classify as preserve.
+    if ($recordProperties -notcontains 'verdict') {
+        return $false
+    }
+    if ($script:AuthorizedRemovalVerdicts -cnotcontains ([string]$record.verdict)) {
+        return $false
+    }
+
+    # Condition 9 -- the branch state is one of the two durable-residual states.
+    if ($recordProperties -notcontains 'branch_state') {
+        return $false
+    }
+    if ($script:AuthorizedBranchStates -cnotcontains ([string]$record.branch_state)) {
+        return $false
+    }
+
+    return $true
+}
+
+function Test-CleanupManifestCheckpointCoversPath {
+    <#
+    .SYNOPSIS
+        Report whether an orchestration checkpoint records the removal target at
+        all.
+    .DESCRIPTION
+        Condition 10 of the specification's allow predicate. This is a PRESENCE
+        test, deliberately not an authorization test: a record matching the target
+        makes the manifest branch inapplicable regardless of that record's
+        merge_status, so a removal the checkpoint does not authorize still reaches
+        the gate's existing deny. Reusing the gates' merge_status predicate here
+        would reopen the one path by which the manifest could widen what the gates
+        protect.
+    .PARAMETER Checkpoint
+        Parsed checkpoint object, or $null when absent or unreadable.
+    .PARAMETER RecordArrayName
+        Name of the record array to scan: features for the epic checkpoint, items
+        for the parallel checkpoint.
+    .PARAMETER WorktreePath
+        The removal target extracted from the command text.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string] $RecordArrayName,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $WorktreePath
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $false
+    }
+    $checkpointProperties = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProperties -notcontains $RecordArrayName) {
+        return $false
+    }
+
+    $normalizedTarget = ConvertTo-CleanupWorktreeManifestNormalizedPath -Path $WorktreePath
+
+    foreach ($record in @($Checkpoint.PSObject.Properties[$RecordArrayName].Value)) {
+        if ($null -eq $record) {
+            continue
+        }
+        $recordProperties = @($record.PSObject.Properties.Name)
+        if ($recordProperties -notcontains 'worktree_path') {
+            continue
+        }
+        $normalizedRecordPath = ConvertTo-CleanupWorktreeManifestNormalizedPath -Path ([string]$record.worktree_path)
+        if ($normalizedRecordPath -eq $normalizedTarget) {
+            return $true
+        }
+    }
+    return $false
+}
+
+Export-ModuleMember -Function `
+    Get-CleanupWorktreeManifestContent, `
+    Get-CleanupWorktreeManifestUtcNow, `
+    ConvertTo-CleanupWorktreeManifestNormalizedPath, `
+    Find-CleanupWorktreeManifestRemovalRecord, `
+    Test-CleanupWorktreeManifestAuthorizesRemoval, `
+    Test-CleanupManifestCheckpointCoversPath