@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.24

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-file-size-limit.ps1

@@ -0,0 +1,282 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks a Write, Edit, or apply_patch leaving a covered file above 800 lines.
+
+.DESCRIPTION
+    This script is invoked by the Codex PreToolUse hook under the ^(apply_patch|Edit|Write)$
+    matcher. It enforces the hard tier of the tiered file-size policy: 500 lines is
+    guidance, 700 lines is advisory, and above 800 lines a split is enforced regardless of
+    logical separability. The policy functions are the dot-sourced Codex twin
+    file-size-policy.ps1, which is held text-identical to the Claude module.
+
+    The stdin payload is parsed by ConvertFrom-CodexPreToolUsePayload and mapped to
+    file-edit records by ConvertTo-CodexFileEditInput. Per record:
+      - A path that is not covered, and a Delete, allow with no file read.
+      - Write and apply_patch Add use the record content.
+      - Edit resolves old_string to new_string in memory against the pre-edit file read
+        through the ReadFileContent seam; a missing or unreadable file, or an edit that
+        cannot be resolved, denies.
+      - apply_patch Update is reconstructed by a second ConvertTo-CodexFileEditInput call
+        with -ResolveUpdateContent and -GovernedPath set to the patched path; empty
+        reconstructed content denies.
+      - A rename evaluates the destination, and the source supplies the pre-edit size.
+    A result above 800 lines is denied unless the file already existed and does not grow.
+
+    Allowed payloads produce NO stdout and exit 0. A deny writes the PreToolUse JSON
+    envelope to stdout and exits 0. Empty, malformed, or tool_input-less stdin writes the
+    reason to stderr and exits 2.
+
+.NOTES
+    Compatible with PowerShell 7+.
+    This script must not modify any state; it is a read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+# Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
+# mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'file-size-policy.ps1') } catch { Add-HookDependencyFailure -Name 'file-size-policy.ps1' -ErrorRecord $_ }
+
+function Get-FileSizeLimitBlockDecision {
+    <#
+    .SYNOPSIS
+        Constructs a deny-decision ordered dictionary carrying the supplied reason.
+    .PARAMETER Reason
+        The deny reason; it starts with FILE_SIZE_LIMIT_BLOCKED:.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Get-CodexFileSizeRecordValue {
+    <#
+    .SYNOPSIS
+        Returns a named property of a file-edit record, or $null when it is absent.
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Record,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    if ($null -eq $Record -or $Record.PSObject.Properties.Name -notcontains $Name) {
+        return $null
+    }
+    return $Record.$Name
+}
+
+function Get-CodexFileSizeReplaceAllFlag {
+    <#
+    .SYNOPSIS
+        Returns the boolean value of a record's replace_all property.
+    .DESCRIPTION
+        A boolean is returned as is; a string is true only when its trimmed value is
+        'true' (case-insensitive); every other value is false.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Record
+    )
+
+    $value = Get-CodexFileSizeRecordValue -Record $Record -Name 'replace_all'
+    if ($value -is [bool]) {
+        return $value
+    }
+    if ($value -is [string]) {
+        return ($value.Trim() -ieq 'true')
+    }
+    return $false
+}
+
+function Get-CodexFileSizeUpdatedContent {
+    <#
+    .SYNOPSIS
+        Reconstructs the post-patch content of an apply_patch Update for one patched path.
+    .OUTPUTS
+        The reconstructed content, or an empty string when it cannot be reconstructed.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        $Payload,
+
+        [Parameter(Mandatory)]
+        [string] $SourcePath
+    )
+
+    $resolved = @(
+        ConvertTo-CodexFileEditInput -Payload $Payload -ResolveUpdateContent -GovernedPath $SourcePath |
+            Where-Object { $_.operation -eq 'Update' -and $_.source_path -eq $SourcePath }
+    )
+    if ($resolved.Count -eq 0) {
+        return ''
+    }
+    return [string]$resolved[0].content
+}
+
+function Invoke-CodexFileSizeLimitDecision {
+    <#
+    .SYNOPSIS
+        Returns the deny decision for one file-edit record, or $null when it is allowed.
+    .PARAMETER Record
+        One record from ConvertTo-CodexFileEditInput.
+    .PARAMETER Payload
+        The parsed payload, used to reconstruct an apply_patch Update.
+    .PARAMETER RepositoryRoot
+        The repository root used to resolve relative paths. Defaults to the current location.
+    .PARAMETER ReadFileContent
+        Seam that returns the text of a file, $null when the file does not exist, and
+        throws when it cannot be read. Tests supply in-memory content.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        $Record,
+
+        [Parameter(Mandatory)]
+        $Payload,
+
+        [string] $RepositoryRoot = (Get-Location).ProviderPath,
+
+        [scriptblock] $ReadFileContent = {
+            param([string] $Path)
+            if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+            return [System.IO.File]::ReadAllText($Path)
+        }
+    )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'FILE_SIZE_LIMIT_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+
+    $operation = [string](Get-CodexFileSizeRecordValue -Record $Record -Name 'operation')
+    $sourcePath = [string](Get-CodexFileSizeRecordValue -Record $Record -Name 'source_path')
+    $relativePath = ConvertTo-FileSizeRelativePath -Path ([string]$Record.file_path) -RepositoryRoot $RepositoryRoot
+    if ($operation -eq 'Delete' -or -not (Test-FileSizeCoveredPath -RelativePath $relativePath)) {
+        return $null
+    }
+
+    # The pre-edit size comes from the source path, which differs from the target only for a rename.
+    $sourceRelative = ConvertTo-FileSizeRelativePath -Path $sourcePath -RepositoryRoot $RepositoryRoot
+    $isRooted = ($sourcePath -match '^[\\/]') -or ($sourcePath -match '^[A-Za-z]:[\\/]')
+    $readPath = if ($isRooted -or $null -eq $sourceRelative) { $sourcePath } else { Join-Path $RepositoryRoot $sourceRelative }
+    $hardLimit = (Get-FileSizePolicyLimit).HardLimit
+
+    $resultCount = 0
+    if ($operation -eq 'Update') {
+        $updated = Get-CodexFileSizeUpdatedContent -Payload $Payload -SourcePath $sourcePath
+        if ([string]::IsNullOrEmpty($updated)) {
+            return Get-FileSizeLimitBlockDecision -Reason "FILE_SIZE_LIMIT_BLOCKED: the apply_patch Update to '$relativePath' could not be reconstructed to measure its size. The gate fails closed for a covered file."
+        }
+        $resultCount = Get-FileSizeLogicalLineCount -Content $updated
+    } elseif ($operation -ne 'Edit') {
+        $resultCount = Get-FileSizeLogicalLineCount -Content ([string](Get-CodexFileSizeRecordValue -Record $Record -Name 'content'))
+    }
+    if ($operation -ne 'Edit' -and $resultCount -le $hardLimit) {
+        return $null
+    }
+
+    try {
+        $preEditContent = & $ReadFileContent $readPath
+    } catch {
+        return Get-FileSizeLimitBlockDecision -Reason "FILE_SIZE_LIMIT_BLOCKED: '$relativePath' could not be read to measure its size ($($_.Exception.Message)). The gate fails closed for a covered file."
+    }
+    $preEditCount = $null
+    if ($null -ne $preEditContent) {
+        $preEditCount = Get-FileSizeLogicalLineCount -Content ([string]$preEditContent)
+    }
+
+    if ($operation -eq 'Edit') {
+        if ($null -eq $preEditContent) {
+            return Get-FileSizeLimitBlockDecision -Reason "FILE_SIZE_LIMIT_BLOCKED: '$relativePath' does not exist, so the Edit cannot be measured. The gate fails closed for a covered file."
+        }
+        $edit = Resolve-FileSizeEditContent -Content ([string]$preEditContent) `
+            -OldString ([string](Get-CodexFileSizeRecordValue -Record $Record -Name 'old_string')) `
+            -NewString ([string](Get-CodexFileSizeRecordValue -Record $Record -Name 'new_string')) `
+            -ReplaceAll (Get-CodexFileSizeReplaceAllFlag -Record $Record)
+        if ($null -ne $edit.Failure) {
+            return Get-FileSizeLimitBlockDecision -Reason "FILE_SIZE_LIMIT_BLOCKED: the Edit to '$relativePath' could not be resolved in memory ($($edit.Failure)). The gate fails closed for a covered file."
+        }
+        $resultCount = Get-FileSizeLogicalLineCount -Content $edit.Content
+    }
+
+    $decision = Get-FileSizeHookDecision -RelativePath $relativePath -ResultLineCount $resultCount -PreEditLineCount $preEditCount
+    if ($decision.Allowed) {
+        return $null
+    }
+    return Get-FileSizeLimitBlockDecision -Reason $decision.Reason
+}
+
+function Invoke-CodexFileSizeLimitEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads one Codex PreToolUse payload and returns the process exit code.
+    .PARAMETER PayloadRaw
+        The raw stdin text. AllowEmptyString is required so empty input reaches the shared
+        parser and fails closed with exit 2.
+    .PARAMETER RepositoryRoot
+        The repository root passed to the per-record decision.
+    .PARAMETER ReadFileContent
+        Optional file-reader seam passed to the per-record decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $PayloadRaw,
+
+        [string] $RepositoryRoot = (Get-Location).ProviderPath,
+
+        [scriptblock] $ReadFileContent
+    )
+
+    try {
+        $payload = ConvertFrom-CodexPreToolUsePayload -PayloadRaw $PayloadRaw -HookName 'enforce-file-size-limit'
+        foreach ($record in @(ConvertTo-CodexFileEditInput -Payload $payload)) {
+            $decisionArgs = @{ Record = $record; Payload = $payload; RepositoryRoot = $RepositoryRoot }
+            if ($PSBoundParameters.ContainsKey('ReadFileContent')) { $decisionArgs['ReadFileContent'] = $ReadFileContent }
+            $decision = Invoke-CodexFileSizeLimitDecision @decisionArgs
+            if ($null -ne $decision) {
+                [Console]::Out.WriteLine(($decision | ConvertTo-Json -Compress -Depth 5))
+                return 0
+            }
+        }
+        return 0
+    } catch {
+        [Console]::Error.WriteLine([string]$_)
+        return 2
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('FILE_SIZE_LIMIT_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'FILE_SIZE_LIMIT_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
+
+exit (Invoke-CodexFileSizeLimitEntryPoint -PayloadRaw ([Console]::In.ReadToEnd()))

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-orchestration-preimplementation-gate-epic-scope.ps1

@@ -4,12 +4,20 @@
 
 .DESCRIPTION
     Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. The Codex counterpart
-    of the issue #663 Claude sibling, holding two groups of functions:
+    of the issue #663 Claude sibling, holding three groups of functions:
 
     - The two per-mode read seams of issue #554 (Get-EpicCheckpointContent and
       Get-ParallelCheckpointContent), relocated verbatim from the gate file so the gate
       stays inside the 500-line cap. Their names and behaviour are unchanged, so tests
       that mock or shadow them by name are unaffected.
+    - The target-resolution building blocks of issue #1010, byte-identical to the Claude
+      sibling: the worktree-list wrapper Get-OrchestrationGateWorktreeList (the only
+      listing seam), the recording invoker Invoke-OrchestrationGateWorktreeList, and the
+      command-operand parser Get-OrchestrationGateCommandOperandPath, plus the reason-code
+      pair restated from WorktreeResolution.psm1. They feed Resolve-OrchestrationGateTarget
+      and Read-OrchestrationGateCheckpoint, which read the single-feature checkpoint through
+      the Get-CheckpointContent seam (mandatory absolute Path, moved here from the gate)
+      beneath the worktree the file path, apply_patch markers, or command operands name.
     - The epic-scope decision for the command, apply_patch, and path legs. A call is epic
       scope when the effective worktree's HEAD (the -C selector worktree when present,
       otherwise the session root) equals the integration_branch of
@@ -29,13 +37,23 @@
     from the resolution sibling dot-sourced below. The per-segment target resolver comes
     from the targets file dot-sourced below (issue #738), which calls
     Read-CommandLineSegment, Get-CommandLineGlobalOption, and Get-CommandLineInvocation,
-    loaded by the gate's dot-source of hook-command-invocation.ps1.
+    loaded by the gate's dot-source of hook-command-invocation.ps1. Resolve-HookTargetWorktree
+    and ConvertFrom-HookTargetWorktreePorcelain come from the guarded dot-source of the
+    resolver twin hook-target-worktree.ps1 (issue #1009).
     Mirrored byte-identically under extensions/drm-copilot/resources/codex-and-agents-customizations/.
     AUTHORITY: PowerShell-authoritative. The epic readiness predicate has no reference implementation in another language, and this hook starts no interpreter process (issue #707, D15).
 #>
 
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-epic-resolution.ps1')
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-targets.ps1')
+try { . (Join-Path $PSScriptRoot 'hook-target-worktree.ps1') } catch { Add-HookDependencyFailure -Name 'hook-target-worktree.ps1' -ErrorRecord $_ }
+
+# The target-resolution reason codes (issue #1010). Their source is
+# Get-WorktreeResolutionAmbiguityReasonCode and Get-WorktreeResolutionNoTargetReasonCode
+# in .claude/lib/worktree-resolution/WorktreeResolution.psm1; Codex hooks cannot import
+# .claude/lib, so the two literals are restated once here and pinned equal by a test.
+$script:OrchestrationGateAmbiguousReasonCode = 'TARGET_WORKTREE_AMBIGUOUS'
+$script:OrchestrationGateNotDerivableReasonCode = 'TARGET_WORKTREE_NOT_DERIVABLE'
 
 # An epic manifest lives under the epics tree; the pattern is tested after backslash
 # normalisation so either separator spelling is accepted.
@@ -68,6 +86,225 @@ function Get-ParallelCheckpointContent {
     return Get-Content -Raw -LiteralPath $path
 }
 
+# The single-feature read seam (issue #1010, moved from the gate file). It takes the
+# absolute path composed beneath the resolved worktree root, so no read binds to the
+# calling process's directory; an absent file returns an empty string.
+function Get-CheckpointContent {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path)) {
+        return ''
+    }
+    return Get-Content -Raw -LiteralPath $Path
+}
+
+function Get-OrchestrationGateWorktreeList {
+    <#
+    .SYNOPSIS
+        Returns the porcelain worktree listing for the session root (issue #1010 seam).
+    .DESCRIPTION
+        Runs the listing exactly as the default WorktreeListInvoker of
+        Resolve-HookTargetWorktree does and returns an empty string on a non-zero exit. It
+        is the only test seam for the listing.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][string] $SessionRoot)
+
+    $porcelain = & git -C $SessionRoot worktree list --porcelain 2>$null
+    if ($LASTEXITCODE -ne 0) { return '' }
+    return ($porcelain -join "`n")
+}
+
+function Invoke-OrchestrationGateWorktreeList {
+    <#
+    .SYNOPSIS
+        Recording WorktreeListInvoker: returns the listing and records a listing failure.
+    .DESCRIPTION
+        Sets $script:OrchestrationGateWorktreeListFailed when the wrapper throws (and then
+        rethrows) or when its text holds no worktree entry, so the gate denies instead of
+        accepting the resolver's session-root fallback (issue #1010, spec E1).
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][string] $SessionRoot)
+
+    try {
+        $text = [string](Get-OrchestrationGateWorktreeList -SessionRoot $SessionRoot)
+    } catch {
+        $script:OrchestrationGateWorktreeListFailed = $true
+        throw
+    }
+    if (@(ConvertFrom-HookTargetWorktreePorcelain -Text $text).Count -eq 0) {
+        $script:OrchestrationGateWorktreeListFailed = $true
+    }
+    return $text
+}
+
+function Get-OrchestrationGateCommandOperandPath {
+    <#
+    .SYNOPSIS
+        Returns the worktree-selecting paths of every git add and git commit invocation.
+    .DESCRIPTION
+        Scans every Structural match of git add and git commit (every command segment and
+        wrapper payload). Each -C value in any git global-option position and each absolute
+        operand is returned, distinct and in first-seen order. Relative operands, a -C on a
+        git segment invoking neither add nor commit, and Indeterminate matches are ignored.
+        For a match whose record is not argument-injected, a subcommand-aware walk (issue
+        #1010, F2) also reads the tokens after the subcommand with a per-subcommand option
+        model, compared case-sensitively: a value option consumes the next token unless its
+        value is inline (--name=value) or attached (-mvalue); a standalone flag consumes
+        itself; '--' makes every later token an operand; a redirection and its target are
+        skipped; any other dash token, such as the cluster -am, stops the walk. Its literal
+        absolute tokens are returned, and a token the walk reads as an option value is not
+        returned as an operand.
+    .PARAMETER Command
+        The full command line.
+    .OUTPUTS
+        System.String[]
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Command)
+
+    $valueOptions = @{
+        commit = @('-m', '--message', '-F', '--file', '--author', '--date', '-C', '--reuse-message', '-c', '--reedit-message', '-t', '--template', '--fixup', '--squash', '--trailer', '--pathspec-from-file')
+        add    = @('--pathspec-from-file', '--chmod')
+    }
+    $flagOptions = @{
+        commit = @('-a', '--all', '--amend', '--no-edit', '--no-verify', '-n', '-s', '--signoff', '-q', '--quiet', '-v', '--verbose', '--allow-empty', '-o', '--only', '-i', '--include', '--pathspec-file-nul')
+        add    = @('-A', '--all', '-u', '--update', '-f', '--force', '-N', '--intent-to-add', '-n', '--dry-run', '-v', '--verbose', '--pathspec-file-nul')
+    }
+    $absolutePattern = '^([A-Za-z]:[\\/]|/)'
+    $paths = [System.Collections.Generic.List[string]]::new()
+    foreach ($subcommand in @('add', 'commit')) {
+        foreach ($match in @(Get-CommandLineInvocation -CommandText $Command -CommandWord 'git' -SubcommandPath @($subcommand))) {
+            if ($match.Status -ne 'Structural') { continue }
+            $walked = [System.Collections.Generic.List[string]]::new()
+            $optionValues = [System.Collections.Generic.List[string]]::new()
+            $tokens = if ($match.Segment.ArgumentInjected) { [string[]]@() } else { [string[]]@($match.Segment.Tokens) }
+            $afterSeparator = $false
+            for ($index = [int]$match.OperandIndex; $index -lt $tokens.Count; $index++) {
+                $token = $tokens[$index]
+                if (-not $afterSeparator -and $token -match '^(<|>|\d*>|&>)') {
+                    if ($token -match '^(\d*[<>]{1,2}&?|&>{1,2})$') { $index++ }
+                    continue
+                }
+                if ($afterSeparator -or -not $token.StartsWith('-')) { $walked.Add($token); continue }
+                if ($token -ceq '--') { $afterSeparator = $true; continue }
+                $name = if ($token.IndexOf('=') -gt 0) { $token.Substring(0, $token.IndexOf('=')) } else { $token }
+                if ($valueOptions[$subcommand] -ccontains $name) {
+                    if ($name -ceq $token -and $index + 1 -lt $tokens.Count) { $index++; $optionValues.Add($tokens[$index]) }
+                    continue
+                }
+                if ($token -match '^-[^-].' -and $valueOptions[$subcommand] -ccontains $token.Substring(0, 2)) { continue }
+                if ($flagOptions[$subcommand] -ccontains $token) { continue }
+                break
+            }
+            $candidates = @(@($match.GlobalOptions) | Where-Object { $_.Name -ceq '-C' -and $_.Value } | ForEach-Object { [string]$_.Value })
+            $candidates += @(@($match.Operands) | Where-Object { $_ -match $absolutePattern -and $optionValues -cnotcontains $_ })
+            $candidates += @($walked | Where-Object { $_ -match $absolutePattern -and (Test-CommandLineTokenLiteral -Token $_) })
+            foreach ($candidate in $candidates) {
+                if ($paths -notcontains $candidate) { $paths.Add($candidate) }
+            }
+        }
+    }
+    return [string[]]$paths.ToArray()
+}
+
+function Resolve-OrchestrationGateTarget {
+    <#
+    .SYNOPSIS
+        Resolves the worktree whose checkpoint governs a single-feature path or command leg (issue #1010).
+    .DESCRIPTION
+        Calls Resolve-HookTargetWorktree with the recording invoker: a file path is passed as
+        -FilePath, the marker paths of an apply_patch body as -FilePath (markers in two
+        worktrees resolve as ambiguous), and any other command's
+        Get-OrchestrationGateCommandOperandPath result as -CommandOperandPath. A failed or
+        empty listing gives NoTarget instead of the session-root fallback; Ambiguous gives
+        Ambiguous; a null root gives NoTarget; otherwise SessionRoot or OtherWorktree.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with Status, WorktreeRoot, ReasonCode, and Detail.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $sessionRoot = (Get-Location).Path
+    $script:OrchestrationGateWorktreeListFailed = $false
+    $invoker = { param($SessionRoot) Invoke-OrchestrationGateWorktreeList -SessionRoot $SessionRoot }
+    $markerPaths = if ($FilePath) { @() } else { @(Get-OrchestrationPatchMarkerPath -PatchText ([string]$Command)) }
+    $resolved = if ($FilePath) {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -FilePath @($FilePath) -WorktreeListInvoker $invoker
+    } elseif ($markerPaths.Count -gt 0) {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -FilePath $markerPaths -WorktreeListInvoker $invoker
+    } else {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -CommandOperandPath @(Get-OrchestrationGateCommandOperandPath -Command ([string]$Command)) -WorktreeListInvoker $invoker
+    }
+    $detail = "resolver source $($resolved.Source): $($resolved.Detail)"
+    if ($script:OrchestrationGateWorktreeListFailed) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateNotDerivableReasonCode; Detail = "the worktree listing failed or named no worktree; $detail" }
+    }
+    if ($resolved.Ambiguous) {
+        return [pscustomobject]@{ Status = 'Ambiguous'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateAmbiguousReasonCode; Detail = $detail }
+    }
+    if ([string]::IsNullOrEmpty([string]$resolved.WorktreeRoot)) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateNotDerivableReasonCode; Detail = $detail }
+    }
+    $isSession = [string]::Equals([string]$resolved.WorktreeRoot, (ConvertTo-HookTargetWorktreeNormalizedPath -Path $sessionRoot), [System.StringComparison]::OrdinalIgnoreCase)
+    $status = if ($isSession) { 'SessionRoot' } else { 'OtherWorktree' }
+    return [pscustomobject]@{ Status = $status; WorktreeRoot = [string]$resolved.WorktreeRoot; ReasonCode = $null; Detail = $detail }
+}
+
+function Read-OrchestrationGateCheckpoint {
+    <#
+    .SYNOPSIS
+        Reads the checkpoint beneath the resolved target worktree, or returns the deny reason.
+    .DESCRIPTION
+        Resolved is $false, with DenyReason set, when the target is NoTarget or Ambiguous.
+        Otherwise Raw holds the checkpoint text (empty when absent) and Path its absolute
+        path, composed beneath the resolved root with a forward slash.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][string] $Mode,
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $target = Resolve-OrchestrationGateTarget -FilePath $FilePath -Command $Command
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return [pscustomobject]@{
+            Resolved   = $false
+            Raw        = ''
+            Path       = $null
+            DenyReason = ("PREIMPLEMENTATION_GATE_BLOCKED: $($target.ReasonCode): the target worktree of this $Mode call " +
+                "could not be resolved: $($target.Detail). Implementation operations require an identifiable target " +
+                'worktree whose checkpoint is ready.')
+        }
+    }
+
+    $path = ([string]$target.WorktreeRoot).TrimEnd('/') + '/artifacts/orchestration/orchestrator-state.json'
+    return [pscustomobject]@{
+        Resolved   = $true
+        Raw        = [string](Get-CheckpointContent -Path $path)
+        Path       = $path
+        DenyReason = $null
+    }
+}
+
 function Get-OrchestrationEpicScopeSelector {
     <#
     .SYNOPSIS

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -33,8 +33,6 @@ try { . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-e
 # Shared command-line parser (issue #545): per-segment scan text and structural matching.
 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 $_ }
-# The readiness checkpoint this gate reads and names in its block message.
-$script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
 # Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
 # of these is orchestration bookkeeping, not implementation, so the gate must not
@@ -270,7 +268,7 @@ function Test-OrchestrationReady {
     }
     $lifecycleReady = $false
     if ($Payload.PSObject.Properties.Name -contains 'lifecycle_ready') {
-        $lifecycleReady = [bool]$Payload.lifecycle_ready
+        $lifecycleReady = ($Payload.lifecycle_ready -is [bool]) -and $Payload.lifecycle_ready
     }
 
     if (-not $issueNum -or -not $featureFolder -or -not $routeId -or -not $lifecycleReady) {
@@ -284,17 +282,6 @@ function Test-OrchestrationReady {
     )
 }
 
-function Get-CheckpointContent {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:CheckpointPath)) {
-        return ''
-    }
-    return Get-Content -Raw -LiteralPath $script:CheckpointPath
-}
-
 function Get-OrchestrationPreimplementationGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -445,8 +432,12 @@ function Invoke-OrchestrationPreimplementationGateDecision {
             Get-OrchestrationModeDenyReason -Mode $mode -Failure $failure)
     }
 
+    # Truthiness fall-through is kept: an empty -CheckpointRaw resolves like an unbound one.
+    # The checkpoint is read beneath the worktree the call targets (issue #1010).
     if (-not $CheckpointRaw) {
-        $CheckpointRaw = Get-CheckpointContent
+        $read = Read-OrchestrationGateCheckpoint -Mode 'single-feature' -FilePath $filePath -Command $command
+        if (-not $read.Resolved) { return Get-OrchestrationPreimplementationGateBlockDecision -Reason $read.DenyReason }
+        $CheckpointRaw = $read.Raw
     }
     try {
         $checkpoint = ConvertFrom-CheckpointJson -Json $CheckpointRaw