@danmoisan/drm-copilot-mcp 1.1.19 → 1.1.20

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

@@ -0,0 +1,190 @@
+<#
+.SYNOPSIS
+    Scope predicate and pull-request selector reader for the epic merge gate (issue #952).
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1 on both runtimes; this file is byte-identical in
+    .claude/hooks and .codex/hooks. Under a merge queue every gh pr merge spelling (--merge, -m,
+    --squash, -s, --rebase, -r, --auto, --admin, or no method flag) adds the pull request to the
+    queue, and the gh api mutations enqueuePullRequest, enablePullRequestAutoMerge, and
+    mergePullRequest and the REST pulls/<n>/merge endpoint also reach the base branch. All of
+    them are in scope. A gh pr merge whose only action flag is --disable-auto is out of scope.
+
+    Pure string logic only: no disk, process, network, clock, or environment access. The file
+    dot-sources and imports nothing; it consumes Get-CommandLineInvocation and
+    Get-CommandLineStructuralMatch, which the gate loads from hook-command-invocation.ps1 first.
+
+    Known limitation (issue #952 code review CR-5): the gh api scope reads the command text
+    only. A GraphQL mutation supplied from a file (gh api graphql -F query=@mutation.graphql,
+    or gh api --input payload.json) is not visible to this text-based scope and is not gated.
+#>
+
+# gh pr merge flags that perform or schedule a merge. Any of them keeps a command in scope even
+# when it also carries --disable-auto.
+$script:EpicMergeGateActionFlags = @('--merge', '-m', '--squash', '-s', '--rebase', '-r', '--auto', '--admin')
+
+# gh pr merge flags, including the inherited --repo, that consume the following token as a value.
+$script:EpicMergeGateValueFlags = @('-b', '--body', '-F', '--body-file', '-t', '--subject', '-A', '--author-email', '--match-head-commit', '-R', '--repo')
+
+# GraphQL mutations that merge, enqueue, or schedule the merge of a pull request.
+$script:EpicMergeGateMutationNames = @('enqueuePullRequest', 'enablePullRequestAutoMerge', 'mergePullRequest')
+
+# The REST merge endpoint path; group 1 is the pull-request number.
+$script:EpicMergeGateRestMergePattern = '(?:^|/)pulls/(\d+)/merge(?:$|[^\w-])'
+
+function Get-EpicMergeGateFlagName {
+    <#
+    .SYNOPSIS
+        Return the flag name of a dash-led token without any '=value' suffix.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Token)
+
+    $split = $Token.IndexOf('=')
+    if ($split -gt 0) { return $Token.Substring(0, $split) }
+    return $Token
+}
+
+function ConvertFrom-EpicMergeGateSelector {
+    <#
+    .SYNOPSIS
+        Convert a gh pr merge selector to a pull-request number, or $null.
+    .DESCRIPTION
+        Accepts an all-digit selector or a URL whose path ends in /pull/<n>. A branch-name
+        selector carries no number and yields $null.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Selector)
+
+    $digits = $null
+    if ($Selector -match '^\d+$') {
+        $digits = $Selector
+    } elseif ($Selector -match '/pull/(\d+)/?(?:[?#].*)?$') {
+        $digits = $Matches[1]
+    }
+    $number = 0
+    if ($null -ne $digits -and [int]::TryParse($digits, [ref] $number)) { return $number }
+    return $null
+}
+
+function Test-EpicMergeGateDisableAutoOnly {
+    <#
+    .SYNOPSIS
+        Report whether a Structural gh pr merge match carries --disable-auto and no action flag.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][pscustomobject] $Match)
+
+    $tokens = [string[]]@($Match.Segment.Tokens)
+    $hasDisableAuto = $false
+    for ($index = $Match.OperandIndex; $index -lt $tokens.Count; $index++) {
+        $name = Get-EpicMergeGateFlagName -Token $tokens[$index]
+        if ($script:EpicMergeGateActionFlags -ccontains $name) { return $false }
+        if ($name -ceq '--disable-auto') { $hasDisableAuto = $true }
+    }
+    return $hasDisableAuto
+}
+
+function Test-EpicMergeGateApiMutationText {
+    <#
+    .SYNOPSIS
+        Report whether gh api text names a merge or enqueue mutation or the REST merge endpoint.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $Text)
+
+    if ([string]::IsNullOrEmpty($Text)) { return $false }
+    foreach ($name in $script:EpicMergeGateMutationNames) {
+        if ($Text.IndexOf($name, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) { return $true }
+    }
+    return [regex]::IsMatch($Text, $script:EpicMergeGateRestMergePattern)
+}
+
+function Test-EpicMergeGateCommandInScope {
+    <#
+    .SYNOPSIS
+        Report whether a command line is a gated merge or enqueue action (issue #952).
+    .DESCRIPTION
+        True for any gh pr merge match, Structural or Indeterminate, unless the match is Structural
+        and its only action flag is --disable-auto; true for any gh api match whose tokens name a
+        merge or enqueue mutation or a pulls/<n>/merge path. Text that only mentions these words
+        produces no match and stays out of scope. An Indeterminate gh pr merge match stays in scope
+        (fail closed).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
+        if ($match.Status -ne 'Structural' -or -not (Test-EpicMergeGateDisableAutoOnly -Match $match)) { return $true }
+    }
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        if (Test-EpicMergeGateApiMutationText -Text (@($match.Segment.Tokens) -join ' ')) { return $true }
+    }
+    return $false
+}
+
+function Get-EpicMergeGateSelectorPrNumber {
+    <#
+    .SYNOPSIS
+        Resolve the pull-request number of a gated merge or enqueue command, or $null.
+    .DESCRIPTION
+        For gh pr merge, only the first Structural match is read. Value flags are skipped with
+        their values, other flags are skipped, an equals-joined --merge=<digits> yields its
+        digits (an equals-joined value that is not a number is skipped like any other flag),
+        and the first non-flag token (or the token after a bare '--') is the selector.
+        For gh api, the number comes from a pulls/<n>/merge token. Any other command yields
+        $null, which the gate handles through its no-number branches.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    $match = Get-CommandLineStructuralMatch -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
+    if ($null -ne $match) {
+        $tokens = [string[]]@($match.Segment.Tokens)
+        $index = $match.OperandIndex
+        while ($index -lt $tokens.Count) {
+            $token = $tokens[$index]
+            if ($token -ceq '--') {
+                if ($index + 1 -lt $tokens.Count) { return ConvertFrom-EpicMergeGateSelector -Selector $tokens[$index + 1] }
+                return $null
+            }
+            if ($token.StartsWith('-') -and $token.Length -gt 1) {
+                $name = Get-EpicMergeGateFlagName -Token $token
+                if ($name -ceq '--merge' -and $token.Length -gt $name.Length) {
+                    $equalsNumber = ConvertFrom-EpicMergeGateSelector -Selector $token.Substring($name.Length + 1)
+                    if ($null -ne $equalsNumber) { return $equalsNumber }
+                }
+                $index += if ($script:EpicMergeGateValueFlags -ccontains $token) { 2 } else { 1 }
+                continue
+            }
+            return ConvertFrom-EpicMergeGateSelector -Selector $token
+        }
+        return $null
+    }
+
+    foreach ($apiMatch in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        foreach ($token in @($apiMatch.Segment.Tokens)) {
+            $rest = [regex]::Match([string]$token, $script:EpicMergeGateRestMergePattern)
+            $number = 0
+            if ($rest.Success -and [int]::TryParse($rest.Groups[1].Value, [ref] $number)) { return $number }
+        }
+    }
+    return $null
+}

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

