@danmoisan/drm-copilot-mcp 1.1.17 → 1.1.19

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

@@ -34,6 +34,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
 
@@ -81,7 +82,7 @@ blocked result before launch.
 
 Because model selection is required once delegation occurs (see `## Model Selection`), a resuming orchestrator must repair a missing model choice deterministically before delegating at a delegating `next_step`. When the resumed `next_step` is a delegating step:
 
-a. **Preflight the checkpoint.** Run the orchestrator-state validator with `--require-model-routing` (via `mcp__drm-copilot__validate_orchestration_artifacts` or the local CLI) against `artifacts/orchestration/orchestrator-state.json` before the first delegation. Record the result in a `model_routing_preflight` block `{ status ("pass"|"fail"), checked_at (ISO-8601 UTC), validator_command, output_summary }`.
+a. **Preflight the checkpoint.** Run the orchestrator-state validator with `--require-model-routing` (via `mcp__drm-copilot__validate_orchestration_artifacts` or the repository-local validator CLI documented in `.claude/rules/orchestrator-state.md`) against `artifacts/orchestration/orchestrator-state.json` before the first delegation. Record the result in a `model_routing_preflight` block `{ status ("pass"|"fail"), checked_at (ISO-8601 UTC), validator_command, output_summary }`.
 b. **Recompute the floor.** For the upcoming phase, recompute the complexity floor with `Get-ComplexityFloor -SignalsPresent <names>` (`.claude/lib/model-routing/ModelRouting.psm1`); do not reimplement the formula.
 c. **Record the assessment.** Write a `complexity_assessments[]` entry `{ phase, band, floor, signals_present[], rationale, assessed_at }` with `floor` equal to the recomputed value and `band >= floor`.
 d. **Resolve and record the receipt.** Resolve the model with `Resolve-DelegationModel -Agent <agent> -Band <complexity_band> -FablePolicy <fable_policy>` (`.claude/lib/model-routing/ModelRouting.psm1`) and write a `model_routing_receipts[]` entry `{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }`.
