@danmoisan/drm-copilot-mcp 1.0.9 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill.ps1

@@ -46,46 +46,7 @@ param()
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
 $script:OrchestratorStateCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
-function Invoke-OrchestratorStatePreflight {
-    <#
-    .SYNOPSIS
-        Runs the orchestrator-state validator against the checkpoint and reports pass/fail.
-    .DESCRIPTION
-        Mirrors Invoke-RoutingContractValidation (.claude/hooks/validate-orchestrator-output.ps1):
-        an injectable subprocess scriptblock seam defaults to ``python -m
-        scripts.dev_tools.validate_orchestration_artifacts orchestrator-state <CheckpointPath>
-        --require-pr-creation-ready``. A missing checkpoint or --require-pr-creation-ready failure
-        both surface via the validator's non-zero exit/stderr text; no separate file-existence check
-        is made, validating pre-PR-creation readiness (steps 5-8, blocked_reason) not full completion.
-    .OUTPUTS
-        System.Collections.Hashtable with keys HasErrors (bool) and ErrorText (string).
-    #>
-    [CmdletBinding()]
-    [OutputType([hashtable])]
-    param(
-        [Parameter(Mandatory = $false)]
-        [string] $CheckpointPath = $script:OrchestratorStateCheckpointPath,
-
-        [Parameter(Mandatory = $false)]
-        [scriptblock] $Invoker = {
-            param($Path)
-            $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
-                orchestrator-state $Path --require-pr-creation-ready 2>&1
-            [pscustomobject]@{
-                ExitCode = $LASTEXITCODE
-                Output   = ($output | Out-String)
-            }
-        }
-    )
-
-    $result = & $Invoker $CheckpointPath
-    $exitCode = 0
-    if ($null -ne $result -and ($result.PSObject.Properties.Name -contains 'ExitCode')) { $exitCode = [int]$result.ExitCode }
-    $outputText = ''
-    if ($null -ne $result -and ($result.PSObject.Properties.Name -contains 'Output')) { $outputText = ([string]$result.Output).Trim() }
-
-    return @{ HasErrors = ($exitCode -ne 0); ErrorText = $outputText }
-}
+Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force
 
 function Get-PrContextArtifactExistence {
     <#
@@ -359,7 +320,7 @@ function Get-PrAuthorBypassReason {
     # Orchestrator-state preflight: runs inside this same PreToolUse hook (so it cannot be
     # bypassed by invoking gh pr create/edit directly) before receipt verification.
     if ($hasBodyFile -and $ContextExists) {
-        $preflightResult = Invoke-OrchestratorStatePreflight
+        $preflightResult = Invoke-OrchestratorStatePreflight -CheckpointPath $script:OrchestratorStateCheckpointPath
         if ($preflightResult.HasErrors) {
             $preflightSummary = if ([string]::IsNullOrWhiteSpace($preflightResult.ErrorText)) {
                 "checkpoint missing at $script:OrchestratorStateCheckpointPath"

package/resources/claude-customizations/.claude/hooks/validate-orchestrator-output.ps1

@@ -38,6 +38,8 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
+Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force
+
 function Get-CheckpointFileContent {
     <#
     .SYNOPSIS
@@ -179,11 +181,30 @@ function Invoke-RoutingContractValidation {
         [Parameter(Mandatory = $false)]
         [scriptblock] $Invoker = {
             param($Path, $Type)
-            $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
-                $Type $Path --require-complete --require-model-routing 2>&1
-            [pscustomobject]@{
-                ExitCode = $LASTEXITCODE
-                Output   = ($output | Out-String)
+            # Capability detection: use the authoritative Python CLI when
+            # scripts.dev_tools is importable (drm-copilot); otherwise fall back to
+            # the portable PowerShell completion module that travels with the
+            # pushed-down pack. The portable path performs the presence-level
+            # required-once-delegated existence gate and still fails closed.
+            if (Test-PythonOrchestratorValidatorAvailable) {
+                $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
+                    $Type $Path --require-complete --require-model-routing 2>&1
+                [pscustomobject]@{
+                    ExitCode = $LASTEXITCODE
+                    Output   = ($output | Out-String)
+                }
+            } else {
+                # Import the portable completion module only when its function is not
+                # already available, so a repeated call (or a test that pre-imports and
+                # mocks the function) does not reload the module and reset the seam.
+                if (-not (Get-Command -Name Test-OrchestratorStateCompletionReadiness -ErrorAction SilentlyContinue)) {
+                    Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateCompletion.psm1') -Force
+                }
+                $portable = Test-OrchestratorStateCompletionReadiness -CheckpointPath $Path
+                [pscustomobject]@{
+                    ExitCode = $portable.ExitCode
+                    Output   = $portable.Output
+                }
             }
         }
     )

package/resources/claude-customizations/.claude/lib/orchestrator-state/OrchestratorState.psm1

@@ -0,0 +1,485 @@
+<#
+.SYNOPSIS
+    Portable orchestrator-state checkpoint checks for pushed-down enforcement hooks.
+
+.DESCRIPTION
+    Provides a self-contained PowerShell implementation of the pushed-down-relevant
+    orchestrator-state checkpoint validations so the `.claude` enforcement hooks work
+    in consumer repositories that do not ship `scripts/dev_tools` (the authoritative
+    Python validator). This module mirrors the portable pattern of
+    `.claude/lib/model-routing/ModelRouting.psm1`.
+
+    It implements PR-creation-readiness parity with
+    `scripts/dev_tools/_orchestrator_state_pr_creation_readiness.py` and the base
+    checkpoint-presence checks (required keys, step-status validity, blocked_reason
+    validity) from `scripts/dev_tools/validate_orchestrator_state.py`. The base
+    constants below are pinned to `REQUIRED_STATE_KEYS`, `STEP_STATUS_KEYS`,
+    `VALID_STEP_STATUS`, and `VALID_BLOCKED_REASONS` in that validator.
+
+    Every public function FAILS CLOSED: a missing checkpoint file, invalid JSON, a
+    missing required key, an invalid step status, or an unmet readiness condition all
+    yield a non-zero ExitCode with a non-empty Output message. The Python validator
+    remains the authoritative reference; this module is the destination-runtime
+    mirror used only when the Python module is not importable.
+
+    This module also hosts the capability-detection probe
+    (Test-PythonOrchestratorValidatorAvailable), shared by both pushed-down hooks
+    (.claude/hooks/enforce-pr-author-skill.ps1 and
+    .claude/hooks/validate-orchestrator-output.ps1) so neither hook duplicates it
+    locally, and the PR-creation preflight orchestration helper
+    (Invoke-OrchestratorStatePreflight) consumed by enforce-pr-author-skill.ps1.
+#>
+
+Set-StrictMode -Version Latest
+
+# The canonical top-level checkpoint keys required by the primary validator.
+# Pinned to REQUIRED_STATE_KEYS in scripts/dev_tools/validate_orchestrator_state.py.
+$script:REQUIRED_STATE_KEYS = @(
+    'objective',
+    'change_budget_estimate',
+    'path_selected',
+    'promotion-type',
+    'short-name',
+    'relativeFile',
+    'long-name',
+    'issue-num',
+    'feature-folder',
+    'work-mode',
+    'plan-path',
+    'completed_steps',
+    'next_step',
+    'last_updated',
+    'step5_status',
+    'step6_status',
+    'step7_status',
+    'step8_status',
+    'step9_status',
+    'step10_status',
+    'delegation_receipts',
+    'blocked_reason'
+)
+
+# The lifecycle step-status keys whose value, when present, must be a member of
+# VALID_STEP_STATUS. Pinned to STEP_STATUS_KEYS in the primary validator.
+$script:STEP_STATUS_KEYS = @(
+    'step5_status',
+    'step6_status',
+    'step7_status',
+    'step8_status',
+    'step9_status',
+    'step10_status'
+)
+
+# The allowed step-status vocabulary. Pinned to VALID_STEP_STATUS in the primary
+# validator.
+$script:VALID_STEP_STATUS = @(
+    'not-applicable',
+    'pending',
+    'delegated',
+    'verified',
+    'blocked',
+    'not_started',
+    'in_progress',
+    'completed'
+)
+
+# The allowed blocked_reason vocabulary. Pinned to VALID_BLOCKED_REASONS in the
+# primary validator.
+$script:VALID_BLOCKED_REASONS = @(
+    'none',
+    'spawn_agent_unavailable',
+    'delegation_launch_failed',
+    'delegate_no_receipt',
+    'delegate_contract_incomplete',
+    'validator_failed',
+    'user_requested_stop'
+)
+
+# The upstream steps that must not be pending/blocked before the first PR creation
+# of a branch. Pinned to PR_CREATION_READY_STEP_KEYS in
+# _orchestrator_state_pr_creation_readiness.py (deliberately narrower than the full
+# step set: steps 9-10 can only populate after PR creation and CI have run).
+$script:PR_CREATION_READY_STEP_KEYS = @(
+    'step5_status',
+    'step6_status',
+    'step7_status',
+    'step8_status'
+)
+
+# The checkpoint list fields that must be empty (or absent) before the first PR
+# creation. Pinned to PR_CREATION_READY_EMPTY_LIST_KEYS in the Python reference.
+$script:PR_CREATION_READY_EMPTY_LIST_KEYS = @(
+    'local_execution_overrides',
+    'delegation_bypasses'
+)
+
+
+function Get-OrchestratorStateCheckpoint {
+    <#
+    .SYNOPSIS
+        Load and parse an orchestrator-state checkpoint, failing closed on error.
+    .DESCRIPTION
+        Private load helper. Reads the checkpoint at -CheckpointPath and parses it as
+        JSON. It never throws to the caller: a missing file or unparseable/invalid
+        JSON is reported through a structured result with Ok = $false and a non-empty
+        Error string, so callers can translate the failure into a fail-closed
+        non-zero ExitCode.
+    .PARAMETER CheckpointPath
+        The path to the orchestrator-state checkpoint JSON file.
+    .OUTPUTS
+        System.Collections.Hashtable with keys:
+          - Ok    (bool): $true when the file exists and parsed to a JSON object.
+          - State (object): the parsed PSCustomObject on success, otherwise $null.
+          - Error (string): a non-empty failure message on failure, otherwise ''.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $CheckpointPath
+    )
+
+    # A missing checkpoint file is a fail-closed condition: there is no state to
+    # validate, so readiness cannot be established.
+    if (-not (Test-Path -LiteralPath $CheckpointPath -PathType Leaf)) {
+        return @{
+            Ok    = $false
+            State = $null
+            Error = "Checkpoint file '$CheckpointPath' does not exist."
+        }
+    }
+
+    $raw = Get-Content -LiteralPath $CheckpointPath -Raw -ErrorAction Stop
+
+    # An empty checkpoint carries no state; treat it as fail-closed rather than
+    # letting ConvertFrom-Json return $null silently.
+    if ([string]::IsNullOrWhiteSpace($raw)) {
+        return @{
+            Ok    = $false
+            State = $null
+            Error = "Checkpoint file '$CheckpointPath' is empty."
+        }
+    }
+
+    # Parse the checkpoint text. Invalid JSON is a fail-closed condition, caught here
+    # so the caller receives a message instead of a terminating error.
+    try {
+        $state = $raw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return @{
+            Ok    = $false
+            State = $null
+            Error = "Checkpoint file '$CheckpointPath' is not valid JSON: $($_.Exception.Message)"
+        }
+    }
+
+    # A JSON scalar or array root is not a checkpoint object; require an object so
+    # the presence checks can inspect named fields.
+    if ($state -isnot [System.Management.Automation.PSCustomObject]) {
+        return @{
+            Ok    = $false
+            State = $null
+            Error = "Checkpoint file '$CheckpointPath' root must be a JSON object."
+        }
+    }
+
+    return @{ Ok = $true; State = $state; Error = '' }
+}
+
+function Get-OrchestratorStateField {
+    <#
+    .SYNOPSIS
+        Read a checkpoint field, distinguishing an absent key from a null value.
+    .DESCRIPTION
+        Private accessor that safely reads a named property from the parsed
+        checkpoint object under Set-StrictMode, where accessing an undefined property
+        would otherwise throw. Returns whether the key is present and its value,
+        mirroring the semantics of Python's ``dict.get`` (absent and null both read
+        as "no value" for the readiness checks).
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .PARAMETER Name
+        The property name to read.
+    .OUTPUTS
+        System.Collections.Hashtable with keys Present (bool) and Value (object).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State,
+
+        [Parameter(Mandatory = $true)]
+        [string] $Name
+    )
+
+    $names = @($State.PSObject.Properties.Name)
+    if ($names -contains $Name) {
+        return @{ Present = $true; Value = $State.$Name }
+    }
+    return @{ Present = $false; Value = $null }
+}
+
+function Get-OrchestratorStateBasePresenceError {
+    <#
+    .SYNOPSIS
+        Return the base checkpoint-presence errors, mirroring the primary validator.
+    .DESCRIPTION
+        Private base check. Emits one error string per missing required key, one per
+        step5_status..step10_status value outside VALID_STEP_STATUS, and one when
+        blocked_reason is present with a value outside VALID_BLOCKED_REASONS. This
+        mirrors the base block of scripts/dev_tools/validate_orchestrator_state.py
+        (required keys, step-status validity, blocked_reason validity) that runs
+        before any mode-specific gate.
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .OUTPUTS
+        System.String[] - zero or more error strings; empty when the base shape is valid.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $names = @($State.PSObject.Properties.Name)
+
+    # Require every canonical top-level field; a missing key is reported individually
+    # so the operator sees exactly which fields are absent.
+    foreach ($key in $script:REQUIRED_STATE_KEYS) {
+        if ($names -notcontains $key) {
+            $errors.Add("Checkpoint missing required key: $key")
+        }
+    }
+
+    # Every present step status must be a member of the allowed vocabulary; an absent
+    # step key contributes no error (mirrors the primary validator's None guard).
+    foreach ($key in $script:STEP_STATUS_KEYS) {
+        $field = Get-OrchestratorStateField -State $State -Name $key
+        if ($field.Present -and $null -ne $field.Value -and
+            ($script:VALID_STEP_STATUS -notcontains [string]$field.Value)) {
+            $errors.Add("Checkpoint has invalid $key`: $($field.Value)")
+        }
+    }
+
+    # A present, non-null blocked_reason must be a member of the allowed vocabulary.
+    $blocked = Get-OrchestratorStateField -State $State -Name 'blocked_reason'
+    if ($blocked.Present -and $null -ne $blocked.Value -and
+        ($script:VALID_BLOCKED_REASONS -notcontains [string]$blocked.Value)) {
+        $errors.Add("Checkpoint has invalid blocked_reason: $($blocked.Value)")
+    }
+
+    return $errors.ToArray()
+}
+
+function Get-OrchestratorStatePrCreationReadinessError {
+    <#
+    .SYNOPSIS
+        Return the PR-creation-readiness errors, parity with the Python reference.
+    .DESCRIPTION
+        Private readiness check mirroring
+        validate_orchestrator_state_pr_creation_readiness in
+        _orchestrator_state_pr_creation_readiness.py: steps 5-8 must not be
+        pending/blocked; blocked_reason must be `none` or absent; and the
+        local_execution_overrides / delegation_bypasses lists must be empty when
+        present. It does not enforce completion, CI, PR, or routing-contract gates.
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .OUTPUTS
+        System.String[] - zero or more error strings; empty when ready for PR creation.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+
+    # Reject an upstream step recorded as pending or blocked; steps 5-8 must have
+    # finished before the first PR of a branch is created.
+    foreach ($key in $script:PR_CREATION_READY_STEP_KEYS) {
+        $field = Get-OrchestratorStateField -State $State -Name $key
+        if ($field.Present -and ($field.Value -eq 'pending' -or $field.Value -eq 'blocked')) {
+            $errors.Add("Checkpoint PR-creation readiness validation failed: $key is $($field.Value).")
+        }
+    }
+
+    # blocked_reason must read as clear: absent, null, or the literal 'none'. Any
+    # other recorded reason means the branch is not ready for PR creation.
+    $blocked = Get-OrchestratorStateField -State $State -Name 'blocked_reason'
+    if ($blocked.Present -and $null -ne $blocked.Value -and ([string]$blocked.Value -ne 'none')) {
+        $errors.Add('Checkpoint PR-creation readiness validation failed: blocked_reason is not `none`.')
+    }
+
+    # Each override list must be empty when present: a present non-list value, or a
+    # present non-empty list, means overrides/bypasses were recorded (mirrors the
+    # Python `value is not None and (not isinstance(value, list) or value)` guard).
+    foreach ($key in $script:PR_CREATION_READY_EMPTY_LIST_KEYS) {
+        $field = Get-OrchestratorStateField -State $State -Name $key
+        if ($field.Present -and $null -ne $field.Value) {
+            $isList = $field.Value -is [System.Array]
+            if (-not $isList -or @($field.Value).Count -gt 0) {
+                $errors.Add("Checkpoint PR-creation readiness validation failed: $key must be an empty list when present.")
+            }
+        }
+    }
+
+    return $errors.ToArray()
+}
+
+function Test-PythonOrchestratorValidatorAvailable {
+    <#
+    .SYNOPSIS
+        Probe whether the authoritative Python orchestrator-state validator is importable.
+    .DESCRIPTION
+        Capability-detection seam. Returns $true only when
+        ``python -c "import scripts.dev_tools.validate_orchestration_artifacts"`` exits 0,
+        indicating the authoritative Python validator ships in this repository (drm-copilot).
+        Returns $false on any non-zero exit or error, so a consumer repository that received
+        only the pushed-down `.claude` pack (no `scripts/dev_tools`) routes to the portable
+        PowerShell module. Any probe failure routes to the portable path, which itself fails
+        closed on bad checkpoints, preserving fail-closed semantics in both branches. Tests
+        mock this seam directly; they never mock `python`.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param()
+
+    try {
+        & python -c 'import scripts.dev_tools.validate_orchestration_artifacts' 2>&1 | Out-Null
+        return ($LASTEXITCODE -eq 0)
+    } catch {
+        return $false
+    }
+}
+
+function Test-OrchestratorStatePrCreationReadiness {
+    <#
+    .SYNOPSIS
+        Validate a checkpoint is ready for the first `gh pr create` of a branch.
+    .DESCRIPTION
+        Public entry point used by the pushed-down enforce-pr-author-skill hook when
+        the authoritative Python validator is not importable. Loads the checkpoint
+        (fail-closed on missing file / invalid JSON), runs the base-presence check
+        (required keys, step-status validity, blocked_reason validity), then runs the
+        PR-creation-readiness parity check. Returns a hashtable compatible with the
+        hook's existing invoker contract: ExitCode is 1 whenever any error is present,
+        and Output carries the newline-joined error text (empty on success).
+    .PARAMETER CheckpointPath
+        The path to the orchestrator-state checkpoint JSON file.
+    .OUTPUTS
+        System.Collections.Hashtable with keys ExitCode (int, 0 or 1) and Output (string).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $CheckpointPath
+    )
+
+    # Fail closed when the checkpoint cannot be loaded: the load error is the whole
+    # output and ExitCode is 1.
+    $loaded = Get-OrchestratorStateCheckpoint -CheckpointPath $CheckpointPath
+    if (-not $loaded.Ok) {
+        return @{ ExitCode = 1; Output = $loaded.Error }
+    }
+
+    # Accumulate base-presence errors and readiness errors; any error yields a
+    # non-zero ExitCode so the hook blocks PR creation.
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $errors.AddRange([string[]]@(Get-OrchestratorStateBasePresenceError -State $loaded.State))
+    $errors.AddRange([string[]]@(Get-OrchestratorStatePrCreationReadinessError -State $loaded.State))
+
+    if ($errors.Count -gt 0) {
+        return @{ ExitCode = 1; Output = ($errors -join [System.Environment]::NewLine) }
+    }
+
+    return @{ ExitCode = 0; Output = '' }
+}
+
+function Invoke-OrchestratorStatePreflight {
+    <#
+    .SYNOPSIS
+        Runs the orchestrator-state validator against the checkpoint and reports pass/fail.
+    .DESCRIPTION
+        Shared by the pushed-down enforce-pr-author-skill hook. Mirrors
+        Invoke-RoutingContractValidation (.claude/hooks/validate-orchestrator-output.ps1):
+        an injectable subprocess scriptblock seam defaults to ``python -m
+        scripts.dev_tools.validate_orchestration_artifacts orchestrator-state <CheckpointPath>
+        --require-pr-creation-ready``. A missing checkpoint or --require-pr-creation-ready failure
+        both surface via the validator's non-zero exit/stderr text; no separate file-existence check
+        is made, validating pre-PR-creation readiness (steps 5-8, blocked_reason) not full completion.
+    .PARAMETER CheckpointPath
+        The path to the orchestrator-state checkpoint JSON file. Callers pass their own
+        checkpoint-path variable explicitly; the default below is only used when a caller omits
+        the parameter.
+    .OUTPUTS
+        System.Collections.Hashtable with keys HasErrors (bool) and ErrorText (string).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $false)]
+        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json',
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $Invoker = {
+            param($Path)
+            # Capability detection: use the authoritative Python CLI when
+            # scripts.dev_tools is importable (drm-copilot); otherwise fall back to
+            # the portable PowerShell function that lives alongside this one in the
+            # pushed-down pack.
+            if (Test-PythonOrchestratorValidatorAvailable) {
+                $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
+                    orchestrator-state $Path --require-pr-creation-ready 2>&1
+                [pscustomobject]@{
+                    ExitCode = $LASTEXITCODE
+                    Output   = ($output | Out-String)
+                }
+            } else {
+                $portable = Test-OrchestratorStatePrCreationReadiness -CheckpointPath $Path
+                [pscustomobject]@{
+                    ExitCode = $portable.ExitCode
+                    Output   = $portable.Output
+                }
+            }
+        }
+    )
+
+    $result = & $Invoker $CheckpointPath
+    # Under this module's Set-StrictMode -Version Latest, member-enumerating .Name directly over
+    # a zero-property PSCustomObject throws (a PowerShell strict-mode gotcha not present in the
+    # hook's un-strict scope this code was moved from), so the property collection is counted
+    # before .Name is ever accessed.
+    $resultPropertyNames = @()
+    if ($null -ne $result -and @($result.PSObject.Properties).Count -gt 0) {
+        $resultPropertyNames = @($result.PSObject.Properties.Name)
+    }
+    $exitCode = 0
+    if ($resultPropertyNames -contains 'ExitCode') { $exitCode = [int]$result.ExitCode }
+    $outputText = ''
+    if ($resultPropertyNames -contains 'Output') { $outputText = ([string]$result.Output).Trim() }
+
+    return @{ HasErrors = ($exitCode -ne 0); ErrorText = $outputText }
+}
+
+# Export the public readiness entry point plus the reusable load, field-accessor,
+# and base-presence primitives so the sibling OrchestratorStateCompletion module can
+# consume them via Import-Module without duplicating the shared parsing and
+# base-check logic. Test-PythonOrchestratorValidatorAvailable and
+# Invoke-OrchestratorStatePreflight are exported so both pushed-down hooks
+# (enforce-pr-author-skill.ps1, validate-orchestrator-output.ps1) can consume them
+# without duplicating the capability probe or the PR-creation preflight orchestration.
+Export-ModuleMember -Function `
+    Test-OrchestratorStatePrCreationReadiness, `
+    Get-OrchestratorStateCheckpoint, `
+    Get-OrchestratorStateField, `
+    Get-OrchestratorStateBasePresenceError, `
+    Test-PythonOrchestratorValidatorAvailable, `
+    Invoke-OrchestratorStatePreflight

