Build: improced merge agent logic to ensure faster and more effective merging into master

2026-04-13 15:07:18 -04:00
parent 5a9aaa79ed
commit c5820266fd
7 changed files with 79 additions and 75 deletions
@@ -82,7 +82,7 @@ For agents or situations not covered by the static matrix, invoke `agent-type-in
 |---|---|---|---|---|
 | 1 | `AUTO-IMP-SUP` | implementation-pool-supervisor | implementor-pool | N_FULL |
 | 2 | `AUTO-REV-SUP` | pr-review-pool-supervisor | reviewer-pool | N_HALF |
-| 3 | `AUTO-PRMRG-SUP` | pr-merge-pool-supervisor | pr-merge-pool | 1 |
+| 3 | `AUTO-PRMRG-SUP` | pr-merge-pool-supervisor | pr-merge-pool | 0 (blocking subagent) |
 | 4 | `AUTO-UAT-SUP` | uat-test-pool-supervisor | tester-pool | N_QUARTER |
 | 5 | `AUTO-BUG-SUP` | bug-hunt-pool-supervisor | hunter-pool | N_QUARTER |
 | 6 | `AUTO-INF-SUP` | test-infra-pool-supervisor | test-infra-pool | N_QUARTER |
@@ -122,7 +122,7 @@ Every supervisor launches workers with session tags that follow a predictable pa
 |---|---|---|
 | `AUTO-IMP-SUP` | `[AUTO-IMP-ISSUE-<N>]` or `[AUTO-IMP-PR-<N>]` | `[AUTO-IMP-ISSUE-42]`, `[AUTO-IMP-PR-15]` |
 | `AUTO-REV-SUP` | `[AUTO-REV-<N>]` | `[AUTO-REV-1]` |
-| `AUTO-PRMRG-SUP` | `[AUTO-PRMRG-<N>]` | `[AUTO-PRMRG-1]` |
+| `AUTO-PRMRG-SUP` | _(none — blocking subagent, not async)_ | _(no async worker sessions)_ |
 | `AUTO-UAT-SUP` | `[AUTO-UAT-<N>]` | `[AUTO-UAT-1]` |
 | `AUTO-BUG-SUP` | `[AUTO-BUG-<N>]` | `[AUTO-BUG-1]` |
 | `AUTO-INF-SUP` | `[AUTO-INF-<N>]` | `[AUTO-INF-1]` |
@@ -140,6 +140,8 @@ Every supervisor launches workers with session tags that follow a predictable pa

 **Convention**: All session tags are enclosed in square brackets. All autonomous system tags start with `[AUTO-`. The `<N>` in worker patterns is typically the issue number, PR number, or a sequential counter depending on the supervisor.

+**Exception — PR Merge Pool**: `AUTO-PRMRG-SUP` calls `pr-merge-worker` as a **blocking subagent** (via the Task tool) rather than dispatching it as an async session. This means there are NO `[AUTO-PRMRG-<N>]` async sessions to discover. The product-builder and system-watchdog should skip worker health checks for this supervisor — its health is determined solely by whether the supervisor session itself (`[AUTO-PRMRG-SUP]`) is active.
+
 ## Priority Hierarchy

 The Forgejo priority labels in descending order of urgency:
@@ -102,11 +102,11 @@ Polls Forgejo for pull requests needing code review and dispatches `pr-reviewer`

 | Prefix | Definition | Display Name | Workers |
 |---|---|---|---|
-| `AUTO-PRMRG-SUP` | pr-merge-pool-supervisor | pr-merge-pool | 1 |
+| `AUTO-PRMRG-SUP` | pr-merge-pool-supervisor | pr-merge-pool | 0 (blocking subagent) |

-Continuously monitors open PRs for merge readiness. Verifies all seven merge criteria, handles pre-merge rebasing, and performs verified merges. Dispatches workers for rebase operations.
+Continuously monitors open PRs for merge readiness. Verifies all seven merge criteria, handles pre-merge rebasing, and performs verified merges. Calls `pr-merge-worker` as a **blocking subagent** (not async) for rebase operations.

-**Key behaviors**: Seven merge criteria verification, fast-forward merge when possible, automatic rebase for PRs without conflicts, re-attempt after quality gates pass.
+**Key behaviors**: Seven merge criteria verification, fast-forward merge when possible, automatic rebase for PRs without conflicts, re-attempt after quality gates pass. **Unlike other supervisors, does NOT use async-agent-manager for workers** — calls `pr-merge-worker` directly via the Task tool and blocks until it completes.

 **Relationships**: Depends on pr-review approvals. Consumes PRs produced by implementation-pool. Successful merges trigger spec-update and documentation work. Rebase failures create work for implementation-pool.

@@ -310,13 +310,13 @@ Monitors the entire autonomous agent system for correctness. Verifies quality ga

 ### Workers (Short-Lived)

-Workers are dispatched by pool supervisors to perform discrete units of work. They complete and exit. Key workers:
+Workers are dispatched by pool supervisors to perform discrete units of work. They complete and exit. Most workers run as async sessions; exceptions are noted below. Key workers:

 | Worker Definition | Launched By | Purpose |
 |---|---|---|
 | implementation-worker | AUTO-IMP-SUP | Implements issues or fixes failing PRs. Full lifecycle from code to merge. |
 | pr-reviewer | AUTO-REV-SUP | Reviews a single PR for quality, spec alignment, and correctness. |
-| pr-merge-worker | AUTO-PRMRG-SUP | Handles rebase operations for a single PR. |
+| pr-merge-worker | AUTO-PRMRG-SUP | Handles rebase operations for a single PR. **Blocking subagent** (not async — no `[AUTO-PRMRG-<N>]` sessions exist). |
 | uat-test-worker | AUTO-UAT-SUP | Tests one feature area against the specification. |
 | bug-hunt-worker | AUTO-BUG-SUP | Deep code analysis on one module for hidden bugs. |
 | test-infra-worker | AUTO-INF-SUP | Analyzes one aspect of testing infrastructure. |
@@ -2,7 +2,8 @@
 description: >
  PR merge supervisor. Continuously monitors open PRs for merge readiness,
  verifies all seven merge criteria, handles pre-merge rebasing, and performs
-  verified merges. Dispatches workers for rebase operations.
+  verified merges. Calls pr-merge-worker as a blocking subagent for rebase
+  operations (no async worker sessions).
 mode: subagent
 hidden: true
 temperature: 0.1
@@ -19,12 +20,12 @@ permission:
    "*api/v1/orgs/*/labels*": deny
    "*api/v1/repos/*/labels*": deny
    "*https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels*": deny
-    # CRITICAL: No direct curl to localhost:4096 - must use async-agent-manager
+    # CRITICAL: No direct HTTP calls to the OpenCode server
    "curl*localhost:4096*": deny
    "curl*127.0.0.1:4096*": deny
  task:
    "*": deny
-    "async-agent-manager": allow
+    "pr-merge-worker": allow
    "automation-tracking-manager": allow
    "repo-isolator": allow
    "git-commit-helper": allow
@@ -53,13 +54,12 @@ permission:

 # PR Merge Supervisor

-You are a supervisor that monitors open PRs for merge readiness, verifies all criteria are met, and merges them. You dispatch workers for rebase operations when PRs are behind the base branch.
+You are a supervisor that monitors open PRs for merge readiness, verifies all criteria are met, and merges them. You call `pr-merge-worker` as a **blocking subagent** for rebase operations when PRs are behind the base branch. Unlike other supervisors, you do NOT use async-agent-manager to dispatch workers — you invoke the worker directly via the Task tool and block until it completes.

 ## What You Receive

 Your prompt from the product-builder includes:
 - Repository owner/name, Forgejo PAT, git identity
- Worker count (1)
 - A customized briefing containing CONTRIBUTING.md merge requirements and open announcements

 ## Merge Verification is Mandatory
@@ -71,9 +71,9 @@ PROCEDURE MERGE_PR(pr_number):
  -- Step 1: Check staleness
  pr := forgejo_get_pull_request_by_index(pr_number)
  IF pr.merge_base != pr.base.sha:
-    -- Branch is behind; dispatch rebase worker, skip merge this cycle
-    DISPATCH_REBASE_WORKER(pr_number)
-    RETURN "rebase_needed"
+    -- Branch is behind; call worker as blocking subagent to rebase, wait for CI, and merge
+    CALL_BLOCKING_WORKER(pr_number)  -- blocks until worker finishes
+    RETURN "rebase_handled"

  -- Step 2: Attempt merge
  forgejo_merge_pull_request(pr_number, style="rebase")
@@ -91,7 +91,7 @@ PROCEDURE MERGE_PR(pr_number):

 ## Seven Merge Criteria

-Before merging any PR, verify ALL of these:
+Before merging any PR, the following must be true:

 1. **Approval** — at least one approving review (formal review, approval comment, or self-approval)
 2. **CI passing** — all workflow runs on the latest commit are successful
@@ -102,32 +102,18 @@ Before merging any PR, verify ALL of these:

 ## Workers

-You dispatch `pr-merge-worker` agents for rebase operations when PRs are behind the base branch.
-
-### Worker Tags
-
-Workers use: `[AUTO-PRMRG-<N>]` where N is the PR number being rebased.
-
-### Rebase Protocol
-
-When a PR is behind, dispatch a worker (`pr-merge-worker`) via `async-agent-manager` to:
-1. Clone the repo using `repo-isolator`
-2. Rebase the branch onto master
-3. Resolve any conflicts that arise by reviewing the recent git history and using that to fix the conflicts
-3. Force-push with lease using `git-commit-helper`
-
-After a rebase, do NOT attempt to merge immediately — wait for CI to run on the rebased commits. Merge on the next cycle after CI passes.
+You call `pr-merge-worker` as a **blocking subagent** (via the Task tool) for rebase operations when PRs are behind the base branch. The worker runs synchronously within your process — you block until it finishes, then continue your cycle. There are no async sessions for workers; this is intentional to simplify coordination since only one rebase happens at a time.

 ## Main Loop

 Poll every 5 minutes using `bash("sleep 300", timeout=360000)`.

 Each cycle:
-1. List all open PRs.
-2. For each PR, check the listed merge criteria.  Prioritize by: milestone order (lowest first), then priority label, then MoSCow label, then issue number.
-3. Merge (using fast-forward) any PR that passes all of the criteria (with mandatory post-merge verification).
-4. Dispatch rebase workers for PRs that are behind.
-5. Update linked issues to `State/Completed` after verified merges.
+1. List all open PRs. (the forgejo task paginates so be sure to go through every page)
+2. for each PR that is marked as mergable attempt to do a fast-forward merge, as always do the mandatory post-merge verification.
+2. For all other PR (including those you attempted to merge but were unsuccessful), filter those that having passing CI quality gates/tests.
+4. For each PR that needs rebasing (prioritized by: milestone order lowest first, then priority label, then MoSCoW label, then issue number), call `pr-merge-worker` as a **blocking subagent** via the Task tool. Pass the PR number, repository info, and credentials in the prompt. The worker will rebase onto the latest master, resolve conflicts, wait for CI, and attempt a fast-forward merge. You block until the worker finishes before processing the next PR.
+5. For any PR that were successfully merged update linked issues, and the PR itself, to `State/Completed` via `forgejo-label-manager`.

 ## Tracking

@@ -138,10 +124,9 @@ Each cycle:
 ## Rules

 1. **Always verify merges.** Never trust the merge API response alone.
-2. **Never merge without all the listed criteria.** No exceptions.
-3. **Never merge immediately after rebase.** Wait for CI.
-4. **Pass credentials down.** Every worker prompt must include repository info, Forgejo PAT, and git identity. Workers never read environment variables.
-5. **Bot signature on all Forgejo content:**
+2. **Never merge immediately after rebase.** Wait for CI to complete quality gates/tests first.
+3. **Pass credentials down.** Every worker prompt must include repository info, Forgejo PAT, and git identity. Workers never read environment variables.
+4. **Bot signature on all Forgejo content:**
 ```
 ---
 **Automated by CleverAgents Bot**
@@ -1,7 +1,8 @@
 ---
 description: >
  PR merge worker. Performs a single rebase operation on a PR branch that is
-  behind the base branch, then exits. Dispatched by the PR merge supervisor.
+  behind the base branch, then exits. Called as a blocking subagent by the
+  PR merge supervisor (not launched as an async session).
 mode: subagent
 hidden: true
 temperature: 0.1
@@ -14,6 +15,7 @@ permission:
    "git *": allow
    "mkdir *": allow
    "rm -rf *": allow
+    "sleep *": allow
    # Block ALL commands that could hit the label creation endpoints
    "*api/v1/orgs/*/labels*": deny
    "*api/v1/repos/*/labels*": deny
@@ -40,19 +42,19 @@ permission:

 # PR Merge Worker

-You perform a single rebase operation on a PR branch, resolve any conflicts, and then exit. You do not loop or sleep.
+You perform a single rebase operation on a PR branch, resolve any conflicts, and then exit. You are called as a **blocking subagent** by `pr-merge-pool-supervisor` via the Task tool — you are NOT an async session. The supervisor blocks until you finish and return your results.

-## Task
+## Procedure

 Your prompt tells you which PR to rebase. You must:
-
-1. Create an isolated clone using the `repo-isolator` subagent.
-2. Check out the PR's branch.
-3. Rebase it onto the base branch (usually `master`).
-4. If there are any conflict then review recent history of master and the current branch, and use that knowledge to resolve the conflicts.
-5. Force-push with lease using the `git-commit-helper` subagent.
-6. Clean up the clone.
-7. Exit and report any relevant details.
+1. Create an isolated clone using the `repo-isolator` subagent ensuring you pass it the branch used by the PR.
+2. Rebase it onto the base branch (usually `master`).
+3. Resolve any conflicts that arise by reviewing the recent git history and using that to fix the conflicts
+4. Force-push with lease using `git-commit-helper`
+5. Clean up the clone.
+6. Poll every minute using `bash("sleep 60", timeout=360000)` to sleep, checking each time if the CI Quality Gates have finished
+7. Once the quality gates finish then merge with a fast-forward if the PR is mergable, if not then skip the merge.
+8. Report back with any relevant details.

 ## Rules

@@ -208,6 +208,10 @@ Every 5th cycle, perform a deeper check on each supervisor:

 Also every 5th cycle, check workers for each supervisor. Workers are short-lived and completing is normal — what matters is whether the supervisor is keeping its pool filled.

+**Exception — PR Merge Pool (`AUTO-PRMRG-SUP`)**: This supervisor calls `pr-merge-worker` as a **blocking subagent** (not async). There are NO `[AUTO-PRMRG-<N>]` async sessions to search for. Skip the worker health check for this supervisor entirely — its health is determined solely by whether the supervisor session itself is active and responsive during the Deep Inspection check. When the supervisor is busy calling its worker, it will appear as a normal busy session.
+
+For all other supervisors:
+
 1. Search for sessions matching the supervisor's worker tag pattern.
 2. Count the active (busy) workers. A worker whose session has completed has finished its task — that's expected behavior, not an error.
 3. Compare the number of active workers against the expected count for that supervisor. If the supervisor has been running for more than 5 minutes but consistently has fewer active workers than expected, investigate. Read the supervisor's messages to understand whether it's waiting for work to become available (normal) or has stopped dispatching (broken).
@@ -98,6 +98,7 @@ Each cycle, check these areas:
 - Read tracking issues from all supervisors
 - Check estimated cycle intervals — if a supervisor's tracking issue age exceeds 2x its interval, it may be frozen
 - Cross-reference active sessions with expected supervisors
+- **Exception — PR Merge Pool (`AUTO-PRMRG-SUP`)**: This supervisor calls `pr-merge-worker` as a blocking subagent (not async). There are NO `[AUTO-PRMRG-<N>]` async worker sessions. Do not flag the absence of worker sessions as a problem — the supervisor's health is determined solely by its own session activity and tracking issue freshness. When the supervisor is busy executing a blocking worker call, it will appear as a normal busy session.

 ### Dependency and Label Integrity
 - Issue dependencies should have correct direction (child BLOCKS parent)
@@ -145,21 +145,24 @@ The system allocates parallel workers according to a tiered formula derived from
 | **Full** (N) | `N` | Implementation Pool | Closes issues; maximum throughput needed |
 | **Half** (N/2) | `max(1, N // 2)` | PR Review Pool | Must keep pace with implementation but not 1:1 |
 | **Quarter** (N/4) | `max(1, N // 4)` | UAT Test, Bug Hunt, Test Infra | Discovery agents; capping prevents scope explosion |
-| **Single** (1) | `1` | All other supervisors (PR Merge + 11 singletons) | Strategic work requiring single-threaded coherence; one worker at a time |
+| **Single** (1) | `1` | 11 singleton supervisors (Architecture through Watchdog, excluding PR Merge) | Strategic work requiring single-threaded coherence; one async worker at a time |
+| **Blocking** (0 async) | `0` | PR Merge Pool | Calls `pr-merge-worker` as a blocking subagent via the Task tool; no async worker sessions (see Section 8.3) |

-!!! note "All Supervisors Dispatch Workers"
+!!! note "Worker Dispatch Model"

-    Every supervisor in the system dispatches workers, including single-worker supervisors. Workers are short-lived — they perform a discrete task (implement an issue, review a PR, scan a module, update a document) and then exit. The supervisor's job is to identify work, dispatch workers, and keep its pool full by launching new workers as old ones complete. This separation ensures crash isolation (a failed worker doesn't take down the supervisor), fresh context per task, and independent health monitoring by both the supervisor and the Product Builder.
+    Almost every supervisor in the system dispatches workers as async sessions via the Async Agent Manager. Workers are short-lived — they perform a discrete task (implement an issue, review a PR, scan a module, update a document) and then exit. The supervisor's job is to identify work, dispatch workers, and keep its pool full by launching new workers as old ones complete. This separation ensures crash isolation (a failed worker doesn't take down the supervisor), fresh context per task, and independent health monitoring by both the supervisor and the Product Builder.

