feat: implement auto-merge for approved PRs and update workflow documentation

docs/ARCHITECTURE.md

@@ -427,7 +427,7 @@ sequenceDiagram
     WF-->>DEV: { announcement: "👀 DEVELOPER REVIEW #42" }
 ```
 
-The issue sits in "In Review" until the heartbeat's **review pass** detects the PR has been merged, then automatically transitions to "To Test".
+The issue sits in "In Review" until the heartbeat's **review pass** detects the PR has been approved. DevClaw then auto-merges the PR and transitions to "To Test". If the merge fails (e.g. conflicts), the issue moves to "To Improve" where a developer is auto-dispatched to resolve conflicts.
 
 ### Phase 6: TESTER pickup
 
@@ -586,7 +586,7 @@ Every piece of data and where it lives:
 │  design_task    → architect dispatch                            │
 │                                                                 │
 │  Bootstrap hook → injects role instructions into worker sessions│
-│  Review pass    → polls PR status, auto-advances In Review      │
+│  Review pass    → polls PR status, auto-merges approved PRs     │
 │  Config loader  → three-layer merge + Zod validation            │
 └─────────────────────────────────────────────────────────────────┘
         ↕ atomic file I/O          ↕ OpenClaw CLI (plugin shells out)
@@ -662,7 +662,7 @@ graph LR
         SD[Session dispatch<br/>create + send via CLI]
         AC[Scheduling<br/>tick queue after work_finish]
         RI[Role instructions<br/>injected via bootstrap hook]
-        RV[Review polling<br/>PR status → auto-advance]
+        RV[Review polling<br/>PR approved → auto-merge]
         A[Audit logging]
         Z[Zombie cleanup]
         CFG[Config validation<br/>Zod + integrity checks]

docs/CONFIGURATION.md

@@ -153,11 +153,12 @@ workflow:
       type: review
       label: In Review
       color: "#c5def5"
-      check: prMerged
+      check: prApproved
       on:
         APPROVED:
           target: toTest
-          actions: [gitPull]
+          actions: [mergePr, gitPull]
+        MERGE_FAILED: toImprove
         BLOCKED: refining
     done:
       type: terminal
@@ -188,7 +189,7 @@ workflow:
 | `queue` | Waiting for pickup. Must have a `role`. Has `priority` for ordering. |
 | `active` | Worker is currently working on it. Must have a `role`. |
 | `hold` | Paused, awaiting human decision. |
-| `review` | Awaiting external check (PR merged/approved). Has `check` field. |
+| `review` | Awaiting external check (PR approved/merged). Has `check` field. Heartbeat polls and auto-transitions. |
 | `terminal` | Completed. No outgoing transitions. |
 
 **Built-in actions:**
@@ -197,6 +198,7 @@ workflow:
 |---|---|
 | `gitPull` | Pull latest from the base branch |
 | `detectPr` | Auto-detect PR URL from the issue |
+| `mergePr` | Merge the PR associated with the issue. Critical in review states (aborts on failure). |
 | `closeIssue` | Close the issue |
 | `reopenIssue` | Reopen the issue |
 

docs/MANAGEMENT.md

@@ -48,8 +48,8 @@ DevClaw enforces a configurable but consistent lifecycle for every task. The def
 
 ```
 Planning → To Do → Doing → To Test → Testing → Done
-                         ↘ In Review → (PR merged) → To Test
-                                    ↘ To Improve → Doing (fix cycle)
+                         ↘ In Review → (PR approved → auto-merge) → To Test
+                                    ↘ To Improve → Doing (merge conflict / fix cycle)
                                     ↘ Refining → (human decision)
 ```
 

docs/ONBOARDING.md

@@ -266,7 +266,7 @@ Change which model powers each level in `workflow.yaml` — see [Configuration](
 | Session management | Plugin | Creates, reuses, and dispatches to sessions via CLI. Agent never touches session tools. |
 | Task completion | Plugin (`work_finish`) | Workers self-report. Scheduler dispatches next role. |
 | Role instructions | Plugin (bootstrap hook) | Injected into worker sessions via `agent:bootstrap` hook at session startup |
-| Review polling | Plugin (heartbeat) | Auto-advances "In Review" issues when PR is merged |
+| Review polling | Plugin (heartbeat) | Auto-merges and advances "In Review" issues when PR is approved |
 | Config validation | Plugin | Zod schemas validate `workflow.yaml` at load time |
 | Audit logging | Plugin | Automatic NDJSON append per tool call |
 | Zombie detection | Plugin | `health` checks active vs alive |

docs/ROADMAP.md

@@ -14,13 +14,13 @@ The issue lifecycle is now a configurable state machine defined in `workflow.yam
 
 ```
 Planning → To Do → Doing → To Test → Testing → Done
-                         ↘ In Review → (PR merged) → To Test
-                                    ↘ To Improve → Doing
+                         ↘ In Review → (PR approved → auto-merge) → To Test
+                                    ↘ To Improve → Doing (merge conflict / fix cycle)
                                     ↘ Refining → (human decision)
 To Design → Designing → Planning
 ```
 
-States have types (`queue`, `active`, `hold`, `review`, `terminal`), transitions with actions (`gitPull`, `detectPr`, `closeIssue`, `reopenIssue`), and review checks (`prMerged`, `prApproved`).
+States have types (`queue`, `active`, `hold`, `review`, `terminal`), transitions with actions (`gitPull`, `detectPr`, `mergePr`, `closeIssue`, `reopenIssue`), and review checks (`prMerged`, `prApproved`).
 
 ### Three-Layer Configuration
 
@@ -42,7 +42,7 @@ Worker sessions receive role-specific instructions via the `agent:bootstrap` hoo
 
 ### In Review State and PR Polling
 
-DEVELOPER can submit a PR for human review (`result: "review"`), which transitions the issue to `In Review`. The heartbeat's review pass polls PR status via `getPrStatus()` on the provider. When the PR is merged, the issue auto-transitions to `To Test` for TESTER pickup.
+DEVELOPER can submit a PR for human review (`result: "review"`), which transitions the issue to `In Review`. The heartbeat's review pass polls PR status via `getPrStatus()` on the provider. When the PR is approved, DevClaw auto-merges via `mergePr()` and transitions to `To Test` for TESTER pickup. If the merge fails (e.g. conflicts), the issue moves to `To Improve` where a developer is auto-dispatched to resolve conflicts.
 
 ### Architect Role
 

docs/TOOLS.md

@@ -244,7 +244,7 @@ Manual trigger for heartbeat: health fix + review polling + queue dispatch. Same
 **Three-pass sweep:**
 
 1. **Health pass** — Runs `checkWorkerHealth` per project per role. Auto-fixes zombies, stale workers, orphaned state.
-2. **Review pass** — Polls PR status for issues in "In Review" state. Transitions to "To Test" when PR is merged.
+2. **Review pass** — Polls PR status for issues in "In Review" state. Auto-merges and transitions to "To Test" when PR is approved. If merge fails (conflicts), transitions to "To Improve" for developer to fix.
 3. **Tick pass** — Calls `projectTick` per project. Fills free worker slots by priority (To Improve > To Test > To Do).
 
 **Execution guards:**