Generated from cat-harness/sdlc/processes/merge-request.bpmn by gen-processes-viz.ts — do not edit here. All processes · cat-harness processes

Merge request: find or elect the merge manager

Process_MergeRequest · strict (defaulted) · 8 step(s)

The sibling’s side of merging. A coding agent whose work depends on an unmerged PR stacks on it rather than waiting, and retargets when it lands. With a PR ready to merge it does not know whether a merge manager exists, so it checks: if one is active and live, it sends the six-line merge request; if none is, it elects one with its siblings by the fixed rule (a lone session is elected alone), the winner announcing itself to all and taking the lane. Only the merge manager merges and re-pins (owner rulings, 2026-11-13): no other session merges, and a PR green except for a re-pin is sent as repin+merge. Any agent may stall, the merge manager included: a request not acknowledged within the stall window sends the sibling to stalled-agent triage and a re-election without the stalled session. The merge manager’s own loop is Process_MergeManagerWatch. Source: owner rulings, 2026-11-07 and 2026-11-13. Ready to merge is defined in merge-queue §”What ‘ready to merge’ means”; a ready PR merges at once, lowest dependency first, and a lower repository never waits on a higher one (owner, 2026-11-15).

BPMN diagram: Merge request: find or elect the merge manager

How it connects

Lanes — who acts

lanerolewhat it does here
Sibling sessionsibling-sessionAny coding agent with a PR ready to merge. It first checks whether a merge manager is active; if none is and one is needed, it elects one with its siblings by the fixed rule; a lone or lapsed session manages its own PRs. It never merges another session’s PR, never pushes to another session’s branch, and treats a merge manager that does not acknowledge within the stall window as stalled. It never waits for a dependency to merge: it stacks on the dependency PR and keeps working.

Steps

Every one of the 8 step(s) is documented.

steplaneskill / sub-processwhat it does
Elect the merge manager with the siblings
Sib_Elect
Sibling sessionmerge-manager-watcherThe deterministic rule (electHolder): the active session that owns the P0 PR, else the earliest-created active session, the session id breaking a tie. Stalled sessions are not candidates. Every sibling computes the same answer from the same listing (owner ruling, 2026-11-07).
Announce and note the merge manager
Sib_Announce
Sibling sessionmerge-manager-watcherSend “merge manager: <session id>” to every sibling and the owner, and note it durably on the coordination work item, so it is used by all, including siblings started later.
Send the six-line merge request
Sib_Send
Sibling sessionmerge-manager-watcherTo the merge manager: the PR URL and full head SHA, the session URL, 1-3 sentences on the change, the rendered preview URL or no preview with a reason, what to look for, and full tier green as judged (owner ruling, 2026-11-07). Never merge it yourself, and never push to another session’s branch. A PR green except for a re-pin is sent as repin+merge: <owner/repo>#<n> <sha> with the same six lines; never re-pin it yourself, and never merge (owner ruling, 2026-11-13).
Stalled-agent triage
Sib_CallStalled
Sibling sessioncalls Stalled-agent triage: collect handovers, consolidate themes, recommend, re-routeTell the owner that the merge manager stalled, then re-elect with the stalled session excluded. The new holder announces itself, takes over the queue and tells the owner.
Merge manager watch
Sib_CallWatch
Sibling sessioncalls Merge manager watch: wake, read the queue live, routeThe elected session holds the merge steward lane and runs its loop until it hands over or the lane lapses.
Stack on it and keep working
Sib_Stack
Sibling sessioncontinual-progressSame repository: branch from the dependency PR’s branch and open a draft PR whose base is that branch; pull the dependency in with merge commits, never rebase or force-push another session’s branch. Across layers: develop against the dependency’s branch laid over a fresh mount; a draft may pin the dependency PR’s full head SHA, never a branch. Write “stacked on <repo>#<n>” in the PR body. A re-pin is its own PR holding only pins; work that needs the new pins stacks on it, and a fix the re-pin needs lands in its owning layer (owner ruling, 2026-11-07).
When the base lands, retarget
Sib_Retarget
Sibling sessioncontinual-progressRetarget the PR onto main and merge main in; across layers, send repin+merge: the merge manager re-pins to the dependency’s merge commit on main, so pins only move forward (owner ruling, 2026-11-13). Never merge the stacked PR into its base branch, and never mark it ready while it pins an unmerged commit.
Make the PR ready
Sib_Ready
Sibling sessioncontinual-progressIts own work is done and its full tier is green as judged; it is marked ready by the queue rule (continual-progress, Pace the ready marking).

Decisions

1 of 4 decision(s) carry no documentation — gateway-documented lists them.

decisionwhat decides itbranches
Merge manager active?
Sib_GwActive
Yes when the latest “merge manager: <session id>” announcement in the coordination group names a session that is live: active, and it answered within the stall window (holding.stalledAfterMinutes). The announcement is sent to every sibling and the owner, and noted durably on the coordination work item, so a newly started sibling finds it. No when there is no announcement, the holder handed over or lapsed, or the holder is stalled.Yes → Send the six-line merge request
No → Elect the merge manager with the siblings
Elected this session?
Sib_GwWon
—Yes → Announce and note the merge manager
No → Send the six-line merge request
Acknowledged in time?
Sib_GwAcked
Yes when the merge manager acknowledged the request within the stall window. No when it did not, or its session went inactive: the lane is treated as vacant.Yes → With the merge manager
No → Stalled-agent triage
Depends on an unmerged PR?
Sib_GwDepends
Yes when the work needs a change that is still in an open, unmerged PR, in this repository or in a lower layer. Do not wait for it to merge: stack on it (owner ruling, 2026-11-07).Yes → Stack on it and keep working
No → Make the PR ready

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev