@danmoisan/drm-copilot-mcp 1.0.7 → 1.0.8

package/out/mcp-server.js

@@ -16208,6 +16208,10 @@ var REPO_AUTOMATION_TOOL_DEFINITIONS = [
         require_complete: {
           type: "boolean",
           description: "When true and artifact_type is 'orchestrator-state', require all phases to be complete."
+        },
+        require_model_routing: {
+          type: "boolean",
+          description: "When true and artifact_type is 'orchestrator-state', require a model_routing_receipts entry per delegated agent once a delegation is recorded. The TypeScript side performs the existence check only; the Python validator is authoritative for full per-receipt correctness."
         }
       },
       required: ["artifact_type", "artifact_path"],
@@ -16597,6 +16601,7 @@ function resolveValidateOrchestrationArtifactsToolInput(rawInput, fallbackWorksp
     );
   }
   const requireComplete = args["require_complete"];
+  const requireModelRouting = args["require_model_routing"];
   return {
     workspaceRoot: normalizeWorkspaceRoot(
       args["workspace_root"],
@@ -16604,7 +16609,8 @@ function resolveValidateOrchestrationArtifactsToolInput(rawInput, fallbackWorksp
     ),
     artifactType,
     artifactPath: normalizeRequiredText(args["artifact_path"], "artifact_path"),
-    ...requireComplete === true ? { requireComplete: true } : {}
+    ...requireComplete === true ? { requireComplete: true } : {},
+    ...requireModelRouting === true ? { requireModelRouting: true } : {}
   };
 }
 
@@ -22519,6 +22525,14 @@ var STEP_STATUS_KEYS = [
   "step9_status",
   "step10_status"
 ];
+var DELEGATING_AGENTS = /* @__PURE__ */ new Set([
+  "atomic-planner",
+  "atomic-executor",
+  "feature-review",
+  "task-researcher",
+  "prd-feature",
+  "pr-author"
+]);
 function isObject7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -22582,6 +22596,53 @@ function resolveRoutingMatrix(options) {
   }
   return void 0;
 }
+function delegatedAgents(stateMap) {
+  const agents = /* @__PURE__ */ new Set();
+  const receipts = stateMap["delegation_receipts"];
+  if (Array.isArray(receipts)) {
+    receipts.forEach((receipt) => {
+      if (!isObject7(receipt)) {
+        return;
+      }
+      const agentName = receipt["agent_name"];
+      if (typeof agentName === "string" && agentName.trim() !== "") {
+        agents.add(agentName);
+      }
+    });
+  }
+  const nextStep = stateMap["next_step"];
+  if (typeof nextStep === "string" && DELEGATING_AGENTS.has(nextStep)) {
+    agents.add(nextStep);
+  }
+  return agents;
+}
+function validateModelRoutingExistence(stateMap) {
+  const errors = [];
+  const delegated = delegatedAgents(stateMap);
+  if (delegated.size === 0) {
+    return errors;
+  }
+  const receiptAgents2 = /* @__PURE__ */ new Set();
+  const receipts = stateMap["model_routing_receipts"];
+  if (Array.isArray(receipts)) {
+    receipts.forEach((receipt) => {
+      if (!isObject7(receipt)) {
+        return;
+      }
+      const agent = receipt["agent"];
+      if (typeof agent === "string" && agent.trim() !== "") {
+        receiptAgents2.add(agent);
+      }
+    });
+  }
+  const missing = [...delegated].filter((a) => !receiptAgents2.has(a)).sort();
+  for (const agent of missing) {
+    errors.push(
+      `Checkpoint model_routing_receipts is missing a receipt for delegated agent: ${agent}.`
+    );
+  }
+  return errors;
+}
 function validateOrchestratorStateText(text, options = {}) {
   const errors = [];
   let state;
@@ -22655,6 +22716,9 @@ function validateOrchestratorStateText(text, options = {}) {
       })
     );
   }
+  if (options.requireModelRouting === true) {
+    errors.push(...validateModelRoutingExistence(stateMap));
+  }
   return errors;
 }
 
