@danmoisan/drm-copilot-mcp 0.0.5 → 1.0.0

package/resources/claude-customizations/.claude/hooks/enforce-evidence-locations.ps1

@@ -17,12 +17,15 @@
       - artifacts/evidence/
       - artifacts/regression-testing/
       - artifacts/post-change/
+      - artifacts/research/
 
     All other paths pass through, including canonical evidence paths of the form
     <FEATURE>/evidence/<kind>/ and permitted artifacts/ sub-paths such as
-    artifacts/orchestration/, artifacts/research/, artifacts/pr_context,
-    artifacts/reviews/, artifacts/status/, artifacts/python/, artifacts/pester/,
-    and artifacts/csharp/.
+    artifacts/orchestration/, artifacts/pr_context, artifacts/reviews/,
+    artifacts/status/, artifacts/python/, artifacts/pester/, and
+    artifacts/csharp/. Research output is no longer an artifacts/ sub-path; it
+    is written to the tracked roots docs/features/<feature>/research/
+    (feature-associated) or docs/research/ (one-off).
 
     If the file_path resolves to a forbidden prefix, the script writes a JSON response
     to stdout with 'decision': 'block' and exits with code 0 so Claude Code surfaces
@@ -61,7 +64,8 @@ function Test-EvidenceLocationForbidden {
         'artifacts/coverage/',
         'artifacts/evidence/',
         'artifacts/regression-testing/',
-        'artifacts/post-change/'
+        'artifacts/post-change/',
+        'artifacts/research/'
     )
 
     # Match the prefix either at the start of the string or after any directory separator,
@@ -133,18 +137,40 @@ function Invoke-EvidenceLocationDecision {
     return [ordered]@{ decision = 'allow' }
 }
 