package/resources/claude-customizations/.claude/lib/orchestrator-state/OrchestratorStateCompletion.psm1

@@ -0,0 +1,243 @@
+<#
+.SYNOPSIS
+    Portable completion-gate presence checks for the orchestrator-state checkpoint.
+
+.DESCRIPTION
+    Provides the destination-runtime PowerShell mirror of the completion-gate
+    presence checks the pushed-down validate-orchestrator-output hook needs when the
+    authoritative Python validator (`scripts/dev_tools`) is not importable. It
+    reuses the shared load, field-accessor, and base-presence primitives from the
+    sibling `OrchestratorState.psm1` and imports `.claude/lib/model-routing/ModelRouting.psm1`
+    so per-receipt model formulas are available where practical.
+
+    The single public function `Test-OrchestratorStateCompletionReadiness` fails
+    closed on a missing checkpoint file, invalid JSON, or an invalid base shape, then
+    applies the model-routing "required once delegated" existence gate - the
+    delegated-agent set (derived from `delegation_receipts[].agent_name` plus a
+    delegating `next_step`) must be a subset of `model_routing_receipts[].agent` -
+    mirroring `scripts/dev_tools/_orchestrator_state_model_routing_gate.py`. Deep
+    per-receipt routing-contract correctness that requires full Python authority is a
+    documented Non-Goal for the portable path; the gate performs the presence-level
+    existence check and reports missing receipts with error text containing the
+    literal token `model_routing_receipts`, so the completion hook maps a failure to
+    its `MODEL_ROUTING_BLOCKED:` block reason. The Python validator remains
+    authoritative; this module is the fallback mirror only.
+#>
+
+Set-StrictMode -Version Latest
+
+# Import the sibling shared module and the portable model-routing module, resolved
+# relative to this module's directory so the imports travel with the pushed-down
+# pack regardless of the consumer repository's working directory.
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorState.psm1') -Force
+$script:ModelRoutingModulePath = Join-Path -Path (Join-Path -Path $PSScriptRoot -ChildPath '..') -ChildPath (Join-Path -Path 'model-routing' -ChildPath 'ModelRouting.psm1')
+Import-Module $script:ModelRoutingModulePath -Force
+
+# The subagent types delegated via the Agent tool that can be named by a delegating
+# next_step. Pinned to _DELEGATING_AGENTS in
+# scripts/dev_tools/_orchestrator_state_model_routing_gate.py. The `orchestrator`
+# type is deliberately excluded: it is the caller, never a routing-receipt target.
+$script:DELEGATING_AGENTS = @(
+    'atomic-planner',
+    'atomic-executor',
+    'feature-review',
+    'task-researcher',
+    'prd-feature',
+    'pr-author'
+)
+
+# Checkpoint keys the gate reads to derive the delegated-agent and receipt-agent sets.
+$script:DELEGATION_RECEIPTS_KEY = 'delegation_receipts'
+$script:MODEL_ROUTING_RECEIPTS_KEY = 'model_routing_receipts'
+$script:NEXT_STEP_KEY = 'next_step'
+
+
+function Get-OrchestratorStateDelegatedAgent {
+    <#
+    .SYNOPSIS
+        Derive the set of agents a checkpoint has delegated (or is about to).
+    .DESCRIPTION
+        Private helper mirroring ``_delegated_agents`` in the Python gate. Collects
+        each well-formed ``delegation_receipts[]`` entry's non-empty ``agent_name``
+        plus the agent implied by a ``next_step`` that names a recognized delegating
+        agent. The list form of ``delegation_receipts`` is the authoritative "a
+        delegation happened" record; the namespaced (promotion) object form carries
+        no agent_name list and contributes no delegated agents.
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .OUTPUTS
+        System.String[] - the delegated-agent names (may be empty).
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $agents = [System.Collections.Generic.HashSet[string]]::new()
+
+    # Collect each list-form delegation receipt's non-empty agent_name. A non-list
+    # (namespaced) delegation_receipts value contributes nothing here.
+    $receiptsField = Get-OrchestratorStateField -State $State -Name $script:DELEGATION_RECEIPTS_KEY
+    if ($receiptsField.Present -and ($receiptsField.Value -is [System.Array])) {
+        foreach ($receipt in $receiptsField.Value) {
+            if ($receipt -is [System.Management.Automation.PSCustomObject]) {
+                $nameField = Get-OrchestratorStateField -State $receipt -Name 'agent_name'
+                if ($nameField.Present -and $null -ne $nameField.Value -and
+                    -not [string]::IsNullOrWhiteSpace([string]$nameField.Value)) {
+                    [void]$agents.Add([string]$nameField.Value)
+                }
+            }
+        }
+    }
+
+    # A delegating next_step names the upcoming delegation that may not yet have a
+    # receipt; include it only when it matches a recognized delegating agent so a
+    # non-delegating label (for example "complete") never triggers the gate.
+    $nextStepField = Get-OrchestratorStateField -State $State -Name $script:NEXT_STEP_KEY
+    if ($nextStepField.Present -and $null -ne $nextStepField.Value -and
+        ($script:DELEGATING_AGENTS -contains [string]$nextStepField.Value)) {
+        [void]$agents.Add([string]$nextStepField.Value)
+    }
+
+    return [string[]]@($agents)
+}
+
+function Get-OrchestratorStateRoutingReceiptAgent {
+    <#
+    .SYNOPSIS
+        Collect the set of agents that carry a model-routing receipt.
+    .DESCRIPTION
+        Private helper mirroring the receipt-agent harvest in the Python gate. Reads
+        the checkpoint's ``model_routing_receipts[]`` array and returns the set of
+        non-empty ``agent`` values present on well-formed receipt objects. A non-list
+        value contributes no agents (the existence gate then reports every delegated
+        agent as unreceipted, preserving fail-closed semantics).
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .OUTPUTS
+        System.String[] - the receipt-agent names (may be empty).
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $agents = [System.Collections.Generic.HashSet[string]]::new()
+
+    $receiptsField = Get-OrchestratorStateField -State $State -Name $script:MODEL_ROUTING_RECEIPTS_KEY
+    if ($receiptsField.Present -and ($receiptsField.Value -is [System.Array])) {
+        # Record each well-formed receipt's non-empty agent so the existence gate can
+        # test the delegated-agent set against it.
+        foreach ($receipt in $receiptsField.Value) {
+            if ($receipt -is [System.Management.Automation.PSCustomObject]) {
+                $agentField = Get-OrchestratorStateField -State $receipt -Name 'agent'
+                if ($agentField.Present -and $null -ne $agentField.Value -and
+                    -not [string]::IsNullOrWhiteSpace([string]$agentField.Value)) {
+                    [void]$agents.Add([string]$agentField.Value)
+                }
+            }
+        }
+    }
+
+    return [string[]]@($agents)
+}
+
+function Get-OrchestratorStateModelRoutingGateError {
+    <#
+    .SYNOPSIS
+        Return the required-once-delegated existence-gate errors.
+    .DESCRIPTION
+        Private gate mirroring ``validate_model_routing_gate`` at the presence level:
+        it fires only when the checkpoint has delegated (or is about to delegate to)
+        at least one agent, then reports one error per delegated agent that lacks a
+        matching ``model_routing_receipts[]`` entry. A delegation-free checkpoint
+        contributes zero errors, preserving backward compatibility. Each error names
+        the literal token ``model_routing_receipts`` so the completion hook routes a
+        failure to ``MODEL_ROUTING_BLOCKED:``.
+    .PARAMETER State
+        The parsed checkpoint PSCustomObject.
+    .OUTPUTS
+        System.String[] - zero or more error strings; empty when the gate is satisfied
+        or does not fire.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+
+    # Backward-compat gate: a delegation-free checkpoint imposes no routing-receipt
+    # requirement, so return early with no errors.
+    $delegated = @(Get-OrchestratorStateDelegatedAgent -State $State)
+    if ($delegated.Count -eq 0) {
+        return $errors.ToArray()
+    }
+
+    $receiptAgents = @(Get-OrchestratorStateRoutingReceiptAgent -State $State)
+
+    # Existence invariant: the routing-receipt agent set must be a superset of the
+    # delegated-agent set. Report each delegated agent with no receipt, sorted for
+    # deterministic error ordering.
+    $missing = $delegated | Where-Object { $receiptAgents -notcontains $_ } | Sort-Object
+    foreach ($agent in $missing) {
+        $errors.Add("Checkpoint model_routing_receipts is missing a receipt for delegated agent: $agent.")
+    }
+
+    return $errors.ToArray()
+}
+
+function Test-OrchestratorStateCompletionReadiness {
+    <#
+    .SYNOPSIS
+        Validate a checkpoint satisfies the portable completion-gate presence checks.
+    .DESCRIPTION
+        Public entry point used by the pushed-down validate-orchestrator-output hook
+        when the authoritative Python validator is not importable. Loads the
+        checkpoint (fail-closed on missing file / invalid JSON / invalid base shape),
+        runs the base-presence check (required keys, step-status validity,
+        blocked_reason validity), then applies the model-routing required-once-
+        delegated existence gate. Returns a hashtable compatible with the hook's
+        invoker contract: ExitCode is 1 whenever any error is present, and Output
+        carries the newline-joined error text (empty on success). A missing routing
+        receipt yields error text containing ``model_routing_receipts`` so the hook
+        surfaces it under ``MODEL_ROUTING_BLOCKED:``.
+    .PARAMETER CheckpointPath
+        The path to the orchestrator-state checkpoint JSON file.
+    .OUTPUTS
+        System.Collections.Hashtable with keys ExitCode (int, 0 or 1) and Output (string).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $CheckpointPath
+    )
+
+    # Fail closed when the checkpoint cannot be loaded: the load error is the whole
+    # output and ExitCode is 1.
+    $loaded = Get-OrchestratorStateCheckpoint -CheckpointPath $CheckpointPath
+    if (-not $loaded.Ok) {
+        return @{ ExitCode = 1; Output = $loaded.Error }
+    }
+
+    # Accumulate base-presence errors and existence-gate errors; any error yields a
+    # non-zero ExitCode so the completion hook blocks DONE.
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $errors.AddRange([string[]]@(Get-OrchestratorStateBasePresenceError -State $loaded.State))
+    $errors.AddRange([string[]]@(Get-OrchestratorStateModelRoutingGateError -State $loaded.State))
+
+    if ($errors.Count -gt 0) {
+        return @{ ExitCode = 1; Output = ($errors -join [System.Environment]::NewLine) }
+    }
+
+    return @{ ExitCode = 0; Output = '' }
+}
+
+Export-ModuleMember -Function Test-OrchestratorStateCompletionReadiness

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -119,6 +119,13 @@ reference implementations are `.claude/lib/model-routing/ModelRouting.psm1`
 (`Get-ComplexityFloor`) and `.claude/lib/model-routing/ModelRouting.psm1`
 (`Resolve-DelegationModel`). Default `fable_policy` is `disabled` when the marker is absent.
 
