@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",
@@ -38,11 +38,12 @@
     "prepack": "node prepack.cjs"
   },
   "overrides": {
-    "fast-uri": "^3.1.4",
+    "fast-uri": "^3.1.8",
     "hono": "^4.12.27",
     "ip-address": "^10.7.2",
     "qs": "^6.15.2",
-    "@hono/node-server": "^2.0.5"
+    "@hono/node-server": "^2.0.5",
+    "brace-expansion": "^5.0.12"
   },
   "devDependencies": {
     "esbuild": "^0.28.0"

package/resources/claude-customizations/.claude/agents/feature-review.md

@@ -9,6 +9,7 @@ tools:
   - "Bash(git diff *)"
   - "Bash(git log *)"
   - "Write(/docs/features/active/**)"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
 skills:
   - policy-compliance-order
   - acceptance-criteria-tracking
@@ -32,7 +33,12 @@ When the active review scope is a selected version folder such as `docs/features
 1. `docs/features/active/<feature-or-selected-version>/policy-audit.<timestamp>.md` — policy compliance audit with PASS/PARTIAL/FAIL verdicts and evidence
 2. `docs/features/active/<feature-or-selected-version>/code-review.<timestamp>.md` — code quality review covering best practices
 3. `docs/features/active/<feature-or-selected-version>/feature-audit.<timestamp>.md` — acceptance criteria verification relative to baseline
-4. If remediation is needed: `docs/features/active/<feature-or-selected-version>/remediation-inputs.<timestamp>.md` with explicit remediation-required findings and artifact paths
+4. For every review with at least one blocking finding, including halt (`HALT_NON_REMEDIABLE`) and wait (`AWAITING_CI`) verdicts: `docs/features/active/<feature-or-selected-version>/remediation-inputs.<timestamp>.md` with explicit remediation-required findings and artifact paths. The file carries these line formats:
+   - one line `Review-Verdict: <VERDICT>`, where the verdict is `PASS`, `REMEDIATION_REQUIRED`, `HALT_NON_REMEDIABLE`, or `AWAITING_CI`,
+   - inside each blocking finding block, one line `Remediability: <class>`, where the class is `autonomous`, `external_dependency`, `policy_hold`, `awaiting_ci`, or `human_decision_required` (`autonomous` when the line is absent),
+   - inside each blocking finding block, one line `Remediability-Evidence: <text>` stating why the class applies.
+
+   These lines, including the evidence text, never contain the substrings the orchestrator counts when it counts blocking findings, so their presence does not change the blocking count. The verdict follows from the classes: no blocking finding is `PASS`; any `autonomous` finding is `REMEDIATION_REQUIRED`; otherwise any `external_dependency`, `policy_hold`, or `human_decision_required` finding is `HALT_NON_REMEDIABLE`; otherwise `AWAITING_CI`.
 
 Timestamp format: `yyyy-MM-ddTHH-mm` (ISO-8601).
 
@@ -44,6 +50,9 @@ Report the required artifact paths in the final response using these tokens:
 - `code-review-path: docs/features/active/<feature-or-selected-version>/code-review.<timestamp>.md`
 - `feature-audit-path: docs/features/active/<feature-or-selected-version>/feature-audit.<timestamp>.md`
 - When remediation inputs are produced: `remediation-inputs-path: docs/features/active/<feature-or-selected-version>/remediation-inputs.<timestamp>.md`
+- Optional: `review-status: <VERDICT>` with the same verdict as the remediation inputs (`PASS` when none were produced). The orchestrator treats the remediation inputs as authoritative and this token as a cross-check.
+
+Validate each review artifact immediately after writing it with `mcp__drm-copilot__validate_orchestration_artifacts`, passing `artifact_path` set to that artifact: use `artifact_type: "policy-audit"` for `policy-audit.<timestamp>.md`, `artifact_type: "code-review"` for `code-review.<timestamp>.md`, and `artifact_type: "feature-audit"` for `feature-audit.<timestamp>.md`. When the validator reports a failure, fix the artifact in the same review and validate it again. Report an artifact path only after its validation passes.
 
 ## Context Sources
 

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

@@ -96,7 +96,9 @@ PR creation and PR body edits must be delegated to `Agent(pr-author)`. The orche
 
 When the orchestrator runs the remediation loop, it records a top-level `remediation_loop` object in `artifacts/orchestration/orchestrator-state.json`:
 
-- `current_cycle` — integer index of the active cycle.
+- `current_cycle` — integer index of the active cycle's record in `cycles[]`; a record position, not an attempt count.
+- `completed_attempts` — non-negative integer equal to the number of cycles whose `candidate_applied` is `true`. This is the shared attempt count for local, CI-failure, merge-conflict, and parallel-drift cycles; the guard halts after three completed attempts.
+- `review_outcomes[]` — one entry per review, including `PASS`, appended in order. Each entry is an object with `verdict` (one of `PASS`, `REMEDIATION_REQUIRED`, `HALT_NON_REMEDIABLE`, `AWAITING_CI`) and `findings[]`, the review's blocking findings only, each an object with `remediability` (one of `autonomous`, `external_dependency`, `policy_hold`, `awaiting_ci`, `human_decision_required`). An optional `inputs_path` names the `remediation-inputs` file.
 - `cycles[]` — an ordered array of cycle records. Each cycle is an object with:
   - `entry_timestamp` — ISO-8601 timestamp when the cycle was entered.
   - `inputs_path` — path to the `remediation-inputs.<entry-ts>.md` that opened the cycle.
@@ -106,14 +108,25 @@ When the orchestrator runs the remediation loop, it records a top-level `remedia
   - `audit_paths` — the reaudit artifact paths produced at cycle exit (`code-review`, `feature-audit`, `policy-audit`).
   - `blocking_count` — the total number of blocking findings across the reaudit artifacts.
   - `exit_condition_met` — boolean; `true` only when the cycle's exit gate is satisfied.
+  - `candidate_applied` — boolean; `true` only for a completed attempt (execution `complete` and a non-empty pre-reaudit commit). A cycle without a candidate records `false` and consumes no attempt number.
+  - `opened_by_review` — zero-based index of the `review_outcomes[]` entry that opened the cycle.
+
+These four fields are recorded by producers. Verdicts follow from the classes of a review's blocking findings: none is `PASS`; any `autonomous` is `REMEDIATION_REQUIRED`; otherwise any `external_dependency`, `policy_hold`, or `human_decision_required` is `HALT_NON_REMEDIABLE`; otherwise `AWAITING_CI`. A `HALT_NON_REMEDIABLE` or `AWAITING_CI` review opens no cycle.
 
 Malformed-cycle rules:
 
 - `plan_path` must be a non-empty string.
 - `execution_status` may be in `{in_progress, complete, failed}` only when `preflight.final_status == 'clear'`; any other preflight status with one of those execution statuses is malformed (execution recorded before preflight cleared).
 - `exit_condition_met == true` requires `blocking_count == 0`; a non-zero `blocking_count` with `exit_condition_met == true` is malformed.
+- R5: `candidate_applied`, when present, must be a boolean.
+- R6: `candidate_applied == true` requires `execution_status == "complete"`.
+- R7: `completed_attempts`, when present, must be a non-negative integer equal to the number of object cycles whose `candidate_applied` is `true`.
+- R8: `review_outcomes`, when present, must be a list, and each entry must be an object.
+- R9: each outcome's `verdict` must be one of the four verdicts, its `findings` must be a list, and each finding must be an object whose `remediability` is one of the five classes (case-sensitive).
+- R10: each well-formed outcome's `verdict` must equal the verdict derived from its findings' classes.
+- R11: `opened_by_review`, when present, must be a non-negative integer that indexes an object entry of `review_outcomes` whose `verdict` is `REMEDIATION_REQUIRED`.
 
-Cycle-aware `next_step` uses the form `remediation.cycle_N.{plan,preflight,execute,reaudit,exit_check}`, where `N` is the cycle index and the sub-step names the current position in the loop.
+Cycle-aware `next_step` uses the form `remediation.cycle_N.{plan,preflight,execute,reaudit,exit_check}`, where `N` is `completed_attempts + 1` (the active cycle number) and the sub-step names the current position in the loop; `current_cycle` remains a record position in `cycles[]`.
 
 ### CI Monitoring and Post-PR Remediation
 
@@ -149,7 +162,7 @@ A new finding discovered during execution triggers a NEW cycle with a follow-up
 
 ### Exit Gate
 
-`blocking_count` is the total of FAIL and blocking-PARTIAL findings across the three reaudit artifacts (`code-review`, `feature-audit`, `policy-audit`). Only `blocking_count == 0` sets `exit_condition_met = true`. A non-zero `blocking_count` leaves the gate unmet and opens the next cycle.
+`blocking_count` is the total of FAIL and blocking-PARTIAL findings across the three reaudit artifacts (`code-review`, `feature-audit`, `policy-audit`). Only `blocking_count == 0` sets `exit_condition_met = true`. The exit gate counts only `autonomous` blocking findings when deciding whether to open the next cycle: a non-zero count of `autonomous` blocking findings leaves the gate unmet and opens the next cycle, while remaining blocking findings that are all non-remediable halt (`HALT_NON_REMEDIABLE`) or wait (`AWAITING_CI`) instead of opening a cycle.
 
 ### Citations
 

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

@@ -18,7 +18,9 @@ tools:
   - "Bash(bash .claude/lib/bash/compute-cohorts.sh*)"
   - "Bash(bash .claude/lib/bash/compute-concurrency-batches.sh*)"
   - "Bash(bash .claude/lib/bash/validate-parallel-manifest.sh*)"
+  - "Bash(bash .claude/lib/bash/abandon-parallel-item.sh*)"
   - "Bash(pwsh -NoProfile -File .claude/lib/project-file-merge/Resolve-MergeableConflict.ps1*)"
+  - "Bash(pwsh -NoProfile -NonInteractive -File .claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1*)"
   - "Bash(dotnet tool restore*)"
   - "Bash(dotnet csharpier check *)"
   - "Bash(dotnet build *)"
@@ -94,12 +96,16 @@ batching use `compute-cohorts.sh` and `compute-concurrency-batches.sh` under the
 entry.
 
 The `poetry run` grants remain for the repository-local paths that still need an interpreter. The
-skill's `## Parallel-Level Checkpoint` section now validates through
-`mcp__drm-copilot__validate_orchestration_artifacts`, so exactly one named consumer is left: the
-drift-detection CLI, invoked as `poetry run python -m`. Each grant stays scoped to its own
-`poetry run python` invocation form — not to `poetry run` as a whole — so `pytest`, `black`,
-`ruff`, and every other `poetry run` subcommand remain outside the allowlist. The sibling persona
-`.claude/agents/parallel-planner.md` records the same destination-runtime posture.
+skill's `## Parallel-Level Checkpoint` section validates through
+`mcp__drm-copilot__validate_orchestration_artifacts`, and since issue #763 radius drift detection runs
+through the destination-runtime PowerShell entry point
+`.claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1` and the abandon disposition through the
+bundled entry point `.claude/lib/bash/abandon-parallel-item.sh`, so no skill step names a
+`poetry run` consumer. The two `poetry run python` grants are left unchanged pending a separate
+removal decision. Each grant stays scoped to its own `poetry run python` invocation form — not to
+`poetry run` as a whole — so `pytest`, `black`, `ruff`, and every other `poetry run` subcommand
+remain outside the allowlist. The sibling persona `.claude/agents/parallel-planner.md` records the
+same destination-runtime posture.
 
 ## Startup Protocol
 
@@ -269,6 +275,12 @@ In `closed` mode, do not report completion until:
    `artifact_type: "parallel-orchestrator-state"`).
 4. Acceptance criteria in the AC source files of each item have been checked off by that item's own
    run, per the `acceptance-criteria-tracking` skill.