+function Invoke-EvidenceLocationEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the evidence-location decision and returns the process exit code.
+    .DESCRIPTION
+        Wraps the dispatch logic that the hook entry point performs so it can be
+        exercised by unit tests. On success it writes the compact JSON decision to
+        the output stream and returns 0. On a hard failure (malformed JSON) it
+        writes the error record and returns 1. This function does not call exit;
+        the thin entry-point wiring converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [string] $ToolInputRaw = $env:CLAUDE_TOOL_INPUT
+    )
+
+    try {
+        $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $ToolInputRaw
+    } catch {
+        Write-Error $_
+        return 1
+    }
+
+    $decision | ConvertTo-Json -Compress | Write-Output
+
+    return 0
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress | Write-Output
-
-exit 0
+exit (Invoke-EvidenceLocationEntryPoint)

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -0,0 +1,198 @@
+<#
+.SYNOPSIS
+    Blocks implementation operations before orchestration readiness exists.
+#>
+[CmdletBinding()]
+param()
+
+$script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+
+function ConvertFrom-CheckpointJson {
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][string] $Json)
+
+    return $Json | ConvertFrom-Json -ErrorAction Stop
+}
+
+function Get-StringProperty {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowNull()] $Value,
+        [Parameter(Mandatory)][string] $Name
+    )
+
+    if ($null -eq $Value -or -not ($Value.PSObject.Properties.Name -contains $Name)) {
+        return ''
+    }
+    return ([string]$Value.$Name).Trim()
+}
+
+function Test-FeatureDocumentationOrEvidencePath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $NormalizedPath)
+
+    return $NormalizedPath.StartsWith('docs/features/active/')
+}
+
+function Test-ImplementationPath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $NormalizedPath)
+
+    if (Test-FeatureDocumentationOrEvidencePath -NormalizedPath $NormalizedPath) {
+        return $false
+    }
+    if ($NormalizedPath -eq $script:CheckpointPath) {
+        return $false
+    }
+    return $NormalizedPath -match '\.(py|ps1|psm1|ts|tsx|js|jsx|cs|json|yml|yaml)$'
+}
+
+function Test-ImplementationCommand {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $Command)
+
+    $normalizedCommand = $Command.Trim()
+    if (-not $normalizedCommand) {
+        return $false
+    }
+
+    $implementationCommandPatterns = @(
+        '(^|\s)git\s+(add|commit)\b',
+        '(^|\s)(poetry\s+run\s+)?(black|ruff|pyright|pytest)\b',
+        '(^|\s)npm\s+.*\s+(prettier|lint|typecheck|test:unit)\b',
+        '(^|\s)npx\s+(prettier|eslint|tsc|jest)\b',
+        '(^|\s)pwsh\s+.*(Invoke-Pester|tests/scripts/)'
+    )
+
+    foreach ($pattern in $implementationCommandPatterns) {
+        if ($normalizedCommand -match $pattern) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Test-ImplementationDelegation {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $ToolInput)
+
+    if ($null -eq $ToolInput) {
+        return $false
+    }
+
+    $payloadText = ($ToolInput | ConvertTo-Json -Depth 20 -Compress)
+    return $payloadText -match '(python-typed-engineer|powershell-typed-engineer|typescript-engineer|csharp-typed-engineer|atomic-executor|implementation|execute)'
+}
+
+function Test-OrchestrationReady {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $Payload)
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+    $issueNum = Get-StringProperty -Value $Payload -Name 'issue-num'
+    $featureFolder = Get-StringProperty -Value $Payload -Name 'feature-folder'
+    $routeId = Get-StringProperty -Value $Payload -Name 'route_id'
+    if (-not $routeId) {
+        $routeId = Get-StringProperty -Value $Payload -Name 'path_selected'
+    }
+    $lifecycleReady = $false
+    if ($Payload.PSObject.Properties.Name -contains 'lifecycle_ready') {
+        $lifecycleReady = [bool]$Payload.lifecycle_ready
+    }
+
+    if (-not $issueNum -or -not $featureFolder -or -not $routeId -or -not $lifecycleReady) {
+        return $false
+    }
+
+    return (
+        $featureFolder.StartsWith('docs/features/active/') -and
+        $routeId -and
+        $lifecycleReady
+    )
+}
+
+function Get-CheckpointContent {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:CheckpointPath)) {
+        return ''
+    }
+    return Get-Content -Raw -LiteralPath $script:CheckpointPath
+}
+
+function Invoke-OrchestrationPreimplementationGateDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw,
+        [string] $CheckpointRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-orchestration-preimplementation-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $requiresReadyCheckpoint = $false
+    $filePath = Get-StringProperty -Value $toolInput -Name 'file_path'
+    if ($filePath) {
+        $normalized = ([string]$filePath) -replace '\\', '/'
+        $requiresReadyCheckpoint = Test-ImplementationPath -NormalizedPath $normalized
+    } else {
+        $command = Get-StringProperty -Value $toolInput -Name 'command'
+        if ($command) {
+            $requiresReadyCheckpoint = Test-ImplementationCommand -Command $command
+        } else {
+            $requiresReadyCheckpoint = Test-ImplementationDelegation -ToolInput $toolInput
+        }
+    }
+
+    if (-not $requiresReadyCheckpoint) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (-not $CheckpointRaw) {
+        $CheckpointRaw = Get-CheckpointContent
+    }
+    try {
+        $checkpoint = ConvertFrom-CheckpointJson -Json $CheckpointRaw
+    } catch {
+        $checkpoint = $null
+    }
+
+    if (Test-OrchestrationReady -Payload $checkpoint) {
+        return [ordered]@{ decision = 'allow' }
+    }
+    return [ordered]@{
+        decision = 'block'
+        reason   = 'PREIMPLEMENTATION_GATE_BLOCKED: Implementation operations require artifacts/orchestration/orchestrator-state.json to contain issue number, feature folder, route metadata, lifecycle readiness, and checkpoint state before implementation begins.'
+    }
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-OrchestrationPreimplementationGateDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+exit 0

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

@@ -14,18 +14,39 @@
       3. gh pr create --body-file artifacts/pr_body_<N>.md
          (or gh pr edit --body-file ...)
 
-    Three block cases:
-      Case A - gh pr create with --body (inline, no --body-file): blocked.
+    Block cases:
+      Case A - gh pr create or gh pr edit with --body (inline, no --body-file): blocked.
       Case B - gh pr create with neither --body nor --body-file: blocked.
       Case C - gh pr create or gh pr edit with --body-file but context artifact absent: blocked.
