@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/claude-customizations/.claude/skills/feature-review-workflow/SKILL.md

@@ -70,7 +70,7 @@ Always apply:
 If the branch diff modifies any path matching `.github/workflows/**`, `scripts/benchmarks/**`, or `.github/actions/**`, the policy audit emits a Blocking finding unless evidence of a green workflow run against the branch head is present in the remediation inputs.
 
 - The rule provides a second, independent line of defense for CI-gate-modifying features, separate from and prior to the orchestrator's S9 CI green gate.
-- "Green workflow run against the branch head" means a workflow run whose head SHA matches the current branch head and whose conclusion is success for the affected workflow.
+- "Green workflow run against the branch head" means a run of the affected workflow whose conclusion is success and which satisfies either (a) or (b): (a) its head SHA equals the current branch head; or (b) all three predecessor-head conditions hold: (1) the run's head SHA is an ancestor of, or equal to, the current branch head and contains the latest commit that changes any path outside the active feature folder (`git merge-base --is-ancestor <commit> <run-sha>`); (2) every commit after the run's head SHA changes only paths inside the active feature folder (`git log <run-sha>..HEAD -- . ":!<feature-folder>"` returns no commits); (3) the policy audit states that the orchestrator's S9 CI green gate remains responsible for `ci_gate.conclusion == "success"` with `ci_gate.head_sha` equal to the final PR head before DONE. Condition (b) exists because an in-repo evidence artifact cannot name the SHA of the commit that contains it.
 - A green `workflow_dispatch` run against the branch head also satisfies the rule, not only a PR-context run. This mitigates the chicken-and-egg case where a feature must land its CI gate before the gate can run in PR context (see spec.md Risks & Mitigations).
 - When the rule fires and no qualifying green-run evidence is present, record a Blocking finding classified `awaiting_ci` (the remediation inputs carry `Remediability: awaiting_ci` and a `Remediability-Evidence:` line naming the awaited workflow) and route it to the wait path (`AWAITING_CI` when no other class is present) instead of the remediation handoff.
 