@@ -23029,6 +23093,7 @@ function validateArtifact(input) {
     case "orchestrator-state": {
       const options = {
         ...input.requireComplete === void 0 ? {} : { requireComplete: input.requireComplete },
+        ...input.requireModelRouting === void 0 ? {} : { requireModelRouting: input.requireModelRouting },
         ...input.fs === void 0 ? {} : { fs: input.fs },
         ...input.root === void 0 ? {} : { root: input.root },
         ...input.routingMatrix === void 0 ? {} : { routingMatrix: input.routingMatrix }
@@ -23056,6 +23121,7 @@ function validateOrchestrationServiceCall(input) {
     artifactType: input.artifactType,
     text,
     ...input.requireComplete === void 0 ? {} : { requireComplete: input.requireComplete },
+    ...input.requireModelRouting === void 0 ? {} : { requireModelRouting: input.requireModelRouting },
     fs: input.fileSystem,
     root: input.workspaceRoot
   });
@@ -23072,6 +23138,18 @@ ${errors.join("\n")}`
   };
 }
 
+// ../../extensions/drm-copilot/src/lib/validate/build-validate-orchestration-service-call-input.ts
+function buildValidateOrchestrationServiceCallInput(fileSystem, input) {
+  return {
+    fileSystem,
+    workspaceRoot: input.workspaceRoot,
+    artifactType: input.artifactType,
+    artifactPath: input.artifactPath,
+    ...input.requireComplete === void 0 ? {} : { requireComplete: input.requireComplete },
+    ...input.requireModelRouting === void 0 ? {} : { requireModelRouting: input.requireModelRouting }
+  };
+}
+
 // ../../extensions/drm-copilot/src/lib/new-potential-bug-entry.ts
 var fs5 = __toESM(require("node:fs"));
 var nodePath4 = __toESM(require("node:path"));
@@ -27713,13 +27791,9 @@ var DefaultRepoAutomationService = class {
     });
   }
   async validateOrchestrationArtifacts(input) {
-    return validateOrchestrationServiceCall({
-      fileSystem: this.fileSystem,
-      workspaceRoot: input.workspaceRoot,
-      artifactType: input.artifactType,
-      artifactPath: input.artifactPath,
-      ...input.requireComplete === void 0 ? {} : { requireComplete: input.requireComplete }
-    });
+    return validateOrchestrationServiceCall(
+      buildValidateOrchestrationServiceCallInput(this.fileSystem, input)
+    );
   }
   async executeScript(options) {
     const execution = await executeBundledScriptFromExtensionRoot(this.output, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/agents/atomic-executor.md

@@ -1,5 +1,6 @@
 ---
 name: atomic-executor
+model: opus
 description: Plan execution agent that runs approved atomic plans task-by-task with explicit toolchain commands for Python, TypeScript, PowerShell, and C# quality gates.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/atomic-planner.md

@@ -1,5 +1,6 @@
 ---
 name: atomic-planner
+model: opus
 description: Planning-only agent that generates deterministic phased implementation plans with atomic P#-T# checkbox tasks, writing output to docs/ and artifacts/ paths only.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/csharp-typed-engineer.md

@@ -1,5 +1,6 @@
 ---
 name: csharp-typed-engineer
+model: sonnet
 description: Project-scoped worker that implements and verifies C# changes within typed repository boundaries. Applies the CSharpier -> .NET Analyzers -> Nullable Analysis -> xUnit toolchain, the 1-3 production-file small-path budget, and zero-regression quality gates.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/epic-orchestrator.md

@@ -1,5 +1,6 @@
 ---
 name: epic-orchestrator
+model: opus
 description: Deterministic epic-scale orchestrator that schedules a dependency graph of child features across parallel, isolated git worktrees, fans results back into a shared integration branch, and drives the final integration-to-main PR. Distinct from orchestrator; only this agent is authorized to delegate to Agent(orchestrator).
 tools:
   - "Agent(orchestrator)"

package/resources/claude-customizations/.claude/agents/epic-review.md

@@ -1,5 +1,6 @@
 ---
 name: epic-review
+model: opus
 description: Project-scoped worker that reviews epic folders and writes epic-audit artifacts.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/feature-review.md

@@ -1,5 +1,6 @@
 ---
 name: feature-review
+model: opus
 description: Feature branch review specialist that produces policy-audit, code-review, and feature-audit artifacts restricted to docs/features/active/ write path.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 name: orchestrator
+model: opus
 description: Deterministic repository orchestrator that estimates change budget, selects small or large workflow path, delegates to specialist subagents, persists checkpoint state, and enforces completion gates proactively.
 tools:
   - "Agent(atomic-planner,atomic-executor,feature-review,task-researcher,prd-feature,staged-review,epic-review,status-updater,pr-author,commit-message,human-exception-runbook,python-typed-engineer,powershell-typed-engineer,csharp-typed-engineer,typescript-engineer)"
@@ -56,6 +57,18 @@ On every invocation:
 4. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`.
 5. If no checkpoint exists or the objective is new, begin from change-budget estimation.
 
+### Model-choice reconciliation on resume
+
+When the resumed `next_step` is a delegating step, repair a missing model choice deterministically before delegating (this mirrors `## Checkpoint Handling` in `.claude/skills/orchestrate/SKILL.md`):
+
+a. Run the orchestrator-state validator with `--require-model-routing` before the first delegation and record a `model_routing_preflight` block `{ status ("pass"|"fail"), checked_at, validator_command, output_summary }`.
+b. Recompute the upcoming phase's floor with `compute_complexity_floor(signals_present)` (no reimplementation).
+c. Record a `complexity_assessments[]` entry `{ phase, band, floor, signals_present[], rationale, assessed_at }` with `floor` equal to the recomputed value and `band >= floor`.
+d. Resolve the model with `resolve_delegation_model(agent, complexity_band, fable_policy)` and record a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`.
+e. Persist the checkpoint, then delegate with `model` equal to the receipt's `model`.
+
+The orchestrator MUST NOT delegate at a delegating `next_step` while `model_routing_preflight` status is `fail`; it repairs the missing choice (steps b-e) and re-preflights until the status is `pass`.
+
 ## Change Budget Routing
 
 The first action is always to estimate the change budget by identifying likely affected production files and tests:

package/resources/claude-customizations/.claude/agents/powershell-typed-engineer.md

@@ -1,5 +1,6 @@
 ---
 name: powershell-typed-engineer
+model: sonnet
 description: Project-scoped worker that implements and verifies PowerShell changes within typed repository boundaries. Applies PoshQC format -> PSScriptAnalyzer -> Pester toolchain, the 1-2 production-file direct-mode budget, the 3-production + 3-test per-batch cap, and zero-regression quality gates.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/prd-feature.md

@@ -1,5 +1,6 @@
 ---
 name: prd-feature
+model: opus
 description: Project-scoped worker that produces feature-document outputs from issue and research context.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/python-typed-engineer.md

@@ -1,5 +1,6 @@
 ---
 name: python-typed-engineer
+model: sonnet
 description: Project-scoped worker that implements and verifies Python changes within typed repository boundaries. Applies the Black -> Ruff -> Pyright -> Pytest toolchain, the 3-production + 3-test per-batch budget, and zero-regression quality gates.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/staged-review.md

@@ -1,5 +1,6 @@
 ---
 name: staged-review
+model: opus
 description: Project-scoped worker that reviews staged diffs and writes staged-review artifacts.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/status-updater.md

@@ -1,5 +1,6 @@
 ---
 name: status-updater
+model: haiku
 description: Project-scoped worker that reconciles plan and issue status and writes status-sync artifacts.
 tools:
   - Read

package/resources/claude-customizations/.claude/agents/typescript-engineer.md

@@ -1,5 +1,6 @@
 ---
 name: typescript-engineer
+model: sonnet
 description: Project-scoped worker that implements and verifies TypeScript changes within typed repository boundaries.
 tools:
   - Read

package/resources/claude-customizations/.claude/hooks/enforce-model-routing-receipt.ps1

@@ -0,0 +1,182 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks a delegation to a gated subagent when the
+    orchestrator checkpoint records no model-routing receipt for that agent.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the Agent (Task) tool. Reads
+    tool input JSON from the CLAUDE_TOOL_INPUT environment variable and the
+    orchestrator checkpoint from artifacts/orchestration/orchestrator-state.json.
+
+    The hook enforces presence only: it cannot read the delegate's chosen
+    `model` (no `model` field is exposed in the tool input), so it verifies that
+    a `model_routing_receipts[]` entry already exists for the target
+    `subagent_type`. Correctness of the recorded model stays with the
+    authoritative Python validator.
+
+    Gated subagent types are the Agent-tool delegates that participate in model
+    selection: atomic-planner, atomic-executor, feature-review, task-researcher,
+    prd-feature, pr-author. The `orchestrator` type is deliberately excluded: it
+    is the calling agent, not a subagent delegated via the Agent tool, so it is
+    never a receipt-gated `subagent_type`.
+
+    Allow-through (graceful allow) applies to a non-delegating `subagent_type`,
+    empty or absent tool input, and malformed tool-input JSON.
+
+    The checkpoint read goes through Get-ModelRoutingCheckpoint so tests can
+    inject a synthetic checkpoint without touching disk.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only presence-gating deterrent.
+#>
+[CmdletBinding()]
+param()
+
+function Get-ModelRoutingCheckpoint {
+    <#
+    .SYNOPSIS
+        Returns the parsed orchestrator checkpoint object, or $null when the
+        file is missing or not valid JSON. Tests mock this seam.
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    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
+        return $raw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return $null
+    }
+}
+
+function Get-ModelRoutingGatedAgent {
+    <#
+    .SYNOPSIS
+        Returns the set of subagent types that are receipt-gated: the Agent-tool
+        delegates that participate in model selection. `orchestrator` is
+        excluded because it is the caller, not a delegated subagent.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param()
+
+    return [string[]] @(
+        'atomic-planner',
+        'atomic-executor',
+        'feature-review',
+        'task-researcher',
+        'prd-feature',
+        'pr-author'
+    )
+}
+
+function Test-ModelRoutingReceiptPresent {
+    <#
+    .SYNOPSIS
+        Returns $true when the checkpoint carries a model_routing_receipts entry
+        whose agent equals the target subagent type.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Checkpoint,
+
+        [Parameter(Mandatory)]
+        [string] $Subagent
+    )
+
+    if ($null -eq $Checkpoint) {
+        return $false
+    }
+    if ($Checkpoint.PSObject.Properties.Name -notcontains 'model_routing_receipts') {
+        return $false
+    }
+
+    # Scan every receipt for one whose agent matches the delegated subagent type.
+    foreach ($receipt in @($Checkpoint.model_routing_receipts)) {
+        if ($null -eq $receipt) {
+            continue
+        }
+        if ($receipt.PSObject.Properties.Name -contains 'agent' -and
+            [string]$receipt.agent -eq $Subagent) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Invoke-ModelRoutingReceiptDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision object.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    $allow = [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+
+    # Empty or absent tool input is not a delegation this hook can gate.
+    if (-not $ToolInputRaw) {
+        return $allow
+    }
+
+    # Malformed tool-input JSON is allowed through gracefully; this hook is a
+    # deterrent, not the authoritative validator.
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return $allow
+    }
+
+    $subagent = [string]$toolInput.subagent_type
+
+    # Only the gated Agent-tool delegates are receipt-checked; any other
+    # subagent_type (including orchestrator) passes through.
+    if (-not $subagent -or ((Get-ModelRoutingGatedAgent) -notcontains $subagent)) {
+        return $allow
+    }
+
+    $checkpoint = Get-ModelRoutingCheckpoint
+    if (Test-ModelRoutingReceiptPresent -Checkpoint $checkpoint -Subagent $subagent) {
+        return $allow
+    }
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = "MODEL_ROUTING_RECEIPT_BLOCKED: cannot delegate to '$subagent' before a model_routing_receipts entry for it is recorded in the orchestrator checkpoint. Perform Model Selection (record the complexity assessment and routing receipt) before delegating."
+        }
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-ModelRoutingReceiptDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+exit 0

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

@@ -180,7 +180,7 @@ function Invoke-RoutingContractValidation {
         [scriptblock] $Invoker = {
             param($Path, $Type)
             $output = & python -m scripts.dev_tools.validate_orchestration_artifacts `
-                $Type $Path --require-complete 2>&1
+                $Type $Path --require-complete --require-model-routing 2>&1
             [pscustomobject]@{
                 ExitCode = $LASTEXITCODE
                 Output   = ($output | Out-String)
@@ -293,6 +293,14 @@ function Invoke-OrchestratorOutputValidation {
     }
     $routingResult = Invoke-RoutingContractValidation @routingArgs
     if ($routingResult.HasErrors) {
+        # One subprocess call now covers both --require-complete and
+        # --require-model-routing. Surface a model-routing gate failure under its
+        # own block reason (its errors name model_routing_receipts or
+        # complexity_assessments); otherwise fall back to the routing-contract
+        # block reason for a generic completion/routing failure.
+        if ($routingResult.ErrorText -match 'model_routing_receipts|complexity_assessments') {
+            return @{ Ok = $false; Message = "MODEL_ROUTING_BLOCKED: $($routingResult.ErrorText)" }
+        }
         return @{ Ok = $false; Message = "ROUTING_CONTRACT_BLOCKED: $($routingResult.ErrorText)" }
     }
 

package/resources/claude-customizations/.claude/rules/orchestrator-state.md

@@ -66,10 +66,27 @@ Each entry records one delegation with the shape `{ agent, phase, complexity_ban
 
 The session `model_budget.fable_policy` switch is a three-way enum `disabled | available | preferred` defined in `config/orchestration-routing.json`, defaulting to `disabled`. It governs only the delegation model tier and is not a route input. `disabled` removes `fable` from the consideration set and clamps `fable` cells to `opus`; `available` applies the base `complexity_to_model` table as-is; `preferred` applies the `preferred_overlay` (which redirects only the C3 cell to `fable` for the overlay agents `atomic-planner`, `prd-feature`, `feature-review`, `task-researcher`) and leaves `atomic-executor` and `pr-author` C3 cells at `opus`. `route` is never an input to model selection.
 
+## Require-Model-Routing Mode Scope and Backward Compatibility
+
+The complexity-assessment and model-routing-receipt invariants above are key-gated: they run only when their key is present, so a checkpoint that omits both arrays passes at every stage. The `require_model_routing` mode adds an existence gate that closes that gap without changing the default behavior. It is an opt-in keyword on `validate_orchestrator_state_text(..., require_model_routing=False)` (CLI flag `--require-model-routing`; MCP parameter `require_model_routing`), defaulting off. Plain, `require_complete`, and `require_pr_creation_ready` calls are unaffected and produce byte-identical results.
+
+## Invariants (require_model_routing mode)
+
+These invariants apply only when a caller passes `require_model_routing=True` and the checkpoint records at least one delegation. A checkpoint with zero delegations (no well-formed `delegation_receipts[]` entry and a `next_step` that names no delegating agent) imposes no requirement, so genuinely old, delegation-free checkpoints stay valid.
+
+1. **Required routing receipt once delegated.** Once the checkpoint records a delegation, the set of `model_routing_receipts[].agent` must be a superset of the delegated-agent set (each well-formed `delegation_receipts[].agent_name` plus a `next_step` that names a delegating agent). A delegated agent with no matching receipt is a violation. The delegating agent set excludes `orchestrator` (the caller, not a delegated subagent).
+
+2. **Required complexity assessment per matched phase.** Each phase named by a routing receipt whose agent is in the delegated-agent set must have a `complexity_assessments[]` entry for that phase.
+
+3. **Per-entry consistency reused, not reimplemented.** Present receipts and assessments must satisfy the model-routing-receipt and complexity-assessment invariants above; the gate reuses `_validate_model_routing_receipts` and `_validate_complexity_assessments` and never reimplements `compute_complexity_floor` or `resolve_delegation_model`. The gate logic lives in `scripts/dev_tools/_orchestrator_state_model_routing_gate.py`; enforcement is the Python validator, not an imported schema.
+
+The completion hook (`.claude/hooks/validate-orchestrator-output.ps1`) passes `--require-model-routing` alongside `--require-complete` and surfaces a gate failure as the `MODEL_ROUTING_BLOCKED:` block reason. The PreToolUse deterrent (`.claude/hooks/enforce-model-routing-receipt.ps1`) performs presence-only gating before a delegation. The MCP TypeScript surface performs the existence check only (delegated-agent set ⊆ routing-receipt-agent set); the Python validator remains authoritative for per-receipt correctness.
+
 ## Enforcement
 
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated invariant when a `remediation_loop` is present, using the existing validator message style (literal, checkpoint-context prefixed). The validator returns a list of error strings and does not mutate its input.
 - `scripts/dev_tools/validate_orchestrator_state.py` likewise appends one error per violated `human_interaction` invariant when a `human_interaction` key is present, using the same literal, checkpoint-context-prefixed message style. The check does not import or read any schema file.
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated `complexity_assessments` invariant when a `complexity_assessments` key is present, delegating to `scripts/dev_tools/_orchestrator_state_complexity.py`, which recomputes the floor via `compute_complexity_floor`. The check does not import or read any schema file.
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated `model_routing_receipts` invariant when a `model_routing_receipts` key is present, delegating to `scripts/dev_tools/_orchestrator_state_model_routing.py`, which recomputes the resolved model via `resolve_delegation_model`. The check does not import or read any schema file.
+- `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated `require_model_routing` invariant only when the caller passes `require_model_routing=True`, delegating to `scripts/dev_tools/_orchestrator_state_model_routing_gate.py`, which reuses the complexity and model-routing per-entry validators. When the flag is not passed the gate does not run, so existing calls are byte-identical.
 - The validator is consumed by the MCP tool `validate_orchestration_artifacts`; backward compatibility for existing step-based checkpoints is preserved.

package/resources/claude-customizations/.claude/settings.json

@@ -156,6 +156,10 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-epic-wave-barrier.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-model-routing-receipt.ps1"
           }
         ]
       }

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -24,6 +24,18 @@ On every invocation, the main session must:
 2. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`.
 3. If no checkpoint exists or the objective is new, begin the orchestration lifecycle from the start.
 
+### Model-choice reconciliation on resume
+
+Because model selection is required once delegation occurs (see `## Model Selection`), a resuming orchestrator must repair a missing model choice deterministically before delegating at a delegating `next_step`. When the resumed `next_step` is a delegating step:
+
+a. **Preflight the checkpoint.** Run the orchestrator-state validator with `--require-model-routing` (via `mcp__drm-copilot__validate_orchestration_artifacts` or the local CLI) against `artifacts/orchestration/orchestrator-state.json` before the first delegation. Record the result in a `model_routing_preflight` block `{ status ("pass"|"fail"), checked_at (ISO-8601 UTC), validator_command, output_summary }`.
+b. **Recompute the floor.** For the upcoming phase, recompute the complexity floor with `compute_complexity_floor(signals_present)` (`scripts/dev_tools/compute_complexity_floor.py`); do not reimplement the formula.
+c. **Record the assessment.** Write a `complexity_assessments[]` entry `{ phase, band, floor, signals_present[], rationale, assessed_at }` with `floor` equal to the recomputed value and `band >= floor`.
+d. **Resolve and record the receipt.** Resolve the model with `resolve_delegation_model(agent, complexity_band, fable_policy)` (`scripts/dev_tools/resolve_delegation_model.py`) and write a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`.
+e. **Persist and delegate.** Persist the checkpoint, then delegate with `model` equal to the receipt's `model`.
+
+The orchestrator MUST NOT delegate at a delegating `next_step` while `model_routing_preflight` status is `fail`; it repairs the missing choice (steps b-e) and re-preflights until the status is `pass`.
+
 ## Autonomous-Execution Mandate
 
 The orchestrator must achieve all actions agentically with no human interaction; full autonomy is a hard requirement. A silent manual blocker discovered at the end of a workflow is a defect, not an acceptable outcome. Every unautomatable (human-interaction) requirement must be detected early, resolved by exactly one of three permitted responses, and recorded in orchestrator state.
@@ -81,7 +93,11 @@ End-to-end procedure:
 3. **Run the per-delegation selection order.** For each delegation, resolve the model as `resolve_delegation_model(agent, complexity_band, fable_policy)`: the `table_model` is the `preferred` overlay value when (`fable_policy == "preferred"` and the agent is in the overlay set `{atomic-planner, prd-feature, feature-review, task-researcher}` and `band == "C3"`), otherwise the base `complexity_to_model[band]`. Under `fable_policy == "disabled"`, a `fable` `table_model` clamps to `model = "opus"` with `clamped_from = "fable"`. `atomic-executor` and `pr-author` C3 cells stay `opus` under every policy.
 4. **Emit a routing receipt.** Record a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`. `table_model` is the pre-clamp lookup; `model` is the post-clamp result.
 