@@ -3,6 +3,11 @@
     Gates epic child and integration PR merges behind checkpointed green state.
 
 .DESCRIPTION
+    Trigger scope (issue #952): every gh pr merge invocation (any merge method, --auto, --admin,
+    or no method flag) and every gh api merge or enqueue mutation is gated, because under a merge
+    queue each of them reaches the base branch; only a pure --disable-auto is out of scope. The
+    predicate and the PR selector reader live in enforce-epic-merge-gate-command.ps1.
+
     Docs-only branch (issue #927): after the standalone branch denies an explicit PR number,
     and only when no checkpoint is present at the repository root (both checkpoint texts are
     blank; operator decision OD-1, stricter than the Claude per-PR rule), the gate calls
@@ -25,6 +30,9 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 # the two runtimes on one implementation of the same concern.
 try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
 try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
+# Merge and enqueue scope predicate and the PR selector reader (issue #952), byte-identical to the
+# Claude copy.
+try { . (Join-Path $PSScriptRoot 'enforce-epic-merge-gate-command.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-epic-merge-gate-command.ps1' -ErrorRecord $_ }
 # Shared docs-only diff classification and the merge-side docs-only exemption (issue #927).
 try { . (Join-Path $PSScriptRoot 'hook-docs-only-diff.ps1') } catch { Add-HookDependencyFailure -Name 'hook-docs-only-diff.ps1' -ErrorRecord $_ }
 
@@ -61,15 +69,11 @@ function Get-CodexMergeCommandPrNumber {
     .SYNOPSIS
         Resolve the explicit pull-request number of a gh pr merge invocation, or $null.
     .DESCRIPTION
-        The number is taken from the segment that structurally invokes `gh pr merge` and
-        from nowhere else: the positional spelling through Get-CommandLineOperand, the
-        flag-led and equals-joined spellings through Get-CommandLineFlagValue. A leading
-        `cd <path>` segment contributes no operand and no flag value, so no digit run
+        The number is resolved by Get-EpicMergeGateSelectorPrNumber in
+        enforce-epic-merge-gate-command.ps1 (issue #952), the file shared byte-identically with
+        the Claude runtime, from the segment that structurally invokes gh pr merge or gh api and
+        from nowhere else. A leading cd <path> segment contributes no selector, so no digit run
         outside the merge segment can be mistaken for a pull-request number.
-
-        This copy has never carried the Claude copy's unanchored whole-text digit scan and
-        deliberately does not acquire one. No regular expression matching a bare digit run
-        is introduced here; the only pattern below anchors an all-digit token end to end.
     .OUTPUTS
         System.Nullable[int]
     #>
@@ -77,18 +81,7 @@ function Get-CodexMergeCommandPrNumber {
     [OutputType([int])]
     param([Parameter(Mandatory)][string] $Command)
 
-    foreach ($operand in @(Get-CommandLineOperand -CommandText $Command -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
-        if ($operand -match '^\d+$') {
-            return [int]$operand
-        }
-    }
-
-    $flagValue = Get-CommandLineFlagValue -CommandText $Command -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
-    if ($null -ne $flagValue -and $flagValue -match '^\d+$') {
-        return [int]$flagValue
-    }
-
-    return $null
+    return Get-EpicMergeGateSelectorPrNumber -CommandText $Command
 }
 
 function Test-CodexChildMergeReady {
@@ -153,23 +146,9 @@ function Invoke-CodexEpicMergeDecision {
         return $null
     }
     $command = [string]$payload.tool_input.command
-    # Both legs are read structurally from the segment that invokes the command, so a
-    # quoted mention of the phrase no longer brings a command into scope. The flag leg needs
-    # a raw-scan fallback: a wrapper's quoted argument collapses into ONE token, so a flag
-    # inside it is never read as a token, and the token-only read took
-    # bash -c "gh pr merge --merge 688" out of scope.
-    $isMergeInvocation = Test-CommandLineInvocation -CommandText $command -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
-    $hasMergeFlag = Test-CommandLineFlag -CommandText $command -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--merge'
-    if (-not $hasMergeFlag) {
-        foreach ($segment in @(Read-CommandLineSegment -CommandText $command)) {
-            if ((Test-CommandLineSegmentRawScan -Segment $segment) -and
-                $segment.ScanText.IndexOf('--merge', [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
-                $hasMergeFlag = $true
-                break
-            }
-        }
-    }
-    if (-not $isMergeInvocation -or -not $hasMergeFlag) {
+    # Scope (issue #952): every gh pr merge invocation except a pure --disable-auto, and every gh api
+    # merge or enqueue mutation, is gated; Test-EpicMergeGateCommandInScope holds the predicate.
+    if (-not (Test-EpicMergeGateCommandInScope -CommandText $command)) {
         return $null
     }
 
@@ -214,7 +193,7 @@ function Invoke-CodexEpicMergeDecision {
         hookSpecificOutput = [ordered]@{
             hookEventName            = 'PreToolUse'
             permissionDecision       = 'deny'
-            permissionDecisionReason = 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires a safe epic child checkpoint or a successful final epic CI gate with a matching PR number.'
+            permissionDecisionReason = 'EPIC_MERGE_GATE_BLOCKED: a pull-request merge or merge-queue enqueue (gh pr merge with any method, --auto, or --admin, or a gh api merge or enqueue mutation) requires a safe epic child checkpoint or a successful final epic CI gate with a matching PR number.'
         }
     }
 }

package/resources/codex-and-agents-customizations/.codex/hooks/hook-docs-only-diff.ps1

@@ -19,7 +19,8 @@
                                                is balanced; a structural gh pr merge; no inline
                                                VAR= prefix token (GH_REPO=, GH_HOST=); no
                                                single-dash token containing R; no --repo or
-                                               --repo= token; no --auto token.
+                                               --repo= token; no --auto token; no token
+                                               containing /pull/ (a URL selector).
       M2 DOCS_ONLY_EXEMPTION_PR_UNRESOLVED   - the worktree root is an existing directory.
       M3 DOCS_ONLY_EXEMPTION_PR_UNRESOLVED   - gh pr view <N> --json baseRefName,headRefOid
                                                exits 0 and returns a JSON object; headRefOid
@@ -368,6 +369,9 @@ function Get-DocsOnlyMergeShapeViolation {
         if ($text -eq '--repo' -or $text.StartsWith('--repo=', [System.StringComparison]::OrdinalIgnoreCase)) {
             return $prefix + "the repository override '$text' is not accepted."
         }
+        if ($text.Contains('/pull/')) {
+            return $prefix + "the URL selector '$text' is not accepted."
+        }
         if ($text -eq '--auto' -or $text.StartsWith('--auto=', [System.StringComparison]::OrdinalIgnoreCase)) {
             return $prefix + 'auto-merge (--auto) is not eligible.'
         }

package/resources/codex-and-agents-customizations/.codex/prompts/feature-review-remediate.md

@@ -4,7 +4,9 @@ description: Run feature review and, if needed, remediation planning with execut
 
 $feature-review
 Use pr_context as authoritative if present and valid. Only fall back to an explicit base branch if pr_context is missing, stale, or ambiguous.
-If remediation is required, explicitly spawn atomic-planner to create or revise the remediation plan.
-Before atomic-planner finalizes the plan, it must explicitly spawn atomic-executor in preflight-validation-only mode against that same file.
-If atomic-executor returns PREFLIGHT: REVISIONS REQUIRED, atomic-planner must revise the same file and repeat until PREFLIGHT: ALL CLEAR.
-Only then finalize the remediation plan and report all generated artifacts.
+If remediation is required, write exactly one mode line into the remediation inputs: `Remediation-Mode: proportionate` when every autonomous finding can be fixed without changing a spec acceptance criterion, a public interface, or the file inventory beyond the branch diff plus tests and mirrors, otherwise `Remediation-Mode: design`. CI-failure findings are normally proportionate.
+Then explicitly spawn atomic-planner to create or revise the remediation plan.
+Before atomic-planner finalizes the plan, it must explicitly spawn atomic-executor in preflight-validation-only mode against that same file, with the preflight directive in the delegation prompt and never in the plan file. Preflight is single-pass: trivial defects are fixed in place.
+If atomic-executor returns PREFLIGHT: REVISIONS REQUIRED, atomic-planner must revise the same file once with the full PREFLIGHT-DEFECT list, and one confirming preflight runs; a second substantive result halts the cycle with `blocked_preflight_iteration_limit`.
+For `Remediation-Mode: proportionate`, preflight and execution may run as one atomic-executor delegation that stops with `BLOCKED at preflight (before [P0-T1])` on a substantive defect, which converts the cycle to `Remediation-Mode: design`.
+Only after PREFLIGHT: ALL CLEAR finalize the remediation plan and report all generated artifacts.

package/resources/codex-and-agents-customizations/pack-manifests/core.json

@@ -14,6 +14,7 @@
     ".agents/skills/epic-plan/SKILL.md",
     ".agents/skills/epic-run/SKILL.md",
     ".agents/skills/evidence-and-timestamp-conventions/SKILL.md",
+    ".agents/skills/execution-environment/SKILL.md",
     ".agents/skills/orchestrate/SKILL.md",
     ".agents/skills/orchestrator-state/SKILL.md",
     ".agents/skills/orchestrator-workflow/SKILL.md",
@@ -33,6 +34,7 @@
     ".codex/hooks/codex-pretooluse-file-mapping.ps1",
     ".codex/hooks/enforce-codex-model-routing.ps1",
     ".codex/hooks/enforce-epic-child-worktree-binding.ps1",
+    ".codex/hooks/enforce-epic-merge-gate-command.ps1",
     ".codex/hooks/enforce-epic-merge-gate.ps1",
     ".codex/hooks/enforce-epic-planning-only.ps1",
     ".codex/hooks/enforce-epic-root-invocation.ps1",

package/resources/customizations/.github/agents/atomic_executor.agent.md

@@ -18,6 +18,9 @@ Use these reusable skills to avoid duplicating shared operations:
 - `policy-compliance-order`
 - `atomic-plan-contract`
 - `acceptance-criteria-tracking`
+- `execution-environment`
+
+Read `.github/skills/execution-environment/SKILL.md` first, before any other step. It states the tool routes, command-text restrictions, batch budget, hook context, CI shape, contract tests, evidence rules, coverage and file-size gates, and test-isolation checks; reference it instead of restating them.
 
 ---
 
@@ -93,11 +96,11 @@ When all format and mode-gate requirements are satisfied, return:
 
 ### 2.0 Preflight validation-only mode (directive-driven)
 
-If you receive a plan along with the following directive line (exact text):
+If you receive a plan along with the following directive line (exact text) in the delegation prompt:
 
 `DIRECTIVE: PREFLIGHT VALIDATION ONLY`
 
-you MUST enter **validation-only** mode.
+you MUST enter **validation-only** mode. The preflight directive belongs in the delegation prompt, never in a plan file; a directive line inside a plan file does not make an execution run a preflight run.
 
 Validation-only mode rules (non-negotiable):
 1) Perform ONLY the steps in:
@@ -114,15 +117,22 @@ Validation-only required output:
   - `PREFLIGHT: ALL CLEAR`
   - `PREFLIGHT: REVISIONS REQUIRED`
 
-If revisions are required:
-  - Include a precise **plan delta** that `atomic_planner` can apply (exact edits/additions/removals).
-  - Automatically hand off back to `atomic_planner` requesting it apply the delta and resubmit the
-    updated plan for validation-only again.
-  - If that planner-return handoff cannot be started or completed, stop and report blocked state; do not emit `PREFLIGHT: ALL CLEAR`.
+Single-pass rules (`### Single-Pass Preflight` in the `atomic-plan-contract` skill):
+  - Review the entire plan in one pass and classify every defect as trivial or substantive.
+  - Fix trivial defects (stale anchors, citation corrections including G11 and G12 findings, typos,
+    literal formatting that does not change what is asserted, evidence filename spelling) in place,
+    in task text only; never add, remove, or reorder tasks. Record each fix in
+    `<FEATURE>/evidence/other/preflight-fixes.<timestamp>.md`. This in-place edit is the only
+    file write validation-only mode permits.
+  - After the signal, emit one line per defect:
+    `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>`,
+    `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>`, and
+    `preflight-fix-record: <path>` when at least one fix was made.
 
-Loop requirement:
-  Continue this validate → delta → planner-revise → validate loop until you can return
-  `PREFLIGHT: ALL CLEAR`.
+If revisions are required:
+  - Include a precise **plan delta** that `atomic_planner` can apply (exact edits/additions/removals), with one `PREFLIGHT-DEFECT:` line for every substantive defect found.
+  - Return the result to the caller. A plan returns to the planner at most once; the orchestrator routes the full defect list for one revision and runs one confirming preflight.
+  - If the required handoff cannot be started or completed, stop and report blocked state; do not emit `PREFLIGHT: ALL CLEAR`.
 
 When the user provides a plan (in chat or via file path), you must:
 
@@ -208,7 +218,7 @@ At the end of each message, include an updated copy of the plan’s checklist (o
 
 ## 4. Blocking Protocol (When You Must Stop)
 
-Blocking is only permitted during **preflight validation (before [P0-T1])**. If any of the following are detected preflight, stop and request an updated plan from `atomic_planner`:
+Blocking is only permitted during **preflight validation (before [P0-T1])**, including the preflight that opens a combined preflight-and-execute run of a proportionate remediation cycle (`Remediation-Mode: proportionate`). Trivial defects are fixed in place rather than blocked on. If any of the following substantive defects are detected preflight, stop and request an updated plan from `atomic_planner`:
 - The plan violates repo policy and cannot be executed as-written.
 - A task is non-atomic / non-verifiable (bucket task).
 - Required work exceeds task scope (needs additional independent outcomes).

package/resources/customizations/.github/agents/atomic_planning.agent.md

@@ -18,6 +18,9 @@ You are a **planning-only agent**. Your job is to generate precise, executable p
 Use these reusable skills to avoid duplicating shared operations:
 - `policy-compliance-order`
 - `atomic-plan-contract`
+- `execution-environment`
+
+Read `.github/skills/execution-environment/SKILL.md` first, before any other step. It states the tool routes, command-text restrictions, batch budget, hook context, CI shape, contract tests, evidence rules, coverage and file-size gates, and test-isolation checks; plans reference it instead of restating them.
 
 Your output must always be structured, binary, and free of “work in progress” tasks.
 
@@ -102,9 +105,11 @@ For `minor-audit`, preflight-required plan gates MUST include baseline evidence,
 
 ---
 
-### 2.5.1 Mandatory preflight validation loop via `atomic_executor`
+### 2.5.1 Mandatory single-pass preflight via `atomic_executor`
+
+Follow `### Single-Pass Preflight` in the `atomic-plan-contract` skill. The preflight directive belongs in the delegation prompt, never in the plan file. The preflight executor fixes trivial defects in place and returns only substantive defects as `PREFLIGHT-DEFECT:` lines. A plan returns to the planner at most once: apply every listed change in one revision of the same file; if the confirming preflight still reports a substantive defect, the orchestrator halts with `blocked_reason: "validator_failed"`.
 
-Follow the preflight validation loop rules in the `atomic-plan-contract` skill.
+Every plan follows `## Design-Level Plan Contract (Mandatory)` in the `atomic-plan-contract` skill: anchors are symbols, headings, or test names (never line numbers or commit SHAs), literals appear only where they are the asserted value, tool routes are not restated, a plan above 40 tasks or 400 lines carries `## Size Justification`, every plan carries a `## Pre-Mortem` section with the seven labels, and the final phase ends with the self-review task.
 
 If the `atomic_executor` delegation cannot be started, resumed, or completed, you MUST stop and report blocked state. You MUST NOT self-approve or finalize the plan.
 
@@ -537,7 +542,7 @@ When updating an existing file, preserve non-plan content (for example, problem
 When the calling system or handoff provides an explicit target plan file path (for example `${file}` or `${plan-path}`), you MUST:
 
 - Update that exact file in place.
-- Reuse that same file for every preflight revision iteration.
+- Reuse that same file for the single permitted preflight revision.
 - Return the same path in `plan-path` outputs unless the caller explicitly changes it.
 
 You MUST NOT create additional timestamped sibling files (for example `plan.<timestamp>.md`) when an authoritative target path has been supplied.

package/resources/customizations/.github/agents/csharp-atomic-executor.agent.md

@@ -95,11 +95,11 @@ When all format and mode-gate requirements are satisfied, return:
 
 ### 2.0 Preflight validation-only mode (directive-driven)
 
-If you receive a plan along with the following directive line (exact text):
+If you receive a plan along with the following directive line (exact text) in the delegation prompt:
 
 `DIRECTIVE: PREFLIGHT VALIDATION ONLY`
 
-you MUST enter **validation-only** mode.
+you MUST enter **validation-only** mode. The preflight directive belongs in the delegation prompt, never in a plan file; a directive line inside a plan file does not make an execution run a preflight run.
 
 Validation-only mode rules (non-negotiable):
 1) Perform ONLY the steps in:
@@ -116,14 +116,18 @@ Validation-only required output:
   - `PREFLIGHT: ALL CLEAR`
   - `PREFLIGHT: REVISIONS REQUIRED`
 
-If revisions are required:
-  - Include a precise **plan delta** that `atomic_planner` can apply (exact edits/additions/removals).
-  - Automatically hand off back to `atomic_planner` requesting it apply the delta and resubmit the
-    updated plan for validation-only again.
+Single-pass rules (`### Single-Pass Preflight` in the `atomic-plan-contract` skill):
+  - Review the entire plan in one pass and classify every defect as trivial or substantive.
+  - Fix trivial defects in place, in task text only; never add, remove, or reorder tasks. Record each
+    fix in `<FEATURE>/evidence/other/preflight-fixes.<timestamp>.md`. This in-place edit is the only file
+    write validation-only mode permits.
+  - After the signal, emit one line per defect: `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>`,
+    `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>`, and
+    `preflight-fix-record: <path>` when at least one fix was made.
 
-Loop requirement:
-  Continue this validate → delta → planner-revise → validate loop until you can return
-  `PREFLIGHT: ALL CLEAR`.
+If revisions are required:
+  - Include a precise **plan delta** that `atomic_planner` can apply (exact edits/additions/removals), with one `PREFLIGHT-DEFECT:` line for every substantive defect found.
+  - Return the result to the caller. A plan returns to the planner at most once; the orchestrator routes the full defect list for one revision and runs one confirming preflight.
 
 When the user provides a plan (in chat or via file path), you must:
 

package/resources/customizations/.github/agents/csharp-atomic-planning.agent.md

@@ -105,9 +105,9 @@ Branch-specific required task sets:
 
 ---
 
-### 2.5.1 Mandatory preflight validation loop via `csharp-atomic-executor`
+### 2.5.1 Mandatory single-pass preflight via `csharp-atomic-executor`
 
-Follow the preflight validation loop rules in the `atomic-plan-contract` skill.
+Follow `### Single-Pass Preflight` in the `atomic-plan-contract` skill. The preflight directive belongs in the delegation prompt, never in the plan file. The preflight executor fixes trivial defects in place and returns only substantive defects as `PREFLIGHT-DEFECT:` lines. A plan returns to the planner at most once: apply every listed change in one revision of the same file; if the confirming preflight still reports a substantive defect, the orchestrator halts with `blocked_reason: "validator_failed"`.
 
 ---
 

package/resources/customizations/.github/agents/csharp-orchestrator.agent.md

@@ -6,7 +6,7 @@ tools: [vscode/runCommand, vscode/extensions, execute/getTerminalOutput, execute
 handoffs:
   - label: Build minimal-audit atomic plan (preflight all clear)
     agent: atomic_planner
-    prompt: "Generate a minimal-audit atomic plan for `${feature-folder}` using `${feature-folder}/issue.md` as the only requirements source (no spec/user-story/research). Use directive `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`. Target plan file path is `${plan-path}` and MUST be updated in place. Do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops. The plan MUST include exactly 3 phases: Phase 0 baseline capture, Phase 1 placeholder for constrained small-path implementation work, Phase 2 final QC loop. Final-QC command tasks MUST be unconditional when present in the plan: do not add IN_SCOPE/OUT_OF_SCOPE branching and do not allow SKIPPED as a valid completion state for those tasks. Require validation-only preflight through `atomic_executor` and iterate until final `PREFLIGHT: ALL CLEAR` while preserving the same target path. Return `plan-path` and final preflight signal."
+    prompt: "Generate a minimal-audit atomic plan for `${feature-folder}` using `${feature-folder}/issue.md` as the only requirements source (no spec/user-story/research). Use directive `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`. Target plan file path is `${plan-path}` and MUST be updated in place. Do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops. The plan MUST include exactly 3 phases: Phase 0 baseline capture, Phase 1 placeholder for constrained small-path implementation work, Phase 2 final QC loop. Final-QC command tasks MUST be unconditional when present in the plan: do not add IN_SCOPE/OUT_OF_SCOPE branching and do not allow SKIPPED as a valid completion state for those tasks. Require validation-only preflight through `atomic_executor` under the single-pass preflight rule (trivial defects fixed in place, at most one return to the planner) ending in `PREFLIGHT: ALL CLEAR` while preserving the same target path. Return `plan-path` and final preflight signal."
     send: true
   - label: Execute Phase 0 only
     agent: atomic_executor
@@ -38,7 +38,7 @@ handoffs:
     send: true
   - label: Build C# atomic plan (preflight all clear)
     agent: csharp-atomic-planning
-    prompt: "You are csharp-atomic-planning.\n\nUse the prompt structure and requirements from `.github/prompts/generate-atomic-plan.prompt.md` as the canonical template.\nThe calling agent may provide a target plan path and full context package; use those exact paths/values.\n\nContext package:\n- objective + expected outcome\n- `${promotion-type}` and `${issue-num}` when available\n- `${feature-folder}`\n- `${feature-folder}/issue.md`\n- `${feature-folder}/spec.md`\n- `${feature-folder}/user-story.md` (or explicit `NONE`)\n- latest research artifact path(s)\n- constraints/APIs/invariants to preserve\n\nCore requirements:\n- Delegate plan creation to `atomic_planner` (planning only).\n- Require `atomic_planner` to run validation-only preflight through `atomic_executor` and iterate until final `PREFLIGHT: ALL CLEAR`.\n- Return the finalized plan path and final preflight signal; do not execute implementation."
+    prompt: "You are csharp-atomic-planning.\n\nUse the prompt structure and requirements from `.github/prompts/generate-atomic-plan.prompt.md` as the canonical template.\nThe calling agent may provide a target plan path and full context package; use those exact paths/values.\n\nContext package:\n- objective + expected outcome\n- `${promotion-type}` and `${issue-num}` when available\n- `${feature-folder}`\n- `${feature-folder}/issue.md`\n- `${feature-folder}/spec.md`\n- `${feature-folder}/user-story.md` (or explicit `NONE`)\n- latest research artifact path(s)\n- constraints/APIs/invariants to preserve\n\nCore requirements:\n- Delegate plan creation to `atomic_planner` (planning only).\n- Require `atomic_planner` to run validation-only preflight through `atomic_executor` under the single-pass preflight rule (trivial defects fixed in place, at most one return to the planner) ending in `PREFLIGHT: ALL CLEAR`.\n- Return the finalized plan path and final preflight signal; do not execute implementation."
     send: true
   - label: Execute approved C# atomic plan
     agent: csharp-atomic-executor

package/resources/customizations/.github/agents/csharp-typed-engineer.agent.md

@@ -6,7 +6,7 @@ tools: [vscode, execute/testFailure, execute/getTerminalOutput, execute/killTerm
 handoffs:
   - label: Architecture + testability plan only (no edits)
     agent: csharp-atomic-planning
-    prompt: "Create a plan ONLY (no implementation edits). Use `.github/prompts/generate-atomic-plan.prompt.md` as the planning contract and resolve it with concrete paths/inputs (`name`, `file`, `spec`, `user-story`, `research`) so there are no placeholders. Produce an executor-ready atomic plan with canonical `### Phase N — ...` headings, `- [ ] [P#-T#]` tasks, mandatory Phase 0 baseline capture, and mandatory final QA loop for all affected toolchains. Plan content must explicitly include: proposed class/module structure, minimal DI seams, MSTest scenario-level test strategy, Moq mock strategy, and exact files to change. After drafting, run the mandatory validation-only preflight loop through the C# planning chain and iterate until `PREFLIGHT: ALL CLEAR`, then return the finalized plan plus the final all-clear signal."
+    prompt: "Create a plan ONLY (no implementation edits). Use `.github/prompts/generate-atomic-plan.prompt.md` as the planning contract and resolve it with concrete paths/inputs (`name`, `file`, `spec`, `user-story`, `research`) so there are no placeholders. Produce an executor-ready atomic plan with canonical `### Phase N — ...` headings, `- [ ] [P#-T#]` tasks, mandatory Phase 0 baseline capture, and mandatory final QA loop for all affected toolchains. Plan content must explicitly include: proposed class/module structure, minimal DI seams, MSTest scenario-level test strategy, Moq mock strategy, and exact files to change. After drafting, run the mandatory single-pass validation-only preflight through the C# planning chain (trivial defects fixed in place, at most one return to the planner) ending in `PREFLIGHT: ALL CLEAR`, then return the finalized plan plus the final all-clear signal."
     send: true
   - label: Implement approved plan
     agent: csharp-atomic-executor
@@ -94,7 +94,7 @@ If any required item is missing in orchestrator handoff mode, STOP and request t
 When in **Orchestrator handoff mode**, this agent MUST run the following delegation chain and MUST NOT bypass it with direct implementation:
 
 1) Delegate to `csharp-atomic-planning` (handoff: **Architecture + testability plan only (no edits)**).
-2) Require planner output to include final `PREFLIGHT: ALL CLEAR` from the preflight validation loop.
+2) Require planner output to include final `PREFLIGHT: ALL CLEAR` from single-pass preflight.
 3) Delegate plan execution to `csharp-atomic-executor` (handoff: **Implement approved plan**).
 4) Delegate final QA to `csharp-atomic-executor` (handoff: **Post-change QA gate (format + analyze + build + tests + coverage)**).
 5) Delegate post-implementation review to `feature_code_review_agent` (handoff: **Post-implementation feature review**).
@@ -205,7 +205,7 @@ The plan should include:
 - Exact files to change (must satisfy scope guardrails).
 
 Orchestrator handoff mode requirement:
-- Even if a draft plan is supplied, delegate to `csharp-atomic-planning` to normalize/validate the plan and run the mandatory preflight validation loop to `PREFLIGHT: ALL CLEAR` before any implementation delegation.
+- Even if a draft plan is supplied, delegate to `csharp-atomic-planning` to normalize/validate the plan and run mandatory single-pass preflight to `PREFLIGHT: ALL CLEAR` before any implementation delegation.
 
 Orchestrator handoff mode hard stop:
 - In this mode, ignore implicit approval shortcuts for direct local execution.

package/resources/customizations/.github/agents/orchestrator.agent.md

@@ -6,7 +6,7 @@ tools: [vscode/runCommand, vscode/extensions, execute, read, agent, edit, search
 handoffs:
   - label: Build minimal-audit atomic plan (preflight all clear)
     agent: atomic_planner
-    prompt: "Generate a minimal-audit atomic plan for `${feature-folder}` using `${feature-folder}/issue.md` as the only requirements source (no spec/user-story/research). Use directive `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`. Target plan file path is `${plan-path}` and MUST be updated in place. Do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops. The plan MUST include exactly 3 phases: Phase 0 baseline capture, Phase 1 placeholder for constrained small-path implementation work, Phase 2 final QC loop. Final-QC command tasks MUST be unconditional when present in the plan: do not add IN_SCOPE/OUT_OF_SCOPE branching and do not allow SKIPPED as a valid completion state for those tasks. Require validation-only preflight through `atomic_executor` and iterate until final `PREFLIGHT: ALL CLEAR` while preserving the same target path. Return `plan-path` and final preflight signal."
+    prompt: "Generate a minimal-audit atomic plan for `${feature-folder}` using `${feature-folder}/issue.md` as the only requirements source (no spec/user-story/research). Use directive `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`. Target plan file path is `${plan-path}` and MUST be updated in place. Do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops. The plan MUST include exactly 3 phases: Phase 0 baseline capture, Phase 1 placeholder for constrained small-path implementation work, Phase 2 final QC loop. Final-QC command tasks MUST be unconditional when present in the plan: do not add IN_SCOPE/OUT_OF_SCOPE branching and do not allow SKIPPED as a valid completion state for those tasks. Require single-pass validation-only preflight through `atomic_executor` (trivial defects fixed in place, at most one return to the planner) ending in `PREFLIGHT: ALL CLEAR` while preserving the same target path. Return `plan-path` and final preflight signal."
     send: true
   - label: Execute Phase 0 only
     agent: atomic_executor
@@ -38,7 +38,7 @@ handoffs:
     send: true
   - label: Build atomic plan (preflight all clear)
     agent: atomic_planner
-    prompt: "You are atomic_planner.\n\nUse the prompt structure and requirements from `.github/prompts/generate-atomic-plan.prompt.md` as the canonical template.\nThe calling agent provides a REQUIRED target plan path `${plan-path}`; update this file in place and do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops.\n\nContext package:\n- objective + expected outcome\n- `${promotion-type}` and `${issue-num}` when available\n- `${feature-folder}`\n- `${feature-folder}/issue.md`\n- `${feature-folder}/spec.md`\n- `${feature-folder}/user-story.md` (or explicit `NONE`)\n- latest research artifact path(s)\n- constraints/APIs/invariants to preserve\n\nCore requirements:\n- Generate a deterministic phased atomic plan (planning only).\n- Require validation-only preflight through `atomic_executor` and iterate until final `PREFLIGHT: ALL CLEAR` while preserving the same target path `${plan-path}`.\n- Plan MUST include explicit coverage-bearing baseline and final-QC testing tasks for each language in scope where policy requires coverage; coverage MUST NOT be left as UNVERIFIED for PASS outcomes.\n- Return the finalized plan path and final preflight signal; do not execute implementation."
+    prompt: "You are atomic_planner.\n\nUse the prompt structure and requirements from `.github/prompts/generate-atomic-plan.prompt.md` as the canonical template.\nThe calling agent provides a REQUIRED target plan path `${plan-path}`; update this file in place and do NOT create additional `plan.*.md` siblings during drafting or preflight revision loops.\n\nContext package:\n- objective + expected outcome\n- `${promotion-type}` and `${issue-num}` when available\n- `${feature-folder}`\n- `${feature-folder}/issue.md`\n- `${feature-folder}/spec.md`\n- `${feature-folder}/user-story.md` (or explicit `NONE`)\n- latest research artifact path(s)\n- constraints/APIs/invariants to preserve\n\nCore requirements:\n- Generate a deterministic phased atomic plan (planning only).\n- Require single-pass validation-only preflight through `atomic_executor` (trivial defects fixed in place, at most one return to the planner) ending in `PREFLIGHT: ALL CLEAR` while preserving the same target path `${plan-path}`.\n- Follow the design-level plan contract and include a `## Pre-Mortem` section.\n- Plan MUST include explicit coverage-bearing baseline and final-QC testing tasks for each language in scope where policy requires coverage; coverage MUST NOT be left as UNVERIFIED for PASS outcomes.\n- Return the finalized plan path and final preflight signal; do not execute implementation."
     send: true
   - label: Execute approved atomic plan
     agent: atomic_executor
@@ -88,6 +88,9 @@ Use these reusable skills to avoid duplicating shared operations:
 - `repo-automation-adapter`
 - `atomic-plan-contract`
 - `acceptance-criteria-tracking`
+- `execution-environment`
+
+Read `.github/skills/execution-environment/SKILL.md` first, before any delegation. It states the tool routes, command-text restrictions, batch budget, hook context, CI shape, contract tests, evidence rules, coverage and file-size gates, and test-isolation checks; delegation prompts reference it instead of restating them.
 
 # Non-negotiable mission behavior
 
@@ -378,9 +381,9 @@ Apply this exact loop after the first feature-review result and after every re-r
    - `REVIEW_STATUS: REMEDIATION_REQUIRED`
    - `REMEDIATION_INPUTS: <path>`
    - `REMEDIATION_PLAN: <path>`
-2. Persist `${review-status}`, `${remediation-inputs-path}`, `${remediation-plan-path}`, and `${remediation-pass}` in the checkpoint.
-3. Delegate handoff **Preflight remediation plan clearance** against `${remediation-plan-path}`.
-4. If preflight returns `PREFLIGHT: REVISIONS REQUIRED`, delegate handoff **Revise remediation plan in place** and then repeat Step 3 against the same `${remediation-plan-path}` until the terminal signal is `PREFLIGHT: ALL CLEAR`.
+2. Persist `${review-status}`, `${remediation-inputs-path}`, `${remediation-plan-path}`, and `${remediation-pass}` in the checkpoint. Confirm that `${remediation-inputs-path}` carries exactly one line `Remediation-Mode: proportionate` or `Remediation-Mode: design`: proportionate when every autonomous finding can be fixed without changing a spec acceptance criterion, a public interface, or the file inventory beyond the branch diff plus tests and mirrors (CI-failure findings are normally proportionate), otherwise design.
+3. Delegate handoff **Preflight remediation plan clearance** against `${remediation-plan-path}`, with the preflight directive in the handoff prompt only. Preflight is single-pass: trivial defects are fixed in place. For `Remediation-Mode: proportionate`, the clearance and execution may run as one executor delegation that stops with `BLOCKED at preflight (before [P0-T1])` on a substantive defect; that converts the cycle to `Remediation-Mode: design`.
+4. If preflight returns `PREFLIGHT: REVISIONS REQUIRED`, delegate handoff **Revise remediation plan in place** once with the full `PREFLIGHT-DEFECT:` list and then run Step 3 once more against the same `${remediation-plan-path}`. If that confirming preflight still reports a substantive defect, record `blocked_preflight_iteration_limit` and stop; a plan returns to the planner at most once.
 5. Delegate handoff **Execute remediation plan** only after the exact preflight signal is `PREFLIGHT: ALL CLEAR`.
 6. Stage all files with `git add -A`.
 7. Do not continue unless staged changes now exist. If staging is empty, stop and record blocked state because remediation execution did not produce a commit-ready delta.