Merge pull request #108 from madhura68/feat/auto-pr-ui-and-docs

docs(PBI-36 ST-1220): auto-pr-flow runbook

docs/INDEX.md

@@ -110,6 +110,7 @@ Auto-generated on 2026-05-05 from front-matter and headings.
 | [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 |
 | [Realtime smoke-checklist — PBI / Story / Task](./realtime-smoke.md) | `realtime-smoke.md` | active | 2026-05-03 |
 | [Agent-flow: open issues & decision log](./runbooks/agent-flow-pitfalls.md) | `runbooks/agent-flow-pitfalls.md` | active | 2026-05-03 |
+| [Auto-PR flow: van story-DONE naar gemergde PR](./runbooks/auto-pr-flow.md) | `runbooks/auto-pr-flow.md` | active | 2026-05-06 |
 | [Branch, PR & Commit Strategy](./runbooks/branch-and-commit.md) | `runbooks/branch-and-commit.md` | active | 2026-05-03 |
 | [Deploy-controle: triggers, labels, path-filter](./runbooks/deploy-control.md) | `runbooks/deploy-control.md` | active | 2026-05-05 |
 | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 |

docs/runbooks/auto-pr-flow.md

@@ -0,0 +1,187 @@
+---
+title: "Auto-PR flow: van story-DONE naar gemergde PR"
+status: active
+audience: [contributor, ai-agent]
+language: nl
+last_updated: 2026-05-06
+when_to_read: "Vóór het aanzetten van auto_pr op een product, of bij debugging van uitblijvende PR's na agent-jobs."
+---
+
+# Auto-PR flow
+
+Wanneer een Scrum4Me-agent een TASK_IMPLEMENTATION-job afrondt, kan de
+hele keten **commit → push → PR → auto-merge → deploy** zonder
+handmatige actie verlopen — mits het bijbehorende product `auto_pr=true`
+heeft staan en de repo + tokens correct geconfigureerd zijn.
+
+---
+
+## Volledige keten
+
+```
+Agent voltooit task in /tmp/job-<id>
+        │
+        ▼
+Agent roept update_job_status('done', branch=feat/story-<n>)
+        │
+        ▼ MCP-tool prepareDoneUpdate (scrum4me-mcp/src/tools/update-job-status.ts)
+        │
+        ├─ pushBranchForJob → git push origin feat/story-<n>
+        │  (no-op als HEAD === origin/main → status DONE zonder pushed_at)
+        │
+        ├─ Job.pushed_at = now()  Job.branch = feat/story-<n>
+        │
+        ▼ maybeCreateAutoPr (scrum4me-mcp/src/tools/update-job-status.ts:203)
+        │
+        ├─ Product.auto_pr === false → STOP (niets meer)
+        │
+        ├─ Product.auto_pr === true:
+        │  ├─ sibling-job in story heeft al pr_url → hergebruik
+        │  └─ eerste DONE-task in story:
+        │      ├─ gh pr create → Job.pr_url
+        │      └─ gh pr merge --auto --squash → CI groen → squash-merged
+        │
+        ▼
+Push naar main → ci.yml deploy-production → Vercel
+```
+
+---
+
+## Wat is wel/niet automatisch?
+
+| Stap | Automatisch? | Door wie |
+|---|---|---|
+| Commit op feature-branch | ✅ | Worker (Claude-CLI in container) |
+| Push naar `origin/<branch>` | ✅ | scrum4me-mcp `pushBranchForJob` |
+| `gh pr create` | ✅ (als `auto_pr=true`) | scrum4me-mcp `maybeCreateAutoPr` |
+| `gh pr merge --auto --squash` | ✅ (als `auto_pr=true`) | scrum4me-mcp `createPullRequest` |
+| CI groen | n.v.t. | GitHub Actions `ci.yml` |
+| Squash-merge | ✅ (als CI groen + auto-merge actief) | GitHub |
+| Productie-deploy na merge | ✅ (mits path-filter "code") | `ci.yml` deploy-production — zie [deploy-control.md](./deploy-control.md) |
+| Sluiten van feature-branch | ✅ (na merge) | GitHub |
+
+---
+
+## Setup-vereisten per product
+
+### 1. Toggle aanzetten
+
+In de webapp: **Product → Settings → Automatisch PR aanmaken na
+succesvolle agent-job** → toggle aan.
+
+Equivalent op DB-niveau:
+```sql
+UPDATE products SET auto_pr = true WHERE id = '<product-id>';
+```
+
+Per product. Standaard staat hij **uit** zodat nieuwe producten geen
+verrassende auto-PR's produceren.
+
+### 2. GitHub repo-instellingen
+
+- Settings → General → **Allow auto-merge** → aanvinken. Zonder dit
+  weigert `gh pr merge --auto` met fout, maar de PR is al wel
+  aangemaakt — auto-merge moet je dan handmatig aanzetten.
+- Settings → General → **Automatically delete head branches** →
+  aanbevolen aan zodat gemergde feature-branches opgeruimd worden.
+- Settings → Branches → branch protection op `main`:
+  - **Required status checks**: minimaal `ci` (lint, typecheck, test, build)
+  - `deploy-preview` is **niet** required (mag skipped zijn door labels —
+    zie [deploy-control.md](./deploy-control.md))
+
+### 3. Tokens op de scrum4me-mcp host
+
+`gh` CLI moet ingelogd zijn als een user/token met `repo`-scope (private)
+of `public_repo` (public). De MCP-host (typisch een NAS-container) draait:
+
+```bash
+gh auth login   # of:
+gh auth login --with-token < /path/to/token
+```
+
+### 4. Worker (scrum4me-docker)
+
+De agent-runner container heeft de relevante MCP-tools al in zijn
+`ALLOWED_TOOLS`-lijst. Geen aanpassing nodig.
+
+---
+
+## Wat zie je in de UI
+
+- **/admin/jobs** (admin): elke ClaudeJob toont `branch`, `pr_url`,
+  `error`. Status-badge: SKIPPED bij no-op (zie
+  [worker-idempotency.md](./worker-idempotency.md)).
+- **Idea-detail Sync-tab** (PBI-36 ST-1219): per Story toont de PR-URL
+  en gemerged-status van de gekoppelde PBI.
+- **Notifications**: SSE-stream vuurt op `claude_job_status`-event
+  zodat dashboard en bel-icoon real-time bijwerken.
+
+---
+
+## Branch-strategie
+
+`feat/story-<8-char-suffix>` per Story. Sibling-tasks in dezelfde Story
+hergebruiken zelfde branch + zelfde PR (zie `maybeCreateAutoPr` regel
+229-239 in `scrum4me-mcp/src/tools/update-job-status.ts`). Eén PR per
+Story, niet per Task.
+
+PBI-niveau aggregatie is **niet** geïmplementeerd: er is geen
+`check_pbi_complete`-MCP-tool en geen "samengestelde" PR die alle
+stories van een PBI bundelt. Eén story = één PR.
+
+---
+
+## Foutpaden
+
+### Push faalt
+`prepareDoneUpdate` zet `Job.status=FAILED` met `error: "push failed
+(<reason>): <stderr-snippet>"`. Mogelijke `reason`:
+
+- `no-credentials` — `gh auth login` ontbreekt op MCP-host
+- `conflict` — non-fast-forward; meestal omdat een sibling-job de
+  branch al aanpaste. Worker maakt geen retry — gebruiker moet handmatig
+  rebasen of nieuwe job aanmaken.
+- `unknown` — netwerkfout / andere git-fout. Stderr in `error`-veld.
+
+### `gh pr create` faalt
+Worktree blijft bestaan voor handmatige inspectie. `Job.pr_url` blijft
+null. Gebruiker kan handmatig PR aanmaken vanuit de gepushte branch.
+
+### Auto-merge faalt
+Best-effort: als `gh pr merge --auto` faalt (repo zonder "Allow
+auto-merge", of token-scope ontoereikend) wordt alleen een warning
+gelogd. PR-URL blijft teruggegeven, gebruiker kan handmatig auto-merge
+aanzetten of mergen.
+
+### CI rood
+PR blijft open. Auto-merge wacht eindeloos. Gebruiker moet ofwel CI
+fixen (extra commit op zelfde branch — pakt MCP niet automatisch op,
+worker is per-job) ofwel auto-merge uitzetten en handmatig sluiten.
+
+---
+
+## Wanneer auto_pr UIT laten
+
+- **Tijdens initial-development** van een nieuw product — wil je elke PR
+  zelf reviewen.
+- **Code-reviews vereist** door org-policy — auto-merge kan branch
+  protection rules omzeilen die niet als "required check" staan.
+- **Externe contributors** — auto-PR met SQUASH-merge schrijft de agent
+  als author. Voor contributor-PRs wil je dat niet.
+
+---
+
+## Referenties
+
+- Tool-implementatie: `scrum4me-mcp/src/tools/update-job-status.ts`
+  (`prepareDoneUpdate`, `maybeCreateAutoPr`)
+- Push-implementatie: `scrum4me-mcp/src/git/push.ts`
+- PR-implementatie: `scrum4me-mcp/src/git/pr.ts` (createPullRequest +
+  auto-merge)
+- UI-toggle: `components/products/auto-pr-toggle.tsx`
+- Server-action: `actions/products.ts` (`updateAutoPrAction`)
+- Schema: `prisma/schema.prisma` → `Product.auto_pr`
+- Gerelateerde runbooks:
+  - [deploy-control.md](./deploy-control.md) — wat gebeurt er na merge
+  - [worker-idempotency.md](./worker-idempotency.md) — JobStatus protocol
+  - [branch-and-commit.md](./branch-and-commit.md) — branch-strategie