@danmoisan/drm-copilot-mcp 1.0.24 → 1.0.27

package/resources/claude-customizations/.claude/hooks/enforce-mermaid-validation.ps1

@@ -0,0 +1,390 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook for Claude Code that blocks Mermaid diagrams with named structural defects.
+
+.DESCRIPTION
+    This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
+    operation. It reads the tool input from the CLAUDE_TOOL_INPUT environment variable
+    (JSON with 'file_path' plus 'content' for Write, or 'old_string'/'new_string' for
+    Edit) and applies two independent gates:
+
+      1. Syntax gate. On a Write of a '.mmd'/'.mermaid' file, the whole file is one
+         diagram. On a Write of a Markdown file, every fenced ```mermaid block is a
+         diagram. Each diagram is validated by .claude/lib/mermaid/MermaidValidation.psm1
+         and a defect of a checked class produces a deny naming the class and the line.
+      2. Managed-diagram gate. A '.mmd'/'.mermaid' file whose ON-DISK frontmatter carries
+         'id:' is connected to the Mermaid Chart sync workflow and must not be hand
+         edited. This is a property of the target file rather than of the payload, so it
+         applies to Edit as well as Write, and the opt-out marker never suppresses it.
+
+    The gate's contract is "rejects the named defect classes", never "proves validity".
+    Blocking a valid diagram is worse than missing an invalid one, so the hook declines
+    to judge rather than rejecting whenever it cannot classify content confidently:
+
+      - empty, absent, or unparseable CLAUDE_TOOL_INPUT: allow;
+      - missing 'file_path', or a path outside the '.mmd'/'.mermaid'/Markdown scope: allow;
+      - the validation module absent from disk: allow;
+      - an Edit payload (the syntax check needs the whole file, which an
+        old_string/new_string fragment cannot supply): allow;
+      - a Markdown file carrying no ```mermaid fence: allow;
+      - a ```mermaid fence nested inside another open fence, which is documentation
+        showing example Mermaid rather than a diagram: skip that block;
+      - a fence immediately preceded by '<!-- mermaid-validator: ignore -->': skip that
+        block, and only that block.
+
+    DELIBERATE DIVERGENCE FROM enforce-evidence-locations.ps1: that hook throws on
+    malformed CLAUDE_TOOL_INPUT JSON and its entry point exits 1. This hook allows
+    instead. The difference is intentional and must not be "fixed" into a hard failure:
+    a content gate that hard-fails on input it cannot parse converts an unparseable
+    payload into a blocked write, which is the false-positive failure mode this feature
+    exists to avoid. The evidence-location hook gates a path, which is always parseable
+    when present; this hook gates content, which is not.
+
+    The extension scope check runs before any content scan, so a write outside the
+    Mermaid scope pays only the JSON parse.
+
+.NOTES
+    Compatible with PowerShell 7+.
+    This script must not modify any state; it is a read-only validation gate.
+    It emits compact hookSpecificOutput JSON on stdout and exits 0 in every case,
+    never a non-zero exit and never the {"decision":"block"} shape.
+    It invokes no Python and starts no subprocess.
+#>
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+
+$script:MermaidModulePath = Join-Path -Path $PSScriptRoot -ChildPath '../lib/mermaid/MermaidValidation.psm1'
+$script:MermaidSkillPointer = 'See .claude/skills/mermaid-diagram/SKILL.md.'
+$script:MermaidSyncPointer = 'Change it through the Mermaid Chart sync workflow in VS Code (Mermaid Chart extension: Sync Diagram with Mermaid, then Review Mermaid Sync) and pull the synced result instead of hand-editing. See .claude/rules/mermaid.md.'
+
+function Import-MermaidValidationModule {
+    <#
+    .SYNOPSIS
+        Imports the validation module, returning $false when it is absent.
+    .DESCRIPTION
+        A consumer repository that receives this hook without the library must not be
+        bricked, so a missing module fails open rather than throwing.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:MermaidModulePath -PathType Leaf)) { return $false }
+
+    try {
+        Import-Module -Name $script:MermaidModulePath -Force -ErrorAction Stop
+    } catch {
+        return $false
+    }
+
+    return $true
+}
+
+function Get-MermaidOnDiskContent {
+    <#
+    .SYNOPSIS
+        Reads the current on-disk content of a target file, or $null when unavailable.
+    .DESCRIPTION
+        The named wrapper seam for the managed-diagram gate. Pester mocks this function
+        rather than the filesystem, so no test needs a temporary file.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Path
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $null }
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+
+    try {
+        return [string](Get-Content -LiteralPath $Path -Raw -ErrorAction Stop)
+    } catch {
+        return $null
+    }
+}
+
+function Get-MermaidToolInputField {
+    <#
+    .SYNOPSIS
+        Reads one field from the parsed tool input, or $null when it is absent.
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $InputObject,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    if ($null -eq $InputObject) { return $null }
+
+    $property = $InputObject.PSObject.Properties[$Name]
+    if ($null -eq $property) { return $null }
+
+    return $property.Value
+}
+
+function Test-MermaidDiagramFilePath {
+    <#
+    .SYNOPSIS
+        Returns $true when the path names a standalone Mermaid diagram file.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $FilePath
+    )
+
+    $normalized = $FilePath -replace '\\', '/'
+    return [bool]($normalized -imatch '\.(mmd|mermaid)$')
+}
+
+function Test-MermaidMarkdownFilePath {
+    <#
+    .SYNOPSIS
+        Returns $true when the path names a Markdown file that may carry a fence.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $FilePath
+    )
+
+    $normalized = $FilePath -replace '\\', '/'
+    return [bool]($normalized -imatch '\.(md|markdown)$')
+}
+
+function Get-MermaidAllowDecision {
+    <#
+    .SYNOPSIS
+        Builds the explicit-allow decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-MermaidDenyDecision {
+    <#
+    .SYNOPSIS
+        Builds a deny decision carrying the supplied token-prefixed reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Get-MermaidValidationBlockedReason {
+    <#
+    .SYNOPSIS
+        Formats the syntax-deny reason from a structured validation result.
+    .DESCRIPTION
+        The reason names the defect class, the line number, and the corrective pointer,
+        because a deny a reader cannot act on is indistinguishable from a broken gate.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath,
+
+        [Parameter(Mandatory)]
+        $Result,
+
+        [AllowEmptyString()]
+        [string] $Location = ''
+    )
+
+    $finding = @($Result.Findings)[0]
+    $declared = if ([string]::IsNullOrWhiteSpace([string]$Result.DiagramType)) { 'no diagram type' } else { "'$($Result.DiagramType)'" }
+    $where = if ([string]::IsNullOrWhiteSpace($Location)) { '' } else { " ($Location)" }
+
+    return "MERMAID_VALIDATION_BLOCKED: '$FilePath'$where declares $declared and has a Mermaid syntax defect: $($finding.Class) at line $($finding.Line): $($finding.Message). $script:MermaidSkillPointer"
+}
+
+function Get-MermaidManagedDiagramBlockedReason {
+    <#
+    .SYNOPSIS
+        Formats the managed-diagram deny reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath
+    )
+
+    return "MERMAID_MANAGED_DIAGRAM_BLOCKED: '$FilePath' is a Mermaid Chart-managed diagram: its on-disk frontmatter carries an 'id:' marker, so a hand-edit would be overwritten by the next sync. $script:MermaidSyncPointer"
+}
+
+function Get-MermaidMarkdownBlockDecision {
+    <#
+    .SYNOPSIS
+        Validates every eligible fenced block of a Markdown payload.
+    .DESCRIPTION
+        Returns a deny decision for the first block carrying a defect, or $null when
+        every block is either accepted or skipped. A nested block is documentation
+        showing example Mermaid; an opted-out block carries the documented marker.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath,
+
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Content
+    )
+
+    foreach ($block in @(Get-MermaidFenceBlock -Content $Content)) {
+        if ($block.IsNested -or $block.IsOptedOut) { continue }
+
+        $result = Test-MermaidDiagram -Content $block.Content -LineOffset ($block.BodyStartLine - 1)
+        if ($result.Verdict -ne 'Invalid') { continue }
+
+        $location = "the mermaid fence opening at line $($block.StartLine)"
+        return Get-MermaidDenyDecision -Reason (Get-MermaidValidationBlockedReason -FilePath $FilePath -Result $result -Location $location)
+    }
+
+    return $null
+}
+
+function Invoke-MermaidValidationDecision {
+    <#
+    .SYNOPSIS
+        Parses the Claude Code tool-input JSON and returns the allow-or-deny decision.
+    .DESCRIPTION
+        The pure decision function, separated from the thin entry point so Pester
+        exercises the logic directly. Returns $null when the call is none of this hook's
+        business (out of scope, unparseable, or a Markdown file with no fence), which the
+        entry point treats as a silent allow.
+    .PARAMETER ToolInputRaw
+        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $ToolInputRaw
+    )
+
+    if ([string]::IsNullOrWhiteSpace($ToolInputRaw)) { return $null }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        # Fail open. See the DELIBERATE DIVERGENCE note in this file's header before
+        # changing this to a throw.
+        return $null
+    }
+
+    $filePath = [string](Get-MermaidToolInputField -InputObject $toolInput -Name 'file_path')
+    if ([string]::IsNullOrWhiteSpace($filePath)) { return $null }
+
+    # Scope check first: a write outside the Mermaid scope pays only the JSON parse.
+    $isDiagramFile = Test-MermaidDiagramFilePath -FilePath $filePath
+    $isMarkdownFile = Test-MermaidMarkdownFilePath -FilePath $filePath
+    if (-not ($isDiagramFile -or $isMarkdownFile)) { return $null }
+
+    if (-not (Import-MermaidValidationModule)) { return $null }
+
+    # Managed-diagram gate: a property of the target file, so Edit is covered without
+    # reconstructing the post-edit content, and the opt-out marker cannot suppress it.
+    if ($isDiagramFile) {
+        $onDisk = Get-MermaidOnDiskContent -Path $filePath
+        if (-not [string]::IsNullOrWhiteSpace([string]$onDisk) -and (Test-MermaidManagedDiagram -Content ([string]$onDisk))) {
+            return Get-MermaidDenyDecision -Reason (Get-MermaidManagedDiagramBlockedReason -FilePath $filePath)
+        }
+    }
+
+    $content = Get-MermaidToolInputField -InputObject $toolInput -Name 'content'
+    if ($null -eq $content) {
+        # Edit payload: old_string/new_string is a fragment, not the resulting file, so
+        # the syntax check cannot run. The next Write catches a regression.
+        return Get-MermaidAllowDecision
+    }
+
+    if ($isDiagramFile) {
+        $result = Test-MermaidDiagram -Content ([string]$content)
+        if ($result.Verdict -eq 'Invalid') {
+            return Get-MermaidDenyDecision -Reason (Get-MermaidValidationBlockedReason -FilePath $filePath -Result $result)
+        }
+
+        return Get-MermaidAllowDecision
+    }
+
+    $blocks = @(Get-MermaidFenceBlock -Content ([string]$content))
+    if ($blocks.Count -eq 0) { return $null }
+
+    $decision = Get-MermaidMarkdownBlockDecision -FilePath $filePath -Content ([string]$content)
+    if ($null -ne $decision) { return $decision }
+
+    return Get-MermaidAllowDecision
+}
+
+function Invoke-MermaidValidationEntryPoint {
+    <#
+    .SYNOPSIS
+        Thin entry point: writes the decision JSON to stdout and nothing else.
+    .DESCRIPTION
+        The function emits only the JSON, and the caller exits 0 unconditionally. An
+        entry point that also returned a status code would place that code in the same
+        output stream as the JSON, so the caller would consume the JSON instead of
+        printing it and the decision would never reach Claude Code.
+    .PARAMETER ToolInputRaw
+        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $ToolInputRaw = $env:CLAUDE_TOOL_INPUT
+    )
+
+    $decision = Invoke-MermaidValidationDecision -ToolInputRaw $ToolInputRaw
+    if ($null -eq $decision) { return }
+
+    $decision | ConvertTo-Json -Compress -Depth 5
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+Invoke-MermaidValidationEntryPoint -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+
+# Exit 0 on allow and on deny alike: the decision travels in the JSON, never in the
+# exit code.
+exit 0

package/resources/claude-customizations/.claude/hooks/validate-discovery-artifact-gate.ps1

@@ -28,8 +28,10 @@
     captured output.
 
 .NOTES
-    Compatible with PowerShell 7+. Read-only validation gate; the validator
-    subprocess is the only external process invoked.
+    Requires PowerShell 7.4+ (the shared validation module uses
+    `Test-Json -SchemaFile` Draft 2020-12 support). Read-only validation gate that
+    invokes NO external process: validation runs in-process through
+    `.claude/lib/discovery-validation/DiscoveryValidation.psm1` (issue #475).
 #>
 [CmdletBinding()]
 param()
@@ -37,11 +39,23 @@ param()
 function Invoke-DiscoveryValidatorExe {
     <#
     .SYNOPSIS
-        Wrapper around the discovery-artifact validator CLI. Mockable seam.
+        Wrapper around the discovery-artifact validator. Mockable seam.
     .DESCRIPTION
-        Invokes `python -m scripts.dev_tools.validate_discovery_artifacts` with
-        the supplied arguments and captures both stdout and stderr. Tests mock
-        this function directly; production code must never mock `python`.
+        Delegates to the portable PowerShell implementation in
+        `.claude/lib/discovery-validation/DiscoveryValidation.psm1`, keeping this
+        function's name, its `-ValidatorArgs <string[]>` parameter, and its
+        `@{ ExitCode; Output }` return shape unchanged so existing mocks and
+        `Should -Invoke` assertions continue to bind.
+
+        This no longer invokes a Python interpreter (issue #475). The `.claude/**`
+        payload ships to destinations with no guaranteed Python, Poetry, or
+        `scripts/dev_tools`, where the previous `python -m ...` call failed
+        obscurely or blocked every operation.
+
+        Success is SILENT by contract: a passing validation returns `ExitCode = 0`
+        with an EMPTY `Output`. The caller denies on a non-zero exit code OR on
+        non-empty output, so any success chatter here would deny a passing
+        validation (defect D-2).
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
@@ -50,8 +64,14 @@ function Invoke-DiscoveryValidatorExe {
         [string[]] $ValidatorArgs
     )
 
-    $output = & python -m scripts.dev_tools.validate_discovery_artifacts @ValidatorArgs 2>&1
-    return @{ ExitCode = $LASTEXITCODE; Output = ($output | Out-String).Trim() }
+    $modulePath = Join-Path -Path $PSScriptRoot `
+        -ChildPath '../lib/discovery-validation/DiscoveryValidation.psm1'
+    if (-not (Test-Path -LiteralPath $modulePath -PathType Leaf)) {
+        return @{ ExitCode = 1; Output = "Discovery-validation module not found: $modulePath" }
+    }
+
+    Import-Module -Name $modulePath -Force -ErrorAction Stop
+    return Invoke-DiscoveryArtifactValidation -ValidatorArgs $ValidatorArgs
 }
 
 function Get-DiscoveryArtifactType {

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

@@ -149,31 +149,94 @@ function Test-HumanInteractionShape {
     return @{ Ok = $true; Message = $null }
 }
 
+function Test-OrchestratorCheckpointStructure {
+    <#
+    .SYNOPSIS
+        Type-scoped structural check for the epic and parallel checkpoint types.
+    .DESCRIPTION
+        PD-3 implementation. The Python reference exposes no validation surface for
+        `epic-orchestrator-state` or `parallel-orchestrator-state` under this hook's
+        flag pair: argparse rejects the pair and exits 2 without running a single
+        check, so parity is UNDEFINED in this region. Rather than inherit an
+        undefined behavior, this hook defines it: the checkpoint must exist, parse
+        as JSON, and have an object root. That is the largest assertion that holds
+        for every checkpoint type without importing a schema this hook does not own.
+
+        Deliberately NOT applied here:
+          - the standard-checkpoint REQUIRED_STATE_KEYS presence block, whose key
+            set belongs to the standard checkpoint and would produce false
+            ROUTING_CONTRACT_BLOCKED verdicts against a well-formed epic or
+            parallel checkpoint (defect D-1),
+          - the model-routing gate, whose receipts live on the standard checkpoint.
+
+        The check fails closed: a missing file, unreadable content, invalid JSON, or
+        a non-object root all yield ExitCode 1 with the load error as Output.
+    .PARAMETER CheckpointPath
+        The path to the 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
+    )
+
+    # Get-OrchestratorStateCheckpoint already implements exactly the three
+    # structural conditions (exists, parses, object root) and reports each as a
+    # fail-closed Error string, so the structural leg reuses it rather than
+    # duplicating the load contract.
+    $loaded = Get-OrchestratorStateCheckpoint -CheckpointPath $CheckpointPath
+    if (-not $loaded.Ok) {
+        return @{ ExitCode = 1; Output = $loaded.Error }
+    }
+
+    return @{ ExitCode = 0; Output = '' }
+}
+
 function Invoke-RoutingContractValidation {
     <#
     .SYNOPSIS
-        Runs the authoritative Python routing-contract validator against the
-        on-disk checkpoint and reports whether it emitted errors.
+        Runs the portable routing-contract validation 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 \
-              <ArtifactType> <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.
-        ArtifactType defaults to 'orchestrator-state' so the default invocation
-        string is unchanged for every existing caller of this hook.
+        Invokes the validation through an injectable scriptblock seam. As of issue
+        #475 the default Invoker names no interpreter and starts no subprocess: the
+        portable PowerShell path is the ONLY path, so the hook behaves identically
+        in this repository and in every destination that received only the
+        pushed-down `.claude` pack. The former capability-detection probe and the
+        interpreter-subprocess leg it guarded are both gone.
+
+        The default Invoker dispatches on ArtifactType:
+
+          orchestrator-state
+              the COMPLETE-PARITY completion validation
+              (Test-OrchestratorStateCompletionReadiness), a row-by-row port of the
+              Python call surface `--require-complete --require-model-routing`.
+
+          epic-orchestrator-state, parallel-orchestrator-state
+              the type-scoped structural check
+              (Test-OrchestratorCheckpointStructure): exists, parses as JSON,
+              object root. PD-3: this is DEFINED behavior in a region where Python
+              parity is UNDEFINED (argparse exit 2, zero checks run). It is a
+              design decision, not a deferral. The standard-checkpoint
+              REQUIRED_STATE_KEYS block and the model-routing gate are deliberately
+              not applied, which is the D-1 fix.
+
+          anything else
+              fail closed, naming the unsupported type. An unrecognized type must
+              never read as a clean pass.
+
+        ArtifactType defaults to 'orchestrator-state' so every existing caller of
+        this hook keeps its current behavior.
 
         Returns a hashtable with keys:
-          - HasErrors:  $true only when the validator reported a non-zero exit
+          - HasErrors:  $true only when the validation reported a non-zero exit
                         code; $false when it exited 0. The exit code is the sole
-                        discriminator, because the validator prints its success
-                        line to stdout on a clean pass and the default Invoker
-                        captures with 2>&1, so output text is present on success.
-          - ErrorText:  the validator's combined captured output text, carried
-                        through unchanged: the error lines on a failure, and the
-                        success line (Python CLI) or empty (portable fallback)
-                        on a clean pass.
+                        discriminator.
+          - ErrorText:  the validation's output text, carried through unchanged:
+                        the error lines on a failure, empty on a clean pass.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
@@ -187,29 +250,36 @@ function Invoke-RoutingContractValidation {
         [Parameter(Mandatory = $false)]
         [scriptblock] $Invoker = {
             param($Path, $Type)
-            # 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)
+            switch ($Type) {
+                'orchestrator-state' {
+                    # 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
+                    }
                 }
-            } 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
+                { $_ -in @('epic-orchestrator-state', 'parallel-orchestrator-state') } {
+                    # PD-3: defined fail-closed structural behavior in an
+                    # undefined-parity region. See Test-OrchestratorCheckpointStructure.
+                    $structural = Test-OrchestratorCheckpointStructure -CheckpointPath $Path
+                    [pscustomobject]@{
+                        ExitCode = $structural.ExitCode
+                        Output   = $structural.Output
+                    }
                 }
-                $portable = Test-OrchestratorStateCompletionReadiness -CheckpointPath $Path
-                [pscustomobject]@{
-                    ExitCode = $portable.ExitCode
-                    Output   = $portable.Output
+                default {
+                    # Fail closed on an unwired type: an unrecognized artifact type is
+                    # not a clean pass.
+                    [pscustomobject]@{
+                        ExitCode = 1
+                        Output   = "orchestrator hook: unsupported artifact type '$Type'; no validation surface is wired for it. Supported types: orchestrator-state, epic-orchestrator-state, parallel-orchestrator-state."
+                    }
                 }
             }
         }
@@ -225,10 +295,10 @@ function Invoke-RoutingContractValidation {
         $outputText = ([string]$result.Output).Trim()
     }
 
-    # The exit code is the complete failure discriminator: the validator prints every
-    # error to stderr and returns non-zero, and prints its success line to stdout and
-    # returns 0. Because the default invoker captures with 2>&1, the success line lands
-    # in $outputText on a clean pass, so output text must not influence this decision.
+    # The exit code is the complete failure discriminator: every dispatch leg
+    # returns a non-zero ExitCode with its error text on failure and ExitCode 0
+    # with empty Output on a clean pass, so output text must not influence this
+    # decision.
     $hasErrors = ($exitCode -ne 0)
     return @{ HasErrors = $hasErrors; ErrorText = $outputText }
 }
@@ -313,9 +383,10 @@ 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.
+    # Delegate to the portable routing-contract validation, dispatched on
+    # ArtifactType. The optional RoutingInvoker seam lets tests inject a mock; the
+    # default seam runs the in-process PowerShell validation and starts no
+    # subprocess.
     $routingArgs = @{ CheckpointPath = $CheckpointPath; ArtifactType = $ArtifactType }
     if ($PSBoundParameters.ContainsKey('RoutingInvoker') -and $null -ne $RoutingInvoker) {
         $routingArgs['Invoker'] = $RoutingInvoker