+      Case D - --body-file present, context artifact present, but the authorization sentinel
+               artifacts/pr_author_authorization.json is absent or empty: blocked
+               (PR_AGENT_AUTHORIZATION_MISSING).
+      Malformed - sentinel present but not valid JSON, or issued_at missing/unparseable: blocked
+               (PR_AGENT_AUTHORIZATION_MALFORMED).
+      Case E - sentinel valid JSON but issued_by != "pr-author": blocked
+               (PR_AGENT_AUTHORIZATION_INVALID).
+      Case F - sentinel issued_by == "pr-author" but elapsed time since issued_at exceeds
+               ttl_seconds: blocked (PR_AGENT_AUTHORIZATION_EXPIRED).
+
+    Authorization sentinel decision order on the --body-file-with-context path:
+      missing -> malformed -> invalid issuer -> expired -> allow.
 
 .NOTES
     Compatible with PowerShell 7+. No external module dependencies.
+
+    Enforcement strength: the authorization sentinel is a policy guardrail, not a cryptographic
+    or security control. Any actor with Write access to artifacts/ can forge
+    artifacts/pr_author_authorization.json, because all agents share the same filesystem and the
+    runtime exposes no native agent-identity signal at Bash PreToolUse time. The mechanism prevents
+    accidental bypass and requires a deliberate, documented act to circumvent. It MUST NOT be
+    described as tamper-proof or as a security boundary.
 #>
 [CmdletBinding()]
 param()
 
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
+$script:PrAuthorAuthorizationPath = 'artifacts/pr_author_authorization.json'
+$script:PrAuthorAuthorizationTtlSeconds = 120
 
 function Get-PrContextArtifactExistence {
     <#
@@ -41,14 +62,126 @@ function Get-PrContextArtifactExistence {
     return [bool](Test-Path -LiteralPath $script:PrContextArtifactPath)
 }
 
+function Get-PrAuthorAuthorizationContent {
+    <#
+    .SYNOPSIS
+        Read the raw text of the authorization sentinel. Tests mock this function (read seam).
+    .DESCRIPTION
+        Returns the raw text content of artifacts/pr_author_authorization.json, or $null when the
+        sentinel file is absent. This is the injectable boundary for sentinel content in tests; no
+        test writes the sentinel file to disk.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:PrAuthorAuthorizationPath)) {
+        return $null
+    }
+
+    return (Get-Content -LiteralPath $script:PrAuthorAuthorizationPath -Raw)
+}
+
+function Get-CurrentDateTimeUtc {
+    <#
+    .SYNOPSIS
+        Return the current UTC time. Tests mock this function (clock seam) for time-travel scenarios.
+    .OUTPUTS
+        System.DateTime
+    #>
+    [CmdletBinding()]
+    [OutputType([datetime])]
+    param()
+
+    return [DateTime]::UtcNow
+}
+
+function Test-PrAuthorAuthorization {
+    <#
+    .SYNOPSIS
+        Validate the authorization sentinel and return a block-reason string, or $null when authorized.
+    .DESCRIPTION
+        Reads the sentinel via Get-PrAuthorAuthorizationContent and computes elapsed time via
+        Get-CurrentDateTimeUtc. Applies the decision order missing -> malformed -> invalid issuer ->
+        expired -> allow (spec FR-2 step 3):
+          - $null/empty contents              -> PR_AGENT_AUTHORIZATION_MISSING
+          - not valid JSON, or issued_at
+            missing/unparseable               -> PR_AGENT_AUTHORIZATION_MALFORMED
+          - issued_by != "pr-author"          -> PR_AGENT_AUTHORIZATION_INVALID
+          - elapsed seconds > ttl_seconds     -> PR_AGENT_AUTHORIZATION_EXPIRED
+          - all checks pass                   -> $null (allow)
+        The ttl_seconds value defaults to the named constant when absent from the sentinel.
+        This is a policy guardrail, not a cryptographic control; the sentinel is forgeable by any
+        actor with Write access to artifacts/.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    $contents = Get-PrAuthorAuthorizationContent
+
+    if ([string]::IsNullOrWhiteSpace($contents)) {
+        return "PR_AGENT_AUTHORIZATION_MISSING: ``$script:PrAuthorAuthorizationPath`` is absent or empty. The pr-author agent must write the authorization sentinel immediately before issuing ``gh pr create``/``gh pr edit --body*``."
+    }
+
+    try {
+        $sentinel = $contents | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` is not valid JSON. The pr-author agent must write a well-formed sentinel with ``issued_by``, ``issued_at``, and ``ttl_seconds``."
+    }
+
+    $issuedAtRaw = $sentinel.issued_at
+    if ([string]::IsNullOrWhiteSpace([string]$issuedAtRaw)) {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` is missing ``issued_at``. The pr-author agent must record a UTC ISO-8601 ``issued_at`` timestamp."
+    }
+
+    $issuedAt = [DateTime]::MinValue
+    $parsed = [DateTime]::TryParse(
+        [string]$issuedAtRaw,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal,
+        [ref] $issuedAt)
+    if (-not $parsed) {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` has an unparseable ``issued_at``. The pr-author agent must record a UTC ISO-8601 ``issued_at`` timestamp."
+    }
+
+    if ($sentinel.issued_by -ne 'pr-author') {
+        return "PR_AGENT_AUTHORIZATION_INVALID: ``$script:PrAuthorAuthorizationPath`` ``issued_by`` is not ``pr-author``. Only the pr-author agent may authorize PR creation or body edits."
+    }
+
+    $ttlSeconds = $script:PrAuthorAuthorizationTtlSeconds
+    if ($null -ne $sentinel.ttl_seconds) {
+        $candidateTtl = 0
+        if ([int]::TryParse([string]$sentinel.ttl_seconds, [ref] $candidateTtl)) {
+            $ttlSeconds = $candidateTtl
+        }
+    }
+
+    $elapsedSeconds = ((Get-CurrentDateTimeUtc) - $issuedAt).TotalSeconds
+    if ($elapsedSeconds -gt $ttlSeconds) {
+        return "PR_AGENT_AUTHORIZATION_EXPIRED: ``$script:PrAuthorAuthorizationPath`` issued $([math]::Round($elapsedSeconds)) s ago, exceeding the ${ttlSeconds}s TTL. The pr-author agent must write a fresh sentinel immediately before the ``gh`` command."
+    }
+
+    return $null
+}
+
 function Get-PrAuthorBypassReason {
     <#
     .SYNOPSIS
         Inspect the command text and return a block reason string, or $null when the command is allowed.
     .DESCRIPTION
-        Returns PR_AUTHOR_SKILL_BLOCKED when gh pr create is run with --body (inline) or with no body
-        flag at all. Returns PR_CONTEXT_MISSING when --body-file is present but the context artifact
-        does not exist on disk. Returns $null for all allowed patterns.
+        Returns PR_AUTHOR_SKILL_BLOCKED when gh pr create or gh pr edit is run with --body (inline,
+        no --body-file), or when gh pr create is run with no body flag at all. Returns
+        PR_CONTEXT_MISSING when --body-file is present but the context artifact
+        does not exist on disk. When --body-file is present and the context artifact exists, evaluates
+        the authorization sentinel via Test-PrAuthorAuthorization and returns its block reason
+        (PR_AGENT_AUTHORIZATION_*) when authorization fails. Returns $null for all allowed patterns.
+        Cases A, B, and C are evaluated first and unchanged; the sentinel check only extends the
+        previously-allowed --body-file-with-context path.
     .PARAMETER CommandText
         The Bash command text extracted from CLAUDE_TOOL_INPUT.
     .PARAMETER ContextExists
@@ -77,12 +210,13 @@ function Get-PrAuthorBypassReason {
     $hasBodyFile = $CommandText -match '(?i)--body-file\b'
     $hasInlineBody = $CommandText -match '(?i)--body(?!-file)\b'
 
-    if ($isPrCreate) {
-        # Case A: gh pr create with inline --body (not --body-file).
-        if ($hasInlineBody -and -not $hasBodyFile) {
-            return "PR_AUTHOR_SKILL_BLOCKED: ``gh pr create`` must use ``--body-file`` with a file produced by the pr-author skill from ``$script:PrContextArtifactPath``. Run ``mcp__drm-copilot__collect_pr_context`` to generate the context file, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
-        }
+    # Case A: gh pr create OR gh pr edit with inline --body (not --body-file). Evaluated before the
+    # gh pr edit no-body allow short-circuit so inline-body edits are blocked, not allowed.
+    if (($isPrCreate -or $isPrEdit) -and $hasInlineBody -and -not $hasBodyFile) {
+        return "PR_AUTHOR_SKILL_BLOCKED: ``gh pr create`` and ``gh pr edit`` must use ``--body-file`` with a file produced by the pr-author skill from ``$script:PrContextArtifactPath``. Run ``mcp__drm-copilot__collect_pr_context`` to generate the context file, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
+    }
 
+    if ($isPrCreate) {
         # Case B: gh pr create with no body flag at all.
         if (-not $hasInlineBody -and -not $hasBodyFile) {
             return "PR_AUTHOR_SKILL_BLOCKED: New PRs require ``--body-file``. Run ``mcp__drm-copilot__collect_pr_context`` to generate ``$script:PrContextArtifactPath``, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
@@ -101,6 +235,15 @@ function Get-PrAuthorBypassReason {
         return "PR_CONTEXT_MISSING: ``$script:PrContextArtifactPath`` is absent. Run ``mcp__drm-copilot__collect_pr_context`` before creating or editing the PR body."
     }
 
+    # Cases D/E/F and malformed: --body-file present and context artifact exists; verify the
+    # authorization sentinel. This extends, and does not replace, the previously-allowed path.
+    if ($hasBodyFile -and $ContextExists) {
+        $authorizationReason = Test-PrAuthorAuthorization
+        if ($authorizationReason) {
+            return $authorizationReason
+        }
+    }
+
     return $null
 }
 

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

@@ -141,6 +141,58 @@ function Test-HumanInteractionShape {
     return @{ Ok = $true; Message = $null }
 }
 
+function Invoke-RoutingContractValidation {
+    <#
+    .SYNOPSIS
+        Runs the authoritative Python routing-contract validator against the
+        on-disk checkpoint and reports whether it emitted errors.
+    .DESCRIPTION
+        Invokes the validator through an injectable subprocess scriptblock seam.
+        The default Invoker runs the authoritative Python CLI:
+          python -m scripts.dev_tools.validate_orchestration_artifacts \
+              orchestrator-state <CheckpointPath> --require-complete
+        Tests inject a mock scriptblock so no Python process runs. The function
+        does not reimplement routing logic; it delegates to the Python validator.
+
+        Returns a hashtable with keys:
+          - HasErrors:  $true when the validator reported a non-zero exit or
+                        produced any error text; $false when clean.
+          - ErrorText:  the validator's combined output text (empty on success).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $CheckpointPath,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $Invoker = {
+            param($Path)
+            $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
+                orchestrator-state $Path --require-complete 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()
+    }
+
+    # The validator signals a routing-contract failure either through a non-zero
+    # exit code or through emitted error text; either condition blocks DONE.
+    $hasErrors = ($exitCode -ne 0) -or (-not [string]::IsNullOrWhiteSpace($outputText))
+    return @{ HasErrors = $hasErrors; ErrorText = $outputText }
+}
+
 function Invoke-OrchestratorOutputValidation {
     <#
     .SYNOPSIS
@@ -154,7 +206,10 @@ function Invoke-OrchestratorOutputValidation {
     [OutputType([hashtable])]
     param(
         [string] $RawPayload,
-        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json',
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingInvoker
     )
 
     if ([string]::IsNullOrWhiteSpace($RawPayload)) {
@@ -217,6 +272,18 @@ function Invoke-OrchestratorOutputValidation {
         return @{ Ok = $false; Message = $hiResult.Message }
     }
 
+    # Delegate to the authoritative Python routing-contract validator. The
+    # optional RoutingInvoker seam lets tests inject a mock; the default seam
+    # produces the real subprocess call.
+    $routingArgs = @{ CheckpointPath = $CheckpointPath }
+    if ($PSBoundParameters.ContainsKey('RoutingInvoker') -and $null -ne $RoutingInvoker) {
+        $routingArgs['Invoker'] = $RoutingInvoker
+    }
+    $routingResult = Invoke-RoutingContractValidation @routingArgs
+    if ($routingResult.HasErrors) {
+        return @{ Ok = $false; Message = "ROUTING_CONTRACT_BLOCKED: $($routingResult.ErrorText)" }
+    }
+
     return @{ Ok = $true; Message = $null }
 }