@@ -137,6 +138,7 @@ A delegation prompt carrying the literal marker `Preparation mode: true` (issued
 - **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`.
 - **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.
 
 ## Epic Mode Bounded Return
@@ -184,10 +186,12 @@ PR creation and PR body edits are delegated work, not orchestrator work. The orc
 The mandatory sequence is:
 
 1. The orchestrator first refreshes the PR-context artifact via `mcp__drm-copilot__collect_pr_context` (or the equivalent context-collection mechanism), which writes `artifacts/pr_context.summary.txt`.
-2. The orchestrator runs the orchestrator-state validator (`mcp__drm-copilot__validate_orchestration_artifacts` or the equivalent local CLI call) against `artifacts/orchestration/orchestrator-state.json --require-pr-creation-ready` and records the pass/fail result under a new `pr_author_preflight` field in the checkpoint, alongside `pr_author_receipt`: `{status ("pass"|"fail"), checked_at (ISO-8601 UTC), checkpoint_path, validator_command, output_summary}`. The orchestrator must not delegate to `Agent(pr-author)` when this preflight fails. The validator's full-lifecycle completion flag (`ci_gate`/`pr_gate`/routing-contract receipts) remains reserved for the post-PR/CI completion context (Step S9 / PR Creation Gate condition 6), not this pre-PR-creation preflight, because those values cannot exist before the first `gh pr create` of a branch.
+2. The orchestrator runs the orchestrator-state validator (`mcp__drm-copilot__validate_orchestration_artifacts` or the equivalent repository-local validator CLI documented in `.claude/rules/orchestrator-state.md`) against `artifacts/orchestration/orchestrator-state.json --require-pr-creation-ready` and records the pass/fail result under a new `pr_author_preflight` field in the checkpoint, alongside `pr_author_receipt`: `{status ("pass"|"fail"), checked_at (ISO-8601 UTC), checkpoint_path, validator_command, output_summary}`. The orchestrator must not delegate to `Agent(pr-author)` when this preflight fails. The validator's full-lifecycle completion flag (`ci_gate`/`pr_gate`/routing-contract receipts) remains reserved for the post-PR/CI completion context (Step S9 / PR Creation Gate condition 6), not this pre-PR-creation preflight, because those values cannot exist before the first `gh pr create` of a branch.
 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.
@@ -237,24 +241,36 @@ After each `feature-review` delegation returns:
 
 1. Locate `remediation-inputs.<timestamp>.md` in the active feature folder (match the highest ISO-8601 timestamp).
 2. If no such file exists, treat as zero blocking findings and advance to the PR creation gate.
-3. If the file exists, count lines matching `BLOCKING` or `Severity: Blocking` (case-sensitive). If count >= 1, enter the remediation loop. If count = 0, advance to the PR creation gate.
+3. If the file exists, count lines matching `BLOCKING` or `Severity: Blocking` (case-sensitive). If count >= 1, enter the remediation loop. If count = 0, advance to the PR creation gate. This count rule applies unchanged when the file carries no `Review-Verdict:` line: a count of at least 1 is `REMEDIATION_REQUIRED` and every finding is treated as `autonomous`.
+4. If the file carries a `Review-Verdict:` line, recompute the verdict from the `Remediability:` lines of the blocking findings (a blocking finding block without a `Remediability:` line counts as `autonomous`): no blocking finding is `PASS`; any `autonomous` finding is `REMEDIATION_REQUIRED`; otherwise any `external_dependency`, `policy_hold`, or `human_decision_required` finding is `HALT_NON_REMEDIABLE`; otherwise `AWAITING_CI`. The `remediation-inputs` file is authoritative; the optional `review-status:` token in the review result is a cross-check.
+5. A mismatch between the declared and recomputed verdicts is a reviewer contract error: record it under `artifact_errors`, re-request the review once, and halt with `blocked_reason: "delegate_contract_incomplete"` if it persists.
+6. Append a `remediation_loop.review_outcomes[]` entry (`verdict` plus one `findings[]` object with `remediability` per blocking finding) for every review, including `PASS`.
+7. Act on the verdict: `PASS` advances to the PR creation gate; `REMEDIATION_REQUIRED` enters the remediation loop with the plan scoped to the `autonomous` findings, carrying the non-remediable findings forward unchanged; `HALT_NON_REMEDIABLE` follows the halt branch; `AWAITING_CI` follows the wait branch.
+
+Halt branch (`HALT_NON_REMEDIABLE`): set `blocked_reason` to the highest-precedence halt class present, append one `human_interaction.requirements[]` entry with `response: "halt"` for each halt class present (`external_dependency`, `policy_hold`, `human_decision_required`) describing the human action needed, leave `remediation_loop.completed_attempts` unchanged, write no cycle, create no remediation plan, and stop. The precedence is:
+
+Halt precedence: human_decision_required > policy_hold > external_dependency
+
+Wait branch (`AWAITING_CI`): set `blocked_reason: "awaiting_ci"` and set `next_step` to the step that re-checks (`S7_feature_review` for a review-time wait, `S9_ci_green` for an S9 poll timeout). Record no `human_interaction.requirements[]` entry for a wait, write no cycle, and create no remediation plan. Poll within the existing bounded S9 interval and timeout; when the bound is exhausted, persist and stop. On resume, set `blocked_reason: "none"` and re-run the named step. For S9, the awaited run is identified by `ci_gate.head_sha` and `ci_gate.pr_pipeline_run_id` with `conclusion: "pending"`; for a review-time wait, the awaited workflow is named in the finding's `Remediability-Evidence:` line.
 
 ## Remediation Loop (R1–R5)
 
-A bounded loop consisting of five steps. The loop variable `remediation_pass` starts at 1 and increments at R5 before returning to R1.
+A bounded loop consisting of five steps. The attempt count is `remediation_loop.completed_attempts`, and `remediation_pass` equals `remediation_loop.completed_attempts`. The active cycle number is `completed_attempts + 1`, and `remediation.cycle_N` in `next_step` uses that number; `remediation_loop.current_cycle` is a record position in `cycles[]`, not a count. A halt or wait verdict never opens a cycle, and every cycle opened from a review records `opened_by_review`, the zero-based index of that `review_outcomes[]` entry.
+
+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.
 
 - **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.
 - **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.
-- **R5 — Loop-exit decision:** If the re-audit produces zero blocking findings, exit the loop and advance to the PR creation gate. Otherwise, record `remediation_pass` increment in the checkpoint and return to R1.
+- **R5 — Loop-exit decision:** Evaluate the re-audit per Post-Review Outcome Evaluation. If it produces zero blocking findings, exit the loop and advance to the PR creation gate. If its verdict is `HALT_NON_REMEDIABLE` or `AWAITING_CI`, follow the halt or wait branch instead of opening the next cycle. Otherwise, record the cycle's `candidate_applied` value and the resulting `completed_attempts` in the checkpoint and return to R1.
 
-**Termination guard:** If `remediation_pass` reaches 3 without resolution, the orchestrator records `step6_status: "blocked_remediation_loop_limit"` in the checkpoint and halts. No further automation is attempted.
+**Termination guard:** Halt after three completed attempts: when `remediation_loop.completed_attempts` equals 3 and the latest verdict is not `PASS`, the orchestrator records `step6_status: "blocked_remediation_loop_limit"` in the checkpoint and halts. No further automation is attempted.
 
 ## 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:
 
@@ -273,12 +289,19 @@ 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.
-4. Poll with a bounded interval and a documented total timeout while `conclusion == "pending"`. When the timeout is exhausted, set `step9_status: "failed_remediation_required"` and enter the remediation-loop CI-failure handling below with a timeout log.
+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.
 
+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.
+
 DONE is not written while `step9_status` is anything other than `passed`.
 
 ## Checkpoint Schema — CI Gate Fields
@@ -286,7 +309,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`.
@@ -321,13 +344,13 @@ 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 or an exhausted poll timeout):
+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` (or the timeout log) is written as `remediation-inputs.<timestamp>.md` in the active feature folder.
+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.
-4. The `remediation_pass` counter is shared with local-finding passes; the cap is 3.
-5. On the third CI-failure pass without resolution, the orchestrator records `step9_status: "blocked_ci_loop_limit"`, does not write DONE, and halts. No further automation is attempted.
+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.
 
 ## PR Creation Gate
 
@@ -335,6 +358,7 @@ The orchestrator must not create a PR, push a branch for PR purposes, or report
 
 1. `blocking_findings_resolved: true` — the most recent `feature-review` produced zero blocking findings.
 2. The AC verification artifact (`p14-acceptance-criteria-checkoff.md` or equivalent) confirms all acceptance criteria pass.
+   A CI-dependent acceptance criterion, one whose verification requires the result of CI on the PR head, cannot pass before CI exists: condition 2 is satisfied when every other criterion passes and each CI-dependent criterion is listed as pending-CI in the AC verification artifact. Pending-CI criteria are checked off under S9 before DONE. This clarifies condition 2 and adds no condition.
 3. The mandatory toolchain passed in its most recent run on the branch (no linting/type-check/test failures).
 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`.