+When `epic-orchestrator` itself spawns `Agent(orchestrator)` or `Agent(pr-author)`, it applies
+the same per-delegation resolution and passes `model` equal to the routing receipt's `model` on
+the spawn call. It MUST NOT omit `model` (an omitted `model` falls back to the delegate's
+frontmatter default — `opus` for these workers — which suppresses a `fable` resolution) and
+MUST NOT hard-code `model=opus` in a way that overrides the resolved routing model, mirroring
+step 5 of `## Model Selection` in `.claude/skills/orchestrate/SKILL.md`.
+
 `route` is never an input to model selection; `route` remains file-count driven and governs only
 agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`
 inherits the parent model and ignores a model override, so model selection applies to agent

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -95,6 +95,8 @@ End-to-end procedure:
 3. **Run the per-delegation selection order.** For each delegation, resolve the model as `resolve_delegation_model(agent, complexity_band, fable_policy)`: the `table_model` is the `preferred` overlay value when (`fable_policy == "preferred"` and the agent is in the overlay set `{atomic-planner, prd-feature, feature-review, task-researcher}` and `band == "C3"`), otherwise the base `complexity_to_model[band]`. Under `fable_policy == "disabled"`, a `fable` `table_model` clamps to `model = "opus"` with `clamped_from = "fable"`. `atomic-executor` and `pr-author` C3 cells stay `opus` under every policy.
 4. **Emit a routing receipt.** Record a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`. `table_model` is the pre-clamp lookup; `model` is the post-clamp result.
 