-The `complexity_assessments[]` and `model_routing_receipts[]` invariants are enforced by `scripts/dev_tools/validate_orchestrator_state.py` per `.claude/rules/orchestrator-state.md`; both arrays are additive and optional.
+The `complexity_assessments[]` and `model_routing_receipts[]` invariants are enforced by `scripts/dev_tools/validate_orchestrator_state.py` per `.claude/rules/orchestrator-state.md`; both arrays remain additive (a checkpoint that predates model routing stays valid).
+
+### Required-once-delegated invariant (`require_model_routing` mode)
+
+The `validate_orchestrator_state_text(...)` validator accepts a `require_model_routing` mode (CLI flag `--require-model-routing`; MCP parameter `require_model_routing`). Under this mode the arrays stop being merely optional: once the checkpoint records at least one delegation (a well-formed `delegation_receipts[]` entry, or a `next_step` that names a delegating agent), every delegated agent must have a matching `model_routing_receipts[]` entry, each matched receipt's phase must have a `complexity_assessments[]` entry, and every present receipt/assessment must be consistent with the reference formulas. A delegation-free checkpoint imposes no requirement, so old checkpoints stay valid. The gate is implemented in `scripts/dev_tools/_orchestrator_state_model_routing_gate.py`; it reuses the per-entry validators and never reimplements `compute_complexity_floor` or `resolve_delegation_model`. Two enforcement layers consume it: the completion gate (`.claude/hooks/validate-orchestrator-output.ps1` passes `--require-model-routing` and surfaces failures as `MODEL_ROUTING_BLOCKED:`), and the pre-delegation deterrent (`.claude/hooks/enforce-model-routing-receipt.ps1`, presence-only). The MCP TypeScript surface performs the existence check only (delegated-agent set ⊆ routing-receipt-agent set); the Python validator is authoritative for per-receipt correctness.
 
 **`fork` caveat.** A skill whose frontmatter `context` field holds the value `fork` inherits the parent model and ignores a model override. Model selection therefore applies to agent delegations, not to fork-routed skill invocations.
 
