@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.5

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner.ps1

@@ -0,0 +1,216 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks atomic-planner delegations when the target
+    feature folder does not yet contain spec.md and user-story.md.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the Agent (Task) tool. Reads
+    tool input JSON from the CLAUDE_TOOL_INPUT environment variable. Activates
+    only when subagent_type is 'atomic-planner'.
+
+    Feature folder resolution order:
+      1. Scan the prompt text for any path matching
+         docs/features/active/<token>, accepting both forward-slash and
+         backslash separators. The longest match wins; when it points at a
+         file (ends with .md), use its parent directory.
+      2. If no candidate was found in the prompt, read the feature-folder field
+         from artifacts/orchestration/orchestrator-state.json.
+      3. If neither yields a folder, block with a reason instructing the caller
+         to reference a feature folder explicitly.
+
+    Once the folder is resolved, the hook verifies that both spec.md and
+    user-story.md exist in that folder. If either is missing, the script blocks
+    with a reason naming the missing file(s) and instructing the orchestrator to
+    invoke prd-feature first.
+
+    Filesystem reads and orchestrator-state lookups go through wrapper functions
+    so tests can inject fakes without touching disk.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+
+function Get-PrdFeatureFileExistence {
+    <#
+    .SYNOPSIS
+        Wrapper around Test-Path for sibling-file existence checks. Tests mock this.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
+}
+
+function Get-PrdFeatureCheckpointFolder {
+    <#
+    .SYNOPSIS
+        Returns the feature-folder field from the orchestrator checkpoint, or
+        $null when the file or field is absent.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+    )
+
+    if (-not (Test-Path -LiteralPath $CheckpointPath -PathType Leaf)) {
+        return $null
+    }
+
+    try {
+        $raw = Get-Content -LiteralPath $CheckpointPath -Raw -ErrorAction Stop
+        $obj = $raw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return $null
+    }
+
+    if ($obj.PSObject.Properties.Name -contains 'feature-folder' -and $obj.'feature-folder') {
+        return [string]$obj.'feature-folder'
+    }
+    return $null
+}
+
+function Find-PrdFeatureFolderFromPrompt {
+    <#
+    .SYNOPSIS
+        Scans a prompt string for docs/features/active/<...> path tokens and
+        returns the longest unique match resolved to a folder path. Returns
+        $null when no match is found.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Prompt
+    )
+
+    if (-not $Prompt) {
+        return $null
+    }
+
+    # Allow forward or backslash separators inside the matched path token.
+    $pattern = 'docs[\\/]+features[\\/]+active[\\/]+[^\s"''`]+'
+    $matchList = [regex]::Matches($Prompt, $pattern)
+    if ($matchList.Count -eq 0) {
+        return $null
+    }
+
+    $unique = @{}
+    foreach ($m in $matchList) {
+        $normalized = ($m.Value -replace '\\', '/').TrimEnd('/')
+        $unique[$normalized] = $true
+    }
+
+    $candidates = @(@($unique.Keys) | Sort-Object -Property Length -Descending)
+    $best = $candidates[0]
+
+    # If the longest match ends in .md, treat it as a file and use its parent.
+    if ($best -match '\.md$') {
+        $parent = $best -replace '/[^/]+\.md$', ''
+        return $parent
+    }
+
+    return $best
+}
+
+function Get-PrdFeatureMissingFile {
+    <#
+    .SYNOPSIS
+        Returns the list of required files (spec.md, user-story.md) missing in
+        the target folder.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FeatureFolder
+    )
+
+    $required = @('spec.md', 'user-story.md')
+    [System.Collections.Generic.List[string]] $missing = [System.Collections.Generic.List[string]]::new()
+    foreach ($name in $required) {
+        $candidate = "$FeatureFolder/$name"
+        if (-not (Get-PrdFeatureFileExistence -Path $candidate)) {
+            $missing.Add($name)
+        }
+    }
+    return [string[]] $missing.ToArray()
+}
+
+function Invoke-PrdFeatureBeforePlannerDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        throw "enforce-prd-feature-before-planner hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $subagent = $toolInput.subagent_type
+    if (-not $subagent -or $subagent -ne 'atomic-planner') {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $prompt = [string]$toolInput.prompt
+    $folder = Find-PrdFeatureFolderFromPrompt -Prompt $prompt
+    if (-not $folder) {
+        $folder = Get-PrdFeatureCheckpointFolder
+    }
+
+    if (-not $folder) {
+        return [ordered]@{
+            decision = 'block'
+            reason   = "PRD_FEATURE_BLOCKED: atomic-planner delegation must reference a feature folder (either in the prompt or via orchestrator-state.json) so spec.md and user-story.md prerequisites can be verified."
+        }
+    }
+
+    $folderNormalized = ($folder -replace '\\', '/').TrimEnd('/')
+    $missing = Get-PrdFeatureMissingFile -FeatureFolder $folderNormalized
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $list = ($missing -join ', ')
+    return [ordered]@{
+        decision = 'block'
+        reason   = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list. Invoke the prd-feature subagent first."
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-PrdFeatureBeforePlannerDecision -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-promotion-mcp-only.ps1

@@ -8,12 +8,18 @@
     variable, inspects the attempted command text, and blocks direct promotion
     script execution that would bypass the repository's MCP-only promotion path.
 
-    Forbidden command tokens:
+    Forbidden command tokens (legacy promotion-script bypass):
       - new-potential-entry.ps1
       - new_potential_bug_entry
       - potential_to_issue
       - new_active_feature_folder
 
+    Forbidden gh-CLI patterns (raw GitHub issue creation bypass):
+      - gh issue create (with any flag suffix)
+      - gh issue new
+      - gh api against repos/<owner>/<repo>/issues with explicit POST method
+        (-X POST or --method POST)
+
     The hook is read-only: it inspects the attempted command and emits a JSON
     allow-or-block decision without mutating the command text.
 
@@ -23,12 +29,14 @@
 [CmdletBinding()]
 param()
 
-$script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drmCopilotExtension MCP promotion tools instead.'
+$script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drm-copilot MCP promotion tools instead.'
+
+$script:PromotionMcpOnlyGhIssueBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct GitHub issue creation via `gh` bypasses the approved drm-copilot MCP promotion path (`mcp__drm-copilot__new_potential_entry` -> `mcp__drm-copilot__potential_to_issue` -> `mcp__drm-copilot__new_active_feature_folder`). Use those MCP tools instead.'
 
 function Get-PromotionMcpOnlyBlockedReason {
     <#
     .SYNOPSIS
-        Return the canonical deny message for promotion-script bypass attempts.
+        Return the canonical deny message for legacy promotion-script bypass attempts.
     .OUTPUTS
         System.String
     #>
@@ -39,24 +47,40 @@ function Get-PromotionMcpOnlyBlockedReason {
     return $script:PromotionMcpOnlyBlockedReason
 }
 
-function Test-PromotionBypassToken {
+function Get-PromotionMcpOnlyGhIssueBlockedReason {
+    <#
+    .SYNOPSIS
+        Return the deny message for raw gh-CLI issue creation bypass attempts.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return $script:PromotionMcpOnlyGhIssueBlockedReason
+}
+
+function Get-PromotionBypassReason {
     <#
     .SYNOPSIS
-        Return $true when a Bash command contains a forbidden promotion token.
+        Inspect the command text and return the specific deny reason, or $null when allowed.
+    .DESCRIPTION
+        Returns the legacy promotion-script reason when any forbidden token is present.
+        Returns the gh-CLI issue creation reason when a forbidden gh pattern is matched.
+        Returns $null when the command is allowed.
     .PARAMETER CommandText
         The Bash command text extracted from CLAUDE_TOOL_INPUT.
     .OUTPUTS
-        System.Boolean
+        System.String or $null.
     #>
     [CmdletBinding()]
-    [OutputType([bool])]
+    [OutputType([string])]
     param(
         [Parameter(Mandatory)]
         [string] $CommandText
     )
 
-    # Inspect only the command text so the hook remains a narrow, non-mutating
-    # policy gate for direct promotion-script bypass attempts.
     $forbiddenTokens = @(
         'new-potential-entry.ps1',
         'new_potential_bug_entry',
@@ -66,27 +90,71 @@ function Test-PromotionBypassToken {
 
     foreach ($token in $forbiddenTokens) {
         if ($CommandText.IndexOf($token, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
-            return $true
+            return (Get-PromotionMcpOnlyBlockedReason)
         }
     }
 
-    return $false
+    # `gh issue create` and `gh issue new` are direct bypasses of the MCP
+    # promotion path. Tolerate any flags after the subcommand.
+    if ($CommandText -match '(?i)\bgh\s+issue\s+(?:create|new)\b') {
+        return (Get-PromotionMcpOnlyGhIssueBlockedReason)
+    }
+
+    # `gh api repos/<owner>/<repo>/issues` is a write surface only when an
+    # explicit POST method is supplied. `gh api` defaults to GET, so we only
+    # block when -X POST or --method POST is present, to avoid false positives
+    # on issue read operations. Use a single regex with lookaheads against the
+    # whole command string.
+    $ghApiIssuesPostPattern = '(?i)(?=.*\bgh\s+api\b)(?=.*repos/[^/\s]+/[^/\s]+/issues(?:\b|/[^/\s]*$))(?=.*(?:-X\s+POST|--method\s+POST))'
+    if ($CommandText -match $ghApiIssuesPostPattern) {
+        return (Get-PromotionMcpOnlyGhIssueBlockedReason)
+    }
+
+    return $null
+}
+
+function Test-PromotionBypassToken {
+    <#
+    .SYNOPSIS
+        Return $true when a Bash command contains a forbidden promotion bypass pattern.
+    .PARAMETER CommandText
+        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    return ($null -ne (Get-PromotionBypassReason -CommandText $CommandText))
 }
 
 function Get-PromotionMcpOnlyBlockDecision {
     <#
     .SYNOPSIS
         Construct the structured block decision for a forbidden Bash command.
+    .PARAMETER Reason
+        The specific deny reason to surface in the block decision. Defaults to the
+        legacy promotion-script reason for backward compatibility.
     .OUTPUTS
         System.Collections.Specialized.OrderedDictionary
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param()
+    param(
+        [string] $Reason
+    )
+
+    if (-not $Reason) {
+        $Reason = Get-PromotionMcpOnlyBlockedReason
+    }
 
     return [ordered]@{
         decision = 'block'
-        reason   = (Get-PromotionMcpOnlyBlockedReason)
+        reason   = $Reason
     }
 }
 
@@ -123,8 +191,9 @@ function Invoke-PromotionMcpOnlyDecision {
         return [ordered]@{ decision = 'allow' }
     }
 
-    if (Test-PromotionBypassToken -CommandText $commandText) {
-        return Get-PromotionMcpOnlyBlockDecision
+    $reason = Get-PromotionBypassReason -CommandText $commandText
+    if ($reason) {
+        return Get-PromotionMcpOnlyBlockDecision -Reason $reason
     }
 
     return [ordered]@{ decision = 'allow' }

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

@@ -262,7 +262,7 @@ function Invoke-ExecutorOutputValidation {
         return @{ Ok = $false; Message = 'atomic-executor hook: completion output must include an `AC Status Summary` section.' }
     }
 
-    $hasCommandEvidence = $agentOutput -match '(?i)(Commands Run|Command[s]?:|poetry run |npx |pwsh |git |mcp__drmCopilotExtension__)'
+    $hasCommandEvidence = $agentOutput -match '(?i)(Commands Run|Command[s]?:|poetry run |npx |pwsh |git |mcp__drm-copilot__)'
     $hasStatusEvidence = $agentOutput -match '(?i)\b(PASS|FAIL)\b'
     if (-not $hasCommandEvidence -or -not $hasStatusEvidence) {
         return @{ Ok = $false; Message = 'atomic-executor hook: completion output must report commands run and pass/fail status results.' }

package/resources/claude-customizations/.claude/hooks/validate-feature-review-coverage.ps1

@@ -158,6 +158,66 @@ function Get-LcovRepoCoverage {
     return [math]::Round(($totalHit * 100.0) / $totalFound, 2)
 }
 
+function Get-LcovBranchCoverage {
+    # Parses LCOV branch counters (BRF: branches found, BRH: branches hit) and returns a percent.
+    # LCOV emits one BRF/BRH line per source file in the report; we sum across the file to compute
+    # repo-wide branch coverage. Returns $null when the artifact is absent or when no branch
+    # information is recorded (BRF total = 0).
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    $totalFound = 0
+    $totalHit = 0
+    foreach ($line in $file.Lines) {
+        if ($line.StartsWith('BRF:')) {
+            $totalFound += [int]($line.Substring(4))
+        }
+        elseif ($line.StartsWith('BRH:')) {
+            $totalHit += [int]($line.Substring(4))
+        }
+    }
+    if ($totalFound -le 0) { return $null }
+    return [math]::Round(($totalHit * 100.0) / $totalFound, 2)
+}
+
+function Get-JacocoBranchCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Path)
+
+    $file = Get-ArtifactFileContent -Path $Path
+    if (-not $file.Exists) { return $null }
+
+    [xml]$doc = $file.Text
+    $counters = $doc.SelectNodes('//counter[@type="BRANCH"]')
+    if (-not $counters -or $counters.Count -eq 0) { return $null }
+
+    $missed = 0
+    $covered = 0
+    foreach ($counter in $counters) {
+        $missed += [int]$counter.missed
+        $covered += [int]$counter.covered
+    }
+    $total = $missed + $covered
+    if ($total -le 0) { return $null }
+    return [math]::Round(($covered * 100.0) / $total, 2)
+}
+
+function Get-LanguageBranchCoverage {
+    [OutputType([Nullable[double]])]
+    param([string]$Language)
+
+    switch ($Language) {
+        'TypeScript' { return Get-LcovBranchCoverage -Path 'coverage/lcov.info' }
+        'Python' { return Get-LcovBranchCoverage -Path 'artifacts/python/lcov.info' }
+        'PowerShell' { return Get-JacocoBranchCoverage -Path 'artifacts/pester/powershell-coverage.xml' }
+        'CSharp' { return Get-JacocoBranchCoverage -Path 'artifacts/csharp/coverage.xml' }
+    }
+    return $null
+}
+
 function Get-JacocoRepoCoverage {
     [OutputType([Nullable[double]])]
     param([string]$Path)
@@ -200,14 +260,15 @@ function Test-LanguageCoverageRow {
     param(
         [string]$AuditText,
         [string]$Language,
-        [Nullable[double]]$RepoWidePct
+        [Nullable[double]]$RepoWidePct,
+        [Nullable[double]]$BranchPct
     )
 
     $languageLabelMap = @{
         'TypeScript' = @('TypeScript', 'typescript')
         'Python'     = @('Python', 'python', 'pytest')
         'PowerShell' = @('PowerShell', 'powershell', 'pester')
-        'CSharp'     = @('C#', 'CSharp', 'csharp', '\.NET', 'dotnet')
+        'CSharp'     = @('C#', 'CSharp', 'csharp', '.NET', 'dotnet')
     }
 
     $labels = $languageLabelMap[$Language]
@@ -249,16 +310,24 @@ function Test-LanguageCoverageRow {
         }
     }
 
-    if ($null -ne $RepoWidePct -and $RepoWidePct -lt 80.0) {
+    if ($null -ne $RepoWidePct -and $RepoWidePct -lt 85.0) {
         $failLines = $coverageLines | Where-Object { $_ -match '\bFAIL\b' }
         if (-not $failLines -or $failLines.Count -eq 0) {
             return @{
                 Ok     = $false
-                Reason = ("{0} repo-wide coverage is {1}% (below the 80% floor) but the policy-audit contains no FAIL verdict on a coverage row for {0}." -f $Language, $RepoWidePct)
+                Reason = ("{0} repo-wide coverage is {1}% (below the 85% line coverage floor) but the policy-audit contains no FAIL verdict on a coverage row for {0}." -f $Language, $RepoWidePct)
             }
         }
     }
 
+    $BranchFloor = 75.0
+    if ($null -ne $BranchPct -and $BranchPct -lt $BranchFloor) {
+        return @{
+            Ok     = $false
+            Reason = ("{0} branch coverage is {1}% (below the 75% branch coverage floor); policy-audit must record FAIL on the corresponding coverage row." -f $Language, $BranchPct)
+        }
+    }
+
     return @{ Ok = $true; Reason = $null }
 }
 
@@ -362,7 +431,8 @@ function Invoke-FeatureReviewCoverageValidation {
     $coverageFailures = [System.Collections.Generic.List[string]]::new()
     foreach ($lang in $changedLanguages.Keys) {
         $repoPct = Get-LanguageRepoCoverage -Language $lang
-        $result = Test-LanguageCoverageRow -AuditText $policyAuditText -Language $lang -RepoWidePct $repoPct
+        $branchPct = Get-LanguageBranchCoverage -Language $lang
+        $result = Test-LanguageCoverageRow -AuditText $policyAuditText -Language $lang -RepoWidePct $repoPct -BranchPct $branchPct
         if (-not $result.Ok) {
             $coverageFailures.Add($result.Reason)
         }

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

@@ -57,6 +57,90 @@ function Get-CheckpointFileContent {
     return @{ Exists = $true; Content = $content }
 }
 
+function Test-HumanInteractionShape {
+    <#
+    .SYNOPSIS
+        Validates the optional human_interaction sub-object against the
+        invariants documented in .claude/rules/orchestrator-state.md and
+        enforced by scripts/dev_tools/validate_orchestrator_state.py,
+        enforcing the autonomous-execution mandate at the completion gate.
+    .DESCRIPTION
+        Returns a hashtable with keys:
+          - Ok:      $true if the field is absent or every requirement is resolved.
+          - Message: rejection message naming the first unresolved requirement; $null on success.
+        A null human_interaction (absent key) passes the gate. When present,
+        the requirements array is inspected and DONE is blocked when, in order:
+          - requirements is missing or non-array.
+          - any requirement has a missing/blank response.
+          - any requirement has a response outside the enum
+            (scope_change | exception | halt).
+          - any requirement has response == 'halt'.
+          - any requirement has response == 'exception' with a missing/empty
+            runbook_path, or a runbook_path whose file does not exist on disk
+            (existence is checked through the injected FileExistsCheck seam).
+        FileExistsCheck is an injectable scriptblock so tests can exercise the
+        existence branch without writing temporary files. It defaults to
+        Test-Path -PathType Leaf.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        $HumanInteraction,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FileExistsCheck = { param($Path) Test-Path -LiteralPath $Path -PathType Leaf }
+    )
+
+    if ($null -eq $HumanInteraction) {
+        return @{ Ok = $true; Message = $null }
+    }
+
+    $hiProps = @($HumanInteraction.PSObject.Properties.Name)
+    if ($hiProps -notcontains 'requirements') {
+        return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction' is present but 'requirements' array is missing." }
+    }
+
+    $requirements = @($HumanInteraction.requirements)
+    $allowedResponses = @('scope_change', 'exception', 'halt')
+
+    for ($i = 0; $i -lt $requirements.Count; $i++) {
+        $req = $requirements[$i]
+        $reqProps = @($req.PSObject.Properties.Name)
+
+        $response = $null
+        if ($reqProps -contains 'response') { $response = [string]$req.response }
+
+        if ([string]::IsNullOrWhiteSpace($response)) {
+            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has no resolved 'response'. Every unautomatable requirement must resolve to one of: scope_change, exception, halt." }
+        }
+
+        if ($allowedResponses -notcontains $response) {
+            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' value '$response' outside the allowed set (scope_change, exception, halt)." }
+        }
+
+        if ($response -eq 'halt') {
+            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'halt'; DONE is blocked while a halt is present." }
+        }
+
+        if ($response -eq 'exception') {
+            $runbookPath = $null
+            if ($reqProps -contains 'runbook_path') { $runbookPath = [string]$req.runbook_path }
+
+            if ([string]::IsNullOrWhiteSpace($runbookPath)) {
+                return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'exception' but no non-empty 'runbook_path'. A permitted exception requires a runbook." }
+            }
+
+            if (-not (& $FileExistsCheck $runbookPath)) {
+                return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' references runbook_path '$runbookPath' but no file exists at that location." }
+            }
+        }
+    }
+
+    return @{ Ok = $true; Message = $null }
+}
+
 function Invoke-OrchestratorOutputValidation {
     <#
     .SYNOPSIS
@@ -124,6 +208,15 @@ function Invoke-OrchestratorOutputValidation {
         return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' has an empty 'objective' field; orchestrator must record the active objective." }
     }
 
+    $humanInteraction = $null
+    if ($checkpointProps -contains 'human_interaction') {
+        $humanInteraction = $checkpoint.human_interaction
+    }
+    $hiResult = Test-HumanInteractionShape -HumanInteraction $humanInteraction
+    if (-not $hiResult.Ok) {
+        return @{ Ok = $false; Message = $hiResult.Message }
+    }
+
     return @{ Ok = $true; Message = $null }
 }