@danmoisan/drm-copilot-mcp 1.1.21 → 1.1.23

package/resources/claude-customizations/.claude/hooks/enforce-parallel-worktree-removal-gate.ps1

@@ -46,6 +46,8 @@ try { Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWor
 try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
 try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
 
+# Shared recorded-path matcher and main-checkout-root seam (issue #995).
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunRecordPath.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunRecordPath.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
@@ -170,7 +172,10 @@ function Find-ParallelWorktreeItemRecord {
         Name of the record array to scan. Defaults to 'items', the parallel
         checkpoint's array, so every existing caller is unchanged; the epic branch
         added for issue #688 passes 'features'. Parameterized rather than duplicated
-        so both topologies share one path-normalization implementation.
+        so both topologies share one path-comparison implementation.
+    .PARAMETER BaseRoot
+        Optional. The roots a relative recorded worktree_path is joined to (issue #995).
+        With none, a relative record matches nothing.
     .OUTPUTS
         System.Object or $null
     #>
@@ -183,7 +188,11 @@ function Find-ParallelWorktreeItemRecord {
         [string] $WorktreePath,
 
         [ValidateNotNullOrEmpty()]
-        [string] $RecordArrayName = 'items'
+        [string] $RecordArrayName = 'items',
+
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [string[]] $BaseRoot = @()
     )
 
     if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
@@ -194,17 +203,14 @@ function Find-ParallelWorktreeItemRecord {
         return $null
     }
 
-    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
-
-    # Scan every recorded item for a worktree_path that matches the removal target;
-    # path separators are normalized so Windows- and POSIX-style paths compare equal.
+    # Scan every recorded item for a worktree_path that names the removal target through
+    # the shared matcher (separator style, trailing slash, case rule, relative join).
     foreach ($item in @($Checkpoint.$RecordArrayName)) {
         $itemProps = @($item.PSObject.Properties.Name)
         if ($itemProps -notcontains 'worktree_path') {
             continue
         }
-        $normalizedItemPath = (([string]$item.worktree_path) -replace '\\', '/').TrimEnd('/')
-        if ($normalizedItemPath -eq $normalizedTarget) {
+        if (Test-WorktreeRunRecordedPathMatchesTarget -RecordedPath ([string]$item.worktree_path) -TargetPath $WorktreePath -BaseRoot $BaseRoot) {
             return $item
         }
     }
@@ -353,8 +359,13 @@ function Get-ParallelWorktreeRemovalTargetDenial {
         }
     }
     $checkpoint = $parallelRead.Checkpoint
+    # A relative record is joined to the main checkout root and to the root holding the
+    # checkpoint read (issue #995); the main root is derived once per target.
+    $mainRoot = Get-WorktreeRunMainCheckoutRoot -SessionRoot (Get-Location).Path
+    $parallelBaseRoot = Get-WorktreeRunRecordBaseRoot -MainRoot $mainRoot -Read $parallelRead
+    $epicBaseRoot = Get-WorktreeRunRecordBaseRoot -MainRoot $mainRoot -Read $epicRead
 
-    $itemRecord = Find-ParallelWorktreeItemRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
+    $itemRecord = Find-ParallelWorktreeItemRecord -Checkpoint $checkpoint -WorktreePath $worktreePath -BaseRoot $parallelBaseRoot
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $itemRecord) {
         return $null
     }
@@ -371,7 +382,7 @@ function Get-ParallelWorktreeRemovalTargetDenial {
     # $null, which yields no record, which is not allowed.
     $epicCheckpoint = $epicRead.Checkpoint
 
-    $featureRecord = Find-ParallelWorktreeItemRecord -Checkpoint $epicCheckpoint -WorktreePath $worktreePath -RecordArrayName 'features'
+    $featureRecord = Find-ParallelWorktreeItemRecord -Checkpoint $epicCheckpoint -WorktreePath $worktreePath -RecordArrayName 'features' -BaseRoot $epicBaseRoot
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $featureRecord) {
         return $null
     }
@@ -386,7 +397,7 @@ function Get-ParallelWorktreeRemovalTargetDenial {
     # reaches the unchanged deny below. This gate defines only the parallel checkpoint
     # seam and has no epic-checkpoint seam, so its exclusion covers the items array
     # only; the epic gate covers the features array with its own exclusion.
-    if (-not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $checkpoint -RecordArrayName 'items' -WorktreePath $worktreePath) -and
+    if (-not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $checkpoint -RecordArrayName 'items' -WorktreePath $worktreePath -BaseRoot $parallelBaseRoot) -and
         (Test-CleanupWorktreeManifestAuthorizesRemoval -WorktreePath $worktreePath)) {
         return $null
     }

package/resources/claude-customizations/.claude/hooks/enforce-powershell-batch-budget.ps1

@@ -61,7 +61,7 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 
 
 try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
-try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-batch-budget-route.ps1' -ErrorRecord $_ }
+$script:PowerShellBatchBudgetRouteImportFailure = $null; try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { $script:PowerShellBatchBudgetRouteImportFailure = 'enforce-batch-budget-route.ps1' }
 
 function Test-PowerShellBatchBudgetPathInRoot {
     <#
@@ -371,6 +371,7 @@ function Invoke-PowerShellBatchBudgetHook {
     if ($normalized -notmatch '\.(ps1|psm1|psd1)$') {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
+    if ($script:PowerShellBatchBudgetRouteImportFailure) { return Get-PowerShellBatchBudgetBlockDecision -Reason "POWERSHELL_LARGE_PATH_REQUIRED: the route helper '$($script:PowerShellBatchBudgetRouteImportFailure)' failed to load, so the batch budget for '$normalized' cannot be evaluated; the gate fails closed." }
 
     $stateDir = Join-Path -Path $Root -ChildPath '.claude/state'
 

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

@@ -11,6 +11,7 @@
 
       - git log ...            and git rev-parse ...        (no git global option)
       - gh pr create ...       and gh pr edit ...           (no gh global option)
+      - gh pr view <N> --json closingIssuesReferences,body  (exactly these six tokens, issue #989)
       - sha256sum artifacts/pr_body_<N>.md                  (only as the whole command)
       - date -u [+<format>]                                 (only as the whole command)
 
@@ -41,7 +42,7 @@ $script:PrAuthorAllowlistWrapperWords = @(
     'sh', 'bash', 'zsh', 'dash', 'ksh', 'pwsh', 'powershell', 'eval', 'xargs',
     'env', 'timeout', 'time', 'command', 'nohup'
 )
-$script:PrAuthorAllowlistFormText = 'git log, git rev-parse, gh pr create, gh pr edit, sha256sum artifacts/pr_body_<N>.md, date -u [+<format>]'
+$script:PrAuthorAllowlistFormText = 'git log, git rev-parse, gh pr create, gh pr edit, gh pr view <N> --json closingIssuesReferences,body, sha256sum artifacts/pr_body_<N>.md, date -u [+<format>]'
 
 function Test-PrAuthorAllowlistForm {
     <#
@@ -69,7 +70,12 @@ function Test-PrAuthorAllowlistForm {
             return ($Token.Count -ge 2 -and @('log', 'rev-parse') -ccontains $Token[1])
         }
         'gh' {
-            return ($Token.Count -ge 3 -and $Token[1] -ceq 'pr' -and @('create', 'edit') -ccontains $Token[2])
+            if ($Token.Count -ge 3 -and $Token[1] -ceq 'pr' -and @('create', 'edit') -ccontains $Token[2]) {
+                return $true
+            }
+            # The read-only closing-reference verification form, matched exactly (issue #989).
+            return ($Token.Count -eq 6 -and $Token[1] -ceq 'pr' -and $Token[2] -ceq 'view' -and $Token[3] -cmatch '^\d+$' -and
+                $Token[4] -ceq '--json' -and $Token[5] -ceq 'closingIssuesReferences,body')
         }
         'sha256sum' {
             return ($IsWholeCommand -and $Token.Count -eq 2 -and $Token[1] -cmatch '^artifacts/pr_body_\d+\.md$')

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

@@ -27,9 +27,10 @@
 
 .NOTES
     Compatible with PowerShell 7+. Dependencies are in-repository only: the command parsers
-    and worktree-resolution modules loaded below, and the artifact-root and docs-only siblings.
-    No PowerShell Gallery module is required.
-    The docs-only sibling runs the git executable at call time (issue #901).
+    and worktree-resolution modules loaded below, and the artifact-root, docs-only, and
+    current-branch siblings. No PowerShell Gallery module is required.
+    The docs-only sibling runs the git executable at call time (issue #901), and so does the
+    current-branch sibling when a call carries no target signal (issue #989).
 #>
 [CmdletBinding()]
 param()
@@ -56,6 +57,8 @@ Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeRead
 . (Join-Path $PSScriptRoot 'enforce-pr-author-skill.artifact-root.ps1')
 # Docs-only exemption from the orchestrator-state preflight (issue #901).
 . (Join-Path $PSScriptRoot 'enforce-pr-author-skill.docs-only.ps1')
+# Current-branch target derivation and the no-target guidance text (issue #989).
+. (Join-Path $PSScriptRoot 'enforce-pr-author-skill.current-branch.ps1')
 
 function Resolve-PrAuthorWorktreeTarget {
     <#
@@ -67,7 +70,8 @@ function Resolve-PrAuthorWorktreeTarget {
         directly would depend on the machine's live worktrees and would pass or fail
         according to what other sessions happen to have checked out, which the repository's
         determinism policy forbids. Mocking here lets a test state the resolution outcome it
-        is exercising and nothing else.
+        is exercising and nothing else. A NoTarget result for a command with no signal passes
+        through Resolve-PrAuthorCurrentBranchTarget, which re-resolves the current branch (#989).
     .OUTPUTS
         The target result object from Resolve-WorktreeItemTarget.
     #>
@@ -77,7 +81,8 @@ function Resolve-PrAuthorWorktreeTarget {
         [string] $CommandText
     )
 
-    return (Resolve-WorktreeItemTarget -Text $CommandText -SessionRoot (Get-Location).Path)
+    $target = Resolve-WorktreeItemTarget -Text $CommandText -SessionRoot (Get-Location).Path
+    return (Resolve-PrAuthorCurrentBranchTarget -CommandText $CommandText -Target $target)
 }
 
 function Get-PrAuthorTargetCheckpointResolution {
@@ -91,10 +96,10 @@ function Get-PrAuthorTargetCheckpointResolution {
           SessionRoot   -> that worktree's own checkpoint, composed absolutely.
           OtherWorktree -> that worktree's own checkpoint, composed the same way.
           NoTarget      -> deny, carrying the code Get-WorktreeResolutionNoTargetReasonCode
-                           returns. pr-author passes --head on every gh pr create, so a call
-                           reaching here omitted the explicit target; the remedy is to supply
-                           it, never to fall back to whichever checkpoint occupies the
-                           session root.
+                           returns. The call named no target and no branch could be derived
+                           from the current checkout; the remedy text from
+                           Get-PrAuthorTargetGuidanceText names the accepted forms, and the
+                           gate never falls back to the session root's checkpoint.
           Ambiguous     -> deny, carrying the code
                            Get-WorktreeResolutionAmbiguityReasonCode returns.
 
@@ -125,7 +130,7 @@ function Get-PrAuthorTargetCheckpointResolution {
             return [ordered]@{ CheckpointPath = (Get-WorktreeItemCheckpointPath -WorktreeRoot $target.WorktreeRoot); Reason = $null; WorktreeRoot = $target.WorktreeRoot; Status = $target.Status }
         }
         default {
-            $reason = "$($target.ReasonCode): $($target.Detail) The pr-author gate will not validate this call against the session root's checkpoint, because that checkpoint may belong to a different item. Pass --head <branch> on the gh pr create command so the call names its own target."
+            $reason = "$($target.ReasonCode): $($target.Detail) The pr-author gate will not validate this call against the session root's checkpoint, because that checkpoint may belong to a different item. $(Get-PrAuthorTargetGuidanceText)"
             return [ordered]@{ CheckpointPath = $null; Reason = $reason; WorktreeRoot = $null; Status = $target.Status }
         }
     }

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

@@ -0,0 +1,149 @@
+<#
+.SYNOPSIS
+    Current-branch target derivation for enforce-pr-author-skill.ps1 (issue #989).
+
+.DESCRIPTION
+    Dot-sourced by enforce-pr-author-skill-helpers.ps1. Resolve-PrAuthorWorktreeTarget passes its
+    command-text resolution through Resolve-PrAuthorCurrentBranchTarget, which applies one
+    fallback: when the command carries no branch signal (--head, --branch, or branch:) and no
+    canonical issue line, and resolution returned NoTarget, the branch checked out in the hook
+    process's working directory is read and re-resolved through the existing resolver as a
+    'branch: <name>' signal. gh pr edit has no --head flag, so this is how an edit run from the
+    item worktree names its own target.
+
+    Derivation order: explicit signal in the command, else the current branch, else the
+    original NoTarget result. A signal that matches no live worktree does not trigger the
+    fallback. A detached HEAD (git prints the literal HEAD), a non-zero git exit, or empty
+    output keeps the original NoTarget result and its reason code.
+
+    Get-PrAuthorTargetGuidanceText supplies the remedy sentence that follows the reason code and
+    detail in the TARGET_WORKTREE_NOT_DERIVABLE denial.
+
+.NOTES
+    PowerShell 7+. Depends, at call time, on Find-WorktreeResolutionBranchSignal,
+    Find-WorktreeItemIssueSignal, and Resolve-WorktreeItemTarget from the worktree-resolution
+    modules the helpers file imports. It reads no file content. The git executable runs only
+    through Invoke-PrAuthorCurrentBranchGitExe, the single executable seam, which never throws.
+    Mirrored byte-identically under extensions/drm-copilot/resources/claude-customizations/.
+#>
+[CmdletBinding()]
+param()
+
+function Invoke-PrAuthorCurrentBranchGitExe {
+    <#
+    .SYNOPSIS
+        Run git with the given arguments in the current directory. The single executable seam.
+    .DESCRIPTION
+        Never throws: an uncaught error ends the hook with exit 1, which PreToolUse treats as
+        non-blocking, so a throw here would allow the call. A git that cannot start returns
+        ExitCode -1. Standard error is discarded so that it is never read as a branch name.
+    .PARAMETER GitArgs
+        The git arguments.
+    .PARAMETER GitInvoker
+        The scriptblock that runs git; a unit test passes a test-local stand-in so that this
+        body runs without starting a process.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with ExitCode and Output (trimmed).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][string[]] $GitArgs,
+        [ValidateNotNull()][scriptblock] $GitInvoker = { git @args 2>$null }
+    )
+
+    try {
+        $lines = @(& $GitInvoker @GitArgs 2>$null)
+        $code = $LASTEXITCODE
+    }
+    catch {
+        return [pscustomobject]@{ ExitCode = -1; Output = '' }
+    }
+    return [pscustomobject]@{ ExitCode = [int]$code; Output = ($lines -join "`n").Trim() }
+}
+
+function Get-PrAuthorCurrentBranch {
+    <#
+    .SYNOPSIS
+        Return the branch checked out in the current directory, or $null.
+    .DESCRIPTION
+        Runs git rev-parse --abbrev-ref HEAD through Invoke-PrAuthorCurrentBranchGitExe. Returns
+        $null for a non-zero exit, for empty output, for output containing whitespace, and for
+        the literal HEAD that git prints on a detached checkout.
+    .PARAMETER GitInvoker
+        Optional. Forwarded to the git seam; omitted, the seam's default invoker runs git.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [scriptblock] $GitInvoker
+    )
+
+    $seamArgs = @{ GitArgs = @('rev-parse', '--abbrev-ref', 'HEAD') }
+    if ($null -ne $GitInvoker) { $seamArgs['GitInvoker'] = $GitInvoker }
+    $result = Invoke-PrAuthorCurrentBranchGitExe @seamArgs
+    $name = [string]$result.Output
+    if ($result.ExitCode -ne 0 -or [string]::IsNullOrWhiteSpace($name) -or $name -match '\s' -or $name -ceq 'HEAD') {
+        return $null
+    }
+    return $name
+}
+
+function Resolve-PrAuthorCurrentBranchTarget {
+    <#
+    .SYNOPSIS
+        Apply the current-branch fallback to a command-text resolution result.
+    .DESCRIPTION
+        Returns Target unchanged unless its Status is NoTarget and the command text carries
+        neither a branch signal nor a canonical issue line. In that case the current branch is
+        read; a $null branch returns Target unchanged, and any other branch is re-resolved with
+        Resolve-WorktreeItemTarget as the text 'branch: <name>', so ambiguity handling and the
+        SessionRoot or OtherWorktree labelling stay with the existing resolver.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER Target
+        The result Resolve-WorktreeItemTarget returned for the command text.
+    .OUTPUTS
+        The target result object from Resolve-WorktreeItemTarget.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string] $CommandText,
+        [Parameter(Mandatory)][AllowNull()][object] $Target
+    )
+
+    if ($null -eq $Target -or $Target.Status -ne 'NoTarget') {
+        return $Target
+    }
+    # Find-WorktreeItemIssueSignal emits its array as one object, so it is assigned before counting.
+    $issueSignal = Find-WorktreeItemIssueSignal -Text $CommandText
+    if ($null -ne (Find-WorktreeResolutionBranchSignal -Text $CommandText) -or $issueSignal.Count -gt 0) {
+        return $Target
+    }
+    $branch = Get-PrAuthorCurrentBranch
+    if ($null -eq $branch) {
+        return $Target
+    }
+    return (Resolve-WorktreeItemTarget -Text "branch: $branch" -SessionRoot (Get-Location).Path)
+}
+
+function Get-PrAuthorTargetGuidanceText {
+    <#
+    .SYNOPSIS
+        Return the remedy sentence of the TARGET_WORKTREE_NOT_DERIVABLE denial.
+    .DESCRIPTION
+        Names the accepted target forms: --head <branch> on gh pr create, and for gh pr edit
+        either running the command from the item worktree (the branch is derived) or appending
+        the shell comment # branch: <branch>. States that --head is not valid for gh pr edit.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return 'Name the target: for gh pr create, pass --head <branch> (gh pr create --head <branch> ...). For gh pr edit, run the command from the item worktree so the gate derives the branch from its checkout, or append the shell comment # branch: <branch> to the command; --head is not valid for gh pr edit.'
+}

package/resources/claude-customizations/.claude/hooks/enforce-python-batch-budget.ps1

@@ -61,7 +61,7 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 
 
 try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
-try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-batch-budget-route.ps1' -ErrorRecord $_ }
+$script:PythonBatchBudgetRouteImportFailure = $null; try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { $script:PythonBatchBudgetRouteImportFailure = 'enforce-batch-budget-route.ps1' }
 
 function Test-PythonBatchBudgetPathInRoot {
     <#
@@ -374,6 +374,7 @@ function Invoke-PythonBatchBudgetHook {
     if ($normalized -notmatch '\.py$') {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
+    if ($script:PythonBatchBudgetRouteImportFailure) { return Get-PythonBatchBudgetBlockDecision -Reason "PYTHON_LARGE_PATH_REQUIRED: the route helper '$($script:PythonBatchBudgetRouteImportFailure)' failed to load, so the batch budget for '$normalized' cannot be evaluated; the gate fails closed." }
 
     $stateDir = Join-Path -Path $Root -ChildPath '.claude/state'
 

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

@@ -0,0 +1,146 @@
+<#
+.SYNOPSIS
+    Adopted feature-folder probe for the orchestrator SubagentStop hook validate-orchestrator-output.ps1 (issue #992).
+
+.DESCRIPTION
+    Dot-sourced by validate-orchestrator-output.ps1 through a guarded load whose catch records the
+    failure with Add-HookDependencyFailure, so a missing or broken copy of this file blocks the hook
+    instead of failing open. It defines Invoke-FeatureFolderGitExe, the single git seam, and
+    Get-OrchestratorOutputFeatureFolderDecision.
+
+    When an orchestrator-state checkpoint waives new_active_feature_folder through
+    issue_adoption.waived_tools, the validators accept a declared feature_folder_record but cannot
+    read the repository. This probe confirms that HEAD of the run worktree holds a tree at the
+    checkpoint feature-folder, so a staged-only, untracked, or absent folder blocks. It proves only
+    that a tree exists at that path at stop time; it does not prove which tool created the folder
+    or that its contents are correct.
+
+    The file imports nothing. Test-OrchestratorStateFeatureFolderPath comes from
+    OrchestratorStateFeatureFolderRecord.psm1, which the main hook imports through its own guarded
+    load. The file invokes no Python.
+#>
+
+$script:FeatureFolderProbeTool = 'new_active_feature_folder'
+
+function Invoke-FeatureFolderGitExe {
+    <#
+    .SYNOPSIS
+        Run git with the given arguments. The single executable seam of the feature-folder probe.
+    .DESCRIPTION
+        Never throws: a git that cannot start, or an invoker that throws, returns ExitCode -1 so the
+        caller blocks instead of failing open. The default invoker merges standard error into Output;
+        success requires the exact output tree, so error text is never read as success.
+    .PARAMETER GitArgs
+        The git arguments.
+    .PARAMETER GitInvoker
+        The scriptblock that runs git; a unit test passes a test-local stand-in that sets
+        $global:LASTEXITCODE, so this body runs without starting a process.
+    .OUTPUTS
+        System.Collections.Hashtable with keys ExitCode (int) and Output (string, trimmed).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string[]] $GitArgs,
+
+        [Parameter(Mandatory = $false)]
+        [ValidateNotNull()]
+        [scriptblock] $GitInvoker = { git @args 2>&1 }
+    )
+
+    try {
+        $lines = @(& $GitInvoker @GitArgs)
+        $code = $LASTEXITCODE
+    }
+    catch {
+        return @{ ExitCode = -1; Output = '' }
+    }
+    if ($null -eq $code) { $code = -1 }
+    return @{ ExitCode = [int]$code; Output = ((@($lines | ForEach-Object { [string]$_ }) -join "`n").Trim()) }
+}
+
+function Test-FeatureFolderProbeWaived {
+    <#
+    .SYNOPSIS
+        Report whether the checkpoint's issue_adoption.waived_tools lists new_active_feature_folder.
+    .PARAMETER Checkpoint
+        The parsed checkpoint object. May be $null.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Checkpoint
+    )
+
+    if ($Checkpoint -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    $adoptionProperty = $Checkpoint.PSObject.Properties['issue_adoption']
+    if ($null -eq $adoptionProperty -or $adoptionProperty.Value -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    $waivedProperty = $adoptionProperty.Value.PSObject.Properties['waived_tools']
+    if ($null -eq $waivedProperty -or $waivedProperty.Value -isnot [System.Array]) { return $false }
+    return (@($waivedProperty.Value | Where-Object { $_ -is [string] }) -ccontains $script:FeatureFolderProbeTool)
+}
+
+function Get-OrchestratorOutputFeatureFolderDecision {
+    <#
+    .SYNOPSIS
+        Confirm that HEAD of the run worktree holds a tree at the adopted feature-folder.
+    .DESCRIPTION
+        Returns @{ Ok = $true; Message = $null } when the checkpoint does not waive
+        new_active_feature_folder. Otherwise the checkpoint feature-folder is re-checked against the
+        shared path pattern before any git call (a failing path never reaches git), and
+        git -C <WorktreeRoot> cat-file -t HEAD:<feature-folder> must exit 0 and print exactly tree.
+        Every other outcome (non-zero exit, -1, empty output, other output) blocks with a repairable
+        ROUTING_CONTRACT_BLOCKED message naming the path.
+    .PARAMETER Checkpoint
+        The parsed checkpoint object. May be $null.
+    .PARAMETER WorktreeRoot
+        The root of the worktree whose run stopped.
+    .PARAMETER GitInvoker
+        Optional. Forwarded to Invoke-FeatureFolderGitExe; omitted, the seam's default runs git.
+    .OUTPUTS
+        System.Collections.Hashtable with keys Ok, Message, and (on a block) Repairable.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Checkpoint,
+
+        [Parameter(Mandatory = $true)]
+        [string] $WorktreeRoot,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $GitInvoker
+    )
+
+    if (-not (Test-FeatureFolderProbeWaived -Checkpoint $Checkpoint)) {
+        return @{ Ok = $true; Message = $null }
+    }
+
+    $folderProperty = $Checkpoint.PSObject.Properties['feature-folder']
+    $folder = if ($null -ne $folderProperty) { $folderProperty.Value } else { $null }
+    $blocked = @{ Ok = $false; Repairable = $true; Message = ('ROUTING_CONTRACT_BLOCKED: Checkpoint feature-folder is not committed in HEAD: {0}.' -f [string]$folder) }
+    # Defense in depth: the validators already require the record path to match the pattern and to
+    # equal feature-folder, but a value that fails the pattern must never become a git argument.
+    if (-not (Test-OrchestratorStateFeatureFolderPath -Value $folder)) {
+        return $blocked
+    }
+
+    $gitArgs = [string[]]@('-C', $WorktreeRoot, 'cat-file', '-t', ('HEAD:' + [string]$folder))
+    $probe = if ($PSBoundParameters.ContainsKey('GitInvoker') -and $null -ne $GitInvoker) {
+        Invoke-FeatureFolderGitExe -GitArgs $gitArgs -GitInvoker $GitInvoker
+    }
+    else {
+        Invoke-FeatureFolderGitExe -GitArgs $gitArgs
+    }
+    if (($probe.ExitCode -eq 0) -and [string]::Equals([string]$probe.Output, 'tree', [System.StringComparison]::Ordinal)) {
+        return @{ Ok = $true; Message = $null }
+    }
+    return $blocked
+}

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

@@ -25,7 +25,9 @@
     ambiguous, or mismatched target blocks with ORCHESTRATOR_CHECKPOINT_UNRESOLVED:
     before any checkpoint is read. For epic-orchestrator-state, the Layer 2 wave-barrier
     ordering check (OrchestratorStateEpicWaveBarrier.psm1, issue #840) runs after the
-    routing dispatch passes.
+    routing dispatch passes. For orchestrator-state, the adopted feature-folder probe
+    (validate-orchestrator-output-feature-folder.ps1, issue #992) runs after the routing
+    dispatch passes, and only when the checkpoint waives new_active_feature_folder.
 
 .NOTES
     Reads the SubagentStop envelope from stdin through Read-SubagentStopEnvelope
@@ -61,6 +63,10 @@ try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/Orchestr
 try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateCompletion.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateCompletion.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateUnconditional.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateUnconditional.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorState.psm1' -ErrorRecord $_ }
+# Imported after the completion modules without -Force, so the instance they already loaded through
+# the adoption module stays the one in use (issue #992).
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateFeatureFolderRecord.psm1') -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateFeatureFolderRecord.psm1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'validate-orchestrator-output-feature-folder.ps1') } catch { Add-HookDependencyFailure -Name 'validate-orchestrator-output-feature-folder.ps1' -ErrorRecord $_ }
 try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 $ErrorActionPreference = 'Stop'
 $script:SubagentStopReportAndHaltLine = 'This condition is not repairable by the subagent. Report it to the operator and halt.'
@@ -194,7 +200,10 @@ function Invoke-OrchestratorOutputValidation {
         [string] $SessionRoot = (Get-Location).Path,
 
         [Parameter(Mandatory = $false)]
-        [scriptblock] $RoutingInvoker
+        [scriptblock] $RoutingInvoker,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FeatureFolderGitInvoker
     )
     $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'ORCHESTRATOR_CHECKPOINT_UNRESOLVED:'
     if ($null -ne $dependencyDecision) { return $dependencyDecision }
@@ -205,6 +214,7 @@ function Invoke-OrchestratorOutputValidation {
         $agentOutput = $envelope.AssistantText
         $blockArguments = @{ AgentOutput = ([string]$agentOutput); CheckpointPath = $CheckpointPath; ArtifactType = $ArtifactType; SessionRoot = $SessionRoot }
         if ($PSBoundParameters.ContainsKey('RoutingInvoker')) { $blockArguments['RoutingInvoker'] = $RoutingInvoker }
+        if ($PSBoundParameters.ContainsKey('FeatureFolderGitInvoker')) { $blockArguments['FeatureFolderGitInvoker'] = $FeatureFolderGitInvoker }
         $decision = Get-OrchestratorOutputBlockDecision @blockArguments
     }
     if ($decision.Ok) { return @{ Ok = $true; Message = $null } }
@@ -235,7 +245,10 @@ function Get-OrchestratorOutputBlockDecision {
         [string] $SessionRoot = (Get-Location).Path,
 
         [Parameter(Mandatory = $false)]
-        [scriptblock] $RoutingInvoker
+        [scriptblock] $RoutingInvoker,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FeatureFolderGitInvoker
     )
 
     if ([string]::IsNullOrWhiteSpace($agentOutput)) {
@@ -322,6 +335,15 @@ function Get-OrchestratorOutputBlockDecision {
         return @{ Ok = $false; Repairable = $true; Message = "ROUTING_CONTRACT_BLOCKED: $($routingResult.ErrorText)" }
     }
 
+    # Issue #992: a waived new_active_feature_folder must name a folder committed in HEAD of the run
+    # worktree. The validators only see the declared record, so the hook probes git once.
+    if ($ArtifactType -eq 'orchestrator-state') {
+        $folderArgs = @{ Checkpoint = $checkpoint; WorktreeRoot = [string]$resolution.WorktreeRoot }
+        if ($PSBoundParameters.ContainsKey('FeatureFolderGitInvoker') -and $null -ne $FeatureFolderGitInvoker) { $folderArgs['GitInvoker'] = $FeatureFolderGitInvoker }
+        $folderDecision = Get-OrchestratorOutputFeatureFolderDecision @folderArgs
+        if (-not $folderDecision.Ok) { return @{ Ok = $false; Repairable = $folderDecision.Repairable; Message = $folderDecision.Message } }
+    }
+
     # Layer 2 (issue #840): the epic checkpoint only, after the routing dispatch passes,
     # on the checkpoint text already read.
     if ($ArtifactType -eq 'epic-orchestrator-state') {