Generated from
cat-harness/sdlc/processes/merge-manager-watch.bpmnbygen-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.
How it connects
- Called by: Merge request: find or elect the merge manager
- Calls: A merge train, Saturation meta-merge: land the ready PRs when the runners are full, Stalled-agent triage: collect handovers, consolidate themes, recommend, re-route
- Presented on: no docs page section shows this diagram
- Running instances: none recorded
Lanes — who acts
Steps
Every one of the 11 step(s) is documented.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Approve the batch cardOwner_Approve | Owner | interaction-modality | In 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 requestsTask_Read | Merge steward | merge-manager-watcher | Read 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-overTask_Lapse | Merge steward | merge-manager-watcher | Tell every sibling and the owner, and update the durable note with the session that holds the lane now. Nobody merges between holders. |
Relieve the runnersTask_Relieve | Merge steward | merge-manager-watcher | Enforce 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-mergeCall_Meta | Merge steward | calls Saturation meta-merge: land the ready PRs when the runners are full | Offer the card and land only on the owner’s tap. |
Post the request in chat, then the batch cardTask_Card | Merge steward | interaction-modality | The 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 trainCall_Train | Merge steward | calls A merge train | Add the merge-train label instead of merging; the train lands the batch with one CI run. |
Merge it through merge:guardTask_Direct | Merge steward | merge-manager-watcher | A 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 triageCall_Stalled | Merge steward | calls Stalled-agent triage: collect handovers, consolidate themes, recommend, re-route | A PR owner who stalled: tell the owner, then take the stalled PR over. |
Re-run the failed job onceTask_Rerun | Merge steward | merge-manager-watcher | Infrastructure 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 fixerTask_DispatchFixer | Merge steward | merge-manager-watcher | One 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.
| decision | what decides it | branches |
|---|---|---|
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 |