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

Merge manager watch: wake, read the queue live, route

Process_MergeManagerWatch · strict (defaulted) · 11 step(s)

The loop run by the session that holds the merge-steward lane (actor merge-manager, skill merge-manager-watcher): elected, appointed, or holding it for its own PRs only. Each wake reads the open PRs, the runner queue, main’s verdict and the PR owners live, acknowledges merge requests within the heartbeat, and routes to the train, a direct merge, runner relief, a saturation meta-merge, a stalled-agent takeover, or a fixer for a red main in any harness repository (owner, 2026-11-10: “That should be a part of merge manager (dispatch an agent to fix them)”, “Add to process”). Every merge waits for the owner’s own OK, given in the merge manager’s session as one card per batch (owner ruling, 2026-11-07, card Approvals, B). How a sibling finds or elects the merge manager and sends it a request is Process_MergeRequest. Across dependent repositories the loop follows merge-manager-watcher §”Merging across dependent repositories” (owner, 2026-11-15): lowest dependency first, queued CI re-ordered the same way, batches per repository, a checkable stable point, content PRs (label content) kept out of the queue and the reports, one merge manager, full green for re-pins, reports at a fixed interval, a draft register, no idle agents, one card per owner question, approvals recorded durably, ignored repositories left out, and no state-branch commit from a sparse checkout. A lower repository never waits on a higher one, and a ready PR (merge-queue §”What ‘ready to merge’ means”: the generic list, out of draft, no conflicts, CI green against its own dependencies with reds that also fail on main and are not its own excused, description complete, approvals given; then the cat-harness additions, content rule, hand-over label, merge:guard success, issue link, and pins with full tier for re-pins) merges in the same sweep, lowest dependency first.

BPMN diagram: Merge manager watch: wake, read the queue live, route

How it connects

Lanes — who acts

lanerolewhat it does here
Merge stewardmerge-stewardThe merge manager: the one session holding the merge-steward lane, by the owner’s word, by election, or for its own PRs only. Each wake it reads the open PRs, the runner queue, main’s verdict and who owns each PR, acknowledges requests within the heartbeat, then routes to the process the queue needs or stays idle. It hands over explicitly when it stops; like any agent it may stall, and the siblings then re-elect.
OwneruserApproves in the merge manager’s session only, one card per batch. An approval given in a sibling’s session does not authorise a merge.

Steps

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

steplaneskill / sub-processwhat it does
Approve the batch card
Owner_Approve
Ownerinteraction-modalityIn the merge manager’s session only: one card per batch, naming each PR, after its six lines were posted in that chat. An approval given in a sibling’s session does not authorise a merge (owner ruling, 2026-11-07, card Approvals, B).
Read the queue, acknowledge requests
Task_Read
Merge stewardmerge-manager-watcherRead live, never from a stored copy: the open PRs (draft, head, mergeable, owed checks, open owner decisions), the queued and running runs with the age of the oldest, the latest main push run, each PR owner’s last push or comment, and every harness repository’s open main-red issue with its newest failed runs on main and gh-pages, whether or not the lane holds a PR there (gh api repos/<owner>/<repo>/actions/runs?branch=<default>&event=push: the latest completed push run per workflow, conclusion failure). One sweep runs merge:watch over every repository it holds, in dependency order (lowest first); merge:watch leaves out PRs labelled content. Liveness duty: acknowledge each new merge request within holding.heartbeatMinutes, and post a heartbeat with each sweep, so siblings can tell a live merge manager from a stalled one. A repin+merge: request is re-pinned by the merge manager itself, as its own re-pin PR in a re-pin train, before the requested PR lands; only the merge manager merges or re-pins, and a scheduled routine never merges (owner rulings, 2026-11-13).
Announce the hand-over
Task_Lapse
Merge stewardmerge-manager-watcherTell every sibling and the owner, and update the durable note with the session that holds the lane now. Nobody merges between holders.
Relieve the runners
Task_Relieve
Merge stewardmerge-manager-watcherEnforce the pacing rule of continual-progress (owner ruling, 2026-11-07, card Cancel CI): close superseded or duplicate PRs, such as a re-pin whose commits another open PR already carries, and cancel their runs; cancel stale queued runs that never started, never a main push run that has started; ask the owners of P3 PRs to return them to draft.
Saturation meta-merge
Call_Meta
Merge stewardcalls Saturation meta-merge: land the ready PRs when the runners are fullOffer the card and land only on the owner’s tap.
Post the request in chat, then the batch card
Task_Card
Merge stewardinteraction-modalityThe sibling’s six lines go into the merge manager’s chat first; a request with no rendered preview and no reason goes back to the sibling (owner ruling, 2026-11-07). Then one card per batch, naming each PR, in priority order: P0 main-red fixes and the re-pin chain, P1 work they unblock, P2 CI speed, P3 the rest.
Merge train
Call_Train
Merge stewardcalls A merge trainAdd the merge-train label instead of merging; the train lands the batch with one CI run.
Merge it through merge:guard
Task_Direct
Merge stewardmerge-manager-watcherA workflow PR, or a PR in a repository with no train, merges directly. A workflow PR needs no approval beyond the batch card (owner ruling, 2026-11-07, card Workflow PRs, A).
Stalled-agent triage
Call_Stalled
Merge stewardcalls Stalled-agent triage: collect handovers, consolidate themes, recommend, re-routeA PR owner who stalled: tell the owner, then take the stalled PR over.
Re-run the failed job once
Task_Rerun
Merge stewardmerge-manager-watcherInfrastructure is re-run, not fixed: re-run the failed job once. A second failure is real and goes back through the sort; a Pages timeout goes to the site-size work. A train that fails only on infrastructure gets its failed job re-run once. Never cancel a main push run that has started.
Dispatch a fixer
Task_DispatchFixer
Merge stewardmerge-manager-watcherOne fixer agent per cause, never one per repository. Give it the failing run, the cause and the repository: pins out of step go to the next re-pin train on the index; the layer’s own bug to a fix PR in that layer; a lower layer’s bug to a fix PR in the lower layer, then a re-pin. It opens a draft fix PR, linked from the main-red issue. The fix is a non-content P0 PR and follows the normal merge rules: the six-line request, the owner’s batch card, full-tier CI green as judged. Close the loop when the next main run is green and the main-red issue closes. Never silence the failure, and never skip, disable or quarantine a gate or a test.

