@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.11",
+  "version": "1.1.14",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",
@@ -40,7 +40,7 @@
   "overrides": {
     "fast-uri": "^3.1.4",
     "hono": "^4.12.27",
-    "ip-address": "^10.2.0",
+    "ip-address": "^10.7.2",
     "qs": "^6.15.2",
     "@hono/node-server": "^2.0.5"
   },

package/resources/claude-customizations/.claude/agents/epic-orchestrator.md

@@ -134,7 +134,7 @@ full schema enforced by `validate_epic_orchestrator_state_text`, implemented in
 `epic_feature_folder`,
 `epic_manifest_path`, `epic_status_doc_path`, `integration_branch`, `completed_steps`, `next_step`,
 `last_updated`, `current_wave`, `waves[]`, `features[]` (including `merge_status` and the four
-lifecycle timestamps), `epic_merge_pr`, and the three receipt arrays
+lifecycle timestamps), `epic_merge_pr`, `epic_issue_num`, `model_routing_receipts[]` (including the `pr-author` receipt recorded before the integration-to-`main` pull request, issue #663), and the three receipt arrays
 (`delegation_receipts[]`, `skill_receipts[]`, `mcp_call_receipts[]`) populated with the `epic`
 route's required names from `config/orchestration-routing.json`.
 

package/resources/claude-customizations/.claude/agents/epic-planner.md

@@ -9,11 +9,13 @@ tools:
   - Glob
   - "Write(docs/features/epics/**)"
   - "Edit(docs/features/epics/**)"
+  - "Write(docs/features/potential/**)"
   - "Write(artifacts/orchestration/**)"
   - "Edit(artifacts/orchestration/**)"
   - "Bash(git *)"
   - "Bash(gh *)"
   - "mcp__drm-copilot__validate_orchestration_artifacts"
+  - "mcp__drm-copilot__potential_to_issue"
 skills:
   - policy-compliance-order
   - epic-plan
@@ -102,10 +104,11 @@ the prepared epic, per the template in the `epic-plan` skill.
 ## Checkpoint Persistence
 
 Update `artifacts/orchestration/epic-planner-state.json` after every completed step with:
-`objective`, `epic_feature_folder`, `epic_manifest_path`, `integration_branch`,
+`objective`, `epic_feature_folder`, `epic_manifest_path`, `integration_branch`, `epic_issue_num`,
 `epic_worthiness` (`{verdict, rationale}`), `features[]` (per-feature `issue_num`,
 `feature_folder`, `depends_on`, `wave`, `complexity_band`, `preparation_status`, `plan_path`,
 `preflight_status`), `kickoff_prompt_path`, `completed_steps`, `next_step`, and `last_updated`.
+`epic_issue_num` is the epic-level issue `epic-planner` promotes at planning time through `mcp__drm-copilot__potential_to_issue` with `promotion_type: epic` (issue #663; see `## Epic-Level Issue Promotion` in the `epic-plan` skill).
 
 ## Completion Requirements
 

package/resources/claude-customizations/.claude/agents/parallel-planner.md

@@ -110,7 +110,8 @@ your own initiative; withdrawal is a caller decision made through F6's remove op
 Update `artifacts/orchestration/parallel-planner-state.json` after every completed step with:
 `objective`, `parallel_slug`, `parallel_manifest_path`, `mode`, `max_concurrency`,
 `plan_home_branch`, `items[]`, `cohorts[]`, `conflict_edges[]`, `recolor_generation`,
-`kickoff_prompt_path`, `completed_steps`, `next_step`, and `last_updated`.
+`kickoff_prompt_path`, `completed_steps`, `next_step`, and `last_updated`. Also record the
+`tolerated_overlaps` list returned by Get-BlastRadiusConflictEdge (tolerated-not-validated).
 
 Each `items[]` entry carries `issue_num`, `feature_folder`, `kind`, `state`, `complexity_band`,
 `preparation_status`, `research_path`, `plan_path`, `preflight_status`, `branch_name`,
@@ -163,6 +164,22 @@ The facade exports `Get-PlanPaths`, `Get-BlastRadius`, `Get-BlastRadiusFromObser
 `Test-BlastRadiusConflict` reads that table's optional `mergeable_paths` list and contributes no
 `path_overlap` edge for a path matching it, while the path stays in the declared radius.
 
+The facade also exports the scheduling entry point Get-BlastRadiusConflictEdge (with its per-pair
+helper `Get-BlastRadiusPairDecision`), the PowerShell port of `schedule_conflict_edges` in
+`scripts/dev_tools/_blast_radius_scheduling.py`. Build the conflict edges with one call,
+`Get-BlastRadiusConflictEdge -Item <records carrying key, radius, band> -Config <parsed truth table> -Relation ${function:Test-BlastRadiusConflict}`,
+rather than applying `Test-BlastRadiusConflict` to each pair by hand. The -Relation argument is
+required: the scheduling module does not resolve the relation itself, and an omitted relation fails
+fast. It applies the detection
+relation to every unordered pair and then the integration-cost edge rule of
+`.claude/rules/parallel-orchestration.md` under the table's configured `conflict_tolerance`, and
+returns `edges` and `tolerated_overlaps`. Record the edges in `conflict_edges[]` (each entry may
+carry the tolerated extra fields `hard`, `cost`, and `benefit`) and record every returned tolerated
+overlap in a `tolerated_overlaps` list on the planner checkpoint; tolerated overlaps are required
+checkpoint content, never discarded. A tolerated pair runs in the same or adjacent cohorts without a
+barrier, and the later-merging item merges `origin/main` and re-passes CI. The configured tolerance
+is the only sanctioned relaxation: never hand-narrow a radius to suppress an edge.
+
 **Cohort seeding and concurrency batching — bash entry points.** The bash library is granted as
 four entry-point-specific allowlist entries — `"Bash(bash .claude/lib/bash/compute-cohorts.sh*)"`,
 `"Bash(bash .claude/lib/bash/compute-concurrency-batches.sh*)"`,

package/resources/claude-customizations/.claude/agents/pr-author.md

@@ -92,3 +92,18 @@ deliberate, documented act to circumvent. It is not tamper-proof and is not a se
 Repository tone is defined in `CLAUDE.md` and `.claude/rules/tonality.md`. Reference only files
 listed under "Additional context files" in the PR-context bundle; do not cite or summarize files
 outside that enumeration. Do not invent issue or PR numbers.
+
+## Required `--head` on `gh pr create` (issue #687)
+
+Every `gh pr create` command this agent issues MUST carry an explicit
+`--head <branch>` naming the branch the pull request is opened from.
+
+This is what makes the call's target derivable. `enforce-pr-author-skill.ps1` resolves the
+worktree the call pertains to from the command text, and validates the orchestrator checkpoint
+belonging to that worktree. Without `--head`, `gh pr create` infers its head branch from the
+current checkout and the command carries no signal at all, so the gate denies with
+`TARGET_WORKTREE_NOT_DERIVABLE` rather than validating against whichever checkpoint occupies the
+session root, which in a parallel or epic topology belongs to a different item.
+
+Pass `--head` even when the branch is the current one: the gate resolves it to the session root
+and behaves exactly as before, and the command stays correct if it is ever replayed elsewhere.

package/resources/claude-customizations/.claude/hooks/enforce-completion-consistency.ps1

@@ -29,9 +29,13 @@
     completion is not asserted, the write is allowed via
     hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
-    Edit tool calls supply only old_string/new_string (a partial patch) and
-    cannot be reliably validated without the full target file content, so they
-    are allowed by this hook, matching enforce-checkpoint-monotonic.ps1. For
+    Edit tool calls supply only old_string/new_string (a partial patch). An Edit
+    call is validated by reading the checkpoint at the Edit's
+    targeted file_path through the injectable CheckpointReader seam and
+    applying the old_string -> new_string replacement in memory; the resulting
+    content is then evaluated like a Write. When the patch cannot be resolved
+    (the targeted file is missing or empty, the Edit has no old_string, or the
+    old_string is absent from the targeted content), the call is allowed. For
     Write calls whose content is not valid JSON, the hook allows the operation
     and defers to downstream tools to surface the error.
 
@@ -266,10 +270,11 @@ function Resolve-EditedCheckpointContent {
         when the patch cannot be applied against the on-disk checkpoint.
     .DESCRIPTION
         Implements the read-then-validate Edit path. When the tool input carries
-        an old_string (an Edit patch), the on-disk checkpoint is read through the
+        an old_string (an Edit patch), the checkpoint at the caller-supplied
+        CheckpointPath (the Edit's targeted file_path) is read through the
         injectable CheckpointReader seam and the old_string -> new_string
         replacement is applied in memory (no on-disk mutation). Returns $null
-        when there is no old_string, the on-disk file does not exist, or the
+        when there is no old_string, the targeted file does not exist or is empty, or the
         old_string is not present in the on-disk content, signalling the caller
         to allow (defer).
     #>
@@ -281,7 +286,10 @@ function Resolve-EditedCheckpointContent {
         $ToolInput,
 
         [Parameter(Mandatory)]
-        [scriptblock] $CheckpointReader
+        [scriptblock] $CheckpointReader,
+
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     $oldString = $null
@@ -297,7 +305,7 @@ function Resolve-EditedCheckpointContent {
         $newString = [string]$ToolInput.new_string
     }
 
-    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
+    $onDisk = & $CheckpointReader $CheckpointPath
     if ([string]::IsNullOrEmpty([string]$onDisk)) {
         # The on-disk checkpoint does not exist (or is empty); cannot patch.
         return $null
@@ -363,7 +371,7 @@ function Invoke-CompletionConsistencyDecision {
     # apply the old_string -> new_string patch in memory (read-then-validate).
     $content = Get-ClaudeHookToolInputString -ToolInput $toolInput -Name 'content'
     if (-not $content) {
-        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader -CheckpointPath $filePath
         if (-not $content) {
             # No content, and the Edit could not be resolved against on-disk
             # state (missing file or non-matching patch): defer and allow.

package/resources/claude-customizations/.claude/hooks/enforce-epic-merge-gate-authorization.ps1

@@ -0,0 +1,443 @@
+<#
+.SYNOPSIS
+    Dot-sourced standalone-merge authorization helpers for enforce-epic-merge-gate.ps1.
+
+.DESCRIPTION
+    Holds the fourth allow condition of the epic merge gate, the standalone-merge
+    authorization record, together with the two pure decision-envelope factories the gate
+    returns on every path.
+
+    This file is split out of the parent hook, .claude/hooks/enforce-epic-merge-gate.ps1,
+    because that file had 13 lines of headroom under the 500-line limit, which a fourth allow
+    condition, its predicates, and the rewritten header could not fit (issue #670). The two
+    envelope factories were moved here unchanged: they read no script-scoped state and no
+    test calls them by name, so the move is a pure relocation with no behaviour change.
+
+    Every function in this file is pure. It reads no file, starts no process, and reads no
+    clock; the parent hook supplies the already-parsed checkpoint objects and the live
+    envelope session_id. A test can therefore dot-source this file on its own.
+
+    Honest disclosure. The standalone-merge authorization record is a policy-level,
+    auditable declaration and is
+    not a cryptographic or security control.
+    It names a specific pull request, a specific session, an authorizer, a time, and a
+    stated basis, so that a standalone merge leaves a reviewable trail and cannot be reached
+    by accident or by a record written for a different pull request. authorized_by is a
+    declaration only: the hook checks that it is present and non-empty and does not verify
+    the identity it names, because the runtime exposes no attested agent identity at Bash
+    PreToolUse time. The record is not tamper-proof: any actor able to write
+    artifacts/orchestration/*.json inside the authorizing session can write a record,
+    because all agents share one filesystem and defaultPermissionMode is bypassPermissions.
+    The session_id cross-check binds a record to the session that emitted it, so a stale
+    record from a previous run or a record copied between runs authorizes nothing; it does
+    not stop same-session forgery. The mechanism converts an untraceable bypass into a
+    deliberate, attributable, auditable act. This is a documented accepted trade, not an
+    unexamined gap.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies.
+#>
+[CmdletBinding()]
+param()
+
+# Reason codes for the standalone-merge authorization branch. Each of the four assignments
+# below is the only place its code literal appears in this file; every other use reads the
+# variable, and the Codex hook's spelling is compared against these assignments by a test.
+$script:StandaloneAbsentReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_ABSENT'
+$script:StandalonePrMismatchReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_PR_MISMATCH'
+$script:StandaloneMalformedReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_MALFORMED'
+$script:StandaloneNotPrSpecificReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_NOT_PR_SPECIFIC'
+
+# The checkpoint key that carries the authorization records, and the pointer every
+# standalone deny message ends with.
+$script:StandaloneAuthorizationKey = 'standalone_merge_authorizations'
+$script:StandaloneAuthorizationGuidance = 'To authorize a standalone merge, write a standalone_merge_authorizations record naming this pull request and the current session_id into an orchestrator checkpoint, as described in the Standalone-Merge-Authorization section of .claude/rules/orchestrator-state.md.'
+
+function Get-EpicMergeGateAllowDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-EpicMergeGateBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Test-StandalonePositiveJsonInteger {
+    <#
+    .SYNOPSIS
+        Report whether a parsed JSON value is an integer strictly greater than zero.
+    .DESCRIPTION
+        ConvertFrom-Json yields a 32- or 64-bit integer for a JSON integer, a double for a
+        JSON number with a fraction, and a string for a quoted value. Only the two integer
+        types qualify, so a string that spells digits is rejected on its type.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Value
+    )
+
+    if (-not ($Value -is [int] -or $Value -is [long])) {
+        return $false
+    }
+    return ($Value -gt 0)
+}
+
+function Test-StandaloneJsonObject {
+    <#
+    .SYNOPSIS
+        Report whether a parsed JSON value is an object rather than a scalar or an array.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Value
+    )
+
+    return ($Value -is [System.Management.Automation.PSCustomObject])
+}
+
+function Get-StandaloneRecordField {
+    <#
+    .SYNOPSIS
+        Read a named field off a parsed record, returning $null when the field is absent.
+    .OUTPUTS
+        System.Object, System.Object[], or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([object], [object[]])]
+    param(
+        [Parameter(Mandatory)]
+        $Record,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    $property = $Record.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+    # The unary comma keeps a one-element array from unrolling into its scalar, so a
+    # pr_number spelled as [691] is still seen as an array and rejected.
+    return , $property.Value
+}
+
+function Get-StandaloneMergeAuthorizationRecord {
+    <#
+    .SYNOPSIS
+        Select the authorization record for one pull request from a parsed checkpoint.
+    .DESCRIPTION
+        Returns the first entry of the checkpoint's authorization array that is an object
+        whose pr_number is a positive JSON integer equal to PrNumber, or nothing when no
+        such entry exists. Reads no file, starts no process, and reads no clock.
+    .PARAMETER Checkpoint
+        Parsed checkpoint object, or $null when the checkpoint is absent or unreadable.
+    .PARAMETER PrNumber
+        The pull request number extracted from the command under evaluation.
+    .OUTPUTS
+        System.Object or nothing
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [Parameter(Mandatory)]
+        [int] $PrNumber
+    )
+
+    if (-not (Test-StandaloneJsonObject -Value $Checkpoint)) {
+        return
+    }
+    $property = $Checkpoint.PSObject.Properties[$script:StandaloneAuthorizationKey]
+    if ($null -eq $property -or $property.Value -isnot [System.Array]) {
+        return
+    }
+    foreach ($entry in $property.Value) {
+        if (-not (Test-StandaloneJsonObject -Value $entry)) {
+            continue
+        }
+        $entryNumber = Get-StandaloneRecordField -Record $entry -Name 'pr_number'
+        if ((Test-StandalonePositiveJsonInteger -Value $entryNumber) -and $entryNumber -eq $PrNumber) {
+            return $entry
+        }
+    }
+}
+
+function Test-StandaloneNonBlankString {
+    <#
+    .SYNOPSIS
+        Report whether a value is a string whose trimmed length reaches a minimum.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Value,
+
+        [int] $MinimumLength = 1
+    )
+
+    if ($Value -isnot [string]) {
+        return $false
+    }
+    return ($Value.Trim().Length -ge $MinimumLength)
+}
+
+function Test-StandaloneAuthorizedAt {
+    <#
+    .SYNOPSIS
+        Report whether an authorized_at value is a parseable date-time.
+    .DESCRIPTION
+        ConvertFrom-Json already converts an ISO 8601 string into a date-time value, so
+        such a value is accepted as parsed. Any other string must parse with the invariant
+        culture, assuming and adjusting to UTC. No clock is read.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Value
+    )
+
+    if ($Value -is [DateTime] -or $Value -is [DateTimeOffset]) {
+        return $true
+    }
+    if (-not (Test-StandaloneNonBlankString -Value $Value)) {
+        return $false
+    }
+    $parsed = [DateTime]::MinValue
+    return [DateTime]::TryParse(
+        $Value,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal,
+        [ref] $parsed)
+}
+
+function Get-StandaloneRecordFailure {
+    <#
+    .SYNOPSIS
+        Build the malformed-record result naming the failing field.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Field,
+
+        [Parameter(Mandatory)]
+        [string] $Rule
+    )
+
+    return [pscustomobject]@{
+        ReasonCode = $script:StandaloneMalformedReasonCode
+        Message    = "the matched authorization record has an invalid '$Field': $Rule"
+    }
+}
+
+function Test-StandaloneMergeAuthorizationRecord {
+    <#
+    .SYNOPSIS
+        Validate the fields of a selected authorization record.
+    .DESCRIPTION
+        Runs the field checks in the fixed order pr_url, issue_num, branch_name,
+        authorized_by, authorized_at, basis, run_slug, session_id. Returns nothing when
+        every check passes; otherwise returns the first failure as an object carrying
+        ReasonCode and a Message that names the failing field. branch_name is checked for
+        presence only and is never compared against the live branch or working directory.
+    .PARAMETER Record
+        The parsed record selected by pr_number.
+    .PARAMETER EnvelopeSessionId
+        The session_id read from the live PreToolUse envelope. A blank value fails closed.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject or nothing
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        $Record,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $EnvelopeSessionId
+    )
+
+    $prUrl = Get-StandaloneRecordField -Record $Record -Name 'pr_url'
+    $pullSuffix = '/pull/' + [string](Get-StandaloneRecordField -Record $Record -Name 'pr_number')
+    if (-not (Test-StandaloneNonBlankString -Value $prUrl) -or
+        -not $prUrl.EndsWith($pullSuffix, [System.StringComparison]::Ordinal)) {
+        return Get-StandaloneRecordFailure -Field 'pr_url' -Rule "it must end with $pullSuffix."
+    }
+    if (-not (Test-StandalonePositiveJsonInteger -Value (Get-StandaloneRecordField -Record $Record -Name 'issue_num'))) {
+        return Get-StandaloneRecordFailure -Field 'issue_num' -Rule 'it must be a JSON integer greater than zero.'
+    }
+    foreach ($name in @('branch_name', 'authorized_by')) {
+        if (-not (Test-StandaloneNonBlankString -Value (Get-StandaloneRecordField -Record $Record -Name $name))) {
+            return Get-StandaloneRecordFailure -Field $name -Rule 'it must be a non-empty string.'
+        }
+    }
+    if (-not (Test-StandaloneAuthorizedAt -Value (Get-StandaloneRecordField -Record $Record -Name 'authorized_at'))) {
+        return Get-StandaloneRecordFailure -Field 'authorized_at' -Rule 'it must be a parseable date-time string.'
+    }
+    if (-not (Test-StandaloneNonBlankString -Value (Get-StandaloneRecordField -Record $Record -Name 'basis') -MinimumLength 20)) {
+        return Get-StandaloneRecordFailure -Field 'basis' -Rule 'it must be at least 20 characters after trimming.'
+    }
+    if ($null -ne $Record.PSObject.Properties['run_slug'] -and
+        -not (Test-StandaloneNonBlankString -Value (Get-StandaloneRecordField -Record $Record -Name 'run_slug'))) {
+        return Get-StandaloneRecordFailure -Field 'run_slug' -Rule 'when present it must be a non-empty string.'
+    }
+    $recordSessionId = Get-StandaloneRecordField -Record $Record -Name 'session_id'
+    if (-not (Test-StandaloneNonBlankString -Value $recordSessionId) -or
+        [string]::IsNullOrWhiteSpace($EnvelopeSessionId) -or
+        -not [string]::Equals($recordSessionId, $EnvelopeSessionId, [System.StringComparison]::Ordinal)) {
+        return Get-StandaloneRecordFailure -Field 'session_id' -Rule 'it must be non-empty and equal the session_id of the live hook envelope.'
+    }
+}
+
+function Get-StandaloneAuthorizationBlockState {
+    <#
+    .SYNOPSIS
+        Classify one parsed checkpoint as Absent, NotPrSpecific, or PrSpecific.
+    .DESCRIPTION
+        Absent means the checkpoint is missing or carries no authorization key. The block
+        is PrSpecific only when it is a non-empty array whose every entry is an object with
+        a positive integer pr_number; any other shape, including a blanket boolean, is
+        NotPrSpecific, so a blanket flag is rejected visibly rather than read as absent.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        $Checkpoint
+    )
+
+    if (-not (Test-StandaloneJsonObject -Value $Checkpoint)) {
+        return 'Absent'
+    }
+    $property = $Checkpoint.PSObject.Properties[$script:StandaloneAuthorizationKey]
+    if ($null -eq $property) {
+        return 'Absent'
+    }
+    $block = $property.Value
+    if ($block -isnot [System.Array] -or $block.Count -eq 0) {
+        return 'NotPrSpecific'
+    }
+    foreach ($entry in $block) {
+        if (-not (Test-StandaloneJsonObject -Value $entry)) {
+            return 'NotPrSpecific'
+        }
+        if (-not (Test-StandalonePositiveJsonInteger -Value (Get-StandaloneRecordField -Record $entry -Name 'pr_number'))) {
+            return 'NotPrSpecific'
+        }
+    }
+    return 'PrSpecific'
+}
+
+function Test-StandaloneCheckpointAllowsMerge {
+    <#
+    .SYNOPSIS
+        Decision logic for the standalone-merge authorization path (branch 4).
+    .DESCRIPTION
+        Evaluates the three parsed orchestrator checkpoints for a record that authorizes
+        CommandPrNumber in the live session. Returns an object whose Allowed member is
+        $true on success; otherwise Allowed is $false and ReasonCode and Message describe
+        the denial:
+          - absent: no checkpoint carries the authorization key;
+          - not PR-specific: a checkpoint carries the key but names no specific pull request;
+          - PR mismatch: records exist, but none names CommandPrNumber;
+          - malformed: the matched record fails a field check, and the message names the field.
+    .PARAMETER Checkpoints
+        The three parsed checkpoint objects; any element may be $null.
+    .PARAMETER CommandPrNumber
+        The explicit pull request number extracted from the command.
+    .PARAMETER EnvelopeSessionId
+        The session_id read from the live PreToolUse envelope.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [object[]] $Checkpoints,
+
+        [Parameter(Mandatory)]
+        [int] $CommandPrNumber,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $EnvelopeSessionId
+    )
+
+    $states = @(foreach ($checkpoint in @($Checkpoints)) { Get-StandaloneAuthorizationBlockState -Checkpoint $checkpoint })
+    $reasonCode = $null
+    $message = $null
+    if ($states -contains 'NotPrSpecific') {
+        $reasonCode = $script:StandaloneNotPrSpecificReasonCode
+        $message = 'an orchestrator checkpoint carries the authorization key but names no specific pull request; a blanket flag is not an authorization record.'
+    } elseif ($states -notcontains 'PrSpecific') {
+        $reasonCode = $script:StandaloneAbsentReasonCode
+        $message = 'no orchestrator checkpoint carries an authorization record, but an authorized standalone merge path exists.'
+    } else {
+        foreach ($checkpoint in @($Checkpoints)) {
+            $record = Get-StandaloneMergeAuthorizationRecord -Checkpoint $checkpoint -PrNumber $CommandPrNumber
+            if ($null -eq $record) {
+                continue
+            }
+            $failure = Test-StandaloneMergeAuthorizationRecord -Record $record -EnvelopeSessionId $EnvelopeSessionId
+            if ($null -eq $failure) {
+                return [pscustomobject]@{ Allowed = $true; ReasonCode = $null; Message = $null }
+            }
+            $reasonCode = $failure.ReasonCode
+            $message = $failure.Message
+            break
+        }
+        if ($null -eq $reasonCode) {
+            $reasonCode = $script:StandalonePrMismatchReasonCode
+            $message = "authorization records exist, but none names pull request $CommandPrNumber."
+        }
+    }
+
+    return [pscustomobject]@{
+        Allowed    = $false
+        ReasonCode = $reasonCode
+        Message    = "$message $script:StandaloneAuthorizationGuidance"
+    }
+}