From 26cbacc27d02da38484b0f5205bb7dcd9a3c23c3 Mon Sep 17 00:00:00 2001
From: Scrum4Me Agent <30029041+madhura68@users.noreply.github.com>
Date: Sun, 3 May 2026 17:21:29 +0200
Subject: [PATCH] docs(ST-2): agent merge-policy sectie in AGENTS.md, CLAUDE.md
 en runbook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documenteert dat de agent na gh pr create altijd set_pbi_pr aanroept
en daarna stopt — nooit gh pr merge. Tabel in AGENTS.md en de
agent-batch flow in branch-and-commit.md bijgewerkt met de nieuwe stap.
Gate-foutmelding (open_pr_url) wordt aan gebruiker getoond, niet geretry'd.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 AGENTS.md                          | 24 +++++++++++++++++++++++-
 CLAUDE.md                          |  2 +-
 docs/runbooks/branch-and-commit.md |  5 ++++-
 3 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6d98658..6728bd8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,28 @@ For Claude Code specifically, CLAUDE.md is loaded automatically. Start there.
 |---|---|---|
 | Start run | `git checkout -b feat/<batch-slug>` | `gh pr create` |
 | Na elke taak | `git add -A && git commit -m "<type>(ST-XXX): <title>"` | `git push` |
-| Queue leeg | `git push -u origin <branch>` + `gh pr create` | — |
+| Queue leeg | `git push -u origin <branch>` + `gh pr create` | `gh pr merge` |
+| Na PR-create | `mcp__scrum4me__set_pbi_pr(pbi_id, pr_url)` → **STOP** | idem |
 
 Full details: [docs/runbooks/branch-and-commit.md § Agent-batch flow](./docs/runbooks/branch-and-commit.md)
+
+---
+
+## PR-merge & PBI-volgorde
+
+**De agent mergt nooit zelf een PR.** Na `gh pr create`:
+
+1. Roep direct `mcp__scrum4me__set_pbi_pr(pbi_id, pr_url)` aan zodat de gate weet dat deze PBI in review zit.
+2. Stop — wacht op handmatige merge door de PB-owner.
+3. Als de gebruiker daarna een nieuwe batch voor een andere PBI start en `enqueueClaudeJobsBatchAction` de error `open_pr_url` teruggeeft: toon de foutmelding aan de gebruiker en stop. Niet opnieuw proberen; de gebruiker moet eerst de open PR mergen.
+
+**Verboden:**
+- `gh pr merge` (ook niet met `--auto`, `--squash`, of `--rebase`)
+- Een PR sluiten en herforken om de gate te omzeilen
+- Opnieuw enqueuen na een gate-weigering zonder gebruikersbevestiging
+
+**PR-body** bevat minimaal:
+- Lijst van geïmplementeerde taak-titels (één per regel)
+- Link naar de PBI (`pbi_id` of de Scrum4Me-URL)
+
+---
diff --git a/CLAUDE.md b/CLAUDE.md
index 566c755..147ae34 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,7 +36,7 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ
 5. Verifieer: `npm run lint && npm test && npm run build`
 6. Commit per laag: `git add -A && git commit` — **geen** `git push` — zie [docs/runbooks/branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
 7. Herhaal stap 2–6 per story; branch blijft dezelfde
-8. Queue leeg → `git push -u origin <branch>` + `gh pr create`
+8. Queue leeg → `git push -u origin <branch>` + `gh pr create` (body: taak-titels + PBI-link) → roep `mcp__scrum4me__set_pbi_pr(pbi_id, pr_url)` aan → **STOP** (nooit `gh pr merge`)
 
 **Track B — manueel:**
 1. Lees taak in `docs/backlog/index.md`
diff --git a/docs/runbooks/branch-and-commit.md b/docs/runbooks/branch-and-commit.md
index 09bf0da..a5256b8 100644
--- a/docs/runbooks/branch-and-commit.md
+++ b/docs/runbooks/branch-and-commit.md
@@ -53,11 +53,14 @@ Wanneer de NAS-agent (`/opt/agent/`) een batch jobs uitvoert:
 |---|---|---|
 | Start run | `git checkout -b feat/<batch-slug>` lokaal | `gh pr create` |
 | Na elke taak | `git add -A && git commit -m "<type>(ST-XXX): <title>"` | `git push` |
-| Queue leeg | `git push -u origin <branch>` + `gh pr create` | — |
+| Queue leeg | `git push -u origin <branch>` + `gh pr create` | `gh pr merge` |
+| Na PR-create | `mcp__scrum4me__set_pbi_pr(pbi_id, pr_url)` → **STOP** | idem |
 
 - Alle commits accumuleren op dezelfde branch — lopende state blijft op disk tot de run klaar is.
 - Één PR per batch → één Vercel preview-deployment.
 - Single-task batch (1 job in queue): dezelfde flow — 1 commit → push + PR.
+- **De agent mergt nooit.** Na PR-create: `set_pbi_pr` aanroepen en stoppen. Wacht op handmatige merge door de PB-owner.
+- Als een volgende batch wordt geblokkeerd door de PBI-gate (open PR): toon de foutmelding (`open_pr_url`) aan de gebruiker. Niet opnieuw proberen.
 
 #### End-to-end verificatie: 1 batch = 1 Vercel-deploy