@@ -126,6 +142,7 @@ The orchestrator must not report completion until:
 1. All required artifacts for the selected workflow path are present on disk.
 2. All validation gates (toolchain, acceptance criteria, audit artifacts) have passed.
 3. The checkpoint file at `artifacts/orchestration/orchestrator-state.json` reflects the completed state.
+4. The model-routing gate passes: `.claude/hooks/validate-orchestrator-output.ps1` runs the validator with `--require-model-routing` alongside `--require-complete` and refuses DONE with `MODEL_ROUTING_BLOCKED:` when a recorded delegation lacks a matching `model_routing_receipts[]` / `complexity_assessments[]` entry (see the required-once-delegated invariant under `## Model Selection`).
 
 ## Pre-Feature-Review Commit
 

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

@@ -22,6 +22,7 @@
     ".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-pr-author-skill.epic-base-branch.ps1",
     ".claude/hooks/enforce-pr-author-skill.ps1",

package/resources/codex-and-agents-customizations/.agents/skills/feature-promotion-lifecycle/SKILL.md

@@ -101,8 +101,14 @@ Lifecycle guardrails:
 - `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`
 
 8a) Resolve and persist `${plan-path}` before delegation:
-- reuse the earliest existing `plan*.md` in `${feature-folder}` when present
-- otherwise create exactly one canonical plan file path and reuse it for all revisions
+- enumerate `${feature-folder}/plan*.md` files in deterministic filename order
+- reuse the first existing `plan*.md` in `${feature-folder}` when present
+- otherwise create exactly one canonical plan file path using the repository's
+  feature-folder plan naming convention and reuse it for all revisions
+- never default to `${feature-folder}/plan.md` when a timestamped scaffolded
+  plan already exists
+- if checkpoint state already contains a different `${plan-path}`, correct the
+  checkpoint before planner delegation instead of creating another plan file
 
 9) Require preflight validation via `atomic_executor` until:
 - `PREFLIGHT: ALL CLEAR`

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

