@danmoisan/drm-copilot-mcp 1.1.19 → 1.1.20

package/resources/claude-customizations/.claude/skills/execution-environment/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: execution-environment
+description: 'Execution-environment brief for research, planning, preflight, execution, and orchestration. Use before planning or delegating work so tool routes, command-text restrictions, the batch budget, hook context, CI shape, contract tests, evidence rules, coverage and file-size gates, and test-isolation checks are known and are not restated in plans.'
+---
+
+# Execution-Environment Brief
+
+## Purpose and Maintenance
+
+This brief states the environment facts that every researcher, planner, preflight executor, executor, and orchestrator needs before work starts. Plans reference this brief instead of restating its content; a plan that restates a tool route, a launcher, or a command-text restriction duplicates text that goes stale when this brief changes.
+
+Maintenance rule: this brief is updated in the same change that alters any fact it states. It carries no line numbers and no commit identifiers; it cites files, symbols, headings, job names, and test names. The same text is byte-identical in six locations: `.claude/skills/execution-environment/SKILL.md`, `.agents/skills/execution-environment/SKILL.md`, `.github/skills/execution-environment/SKILL.md`, and their bundled copies under `extensions/drm-copilot/resources/`. Where the Claude and Codex runtimes differ, both paths are named (`.claude/hooks/...` and `.codex/hooks/...`).
+
+## Tool Routes by Agent
+
+- `atomic-executor` has no PowerShell tool. Its `tools:` list is Read, Grep, Glob, Edit, Write, several `Bash(...)` entries, the four `mcp__drm-copilot__run_poshqc_*` tools, and `mcp__drm-copilot__validate_orchestration_artifacts`. A `(pattern)` suffix on a `tools:` entry admits the bare tool, so the executor has Bash, subject to the repository hooks and the runtime guard described under Command-Text Restrictions.
+- `atomic-planner` has no Bash. It has Read, Grep, Glob, Edit, Write, and `mcp__drm-copilot__validate_orchestration_artifacts`, so it can validate a plan with the installed validator before handoff but cannot run any toolchain command.
+- `task-researcher` has Read, Grep, Glob, WebFetch, and Write. It cannot run `git show` or `gh`; facts that need either are marked for the orchestrator to confirm.
+- `orchestrator` and the main session running the `orchestrate` skill have Bash, the PoshQC and validation MCP tools, and the `Agent` tool. Only they can delegate, so any step that needs a further agent run is orchestrator-owned.
+- PowerShell for the executor therefore runs through the `mcp__drm-copilot__run_poshqc_*` tools or through a `sh` launcher script stored under `SCRATCH` that invokes PowerShell 7 from inside the script file.
+
+## Command-Text Restrictions
+
+Two separate mechanisms restrict Bash command text. They are kept apart here because they have different causes and different fixes.
+
+- **Worktree isolation guard (Claude Code runtime behavior, not a repository hook).** Inside an agent-isolated worktree, the Claude Code runtime refuses Bash command text it cannot show stays inside the worktree. Observed refusals include text containing `pwsh`, `bash`, or `wsl`, heredocs, `printf --`, a `cd <path> &&` prefix before `git`, `git -C <other worktree>`, embedded `jq` filter strings, an unquoted shell variable in an option position, and loops or other compound constructs around `sh`. Text that passes includes `sh <file>.sh` with a literal path, `npx`, `poetry run python <script>`, `gh`, worktree-scoped `git`, and `git commit -F <file>`. No file under `.claude/hooks/` implements this guard, and no settings file registers it.
+- **Repository hooks.** `.claude/hooks/validate-bash.ps1` (`.codex/hooks/validate-bash.ps1` for Codex; functions `Get-BlockedBashPattern`, `Get-CdChainedReadCommandMatch`, `Get-BashBlockReason`) denies destructive patterns (`rm -rf`, forced pushes, `git reset --hard`, recursive forced removal) and a `cd` followed later in the same command by a file-reading command such as `grep`, `cat`, `head`, `tail`, `less`, `more`, `awk`, or `sed -n`. `.claude/hooks/enforce-parallel-worktree-removal-gate.ps1` denies the literal worktree-removal command anywhere in a command.
+- A multi-line `poetry run python -c` program exits 0 without running. Put Python helpers in a file under `SCRATCH` and run the file.
+
+## PowerShell Route and PoshQC MCP Limits
+
+- PoshQC MCP results carry no output. The summary string is composed from a fixed template before the child process runs (`runPoshQcWorkflow` in `extensions/drm-copilot/src/repo-automation-service.ts`), and `RepoAutomationExecutionResult` has no exit-code or output field. An `ok: true` result proves only that the tool was invoked.
+- Counts, percentages, and findings therefore come from files or direct runs: pass and fail counts from `artifacts/pester/pester-junit.xml`, line coverage from `artifacts/pester/powershell-coverage.xml`, and analyzer findings from a direct `Invoke-ScriptAnalyzer` run with `scripts/powershell/PoshQC/settings/pssa.settings.psd1`.
+- The MCP test tool reads the installed extension's settings. Branch-current Pester runs import `scripts/powershell/PoshQC/PoshQC.psd1` and call `Invoke-PoshQCTest` from a `sh`-launched PowerShell 7. The coverage population is derived by `Invoke-PoshQCTest` from `config/poshqc-coverage.json`; there is no hand-maintained coverage path list.
+- `Invoke-Pester` without `-EnableExit` (or `Run.Exit`) exits 0 when tests fail; read the JUnit file rather than the exit code of such a run.
+
+## Batch Budget
+
+- In direct mode the batch-budget hooks allow at most three distinct production files per kind in one session: the fourth distinct non-test PowerShell file is denied with `POWERSHELL_LARGE_PATH_REQUIRED` and the fourth distinct non-test Python file with `PYTHON_LARGE_PATH_REQUIRED` (`.claude/hooks/enforce-powershell-batch-budget.ps1` and `.claude/hooks/enforce-python-batch-budget.ps1`; Codex copies under `.codex/hooks/`). Test files never count.
+- Exemption: the cap does not apply when `artifacts/orchestration/orchestrator-state.json` in the worktree that holds the hook script selects the `large`, `remediation`, or `preparation` route and is not terminal (`Test-BatchBudgetLargePathRoute` in `.claude/hooks/enforce-batch-budget-route.ps1`). An isolated subagent worktree has no checkpoint, because `artifacts/` is gitignored, so direct mode applies there.
+- Bundle mirror copies under `extensions/drm-copilot/resources/` are production files and count against the cap.
+- A scratch `.ps1` file counts when it resolves inside the worktree root. Files under `SCRATCH`, which is outside the worktree root, are discarded without consuming a slot.
+- Only `Write` and `Edit` calls are seen (the hook matcher is `Write|Edit`). Files written by Bash, by a copy script, or by a generator are not seen.
+- Budget state is kept per session under `.claude/state/`; there is no automatic reset.
+
+## Hook Execution Context
+
+- Hooks for an isolated subagent run inside the subagent's worktree with that worktree's hook scripts, which are `main`'s copies. A hook change on a branch is not exercised by isolated subagents until it merges.
+- Hook behavior on a branch is therefore proven by Pester suites, not by a live subagent run. A live check of a branch hook needs a non-isolated delegation from the item worktree.
+- Enforcement hooks do not invoke Python; bash is preferred and PowerShell is acceptable (`tests/scripts/claude-runtime/enforcement-hooks-no-python-invocation.Tests.ps1`).
+
+## MCP Surfaces Run the Installed Extension
+
+- Every `mcp__drm-copilot__*` tool runs the installed extension, not the branch. `validate_orchestration_artifacts` applies the installed rule set, so validator rules added on a branch apply through MCP only after the extension release that carries them is installed.
+- Branch-current plan validation runs the repository's Python CLI `scripts/dev_tools/validate_orchestration_artifacts.py` with its `plan` subcommand, through Poetry in module form.
+- A push-down served by the MCP tools writes the installed extension's bundled payload; a repository-side edit under `extensions/drm-copilot/resources/` changes that payload only after a rebuild and reinstall.
+
+## CI Shape and Required Checks
+
+- `.github/workflows/ci.yml` triggers on `push` to `main` and `development`, on `pull_request` to `main`, `development`, and `epic/**`, on `workflow_dispatch`, and on `merge_group` (`types: [checks_requested]`, added by issue #952), with no path filters. When the merge queue on `main` is enabled, every required check is produced by a `merge_group` run of `ci.yml` as well as by the pull-request run; `.github/workflows/README.md` (`## Triggers`) records the trigger set.
+- Jobs in `ci.yml` and their check names: `Change scope` (job `changes`, the change-scope decision below); `CI full run` (job `full-run-marker`, which runs only on a full run, marks that run as a valid base for later decisions, and is not a required check); `quality-checks7 / Code Quality & Tests (<python-version>)` on Python 3.10, 3.11, 3.12, and 3.13 (`_quality-checks.yml`: Black check, Ruff, Pyright, the Codex generator `--check`, the tier classification, Pytest with line and branch coverage, and the coverage-threshold check on the JSON report totals); `security-scan / Security Scanning` (its `safety check` step carries `continue-on-error: true` and does not fail the check); `docs-validation / Documentation Validation`; `build-check / Build Package`; `shell-coverage / Shell Coverage (Bats + kcov)`; `drm-copilot-extension-tests / drm-copilot Extension Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `root-typescript-tests / Root TypeScript Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `NPM Audit Gate / npm audit (<manifest>)` (the calling job carries the name `NPM Audit Gate`); and the `poshqc` group below.
+- PowerShell CI (`_poshqc.yml`): `poshqc / PowerShell QC static` (format and analyze on `windows-latest`); the shard matrix `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3` (`Invoke-PoshQCTest -ShardIndex -ShardCount` over the scan folders of `config/poshqc-scan.json`, with coverage, on `windows-latest`); the aggregator `poshqc / PowerShell QC`, which requires the static and shard jobs to succeed, verifies shard completeness against a Pester discovery count, and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)`, which runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest` with coverage disabled. A new test file under a scanned folder is assigned to a shard automatically and is counted by the completeness check.
+- Change-scope decision (issue #962): the `Change scope` job runs `scripts/ci/Invoke-CiChangeScope.ps1` and publishes the job output `code`. The decision is `code=false` (docs-only) only on a `pull_request` event from this repository when every file changed since the newest successful `ci.yml` run on the pull-request branch whose `CI full run` job succeeded, and whose head commit is an ancestor of the current head, is on the allowlist `config/ci-docs-only-paths.json`. A path is allowlisted when it starts with `docs/features/active/`, `docs/features/completed/`, `docs/features/potential/`, or `docs/research/`, does not start with `docs/features/templates/` or `docs/features/potential/template.md`, and ends in `.md`, `.txt`, `.log`, `.json`, or `.xml`; the allowlist file itself is not allowlisted. Every other case is a full run (`code=true`): `push`, `merge_group`, and `workflow_dispatch` events, a fork pull request, unreadable run or job data, no earlier full green run, a missing or non-ancestor base, an empty diff, any path outside the allowlist, and any error. The decision step carries `continue-on-error: true` and the callers compare the output with `!= 'false'`, so a failed or missing decision also gives a full run.
+- Docs-only behavior (`code=false`): `ci.yml` passes `run-heavy: false` to `_quality-checks.yml`, `_security-scan.yml`, `_build-check.yml`, `_poshqc.yml`, `_shell-coverage.yml`, and `_drm-copilot-extension-tests.yml`. Each required job still starts under its full-run check name with every step skipped, so every required context reports `success` without running its suite. In `_poshqc.yml` the aggregator `poshqc / PowerShell QC` runs with every step gated, and `poshqc / PowerShell QC static`, the shard jobs, and `poshqc / PowerShell hook suites (Linux)` are skipped at job level. `docs-validation / Documentation Validation` runs in full. `root-typescript-tests`, `NPM Audit Gate`, and `CI full run` are skipped at job level. A `success` on a docs-only commit is therefore not evidence that the heavy suites pass for that commit; that evidence is the newest run whose `CI full run` job succeeded.
+- A commit that changes any path outside the allowlist (any code, workflow, configuration, script, test, or customization file) runs the full set of jobs, and its `CI full run` job marks it as a base for later docs-only decisions. A standalone `workflow_dispatch` of a reusable workflow, or a caller that omits `run-heavy`, also runs in full. `.github/workflows/README.md` (`## Change-Scope Decision (Issue #962)`) records the reason codes and the per-context behavior table.
+- Required contexts of ruleset 15241672, confirmed by the orchestrator through `gh api` on 2026-10-16: `drm-copilot-extension-tests / drm-copilot Extension Tests (ubuntu-latest)`, `drm-copilot-extension-tests / drm-copilot Extension Tests (windows-latest)`, `docs-validation / Documentation Validation`, `poshqc / PowerShell QC`, `shell-coverage / Shell Coverage (Bats + kcov)`, `security-scan / Security Scanning`, `quality-checks7 / Code Quality & Tests (3.10)`, `quality-checks7 / Code Quality & Tests (3.11)`, `quality-checks7 / Code Quality & Tests (3.12)`, `quality-checks7 / Code Quality & Tests (3.13)`, `build-check / Build Package`.
+- Refresh rule: a change that renames a job, adds or removes a matrix entry, or changes the ruleset refreshes this list in the same change, and the orchestrator re-confirms the contexts with a read-only `gh api repos/drmoisan/drm-copilot/rulesets/15241672` call before relying on them.
+- Skipped-check semantics: a job skipped by an `if:` condition reports success to a required check; a workflow that does not run at all reports nothing, which leaves the required check pending.
+- A pull request into a branch other than `main`, `development`, or `epic/**` gets no CI run; dispatch `ci.yml` manually for it.
+
+## CI-Only Failure Classes
+
+- A test that reads gitignored `artifacts/` state passes only on a worktree that holds that state; CI has none.
+- A fixture rooted at a drive letter or a `C:/workspace` path fails `path.isAbsolute` and path joins on Linux.
+- `_shell-coverage.yml` checks out at depth one, so `origin/main` does not exist in that job; no test may diff against it.
+- The Linux hook-suite job runs `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on a case-sensitive file system: use `Join-Path`, forward-slash relative paths, exact file-name case, and no drive letters or backslash literals.
+- The `.gitattributes` rule `* text=auto eol=lf` normalizes line endings on checkout, so a CRLF fixture committed as text is not CRLF in CI.
+- Shard and single-process Pester runs expose module-scope import visibility and leaked state that per-suite local runs hide.
+
+## Contract Tests That Pin Mirrored Files
+
+Run these after editing any mirrored or bundled file; each is under `tests/scripts/dev_tools/` unless named otherwise.
+
+- `test_push_down_claude_resource_contracts.py` and `test_push_down_codex_and_agents_resource_contracts.py`: every distributable `.claude`, `.agents`, and `.codex` file exists in the bundle with equal text.
+- `test_push_down_claude_pack_manifest_completeness.py` and `test_push_down_codex_and_agents_pack_manifest_completeness.py`: every bundled file is listed in a pack manifest.
+- The Codex generator check: `scripts/dev_tools/generate_codex_agent_variants.py` run in module form with `--check` (base agents are hand-edited; variants, bundle copies, and the Codex `core.json` are generated).
+- `test_codex_agent_wrapper_contracts.py` and `test_codex_handoff_contract_parity.py`: pinned Codex agent fragments and handoff parity.
+- `test_claude_rules_frontmatter.py`: rule `paths:` scopes and that every preloaded skill exists.
+- `parallel_orchestrator_surface_expectations.py` (`PINNED_FROZEN_SURFACE_HASHES`): byte hashes of frozen orchestration surfaces, including `.claude/skills/epic-orchestrate/SKILL.md` and `.claude/agents/epic-orchestrator.md`.
+- `test_quality_checks_workflow_contracts.py`: workflow step conditions.
+- `test_push_down_issue_824_follow_ups.py`: pushed rules and skills name no consuming product.
+- `test_typescript_toolchain_instruction_contracts.py`: no reference to another test framework, and every backticked npm script token in the pinned mirrors exists in the root `package.json`.
+- `tests/scripts/claude-runtime/claude-architecture-doc.Tests.ps1` and `tests/scripts/claude-runtime/hook-dependency-guard-completeness.Tests.ps1`: agent tool names in the architecture document and the guarded dot-source pattern in hooks.
+
+## Preflight Defect Classes the Validator Cannot See
+
+These pass every validator rule and are found only by reading the plan against the tree:
+
+- `git grep` against a file the plan creates (untracked, so invisible to `git grep`); a search pattern beginning with `-` that is not passed through `-e`.
+- A checkbox diff-pair assertion against a file the plan adds, and a CRLF fixture under the `eol=lf` attribute rule.
+- A new TypeScript production file without its own `coverageThreshold` entry in `extensions/drm-copilot/jest.config.cjs`, whose threshold map has per-file entries only and no `global` key.
+- A per-file coverage floor asserted for code that the tests replace with blanket mocks.
+- Batch-budget exhaustion across a session, and an acceptance condition that depends on a branch hook being exercised by an isolated subagent.
+- `origin/main` advancing during planning: scope diffs anchor on the merge base of `origin/main` and `HEAD`, never on `origin/main` itself.
+- `Measure-Object -Line` counts non-empty lines only; physical line counts use `wc -l` or `@(Get-Content -LiteralPath <path>).Count`.
+- A coverage argument written as a filesystem path measures nothing; the dotted module form is required, and branch figures come from the JSON report, not the combined terminal column.
+- A task that changes the observable behavior of an existing function, script, fixture, or test stub (signature, argv, output, exit status, or written files) while the tests that assert that behavior are outside the task's file set: those tests fail once the change lands, and the plan's own acceptance cannot be met. Preflight searches the test tree for the changed symbol, the file name, and the asserted output, and confirms that the task names each matching test with its disposition (unchanged because unaffected, or updated with the reason).
+- A plan that alters a fact this brief states (it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) with no task that updates the brief in the same change, in all six byte-identical copies: the plan then breaks the maintenance rule in `## Purpose and Maintenance`. Preflight compares each task's changes against the facts this brief states and confirms that a brief-update task exists and that the plan's `Mirror parity` Pre-Mortem bullet names it.
+
+## Evidence and Documentation Rules
+
+- Evidence lives under `<FEATURE>/evidence/<kind>/` with kinds `baseline`, `regression-testing`, `qa-gates`, `other`, `issue-updates`, and `remediation-baseline` (`.claude/skills/evidence-and-timestamp-conventions/SKILL.md`; enforced by `.claude/hooks/enforce-evidence-locations.ps1`).
+- Evidence filenames carry the UTC time of the write, read from the clock, in the `yyyy-MM-ddTHH-mm` shape; a consumer selects the lexicographically greatest `<name>.*.md`. Plan files are stamped by the feature-folder tooling in America/New_York.
+- Every command-step artifact carries `Timestamp:`, `Command:`, `EXIT_CODE:`, and `Output Summary:`. No artifact records an absolute path, a host name, or a session scratchpad path; scratch locations are recorded as the token `SCRATCH`.
+- `SCRATCH` is `<session scratchpad>/issue-<issue-num>/`, and scratch file names start with `issue-<issue-num>-`.
+- `.github/workflows/_docs-validation.yml` checks only that `README.md` is present and non-empty and that `LICENSE` exists, and it warns when two instruction files are missing. There is no Markdown lint or link check in CI.
+
+## Coverage and File-Size Gates
+
+- Line coverage of at least 85% and branch coverage of at least 75% apply per changed production file in Python and TypeScript. PowerShell has a line threshold of 85% and no branch gate, because Pester does not measure branch coverage. No production file may be excluded from measurement.
+- Python: measure a module with `--cov=<dotted.module>`, `--cov-branch`, `--cov-report=term-missing`, and `--cov-report=json:<path>`; read branch figures from the JSON report.
+- TypeScript: a new production file needs its own entry in the `coverageThreshold` map of `extensions/drm-copilot/jest.config.cjs`; Jest runs through `node run-jest.cjs` in `extensions/drm-copilot/`.
+- PowerShell: per-file line coverage is read from `artifacts/pester/powershell-coverage.xml` written by the self-hosted PoshQC module.
+- No production, test, or reusable script file exceeds 500 physical lines; Markdown is exempt. Files at or near the limit are not extended; new logic goes into a new module and a new test file.
+
+## Test Isolation Checks
+
+- Tests create no temporary files; file and transcript reads go through injected seams with in-memory content.
+- Before review, run each isolation check and record it under `<FEATURE>/evidence/regression-testing/`:
+  - a seeded shuffled Jest run (`node run-jest.cjs --randomize --seed=<n>` in `extensions/drm-copilot/`) with the seed recorded;
+  - a reversed-order run of the new or changed Python test modules in one process;
+  - a seeded shuffled file-order run of the touched Pester suites in one process, with at least three seeds and each seed and its file order recorded;
+  - a fresh single-process Pester run over `tests/scripts`, which is the CI shape.
+- An order dependence found by any run is fixed on both sides: the suite that leaves state behind (globals, functions, environment variables, mocks, imported modules, script-scope state) and the suite that assumes prior state. Every seed is then re-run.

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

@@ -25,6 +25,7 @@ Before proceeding, the orchestrator must:
 1. Read `CLAUDE.md` for repository tone policy and architectural context.
 2. Read applicable `.claude/rules/` files for the languages in scope.
 3. Read the policy files listed in the compliance reading order section of `CLAUDE.md`.
+4. Read the `execution-environment` skill (`.claude/skills/execution-environment/SKILL.md`) before delegating any worker. Delegation prompts and plans reference that brief instead of restating tool routes, command-text restrictions, the batch budget, hook context, or CI shape.
 
 ## Checkpoint Handling
 
@@ -131,12 +132,18 @@ After reading `artifacts/orchestration/orchestrator-state.json`, the main sessio
 
 The orchestrator does not perform deep implementation itself. It coordinates, tracks state, and enforces completion.
 
+Single-pass preflight for S4 planning (and for preparation mode). The directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY` goes in the `atomic-executor` delegation prompt only, never in the plan file. Preflight follows `### Single-Pass Preflight` in the `atomic-plan-contract` skill: the preflight executor fixes trivial defects in place and returns only substantive defects as `PREFLIGHT-DEFECT:` lines. The at-most-one-return rule applies:
+
+1. Preflight round one returns `PREFLIGHT: ALL CLEAR` (in-place `PREFLIGHT-FIX:` lines permitted) or `PREFLIGHT: REVISIONS REQUIRED` with every substantive defect listed.
+2. On `PREFLIGHT: REVISIONS REQUIRED`, delegate one `atomic-planner` revision of the same plan file carrying the full `PREFLIGHT-DEFECT:` list, then run preflight round two. A plan returns to the planner at most once.
+3. If round two still returns a substantive defect, halt with `blocked_reason: "validator_failed"` and record both preflight returns in the checkpoint. Do not open a third round.
+
 ## Preparation Mode
 
 A delegation prompt carrying the literal marker `Preparation mode: true` (issued by `epic-planner` per the `.claude/skills/epic-plan/SKILL.md` kickoff line) scopes the run to planning only:
 
 - **Route.** Select `route_id: preparation`. The route's routing-matrix entry requires receipts for `task-researcher`, `prd-feature`, `atomic-planner`, and `atomic-executor`; the skills `orchestrate`, `feature-promotion-lifecycle`, and `atomic-plan-contract`; and the promotion plus validator MCP tools.
-- **Scope.** Run promotion (MCP surface), research, feature documents (`spec.md`, `user-story.md`), atomic planning, and the atomic-executor preflight (precondition validation only, R2 semantics: iterate plan revisions until `PREFLIGHT: ALL CLEAR`). Atomic execution, PR authoring, CI monitoring, and feature review are out of scope and are executed later by `epic-orchestrator`.
+- **Scope.** Run promotion (MCP surface), research, feature documents (`spec.md`, `user-story.md`), atomic planning, and the atomic-executor preflight (precondition validation only, under the single-pass preflight and at-most-one-return rule stated under `## Delegation Model`). Atomic execution, PR authoring, CI monitoring, and feature review are out of scope and are executed later by `epic-orchestrator`.
 - **Terminal checkpoint.** Stop with `completed_steps` containing `S3_promotion` and `S4_atomic_planning`, `next_step: "S5_atomic_execution"`, out-of-scope step statuses set to `not-applicable`, and `blocked_reason: "none"`. Do NOT assert completion (`next_step: "complete"`, `S12_complete`, or a `completed` step8/9/10 status): the run has no PR or CI evidence, and the route's `requires_ci_gate: false` exempts it from `ci_gate` at the completion validator instead.
 - **Premise-falsified halt.** Use `blocked_reason: "premise_falsified"` when every delegation and validator succeeded but evidence gathered during execution falsified the plan's premise. Still record the evidence path in free-form checkpoint keys; `blocked_reason` carries only the classification. The preparation terminal checkpoint above still sets `blocked_reason: "none"`. The full `blocked_reason` vocabulary and its partition are in `.claude/rules/orchestrator-state.md`.
 - **Commit.** Commit the prepared feature folder and plan to the current branch (the worktree branch created off the epic integration branch) before stopping, and report the `plan-path` and preflight status in the final output.
@@ -228,10 +235,11 @@ The orchestrator must not report completion until:
 
 Before delegating to the `feature-review` subagent, the orchestrator must:
 
-1. Stage all modified and new files: `git add -A`.
-2. Delegate to `Agent(commit-message)` to generate a conventional commit message from the staged diff. The agent is read-only and returns message text only; it does not commit.
-3. Commit using the generated message: `git commit -m "<generated message>"`. The `git add` and `git commit` actions remain on the orchestrator.
-4. Only after a successful commit may the orchestrator proceed to the `feature-review` delegation.
+1. Confirm the self-review: the lexicographically greatest `self-review.*.md` under `<FEATURE>/evidence/qa-gates/` exists and records no FAIL row. If it is missing or records a FAIL row, run a proportionate correction (one planner delegation and one combined preflight-and-execute executor delegation, as under `## Remediation Loop (R1–R5)`) that fixes the failing items and rewrites the self-review, then repeat this check before the commit.
+2. Stage all modified and new files: `git add -A`.
+3. Delegate to `Agent(commit-message)` to generate a conventional commit message from the staged diff. The agent is read-only and returns message text only; it does not commit.
+4. Commit using the generated message: `git commit -m "<generated message>"`. The `git add` and `git commit` actions remain on the orchestrator.
+5. Only after a successful commit may the orchestrator proceed to the `feature-review` delegation.
 
 The review subagent compares against a base branch; uncommitted changes are invisible to the diff tool and cannot be audited.
 
@@ -259,8 +267,13 @@ A bounded loop consisting of five steps. The attempt count is `remediation_loop.
 
 Cycle accounting: a remediation attempt is complete when R3 execution finished (`execution_status: "complete"`) and the pre-R4 commit recorded a non-empty change set; only then set `candidate_applied: true` on that cycle and increment `completed_attempts`. A cycle that ends without a candidate (execution not started, execution failed, or an empty staged change set) records `candidate_applied: false` and consumes no number. It is followed by at most one re-plan under the same number when the executor output identifies an autonomous plan defect; otherwise reclassify the blocker (typically `external_dependency`) and halt. Two consecutive no-candidate cycles halt with `step6_status: "blocked_remediation_loop_limit"`. Local, CI-failure, merge-conflict, and parallel-drift cycles share the one count.
 
+Remediation mode. Before R1, the orchestrator writes exactly one line into the cycle's `remediation-inputs.<timestamp>.md`: `Remediation-Mode: proportionate` or `Remediation-Mode: design`. The classification rule: a cycle is proportionate when every `autonomous` finding can be fixed without changing a spec acceptance criterion, a public interface, or the item's file inventory beyond the files already in the branch diff plus their tests and mirrors; otherwise the cycle is design. CI-failure findings are normally proportionate.
+
+- **Proportionate cycle.** R1 is one `atomic-planner` delegation that writes a short remediation plan carrying a `## Pre-Mortem` section and a final self-review task. R2 and R3 run as one `atomic-executor` delegation: the executor runs single-pass preflight with in-place trivial fixes (`### Single-Pass Preflight` in `atomic-plan-contract`) and then executes the plan. Record `preflight: {iterations: 1, final_status: "clear"}` on the cycle before `execution_status`. If preflight finds a substantive defect, the executor stops with `BLOCKED at preflight (before [P0-T1])`, a plan delta, and no checked task; the orchestrator rewrites the mode line to `Remediation-Mode: design` and the cycle continues as a design cycle with one planner revision. The pre-R4 commit, R4, and R5 are unchanged.
+- **Design cycle.** R1 to R5 run as listed below, and R2 follows the single-pass preflight and at-most-one-return rule.
+
 - **R1 — Remediation planning:** Delegate to `atomic-planner` with `remediation-inputs.<timestamp>.md` path as primary context. Receive `remediation-plan.<timestamp>.md` in the active feature folder.
-- **R2 — Preflight clearance:** Delegate to `atomic-executor` for precondition validation only (no implementation). If the executor does not return `PREFLIGHT: ALL CLEAR`, return to R1 and re-delegate to `atomic-planner` with the required-changes output from the executor. Only after `PREFLIGHT: ALL CLEAR` may the orchestrator advance to R3.
+- **R2 — Preflight clearance:** Delegate to `atomic-executor` for precondition validation only (no implementation), with the preflight directive in the delegation prompt. Trivial defects are fixed in place. If the executor returns `PREFLIGHT: REVISIONS REQUIRED`, return to R1 once and re-delegate to `atomic-planner` with the full `PREFLIGHT-DEFECT:` list; if the following preflight still reports a substantive defect, record `final_status: "blocked_preflight_iteration_limit"` on the cycle and halt per `.claude/skills/remediation-handoff-atomic-planner/SKILL.md`. Only after `PREFLIGHT: ALL CLEAR` may the orchestrator advance to R3.
 - **R3 — Remediation execution:** Delegate to `atomic-executor` with full execution authorization. Each task's toolchain loop (format → lint → type-check → test) is mandatory; no skipping.
 - **Pre-R4 commit:** Stage all changes (`git add -A`), delegate to `Agent(commit-message)` to generate a commit message from the staged diff (the agent returns message text only and does not commit), then commit with the generated message. The `git commit` action remains on the orchestrator. Advance to R4 only after a successful commit.
 - **R4 — Re-audit:** Delegate to `feature-review` with the same inputs as the original review (resolved base branch, feature folder, refreshed PR context artifacts, acceptance-criteria source). No scope narrowing. The canonical issue number line must be included.
@@ -298,7 +311,7 @@ S9 procedure:
 3. Parse the JSON by running `pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1 -ChecksJson <checks-json> -HeadSha <head-sha>`, appending `-RequireWorkflow CI` when `epic_mode` is `true`. The parser emits the `ci_gate` object defined below and derives `ci_gate.conclusion` over the queried checks (every check on the PR head SHA, for every PR): `success` when every queried check passed or was skipped, `failure` when any queried check failed or was cancelled, and `pending` when any queried check is still in progress. With `-RequireWorkflow CI`, the parser returns `pending` instead of `success` until at least one check whose `workflow` is `CI` has passed.
 4. Poll with a bounded interval and a documented total timeout while `conclusion == "pending"`. When the timeout is exhausted, record the timeout as a finding with `Remediability: awaiting_ci` in `remediation-inputs.<timestamp>.md` and follow the wait branch in Post-Review Outcome Evaluation (`blocked_reason: "awaiting_ci"`, `next_step: "S9_ci_green"`); `step9_status` stays `pending`. A poll timeout does not enter the remediation loop.
 5. Write the `ci_gate` object and `last_verified_ci_sha` to the checkpoint, and set `step9_status` to `passed` only when `ci_gate.conclusion == "success"` AND `ci_gate.head_sha` equals the current PR head SHA.
-6. If the checkpoint's `epic_mode` is `true`, execute `gh pr merge --merge <PR>` merging the feature branch into `epic_context.integration_branch` (already the PR's base branch per the epic-mode `--base` override applied at S8). On success, record `epic_merge: { merge_commit_sha, target_branch, merged_at }` in the checkpoint. On failure due to merge conflict (non-mergeable PR), do not retry blindly: convert the conflict into a synthetic Blocking finding per "Merge-Conflict Remediation" below and re-enter the standard R1–R5 remediation loop; do not proceed to DONE.
+6. If the checkpoint's `epic_mode` is `true`, execute `gh pr merge --merge <PR>` merging the feature branch into `epic_context.integration_branch` (already the PR's base branch per the epic-mode `--base` override applied at S8). On success, record `epic_merge: { merge_commit_sha, target_branch, merged_at }` in the checkpoint. On failure due to merge conflict (non-mergeable PR), do not retry blindly: convert the conflict into a synthetic Blocking finding per "Merge-Conflict Remediation" below and re-enter the standard R1–R5 remediation loop; do not proceed to DONE. Merge confirmation (issue #952): a zero exit from `gh pr merge` does not prove a merge when the base branch uses a merge queue, so `epic_merge.merge_commit_sha` is recorded only after the merge is confirmed by polling and ancestry check. Read the pull-request state every 30 seconds, for at most 90 minutes, with the `gh api graphql` query and `.claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1` exactly as step 3 of `## Per-Item Merge to Main (Merge-on-Green)` in `.claude/skills/parallel-orchestrate/SKILL.md` defines them; on `merged`, run `git fetch origin <integration_branch>` and confirm that `git merge-base --is-ancestor <merge-commit-oid> origin/<integration_branch>` exits 0 before recording `epic_merge`. When the 90 minutes are exhausted, record a finding naming `awaiting_merge_queue` with `Remediability: awaiting_ci` in `remediation-inputs.<timestamp>.md` and follow the wait branch (`blocked_reason: "awaiting_ci"`, `next_step: "S9_ci_green"`). A `not_queued` outcome whose `mergeable` value is `CONFLICTING` follows "Merge-Conflict Remediation"; any other `not_queued` outcome enters `## Remediation Loop — CI-Failure Handling`; a `closed` outcome halts the run with a failure. `gh pr merge` is never re-issued in a loop after `not_queued`.
 
 CI-dependent acceptance criteria: when the item has acceptance criteria whose verification requires the result of CI on the PR head, the item's own orchestrator run owns their check-off, and a parent or coordinating session never commits them from its own root. After step 5 records `ci_gate.conclusion == "success"`, check off each CI-dependent criterion in the item's own worktree, commit, push to the PR branch, and re-run S9 from step 1 against the new head SHA, so that `ci_gate.head_sha` equals the final PR head before DONE. In epic mode this completes before step 6 merges. A failed re-run enters `## Remediation Loop — CI-Failure Handling` below; the shared `remediation_loop.completed_attempts` count and its halt after three completed attempts are unchanged.
 
@@ -348,7 +361,7 @@ When S9 records `step9_status: "failed_remediation_required"` (a failed check; a
 
 1. The failed-check log from `gh run view <run-id> --log-failed` is written as `remediation-inputs.<timestamp>.md` in the active feature folder.
 2. The failure is converted to a synthetic finding with severity `Blocking` that identifies the failing check by name and the failing job by URL.
-3. The existing R1-R5 remediation loop processes that finding exactly as it processes a local blocking finding. No new loop is introduced.
+3. The existing R1-R5 remediation loop processes that finding exactly as it processes a local blocking finding. No new loop is introduced. The inputs file carries `Remediation-Mode: proportionate` unless the fix requires changing a spec acceptance criterion, a public interface, or the file inventory beyond the branch diff plus tests and mirrors, in which case it carries `Remediation-Mode: design`.
 4. CI-failure cycles share `remediation_loop.completed_attempts` with local-finding cycles; a CI-failure finding stays `autonomous`, and the active cycle number is `completed_attempts + 1`.
 5. The shared guard applies: after three completed attempts without a passing result, the orchestrator records `step9_status: "blocked_ci_loop_limit"`, does not write DONE, and halts. No further automation is attempted.
 
@@ -363,7 +376,7 @@ The orchestrator must not create a PR, push a branch for PR purposes, or report
 4. The checkpoint `next_step` is `S8_create_pr` (precondition to entering S9).
 5. PR body produced via the pr-author handoff: `artifacts/pr_body_<N>.md` exists with a matching `artifacts/pr_body_<N>.receipt.json`, created with `--body-file`.
 6. `ci_gate.conclusion == "success"` AND `ci_gate.head_sha == current head SHA of the PR branch`. DONE is not written while either sub-condition is false.
-7. `epic_mode` is `false`, OR (`epic_mode` is `true` AND the integration-branch merge (`gh pr merge --merge`) has completed and `epic_merge.merge_commit_sha` is recorded in the checkpoint).
+7. `epic_mode` is `false`, OR (`epic_mode` is `true` AND the integration-branch merge (`gh pr merge --merge`) has completed and `epic_merge.merge_commit_sha` is recorded in the checkpoint). `epic_merge.merge_commit_sha` is recorded only after the merge is confirmed by polling and ancestry check (S9 step 6).
 
 This gate is non-negotiable. Each condition is independently verified before PR creation proceeds. Conditions 1-4 are unchanged from the prior contract; conditions 5-7 (receipt handoff, CI-green gate, and epic-mode merge-on-green gate) are additive.
 

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

@@ -389,12 +389,32 @@ Procedure, per item:
    `merge_status: ci_green` and do not run `gh pr merge`; the item waits until its child pushes
    the check-off and re-runs S9, and the parent does not commit the check-off itself.
 3. Execute `gh pr merge --merge <PR>` for that item's pull request, whose base is `main`.
-4. On success, record `merge_commit_sha`, `merged_at`, and `merge_status: merged`, then regenerate
+   Do not pass `--delete-branch` or `--auto`. A zero exit status does not prove a merge: when
+   `main` uses a merge queue, `gh pr merge` exits 0 after it enqueues the pull request or enables
+   auto-merge (issue #952). Confirm the merge before step 4. Every 30 seconds, for at most 90
+   minutes, read the pull-request state with
+   `gh api graphql -f query='query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){state mergedAt isInMergeQueue mergeCommit{oid} autoMergeRequest{enabledAt}}}}' -F owner='{owner}' -F name='{repo}' -F number=<PR> --jq .data.repository.pullRequest`
+   and classify it with
+   `pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1 -PrJson <snapshot-json> -AsJson`.
+   On `pending`, read again. When the 90 minutes are exhausted, report the item as
+   `awaiting_merge_queue`, leave its `merge_status` at `ci_green`, and do not record `merged`.
+   On `merged`, run `git fetch origin main` and
+   `git merge-base --is-ancestor <merge-commit-oid> origin/main`; the merge is confirmed only
+   when that command exits 0. On `not_queued`, read `gh pr view <PR> --json mergeable`: a
+   `CONFLICTING` value enters `## Per-Item Merge-Conflict Handling`, and any other value is a
+   merge-group CI failure that re-delegates the item's child to merge `origin/main` and re-run
+   S9 as one CI-failure remediation cycle, consuming a remediation attempt. On `closed`, stop
+   and report a failure for the item. Never re-issue `gh pr merge` in a loop after a
+   `not_queued` outcome.
+4. Record `merge_commit_sha`, `merged_at`, and `merge_status: merged` only after the merge is
+   confirmed by polling and ancestry check, then regenerate
    `docs/features/parallel/<slug>/parallel-status.md`.
 5. On a merge failure caused by a conflict, follow `## Per-Item Merge-Conflict Handling`.
 
 **Merge-gate authorization.** `.claude/hooks/enforce-epic-merge-gate.ps1` is a project-wide
-`PreToolUse` Bash-matcher hook that denies any `gh pr merge --merge` unless a checkpoint satisfies
+`PreToolUse` Bash-matcher hook that denies every merge or merge-queue enqueue action (any
+`gh pr merge` spelling except a pure `--disable-auto`, and every `gh api` merge or enqueue
+mutation; issue #952) unless a checkpoint satisfies
 one of its allow conditions; its block reason is `EPIC_MERGE_GATE_BLOCKED`. The gate has
 four allow conditions
 which it evaluates in this order: a per-feature checkpoint with `epic_mode == true` and
@@ -436,7 +456,9 @@ security control; see the Standalone-Merge-Authorization section of
 Branch protection on `main` affects only the pacing of step 3, not its ownership: if `main`
 requires branches to be up to date, an automated `gh pr update-branch` plus re-green cycle is
 inserted between same-cohort merges, which serializes those merges in practice while remaining
-unattended.
+unattended. When `main` uses a merge queue, the queue replaces that `gh pr update-branch` cycle:
+step 3 enqueues each green pull request, the queue validates it against the latest `main`
+together with the entries ahead of it, and step 3's confirmation polling waits for the merge.
 
 ## Per-Item Merge-Conflict Handling
 
@@ -447,7 +469,8 @@ this surface.
 Project-file conflicts are resolved by the parent first (issue #643); the numbered steps below are
 the escalation path.
 
-- (a) On a conflicted `gh pr merge --merge`, the parent runs the two commands
+- (a) On a conflicted `gh pr merge --merge`, or a `not_queued` merge confirmation whose
+  `mergeable` value is `CONFLICTING`, the parent runs the two commands
   `git -C <worktree_path> fetch origin main` and
   `git -C <worktree_path> merge --no-commit origin/main`.
 - (b) The parent then runs
@@ -467,7 +490,8 @@ the escalation path.
   item, sets `merge_status: pr_open`, regenerates `parallel-status.md`, and re-enters
   `## Per-Item Merge to Main (Merge-on-Green)` at the durable `gh pr checks` confirmation step.
 
-1. On a conflicted `gh pr merge --merge`, the parent detects the failure and re-delegates that item's
+1. On a conflicted `gh pr merge --merge`, or a `not_queued` merge confirmation whose `mergeable`
+   value is `CONFLICTING`, the parent detects the failure and re-delegates that item's
    child orchestration, passing the conflict signal and the instruction to resolve against
    `origin/main`. The conflict capture and the finding write both belong to the child's
    `atomic-executor`, which works inside the item's own worktree, the only working tree holding the

package/resources/claude-customizations/.claude/skills/powershell-change-budget-router/SKILL.md

@@ -28,7 +28,7 @@ When routed through `/orchestrate`, small path still requires lifecycle scaffold
 - promote potential item to GitHub issue with `--work-mode minor-audit`,
 - create active feature folder with `--work-mode minor-audit`,
 - delegate minimal-audit plan creation to `atomic_planner` with `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`,
-- require `atomic_executor` preflight until `PREFLIGHT: ALL CLEAR`,
+- require single-pass `atomic_executor` preflight ending in `PREFLIGHT: ALL CLEAR` (at most one return to the planner),
 - execute Phase 0 only via `atomic_executor` before branching,
 - run reduced small-audit after implementation and QC.
 

package/resources/claude-customizations/.claude/skills/python-change-budget-router/SKILL.md

@@ -40,7 +40,7 @@ When routed through `/orchestrate`, the small path still requires lifecycle scaf
 - promote the potential item to a GitHub issue with `--work-mode minor-audit`,
 - create the active feature folder with `--work-mode minor-audit`,
 - delegate minimal-audit plan creation to `atomic_planner` with `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`,
-- require `atomic_executor` preflight until `PREFLIGHT: ALL CLEAR`,
+- require single-pass `atomic_executor` preflight ending in `PREFLIGHT: ALL CLEAR` (at most one return to the planner),
 - execute Phase 0 only via `atomic_executor` before branching,
 - run the reduced small-audit after implementation and QC.
 

package/resources/claude-customizations/.claude/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -5,7 +5,7 @@ description: 'Remediation handoff chain from orchestrator through atomic-planner
 
 # Remediation Handoff to atomic-planner
 
-Strict handoff chain for orchestrator-initiated remediation cycles. The chain enforces that an `atomic-planner`-authored plan is preflighted by `atomic-executor`, revised through a preflight sub-loop if needed, executed by `atomic-executor` task-by-task, and reaudited by `feature-review`. Workers are never invoked directly by the orchestrator.
+Strict handoff chain for orchestrator-initiated remediation cycles. The chain enforces that an `atomic-planner`-authored plan is preflighted by `atomic-executor`, revised at most once through the preflight sub-loop if needed, executed by `atomic-executor` task-by-task, and reaudited by `feature-review`. Workers are never invoked directly by the orchestrator.
 
 ## When to Use This Skill
 
@@ -30,7 +30,7 @@ orchestrator
              PREFLIGHT: ALL CLEAR        -> proceed to execution
              PREFLIGHT: REVISIONS REQUIRED -> route back to atomic-planner
                 with a precise plan delta; planner revises in place and
-                orchestrator re-runs preflight (sub-loop until clear)
+                orchestrator re-runs preflight once (at most one return)
      -> atomic-executor executes the cleared plan task-by-task
         (workers are invoked by atomic-executor only)
      -> orchestrator delegates to feature-review
@@ -63,6 +63,11 @@ The orchestrator authors `remediation/<entry-ts>/remediation-inputs.md` with:
 - Enumerated fix list with file paths, expected behavior, and verification commands.
 - A "do not do" list (no scope creep, no policy weakening, no silent skips).
 - A pointer to the audit artifacts that produced the findings.
+- Exactly one mode line, `Remediation-Mode: proportionate` or `Remediation-Mode: design`. The cycle is proportionate when every `autonomous` finding can be fixed without changing a spec acceptance criterion, a public interface, or the item's file inventory beyond the files already in the branch diff plus their tests and mirrors; otherwise it is design. CI-failure findings are normally proportionate.
+
+Proportionate cycle. One `atomic-planner` delegation writes a short plan; one `atomic-executor` delegation then runs single-pass preflight with in-place trivial fixes and executes the plan in the same run. The orchestrator records `preflight: {iterations: 1, final_status: "clear"}` on the cycle before `execution_status`. When that preflight finds a substantive defect, the executor stops with `BLOCKED at preflight (before [P0-T1])`, a plan delta, and no checked task, and the orchestrator converts the cycle to design mode by rewriting the mode line to `Remediation-Mode: design` before one planner revision.
+
+Design cycle. The full chain above runs with the preflight sub-loop below, bounded by the at-most-one-return rule.
 
 ## Required Artifacts
 
@@ -96,25 +101,28 @@ A comprehensive or final sweep in a remediation cycle covers that cycle's own pl
 - Phase 0 captures policy reads and baseline toolchain results per `policy-compliance-order` and `evidence-and-timestamp-conventions`.
 - Final phase runs the full toolchain QA loop in the order specified by `atomic-plan-contract` and records numeric coverage values where the repository policy requires coverage.
 - Evidence paths resolve to `<FEATURE>/evidence/<kind>/` per the non-overridable evidence path clause.
+- The plan is design-level per `## Design-Level Plan Contract (Mandatory)` in `atomic-plan-contract`, carries a `## Pre-Mortem` section, and ends with the final-phase self-review task. A proportionate plan covers only the listed findings and stays short.
 
 The plan must pass the `mcp__drm-copilot__validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>` before `atomic-executor` runs preflight against it.
 
 ## Preflight Sub-Loop
 
-After the plan is authored, `atomic-executor` runs preflight under the directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`. The exact signal returned is either:
+After the plan is authored, `atomic-executor` runs preflight under the directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`, which the orchestrator places in the delegation prompt and never in the plan file. Preflight is single-pass: trivial defects are fixed in place and recorded as `PREFLIGHT-FIX:` lines with a `preflight-fix-record:` path. The exact signal returned is either:
 
 - `PREFLIGHT: ALL CLEAR` — the plan proceeds to execution.
-- `PREFLIGHT: REVISIONS REQUIRED` — `atomic-executor` returns a precise plan delta. The orchestrator routes the delta to `atomic-planner` for revision. `atomic-planner` updates the same plan file in place (per the plan-path continuity contract in `atomic-plan-contract`). The orchestrator then re-runs preflight. The sub-loop repeats until `PREFLIGHT: ALL CLEAR` is returned.
+- `PREFLIGHT: REVISIONS REQUIRED` — `atomic-executor` returns a precise plan delta with one `PREFLIGHT-DEFECT:` line per substantive defect. The orchestrator routes the full defect list to `atomic-planner` for one revision. `atomic-planner` updates the same plan file in place (per the plan-path continuity contract in `atomic-plan-contract`). The orchestrator then re-runs preflight once.
+
+At most one return. The sub-loop returns to `atomic-planner` at most once per cycle: when the second preflight still reports a substantive defect, the iteration ceiling below applies.
 
 The orchestrator records the preflight outcome in `remediation_loop.cycles[current_cycle].preflight` with `iterations` (counter) and `final_status` (`clear|changes_requested|pending`).
 
 For a well-scoped item where `preflight.iterations > 1`, record a process-defect investigation that identifies the incomplete planner internal-review dimension. Treat excess rounds as a process signal, not routine iteration.
 
-The exhaustive-pass, defect-enumeration, and delta-self-check rules that govern how `atomic-executor` conducts preflight are defined in the `## Preflight Validation (Planner ↔ Executor)` section of `.claude/skills/atomic-plan-contract/SKILL.md` and are not restated here.
+The exhaustive-pass, defect-classification, in-place-fix, and fix-self-check rules that govern how `atomic-executor` conducts preflight are defined in the `## Preflight Validation (Planner ↔ Executor)` section of `.claude/skills/atomic-plan-contract/SKILL.md` and are not restated here.
 
 Alongside `iterations` and `final_status`, the orchestrator also records in `remediation_loop.cycles[current_cycle].preflight` the convergence line `atomic-executor` returned on that round, which is one of `CONVERGENCE: NO FURTHER ROUNDS EXPECTED` or `CONVERGENCE: FURTHER ROUNDS LIKELY`. This convergence field extends the field set already recorded at `remediation_loop.cycles[current_cycle].preflight` rather than replacing it: `iterations` and `final_status` continue to be recorded exactly as stated above, and the convergence field is written in addition to them.
 
-Iteration ceiling. When a cycle's `iterations` would exceed 2, the orchestrator records `final_status: "blocked_preflight_iteration_limit"`, halts the preflight sub-loop, and escalates to the caller, rather than continuing the sub-loop indefinitely. `blocked_preflight_iteration_limit` is a fourth `final_status` value extending the `clear|changes_requested|pending` enumeration stated above. This ceiling bounds the repeat-until-clear behavior stated above it: the sub-loop still repeats until `PREFLIGHT: ALL CLEAR` is returned, and the ceiling supplies the terminating condition for the case where that signal is not reached within two iterations.
+Iteration ceiling. When a cycle's `iterations` would exceed 2, the orchestrator records `final_status: "blocked_preflight_iteration_limit"`, halts the preflight sub-loop, and escalates to the caller. `blocked_preflight_iteration_limit` is a fourth `final_status` value extending the `clear|changes_requested|pending` enumeration stated above. Under the at-most-one-return rule the ceiling is reached after one planner revision: the first preflight and the confirming preflight are the two permitted iterations.
 
 ## Execution and Reaudit
 

package/resources/claude-customizations/.claude/skills/research-issue/SKILL.md

@@ -63,6 +63,12 @@ Create or update a single research file at one of the two tracked research roots
 - Propose a test strategy consistent with repository policy (unit tests for pure logic, integration seams).
 - Do not write test code; describe the strategy only.
 
+### 6. Pre-Mortem
+
+- Feature-associated research (a research path under `docs/features/`) MUST carry a `## Pre-Mortem` section with one bullet beginning with each of the seven labels `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`. Each bullet states how the next review or CI run could fail on that dimension and the mitigation the plan must carry; a label that does not apply is written as "not applicable" followed by the reason.
+- One-off research under `docs/research/` is exempt.
+- The researcher SubagentStop hook blocks feature research without a complete section. The `execution-environment` skill states the CI shape, contract tests, and isolation checks the section accounts for.
+
 ## Constraints
 
 - Research only. Do not implement changes.

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

@@ -30,6 +30,7 @@
     ".claude/hooks/enforce-epic-merge-gate.ps1",
     ".claude/hooks/enforce-epic-merge-gate-authorization.ps1",
     ".claude/hooks/enforce-epic-merge-gate-resolution.ps1",
+    ".claude/hooks/enforce-epic-merge-gate-command.ps1",
     ".claude/hooks/enforce-epic-wave-barrier.ps1",
     ".claude/hooks/enforce-epic-worktree-removal-gate.ps1",
     ".claude/hooks/enforce-epic-worktree-removal-gate-resolution.ps1",
@@ -67,6 +68,7 @@
     ".claude/hooks/hook-dependency-guard.ps1",
     ".claude/hooks/hook-docs-only-diff.ps1",
     ".claude/hooks/persist-session-id.ps1",
+    ".claude/hooks/premortem-section.ps1",
     ".claude/hooks/subagentstop-envelope.ps1",
     ".claude/hooks/validate-bash.ps1",
     ".claude/hooks/validate-discovery-artifact-gate.ps1",
@@ -117,6 +119,7 @@
     ".claude/skills/epic-run/SKILL.md",
     ".claude/skills/evidence-and-timestamp-conventions/SKILL.md",
     ".claude/skills/execute-hard-lock/SKILL.md",
+    ".claude/skills/execution-environment/SKILL.md",
     ".claude/skills/feature-promotion-lifecycle/SKILL.md",
     ".claude/skills/feature-review-workflow/SKILL.md",
     ".claude/skills/fill-feature-docs/SKILL.md",
@@ -181,6 +184,7 @@
     ".claude/lib/project-file-merge/ProjectFileMerge.psm1",
     ".claude/lib/project-file-merge/Resolve-MergeableConflict.ps1",
     ".claude/lib/ci-gate/Invoke-CiGateParser.ps1",
+    ".claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1",
     ".claude/lib/parallel-drift/ParallelDriftHalt.psm1",
     ".claude/lib/parallel-drift/ParallelDrift.psm1",
     ".claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1",

package/resources/codex-and-agents-customizations/.agents/skills/README.md

@@ -9,6 +9,7 @@ Repository-local Codex skills live under `.agents/skills/<skill-name>/SKILL.md`.
   - `atomic-plan-contract`
   - `acceptance-criteria-tracking`
   - `evidence-and-timestamp-conventions`
+  - `execution-environment`
   - `skill-canonical-location-audit`
 
 - Integration

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

@@ -13,6 +13,7 @@ Always apply:
 - `policy-compliance-order`
 - `atomic-plan-contract`
 - `acceptance-criteria-tracking`
+- `execution-environment`
 
 ## Role
 
@@ -33,17 +34,17 @@ Blocking is allowed only during preflight.
 
 ### Validation-Only Mode Contract
 
-If the incoming handoff includes the exact directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`:
+If the incoming handoff includes the exact directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY` (the directive belongs in the delegation prompt, never in a plan file):
 
-1. Perform preflight validation only.
+1. Perform preflight validation only, in one pass over the entire plan, under `### Single-Pass Preflight` in `atomic-plan-contract`.
 2. Do not execute tasks, establish execution state, or run implementation commands.
-3. Return exactly one of:
+3. 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`, and report it as a `PREFLIGHT-FIX:` line with a `preflight-fix-record:` path.
+4. Return exactly one of:
    - `PREFLIGHT: ALL CLEAR`
    - `PREFLIGHT: REVISIONS REQUIRED`
-4. If revisions are required, include a precise plan delta that `atomic-planner` can apply to the same plan file.
-5. If revisions are required, automatically hand off back to `atomic-planner` and request that it apply the delta to the same plan file and resubmit that file for validation-only again.
-6. Continue the validate -> delta -> planner-revise -> validate loop until preflight can return `PREFLIGHT: ALL CLEAR`.
-7. If the planner-return handoff cannot be started or completed, stop and report blocked state; do not convert the failure into `PREFLIGHT: ALL CLEAR`.
+5. If revisions are required, include a precise plan delta that `atomic-planner` can apply to the same plan file, with one `PREFLIGHT-DEFECT:` line per substantive defect and every substantive defect listed.
+6. Return the result to the caller. A plan returns to the planner at most once; the orchestrator routes the defect list for one revision and runs one confirming preflight.
+7. If the required handoff cannot be started or completed, stop and report blocked state; do not convert the failure into `PREFLIGHT: ALL CLEAR`.
 
 ## Execution Rules
 

package/resources/codex-and-agents-customizations/.agents/skills/atomic-plan-contract/SKILL.md

@@ -21,6 +21,22 @@ Use this skill when:
 - Task IDs must match their phase and be sequential per phase.
 - Plans must pass the `mcp__drm-copilot__validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>` before they can be reported as approved.
 
+## Design-Level Plan Contract (Mandatory)
+
+A plan is a design-level document: it states what changes and how the change is proven, not a transcript of commands. Every task names the files it creates or edits, the symbols, headings, or tests it touches, the behavior the change produces, the tests that prove that behavior, and an acceptance condition stated as an observable outcome.
+
+Rules:
+
+- **Anchors are symbols, headings, or test names.** A plan never cites a line number, a `path:line` locator, a `#L` anchor, or a commit SHA, because each goes stale when `main` moves (validator rules G11 and G12). Scope comparisons name the merge-base derivation of `origin/main` and `HEAD`, not a commit.
+- **Literals only where they are the asserted value.** A plan quotes a literal when an acceptance condition asserts that exact value. It does not quote file contents, command output, or prose for context.
+- **Tool routes are not restated.** Tool routes, launchers, wrapper scripts, command-text restrictions, the batch budget, hook context, and CI shape are owned by the `execution-environment` skill. A plan references that skill instead of restating its content.
+- **Changed existing behavior names its asserting tests.** A task that changes the observable behavior of an existing function, script, fixture, or test stub (its signature, argv, output, exit status, or the files it writes) names every existing test that asserts that behavior and states each test's disposition: unchanged because it is unaffected, or updated, with the reason for the update. The tests are found by searching the test tree for the symbol, the file name, and the asserted output. A test that asserts the current behavior and is outside the task's file set fails once the change lands, and the plan's own acceptance condition then cannot be met. The planner's adversarial self-review includes this search for every task that changes existing behavior.
+- **Size guideline.** A plan stays within 40 canonical tasks and 400 physical lines. A plan that needs more carries a `## Size Justification` section with at least one line stating why the size is necessary (validator rule G13). Files produced by one generator run count as one generator task.
+- **Pre-Mortem.** Every plan carries a `## Pre-Mortem` section with one bullet beginning with each of the seven labels `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`. Each bullet states how the plan prevents that failure class, or states "not applicable" followed by the reason. The `Test isolation` bullet names the isolation runs the plan performs: a seeded shuffled Jest run with the seed recorded, a reversed-order run of the new or changed Python test modules, and a seeded shuffled file-order run of the touched Pester suites with at least three seeds, each seed recorded. The `Mirror parity` bullet also covers the execution-environment brief: a plan that alters a fact the brief states (for example, it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) includes a task that updates the brief in the same change, in all six byte-identical copies, and the bullet names that task. Without that task the brief states a superseded fact once the change lands, which breaks the brief's own maintenance rule. The planner SubagentStop hook blocks a plan without a complete section.
+- **Final-phase self-review.** The final phase of every plan contains a self-review task that walks the policy-audit, code-review, and feature-audit templates under `docs/features/templates/policy_audit/` against the branch diff from the merge base and writes `<FEATURE>/evidence/qa-gates/self-review.<timestamp>.md` with one PASS, FAIL, or N/A row per checklist item. A FAIL row is fixed and the QA loop is re-run before the self-review is rewritten; the plan does not complete with a FAIL row.
+
+This section takes precedence over the literal-quoting rules of `## Wrap-Tolerant Assertion Authoring (Mandatory)`: those rules govern the asserted value of an acceptance condition, not context.
+
 ## Short-Path Minimal Plan Contract
 
 When orchestration selects short path, a minimal plan is still mandatory and must include these blocks:
@@ -159,13 +175,30 @@ Any regression test task expected to fail must be tagged with `[expect-fail]` an
 ## Preflight Validation (Planner ↔ Executor)
 
 When validating or handing off plans for execution:
-- Use the directive line: `DIRECTIVE: PREFLIGHT VALIDATION ONLY`.
+- Put the directive line `DIRECTIVE: PREFLIGHT VALIDATION ONLY` in the delegation prompt. The preflight directive belongs in the delegation prompt, never in a plan file.
 - Require one of the exact signals:
 	- `PREFLIGHT: ALL CLEAR`
 	- `PREFLIGHT: REVISIONS REQUIRED`
-- If revisions are required, provide a precise plan delta and repeat validation until all clear.
+- If revisions are required, provide a precise plan delta with one `PREFLIGHT-DEFECT:` line per substantive defect. A plan returns to the planner at most once.
 - If the required planner ↔ executor handoff cannot be started or completed, stop and report blocked state; do not self-approve the plan.
 
+### Single-Pass Preflight
+
+- **Review the entire plan in one pass.** The preflight executor checks every phase, task, and prose region and does not stop at the first defect.
+- **Classify every defect as trivial or substantive.** Trivial defects are a stale or misspelled anchor, symbol, heading, or path whose intent is unambiguous; a citation correction, including removal of a G11 line-number or G12 commit-SHA citation; a typo; a literal-formatting defect that does not change what is asserted; and an evidence filename spelling. Substantive defects are a missing or extra task; a wrong file set or design; an acceptance criterion with no implementing task; an acceptance condition whose correction changes what is asserted; a task-ordering error; and a scope-boundary violation.
+- **Fix trivial defects in place, in task text only.** The preflight executor edits task text and plan preamble in the same plan file and never adds, removes, or reorders tasks. Each fix is recorded in `<FEATURE>/evidence/other/preflight-fixes.<timestamp>.md`.
+- **Return substantive defects only, all of them.** `PREFLIGHT: REVISIONS REQUIRED` is returned only when at least one substantive defect remains, and it lists every one. `PREFLIGHT: ALL CLEAR` may follow in-place fixes.
+
+Output format. After the `PREFLIGHT:` signal, the return carries one line per defect:
+
+- `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>`
+- `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>`
+- `preflight-fix-record: <path>` when at least one fix was made.
+
+`PREFLIGHT: ALL CLEAR` carries no `PREFLIGHT-DEFECT:` line, and `PREFLIGHT: REVISIONS REQUIRED` carries at least one.
+
+At most one return. On `PREFLIGHT: REVISIONS REQUIRED`, the orchestrator delegates one planner revision carrying the full `PREFLIGHT-DEFECT:` list and runs one more preflight. If that preflight still reports a substantive defect, the orchestrator halts with `blocked_reason: "validator_failed"` during planning, or records `final_status: "blocked_preflight_iteration_limit"` in a remediation cycle.
+
 ## Validator Gate (Mandatory)
 
 Before a plan can be treated as approved:
@@ -174,15 +207,17 @@ Before a plan can be treated as approved:
 - reject the plan if that validator exits non-zero,
 - do not treat human-readable summaries as a substitute for validator success.
 
+The validator applies the acceptance-gate rules of `.claude/rules/plan-acceptance-gates.md`. G1 through G9 judge the commands a plan states as acceptance conditions; G10 reports a SCRATCH definition not namespaced by issue number; and the document-level rules G11, G12, and G13 report a line-number citation, a commit-SHA citation, and a plan above 40 tasks or 400 lines without a non-empty `## Size Justification` section. The complete shipped set is therefore G1 through G13. The installed MCP validator applies G11 through G13 only after the extension release that carries them is installed; until then, validate a plan with the repository's Python CLI `scripts/dev_tools/validate_orchestration_artifacts.py` and its `plan` subcommand, as the `execution-environment` skill states.
+
 ## Plan-Path Continuity Contract (Mandatory)
 
 When a caller provides an explicit target plan file path (for example `${plan-path}` or `${file}`):
 
 - Planner MUST update that exact file in place.
-- Planner MUST reuse the same file for all preflight revision iterations.
+- Planner MUST reuse the same file for the single permitted preflight revision.
 - Planner MUST NOT create additional timestamped sibling files (for example `plan.<timestamp>.md`) during the same planning cycle.
 
-If the provided path does not exist, it may be created once, then reused for all subsequent revisions in that cycle.
+If the provided path does not exist, it may be created once, then reused for the single permitted revision in that cycle.
 
 ## Mode source precedence (Mandatory)