+   A CI-dependent criterion, whose verification requires the result of CI on the pull-request head,
+   is checked off and pushed by the item's own run after its S9 success and before its DONE, and
+   that run re-runs S9 so its reported `ci_gate.head_sha` is the final head. Before `gh pr merge`,
+   confirm that the `headRefOid` value equals that reported `ci_gate.head_sha` and that the item
+   reported no pending CI-dependent criteria. You never commit acceptance-criteria check-offs from
+   the coordinator root.
 
 In `open` mode there is no automatic completion. The run is a standing queue and terminates only
 via `/parallel-close`, which is owned by F6 and is not specified here or shipped by this feature. Do

package/resources/claude-customizations/.claude/agents/python-typed-engineer.md

@@ -1,7 +1,7 @@
 ---
 name: python-typed-engineer
 model: sonnet
-description: Project-scoped worker that implements and verifies Python changes within typed repository boundaries. Applies the Black -> Ruff -> Pyright -> Pytest toolchain, the 3-production + 3-test per-batch budget, and zero-regression quality gates.
+description: Project-scoped worker that implements and verifies Python changes within typed repository boundaries. Applies the Black -> Ruff -> Pyright -> Pytest toolchain, the 1-3 production-file direct-mode budget with routing to the orchestrated large path above it, and zero-regression quality gates.
 tools:
   - Read
   - Write