@@ -109,6 +109,24 @@ staging, commits, or implementation delegation. This gate covers edits, formatte
 If any required item is missing, implementation is blocked until the checkpoint
 and lifecycle state are corrected.
 
+## Plan-Path Resolution Gate
+
+After active feature folder creation and before any planning delegation, the
+main session must resolve `${plan-path}` from the active feature folder:
+
+1. Enumerate existing `${feature-folder}/plan*.md` files in deterministic
+   filename order.
+2. If one or more files exist, persist `${plan-path}` as the first existing
+   file and require every planner and executor handoff to use that exact path.
+3. If no `plan*.md` file exists, create exactly one canonical target path using
+   the repository's feature-folder plan naming convention, persist that path,
+   and reuse it for all revisions.
+4. Do not default to `${feature-folder}/plan.md` when a timestamped scaffolded
+   plan already exists.
+5. If checkpoint state names a different plan path than the resolved existing
+   plan file, correct the checkpoint before planner delegation. Do not create a
+   second plan artifact to satisfy an incorrect checkpoint value.
+
 ## Pre-Implementation Violation Handling
 
 If an implementation action is attempted before a required orchestration gate

package/resources/codex-and-agents-customizations/.agents/skills/orchestrator-workflow/SKILL.md

@@ -101,6 +101,16 @@ Persist and reuse these fields exactly:
 - `lifecycle_operations`
 - `pre-implementation-violation`
 