@@ -420,6 +444,8 @@ 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.
+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 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
@@ -313,16 +362,32 @@ unchanged: `.claude/skills/orchestrate/SKILL.md` is **not modified by this featu
 `parallel_mode` clause in its step 9, no `parallel_merge` object in the child checkpoint, and no
 additional condition on the child's PR Creation Gate.
 
+Issue #744 later amended two parts of that child contract for CI-dependent acceptance criteria,
+whose verification requires the result of CI on the item's pull-request head: PR Creation Gate
+condition 2 and step S9 of `.claude/skills/orchestrate/SKILL.md`. The child checks those criteria
+off in its own worktree, pushes the check-off commit to its pull-request branch, and re-runs S9
+before DONE. The parent never commits acceptance-criteria check-offs from the coordinator root.
+
 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
    `docs/features/parallel/<slug>/parallel-status.md`.
@@ -417,8 +482,10 @@ the escalation path.
 2. The parent re-delegates that item's child orchestration. The child processes the finding through
    its unmodified R1 through R5 remediation loop exactly as it processes any local Blocking
    finding. No new remediation loop is introduced by this procedure.
-3. The child's `remediation_pass` counter is shared with its local-finding and CI-failure passes,
-   with the cap of 3, unmodified.
+3. Drift cycles share the child's `remediation_loop.completed_attempts` count with its
+   local-finding and CI-failure cycles, and the child halts after three completed attempts. The
+   active cycle number is `completed_attempts + 1`, and a cycle without an applied candidate
+   consumes no number.
 4. Each remediated pass ends again at child DONE with the pull request open and CI green, after
    which the parent retries the merge per `## Per-Item Merge to Main (Merge-on-Green)`. During
    remediation the item's `merge_status` legitimately remains `pr_open` or `ci_green`: the
@@ -567,6 +634,8 @@ hold:
    `artifact_type: "parallel-orchestrator-state"`.
 4. Each item's acceptance criteria have been checked off in that item's own acceptance-criteria
    source files by that item's own run, per the `acceptance-criteria-tracking` skill.
+   A CI-dependent criterion is checked off and pushed by that item's own run before its DONE, so
+   the head the parent merges already contains the check-off; the parent never commits it.
 
 In `open` mode there is no automatic completion. The run is a standing queue and terminates only via
 `/parallel-close`, which is owned by F6 and is neither specified nor shipped by this feature. Do not
@@ -598,9 +667,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
 
@@ -704,8 +774,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
@@ -753,18 +824,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
@@ -1113,7 +1191,7 @@ R5 loop that drives the remediation preceding either write is **reused
 unmodified**: `atomic-planner` plans the resolution, `atomic-executor` performs preflight then
 resolves, `feature-review` re-audits, and the loop exits on zero blocking findings. No new
 remediation loop is authored, no line of the existing loop is modified, and the shared
-`remediation_pass` cap of 3 applies. `.claude/skills/orchestrate/SKILL.md` is not modified by this
+`remediation_loop.completed_attempts` count applies, with the halt after three completed attempts. `.claude/skills/orchestrate/SKILL.md` is not modified by this
 feature.
 
 #### Layer-1 Narrowing — a Documented Limitation