Decisions

Every one of the 7 decision(s) is documented.

decisionwhat decides itbranches
Still holding the lane?
Gw_Needed
Yes while this session holds the lane. The lane does not lapse (owner ruling, 2026-11-13): a quiet queue still goes through the merge manager, and laneNeeded only says when the queue is contended. No when it hands over to a named session.Yes → What does the queue need?
No → Announce the hand-over
What does the queue need?
Gw_Route
Saturated: queued runs are 60+ minutes old and nothing has landed, or the owner says the runners are full. Stalled: a PR owner has been silent for 2+ hours. Ready: a merge request is in, with green owed CI. Main red: the main-red issue is open, or the latest completed push run of a workflow on a harness repository’s main (or a gh-pages deploy) failed. Otherwise nothing.Saturated → Relieve the runners
Ready → All green per rule 1?
Stalled → Stalled-agent triage
Nothing → Nothing to do
Main red → Owned?
All green per rule 1?
Gw_Green
Every check run on the head SHA has finished, and anything pending blocks; wait for every tier, e2e included. The full tier ran (the No new failures judge, or every full test shard); a draft or fast-tier-only pass never counts. Every judge passes (owner ruling, 2026-11-07): an aggregate job covers only the parts it names, and each test shard’s own no-new-failures table lists 0 new failures; with no judge, each check concluded success, skipped or neutral. A cancelled job counts only when a later run of the same workflow on the same head passed that job. merge:watch prints this verdict per PR.Yes → Pre-approved?
No → Not green yet
Pre-approved?
Gw_Approved
Yes when the owner already said to merge this PR when green, so no second card is needed. Otherwise the request goes on the next batch card.Yes → Rides the train?
No → Post the request in chat, then the batch card
Rides the train?
Gw_Train
Yes for a folio-assistant PR that does not change .github/workflows/. No for a workflow PR, or a PR in a repository with no train (owner ruling, 2026-11-07, card Train, A).Yes → Merge train
No → Merge it through merge:guard
Owned?
Gw_RedOwned
Coordinate, never duplicate. Yes when a thread, agent or open PR already owns this failure: a draft fix PR linked from the main-red issue, an open PR in that repository touching the same files (rule 3), or a sibling’s claim in the coordination group. One fixer per cause, never one per repository: a single lower-layer bug can redden every layer above it, so a red that shares a cause with an owned one is owned too.Yes → Owned: coordinate
No → Which cause?
Which cause?
Gw_RedCause
Sort each failure into one cause before dispatching, because the fix lands in a different place for each. Infrastructure: “The runner has received a shutdown signal”, a cancelled job, a Pages deploy stuck at syncing_files until it times out. Pins out of step: the failure names a file or test of another layer whose own main already differs. The layer’s own bug: it names this layer’s own file and fails at this layer’s own main. A lower layer’s bug: it names a lower layer’s file and fails at that layer’s main too.Infrastructure → Re-run the failed job once
Code or pins → Dispatch a fixer

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