+Plan-path invariant:
+- `${plan-path}` is resolved only after `${feature-folder}` exists.
+- The orchestrator MUST enumerate existing `${feature-folder}/plan*.md` files
+  in deterministic filename order before planner delegation.
+- If any existing plan file is present, `${plan-path}` MUST be that first
+  existing file. Do not persist or delegate against `${feature-folder}/plan.md`
+  when a timestamped scaffolded plan already exists.
+- If checkpoint state conflicts with the resolved existing plan file, correct
+  checkpoint state before delegation and do not create a duplicate plan.
+
 For small-path runs, also persist:
 - `bootstrap_mode`
 - `phase0_execution_summary`
@@ -310,6 +320,9 @@ Required behavior:
 7. When those specialists are not yet migrated, perform the authoring steps directly without changing template headings.
 8. Spawn `atomic-planner` to finalize `${plan-path}` and require `PREFLIGHT: ALL CLEAR`.
     Hard enforcement for Step 7:
+    - Before spawning `atomic-planner`, resolve `${plan-path}` by enumerating
+      existing `${feature-folder}/plan*.md` files. Reuse the first existing file
+      in deterministic filename order, including timestamped scaffolded plans.
     - The planning route MUST be `atomic-planner -> atomic-executor` for preflight validation.
     - The planner MUST update `${plan-path}` in place and MUST NOT create additional `plan.*.md` files for revisions.
     - The approved plan MUST include explicit Phase 0 baseline evidence tasks and explicit final-QA evidence or coverage tasks for each language in scope where policy requires them.

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

