@danmoisan/drm-copilot-mcp 1.0.7 → 1.0.9

package/resources/claude-customizations/.claude/lib/model-routing/ModelRouting.psm1

@@ -0,0 +1,209 @@
+<#
+.SYNOPSIS
+    Model-routing reference formulas for the orchestrator, ported from the Python references.
+
+.DESCRIPTION
+    Provides the destination-runtime PowerShell ports of the two self-contained,
+    pure model-routing formulas that the `orchestrate` skill instructs the
+    orchestrator to run:
+
+      - Get-ComplexityFloor    port of scripts/dev_tools/compute_complexity_floor.py
+      - Resolve-DelegationModel port of scripts/dev_tools/resolve_delegation_model.py
+
+    Both functions are pure and deterministic: they read no file at runtime and
+    encode only the fixed band ordering, the base complexity-to-model table, the
+    preferred overlay, and the disabled-mode clamp as module-scope constants.
+    Those literals are pinned to config/orchestration-routing.json (model_policy /
+    model_budget) by a static config-parity Pester test, and the Python modules
+    remain the validator's authoritative reference. This module is one half of a
+    two-language mirror; it never imports validator logic.
+#>
+
+Set-StrictMode -Version Latest
+
+# The fixed complexity-band vocabulary, ordered from lowest to highest rigor.
+# The array order defines "higher" and "lower" band comparisons used by the
+# floor computation, mirroring BAND_ORDER in compute_complexity_floor.py.
+$script:BAND_ORDER = @('C1', 'C2', 'C3', 'C4')
+
+# The lowest band, returned when no floor signal is present (LOWEST_BAND).
+$script:LOWEST_BAND = 'C1'
+
+# Every present floor signal contributes this uniform candidate band, per the
+# model_policy.complexity contract (each [floor] signal contributes C3).
+$script:FLOOR_CANDIDATE_BAND = 'C3'
+
+# Floors never exceed this ceiling; C4 is judgment-only and never floor-forced,
+# so the computed floor is clamped to at most C3 (FLOOR_CEILING_BAND).
+$script:FLOOR_CEILING_BAND = 'C3'
+
+# The three session-level fable policies (model_budget.fable_policy).
+$script:DISABLED_POLICY = 'disabled'
+$script:PREFERRED_POLICY = 'preferred'
+
+# The model tier removed from consideration under the disabled policy, the tier
+# a disabled-mode fable cell clamps down to, and the recorded clamp reason.
+$script:FABLE_MODEL = 'fable'
+$script:DISABLED_CLAMP_MODEL = 'opus'
+$script:DISABLED_CLAMP_REASON = 'fable_disabled'
+
+# The base complexity-to-model table applied uniformly across delegated agents
+# (BASE_COMPLEXITY_TO_MODEL). Pinned to model_policy.complexity_to_model.
+$script:BASE_COMPLEXITY_TO_MODEL = @{
+    C1 = 'haiku'
+    C2 = 'sonnet'
+    C3 = 'opus'
+    C4 = 'fable'
+}
+
+# The agents whose C3 cell the preferred overlay redirects to fable. No other
+# agent and no other band is affected (PREFERRED_OVERLAY_AGENTS).
+$script:PREFERRED_OVERLAY_AGENTS = @(
+    'atomic-planner',
+    'prd-feature',
+    'feature-review',
+    'task-researcher'
+)
+
+# The single band and target model the preferred overlay applies.
+$script:PREFERRED_OVERLAY_BAND = 'C3'
+$script:PREFERRED_OVERLAY_MODEL = 'fable'
+
+
+function Get-ComplexityFloor {
+    <#
+    .SYNOPSIS
+        Compute the deterministic complexity-band floor from present floor signals.
+
+    .DESCRIPTION
+        Faithful PowerShell port of compute_complexity_floor
+        (scripts/dev_tools/compute_complexity_floor.py). Returns the deterministic
+        lower-bound complexity band implied by the set of present floor signals:
+        each present floor signal contributes a candidate band of C3, the floor is
+        the maximum triggered candidate band, and the floor never exceeds C3
+        (C4 is never floor-forced). With no floor signal present the floor is the
+        lowest band C1. The function is pure: it reads no file and does not mutate
+        its input, and the result is independent of input ordering.
+
+    .PARAMETER SignalsPresent
+        The names of the present signals flagged [floor] in the
+        model_policy.complexity catalog. Every element is treated as a triggered
+        floor signal contributing the candidate band C3. An empty collection means
+        no floor signal is present.
+
+    .OUTPUTS
+        System.String. The floor band: C1 when no floor signal is present,
+        otherwise the maximum triggered candidate band clamped to at most C3.
+        C4 is never returned.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [string[]] $SignalsPresent
+    )
+
+    # With no present floor signal there is no candidate band to raise the floor
+    # above the lowest band, so the floor is C1 (mirrors the empty-input guard).
+    if (-not $SignalsPresent -or $SignalsPresent.Count -eq 0) {
+        return $script:LOWEST_BAND
+    }
+
+    # Each present floor signal contributes the uniform candidate band; the floor
+    # is the maximum triggered candidate rank across all of them. Because every
+    # signal contributes the same candidate band, the max equals that rank.
+    $candidateRank = $script:BAND_ORDER.IndexOf($script:FLOOR_CANDIDATE_BAND)
+    $highestRank = $candidateRank
+
+    # Clamp with the ceiling rank so the floor can never exceed C3; this is what
+    # keeps C4 from ever being floor-forced regardless of how many signals exist.
+    $ceilingRank = $script:BAND_ORDER.IndexOf($script:FLOOR_CEILING_BAND)
+    $floorRank = [Math]::Min($highestRank, $ceilingRank)
+    return $script:BAND_ORDER[$floorRank]
+}
+
+function Resolve-DelegationModel {
+    <#
+    .SYNOPSIS
+        Resolve the delegation model tier for an agent, band, and fable policy.
+
+    .DESCRIPTION
+        Faithful PowerShell port of resolve_delegation_model
+        (scripts/dev_tools/resolve_delegation_model.py). Applies the model_policy
+        selection formula to a single delegation: it computes the pre-clamp
+        table_model (the base complexity_to_model table plus any preferred overlay)
+        and the post-clamp model, recording the clamp provenance. The preferred
+        overlay redirects only the C3 cell to fable and only for the four overlay
+        agents; atomic-executor and pr-author C3 cells stay opus under every
+        policy. Under the disabled policy a fable table cell clamps to opus with
+        clamped_from = fable and clamp_reason = fable_disabled. The function is
+        pure: it reads no file and mutates no input.
+
+    .PARAMETER Agent
+        The target delegate agent name (for example atomic-planner). Only
+        participates in preferred-overlay eligibility.
+
+    .PARAMETER Band
+        The assessed complexity band, one of C1..C4. Used as the key into the
+        base complexity_to_model table. A band outside the table is the PowerShell
+        analog of the Python KeyError and causes a terminating error (throw).
+
+    .PARAMETER FablePolicy
+        The session fable policy, one of disabled, available, or preferred.
+
+    .OUTPUTS
+        System.Collections.Hashtable. A hashtable with keys table_model (the
+        pre-clamp table lookup, including any overlay), model (the post-clamp
+        result), clamped_from (fable when a clamp occurred, else $null), and
+        clamp_reason (fable_disabled when a clamp occurred, else $null).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Agent,
+        [Parameter(Mandatory = $true)]
+        [string] $Band,
+        [Parameter(Mandatory = $true)]
+        [string] $FablePolicy
+    )
+
+    # The preferred overlay redirects only the C3 cell to fable, and only for the
+    # overlay agents; every other case reads the base table unchanged. The three
+    # conditions (policy, agent membership, band) must all hold for the overlay.
+    if ($FablePolicy -eq $script:PREFERRED_POLICY -and
+        $script:PREFERRED_OVERLAY_AGENTS -contains $Agent -and
+        $Band -eq $script:PREFERRED_OVERLAY_BAND) {
+        $tableModel = $script:PREFERRED_OVERLAY_MODEL
+    }
+    else {
+        # A band outside the base table is the PowerShell analog of the Python
+        # KeyError: fail fast rather than return a silently wrong value.
+        if (-not $script:BASE_COMPLEXITY_TO_MODEL.ContainsKey($Band)) {
+            throw "Unknown complexity band '$Band'; expected one of $($script:BAND_ORDER -join ', ')."
+        }
+        $tableModel = $script:BASE_COMPLEXITY_TO_MODEL[$Band]
+    }
+
+    # Under the disabled policy, fable is removed from consideration: a fable
+    # table cell clamps down to opus and records the clamp provenance.
+    if ($FablePolicy -eq $script:DISABLED_POLICY -and $tableModel -eq $script:FABLE_MODEL) {
+        return @{
+            table_model  = $tableModel
+            model        = $script:DISABLED_CLAMP_MODEL
+            clamped_from = $script:FABLE_MODEL
+            clamp_reason = $script:DISABLED_CLAMP_REASON
+        }
+    }
+
+    # No clamp applies: the resolved model is the table model verbatim.
+    return @{
+        table_model  = $tableModel
+        model        = $tableModel
+        clamped_from = $null
+        clamp_reason = $null
+    }
+}
+
+Export-ModuleMember -Function Get-ComplexityFloor, Resolve-DelegationModel

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/epic-orchestrate/SKILL.md

