@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

@@ -68,31 +68,23 @@ $script:PlanTaskPattern = [regex]::new(
 # on its own line, from producing spurious spans.
 $script:InlineCodeSpanPattern = [regex]::new('`([^`]+)`')
 
-# Top-level directories of this repository. A token starting with one of these is
-# accepted without needing a recognized extension, which admits ** globs naming a
-# subtree. artifacts/ is deliberately absent (issue #489): the process-artifact
-# tree is read by mandate rather than written by a work item, so admitting
-# artifacts/** as a subtree claim made unrelated items contend.
+# Top-level directories of this repository. A wildcard token starting with one of
+# these is accepted without its final component naming a file (issue #797), which
+# admits ** globs naming a subtree. artifacts/ is deliberately absent (issue
+# #489): the process-artifact tree is read by mandate rather than written by a
+# work item, so admitting artifacts/** as a subtree claim made unrelated items
+# contend.
 $script:KnownTopLevelSegment = @(
     'scripts/', 'tests/', 'docs/', 'config/', 'schemas/', 'packages/',
     'extensions/', '.claude/', '.codex/', '.github/', '.agents/'
 )
 
 # A file citation may carry a trailing line reference such as :90. The suffix is
-# stripped before the extension test so a line-anchored citation keeps the
-# acceptance its unanchored form has; the token itself is recorded verbatim.
+# stripped before the file-shape test (issue #797) so a line-anchored citation
+# keeps the acceptance its unanchored form has; the token itself is recorded
+# verbatim.
 $script:LineSuffixPattern = [regex]::new(':\d+$')
 
-# Fallback acceptance rule: a token shaped <segment>/.../<name>.<ext> counts as a
-# repository path when its final component carries one of these extensions.
-$script:RecognizedPathExtension = [System.Collections.Generic.HashSet[string]]::new(
-    [string[]] @(
-        'cfg', 'cs', 'csproj', 'ini', 'js', 'json', 'jsx', 'lock', 'md', 'ps1',
-        'psd1', 'psm1', 'py', 'sh', 'sln', 'toml', 'ts', 'tsx', 'txt', 'xml',
-        'yaml', 'yml'
-    ),
-    [StringComparer]::Ordinal)
-
 # Classification vocabulary for accepted path tokens. Concrete entries take part
 # in exact-match checks; glob entries cannot and are matched by pattern.
 $script:PathKindConcrete = 'concrete'
@@ -249,8 +241,11 @@ function Get-PathTokenKind {
         bare word such as a function name is a contract identifier, not a path.
         It must also be repository-relative: a leading separator marks an absolute
         path and a colon in the leading segment marks a URL scheme or a Windows
-        drive. Acceptance then requires one of the two documented shape rules, a
-        known top-level segment or a recognized final extension.
+        drive. A wildcard-free token is then accepted only when its final
+        component, after any :<line> suffix is stripped, names a file according
+        to Test-FileShapedComponent (a letter-led extension or a known file
+        name, issue #797); a wildcard token needs a known top-level segment or
+        such a final component.
 
         A token carrying any configured placeholder or interpolation marker is
         rejected wherever the marker sits, because it documents a shape rather
@@ -305,7 +300,7 @@ function Get-PathTokenKind {
     # disagree, and putting the cheaper marker scan first would only add work to
     # the common accepted case. It runs BEFORE the separator guard because a
     # marker-bearing token frequently does carry a separator and would otherwise
-    # sail past that guard and reach the extension rule, which accepts it: the
+    # sail past that guard and reach the file-shape rule, which accepts it: the
     # dominant corpus shape is an angle-bracketed leading segment followed by a
     # real .md tail, and that is exactly the token this guard exists to reject.
     if (Test-PlaceholderMarker -Token $Token) {
@@ -320,26 +315,20 @@ function Get-PathTokenKind {
         return $null
     }
 
-    # Read the final component's extension for the fallback acceptance rule; a
-    # component with no dot (a directory name or **) has no extension. A trailing
-    # line reference is stripped first so file.md:90 reads as md rather than as
-    # the unrecognized extension md:90.
+    # Decide whether the final component names a file (issue #797): a letter-led
+    # extension or a known file name does; a directory name, a dot-directory, **,
+    # a digit-led tail, and a trailing dot do not. A trailing line reference is
+    # stripped first so file.md:90 reads as file.md rather than as md:90.
     $finalComponent = $script:LineSuffixPattern.Replace(
         $Token.Substring($Token.LastIndexOf('/') + 1), '')
-    $extension = ''
-    $dotIndex = $finalComponent.LastIndexOf('.')
-    if ($dotIndex -ge 0) {
-        $extension = $finalComponent.Substring($dotIndex + 1).ToLowerInvariant()
-    }
-
-    $hasExtension = $script:RecognizedPathExtension.Contains($extension)
+    $namesFile = Test-FileShapedComponent -Component $finalComponent
 
     # A wildcard-free token must name a file, not a directory (issue #489). A
     # directory-shaped token such as scripts/dev_tools is a location reference,
     # not a write claim, and admitting it made every item touching anything under
     # that directory contend at the path level.
     if ($Token.IndexOf('*') -lt 0) {
-        if ($hasExtension) {
+        if ($namesFile) {
             return $script:PathKindConcrete
         }
         return $null
@@ -356,7 +345,7 @@ function Get-PathTokenKind {
     # A wildcard-bearing token must still satisfy one of the two documented shape
     # rules; failing both means the token is prose or a non-path expression that
     # merely contains a separator, so it is dropped.
-    if (-not $hasKnownSegment -and -not $hasExtension) {
+    if (-not $hasKnownSegment -and -not $namesFile) {
         return $null
     }
 
@@ -469,6 +458,7 @@ Export-ModuleMember -Function `
     Get-InlineCodeToken, `
     Test-PlaceholderMarker, `
     Test-MultipleFeatureFolderSpan, `
+    Test-FileShapedComponent, `
     Get-PathTokenKind, `
     Get-PathFromLine, `
     Get-PlanPaths

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

@@ -44,11 +44,17 @@
         exactly the two members that matter most.
       - Substring search uses [System.StringComparison]::Ordinal so the result
         is culture-independent and matches Python's byte-wise 'in' operator.
-      - Both predicates are total on every string, including the empty string, a
-        token consisting only of a marker, and a bare bracket pair. Neither
-        throws for any input, because the classifier that calls them runs over
-        every inline-code span in a document and a throw would abort an entire
-        derivation over one stray span.
+      - Every predicate is total on every string, including the empty string, a
+        token consisting only of a marker, a bare bracket pair, and a lone dot.
+        None throws for any input, because the classifier that calls them runs
+        over every inline-code span in a document and a throw would abort an
+        entire derivation over one stray span.
+      - Test-FileShapedComponent (issue #797) ports is_file_shaped_component.
+        Its extension pattern text is identical to FILE_EXTENSION_PATTERN_TEXT
+        and its known-name set equals KNOWN_FILE_NAMES; a Pester test reads both
+        from the Python source and pins them equal. A non-ASCII extension is
+        rejected before lower-casing (issue #903); ToLowerInvariant then matches
+        Python's str.lower on ASCII input, and known-name membership is ordinal.
     CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
 #>
 
@@ -84,6 +90,30 @@ $script:PlaceholderMarker = [string[]]@(
 $script:FeatureCorpusPrefix = 'docs/features/'
 $script:FeatureFolderSegmentIndex = 1
 
+# File-shape extension pattern (issue #797). A final component names a file when
+# the text after its last dot, lower-cased, is an ASCII letter followed by ASCII
+# letters or digits. The pattern text is identical to FILE_EXTENSION_PATTERN_TEXT
+# in the Python reference; \A and \z anchor the whole string without admitting a
+# trailing newline, which matches Python's re.fullmatch. The regex is built with
+# no options, so matching is case-sensitive and the explicit ASCII classes match
+# exactly the inputs the Python pattern matches.
+$script:FileExtensionPatternText = '[a-z][a-z0-9]*'
+$script:FileExtensionPattern = [regex]::new('\A' + $script:FileExtensionPatternText + '\z')
+$script:NonAsciiPattern = [regex]::new('[^\x00-\x7F]')
+
+# Known extensionless file names and dotfiles (issue #797). Membership is exact
+# and ordinal, matching Python's frozenset membership. The set is closed and is
+# pinned equal to KNOWN_FILE_NAMES in the Python reference by a Pester parity
+# test that reads the Python source, so edit both files together.
+$script:KnownFileName = [System.Collections.Generic.HashSet[string]]::new(
+    [string[]] @(
+        'Dockerfile', 'Makefile', 'LICENSE', 'CODEOWNERS', 'NOTICE', '.gitignore',
+        '.gitattributes', '.gitkeep', '.gitmodules', '.vscodeignore', '.npmignore',
+        '.npmrc', '.nvmrc', '.editorconfig', '.prettierrc', '.prettierignore',
+        '.eslintignore', '.shellcheckrc'
+    ),
+    [StringComparer]::Ordinal)
+
 function Test-PlaceholderMarker {
     <#
     .SYNOPSIS
@@ -184,6 +214,56 @@ function Test-MultipleFeatureFolderSpan {
     return $false
 }
 
+function Test-FileShapedComponent {
+    <#
+    .SYNOPSIS
+        Report whether a final path component names a file (issue #797).
+
+    .DESCRIPTION
+        Port of is_file_shaped_component. The classifier formerly admitted a
+        wildcard-free token only when its extension appeared in a fixed
+        allowlist, so files a plan writes with an unlisted extension, dotfiles,
+        and extensionless names were dropped from the derived radius. This
+        predicate replaces the allowlist with a structural rule that still
+        rejects the directory-shaped tokens of issue #489: a component with no
+        dot, a dot-leading component outside the known-name set, a digit-led
+        tail, and a trailing dot all report false.
+
+    .PARAMETER Component
+        The final path component, after any :<line> suffix has been stripped.
+        The empty string is accepted and reports false.
+
+    .OUTPUTS
+        System.Boolean. True when the component is an ordinal member of the
+        known-name set, or when it has a non-empty stem before its last dot and
+        the lower-cased text after that dot fully matches the extension pattern;
+        otherwise false.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Component
+    )
+
+    if ($script:KnownFileName.Contains($Component)) {
+        return $true
+    }
+
+    # LastIndexOf returns -1 when there is no dot and 0 when the dot leads the
+    # component; both leave no stem, so neither names a file by this rule.
+    $dotIndex = $Component.LastIndexOf('.')
+    if ($dotIndex -le 0) {
+        return $false
+    }
+
+    $extension = $Component.Substring($dotIndex + 1)
+    if ($script:NonAsciiPattern.IsMatch($extension)) { return $false }
+    return $script:FileExtensionPattern.IsMatch($extension.ToLowerInvariant())
+}
+
 Export-ModuleMember -Function `
     Test-PlaceholderMarker, `
-    Test-MultipleFeatureFolderSpan
+    Test-MultipleFeatureFolderSpan, `
+    Test-FileShapedComponent

package/resources/claude-customizations/.claude/lib/ci-gate/Invoke-CiGateParser.ps1

@@ -5,7 +5,7 @@
 
 .DESCRIPTION
     Consumes the JSON array emitted by
-    `gh pr checks --required --json bucket,name,state,link,workflow` and produces
+    `gh pr checks --json bucket,name,state,link,workflow` and produces
     the `ci_gate` object the orchestrator writes to its checkpoint. The object
     carries the five contract fields: head_sha, pr_pipeline_run_id,
     pr_pipeline_run_url, conclusion, and verified_at.
@@ -17,25 +17,33 @@
     the logic is deterministically testable.
 
     Conclusion derivation (per the documented bucket mapping):
-      - Any required check with bucket 'fail' or 'cancel'  -> conclusion 'failure'
-      - Else any required check with bucket 'pending'       -> conclusion 'pending'
+      - Any check with bucket 'fail' or 'cancel'  -> conclusion 'failure'
+      - Else any check with bucket 'pending'       -> conclusion 'pending'
       - Else (all checks 'pass' or 'skipping', or empty set) -> conclusion 'success'
-    An empty required-check set is treated as 'success' (vacuously satisfied: no
-    required check can fail or be in progress). An unrecognized bucket value is a
+    An empty check set is treated as 'success' (vacuously satisfied: no
+    check can fail or be in progress). An unrecognized bucket value is a
     fail-fast error so the parser never silently passes an enum it does not
     understand.
 
+    Epic-child guard (-RequireWorkflow): when -RequireWorkflow names a workflow
+    (S9 passes 'CI' when the checkpoint epic_mode is true), the empty-set rule
+    above does not apply. Failure and pending precedence is unchanged over every
+    observed check; the conclusion is 'success' only when at least one observed
+    check whose workflow property equals the name (case-sensitive) has bucket
+    'pass', and 'pending' otherwise. An empty or null check set therefore yields
+    'pending'. The default value ('') keeps the behavior described above.
+
     The verified_at timestamp is produced through an injectable clock delegate
     (-NowProvider) so tests can assert an exact deterministic value without
     reading the wall clock.
 
 .PARAMETER ChecksJson
-    The JSON array string emitted by `gh pr checks --required --json ...`. Each
+    The JSON array string emitted by `gh pr checks --json ...`. Each
     element is expected to expose at least a `bucket` property. Accepts pipeline
     / stdin input so the orchestrator can pipe the `gh` output directly.
 
 .PARAMETER HeadSha
-    The PR head SHA the required checks were observed against. Recorded verbatim
+    The PR head SHA the queried checks were observed against. Recorded verbatim
     as ci_gate.head_sha.
 
 .PARAMETER PrPipelineRunId
@@ -51,15 +59,26 @@
     ci_gate.verified_at. Defaults to a UTC Get-Date formatted as ISO-8601. Tests
     inject a fixed delegate to make verified_at deterministic.
 
+.PARAMETER RequireWorkflow
+    Optional workflow name (default ''). When non-empty, the conclusion is
+    'success' only after at least one check whose `workflow` property equals
+    this value (case-sensitive) has bucket 'pass'; an empty or null check set
+    yields 'pending'. S9 passes 'CI' for an epic-child PR. A whitespace-only
+    value is rejected with an error.
+
 .PARAMETER AsJson
     When set, emits the ci_gate object as a JSON string instead of a PowerShell
     object. The default (object) output is convenient for in-process callers; the
     JSON output is convenient for checkpoint serialization.
 
 .EXAMPLE
-    gh pr checks --required --json bucket,name,state,link,workflow |
+    gh pr checks --json bucket,name,state,link,workflow |
         ./.claude/lib/ci-gate/Invoke-CiGateParser.ps1 -HeadSha $sha
 
+.EXAMPLE
+    gh pr checks --json bucket,name,state,link,workflow |
+        ./.claude/lib/ci-gate/Invoke-CiGateParser.ps1 -HeadSha $sha -RequireWorkflow CI
+
 .OUTPUTS
     A PSCustomObject (or JSON string when -AsJson is set) with properties
     head_sha, pr_pipeline_run_id, pr_pipeline_run_url, conclusion, verified_at.
@@ -84,6 +103,9 @@ param(
     [ValidateNotNull()]
     [ScriptBlock]$NowProvider = { (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') },
 
+    [Parameter(Mandatory = $false)]
+    [string]$RequireWorkflow = '',
+
     [Parameter(Mandatory = $false)]
     [switch]$AsJson
 )
@@ -96,7 +118,7 @@ begin {
     function Get-CiGateConclusion {
         <#
     .SYNOPSIS
-        Pure derivation of ci_gate.conclusion from a parsed required-check set.
+        Pure derivation of ci_gate.conclusion from a parsed check set.
 
     .DESCRIPTION
         Implements the documented bucket precedence with no I/O and no external
@@ -109,9 +131,20 @@ begin {
         bucket value outside the known enum throws a fail-fast error naming the
         unrecognized value, preventing a silent pass on an unknown state.
 
+        With -RequireWorkflow set, one rule follows the pending rule: when no
+        check whose `workflow` property equals the name (case-sensitive) has
+        bucket 'pass', the result is 'pending'. An empty or null set then yields
+        'pending' instead of 'success'.
+
     .PARAMETER Checks
-        The parsed required-check collection (each element exposing a `bucket`
-        property). May be $null or empty, which yields 'success'.
+        The parsed check collection (each element exposing a `bucket`
+        property). May be $null or empty, which yields 'success' unless
+        -RequireWorkflow is set.
+
+    .PARAMETER RequireWorkflow
+        Optional workflow name; '' (default) disables the guard. A
+        whitespace-only value throws. An element without a `workflow` property
+        never matches.
 
     .OUTPUTS
         One of the strings 'success', 'failure', or 'pending'.
@@ -124,12 +157,27 @@ begin {
         param(
             [Parameter(Mandatory = $false)]
             [AllowNull()]
-            [object[]]$Checks
+            [object[]]$Checks,
+
+            [Parameter(Mandatory = $false)]
+            [string]$RequireWorkflow = ''
         )
 
-        # Empty or null required-check set is vacuously satisfied: there is no check
-        # that can fail or be in progress, so the gate concludes 'success'.
+        # A non-empty, whitespace-only workflow name is invalid input. Reject it
+        # rather than silently disabling the guard and restoring vacuous success.
+        if ($RequireWorkflow.Length -gt 0 -and [string]::IsNullOrWhiteSpace($RequireWorkflow)) {
+            throw "Invoke-CiGateParser: -RequireWorkflow must be '' or a workflow name; a whitespace-only value is not accepted."
+        }
+
+        $requireWorkflowGuard = $RequireWorkflow.Length -gt 0
+
+        # Empty or null check set. Without the guard it is vacuously satisfied (no
+        # check can fail or be in progress); with the guard no passing check from
+        # the named workflow was observed, so the gate stays 'pending'.
         if ($null -eq $Checks -or $Checks.Count -eq 0) {
+            if ($requireWorkflowGuard) {
+                return 'pending'
+            }
             return 'success'
         }
 
@@ -137,7 +185,10 @@ begin {
         # decision until after confirming nothing failed (failure outranks pending).
         $anyPending = $false
 
-        # Inspect each required check once, classifying by its bucket value. Failure
+        # Track whether a passing check from the named workflow was observed.
+        $requiredWorkflowPassed = $false
+
+        # Inspect each check once, classifying by its bucket value. Failure
         # short-circuits immediately because it is the highest-precedence outcome.
         foreach ($check in $Checks) {
             # A check element must expose a bucket; absence is an undefined state and
@@ -152,10 +203,19 @@ begin {
             # change semantics because failure short-circuits via return; pending is
             # only recorded (not returned) so a later failure can still take priority.
             switch ($bucket) {
-                'fail' { return 'failure' }       # a failed required check is terminal-non-success
-                'cancel' { return 'failure' }       # a cancelled required check is treated conservatively as failure
+                'fail' { return 'failure' }       # a failed check is terminal-non-success
+                'cancel' { return 'failure' }       # a cancelled check is treated conservatively as failure
                 'pending' { $anyPending = $true }     # in-progress; defer until failures are ruled out
-                'pass' { }                        # passing check contributes to success; no state change
+                'pass' {
+                    # Under the guard, record a pass from the named workflow. The
+                    # property test keeps an element without `workflow` from
+                    # throwing under Set-StrictMode; such an element never matches.
+                    if ($requireWorkflowGuard -and
+                        ($check.PSObject.Properties.Name -contains 'workflow') -and
+                        ([string]$check.workflow -ceq $RequireWorkflow)) {
+                        $requiredWorkflowPassed = $true
+                    }
+                }
                 'skipping' { }                        # skipped check is non-blocking; neither failure nor pending
                 default {
                     # Unknown bucket: fail fast and name the value so the unsupported
@@ -171,6 +231,12 @@ begin {
             return 'pending'
         }
 
+        # With the guard, nothing failed or is pending, but success also requires
+        # at least one passing check from the named workflow.
+        if ($requireWorkflowGuard -and -not $requiredWorkflowPassed) {
+            return 'pending'
+        }
+
         return 'success'
     }
 
@@ -241,6 +307,8 @@ begin {
         See script-level parameter of the same name.
     .PARAMETER NowProvider
         See script-level parameter of the same name.
+    .PARAMETER RequireWorkflow
+        See script-level parameter of the same name.
     .PARAMETER AsJson
         See script-level parameter of the same name.
 
@@ -269,6 +337,9 @@ begin {
             [ValidateNotNull()]
             [ScriptBlock]$NowProvider = { (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') },
 
+            [Parameter(Mandatory = $false)]
+            [string]$RequireWorkflow = '',
+
             [Parameter(Mandatory = $false)]
             [switch]$AsJson
         )
@@ -288,7 +359,7 @@ begin {
         # downstream Count/foreach logic uniform for the empty, single, and many cases.
         $checks = @($parsed)
 
-        $conclusion = Get-CiGateConclusion -Checks $checks
+        $conclusion = Get-CiGateConclusion -Checks $checks -RequireWorkflow $RequireWorkflow
 
         # Resolve the timestamp through the injected delegate so tests can pin an
         # exact value; the default delegate reads UTC wall-clock time.
@@ -324,6 +395,7 @@ process {
             -PrPipelineRunId $PrPipelineRunId `
             -PrPipelineRunUrl $PrPipelineRunUrl `
             -NowProvider $NowProvider `
+            -RequireWorkflow $RequireWorkflow `
             -AsJson:$AsJson
     }
 }

package/resources/claude-customizations/.claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1

@@ -0,0 +1,203 @@
+<#
+.SYNOPSIS
+    Maps one pull-request snapshot to a merge-confirmation status (issue #952).
+
+.DESCRIPTION
+    Consumes the JSON emitted by
+    `gh pr view <n> --json state,mergeCommit,mergedAt,autoMergeRequest`, or a GraphQL
+    `pullRequest` node that may also carry `isInMergeQueue`, and reports whether the pull
+    request has merged. Merge procedures call this parser while they poll after a merge or
+    merge-queue enqueue, and record a merge only after it reports `merged`.
+
+    Mapping (state values are case-sensitive):
+      - MERGED with a non-empty mergeCommit.oid             -> merged
+      - MERGED with a null mergeCommit or an empty oid      -> error
+      - CLOSED                                              -> closed
+      - OPEN with isInMergeQueue true, or with a present
+        non-null autoMergeRequest                           -> pending
+      - OPEN otherwise                                      -> not_queued
+      - a null snapshot, a missing state, or any other
+        state value                                         -> error
+
+    Every error message starts with 'Invoke-MergeConfirmationParser: '.
+
+    This script does NOT invoke `gh`. The caller runs `gh` and passes the resulting JSON
+    through -PrJson or the pipeline, so the mapping is deterministically testable.
+
+.PARAMETER PrJson
+    The pull-request snapshot JSON. Accepts pipeline input. Defaults to '' so the file can be
+    dot-sourced with no arguments.
+
+.PARAMETER AsJson
+    When set, emits the result as compressed JSON instead of a PowerShell object.
+
+.EXAMPLE
+    pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1 -PrJson $snapshot -AsJson
+
+.OUTPUTS
+    A PSCustomObject (or a JSON string when -AsJson is set) with the properties Status
+    (merged, pending, not_queued, or closed), MergeCommitSha, and MergedAt. MergeCommitSha and
+    MergedAt are empty unless Status is merged.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(ValueFromPipeline = $true)]
+    [AllowEmptyString()]
+    [string]$PrJson = '',
+
+    [Parameter(Mandatory = $false)]
+    [switch]$AsJson
+)
+
+# Function definitions live in begin so the script is a single explicit begin/process unit;
+# the pipeline-bound -PrJson parameter forces a named process block.
+begin {
+    function Get-MergeConfirmationPropertyValue {
+        <#
+        .SYNOPSIS
+            Return a named property value of a parsed object, or $null when it is absent.
+        .DESCRIPTION
+            Reads through PSObject.Properties so an absent property is not an error under
+            Set-StrictMode -Version Latest.
+        #>
+        [CmdletBinding()]
+        param(
+            [AllowNull()]
+            $InputObject,
+
+            [Parameter(Mandatory = $true)]
+            [string]$Name
+        )
+
+        if ($null -eq $InputObject) {
+            return $null
+        }
+        $property = $InputObject.PSObject.Properties[$Name]
+        if ($null -eq $property) {
+            return $null
+        }
+        return $property.Value
+    }
+
+    function ConvertTo-MergeConfirmationTimeText {
+        <#
+        .SYNOPSIS
+            Render a mergedAt value as text: strings verbatim, dates as UTC ISO-8601.
+        #>
+        [CmdletBinding()]
+        [OutputType([string])]
+        param(
+            [AllowNull()]
+            $Value
+        )
+
+        $format = 'yyyy-MM-ddTHH:mm:ssZ'
+        $culture = [System.Globalization.CultureInfo]::InvariantCulture
+        if ($null -eq $Value) {
+            return ''
+        }
+        if ($Value -is [datetimeoffset]) {
+            return $Value.UtcDateTime.ToString($format, $culture)
+        }
+        if ($Value -is [datetime]) {
+            # A Kind of Unspecified carries no offset; JSON timestamps from gh are UTC.
+            $utc = if ($Value.Kind -eq [System.DateTimeKind]::Unspecified) { [datetime]::SpecifyKind($Value, [System.DateTimeKind]::Utc) } else { $Value.ToUniversalTime() }
+            return $utc.ToString($format, $culture)
+        }
+        return [string]$Value
+    }
+
+    function Get-MergeConfirmationStatus {
+        <#
+        .SYNOPSIS
+            Map one parsed pull-request snapshot to the merge-confirmation result object.
+        .PARAMETER Snapshot
+            The parsed snapshot (gh pr view JSON or a GraphQL pullRequest node).
+        .OUTPUTS
+            PSCustomObject with Status, MergeCommitSha, and MergedAt.
+        #>
+        [CmdletBinding()]
+        [OutputType([pscustomobject])]
+        param(
+            [AllowNull()]
+            $Snapshot
+        )
+
+        if ($null -eq $Snapshot) {
+            throw 'Invoke-MergeConfirmationParser: the pull-request snapshot is null or empty.'
+        }
+        $state = Get-MergeConfirmationPropertyValue -InputObject $Snapshot -Name 'state'
+        if ($null -eq $state) {
+            throw 'Invoke-MergeConfirmationParser: the pull-request snapshot has no state field.'
+        }
+        $stateText = [string]$state
+
+        if ($stateText -ceq 'MERGED') {
+            $mergeCommit = Get-MergeConfirmationPropertyValue -InputObject $Snapshot -Name 'mergeCommit'
+            $oid = [string](Get-MergeConfirmationPropertyValue -InputObject $mergeCommit -Name 'oid')
+            if ([string]::IsNullOrWhiteSpace($oid)) {
+                throw 'Invoke-MergeConfirmationParser: state MERGED carries no merge commit oid.'
+            }
+            $mergedAt = ConvertTo-MergeConfirmationTimeText -Value (Get-MergeConfirmationPropertyValue -InputObject $Snapshot -Name 'mergedAt')
+            return [pscustomobject]@{ Status = 'merged'; MergeCommitSha = $oid; MergedAt = $mergedAt }
+        }
+        if ($stateText -ceq 'CLOSED') {
+            return [pscustomobject]@{ Status = 'closed'; MergeCommitSha = ''; MergedAt = '' }
+        }
+        if ($stateText -ceq 'OPEN') {
+            $inQueue = Get-MergeConfirmationPropertyValue -InputObject $Snapshot -Name 'isInMergeQueue'
+            $autoMerge = Get-MergeConfirmationPropertyValue -InputObject $Snapshot -Name 'autoMergeRequest'
+            $queued = ($inQueue -is [bool] -and $inQueue) -or ($null -ne $autoMerge)
+            $status = if ($queued) { 'pending' } else { 'not_queued' }
+            return [pscustomobject]@{ Status = $status; MergeCommitSha = ''; MergedAt = '' }
+        }
+
+        throw ("Invoke-MergeConfirmationParser: unrecognized pull-request state '{0}'." -f $stateText)
+    }
+
+    function Invoke-MergeConfirmationParser {
+        <#
+        .SYNOPSIS
+            Parse a pull-request snapshot JSON string and map it to a merge-confirmation status.
+        .PARAMETER PrJson
+            The snapshot JSON text.
+        .PARAMETER AsJson
+            Emit compressed JSON instead of the result object.
+        .OUTPUTS
+            PSCustomObject, or System.String when -AsJson is set.
+        #>
+        [CmdletBinding()]
+        param(
+            [AllowEmptyString()]
+            [AllowNull()]
+            [string]$PrJson,
+
+            [switch]$AsJson
+        )
+
+        $snapshot = $null
+        if (-not [string]::IsNullOrWhiteSpace($PrJson)) {
+            try {
+                $snapshot = $PrJson | ConvertFrom-Json -ErrorAction Stop
+            }
+            catch {
+                throw ('Invoke-MergeConfirmationParser: the pull-request snapshot is not valid JSON: ' + $_.Exception.Message)
+            }
+        }
+
+        $result = Get-MergeConfirmationStatus -Snapshot $snapshot
+        if ($AsJson) {
+            return ($result | ConvertTo-Json -Depth 3 -Compress)
+        }
+        return $result
+    }
+}
+
+# Entry point. The parser runs only when the file is executed directly; when dot-sourced,
+# $MyInvocation.InvocationName is '.', so the guard leaves only the function definitions.
+process {
+    if ($MyInvocation.InvocationName -ne '.') {
+        Invoke-MergeConfirmationParser -PrJson $PrJson -AsJson:$AsJson
+    }
+}