@@ -37,7 +37,7 @@ Language standards and toolchain are defined in `.claude/rules/python.md` and `.
 Follow the phased workflow defined by the preloaded skills:
 
 1. **Policy compliance** — apply `policy-compliance-order` to load mandatory repo policies before any change.
-2. **Routing and scope** — apply `python-change-budget-router` to estimate scope, select small vs large path, and enforce the 3 production + 3 test per-batch cap.
+2. **Routing and scope** — apply `python-change-budget-router` to estimate scope and select direct mode (1-3 production files) or, for more than 3 production files, large-path escalation through `/orchestrate`. The large path has no production-file cap, and test files are not counted toward the routing threshold.
 3. **Plan and baseline** — apply `atomic-plan-contract` for Phase 0 baseline capture and atomic plan structure. Delegate plan authoring to `atomic_planner` when no plan is supplied.
 4. **Implement in batches** — apply the approved plan. After each batch, run targeted Ruff and Pyright on touched files plus targeted Pytest, and confirm per-file coverage.
 5. **Final QA gate** — apply `python-qa-gate` to run the full toolchain, enforce zero-regression deltas against the baseline, and produce the required reporting block before declaring completion.
@@ -58,7 +58,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 
 Stop implementation and return to the user when:
 
-- the scope estimate or an in-flight batch would exceed the 3-production-file cap,
+- the scope estimate exceeds 3 production files in direct mode,
 - a file is near or would exceed the 500-line limit,
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),

package/resources/claude-customizations/.claude/hooks/{enforce-powershell-batch-budget-route.ps1 → enforce-batch-budget-route.ps1}

@@ -1,19 +1,21 @@
 <#
 .SYNOPSIS
-    Pure route helpers for the PowerShell batch-budget hook.
+    Pure route helpers shared by the batch-budget hooks.
 
 .DESCRIPTION
     Defines the functions that read the selected route from orchestrator checkpoint
     text and decide whether that checkpoint selects the uncapped orchestrated large
-    path. The file is dot-sourced by enforce-powershell-batch-budget.ps1 and has no
-    entry point. None of the functions reads a file or an environment variable; the
-    checkpoint text is supplied by the caller.
+    path. The file is dot-sourced by the PowerShell and Python batch-budget hooks and
+    has no entry point. The Claude and Codex runtime copies of this file are
+    byte-identical, and a parity test holds them identical. None of the functions
+    reads a file or an environment variable; the checkpoint text is supplied by the
+    caller.
 
 .NOTES
     Compatible with PowerShell 7+.
 #>
 
-function ConvertFrom-PowerShellBatchBudgetCheckpoint {
+function ConvertFrom-BatchBudgetCheckpoint {
     <#
     .SYNOPSIS
         Parses orchestrator checkpoint text into a checkpoint object.
@@ -50,7 +52,7 @@ function ConvertFrom-PowerShellBatchBudgetCheckpoint {
     return $null
 }
 
-function Get-PowerShellBatchBudgetSelectedRoute {
+function Get-BatchBudgetSelectedRoute {
     <#
     .SYNOPSIS
         Returns the route selected by an orchestrator checkpoint.
@@ -69,7 +71,7 @@ function Get-PowerShellBatchBudgetSelectedRoute {
         [string] $CheckpointText
     )
 
-    $checkpoint = ConvertFrom-PowerShellBatchBudgetCheckpoint -CheckpointText $CheckpointText
+    $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
     if ($null -eq $checkpoint) {
         return ''
     }
@@ -89,7 +91,7 @@ function Get-PowerShellBatchBudgetSelectedRoute {
     return ''
 }
 
-function Test-PowerShellBatchBudgetLargePathRoute {
+function Test-BatchBudgetLargePathRoute {
     <#
     .SYNOPSIS
         Reports whether an orchestrator checkpoint selects the uncapped large path.
@@ -110,12 +112,12 @@ function Test-PowerShellBatchBudgetLargePathRoute {
     )
 
     try {
-        $checkpoint = ConvertFrom-PowerShellBatchBudgetCheckpoint -CheckpointText $CheckpointText
+        $checkpoint = ConvertFrom-BatchBudgetCheckpoint -CheckpointText $CheckpointText
         if ($null -eq $checkpoint) {
             return $false
         }
 
-        $route = Get-PowerShellBatchBudgetSelectedRoute -CheckpointText $CheckpointText
+        $route = Get-BatchBudgetSelectedRoute -CheckpointText $CheckpointText
         if (-not (@('large', 'remediation', 'preparation') -ccontains $route)) {
             return $false
         }

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

@@ -0,0 +1,221 @@
+<#
+.SYNOPSIS
+    Checkpoint read seams and run-target resolution for the epic merge gate (issue #690).
+
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1 immediately after the authorization sibling.
+    Holds:
+
+    - The import guard for WorktreeRunResolution.psm1. A failed import is recorded in
+      $script:EpicMergeGateResolutionImportFailure, and
+      Get-EpicMergeGateImportFailureDecision turns it into a deny, so a missing module
+      cannot make the gate exit non-zero and fail open.
+    - The three checkpoint read seams, relocated from the gate file with their names kept.
+      Each takes a mandatory absolute path composed beneath a resolved worktree root.
+    - The session worktree root, used for the child branch and for a bare command.
+    - The resolution seam Resolve-EpicMergeGateRunTarget, which locates the epic or
+      parallel checkpoint that records the command's pull request number.
+    - Test-ChildCheckpointPrGateBinding, which binds the command's pull request number to
+      the per-feature checkpoint's pr_gate.pr_number when that field is recorded.
+    - Get-EpicMergeGateUnresolvedReason, the reason prefix used when neither run branch
+      resolves.
+
+.NOTES
+    PowerShell 7+. Depends on Get-EpicMergeGateBlockDecision from the authorization
+    sibling, dot-sourced by the gate before this file. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+#>
+
+# Import guard (issue #690): a failed import denies instead of failing open.
+$script:EpicMergeGateResolutionImportFailure = $null
+try {
+    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
+}
+catch {
+    $script:EpicMergeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
+}
+
+function Get-EpicMergeGateImportFailureDecision {
+    <#
+    .SYNOPSIS
+        Returns the deny for a failed worktree-resolution import, or $null.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary, or $null when the import succeeded.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    if (-not $script:EpicMergeGateResolutionImportFailure) {
+        return $null
+    }
+    return Get-EpicMergeGateBlockDecision -Reason (
+        "EPIC_MERGE_GATE_BLOCKED: the worktree-resolution module '$($script:EpicMergeGateResolutionImportFailure)' " +
+        'failed to import, so the run checkpoint that governs this merge cannot be located; the gate fails closed.')
+}
+
+function Get-ChildOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the session worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-EpicOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the epic checkpoint. Tests mock this function
+        (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the resolved worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-ParallelOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .PARAMETER Path
+        The absolute checkpoint path composed beneath the resolved worktree root.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $Path -Raw)
+}
+
+function Get-EpicMergeGateSessionWorktreeRoot {
+    <#
+    .SYNOPSIS
+        Return the worktree root the session runs in (the child branch and bare-command root).
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return (Resolve-WorktreeOperandTarget -Path '' -SessionRoot (Get-Location).Path).WorktreeRoot
+}
+
+function Resolve-EpicMergeGateRunTarget {
+    <#
+    .SYNOPSIS
+        Resolve the worktree whose run checkpoint records a pull request number (issue #690 seam).
+    .PARAMETER Kind
+        epic or parallel.
+    .PARAMETER PrNumber
+        The explicit pull request number the command names.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][ValidateSet('epic', 'parallel')][string] $Kind,
+        [Parameter(Mandatory)][int] $PrNumber
+    )
+
+    return Resolve-WorktreeRunTargetByRecord -Kind $Kind -RecordField pr_number -Value ([string]$PrNumber) -SessionRoot (Get-Location).Path
+}
+
+function Test-ChildCheckpointPrGateBinding {
+    <#
+    .SYNOPSIS
+        True unless the per-feature checkpoint records a pr_gate.pr_number that differs from the command's.
+    .DESCRIPTION
+        A bare command, an absent checkpoint, and a checkpoint without pr_gate.pr_number
+        keep today's unbound child-branch decision. When both numbers are present they must
+        parse as integers and be equal.
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint, or $null.
+    .PARAMETER CommandPrNumber
+        The explicit pull request number the command names, or $null.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()][Nullable[int]] $CommandPrNumber
+    )
+
+    if ($null -eq $CommandPrNumber -or $null -eq $Checkpoint) {
+        return $true
+    }
+    if (@($Checkpoint.PSObject.Properties.Name) -notcontains 'pr_gate' -or $null -eq $Checkpoint.pr_gate) {
+        return $true
+    }
+    $prGate = $Checkpoint.pr_gate
+    if (@($prGate.PSObject.Properties.Name) -notcontains 'pr_number' -or $null -eq $prGate.pr_number) {
+        return $true
+    }
+    $recorded = 0
+    if (-not [int]::TryParse([string]$prGate.pr_number, [ref] $recorded)) {
+        return $false
+    }
+    return ($recorded -eq $CommandPrNumber)
+}
+
+function Get-EpicMergeGateUnresolvedReason {
+    <#
+    .SYNOPSIS
+        Returns '<code>: <epic detail>; <parallel detail>' when neither run branch resolved, or $null.
+    .DESCRIPTION
+        The ambiguity code wins when either target is Ambiguous. Returns $null when either
+        target is absent (a bare command) or either target resolved.
+    .PARAMETER EpicTarget
+        The epic run target, or $null.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget
+    )
+
+    if ($null -eq $EpicTarget -or $null -eq $ParallelTarget) {
+        return $null
+    }
+    $unresolved = @('NoTarget', 'Ambiguous')
+    if ($unresolved -notcontains $EpicTarget.Status -or $unresolved -notcontains $ParallelTarget.Status) {
+        return $null
+    }
+    $code = if ($EpicTarget.Status -eq 'Ambiguous') { $EpicTarget.ReasonCode } elseif ($ParallelTarget.Status -eq 'Ambiguous') { $ParallelTarget.ReasonCode } else { $EpicTarget.ReasonCode }
+    return ('{0}: {1}; {2}' -f $code, $EpicTarget.Detail, $ParallelTarget.Detail)
+}

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

@@ -38,10 +38,16 @@
     policy-level-not-cryptographic posture already accepted for
     enforce-pr-author-skill.ps1's own receipt mechanism. It is not a cryptographic control.
 
+    Issue #690: with an explicit PR number, the epic and parallel checkpoints are read
+    beneath the live worktree whose run checkpoint records that number, and the child
+    branch binds the number to pr_gate.pr_number when the per-feature checkpoint records
+    it. A bare command reads every checkpoint beneath the session worktree.
+
 .NOTES
-    Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
-    through injectable wrapper functions so tests can mock the boundary without writing
-    temporary files.
+    Compatible with PowerShell 7+. Depends on WorktreeRunResolution.psm1 through the
+    dot-sourced enforce-epic-merge-gate-resolution.ps1, whose import guard denies on a
+    failed import. Filesystem reads go through injectable wrapper functions so tests can
+    mock the boundary without writing temporary files.
 
     Honest disclosure: the standalone-merge authorization record is a policy-level,
     auditable declaration and is not a cryptographic or security control. authorized_by is
@@ -59,64 +65,8 @@ Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 # Standalone-merge authorization predicates and the two decision-envelope factories (issue #670).
 . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-authorization.ps1')
-
-$script:ChildCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
-$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
-$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
-
-function Get-ChildOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the per-feature orchestrator checkpoint. Tests mock
-        this function (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:ChildCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:ChildCheckpointPath -Raw)
-}
-
-function Get-EpicOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the epic checkpoint. Tests mock this function
-        (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
-}
-
-function Get-ParallelOrchestratorCheckpointContent {
-    <#
-    .SYNOPSIS
-        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
-        this function (read seam).
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:ParallelCheckpointPath -PathType Leaf)) {
-        return $null
-    }
-    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
-}
+# Checkpoint read seams, the import guard, and run-target resolution (issue #690).
+. (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-resolution.ps1')
 
 function ConvertFrom-EpicMergeGateJson {
     <#
@@ -361,6 +311,12 @@ function Invoke-EpicMergeGateDecision {
         [string] $ToolInputRaw
     )
 
+    # A failed worktree-resolution import denies before any other logic (issue #690).
+    $importFailure = Get-EpicMergeGateImportFailureDecision
+    if ($null -ne $importFailure) {
+        return $importFailure
+    }
+
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
         return Get-EpicMergeGateBlockDecision -Reason (
@@ -399,18 +355,35 @@ function Invoke-EpicMergeGateDecision {
     }
 
     $commandPrNumber = Get-EpicMergeGateCommandPrNumber -CommandText $commandText
+    $sessionRoot = Get-EpicMergeGateSessionWorktreeRoot
 
-    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent)
-    if (Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) {
+    # The child merges from its own worktree, so its checkpoint is the session worktree's;
+    # a recorded pr_gate.pr_number must match an explicit command PR number (issue #690).
+    $childCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ChildOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind item -WorktreeRoot $sessionRoot))
+    if ((Test-ChildCheckpointAllowsEpicMerge -Checkpoint $childCheckpoint) -and
+        (Test-ChildCheckpointPrGateBinding -Checkpoint $childCheckpoint -CommandPrNumber $commandPrNumber)) {
         return Get-EpicMergeGateAllowDecision
     }
 
-    $epicCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-EpicOrchestratorCheckpointContent)
+    # A bare command targets the current branch's PR, so it reads the session worktree. An
+    # explicit PR number locates each run checkpoint that records it (issue #690).
+    $epicTarget = $null
+    $parallelTarget = $null
+    $epicRoot = $sessionRoot
+    $parallelRoot = $sessionRoot
+    if ($null -ne $commandPrNumber) {
+        $epicTarget = Resolve-EpicMergeGateRunTarget -Kind epic -PrNumber $commandPrNumber
+        $parallelTarget = Resolve-EpicMergeGateRunTarget -Kind parallel -PrNumber $commandPrNumber
+        $epicRoot = if (@('SessionRoot', 'OtherWorktree') -contains $epicTarget.Status) { $epicTarget.WorktreeRoot } else { $null }
+        $parallelRoot = if (@('SessionRoot', 'OtherWorktree') -contains $parallelTarget.Status) { $parallelTarget.WorktreeRoot } else { $null }
+    }
+
+    $epicCheckpoint = if ($epicRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-EpicOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind epic -WorktreeRoot $epicRoot)) } else { $null }
     if (Test-EpicCheckpointAllowsMerge -Checkpoint $epicCheckpoint -CommandPrNumber $commandPrNumber) {
         return Get-EpicMergeGateAllowDecision
     }
 
-    $parallelCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ParallelOrchestratorCheckpointContent)
+    $parallelCheckpoint = if ($parallelRoot) { ConvertFrom-EpicMergeGateJson -Raw (Get-ParallelOrchestratorCheckpointContent -Path (Get-WorktreeRunCheckpointPath -Kind parallel -WorktreeRoot $parallelRoot)) } else { $null }
     if (Test-ParallelCheckpointAllowsMerge -Checkpoint $parallelCheckpoint -CommandPrNumber $commandPrNumber) {
         return Get-EpicMergeGateAllowDecision
     }
@@ -423,7 +396,10 @@ function Invoke-EpicMergeGateDecision {
         if ($standalone.Allowed) {
             return Get-EpicMergeGateAllowDecision
         }
-        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $standalone.ReasonCode + ': ' + $standalone.Message)
+        # When neither run branch resolved, its reason code and detail precede the standalone reason.
+        $unresolved = Get-EpicMergeGateUnresolvedReason -EpicTarget $epicTarget -ParallelTarget $parallelTarget
+        $prefix = if ($unresolved) { $unresolved + '; ' } else { '' }
+        return Get-EpicMergeGateBlockDecision -Reason ('EPIC_MERGE_GATE_BLOCKED: ' + $prefix + $standalone.ReasonCode + ': ' + $standalone.Message)
     }
 
     return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number, or a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green". No checkpoint satisfied this gate.'