+5. **Delegate with the resolved model.** Pass `model` equal to the receipt's `model` on the `Agent(...)` spawn call for that delegation. The orchestrator MUST NOT omit `model` on the spawn (an omitted `model` falls back to the delegate's frontmatter default — `opus` for most workers — which suppresses a `fable` or `sonnet` resolution), and MUST NOT hard-code `model=opus` in a way that overrides the resolved routing model. This applies to every fresh delegation, mirroring the resume-path rule ("delegate with `model` equal to the receipt's `model`") so both paths bind the spawn model to the routing receipt.
+
 The `complexity_assessments[]` and `model_routing_receipts[]` invariants are enforced by `scripts/dev_tools/validate_orchestrator_state.py` per `.claude/rules/orchestrator-state.md`; both arrays remain additive (a checkpoint that predates model routing stays valid).
 
 ### Required-once-delegated invariant (`require_model_routing` mode)

package/resources/claude-customizations/pack-manifests/core.json

@@ -70,6 +70,8 @@
     ".claude/skills/skill-canonical-location-audit/SKILL.md",
     ".claude/skills/translate-copilot-to-claude/SKILL.md",
     ".claude/skills/update-status/SKILL.md",
-    ".claude/lib/model-routing/ModelRouting.psm1"
+    ".claude/lib/model-routing/ModelRouting.psm1",
+    ".claude/lib/orchestrator-state/OrchestratorState.psm1",
+    ".claude/lib/orchestrator-state/OrchestratorStateCompletion.psm1"
   ]
 }

package/resources/config/orchestration-routing.json

@@ -163,6 +163,6 @@
   },
   "model_budget": {
     "description": "Session-level model budget. fable_policy is a three-way switch controlling whether the fable tier is disabled (removed and clamped to opus), available (used as-is), or preferred (applies the preferred_overlay).",
-    "fable_policy": "disabled"
+    "fable_policy": "preferred"
   }
 }