@@ -115,9 +115,9 @@ The child's own `orchestrator` reads this line and applies the two-axis model-se
 documented in `.claude/skills/orchestrate/SKILL.md` (`## Model Selection`): it assesses a
 judgment-based `complexity_band`, records `complexity_assessments[]` and `model_routing_receipts[]`,
 and resolves each delegation's model tier under the given `fable_policy`. The two canonical, tested
-reference implementations are `scripts/dev_tools/compute_complexity_floor.py`
-(`compute_complexity_floor`) and `scripts/dev_tools/resolve_delegation_model.py`
-(`resolve_delegation_model`). Default `fable_policy` is `disabled` when the marker is absent.
+reference implementations are `.claude/lib/model-routing/ModelRouting.psm1`
+(`Get-ComplexityFloor`) and `.claude/lib/model-routing/ModelRouting.psm1`
+(`Resolve-DelegationModel`). Default `fable_policy` is `disabled` when the marker is absent.
 
 `route` is never an input to model selection; `route` remains file-count driven and governs only
 agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`

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 `Get-ComplexityFloor -SignalsPresent <names>` (`.claude/lib/model-routing/ModelRouting.psm1`); 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-DelegationModel -Agent <agent> -Band <complexity_band> -FablePolicy <fable_policy>` (`.claude/lib/model-routing/ModelRouting.psm1`) 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.
@@ -71,8 +83,10 @@ Model selection is a second axis, strictly separate from `route`. `route` (`smal
 
 The two canonical, tested reference implementations express the formulas the orchestrator applies by judgment:
 
-- `scripts/dev_tools/compute_complexity_floor.py` (`compute_complexity_floor`) — the deterministic complexity-floor formula. Each present `[floor]` signal contributes a candidate band of `C3`; the floor is the maximum triggered candidate band; the floor never exceeds `C3`. C4 is never floor-forced; it is reached only by judgment.
-- `scripts/dev_tools/resolve_delegation_model.py` (`resolve_delegation_model`) — the delegation-model selection formula (base `complexity_to_model` table, the `preferred` overlay, and the `disabled` clamp).
+- `.claude/lib/model-routing/ModelRouting.psm1` (`Get-ComplexityFloor`) — the deterministic complexity-floor formula. Each present `[floor]` signal contributes a candidate band of `C3`; the floor is the maximum triggered candidate band; the floor never exceeds `C3`. C4 is never floor-forced; it is reached only by judgment.
+- `.claude/lib/model-routing/ModelRouting.psm1` (`Resolve-DelegationModel`) — the delegation-model selection formula (base `complexity_to_model` table, the `preferred` overlay, and the `disabled` clamp).
+
+The runnable reference the destination runtime applies is the `.claude`-resident PowerShell module above; the repository validator remains the Python authority (`scripts/dev_tools/compute_complexity_floor.py` and `scripts/dev_tools/resolve_delegation_model.py`), pinned to the same `config/orchestration-routing.json` truth table by a static config-parity test.
 
 End-to-end procedure:
 
@@ -81,7 +95,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 +144,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",
@@ -68,6 +69,7 @@
     ".claude/skills/review-staged/SKILL.md",
     ".claude/skills/skill-canonical-location-audit/SKILL.md",
     ".claude/skills/translate-copilot-to-claude/SKILL.md",
-    ".claude/skills/update-status/SKILL.md"
+    ".claude/skills/update-status/SKILL.md",
+    ".claude/lib/model-routing/ModelRouting.psm1"
   ]
 }

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 },
+]