-**Capacity examples** (concurrent worker sessions, not counting the 18 supervisor sessions themselves):
+    **Exception — PR Merge Pool**: The PR Merge Pool Supervisor calls `pr-merge-worker` as a **blocking subagent** (via the Task tool) rather than dispatching it as an async session. The supervisor blocks until the worker finishes, then continues its cycle. This means there are no `[AUTO-PRMRG-<N>]` async sessions. The Product Builder and System Watchdog must skip worker health checks for this supervisor — its health is determined solely by whether the supervisor session itself (`[AUTO-PRMRG-SUP]`) is active. When the supervisor is busy calling its worker, it appears as a normal busy session.

-| N | Implementation | PR Review | UAT | Bug Hunt | Test Infra | Single-worker (×12) | Total Workers |
-|---|---------------|-----------|-----|----------|------------|---------------------|---------------|
-| 4 | 4 | 2 | 1 | 1 | 1 | 12 | 21 |
-| 8 | 8 | 4 | 2 | 2 | 2 | 12 | 30 |
-| 16 | 16 | 8 | 4 | 4 | 4 | 12 | 48 |
+**Capacity examples** (concurrent async worker sessions, not counting the 18 supervisor sessions themselves):

-Total concurrent sessions = 18 supervisors + worker count from the table above. For N=4: 18 + 22 = 40 sessions.
+| N | Implementation | PR Review | UAT | Bug Hunt | Test Infra | Single-worker (×11) | PR Merge (blocking) | Total Async Workers |
+|---|---------------|-----------|-----|----------|------------|---------------------|---------------------|---------------------|
+| 4 | 4 | 2 | 1 | 1 | 1 | 11 | 0 | 20 |
+| 8 | 8 | 4 | 2 | 2 | 2 | 11 | 0 | 29 |
+| 16 | 16 | 8 | 4 | 4 | 4 | 11 | 0 | 47 |
+
+Total concurrent sessions = 18 supervisors + async worker count from the table above. For N=4: 18 + 20 = 38 sessions. (PR Merge worker runs inside the supervisor's session, not as a separate session.)

 ---

@@ -360,7 +363,7 @@ The registered tag prefixes are:
 | `AUTO-UAT-<N>` | uat-test-worker | UAT test worker |
 | `AUTO-BUG-<N>` | bug-hunt-worker | Bug hunt worker |
 | `AUTO-INF-<N>` | test-infra-worker | Test infra worker |
-| `AUTO-PRMRG-<N>` | pr-merge-worker | PR merge/rebase worker |
+| ~~`AUTO-PRMRG-<N>`~~ | ~~pr-merge-worker~~ | ~~PR merge/rebase worker~~ *(Removed — pr-merge-worker is now called as a blocking subagent, not an async session. See Section 8.3.)* |
 | `AUTO-ARCH-<N>` | architecture-worker | Architecture spec worker |
 | `AUTO-EPIC-<N>` | epic-planning-worker | Epic planning worker |
 | `AUTO-HUMAN-<N>` | human-liaison-worker | Human liaison worker |
@@ -391,7 +394,7 @@ Every fifth fast cycle, perform deeper checks on each supervisor and its workers

 1. **Supervisor inspection**: Read the last several messages from each supervisor's session, including the agent's internal thinking. Evaluate whether the supervisor is making progress and behaving correctly. Look for repeated errors, no work activity for fifteen or more minutes, looping behavior, or the agent doing work outside its responsibilities. If the supervisor appears stuck or misbehaving, stop it and launch a fresh one.

-2. **Worker health check**: For each pool supervisor, search for sessions matching the supervisor's worker tag pattern (see Section 4.2.1). Count active workers and compare against the expected count for that supervisor's tier. If a pool supervisor has been running for more than five minutes but has zero workers, investigate by reading the supervisor's messages. Check individual worker sessions for problems (errored, stuck, completed but not cleaned up).
+2. **Worker health check**: For each pool supervisor, search for sessions matching the supervisor's worker tag pattern (see Section 4.2.1). Count active workers and compare against the expected count for that supervisor's tier. If a pool supervisor has been running for more than five minutes but has zero workers, investigate by reading the supervisor's messages. Check individual worker sessions for problems (errored, stuck, completed but not cleaned up). **Exception — PR Merge Pool (`AUTO-PRMRG-SUP`)**: This supervisor calls `pr-merge-worker` as a blocking subagent (not async). There are no `[AUTO-PRMRG-<N>]` async worker sessions to search for. Skip the worker health check for this supervisor entirely — its health is determined solely by whether the supervisor session itself is active.

 #### 4.3.3 Hourly Status Cycle (~60 fast cycles)

@@ -708,7 +711,7 @@ For the remaining seven supervisors (Architecture, Epic Planning, Agent Evolutio
 - `AUTO-PROD-BLDR` and `AUTO-SESSION` exist only as tracking prefixes (the Product Builder and Session Persister are not launched via the Async Agent Manager).
 - `AUTO-ONEOFF` exists only as a session tag (one-off dispatched agents don't create tracking issues).

- Worker-level session tags (e.g., `AUTO-IMP-ISSUE-<N>`, `AUTO-IMP-PR-<N>`, `AUTO-REV-<N>`, `AUTO-UAT-<N>`, `AUTO-BUG-<N>`, `AUTO-INF-<N>`, and all other `AUTO-*-<N>` worker patterns) have no tracking prefix counterpart except `AUTO-IMP-WRK`. Implementation workers use `AUTO-IMP-ISSUE-<N>` when implementing a new issue and `AUTO-IMP-PR-<N>` when fixing an existing PR. All other workers follow the pattern `AUTO-{SUPERVISOR_PREFIX}-<N>`.
+- Worker-level session tags (e.g., `AUTO-IMP-ISSUE-<N>`, `AUTO-IMP-PR-<N>`, `AUTO-REV-<N>`, `AUTO-UAT-<N>`, `AUTO-BUG-<N>`, `AUTO-INF-<N>`, and all other `AUTO-*-<N>` worker patterns) have no tracking prefix counterpart except `AUTO-IMP-WRK`. Implementation workers use `AUTO-IMP-ISSUE-<N>` when implementing a new issue and `AUTO-IMP-PR-<N>` when fixing an existing PR. All other workers follow the pattern `AUTO-{SUPERVISOR_PREFIX}-<N>`. **Exception**: `AUTO-PRMRG-<N>` no longer exists as a session tag — `pr-merge-worker` is called as a blocking subagent by the PR Merge Pool Supervisor (see Section 8.3).

 ### 5.6 Tracking Issue Body Template

@@ -1732,7 +1735,7 @@ Every third cycle creates a custom mix for serendipitous discovery.

 #### 8.3.1 Purpose

-A singleton supervisor that continuously monitors pull requests for merge readiness. It verifies all merge criteria are met, automatically rebases PRs without conflicts, and merges using fast-forward when possible.
+A singleton supervisor that continuously monitors pull requests for merge readiness. It verifies all merge criteria are met, automatically rebases PRs without conflicts, and merges using fast-forward when possible. Unlike other supervisors, the PR Merge Pool calls `pr-merge-worker` as a **blocking subagent** (via the Task tool) rather than dispatching it as an async session. The supervisor blocks until the worker finishes, then continues its cycle. This means there are no `[AUTO-PRMRG-<N>]` async sessions — the Product Builder and System Watchdog must skip worker health checks for this supervisor.

 #### 8.3.2 Merge Criteria

@@ -1776,17 +1779,21 @@ This verification protocol is enforced in three locations:

 #### 8.3.5 Pre-Merge Rebase Protocol

-When a branch is behind the base branch (`merge_base != base.sha`), the PR Merge supervisor handles it based on whether conflicts exist:
+When a branch is behind the base branch (`merge_base != base.sha`), the PR Merge supervisor calls `pr-merge-worker` as a **blocking subagent** via the Task tool. The worker handles the rebase operation based on whether conflicts exist:

 | Condition | Action |
 |-----------|--------|
-| Behind, no conflicts | Automatic rebase via clone → `git rebase` → `--force-with-lease` push. Post rebase comment. Wait for CI. Merge on next cycle. |
-| Behind, with conflicts | Post comment requesting manual rebase. Skip PR. Merge automatically when conflicts are resolved and CI passes. |
-| Up-to-date | Proceed directly to merge. |
+| Behind, no conflicts | Worker creates an isolated clone via `repo-isolator`, rebases via `git rebase`, force-pushes with lease via `git-commit-helper`, cleans up the clone, waits for CI to pass, then attempts a fast-forward merge if the PR is mergeable. |
+| Behind, with conflicts | Worker resolves conflicts by reviewing recent git history, or posts comment requesting manual rebase if unresolvable. |
+| Up-to-date | Supervisor proceeds directly to merge (no worker needed). |

-**Critical rule**: After a successful rebase, the supervisor must NOT attempt to merge immediately. The rebased commits need CI to run first. The merge happens on the next polling cycle after CI passes.
+**Blocking call semantics**: The supervisor blocks while the worker runs — including during the worker's CI polling wait. Only after the worker finishes does the supervisor continue to the next PR. This is intentional since only one rebase operation happens at a time.

-**Subagents**: `ref-reader`, `pr-status-analyzer`, `automation-tracking-manager`, `repo-isolator`, `git-commit-helper`
+**Critical rule**: After a successful rebase, the worker waits for CI to complete before attempting merge. The worker polls every 60 seconds for CI completion and only merges with fast-forward if CI passes and the PR is mergeable.
+
+**Supervisor subagents**: `automation-tracking-manager`, `repo-isolator`, `git-commit-helper`, `pr-merge-worker` (blocking)
+
+**Worker subagents** (used by `pr-merge-worker`): `repo-isolator`, `git-commit-helper`

 #### 8.3.6 PR Merge Pool Supervisor Responsibilities

@@ -3685,13 +3692,15 @@ Unlike other pool supervisors which dispatch workers via the Async Agent Manager

 ### 21.2 PR Merge Pool Supervisor: Complete Subagent List

-**Subagents**: `ref-reader`, `pr-status-analyzer`, `automation-tracking-manager`, `repo-isolator`, `git-commit-helper`
+**Subagents**: `pr-merge-worker` (blocking), `automation-tracking-manager`, `repo-isolator`, `git-commit-helper`

-**Important**: `edit: deny` -- the PR Merge supervisor does NOT have file edit permissions. Rebase operations are performed exclusively via bash git commands within an isolated clone (created by `repo-isolator`), not via the Edit tool.
+**Worker dispatch model**: Unlike all other supervisors, the PR Merge Pool Supervisor calls `pr-merge-worker` as a **blocking subagent** via the Task tool. It does NOT use `async-agent-manager` to dispatch workers. The supervisor blocks until the worker finishes, then continues its cycle. There are no `[AUTO-PRMRG-<N>]` async sessions. The `async-agent-manager` is not in the supervisor's task permissions.
+
+**Important**: `edit: deny` -- the PR Merge supervisor does NOT have file edit permissions. Rebase operations are delegated to the `pr-merge-worker` subagent, which creates an isolated clone via `repo-isolator` and performs git operations within it.

 **Branch Deletion Policy**: `delete_branch_after_merge` is set to `False` (not True as the merge safety default suggests). The rationale is to let humans decide when to delete branches.

-**Rebase Protocol**: When a PR has no merge conflicts but is behind master, the supervisor: (1) clones via repo-isolator, (2) fetches latest, (3) rebases, (4) force-pushes with lease, (5) cleans up clone, (6) posts comment.
+**Rebase Protocol**: When a PR has no merge conflicts but is behind master, the supervisor calls `pr-merge-worker` which: (1) creates an isolated clone via repo-isolator, (2) rebases onto the base branch, (3) resolves conflicts by reviewing recent git history, (4) force-pushes with lease via git-commit-helper, (5) cleans up the clone, (6) polls for CI completion, (7) merges with fast-forward if the PR is mergeable.

 ### 21.3 UAT Test Pool Supervisor: Complete Subagent List

@@ -4711,7 +4720,7 @@ The Branch Setup agent creates or checks out branches with a strict rebase-only
 | Layer | Agent | Role | Specific Actions |
 |-------|-------|------|-----------------|
 | **1 (Branch Setup)** | [Branch Setup](#2123-branch-setup-rebase-only-policy) | Creates or checks out branches with strict rebase-only policy. Supports dependent branch stacking via `base_branch` parameter. If branch exists: fetches, checkouts, rebases onto base. If not: creates from base. Rebase conflicts are NOT auto-resolved — aborts and reports. (Section [21.23](#2123-branch-setup-rebase-only-policy)) | Branch creation, checkout, rebase-only enforcement |
-| **2 (Pre-merge Rebase)** | [PR Merge Pool](#83-pr-merge-pool-supervisor) | Pre-merge staleness check: compares `merge_base` vs `base.sha`. If behind without conflicts: clones via repo-isolator, fetches latest, rebases, force-pushes with lease. Waits for CI (does NOT merge immediately). If behind with conflicts: posts comment requesting manual rebase. (Section [8.3.5](#835-pre-merge-rebase-protocol)) | Pre-merge rebase, conflict detection |
+| **2 (Pre-merge Rebase)** | [PR Merge Pool](#83-pr-merge-pool-supervisor) | Pre-merge staleness check: compares `merge_base` vs `base.sha`. If behind: calls `pr-merge-worker` as a **blocking subagent** which clones via repo-isolator, rebases, force-pushes with lease, waits for CI, and attempts fast-forward merge. With conflicts: worker resolves by reviewing git history or posts comment. (Section [8.3.5](#835-pre-merge-rebase-protocol)) | Pre-merge rebase via blocking worker, conflict detection |
 | **3 (Worker Rebase)** | [Implementation Worker](#101-implementation-worker) | Before committing: rebases branch onto latest master (stash, fetch, rebase, pop). Resolves simple conflicts automatically (imports, whitespace, version numbers). Falls back to no-rebase if auto-resolution fails. Before merge: compares `merge_base` vs `base.sha`, rebases if behind, waits 120s for CI. (Section [10.1](#101-implementation-worker)) | Pre-commit rebase, pre-merge rebase |

 ---
@@ -6875,6 +6884,7 @@ The system uses five distinct redundancy patterns:
 | 2026-04-10 | 1.21.0 | Twenty-fourth pass (label deny and permission consistency audit): Expanded Section 6.19 from Automation-Tracking-Manager-specific to universal label application delegation rule documenting all 77 agents with deny + 2 intentional exceptions (forgejo-label-manager, issue-state-updater); **fixed 6 agent definition bugs**: pr-editor.md, pr-manager.md, pr-merge-pool-supervisor.md, async-agent-manager.md (all 4 missing `forgejo_add_issue_labels: deny` — could bypass label delegation), forgejo-signature-appender.md (missing deny AND broken YAML `permission: {}` creating disconnected forgejo block); verified 41 edit:deny agents match spec claim exactly, 3 webfetch:allow agents match spec claim exactly |
 | 2026-04-10 | 1.22.0 | Twenty-fifth pass (directory layout, bash permissions, subsystem verification): Added Section 2.4 (Directory Layout) documenting `.opencode/` structure including agents/, shared/, config/, scripts/, deprecated stubs; **fixed 1 agent definition bug**: forgejo-signature-appender.md (missing `bash: "*": deny` and `edit: deny` — the only active agent without any bash restriction, could run arbitrary commands despite being a text-formatting-only agent); verified 3-Tier Approval Detection (Section 6.17) matches pr-merge-pool-supervisor implementation; verified Mandatory Merge Verification Protocol (Section 8.3.4) matches shared/merge_safety.md; confirmed zero remaining stale names, stale labels, or stale session prefixes across all agent files |
 | 2026-04-10 | 1.23.0 | Twenty-sixth pass (deep automation tracking audit): Major rewrite of Section 5.2 (Status Issues) with one-at-a-time invariant, close-ALL-then-create protocol, and explicit "even from previous sessions" language; new Section 5.3.1 (Announcement Issue Lifecycle) with mandatory self-review every 3 cycles; new Section 5.3.2 (Tracking Issue Consumption Protocol) with per-agent triage table, read depth levels, and priority-based filtering; **fixed 4 agent definitions**: automation-tracking-manager.md (strengthened CREATE_TRACKING_ISSUE to specify close-ALL-then-create invariant), backlog-grooming-pool-supervisor.md (added READ_ANNOUNCEMENTS from watchdog/liaison/owner + REVIEW_OWN_ANNOUNCEMENTS every 3 cycles), pr-review-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog/liaison + REVIEW_OWN_ANNOUNCEMENTS), agent-evolution-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog + REVIEW_OWN_ANNOUNCEMENTS with 24h stale threshold); updated shared/tracking_discovery_guide.md with mandatory announcement review and consumption protocols |
+| 2026-04-13 | 2.13.0 | Fourteenth pass (PR Merge blocking subagent migration): Changed `pr-merge-pool-supervisor` from async worker dispatch to **blocking subagent** model — it now calls `pr-merge-worker` via the Task tool and blocks until it finishes, instead of dispatching it as an async session via `async-agent-manager`. Updated 8 spec sections: Section 1.3 (added Blocking tier to worker allocation table, updated capacity examples to show ×11 singleton workers instead of ×12, adjusted session totals); Section 4.2.1 (struck through `AUTO-PRMRG-<N>` entry in session tag table since no async worker sessions exist); Section 4.3.2 (added PR Merge exception to worker health check); Section 5.5.1 (added exception note for `AUTO-PRMRG-<N>`); Section 8.3.1 (documented blocking subagent model in purpose); Section 8.3.5 (rewrote pre-merge rebase protocol to describe worker-based rebase with CI polling); Section 21.2 (updated subagent list: replaced `async-agent-manager` with `pr-merge-worker`, documented dispatch model difference); Section 22.30 R-30 (updated rebase layer 2 to reflect blocking worker). **Updated 6 agent definition files** in prior commits: pr-merge-pool-supervisor.md (replaced `async-agent-manager: allow` with `pr-merge-worker: allow` in task permissions, rewrote all dispatch language to blocking subagent), pr-merge-worker.md (updated description and intro), agent-type-info.md (updated PR Merge Pool entry and worker table), agent-prefix-info.md (changed worker tag pattern to "none", added exception paragraph), product-builder.md (added worker health check exception for PR Merge), system-watchdog-pool-supervisor.md (added supervisor health exception for PR Merge). |
 | 2026-04-12 | 2.12.0 | Thirteenth pass: Reader experience and navigation improvements. Added 6th foundational principle to Section 1.1 ("Defense-in-Depth Redundancy") with cross-reference to Section 22. Added "How to Read This Section" tip box at top of Section 22 with 5 navigation paths (by responsibility, by agent, by category, by redundancy, by scale). Added introductory paragraphs to all 8 categories explaining scope, scale, and significance: A (50 responsibilities, core value chain), B (deepest redundancy — quadruple), C (Groomer + Watchdog strongest redundancy zone), D (bidirectional spec flow), E (invisible plumbing), F (2-minute human response), G (long-timescale governance), H (triple enforcement of standards). |
 | 2026-04-12 | 2.11.0 | Twelfth pass: Consistency and quality audit. Fixed 3 R-items (R-41, R-77, R-79) missing from agent back-reference tables by adding them to the Universal Supervisor Responsibilities table (Section 7.9). Expanded 2 thin R-item detail sections: R-67 (Product Completion) expanded from 12 to 20 lines with full 10-point verification table showing check methods and failure outputs; R-88 (UAT Feature Retest) expanded from 12 to 17 lines with 5-step file→area mapping process. Verified: all 144 R-items have detail sections, all 144 are in category index tables, all referenced agents have back-reference tables. Zero broken cross-references. |
 | 2026-04-12 | 2.10.0 | Eleventh pass: Added Section 7.9 (Universal Supervisor Responsibilities) — a shared baseline table of 13 responsibilities that ALL 18 supervisors inherit (R-141 Startup Sequence, R-142 State Recovery, R-20 Tracking, R-143 Dual Cleanup, R-133 Announcement Consumption, R-43 Announcement Lifecycle, R-44 Context Management, R-113 Resource Cleanup, R-114 Credential Validation, R-63 Bot Signature, R-78 Logging, R-127 No Label Creation, R-134 No Internet). Added "*In addition to universal supervisor responsibilities*" cross-reference notes to all 18 supervisor responsibility tables (Sections 8.1.7, 8.2.4, 8.3.6, 8.4.3, 8.5.4, 8.6.4, 8.7.4, 9.1.1, 9.2.1, 9.3.1, 9.4.1, 9.5.1, 9.6.1, 9.7.1, 9.8.1, 9.9.1, 9.10.1, 9.11.4). Expanded 4 thin agent tables: PR Fix Pool (+R-27, R-112), Documentation (+R-57, R-61), Timeline (+R-57), Agent Evolution (+R-57, R-135). Each supervisor's effective responsibility count is now its specific entries PLUS 13 universal = true total. |