@@ -108,12 +108,13 @@ If the branch diff modifies any path matching `.github/workflows/**`, `scripts/b
         - Python: `poetry run pytest --cov` → artifact: `artifacts/python/lcov.info`
         - PowerShell: `mcp__drm-copilot__run_poshqc_test` → artifact: `artifacts/pester/powershell-coverage.xml`
         - C#: `dotnet test --collect:"XPlat Code Coverage"` → artifact: `artifacts/csharp/coverage.xml`
-        - Coverage thresholds (uniform tier rule per quality-tiers.md). The branch threshold applies only to branch-capable languages — TypeScript, Python, and C#. PowerShell is a coverage language and is fully subject to the line threshold and the no-regression requirement, but Pester measures command (instruction) coverage and line coverage only, so no branch percentage exists to evaluate and no branch threshold applies to it (see `.claude/rules/powershell.md`). Do not flag a missing PowerShell branch figure as FAIL:
+        - Coverage thresholds (threshold precedence per `.claude/rules/quality-tiers.md` and `.claude/rules/general-unit-test.md`: when the repository's root `CLAUDE.md` states line or branch coverage thresholds, those thresholds govern; otherwise the default thresholds below govern; each metric falls back independently, so a root `CLAUDE.md` that states only one of the two thresholds governs only that metric). The branch threshold applies only to branch-capable languages — TypeScript, Python, and C#. PowerShell is a coverage language and is fully subject to the line threshold and the no-regression requirement, but Pester measures command (instruction) coverage and line coverage only, so no branch percentage exists to evaluate and no branch threshold applies to it (see `.claude/rules/powershell.md`). Do not flag a missing PowerShell branch figure as FAIL:
           - New code files (added in this feature): line coverage >= 85%, and branch coverage >= 75% for branch-capable languages. Flag as FAIL otherwise.
           - Modified files (changed but previously existing): line coverage >= 85%, branch coverage >= 75% for branch-capable languages, and no regression on changed lines relative to baseline. Flag as FAIL otherwise.
           - Repo-wide per language: line coverage >= 85%, and branch coverage >= 75% for branch-capable languages. Flag as FAIL otherwise.
         - If coverage artifacts already exist from the executor run, inspect them instead of re-running.
         - If no coverage artifact exists for a language that has changed files, flag as FAIL — coverage verification is mandatory for all languages with changed files.
+        - Tier classification findings: report a missing or incomplete `quality-tiers.yml` only when the repository has adopted tiers, that is, when `quality-tiers.yml` exists at the repository root on the resolved base branch or the repository's CI runs a tier-classification check. Otherwise record tier classification as not applicable; it is not a finding.
    - Run the smallest relevant subset first when the repo policy permits it.
    - If a tool cannot run in the environment, mark the affected section unverified or partial with a concrete reason.
 
@@ -145,7 +146,7 @@ If the branch diff modifies any path matching `.github/workflows/**`, `scripts/b
      - toolchain checks fail
      - the code review contains blockers
      - required acceptance criteria are FAIL or PARTIAL
-     - coverage regression below policy threshold (< 80% repo-wide per language, < 80% or regression for modified files, or < 90% for new files)
+     - coverage below the governing thresholds defined in step 5 (repo-wide per language, modified files including any regression on changed lines, or new files)
      - coverage artifact absent for any language that has changed files
    - Classify each blocking finding before triggering remediation: each receives one remediability class (`autonomous`, `external_dependency`, `policy_hold`, `awaiting_ci`, or `human_decision_required`; `autonomous` when no class is stated). A published MCP runtime that lags the repository contract is classified `external_dependency`.
    - Trigger the remediation handoff only when at least one blocking finding is `autonomous`. When every blocking finding is non-remediable, write the remediation inputs with the `HALT_NON_REMEDIABLE` or `AWAITING_CI` verdict and create no remediation plan target.

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
 
@@ -34,6 +35,7 @@ On every invocation, the main session must:
 2. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`.
 3. If no checkpoint exists or the objective is new, begin the orchestration lifecycle from the start.
 4. **Checkpoint hygiene (issue #673).** When the checkpoint at `artifacts/orchestration/orchestrator-state.json` records an `issue-num` other than the item this invocation is about, move it to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json` before writing a new checkpoint, rather than overwriting it or leaving it in place. Apply the same move when this session hands an item whose checkpoint it holds to another session or worktree. A checkpoint left at a session root is read by gates that resolve against that root, so a foreign one there is state a gate can answer from.
+5. **Required checkpoint keys (issue #798).** Every checkpoint write carries each top-level key listed in `.claude/rules/orchestrator-state.md` under `## Required Top-Level Keys`; plain validation reports each absent key as `Checkpoint missing required key: <key>` under every flag combination. The list includes `last_updated`, an ISO-8601 UTC date-time string (for example `2026-10-08T17:28:00Z`) that is rewritten on every checkpoint write: after every completed step and every state transition, including halts.
 
 ## Prepared-State Portable Handoff Intake
 
@@ -130,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.
@@ -189,6 +197,8 @@ The mandatory sequence is:
 3. The orchestrator then delegates PR creation and any PR body edits to `Agent(pr-author)`. The `pr-author` agent runs the `pr-author` skill to author the body, writes the body file `artifacts/pr_body_<N>.md` and the sibling receipt `artifacts/pr_body_<N>.receipt.json` with the shape `{skill, pr_body_path, number, sha256 (lowercase hex of the body bytes), context_summary_path, created_at (ISO-8601 UTC, strictly newer than `artifacts/pr_context.summary.txt` last-write)}`, issues `gh pr create --body-file artifacts/pr_body_<N>.md` (or `gh pr edit --body-file ...`), and reports the resulting PR URL or PR number.
 4. The orchestrator records `pr_author_receipt` in the checkpoint, citing the body-file path and the receipt path that were verified.
 
+When the pr-author agent runs outside the item worktree (its process directory is not the worktree that holds the item's `artifacts/` tree), it passes the absolute canonical path `<item worktree>/artifacts/pr_body_<N>.md` to `--body-file`. The `enforce-pr-author-skill.ps1` hook resolves the item worktree from `--head` and reads the PR context summary, the body, and the receipt beneath it; in that topology it denies a relative `--body-file` with `PR_BODY_PATH_NONCANONICAL`, because `gh` would read the relative path from its own process directory.
+
 `Agent(pr-author)` is the mandatory delegate for PR creation and PR body edits. Direct `gh pr create`/`gh pr edit --body*` from the main thread is prohibited and is blocked by the hook. Before the five receipt checks, the `enforce-pr-author-skill.ps1` PreToolUse hook independently re-validates the orchestrator-state checkpoint against `--require-pr-creation-ready` (via an injectable `$Invoker` subprocess seam) and blocks with `ORCHESTRATOR_STATE_PREFLIGHT_FAILED` when the checkpoint is missing or invalid — this is the local, hook-level enforcement mechanism that closes the bypass path (it runs inside the same hook that already intercepts `gh pr create`/`gh pr edit`, not as a CI check). The PreToolUse hook then verifies the receipt in five ordered checks: canonical body-file path, receipt present, `number` match, `sha256` match against the body bytes, and `created_at` strictly newer than the context summary last-write.
 
 The SHA-256 receipt is a policy-level integrity check, not a cryptographic or security boundary; any actor with `Write(/artifacts/**)` access can replace both the body file and its receipt together with a matching SHA-256. It binds the body bytes to the receipt, prevents accidental bypass, and requires a deliberate, documented act to circumvent.
@@ -225,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.
 
@@ -256,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.
@@ -267,7 +283,7 @@ Cycle accounting: a remediation attempt is complete when R3 execution finished (
 
 ## Issue Number Consistency
 
-The canonical issue number is derived once from the active feature folder name: extract the trailing integer from the folder base name (e.g., `2026-04-26-push-down-claude-customizations-162` yields `162`). Record as `issue_num` in the checkpoint.
+The canonical issue number is derived once from the active feature folder name: extract the trailing integer from the folder base name (e.g., `2026-04-26-push-down-claude-customizations-162` yields `162`). Record as `issue-num` in the checkpoint; the hyphenated key is the one listed in `.claude/rules/orchestrator-state.md` under `## Required Top-Level Keys`.
 
 Every delegation prompt to a receipt-gated subagent type — `atomic-planner`, `atomic-executor`, `feature-review`, `task-researcher`, `prd-feature`, and `pr-author` — must include the line:
 
@@ -286,11 +302,16 @@ If a subagent artifact references a different issue number, the orchestrator rej
 S9 procedure:
 
 1. Resolve the live PR head SHA for the feature branch (`gh pr view --json headRefOid` or equivalent).
-2. Invoke `gh pr checks --required --json bucket,name,state,link,workflow` (or an equivalent JSON-emitting command) against that head SHA. `gh` is the only sanctioned channel for querying GitHub Actions state.
-3. Parse the JSON by running `pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1 -ChecksJson <checks-json> -HeadSha <head-sha>`, which emits the `ci_gate` object defined below and derives `ci_gate.conclusion` as `success` when all required checks pass, `failure` when any required check failed, and `pending` when any required check is still in progress.
+2. Invoke `gh pr checks --json bucket,name,state,link,workflow` (or an equivalent JSON-emitting command) against that head SHA. The query covers every check on the head SHA for every PR, whether or not branch protection marks the check as required. `gh` is the only sanctioned channel for querying GitHub Actions state.
+
+   No-checks rule: when `gh pr checks` fails with a `no checks reported` error, that error is never treated as green for any PR. On a non-epic PR the gate stays `pending` and step 4 continues the bounded poll. On an epic child, step 3 runs the parser with `-ChecksJson '[]'` and `-RequireWorkflow CI`, which returns `pending`. The parser is never run with `-ChecksJson '[]'` without `-RequireWorkflow CI`, because its default path returns `success` for an empty set.
+
+   Epic-child rule: when the PR base branch is an `epic/<slug>-integration` branch (checkpoint `epic_mode` is `true`), the step 2 query is the same unfiltered query; integration branches carry no required-status-check protection. An empty check list is not accepted as green for such a PR: the gate must observe at least one check whose `workflow` is `CI` against the child head SHA, and every observed `CI` check must succeed before `ci_gate.conclusion` is accepted as `success`. Every check returned by the unfiltered query counts: a failing or cancelled non-`CI` check fails the gate, and a pending one keeps it pending. Step 3 enforces this rule by passing `-RequireWorkflow CI` to the parser, which never returns `success` until at least one passing `CI` check is observed. When `gh pr checks` fails with a `no checks reported` error on the child branch, step 3 runs the parser with `-ChecksJson '[]'`; that error is never treated as green, and the parser returns `pending` for it.
+
+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.
 
@@ -301,7 +322,7 @@ DONE is not written while `step9_status` is anything other than `passed`.
 The orchestrator checkpoint (`artifacts/orchestration/orchestrator-state.json`) is extended with:
 
 - a top-level `ci_gate` object containing:
-  - `head_sha` — the PR head SHA that the required checks were observed against.
+  - `head_sha` — the PR head SHA that the queried checks were observed against.
   - `pr_pipeline_run_id` — the GitHub Actions run id for the PR Pipeline.
   - `pr_pipeline_run_url` — the URL of that run.
   - `conclusion` — one of `success`, `failure`, `pending`.
@@ -336,11 +357,11 @@ A checkpoint that predates this schema and has no `ci_gate` object (or no `step9
 
 ## Remediation Loop — CI-Failure Handling
 
-When S9 records `step9_status: "failed_remediation_required"` (a failed required check; a poll timeout follows the wait branch per S9 step 4):
+When S9 records `step9_status: "failed_remediation_required"` (a failed check; a poll timeout follows the wait branch per S9 step 4):
 
 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.
 
@@ -355,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.
 
@@ -438,6 +459,6 @@ Example:
 
 The validator counts an MCP receipt as successful only when `tool` is a non-empty string, `ok` is exactly `true`, and `evidence` is a non-empty string. Every `required_mcp_tools` entry must have such a receipt unless a valid `issue_adoption` record waives it.
 
-When the GitHub issue already exists before orchestration starts (transferred, filed by hand, or created by epic decomposition) and has been verified read-only (`gh issue view`, a `gh api` GET, or a GitHub MCP issue read), do not call `potential_to_issue`. Record a top-level `issue_adoption` object in the checkpoint instead of a `potential_to_issue` receipt. It may waive only `potential_to_issue` and, with a valid `potential_record` under `docs/features/potential/`, the checkpoint's promotion-entry tool (`new_potential_entry`, or `new_potential_bug_entry` for a bug-type checkpoint); `potential_to_issue` must always be listed. Every other required tool still needs a successful receipt. Any adoption error waives nothing. The field rules, the closed waivable set, and the error placement are defined in `.claude/rules/orchestrator-state.md` under `## Invariants (issue_adoption object)`.
+When the GitHub issue already exists before orchestration starts (transferred, filed by hand, or created by epic decomposition) and has been verified read-only (`gh issue view`, a `gh api` GET, or a GitHub MCP issue read), do not call `potential_to_issue`. Record a top-level `issue_adoption` object in the checkpoint instead of a `potential_to_issue` receipt. It may waive only `potential_to_issue` and the checkpoint's promotion-entry tool (`new_potential_entry`, or `new_potential_bug_entry` for a bug-type checkpoint); `potential_to_issue` must always be listed. For a promotion-entry waiver, `potential_record` (a markdown path under `docs/features/potential/`) is required when `origin` is `epic_decomposition`, optional when `origin` is `transferred` or `filed_before_orchestration`, and validated whenever it is present. Every other required tool still needs a successful receipt. Any adoption error waives nothing. The field rules, the closed waivable set, and the error placement are defined in `.claude/rules/orchestrator-state.md` under `## Invariants (issue_adoption object)`.
 
 These three receipt arrays, populated with the retained required names of the selected route, are what allow the routing-contract validation under `require_complete: true` to pass.

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

@@ -56,7 +56,21 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    contract for parallel admission. Preparation yields the item's DECLARED blast radius, and only
    the planner-computed declared radius is authoritative for scheduling. The item's lifecycle
    advances `proposed` -> `admitted` -> `prepared` during this step, recorded as item-state updates in
-   `items[]` with the checkpoint's lifecycle timestamps.
+   `items[]` with the checkpoint's lifecycle timestamps. After the admitted item's preflight
+   clearance, perform the `parallel-plan` skill's `## Complexity Assessment` procedure for it, and
+   record the resulting `complexity_band` on the admitted orchestrator-checkpoint item so step 3's
+   edge derivation and the parent's model routing read the same band.
+   The admitted item records `complexity_band` and no `model_routing_receipt`; the parent resolves
+   the item's model from that band at spawn time per `parallel-orchestrate` `## Model Selection`.
+   For an issue-number item, the preparation delegation prompt carries the issue-adoption line used
+   by `/parallel-plan` `## Preparation Fan-Out`, quoted verbatim: `Issue adoption: this item's GitHub
+   issue already exists. Verify it read-only (gh issue view), do not call potential_to_issue or the
+   promotion-entry tool, and record a top-level issue_adoption object in the checkpoint per
+   .claude/rules/orchestrator-state.md with origin filed_before_orchestration (or transferred when
+   the issue was transferred), waiving potential_to_issue and the promotion-entry tool for the
+   checkpoint's promotion-type. When a lifecycle record for the item exists under
+   docs/features/potential/promoted/, cite it as potential_record.` The line is omitted for a
+   potential-entry item, whose child promotes it.
 
 3. **Compute conflict edges over ALL items, including in-flight ones.** Invoke the scheduling
    entry point Get-BlastRadiusConflictEdge from the destination-runtime PowerShell port
@@ -91,17 +105,28 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    barrier, and the later-merging item merges `origin/main` under the existing per-item
    merge-conflict handling and re-passes CI before it merges.
 
-4. **Decide admission.** Call
-   `decide_admission(candidate, conflict_edges, in_flight, current_cohort_members=current_cohort_members)`
-   from `scripts/dev_tools/parallel_mutation_protocol.py`.
-   - `ADMIT_CURRENT_COHORT` — the candidate shares no edge with any member of the current cohort,
+4. **Decide admission.** Call the bundled entry point, which needs no Python interpreter:
+
+   ```bash
+   bash .claude/lib/bash/mutate-parallel-run.sh admit --candidate <key> --edges "<a>:<b> ..." --in-flight "<k> ..." --current-cohort-members "<k> ..."
+   ```
+
+   `--edges` carries the step-3 conflict edges over ALL items, `--in-flight` the in-flight (pinned)
+   keys, and `--current-cohort-members` the full current-cohort membership. The command prints one
+   JSON object whose `outcome` field is one of:
+   - `admit_current_cohort` — the candidate shares no edge with any member of the current cohort,
      pinned or unstarted. Admit it into the current cohort. NO recompute occurs and
      `recolor_generation` is unchanged — precisely because the candidate conflicts with no
      current-cohort member, so no cohort assignment needs to change.
-   - `DEFER_AND_RECOLOR` — the candidate shares an edge with at least one member of the current
-     cohort, pinned or not-yet-launched. Defer it to a future cohort and recolor by calling
-     `recolor_unstarted(unstarted_items, conflict_edges, pinned, current_generation, current_cohort=current_cohort, highest_pinned_cohort=highest_pinned_cohort)`.
-     `highest_pinned_cohort` is derived from re-verified durable state: the highest
+   - `defer_and_recolor` — the candidate shares an edge with at least one member of the current
+     cohort, pinned or not-yet-launched. Defer it to a future cohort and recolor through the
+     bundled entry point:
+
+     ```bash
+     bash .claude/lib/bash/mutate-parallel-run.sh recolor --unstarted "<k> ..." --edges "<a>:<b> ..." --pinned "<k> ..." --generation <g> --current-cohort <c> --highest-pinned-cohort <h>
+     ```
+
+     `--highest-pinned-cohort` is derived from re-verified durable state: the highest
      current-generation cohort index occupied by any in-flight item.
      The recolor is a recompute: `recolor_generation` increments by exactly one, and it places every
      unstarted item at an index at or above `current_cohort`, strictly above
@@ -125,8 +150,9 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    with an unstarted item OUTSIDE the current cohort does not defer: the cohort barrier keeps the
    two from running concurrently, so the coloring's existing separation already resolves it.
 
-5. **Apply the recolor result.** Write `RecolorResult.cohort_assignments` into `cohorts[]` and set
-   the top-level `recolor_generation` to `RecolorResult.generation`. The result's key set equals the
+5. **Apply the recolor result.** Write the recolor output field `cohort_assignments` into
+   `cohorts[]` and set the top-level `recolor_generation` to the output field `generation`. The
+   result's key set equals the
    unstarted set exactly and contains no pinned key: no in-flight item changes cohort or state as a
    result of this admission. Verify that before writing, and stop rather than write a result that
    names a pinned key. The admit branch performs no recolor at all, precisely because the candidate
@@ -141,8 +167,17 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    values to be unique (`scripts/dev_tools/_parallel_state_structures.py:282-305` — duplicate-index
    detection at 282-293, error emission at 301-305).
 
-6. **Append exactly one `mutations[]` entry**, at admission-decision time, built by
-   `build_add_entry` from `scripts/dev_tools/parallel_mutation_protocol.py`:
+6. **Append exactly one `mutations[]` entry**, at admission-decision time, built by the bundled
+   entry point. Run the first line on the admit branch (`--deferred false`) and the second on the
+   defer branch (`--deferred true`):
+
+   ```bash
+   bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> --deferred false --generation <g> --at <timestamp>
+   bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> --deferred true --generation <g> --at <timestamp>
+   ```
+
+   `--generation` is the run's generation before this admission, read before any step-5 recolor;
+   the printed entry stamps it unchanged or plus one per the table below:
 
    | Case | `op` | `item_key` | `prior_state` | `new_state` | `disposition` | `recolor_generation` |
    | --- | --- | --- | --- | --- | --- | --- |
@@ -152,7 +187,8 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    `prior_state` is null on BOTH add rows. The accompanying `prepared` -> `scheduled` transition is
    not lost and is not recorded in the mutation entry: it is recorded as an item-state update in
    `items[]`, the same mechanism that records `proposed` -> `admitted` -> `prepared` in step 2. The
-   `at` timestamp comes from the engine's injected clock seam.
+   `at` timestamp is supplied through `--at`; when `--at` is omitted the entry point stamps the
+   current UTC minute.
 
 7. **Validate the checkpoint** before treating the admission as applied. Run the
    `validate_orchestration_artifacts` MCP tool with `artifact_type:
@@ -168,6 +204,8 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
   and `benefit` (tolerated-not-validated, returned by the scheduling entry point), and no reason
   member is added: the four `conflict_edges[].reason` members are unchanged. The nine parallel
   enums are owned by `.claude/rules/parallel-orchestration.md` and are consumed, never extended.
+  The `complexity_band` recorded in step 2 is not a new field: it is an existing scheduling field
+  read by drift re-scheduling.
 - This operation never moves, restates, or re-derives an in-flight item's cohort or state.
 - This operation performs no destructive side effect: it closes no pull request and removes no
   worktree. Those belong to `/parallel-remove` with `--disposition abandon`.

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

@@ -45,24 +45,37 @@ which is exactly what the gate exists to prevent. The re-derivation is mandatory
 
 1. Re-derive durable state as above and resolve the run's `items[]`.
 
-2. **Gate the close on no item being in flight.** Call `decide_close(items)` from
-   `scripts/dev_tools/parallel_mutation_protocol.py`. It raises the dedicated rejection exception
-   carrying EVERY in-flight key, so the rejection names all the work that must finish first rather
-   than one item at a time. On rejection: report the blocking keys and stop. A rejected close
-   appends NO `mutations[]` entry and makes NO state change — do not record the attempt.
+2. **Gate the close on no item being in flight.** Pass every re-derived item, as one
+   `<key>:<state>` token each, to the bundled entry point, which needs no Python interpreter:
 
-3. **Append exactly one run-scoped `mutations[]` entry** for a successful close, built by
-   `build_close_entry` from `scripts/dev_tools/parallel_mutation_protocol.py`:
+   ```bash
+   bash .claude/lib/bash/mutate-parallel-run.sh close --items "<k>:<state> ..."
+   ```
+
+   Exit 0 (stdout `{"close_permitted":true}`) permits the close. Exit 1 rejects it and prints one
+   stderr line naming EVERY in-flight key, so the rejection names all the work that must finish
+   first rather than one item at a time. On rejection: report the blocking keys and stop. A
+   rejected close appends NO `mutations[]` entry and makes NO state change — do not record the
+   attempt.
+
+3. **Append exactly one run-scoped `mutations[]` entry** for a successful close, built by the
+   bundled entry point:
+
+   ```bash
+   bash .claude/lib/bash/mutate-parallel-run.sh close-entry --generation <g> --at <timestamp>
+   ```
 
    | Case | `op` | `item_key` | `prior_state` | `new_state` | `disposition` | `recolor_generation` |
    | --- | --- | --- | --- | --- | --- | --- |
    | Close | `close` | null (run-scoped) | null | null | null | `g` (unchanged) |
 
    The entry is run-scoped, so `item_key` is null: the close acts on the run, not on an item. The
-   `at` timestamp comes from the engine's injected clock seam.
+   `at` timestamp is supplied through `--at`; when `--at` is omitted the entry point stamps the
+   current UTC minute.
 
 4. **Do not recompute.** Run termination changes no cohort assignment, so `recolor_generation` is
-   UNCHANGED and `cohorts[]` is not rewritten. Do not call `recolor_unstarted` as part of a close.
+   UNCHANGED and `cohorts[]` is not rewritten.
+   Do not run the `recolor` subcommand as part of a close.
 
 5. **Stop admitting.** After the close is recorded, the run accepts no further `/parallel-add`. The
    close record is the run's final mutation; nothing may be appended to `mutations[]` after it.

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

@@ -256,12 +256,40 @@ carries exactly these five elements.
    execution from that plan rather than re-running promotion, research, or planning. The item's
    prepared feature folder and approved atomic plan are already committed and preflight-clear on the
    item's own pushed feature branch.
+   The execution child starts a new checkpoint in its own worktree, and the preparation checkpoint
+   does not carry over, so the prompt also instructs the child to verify the item's GitHub issue
+   read-only (gh issue view), not to call `potential_to_issue` or the promotion-entry tool, and to
+   record its own top-level `issue_adoption` object per `.claude/rules/orchestrator-state.md`,
+   with origin `filed_before_orchestration` unless the issue was transferred, waiving
+   `potential_to_issue` and the promotion-entry tool for the checkpoint's promotion-type. When a
+   lifecycle record for the item exists under `docs/features/potential/promoted/`, the child cites
+   it as `potential_record`.
 5. The model-budget marker line `model_budget.fable_policy: <disabled|available|preferred>.`
 
 Spawn parameters, passed on the `Agent` call and never written into the prompt text:
 `isolation: "worktree"`, `run_in_background: true`, branch base `origin/main`, and `model` equal to
 that item's model routing receipt's resolved model.
 
+**Band and receipt source.** The parent reads each item's `complexity_band` and
+`model_routing_receipt` from the planner checkpoint `artifacts/orchestration/parallel-planner-state.json`.
+When the planner checkpoint is unavailable, the committed kickoff artifact's `## Item Summary`
+`complexity` column is the fallback band source. The parent passes `model` equal to the receipt's
+`model` when the run's `fable_policy` equals the receipt's `fable_policy`; otherwise it re-resolves
+with `Resolve-DelegationModel -Agent orchestrator -Band <band> -FablePolicy <run fable_policy>` and
+passes that result.
+An item admitted through `/parallel-add` appears neither in the planner checkpoint
+`artifacts/orchestration/parallel-planner-state.json` `items[]` nor in the kickoff
+`## Item Summary`; for such an item the band source is that item's `complexity_band` on the
+orchestrator checkpoint `artifacts/orchestration/parallel-orchestrator-state.json` `items[]`. An
+admitted item carries no `model_routing_receipt`, so the parent resolves `model` at spawn time as
+`model_policy.complexity_to_model[<band>]` from `config/orchestration-routing.json` under the
+run's `fable_policy`, with `fable` clamped to `opus` when `fable_policy` is `disabled`. That result
+equals `Resolve-DelegationModel -Agent orchestrator -Band <band> -FablePolicy <run fable_policy>`
+because `preferred_overlay.agents` does not include `orchestrator`. The parent passes that explicit
+`model` on the spawn rather than relying on the frontmatter default, and it stops rather than
+spawning without `model` when the admitted item has no `complexity_band` on the orchestrator
+checkpoint.
+
 Negative obligations on the prompt:
 
 - It never carries `Preparation mode: true`. Preparation fan-out belongs to `parallel-planner` and
@@ -301,6 +329,27 @@ omitted `model` falls back to the delegate's frontmatter default, `opus`, which
 `fable` resolution — and MUST NOT hard-code `model=opus` in a way that overrides the resolved
 routing model.
 
+The band and receipt for each item come from the planner checkpoint
+`artifacts/orchestration/parallel-planner-state.json`: the parent reads the item's `complexity_band`
+and `model_routing_receipt` there. When the planner checkpoint is unavailable, the committed kickoff
+artifact's `## Item Summary` `complexity` column is the fallback band source. The parent passes
+`model` equal to the receipt's `model` when the run's `fable_policy` equals the receipt's
+`fable_policy`; otherwise it re-resolves with
+`Resolve-DelegationModel -Agent orchestrator -Band <band> -FablePolicy <run fable_policy>` and
+passes that result.
+An item admitted through `/parallel-add` appears neither in the planner checkpoint
+`artifacts/orchestration/parallel-planner-state.json` `items[]` nor in the kickoff
+`## Item Summary`; for such an item the band source is that item's `complexity_band` on the
+orchestrator checkpoint `artifacts/orchestration/parallel-orchestrator-state.json` `items[]`. An
+admitted item carries no `model_routing_receipt`, so the parent resolves `model` at spawn time as
+`model_policy.complexity_to_model[<band>]` from `config/orchestration-routing.json` under the
+run's `fable_policy`, with `fable` clamped to `opus` when `fable_policy` is `disabled`. That result
+equals `Resolve-DelegationModel -Agent orchestrator -Band <band> -FablePolicy <run fable_policy>`
+because `preferred_overlay.agents` does not include `orchestrator`. The parent passes that explicit
+`model` on the spawn rather than relying on the frontmatter default, and it stops rather than
+spawning without `model` when the admitted item has no `complexity_band` on the orchestrator
+checkpoint.
+
 `route` is never an input to model selection. `route` remains file-count driven and governs only
 agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`
 inherits the parent model and ignores a model override, so model selection applies to agent
@@ -324,23 +373,48 @@ Procedure, per item:
 1. The item's child orchestration runs unmodified, with `epic_mode` `false` or absent, and finishes
    at its own DONE. The child's PR Creation Gate condition 6 already requires
    `ci_gate.conclusion == "success"`, so at child DONE the item's pull request is open against
-   `main` and its checks are green. The child is never instructed to merge its own pull request.
+   `main` and every check on its head SHA passed or was skipped. The child is never instructed to
+   merge its own pull request.
 2. On child completion, durably confirm pull-request state and check conclusion with
-   `gh pr view --json state,mergedAt,headRefOid`, and with `gh pr checks` when the check conclusion
-   must be re-read — never from an in-memory completion notification — then record
-   `merge_status: ci_green`.
+   `gh pr view --json state,mergedAt,headRefOid` and an unconditional re-read of every check on
+   that head, never from an in-memory completion notification or from the child's DONE report
+   alone. Run `gh pr checks <PR> --json bucket,name,state,link,workflow` and parse its output with
+   `pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1 -ChecksJson <checks-json> -HeadSha <headRefOid>`.
+   Record `merge_status: ci_green` only when that parser conclusion is `success`; on `failure` or
+   `pending`, or when `gh pr checks` fails with a "no checks reported" error, do not record
+   `merge_status: ci_green` and do not run `gh pr merge`.
    Before recording `merge_status: ci_green`, confirm that the `headRefOid` value equals the
    `ci_gate.head_sha` the child reported at DONE and that the child reported no pending
    CI-dependent acceptance criteria. When either check fails, do not record
    `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
@@ -382,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
 
@@ -393,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
@@ -413,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
@@ -613,9 +691,10 @@ Every mutation re-derives durable state (`git worktree list --porcelain`, `git b
 `gh pr view`) before it is applied, because the checkpoint is a cache of durable state and not the
 source of truth. A rejected mutation appends no entry and changes no state.
 
-The decision logic for all three commands is the pure engine
-`scripts/dev_tools/parallel_mutation_protocol.py`. It decides; it never applies. Item keys are
-integers (`items[].issue_num`) everywhere on this surface.
+The decision logic for all three commands runs through the bundled bash entry points, which need no
+Python interpreter: `bash .claude/lib/bash/mutate-parallel-run.sh` for add, close, and requeue, and
+`bash .claude/lib/bash/remove-parallel-item.sh` for remove. They decide; they never apply. Item
+keys are integers (`items[].issue_num`) everywhere on this surface.
 
 ### Pinning invariant
 
@@ -719,8 +798,9 @@ lost and is not recorded in the mutation entry: it is recorded as an item-state
 with the checkpoint's lifecycle timestamps, the same mechanism that records
 `proposed` -> `admitted` -> `prepared` during preparation. `new_state` is null for `close` only, and
 `item_key` is null for `close` only. `disposition` is non-null only on a `remove` entry whose
-`prior_state` is `in_flight`. Every `at` timestamp comes from the engine's injected clock seam; the
-engine never reads the wall clock. No field and no enum member is added to `mutations[]`; the nine
+`prior_state` is `in_flight`. Every `at` timestamp is supplied by the caller through `--at`; an
+entry point reads the clock only when `--at` is omitted, and then stamps the current UTC minute. No
+field and no enum member is added to `mutations[]`; the nine
 parallel enums of `.claude/rules/parallel-orchestration.md` are consumed, never extended.
 
 Retrospective validation of the log is the helper
@@ -768,18 +848,25 @@ command to evade the match: that defeats the only mechanism protecting a destruc
 ### Drift-requeue append contract
 
 Radius drift detection consumes this protocol rather than reimplementing it. When drift halts the
-later-started item of a newly conflicting pair, the requeue is recorded through the mutation
-engine's `build_requeue_entry` constructor and the recolor through `recolor_unstarted`:
+later-started item of a newly conflicting pair, the requeue is recorded through the `requeue-entry`
+subcommand of the bundled entry point and the recolor through its `recolor` subcommand:
+
+```bash
+bash .claude/lib/bash/mutate-parallel-run.sh requeue-entry --item <key> --generation <g> --at <timestamp>
+```
 
 - Item state becomes `blocked` and per-item `merge_status` becomes `blocked_drift`.
 - Exactly one `mutations[]` entry is appended with `op: requeue`, `prior_state: in_flight`,
   `new_state: blocked`, `disposition: null`, and `recolor_generation` equal to `g` + 1 — the requeue
   is a recompute.
-- The recolor runs over the unstarted subgraph only, so no other in-flight item moves. Its call
-  shape is the six-argument form
-  `recolor_unstarted(unstarted_items, conflict_edges, pinned, current_generation, current_cohort=current_cohort, highest_pinned_cohort=highest_pinned_cohort)`,
-  where `current_cohort` and `highest_pinned_cohort` are both required and keyword-only.
-  `highest_pinned_cohort` is derived from re-verified durable state: the highest
+- The recolor runs over the unstarted subgraph only, so no other in-flight item moves. Run it as:
+
+  ```bash
+  bash .claude/lib/bash/mutate-parallel-run.sh recolor --unstarted "<k> ..." --edges "<a>:<b> ..." --pinned "<k> ..." --generation <g> --current-cohort <c> --highest-pinned-cohort <h>
+  ```
+
+  where `--current-cohort` and `--highest-pinned-cohort` are both required.
+  `--highest-pinned-cohort` is derived from re-verified durable state: the highest
   current-generation cohort index occupied by any in-flight item.
 
 The drift event itself is recorded in `drift_events[]`, which this protocol does not write. See