@@ -76,6 +76,8 @@ Every agent named above must exist as a native Codex agent under `.codex/agents/
 - Do not rename, back up, or create sidecar checkpoint files.
 - Do not create or edit `${feature-folder}/issue.md`, `${feature-folder}/spec.md`, `${feature-folder}/user-story.md`, or `plan*.md` until lifecycle setup succeeds.
 - Do not persist placeholder lifecycle values such as `NONE`, `TBD`, or empty strings once lifecycle setup begins.
+- After active folder creation and before planner delegation, resolve `${plan-path}` by enumerating existing `${feature-folder}/plan*.md` files in deterministic filename order. If a scaffolded timestamped plan exists, persist and delegate against that exact file. Do not default to `${feature-folder}/plan.md` and do not create a second plan artifact when a plan already exists.
+- For issue #306, the canonical existing plan path is `docs/features/active/2026-07-04-codex-agent-role-config-306/plan.2026-07-04T13-47.md`; reuse that exact file and do not create `docs/features/active/2026-07-04-codex-agent-role-config-306/plan.md`.
 
 ## Checkpoint Persistence
 
@@ -133,17 +135,16 @@ The MCP validator and required CI checks are the hard completion boundary. There
 Do not claim mission completion unless all required delegations completed with receipts and the required orchestration artifacts exist on disk.
 '''
 
-[mcp_servers.drm-copilot]
-enabled = true
-
-[skills.config]
-policy-compliance-order = true
-orchestrate = true
-orchestrator-workflow = true
-feature-promotion-lifecycle = true
-repo-automation-adapter = true
-atomic-plan-contract = true
-acceptance-criteria-tracking = true
-evidence-and-timestamp-conventions = true
-pr-context-artifacts = true
-pr-base-branch-merge-base = true
+[skills]
+config = [
+    { name = "policy-compliance-order", enabled = true },
+    { name = "orchestrate", enabled = true },
+    { name = "orchestrator-workflow", enabled = true },
+    { name = "feature-promotion-lifecycle", enabled = true },
+    { name = "repo-automation-adapter", enabled = true },
+    { name = "atomic-plan-contract", enabled = true },
+    { name = "acceptance-criteria-tracking", enabled = true },
+    { name = "evidence-and-timestamp-conventions", enabled = true },
+    { name = "pr-context-artifacts", enabled = true },
+    { name = "pr-base-branch-merge-base", enabled = true },
+]

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-consistency.ps1

@@ -23,9 +23,11 @@
         variables.feature-folder);
       - a ci_gate object with conclusion == "success" and a non-empty head_sha.
 
-    The block reason names the specific missing evidence so the caller can
-    remediate. When completion is not asserted, the write is allowed
-    (backward compatibility).
+    When completion evidence is missing the hook emits a PreToolUse JSON
+    response with hookSpecificOutput.permissionDecision='deny' and a reason that
+    names the specific missing evidence so the caller can remediate. When
+    completion is not asserted, the write is allowed via
+    hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
     Edit tool calls supply only old_string/new_string (a partial patch) and
     cannot be reliably validated without the full target file content, so they
@@ -39,6 +41,11 @@
 [CmdletBinding()]
 param()
 
+# Dot-source the shared validation helpers. Guarded so a missing file produces a
+# clear error and so dot-sourcing this hook in tests loads the helpers too.
+$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
+. $script:CompletionHelpersPath
+
 function ConvertFrom-CheckpointJson {
     <#
     .SYNOPSIS
@@ -53,6 +60,29 @@ function ConvertFrom-CheckpointJson {
     return $Json | ConvertFrom-Json -ErrorAction Stop
 }
 
+function Get-CheckpointFileContent {
+    <#
+    .SYNOPSIS
+        Reads the on-disk checkpoint content for the read-then-validate Edit path.
+    .DESCRIPTION
+        Returns the full file text when the path resolves to a file on disk, or
+        $null when the file does not exist. Tests inject a CheckpointReader
+        scriptblock instead of mocking this function so no temporary files are
+        required.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+}
+
 function Test-IsCheckpointPath {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -149,7 +179,13 @@ function Get-MissingCompletionEvidence {
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
-        $Payload
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     $missing = @()
@@ -158,16 +194,17 @@ function Get-MissingCompletionEvidence {
     if (-not $issueNum -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $issueNum = Get-CheckpointStringValue -Payload $Payload.variables -Name 'issue-num'
     }
-    if (-not $issueNum) {
-        $missing += 'issue-num'
+    if (-not (Test-IsValidIssueNum -Value $issueNum)) {
+        # Name the offending value so sentinel/placeholder inputs are explicit.
+        $missing += "issue-num value '$issueNum' is not a valid issue number (must be digits-only)"
     }
 
     $featureFolder = Get-CheckpointStringValue -Payload $Payload -Name 'feature-folder'
     if (-not $featureFolder -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $featureFolder = Get-CheckpointStringValue -Payload $Payload.variables -Name 'feature-folder'
     }
-    if (-not $featureFolder) {
-        $missing += 'feature-folder'
+    if (-not (Test-IsValidFeatureFolder -Value $featureFolder -FolderExistsCheck $FolderExistsCheck)) {
+        $missing += "feature-folder value '$featureFolder' is not a valid feature folder (must be under docs/features/active/ and exist)"
     }
 
     $ciGate = $null
@@ -188,7 +225,14 @@ function Get-MissingCompletionEvidence {
         }
     }
 
-    if ($issueNum -eq '232') {
+    # PR-gate evidence is required only when the checkpoint's selected route
+    # opts into it via requires_pr_gate in the routing matrix. This replaces the
+    # former issue-number special-casing with route-driven enforcement.
+    $prGateArgs = @{ Payload = $Payload }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $prGateArgs['RoutingMatrixReader'] = $RoutingMatrixReader
+    }
+    if (Test-RouteRequiresPrGate @prGateArgs) {
         $prGate = $null
         if ($null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'pr_gate')) {
             $prGate = $Payload.pr_gate
@@ -213,6 +257,60 @@ function Get-MissingCompletionEvidence {
     return [string[]]$missing
 }
 
+function Resolve-EditedCheckpointContent {
+    <#
+    .SYNOPSIS
+        Returns the patched checkpoint content for an Edit-tool call, or $null
+        when the patch cannot be applied against the on-disk checkpoint.
+    .DESCRIPTION
+        Implements the read-then-validate Edit path. When the tool input carries
+        an old_string (an Edit patch), the on-disk checkpoint is read through the
+        injectable CheckpointReader seam and the old_string -> new_string
+        replacement is applied in memory (no on-disk mutation). Returns $null
+        when there is no old_string, the on-disk file does not exist, or the
+        old_string is not present in the on-disk content, signalling the caller
+        to allow (defer).
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput,
+
+        [Parameter(Mandatory)]
+        [scriptblock] $CheckpointReader
+    )
+
+    $oldString = $null
+    if ($null -ne $ToolInput -and ($ToolInput.PSObject.Properties.Name -contains 'old_string')) {
+        $oldString = [string]$ToolInput.old_string
+    }
+    if ([string]::IsNullOrEmpty($oldString)) {
+        return $null
+    }
+
+    $newString = ''
+    if ($ToolInput.PSObject.Properties.Name -contains 'new_string') {
+        $newString = [string]$ToolInput.new_string
+    }
+
+    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
+    if ([string]::IsNullOrEmpty([string]$onDisk)) {
+        # The on-disk checkpoint does not exist (or is empty); cannot patch.
+        return $null
+    }
+
+    $onDiskText = [string]$onDisk
+    if (-not $onDiskText.Contains($oldString)) {
+        # The old_string is not present, so the patch does not apply here.
+        return $null
+    }
+
+    # Apply the patch in memory using a literal (non-regex) replacement.
+    return $onDiskText.Replace($oldString, $newString)
+}
+
 function Invoke-CompletionConsistencyDecision {
     <#
     .SYNOPSIS
@@ -222,11 +320,20 @@ function Invoke-CompletionConsistencyDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $ToolInputRaw
+        [string] $ToolInputRaw,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $CheckpointReader = { param($Path) Get-CheckpointFileContent -Path $Path },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     if (-not $ToolInputRaw) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     try {
@@ -238,19 +345,25 @@ function Invoke-CompletionConsistencyDecision {
 
     $filePath = $toolInput.file_path
     if (-not $filePath) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $normalized = $filePath -replace '\\', '/'
     if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload. Edit tool: partial new_string is
-    # not reliable without the full target file content, so allow.
+    # Write tool: validate the content payload directly. Edit tool: no content is
+    # supplied, so read the on-disk checkpoint through the injectable seam and
+    # apply the old_string -> new_string patch in memory (read-then-validate).
     $content = $toolInput.content
     if (-not $content) {
-        return [ordered]@{ decision = 'allow' }
+        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+        if (-not $content) {
+            # No content, and the Edit could not be resolved against on-disk
+            # state (missing file or non-matching patch): defer and allow.
+            return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+        }
     }
 
     try {
@@ -259,26 +372,29 @@ function Invoke-CompletionConsistencyDecision {
     catch {
         # The content itself is not valid JSON. Let downstream tools surface the
         # error rather than blocking with a misleading reason here.
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     if (-not (Test-CompletionAsserted -Payload $payload)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    $missing = Get-MissingCompletionEvidence -Payload $payload
-    if ($missing.Count -eq 0) {
-        return [ordered]@{ decision = 'allow' }
+    $missingArgs = @{ Payload = $payload; FolderExistsCheck = $FolderExistsCheck }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $missingArgs['RoutingMatrixReader'] = $RoutingMatrixReader
     }
-
-    $issueContext = ''
-    if ((Get-CheckpointStringValue -Payload $payload -Name 'issue-num') -eq '232') {
-        $issueContext = ' Issue #232 requires pr_gate evidence and current-head ci_gate evidence.'
+    $missing = Get-MissingCompletionEvidence @missingArgs
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
+    $reason = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', '). A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha; routes whose requires_pr_gate is true must also include pr_gate evidence with a matching head_sha. Supply the missing evidence or remove the completion assertion."
     return [ordered]@{
-        decision = 'block'
-        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', ').$issueContext A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha. Supply the missing evidence or remove the completion assertion."
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $reason
+        }
     }
 }
 
@@ -295,6 +411,6 @@ catch {
     exit 1
 }
 
-$decision | ConvertTo-Json -Compress | Write-Output
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
 exit 0

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-helpers.ps1

@@ -0,0 +1,163 @@
+<#
+.SYNOPSIS
+    Dot-sourced helper functions for enforce-completion-consistency.ps1.
+
+.DESCRIPTION
+    Provides testable validation helpers used by the completion-consistency
+    PreToolUse hook:
+
+      - Test-IsValidIssueNum: rejects sentinel/placeholder and non-digit issue
+        numbers; accepts digits-only strings.
+      - Test-IsValidFeatureFolder: rejects sentinel/placeholder feature folders
+        and folders not anchored under docs/features/active/<segment>; optionally
+        verifies on-disk existence through an injectable scriptblock seam.
+
+    This script is dot-sourced by enforce-completion-consistency.ps1. It contains
+    no entrypoint logic, so dot-sourcing it in tests has no side effects.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+[CmdletBinding()]
+param()
+
+# Sentinel/placeholder values that must never satisfy a presence check.
+$script:CompletionEvidenceSentinels = @('n/a', 'none', 'tbd')
+
+function Test-IsValidIssueNum {
+    <#
+    .SYNOPSIS
+        Returns $true only for a digits-only issue number.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, a sentinel
+        (n/a, none, tbd; case-insensitive), or contains any non-digit character.
+        Returns $true only when the trimmed value matches ^\d+$.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    # Sentinel placeholders are explicitly rejected even though they are
+    # non-empty strings; the comparison is case-insensitive.
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+    return $trimmed -match '^\d+$'
+}
+
+function Test-IsValidFeatureFolder {
+    <#
+    .SYNOPSIS
+        Returns $true only for a sentinel-free feature folder anchored under
+        docs/features/active/ with a non-empty trailing segment that exists.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, or a sentinel
+        (n/a, none, tbd; case-insensitive). Requires the value to start with
+        'docs/features/active/' and to carry at least one additional non-empty
+        path segment after that prefix. Invokes the injectable FolderExistsCheck
+        scriptblock (default Test-Path -PathType Container) and returns $false
+        when it reports the folder does not exist.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container }
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+
+    $prefix = 'docs/features/active/'
+    $normalized = $trimmed -replace '\\', '/'
+    if (-not $normalized.StartsWith($prefix)) {
+        return $false
+    }
+
+    # Require a non-empty segment after the active/ prefix so the bare prefix is
+    # not accepted as a valid folder.
+    $suffix = $normalized.Substring($prefix.Length).TrimEnd('/')
+    if ([string]::IsNullOrWhiteSpace($suffix)) {
+        return $false
+    }
+
+    return [bool](& $FolderExistsCheck $normalized)
+}
+
+function Test-RouteRequiresPrGate {
+    <#
+    .SYNOPSIS
+        Returns $true when the payload's selected route opts into the PR gate.
+    .DESCRIPTION
+        Resolves the route id from the payload (route_id, falling back to
+        path_selected), looks it up in the routing matrix returned by the
+        injectable RoutingMatrixReader seam, and returns $true only when that
+        route's requires_pr_gate value is the boolean $true. A missing route id,
+        an unknown route, a matrix without routes, or a missing/false
+        requires_pr_gate returns $false. This generalizes the former issue-232
+        special-casing into a route-driven check.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader = {
+            $configPath = Join-Path $PSScriptRoot '../../config/orchestration-routing.json'
+            if (-not (Test-Path -LiteralPath $configPath)) { return $null }
+            Get-Content -LiteralPath $configPath -Raw | ConvertFrom-Json
+        }
+    )
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+
+    # Resolve the selected route id, preferring route_id over path_selected.
+    $routeId = ''
+    if ($Payload.PSObject.Properties.Name -contains 'route_id') {
+        $routeId = ([string]$Payload.route_id).Trim()
+    }
+    if (-not $routeId -and ($Payload.PSObject.Properties.Name -contains 'path_selected')) {
+        $routeId = ([string]$Payload.path_selected).Trim()
+    }
+    if (-not $routeId) {
+        return $false
+    }
+
+    $matrix = & $RoutingMatrixReader
+    if ($null -eq $matrix -or -not ($matrix.PSObject.Properties.Name -contains 'routes')) {
+        return $false
+    }
+    $routes = $matrix.routes
+    if ($null -eq $routes -or -not ($routes.PSObject.Properties.Name -contains $routeId)) {
+        return $false
+    }
+    $route = $routes.$routeId
+    if ($null -eq $route -or -not ($route.PSObject.Properties.Name -contains 'requires_pr_gate')) {
+        return $false
+    }
+    return ([bool]$route.requires_pr_gate -eq $true)
+}