Parallel Orchestrate Skill
A user invocation (/parallel-orchestrate <parallel-manifest-path>) forks the
parallel-orchestrator agent with this procedure in context. The parallel manifest path (or
parallel slug) for this run is:
$ARGUMENTS
This skill frames work for the parallel-orchestrator agent, parallel to how
.claude/skills/orchestrate/SKILL.md frames work for orchestrator. It documents manifest
consumption, cohort consumption and ordering, the cohort barrier and max_concurrency slot
filling, the per-item branch and worktree lifecycle, the child kickoff parameter, model selection,
per-item merge to main, per-item merge-conflict handling, worktree cleanup,
parallel-status.md maintenance, checkpoint persistence, and completion, so that the procedure is
not re-derived ad hoc on each parallel run.
Each item on this surface ships independently: an item's pull request targets main directly.
There is no integration branch, no final integration pull request, and no fan-in path anywhere in
this procedure. Scheduling order comes only from computed blast-radius contention recorded in the
cohort table; there is no depends_on field on this surface.
Every section below is self-contained. A cross-reference names another section by its exact
heading text, never by position or number, so a section can be added or extended without
reflowing, reordering, or renumbering anything else in this file. The sections
## Mutation Protocol (F6), ## Enforcement Hooks (F7), and ## Radius Drift Detection (F8)
are reserved for the wave-4 features named in them: each is appended to by its own feature and
must not be relocated.
Prerequisites
Before proceeding, parallel-orchestrator must:
- Read
CLAUDE.mdfor repository tone policy and architectural context. - Read the applicable
.claude/rules/files for the languages in scope, including.claude/rules/parallel-orchestration.md, which is the schema authority for this surface. - Read the policy files listed in the compliance reading order section of
CLAUDE.md.
Parallel Manifest Consumption
The run manifest is the YAML frontmatter of docs/features/parallel/<slug>/parallel.md, authored
by parallel-planner on the planner-owned branch parallel/<slug>-plan. That branch is not an
integration branch: no item branch merges into it, it merges into no item branch, and it holds
only run-level artifacts under docs/features/parallel/<slug>/.
This section is not a schema authority. The manifest schema, the checkpoint schema, and all
nine parallel enums are defined once as prose invariants in
.claude/rules/parallel-orchestration.md (manifest invariants M1 through M7) and are enforced by
the F3-owned validators scripts/dev_tools/parallel_manifest_contract.py and
scripts/dev_tools/validate_parallel_orchestrator_state.py, with the manifest half reachable on the
destination-runtime path as bash .claude/lib/bash/validate-parallel-manifest.sh. This is a deliberate delta from
.claude/skills/epic-orchestrate/SKILL.md, whose manifest section carries its schema inline. Read
the schema from the rule file and the validators; consume it here and never redefine or extend it.
Consumption rules:
issue_numis the primary key for every item reference. It is the stable GitHub issue number, so it does not drift when an item's folder moves fromdocs/features/active/todocs/features/completed/.- Read
mode(closedoropen, defaulting toclosed),max_concurrency(an integer from 1 through 32, defaulting to 4), and each item's identity and state:feature_folder,kind,state, andblast_radius. - The manifest is read-only to
parallel-orchestrator. It is static input authored byparallel-planner: never write it, rewrite it, or back-fill a field into it. - The manifest carries no
depends_onkey at any level and no top-levelintegration_branchkey. Presence of either is an explicit rejection, not a tolerated extra field. - A malformed manifest is rejected before any kickoff, recorded as a synthetic Blocking finding in
the checkpoint. Do not guess a repair, do not silently skip the offending item, and do not launch
a partial cohort. Validate with the destination-runtime bash entry point, which needs no Python
interpreter and is published by push-down alongside
.claude:bash .claude/lib/bash/validate-parallel-manifest.sh docs/features/parallel/<slug>/parallel.md. Its non-zero exit is the rejection signal and its printed error list, one error per line on stdout, is the content of the Blocking finding; exit 1 means the manifest is invalid and exit 2 means the file is unreadable or uses a YAML construct outside the supported subset. Consumemodeandmax_concurrencythrough the same entry point's--print-modeand--print-max-concurrencysubcommands rather than reading the frontmatter directly.validate_parallel_manifest_textinscripts/dev_tools/parallel_manifest_contract.pyremains the repository authority and the parity reference. Manifest validation is deliberately not an MCP artifact type.
Cohort Consumption and Ordering
cohorts[] is an input, not a computation. Each entry has the shape
{ index, generation, item_keys[] } and is seeded by parallel-planner at generation: 0 from
the deterministic Welsh-Powell coloring in scripts/dev_tools/parallel_cohort_computation.py.
parallel-orchestrator consumes the recorded partition and never computes or recolors one:
- Cohort computation belongs to the cohort-scheduler library that
parallel-plannercalls. - Recoloring after a membership change belongs to F6; recoloring after a drift event belongs to F8.
- Read
recolor_generationand schedule only from the cohorts whosegenerationequals it.
Items within a cohort are non-conflicting by construction — a cohort is an independent set in the
conflict graph — so they may branch from the same main tip and may merge in any order. After one
same-cohort item merges, another same-cohort item's pull request, based on the older tip, remains
mergeable, and GitHub produces a merge commit.
The conflict graph the cohorts project was computed by a contention relation that fails closed. Since the blast-radius corrections of issue #452 (merged as PR #453), that relation reports more contention rather than less: separator-free repository-root shared surfaces are reached from plan and specification text, and path comparison honours listed-directory prefixes on both sides. Build on that corrected behaviour. Never narrow a radius, re-derive a partition, or reinterpret an edge in order to combine two cohorts or widen a launch batch.
Cohort Barrier and Max-Concurrency Slot Filling
Two independent controls govern every launch. The cohort barrier governs when an individual item
may start. max_concurrency governs how many eligible items run at once. Neither substitutes for
the other.
Cohort barrier (per-edge). An item may start only when every conflicting neighbour
(conflict_edges[]) that sits in a strictly prior current-generation cohort has merge_status of
merged or worktree_removed. ci_green does not satisfy the barrier: the pull request is not
merged, so its work is not on main. Same-cohort and later-cohort neighbours do not hold an item
back, and items with no conflicting prior-cohort neighbour may start regardless of other cohorts'
progress. The barrier is a predicate over one item's own conflict edges, not a global gate over
whole cohorts.
Evaluate the predicate only against durable state read from git worktree list --porcelain,
git branch, and gh pr view --json state,mergedAt,headRefOid — never from an in-memory
completion notification. A blocked item (blocked_ci_loop_limit or blocked_drift) is neither
merged nor worktree_removed, so it holds every conflicting later-cohort neighbour and,
transitively, the tail of its own conflict component; items outside that component are unaffected.
current_cohort is a progress indicator, not a gate. current_cohort is the LOWEST
current-generation cohort index that still contains a non-terminal, non-withdrawn item. It is
recomputed and written only on durable confirmation from git worktree list --porcelain,
git branch, and gh pr view --json state,mergedAt,headRefOid — never from an in-memory
completion notification. It gates nothing: no item's eligibility is decided by comparing it to
current_cohort, because eligibility is the per-edge predicate above. It is reported in the status
document, is the base index the mutation engine recolors from, and is bounded by rule invariant 14,
whose text is unchanged. Because the barrier is per-edge, in-flight items are not confined to
current_cohort; the highest current-generation index any pinned item occupies is a separate value
(highest_pinned_cohort, see ## Membership Mutation Protocol (F6)).
Safety argument. An item that starts under the per-edge rule while a non-conflicting
prior-cohort item is still open branches from a main that lacks only non-conflicting merged work.
That is byte-for-byte the situation the same-cohort merge-order text above already accepts as safe:
"Items within a cohort are non-conflicting by construction — a cohort is an independent set in the
conflict graph — so they may branch from the same main tip and may merge in any order." The
per-edge barrier extends that accepted situation across cohort boundaries without weakening it,
because the only work the starting item can be missing is work it does not conflict with. That
same-cohort text is unchanged by this rule.
Availability argument. Under a global barrier a single blocked_ci_loop_limit or
blocked_drift item halts every lane, because no item of the next cohort may start until every
item of the current one is terminal. Under the per-edge rule the blocked item holds only its own
conflict component's tail: its conflicting later-cohort neighbours, and transitively theirs.
Unrelated lanes keep advancing. That is the difference between one stuck item stalling a 13-lane
run and one stuck item stalling one lane.
max_concurrency slot filling. max_concurrency caps the number of simultaneously in-flight
items independently of cohort size: a cohort of twelve items executes at most max_concurrency
items at a time. Fill slots in ascending item-key order, keyed on issue_num, and refill each
freed slot with the next unstarted item of the current cohort in that same ascending item-key
order. A cohort larger than max_concurrency therefore launches in several batches, each from the
main tip recorded for that batch. The batching is a pure function, reached on the
destination-runtime path as
bash .claude/lib/bash/compute-concurrency-batches.sh --keys "<k1> <k2> ..." --max-concurrency <n>.
It prints a compact JSON array of arrays, returns the batches in order, and sorts the keys itself,
so determinism does not depend on caller ordering.
compute_concurrency_batches(cohort_item_keys, max_concurrency) in
scripts/dev_tools/parallel_cohort_computation.py remains the repository authority and the parity
reference.
Mechanical enforcement of the barrier is F7 scope, not this feature's. F7 delivers a two-layer
design, because no single PreToolUse hook can validate a batch of concurrent Agent calls: hooks
fire per call with no cross-call state visibility.
- Layer 1, per-call deterrent:
.claude/hooks/enforce-parallel-cohort-barrier.ps1, aPreToolUsehook on theAgentmatcher. It fires whensubagent_type == "orchestrator"and the serialized prompt carries the parallel kickoff marker, resolves the target item, readsartifacts/orchestration/parallel-orchestrator-state.json, and denies with reasonPARALLEL_COHORT_BARRIER_BLOCKEDunless every conflicting item in a prior cohort ismergedorworktree_removed. - Layer 2, retrospective backstop: a cohort-ordering invariant inside
validate_parallel_orchestrator_state_text, enforced atparallel-orchestratorSubagentStoptime, appendingPARALLEL_COHORT_BARRIER_VIOLATIONwhen the ordering invariant is violated.
Neither layer is shipped by this feature; both are named here so the obligation is legible to an operator and to the F7 planner. Until F7 lands, the barrier is enforced by this procedure alone.
The two layers fail closed differently, and the difference is deliberate. Do not read either layer's silence as permission.
- Layer 1 is PROSPECTIVE and evaluated per launch, so it denies fail-closed on every condition that
leaves the target's own eligibility unknowable: a missing or unparseable checkpoint, an unresolved
feature-folder token, a missing
items[]record for the target, a target with no current-generation cohort assignment, a missing neighbour record, and a missing neighbourmerge_status. Its one permissive case is neighbour-side: a NEIGHBOUR that carries no current-generation cohort assignment is skipped rather than denied, because such a neighbour sits in no prior cohort and therefore constrains nothing. - Layer 2 is RETROSPECTIVE and evaluated per edge, so it is deliberately silent on an edge it cannot
judge; a malformed edge is invariant 15's to report, not the barrier's. It applies three readings
of the same edge. The STRUCTURAL reading rejects two conflicting items colored into the same
current-generation cohort outright — a violation Layer 1 has no counterpart for, because Layer 1
only ever asks about strictly prior cohorts. The STATUS reading is the retrospective
contrapositive of the per-edge launch rule. The TEMPORAL reading rejects
merged_at(earlier) > worktree_created_at(later), and degrades to the status reading alone when either timestamp is absent or is not a string.
Per-Item Branch and Worktree Lifecycle
- Run one
git fetch origin mainimmediately before each launch batch, so every item in that batch branches from the same current remotemaintip rather than from a stale local ref. The unit is the launch batch, not the cohort: under the per-edge barrier a cohort's items become eligible at different times, and a cohort larger thanmax_concurrencylaunches in several batches, so a per-cohort fetch would leave later batches on a stale tip. Record the fetched tip for each batch. - Each item's worktree is created by that item's delegation spawn,
Agent(orchestrator, isolation: "worktree", run_in_background: true), branched fromorigin/main. Do not create or check out item worktrees by hand. parallel-plannercreated and pushed each item's feature branch fromorigin/mainat preparation time, and that branch is reused unchanged as the item's execution branch, so the spawn checks out an existing branch whose base isorigin/main. Because that base may be older than the fetched tip, the item's own run reconciles its branch against the fetchedorigin/maintip at execution start. Real path overlap that survives that reconciliation is drift; the conflict outcome is handled per## Per-Item Merge-Conflict Handling, and drift recording itself belongs to F8.- Each item's pull request base branch is
main. Recordworktree_path,branch_name,pr_number, andpr_urlfor the item, and setmerge_status: worktree_createdat spawn. - Worktree removal is the terminal step of this lifecycle and is specified in
## Worktree Cleanup.
No integration branch is created, fetched, pushed, or referenced at any point in this lifecycle. There is no final integration pull request and no fan-in path: the epic surface's integration-branch lifecycle has no counterpart on this surface, and its absence is structural rather than an omission.
Checkpoint hygiene (issue #673). The coordinating session never holds a per-feature checkpoint at its own root. Before the first item delegation of a run it moves any artifacts/orchestration/orchestrator-state.json at its root to artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json, and writes none there for the rest of the run, because each item's checkpoint lives in that item's worktree. A gated call the coordinator issues on an item's behalf is resolved by the item's issue number and branch, never by the coordinator root.
Parallel-Mode Kickoff Parameter
When parallel-orchestrator delegates an item to Agent(orchestrator), the delegation prompt
carries exactly these five elements.
The literal marker line:
Parallel mode: true. parallel_slug: <slug>. parallel_checkpoint_path: artifacts/orchestration/parallel-orchestrator-state.json. cohort_index: <n>. PR base branch MUST be main; pass --base main to gh pr create.The token
Parallel mode: truemust appear exactly: it is the marker F7's Layer 1 barrier hook matches on. The clausePR base branch MUST be mainis the child's explicit base-branch instruction, recorded as prompt text rather than left to a base-branch ancestry heuristic.The item's active feature folder path, written literally as
docs/features/active/<basename>. The child needs it for its own operation, and F7's Layer 1 hook resolves the target item by scanning the prompt for exactly that path shape, so the path is emitted as a bare path token.The canonical issue number line, which is the item key.
The item's committed
plan-path, together with the resume instruction: resume at atomic 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 callpotential_to_issueor the promotion-entry tool, and to record its own top-levelissue_adoptionobject per.claude/rules/orchestrator-state.md, with originfiled_before_orchestrationunless the issue was transferred, waivingpotential_to_issueand the promotion-entry tool for the checkpoint's promotion-type. When a lifecycle record for the item exists underdocs/features/potential/promoted/, the child cites it aspotential_record.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 toparallel-plannerand to F6's admission path; an item that reaches this procedure is already prepared. - It never carries the epic-mode marker line that
.claude/skills/epic-orchestrate/SKILL.mdemits — the marker whose text isEpic modefollowed by the valuetrue— so the epic wave-barrier hook does not fire on a parallel child. That marker's value is deliberately not written out anywhere in this file, so no file this feature delivers carries an epic-mode marker string. - It contains no instruction for the child to merge its own pull request. The parent performs each
item's merge, as specified in
## Per-Item Merge to Main (Merge-on-Green).
Excluded from the prompt as parent-side concerns: the item's declared blast radius,
max_concurrency, and mode. Keeping the prompt minimal preserves the child contract unchanged.
The run gates enforce-orchestration-preimplementation-gate.ps1, enforce-parallel-cohort-barrier.ps1, and enforce-parallel-drift-gate.ps1 locate the parallel checkpoint by the parallel_slug: value of the marker line. They select the single live worktree whose artifacts/orchestration/parallel-orchestrator-state.json records route_id parallel and that slug, and deny the delegation with TARGET_WORKTREE_NOT_DERIVABLE or TARGET_WORKTREE_AMBIGUOUS when none or more than one matches. The child run's own delegations to implementation agents carry the canonical issue-number line and branch: label defined in .claude/skills/orchestrate/SKILL.md ## Issue Number Consistency.
Model Selection
When parallel-orchestrator delegates an item to Agent(orchestrator), the prompt appends the
session model-budget kickoff marker line, following the existing kickoff-marker pattern:
model_budget.fable_policy: <disabled|available|preferred>.
The item's own orchestrator reads that line and applies the two-axis model-selection mechanism
documented in .claude/skills/orchestrate/SKILL.md (## Model Selection): it assesses a
judgment-based complexity_band, records complexity_assessments[] and
model_routing_receipts[], and resolves each of its own delegations' model tier under the given
fable_policy. The canonical, tested reference implementations are Get-ComplexityFloor and
Resolve-DelegationModel in .claude/lib/model-routing/ModelRouting.psm1. Default fable_policy
is disabled when the marker is absent.
parallel-orchestrator spawns exactly one delegation channel, Agent(orchestrator), one
delegation per item. It applies the same per-delegation resolution to that channel and passes
model equal to the routing receipt's model on the spawn call. It MUST NOT omit model — an
omitted model falls back to the delegate's frontmatter default, opus, which suppresses a
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
delegations, not to fork-routed skill invocations.
Per-Item Merge to Main (Merge-on-Green)
The parent — parallel-orchestrator — performs each item's merge to main. The child contract is
unchanged: .claude/skills/orchestrate/SKILL.md is not modified by this feature. There is no
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:
- The item's child orchestration runs unmodified, with
epic_modefalseor absent, and finishes at its own DONE. The child's PR Creation Gate condition 6 already requiresci_gate.conclusion == "success", so at child DONE the item's pull request is open againstmainand every check on its head SHA passed or was skipped. The child is never instructed to merge its own pull request. - On child completion, durably confirm pull-request state and check conclusion with
gh pr view --json state,mergedAt,headRefOidand 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. Rungh pr checks <PR> --json bucket,name,state,link,workflowand parse its output withpwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1 -ChecksJson <checks-json> -HeadSha <headRefOid>. Recordmerge_status: ci_greenonly when that parser conclusion issuccess; onfailureorpending, or whengh pr checksfails with a "no checks reported" error, do not recordmerge_status: ci_greenand do not rungh pr merge. Before recordingmerge_status: ci_green, confirm that theheadRefOidvalue equals theci_gate.head_shathe child reported at DONE and that the child reported no pending CI-dependent acceptance criteria. When either check fails, do not recordmerge_status: ci_greenand do not rungh 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. - Execute
gh pr merge --merge <PR>for that item's pull request, whose base ismain. Do not pass--delete-branchor--auto. A zero exit status does not prove a merge: whenmainuses a merge queue,gh pr mergeexits 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 withgh 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.pullRequestand classify it withpwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1 -PrJson <snapshot-json> -AsJson. Onpending, read again. When the 90 minutes are exhausted, report the item asawaiting_merge_queue, leave itsmerge_statusatci_green, and do not recordmerged. Onmerged, rungit fetch origin mainandgit merge-base --is-ancestor <merge-commit-oid> origin/main; the merge is confirmed only when that command exits 0. Onnot_queued, readgh pr view <PR> --json mergeable: aCONFLICTINGvalue enters## Per-Item Merge-Conflict Handling, and any other value is a merge-group CI failure that re-delegates the item's child to mergeorigin/mainand re-run S9 as one CI-failure remediation cycle, consuming a remediation attempt. Onclosed, stop and report a failure for the item. Never re-issuegh pr mergein a loop after anot_queuedoutcome. - Record
merge_commit_sha,merged_at, andmerge_status: mergedonly after the merge is confirmed by polling and ancestry check, then regeneratedocs/features/parallel/<slug>/parallel-status.md. - 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 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
step9_status == "passed"; an epic checkpoint whose epic_merge_pr.ci_gate.conclusion is
success with a matching pr_number; the parallel condition described next; and a standalone
merge authorization record, described after it. The parallel condition authorizes a per-item merge
when the parallel-orchestrator checkpoint has route_id == "parallel", the target item's
merge_status == "ci_green", and, when a PR number is named, it matches the item's pr_number.
Step 3 above is therefore permitted for a legitimate parallel merge; a missing, unreadable, or
invalid parallel checkpoint, a target item whose merge_status is not ci_green, or a PR number
that matches no item still fails closed with EPIC_MERGE_GATE_BLOCKED.
The standalone condition (issue #670) is the only route for merging a pull request that is not a parallel item, such as a standalone fix that unblocks the run. It is evaluated last and never overrides the other three. Writer procedure for the coordinating session:
- Write the record into a top-level
standalone_merge_authorizationsarray in the parallel-orchestrator checkpoint (artifacts/orchestration/parallel-orchestrator-state.json); the gate also reads the key from the per-feature and epic checkpoints. - Write one entry per authorized pull request, with these fields:
pr_number(JSON integer),pr_url(ending in/pull/<pr_number>),issue_num(JSON integer),branch_name,authorized_by,authorized_at(ISO 8601 date-time),session_id,basis(at least 20 characters), and optionallyrun_slug. - Set
session_idto the session id of the coordinating session that will run the merge command. The gate compares it with the live hook envelope and denies on any difference, so a record written by another session or a previous run authorizes nothing. - Name the pull request explicitly in the merge command (
gh pr merge <PR> --merge); a bare command never satisfies the standalone condition.
A blanket flag is actively rejected: a standalone_merge_authorizations value that names no
specific pull request (for example true) denies with
STANDALONE_MERGE_AUTHORIZATION_NOT_PR_SPECIFIC. Other denials carry
STANDALONE_MERGE_AUTHORIZATION_ABSENT, STANDALONE_MERGE_AUTHORIZATION_PR_MISMATCH, or
STANDALONE_MERGE_AUTHORIZATION_MALFORMED (naming the failing field) after the
EPIC_MERGE_GATE_BLOCKED token. The record is a policy-level, auditable declaration, not a
security control; see the Standalone-Merge-Authorization section of
.claude/rules/orchestrator-state.md for the full field rules and the disclosure.
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. 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
Remediation is child-owned and parent-initiated. The conflict is always between one item's own
branch and origin/main; there is no integration branch and therefore no fan-in conflict path on
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, or anot_queuedmerge confirmation whosemergeablevalue isCONFLICTING, the parent runs the two commandsgit -C <worktree_path> fetch origin mainandgit -C <worktree_path> merge --no-commit origin/main. - (b) The parent then runs
pwsh -NoProfile -File .claude/lib/project-file-merge/Resolve-MergeableConflict.ps1 -Worktree <worktree_path>and parses its single JSON object. Aresultofescalatemakes the parent rungit -C <worktree_path> merge --abortand continue with step 1 below, includingescalate_pathsin the Blocking finding. - (c) On
resolvedthe parent stages and commits the resolved paths with a message body listing every entry added from each side and every version choice, then runs the three commandsdotnet tool restore --tool-manifest <worktree_path>/.config/dotnet-tools.json,dotnet csharpier check <worktree_path>, anddotnet build <worktree_path>/<solution>, each with path arguments rather thancd. A failing check reverts withgit -C <worktree_path> reset --hard HEAD~1and escalates with the tool output as the finding. - (d) On success the parent pushes the item branch, records
mergeable_conflicts_resolvedon the item, setsmerge_status: pr_open, regeneratesparallel-status.md, and re-enters## Per-Item Merge to Main (Merge-on-Green)at the durablegh pr checksconfirmation step.
- On a conflicted
gh pr merge --merge, or anot_queuedmerge confirmation whosemergeablevalue isCONFLICTING, the parent detects the failure and re-delegates that item's child orchestration, passing the conflict signal and the instruction to resolve againstorigin/main. The conflict capture and the finding write both belong to the child'satomic-executor, which works inside the item's own worktree, the only working tree holding the item's branch. It runsgit fetch origin main, thengit merge --no-commit origin/main, and on non-zero exit capturesgit diff --name-only --diff-filter=Ufor the conflicted-file list together with the raw conflict-marker content of each conflicted file. The child'satomic-executorthen writes that evidence as a synthetic Blocking finding to the item's ownremediation-inputs.<timestamp>.mdin the item's active feature folder underdocs/features/active/, not to the run's parallel folder. Assigning both the capture and the finding write to the child's chain matches.claude/skills/epic-orchestrate/SKILL.md, whose equivalent capture and finding write also belong to the child'satomic-executor. - 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.
- Drift cycles share the child's
remediation_loop.completed_attemptscount with its local-finding and CI-failure cycles, and the child halts after three completed attempts. The active cycle number iscompleted_attempts + 1, and a cycle without an applied candidate consumes no number. - 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'smerge_statuslegitimately remainspr_openorci_green: themerge_statusenum is F3-owned, carries no conflict member, and is not extended by this feature. - On loop exhaustion, the parent records the terminal
merge_status: blocked_ci_loop_limitfor the item; the child's own checkpoint retains its precise blocked status. A blocked item is neithermergednorworktree_removed, so under the per-edge barrier defined in## Cohort Barrier and Max-Concurrency Slot Fillingit holds back exactly its own conflicting later-cohort neighbours — and, transitively, the tail of its own conflict component. Every item outside that component, including every item of a later cohort that shares no conflict edge with it, remains eligible and continues to launch.
Boundary with F8: a merge conflict between two same-cohort items is evidence that the declared
blast radius under-reported, and this feature records the child's blocked or remediated outcome
only, leaving drift recording in drift_events[], quiesce of admission, conflict recomputation
against the observed radius, and requeue of the later-started item to F8.
Worktree Cleanup
After an item reaches merge_status: merged and that state is durably confirmed by
gh pr view --json state,mergedAt,headRefOid, the parent — running from the main repository
checkout, never from inside a child worktree — issues git worktree remove <worktree_path>. On
success it records merge_status: worktree_removed and worktree_removed_at, then regenerates
docs/features/parallel/<slug>/parallel-status.md.
Mechanical gating of this command for parallel worktrees is delivered. Both halves have landed.
.claude/hooks/enforce-parallel-worktree-removal-gate.ps1 exists and is registered in
.claude/settings.json on the Bash matcher; it authorizes a removal from the
parallel-orchestrator checkpoint and owns the block reason
PARALLEL_WORKTREE_REMOVAL_BLOCKED. .claude/hooks/enforce-epic-worktree-removal-gate.ps1 is a
project-wide PreToolUse Bash-matcher hook registered alongside it whose block reason is
EPIC_WORKTREE_REMOVAL_BLOCKED; it now carries a second, parallel allow-branch, so it authorizes a
removal either from a matching epic checkpoint features[] record or from a parallel-orchestrator
checkpoint whose route_id is parallel and whose matching items[].worktree_path record has
merge_status in {merged, worktree_removed}. An unreadable checkpoint, an absent record, or a
non-authorizing merge_status still denies on both branches. The coordination matters because
PreToolUse denials are conjunctive: a
…(truncated)