@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.12

package/resources/claude-customizations/.claude/skills/quota-throttling/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: quota-throttling
+description: 'Quota throttling and account-switching policy for multi-agent orchestration. Use when pacing agent work against five-hour and seven-day usage limits, deciding whether and when to switch accounts, setting concurrency caps, forecasting a rate-limit wall, handling total weekly exhaustion, or designing a usage monitor. Covers account viability, failover-dependent pacing targets, the measured cost model, commit-before-the-wall, and the coordinator/agent division of labour.'
+---
+
+# Quota Throttling and Account-Switching Policy
+
+Policy for keeping long-running, multi-agent orchestration inside account usage limits without
+losing work. Derived from about five days of continuous multi-agent orchestration (TaskMaster runs
+`bugs-2026-09-11` and `bugs-2026-09-17`).
+
+Every figure marked **MEASURED** was observed; figures marked **ESTIMATE** are extrapolations.
+Cost figures are machine- and repository-specific. Re-measure before relying on them elsewhere.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- a coordinating session runs orchestrators, epic runs, or parallel runs that spawn subagents;
+- deciding whether to start, stagger, hold, or stop agent work because of usage limits;
+- choosing whether and when to switch between accounts;
+- a rate-limit wall is forecast, or every account is exhausted;
+- designing a monitor that watches usage or CI state.
+
+## Reading Quota
+
+The coordinator reads usage from the account switcher, for example `cswap list --json`. The
+fields each rule below depends on:
+
+| Field | Meaning |
+|---|---|
+| `accounts[].active` | Whether the account currently supplies credentials. |
+| `accounts[].usageStatus` | Must be `ok`; any other value makes the account non-viable. |
+| `usage.fiveHour.pct` | Five-hour window utilization, an integer percentage. |
+| `usage.fiveHour.resetsAt` | Authoritative ISO-8601 UTC reset time. `null` means the window has not started. |
+| `usage.sevenDay.pct` | Seven-day utilization, an integer percentage. |
+| `usage.sevenDay.resetsAt` | Authoritative ISO-8601 UTC weekly reset time. |
+| `usage.sevenDay.willLastToReset` | The switcher's own projection of whether the weekly budget lasts. |
+| `usage.*.clock`, `usage.*.countdown` | Human-readable display values. `clock` is LOCAL time; do not use it for arithmetic. |
+
+Some switchers switch automatically on the five-hour threshold alone and do not consult the
+seven-day window. Such a switcher can hand over to an account whose five-hour window has reset
+but whose weekly budget is spent. Apply section 1 yourself rather than relying on the switcher.
+
+## 1. Account Viability
+
+An account is a viable target only if BOTH hold:
+
+- seven-day usage < 95%
+- five-hour usage < 90%
+
+The weekly gate dominates. An account at >= 95% weekly is NOT a viable target regardless of its
+five-hour state, and must be excluded from all pacing math.
+
+The binding budget is `min(five-hour headroom to 90%, weekly headroom to 95%)`. Compute both every
+time. Late in a week the weekly headroom is usually the smaller number, and the five-hour window
+is then irrelevant.
+
+## 2. Pacing Target Depends on Whether a Failover Exists
+
+**Two or more viable accounts: front-load.** Target about 90% of the five-hour window in about
+2 hours (about 45% per hour). Reaching 90% triggers a switch, so the unused remainder of the
+window costs nothing.
+
+**Exactly one viable account: spread.** Target about 90% across the WHOLE five-hour window (about
+18% per hour). Front-loading here is wrong: reaching 90% at the 2-hour mark produces a stall of
+about 3 hours with no account to switch to.
+
+These are different policies, not different settings of one policy. Applying the two-account
+target to a one-account situation is the most expensive mistake observed (see section 12,
+item 1).
+
+## 3. Cost Model (MEASURED, Serialized Single Items)
+
+| Activity | Five-hour points | Weekly points | Wall clock |
+|---|---|---|---|
+| Coordination only (API calls, git, checkpoint writes, no agents) | ~3 total | negligible | — |
+| One item, full cycle (child + executor + toolchain + coverage run) | ~17 | ~3 | ~43 min |
+| One plan revision, or a low-cost item | ~4-5 | — | — |
+| Three items entering Phase 0 simultaneously | 96-108 per hour | — | a full five-hour window in 62 min |
+
+Builds and test runs consume wall-clock time but zero quota. A long quiet period at 0% per hour
+with agents alive usually means they are inside a build, not stalled.
+
+Ratio (ESTIMATE, two data points): one full five-hour window is about 14 weekly points.
+
+## 4. Concurrency Control
+
+A concurrency cap governs an orchestrator's DIRECT children. Each child spawns its own
+grandchildren (executors, planners, researchers), and those are the dominant consumers. Always
+express a cap as a budget on TOTAL AGENTS IN THE SUBTREE, and require that it be propagated
+verbatim to every level.
+
+A cap change only restricts NEW starts. It does nothing to work already running. Cutting a cap
+from 6 to 2 mid-flight changed the burn rate by zero, because the cost was in agents already
+alive.
+
+For in-flight burn there are exactly two controls:
+
+- **Commit-and-hold** — finish the current task, commit, start nothing new.
+- **Stopping agents outright** — destructive; use only as a last resort.
+
+**Stagger starts.** The dominant cost driver is not item count; it is simultaneous Phase 0
+cycles. Bring items in one at a time and let each settle before starting the next.
+
+## 5. Measurement Discipline
+
+- The usage percentage is an INTEGER. At 5-minute sampling the computed rate quantizes to
+  multiples of about 12% per hour. Do not react to a single sample; measure over spans of at
+  least 15 minutes.
+- The FIRST sample after an account switch is inflated by batched accounting. Take a second
+  reading before acting on it, but do not dismiss it either; it has been partly real more than
+  once.
+- Reset times: the human-readable `clock` field is LOCAL time. The ISO `resetsAt` field is
+  authoritative. Convert before doing arithmetic; a four-hour error from this changed a plan.
+- Five-hour window elapsed time = 300 − (minutes until reset). The window starts on first use,
+  not on a fixed clock boundary.
+- VERIFY a reset directly before resuming. Never infer it from the clock. A reset timestamp can
+  pass while the counter still reads the old value for a minute or two.
+
+## 6. Approaching a Wall
+
+Commit BEFORE the wall, not at it. A rate-limit error terminates an agent immediately; the agent
+does not wait out the gap and resume. The duration of the outage does not change this risk: even
+a 60-second gap terminates in-flight work.
+
+Sequence when a wall is forecast:
+
+1. Order all in-flight children to COMMIT NOW, in whatever state, without finishing the current
+   task. A committed partial result is recoverable; an uncommitted complete one is not.
+2. Let them keep working until the wall actually arrives.
+3. Set the commit checkpoint with real margin, and recompute it as the rate moves. A checkpoint
+   that lands ON the forecast wall protects nothing.
+
+Git operations are LOCAL and consume no model quota; they succeed on a fully exhausted account.
+If errors start before committing finishes, keep retrying the COMMIT specifically and nothing
+else.
+
+## 7. Total Weekly Exhaustion
+
+When no account is viable:
+
+1. **Serialize** — stop all parallel activity; zero new starts.
+2. **Commit ALL working documents across ALL worktrees** — every item worktree, the plan-home
+   worktree, and every in-flight child, not only the current item.
+3. **Report and hold.**
+
+This differs from a routine pause: the outage may last days, so nothing may be left uncommitted
+on the assumption of a quick return.
+
+## 8. Switching
+
+- Switch at 90% of the five-hour window IF a viable target exists.
+- If no viable target exists, do NOT switch; hold until the earliest reset. Switching onto an
+  exhausted account produces immediate failures.
+- Verify the switch landed (active account, both windows) before releasing work.
+- A mid-flight credential change is transparent to running agents. Instruct them explicitly not
+  to treat the change, or a brief error around it, as a failure signal.
+
+## 9. Usage Credits and Overage
+
+Never spend credits on work. The ONLY sanctioned use is completing a non-destructive
+serialization and commit so that work is not lost. If any path offers to continue past a limit
+by consuming credits, stop and ask the user.
+
+## 10. Reserve Policy
+
+Holding an account's last few points as an emergency commit reserve is correct ONLY while
+something is uncommitted. Verify first: if every branch is pushed and every worktree is clean,
+the reserve protects nothing and should be spent on useful work instead. Check before assuming.
+
+## 11. Monitor Design
+
+Report on thresholds, not on every sample. An idle monitor that fires every ten minutes costs a
+turn each time and hides the signal among routine readings.
+
+**A check for the ABSENCE of a bad state is satisfied by the absence of ALL state.** A CI waiter
+polling for "no pending checks" reported SETTLED during the window between one run being
+superseded and the next registering, when no checks existed at all. Require a POSITIVE assertion
+instead: a conjunction that an empty set cannot satisfy (for example, "at least one required check
+exists AND none is pending").
+
+Alert on:
+
+- threshold crossings;
+- a sustained rate above target;
+- a non-`ok` status;
+- account-viability changes;
+- window rollovers.
+
+Stay silent otherwise.
+
+## 12. Observed Failure Modes
+
+1. Applying the two-account front-load target with only one viable account.
+   Cost: about 95 minutes of idle time.
+2. Cutting a concurrency cap to control burn from work already running.
+   Cost: none directly, but the effective control went unused while the window drained.
+3. Launching multiple items into simultaneous Phase 0.
+   Cost: a full five-hour window in 62 minutes.
+4. Assuming a fallback account was fresh without checking.
+   Cost: about 1 hour, and seven items' preparation output stranded uncommitted when agents were
+   terminated.
+5. Setting a commit checkpoint that landed on the forecast wall instead of before it.
+6. Reacting to single 5-minute samples inside the quantization band, producing cap oscillation
+   that achieved nothing.
+
+## 13. Division of Labour
+
+An orchestrating agent generally CANNOT see quota. Do not ask it to estimate usage. The workable
+split is:
+
+- the **agent** reports its COST PROFILE: how many agents are alive, what kind of work they are
+  doing, and what it is about to start;
+- the **coordinator** supplies the MEASUREMENT and the decision.
+
+Have the agent announce before starting each item, and reply with a live reading.
+
+Corollary: if the coordinator is slow to respond, the agent should proceed on its own rather than
+stall. A four-hour idle period occurred because an agent correctly held for a ruling that was
+never sent. Absorbing a small pacing error is preferable to repeating that.

package/resources/claude-customizations/pack-manifests/core.json

@@ -27,12 +27,14 @@
     ".claude/hooks/enforce-discovery-artifact-gate.ps1",
     ".claude/hooks/enforce-epic-invocation-origin.ps1",
     ".claude/hooks/enforce-epic-merge-gate.ps1",
+    ".claude/hooks/enforce-epic-merge-gate-authorization.ps1",
     ".claude/hooks/enforce-epic-wave-barrier.ps1",
     ".claude/hooks/enforce-epic-worktree-removal-gate.ps1",
     ".claude/hooks/enforce-evidence-locations.ps1",
     ".claude/hooks/enforce-feature-folder-order.ps1",
     ".claude/hooks/enforce-model-routing-receipt.ps1",
     ".claude/hooks/enforce-orchestration-preimplementation-gate.ps1",
+    ".claude/hooks/enforce-orchestration-preimplementation-gate-epic-scope.ps1",
     ".claude/hooks/enforce-orchestration-preimplementation-gate-helpers.ps1",
     ".claude/hooks/enforce-orchestration-preimplementation-gate-modes.ps1",
     ".claude/hooks/enforce-parallel-abandon-gate.ps1",
@@ -44,6 +46,7 @@
     ".claude/hooks/enforce-pr-author-skill.epic-base-branch.ps1",
     ".claude/hooks/enforce-pr-author-skill.ps1",
     ".claude/hooks/enforce-pr-author-skill-helpers.ps1",
+    ".claude/hooks/enforce-prd-feature-before-planner-helpers.ps1",
     ".claude/hooks/enforce-prd-feature-before-planner.ps1",
     ".claude/hooks/enforce-promotion-mcp-only.ps1",
     ".claude/hooks/hook-command-invocation.ps1",
@@ -103,6 +106,7 @@
     ".claude/skills/pr-author/SKILL.md",
     ".claude/skills/pr-base-branch-merge-base/SKILL.md",
     ".claude/skills/pr-context-artifacts/SKILL.md",
+    ".claude/skills/quota-throttling/SKILL.md",
     ".claude/skills/remediation-handoff-atomic-planner/SKILL.md",
     ".claude/skills/research-issue/SKILL.md",
     ".claude/skills/review-epic/SKILL.md",
@@ -163,6 +167,11 @@
     ".claude/lib/mermaid/MermaidLineScanner.psm1",
     ".claude/lib/mermaid/MermaidMarkdownFences.psm1",
     ".claude/lib/mermaid/MermaidValidation.psm1",
+    ".claude/lib/worktree-resolution/WorktreeResolution.psm1",
+    ".claude/lib/worktree-resolution/WorktreeTargetResolution.psm1",
+    ".claude/lib/worktree-resolution/WorktreeItemResolution.psm1",
+    ".claude/lib/worktree-resolution/EpicScopeResolution.psm1",
+    ".claude/lib/worktree-resolution/EpicScopeReadiness.psm1",
     ".claude/skills/mermaid-diagram/references/flowchart.md",
     ".claude/skills/mermaid-diagram/references/sequence.md",
     ".claude/skills/mermaid-diagram/references/class.md",

package/resources/codex-and-agents-customizations/.agents/skills/codex-model-routing/SKILL.md

@@ -16,7 +16,7 @@ agent profile.
 2. Run the canonical topology resolver before choosing a logical agent:
 
    ```powershell
-   poetry run python -m scripts.dev_tools.resolve_codex_topology `
+   pwsh -NoProfile -File .codex/scripts/Resolve-CodexTopology.ps1 `
      --language <python|powershell|csharp|typescript> `
      --production-file-count <count> `
      --test-file-count <count> `
@@ -53,7 +53,7 @@ epic root personas are forced independently of file count.
 5. Run the canonical resolver:
 
    ```powershell
-   poetry run python -m scripts.dev_tools.resolve_codex_deployment `
+   pwsh -NoProfile -File .codex/scripts/Resolve-CodexDeployment.ps1 `
      --logical-agent <agent> `
      --complexity-band <C1|C2|C3|C4> `
      --execution-context <context> `
@@ -96,15 +96,14 @@ incomplete, and request a policy change. Do not silently fall back.
 ## Validation
 
 Before accepting delegated results or reporting completion, validate the
-checkpoint with the Codex routing gate:
-
-```powershell
-poetry run python -m scripts.dev_tools.validate_orchestration_artifacts `
-  orchestrator-state artifacts/orchestration/orchestrator-state.json `
-  --require-codex-topology `
-  --require-codex-model-routing
-```
-
-For epic execution use `epic-orchestrator-state` with the same flag. The MCP
-`validate_orchestration_artifacts` surface is the authoritative completion gate
-when available.
+checkpoint with the Codex routing gate by calling the MCP tool
+`validate_orchestration_artifacts` with these arguments:
+
+- `artifact_type`: `orchestrator-state` (use `epic-orchestrator-state` for epic
+  execution)
+- `artifact_path`: `artifacts/orchestration/orchestrator-state.json`
+- `workspace_root`: the repository root
+- `require_codex_topology`: `true`
+- `require_codex_model_routing`: `true`
+
+The MCP tool is the authoritative completion gate and needs no Python toolchain.

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -2,7 +2,7 @@ default_permissions = ":danger-full-access"
 
 [mcp_servers.drm-copilot]
 command = "npx"
-args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.11"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.12"]
 required = true
 enabled_tools = [
     "collect_commit_context",

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-merge-gate.ps1

@@ -11,6 +11,14 @@ param()
 . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
 . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
 
+# Reason codes for the standalone-merge authorization branch (issue #670), spelled
+# byte-identically to the Claude helpers file. Each of the four assignments below is the only
+# place its code literal appears in this file.
+$script:CodexStandaloneAbsentReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_ABSENT'
+$script:CodexStandalonePrMismatchReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_PR_MISMATCH'
+$script:CodexStandaloneMalformedReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_MALFORMED'
+$script:CodexStandaloneNotPrSpecificReasonCode = 'STANDALONE_MERGE_AUTHORIZATION_NOT_PR_SPECIFIC'
+
 function ConvertFrom-CodexMergeJson {
     [CmdletBinding()]
     param([AllowNull()][AllowEmptyString()][string] $Raw, [Parameter(Mandatory)][string] $Name, [switch] $Optional)
@@ -155,6 +163,24 @@ function Invoke-CodexEpicMergeDecision {
         return $null
     }
 
+    # Standalone branch (issue #670), evaluated last and only for an explicit PR number: a
+    # PR-specific authorization record bound to the payload session. Its deny keeps the gate
+    # token first.
+    if ($null -ne $prNumber) {
+        $sessionId = [string]$payload.session_id
+        $verdict = Test-CodexStandaloneMergeAuthorization -Checkpoints @($child, $epic) -CommandPrNumber $prNumber -SessionId $sessionId
+        if ($verdict.Allowed) {
+            return $null
+        }
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = 'EPIC_MERGE_GATE_BLOCKED: ' + $verdict.ReasonCode + ': ' + $verdict.Message
+            }
+        }
+    }
+
     return [ordered]@{
         hookSpecificOutput = [ordered]@{
             hookEventName            = 'PreToolUse'
@@ -164,6 +190,173 @@ function Invoke-CodexEpicMergeDecision {
     }
 }
 
+function Test-CodexStandalonePositiveInteger {
+    <#
+    .SYNOPSIS
+        Report whether a parsed JSON value is an integer greater than zero; a digit string fails.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()] $Value)
+
+    return (($Value -is [int] -or $Value -is [long]) -and $Value -gt 0)
+}
+
+function Test-CodexStandaloneText {
+    <#
+    .SYNOPSIS
+        Report whether a value is a string whose trimmed length reaches a minimum.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()] $Value, [int] $MinimumLength = 1)
+
+    return ($Value -is [string] -and $Value.Trim().Length -ge $MinimumLength)
+}
+
+function Get-CodexStandaloneField {
+    <#
+    .SYNOPSIS
+        Read a named field off a parsed record, or $null; the unary comma keeps a
+        one-element array from unrolling into its scalar.
+    #>
+    [CmdletBinding()]
+    [OutputType([object], [object[]])]
+    param([Parameter(Mandatory)] $Record, [Parameter(Mandatory)][string] $Name)
+
+    $property = $Record.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+    return , $property.Value
+}
+
+function Get-CodexStandaloneRecordFailure {
+    <#
+    .SYNOPSIS
+        Return the first failing field of a matched record, or $null when every check passes.
+    .DESCRIPTION
+        Uses the same fixed order as the Claude helpers file: pr_url, issue_num, branch_name,
+        authorized_by, authorized_at, basis, run_slug, session_id. branch_name is checked for
+        presence only. A blank payload session fails closed.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)] $Record, [AllowNull()][AllowEmptyString()][string] $SessionId)
+
+    $prUrl = Get-CodexStandaloneField -Record $Record -Name 'pr_url'
+    if (-not (Test-CodexStandaloneText -Value $prUrl) -or
+        -not $prUrl.EndsWith('/pull/' + [string]$Record.pr_number, [System.StringComparison]::Ordinal)) {
+        return 'pr_url'
+    }
+    if (-not (Test-CodexStandalonePositiveInteger -Value (Get-CodexStandaloneField -Record $Record -Name 'issue_num'))) {
+        return 'issue_num'
+    }
+    foreach ($name in @('branch_name', 'authorized_by')) {
+        if (-not (Test-CodexStandaloneText -Value (Get-CodexStandaloneField -Record $Record -Name $name))) {
+            return $name
+        }
+    }
+    $authorizedAt = Get-CodexStandaloneField -Record $Record -Name 'authorized_at'
+    $parsedAt = [DateTime]::MinValue
+    $timestampValid = $authorizedAt -is [DateTime] -or $authorizedAt -is [DateTimeOffset]
+    if (-not $timestampValid -and (Test-CodexStandaloneText -Value $authorizedAt)) {
+        $timestampValid = [DateTime]::TryParse(
+            $authorizedAt,
+            [System.Globalization.CultureInfo]::InvariantCulture,
+            [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal,
+            [ref] $parsedAt)
+    }
+    if (-not $timestampValid) {
+        return 'authorized_at'
+    }
+    if (-not (Test-CodexStandaloneText -Value (Get-CodexStandaloneField -Record $Record -Name 'basis') -MinimumLength 20)) {
+        return 'basis'
+    }
+    if ($null -ne $Record.PSObject.Properties['run_slug'] -and
+        -not (Test-CodexStandaloneText -Value (Get-CodexStandaloneField -Record $Record -Name 'run_slug'))) {
+        return 'run_slug'
+    }
+    $recordSession = Get-CodexStandaloneField -Record $Record -Name 'session_id'
+    if (-not (Test-CodexStandaloneText -Value $recordSession) -or
+        [string]::IsNullOrWhiteSpace($SessionId) -or
+        -not [string]::Equals($recordSession, $SessionId, [System.StringComparison]::Ordinal)) {
+        return 'session_id'
+    }
+    return $null
+}
+
+function Test-CodexStandaloneMergeAuthorization {
+    <#
+    .SYNOPSIS
+        Codex counterpart of the Claude standalone-merge authorization predicate.
+    .DESCRIPTION
+        Evaluates the parsed child and epic checkpoints with the same activation condition
+        as the Claude side: a PR-specific record naming CommandPrNumber, with well-formed
+        fields and a session_id equal to the payload session. Returns an object whose
+        Allowed member is $true on success, or $false with ReasonCode and Message.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][AllowEmptyCollection()][object[]] $Checkpoints,
+        [Parameter(Mandatory)][int] $CommandPrNumber,
+        [AllowNull()][AllowEmptyString()][string] $SessionId
+    )
+
+    $key = 'standalone_merge_authorizations'
+    $present = $false
+    $specific = $true
+    $match = $null
+    foreach ($checkpoint in @($Checkpoints)) {
+        if ($checkpoint -isnot [System.Management.Automation.PSCustomObject] -or
+            $null -eq $checkpoint.PSObject.Properties[$key]) {
+            continue
+        }
+        $present = $true
+        $block = $checkpoint.PSObject.Properties[$key].Value
+        if ($block -isnot [System.Array] -or $block.Count -eq 0) {
+            $specific = $false
+            continue
+        }
+        foreach ($entry in $block) {
+            $number = $null
+            if ($entry -is [System.Management.Automation.PSCustomObject]) {
+                $number = Get-CodexStandaloneField -Record $entry -Name 'pr_number'
+            }
+            if (-not (Test-CodexStandalonePositiveInteger -Value $number)) {
+                $specific = $false
+            } elseif ($null -eq $match -and $number -eq $CommandPrNumber) {
+                $match = $entry
+            }
+        }
+    }
+
+    if (-not $present) {
+        $code = $script:CodexStandaloneAbsentReasonCode
+        $message = 'no orchestrator checkpoint carries an authorization record, but an authorized standalone merge path exists.'
+    } elseif (-not $specific) {
+        $code = $script:CodexStandaloneNotPrSpecificReasonCode
+        $message = 'an orchestrator checkpoint carries the authorization key but names no specific pull request; a blanket flag is not an authorization record.'
+    } elseif ($null -eq $match) {
+        $code = $script:CodexStandalonePrMismatchReasonCode
+        $message = "authorization records exist, but none names pull request $CommandPrNumber."
+    } else {
+        $field = Get-CodexStandaloneRecordFailure -Record $match -SessionId $SessionId
+        if ($null -eq $field) {
+            return [pscustomobject]@{ Allowed = $true; ReasonCode = $null; Message = $null }
+        }
+        $code = $script:CodexStandaloneMalformedReasonCode
+        $message = "the matched authorization record has an invalid '$field'."
+    }
+
+    return [pscustomobject]@{
+        Allowed    = $false
+        ReasonCode = $code
+        Message    = "$message To authorize a standalone merge, write a $key record naming this pull request and the current session_id into an orchestrator checkpoint, as described in .claude/rules/orchestrator-state.md."
+    }
+}
+
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-planning-only.ps1

@@ -83,9 +83,6 @@ function Get-EpicPlanningRegisteredMcpTool {
 }
 
 $script:EpicPlanningRepositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
-$script:AllowedPreparationSemanticMcpTools = @(Get-EpicPlanningRegisteredMcpTool `
-        -RegistryPath (Join-Path $script:EpicPlanningRepositoryRoot 'config/orchestration-handoff-registry.json') `
-        -SemanticIds $script:PreparationSemanticMcpIds)
 
 function Get-EpicPlanningDenyDecision {
     [CmdletBinding()]
@@ -209,7 +206,8 @@ function Invoke-EpicPlanningOnlyDecision {
         [AllowNull()][AllowEmptyString()][string] $CheckpointRaw,
         [AllowNull()][AllowEmptyString()][string] $EpicExecutionContext,
         [AllowNull()][string[]] $StagedPaths,
-        [AllowNull()][AllowEmptyString()][string] $CurrentBranch
+        [AllowNull()][AllowEmptyString()][string] $CurrentBranch,
+        [string] $RegistryPath = (Join-Path $script:EpicPlanningRepositoryRoot 'config/orchestration-handoff-registry.json')
     )
 
     $payload = ConvertFrom-EpicPlanningJson -Raw $PayloadRaw -Name 'PreToolUse input'
@@ -269,8 +267,20 @@ function Invoke-EpicPlanningOnlyDecision {
         return Get-EpicPlanningDenyDecision -Reason 'the Bash command is outside the preparation read, branch, commit, push, or validator allowlist.'
     }
 
+    # Lifecycle tools are decided first and never need the registry. Only a
+    # registry-dependent mcp__ call reads it, so a destination without the
+    # registry keeps every other decision and fails closed for semantic MCP.
     $allowedRepositoryMcp = $script:AllowedPreparationMcpTools -contains $toolName
-    $allowedSemanticMcp = $script:AllowedPreparationSemanticMcpTools -contains $toolName
+    $allowedSemanticMcp = $false
+    if (-not $allowedRepositoryMcp -and $toolName -like 'mcp__*') {
+        if (-not (Test-Path -LiteralPath $RegistryPath -PathType Leaf)) {
+            return Get-EpicPlanningDenyDecision -Reason "semantic MCP registry '$RegistryPath' does not exist; registry-dependent MCP tool '$toolName' is denied in preparation mode."
+        }
+        $registeredSemanticMcp = @(Get-EpicPlanningRegisteredMcpTool `
+                -RegistryPath $RegistryPath `
+                -SemanticIds $script:PreparationSemanticMcpIds)
+        $allowedSemanticMcp = $registeredSemanticMcp -contains $toolName
+    }
     if ($allowedRepositoryMcp -or $allowedSemanticMcp) {
         if ($attestedPreparation) {
             $workspaceRoot = [string]$payload.tool_input.workspace_root