docs(PBI-86): hybride Forgejo-flow gedocumenteerd (T-1008)

Werker-flow docs aangepast naar het hybride model: `origin` is Forgejo,
de worker maakt geen GitHub-PR meer; die ontstaat via een handmatig
getriggerde promote-Action in Forgejo.

- docs/runbooks/forgejo-hybrid-flow.md: nieuw canoniek runbook met
  het flow-diagram, de promote-stap en main-sync.
- CLAUDE.md: stap 1 + stap 8 + Hardstop "Push" verwijzen naar het
  nieuwe runbook.
- AGENTS.md: tabel-rij "Queue leeg" + PBI-86-toelichting.
- docs/runbooks/branch-and-commit.md: intro herschreven (Vercel-cost
  verschuift naar promote-trigger), agent-batch-flow tabel + E2E-
  verificatie + rebase-noot bijgewerkt.
- docs/runbooks/auto-pr-flow.md: DEPRECATED-banner; document blijft als
  historische referentie.
- docs/manual/03-git-workflow.md: rule 3 (push), rule 5 (auto-PR →
  promote) en de merge-conflicts tabel.
- docs/manual/04-mcp-integration.md: mermaid-stap aangepast.
- docs/manual/05-docker.md: GITHUB_TOKEN-beschrijving verduidelijkt
  (optioneel; niet meer nodig voor de worker zelf).
- docs/INDEX.md: regen via npm run docs (113 docs).

npm run verify groen: 924 tests, typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -18,6 +18,11 @@ 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>` (Forgejo) | `gh pr create` — GitHub-PR via de promote-Action |
+
+Sinds **PBI-86** (hybride Forgejo-model) is `origin` Forgejo. De worker
+initieert geen GitHub-PR meer — die ontstaat via een handmatig getriggerde
+promote-Action in Forgejo. Zie
+[docs/runbooks/forgejo-hybrid-flow.md](./docs/runbooks/forgejo-hybrid-flow.md).
 
 Full details: [docs/runbooks/branch-and-commit.md § Agent-batch flow](./docs/runbooks/branch-and-commit.md)

CLAUDE.md

@@ -29,14 +29,14 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ
 
 ## Hoe werk vinden
 
-1. Branch aanmaken: `git checkout -b feat/<batch-slug>` — nog **geen** `gh pr create`
+1. Branch aanmaken: `git checkout -b feat/<batch-slug>` — `gh pr create` komt niet meer voor in de worker-flow (PBI-86, zie [forgejo-hybrid-flow.md](./docs/runbooks/forgejo-hybrid-flow.md))
 2. `mcp__scrum4me__get_claude_context` → pak de next story
 3. Voer taken uit in `sort_order`; update status per taak
 4. Lees het relevante patroon en styling vóór je begint
 5. Verifieer: `npm run verify && npm run build` — `verify` = lint + typecheck + test
 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>` (Forgejo). De GitHub-PR ontstaat los via de handmatig getriggerde promote-Action — zie [forgejo-hybrid-flow.md](./docs/runbooks/forgejo-hybrid-flow.md)
 
 Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbooks/mcp-integration.md)
 
@@ -46,7 +46,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo
 
 - **Styling:** nooit `bg-blue-500`; altijd MD3-tokens (`bg-primary`, `bg-status-done`, …)
 - **UI:** gebruik `@base-ui/react` met `render`-prop, niet Radix `asChild`
-- **Push:** commits accumuleren lokaal per taak (`git add -A && git commit`); push + PR pas bij lege queue of na expliciete gebruikersbevestiging — zie [branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
+- **Push:** commits accumuleren lokaal per taak (`git add -A && git commit`); push naar **Forgejo** (`origin`) pas bij lege queue of na expliciete gebruikersbevestiging. GitHub-PR via de promote-Action (geen `gh pr create` vanuit de worker) — zie [forgejo-hybrid-flow.md](./docs/runbooks/forgejo-hybrid-flow.md) en [branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
 - **Demo:** drie lagen — proxy.ts + server action + UI disabled knop
 - **Proxy:** `proxy.ts` in repo-root (géén `middleware.ts`) onverzegelt de iron-session, redirect niet-geauthenticeerde users op `/dashboard|/products|/ideas`, en blokkeert niet-GET API-writes voor demo-users behalve `/api/cron/*`
 - **Enum:** DB UPPER_SNAKE ↔ API lowercase — uitsluitend via `lib/task-status.ts`

docs/INDEX.md

@@ -134,6 +134,7 @@ Auto-generated on 2026-05-15 from front-matter and headings.
 | [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-07 |
 | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 |
+| [Forgejo hybride model — worker pusht intern, promote naar GitHub](./runbooks/forgejo-hybrid-flow.md) | `runbooks/forgejo-hybrid-flow.md` | active | 2026-05-15 |
 | [Job-model-selectie per ClaudeJob-kind](./runbooks/job-model-selection.md) | `runbooks/job-model-selection.md` | active | 2026-05-09 (idea-kinds + PLAN_CHAT permission_mode → acceptEdits) |
 | [MCP Integration — Scrum4Me Tools](./runbooks/mcp-integration.md) | `runbooks/mcp-integration.md` | active | 2026-05-08 |
 | [Plan → Sprint/PBI/Story/Task workflow](./runbooks/plan-to-pbi-flow.md) | `runbooks/plan-to-pbi-flow.md` | active | 2026-05-11 |

docs/manual/03-git-workflow.md

@@ -42,7 +42,7 @@ docs(ST-XXX): document the X feature              # docs
 
 ### 3. Push only after the user has tested
 
-Commits accumulate **locally** until the milestone is functionally complete and the user has confirmed it works. Then — and only then — `git push` and `gh pr create`.
+Commits accumulate **locally** until the milestone is functionally complete and the user has confirmed it works. Then — and only then — `git push` (to Forgejo, the worker's `origin` since PBI-86). The GitHub-PR comes later via the manual promote-Action — see [`forgejo-hybrid-flow.md`](../runbooks/forgejo-hybrid-flow.md).
 
 > **Why?** Same cost reason as rule 1. Mid-milestone "save points" should be local tags or `git stash`, not pushes. Some exceptions exist (planning-only PRs, emergency hotfixes); they're enumerated in [`branch-and-commit.md`](../runbooks/branch-and-commit.md#uitzonderingen-op-de-push-regel).
 
@@ -52,12 +52,13 @@ When the worker runs through a queue of jobs, the entire run produces **one** PR
 
 The end-to-end verification — that one batch produces exactly one Vercel deployment — is in [`branch-and-commit.md`](../runbooks/branch-and-commit.md) (see the *End-to-end verificatie* section).
 
-### 5. Auto-PR flow at the end
+### 5. Promote to GitHub at the end (PBI-86 hybrid model)
 
-Once a story reaches `DONE`, the auto-PR flow takes over: it pushes the branch, opens a PR, waits for the scope to be complete, waits for checks, and merges. The contract for "scope complete" and the path-filter / label rules that decide whether a deploy actually runs are split between two runbooks:
+Once a story reaches `DONE` and the branch is pushed to Forgejo, a human operator triggers the promote-Action in Forgejo to land the branch on GitHub and open the PR. Path-filter / label rules then decide whether a Vercel deploy runs.
 
-- **End-to-end pipeline**: [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md)
+- **Hybrid model + promote flow**: [`docs/runbooks/forgejo-hybrid-flow.md`](../runbooks/forgejo-hybrid-flow.md)
 - **Selective deploy controls** (`skip-deploy` label, path-filter for `app/`/`components/`/`lib/`): [`docs/runbooks/deploy-control.md`](../runbooks/deploy-control.md)
+- **Historical auto-PR flow** (removed in T-1005…T-1007): [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md)
 
 ## Commit message format
 
@@ -75,7 +76,7 @@ For PBI-level work (no single story), use the PBI code: `docs(PBI-58): scaffold
 |---|---|---|
 | Multiple tasks on the same batch branch | No — they stack linearly on one branch | None needed |
 | Two parallel batches touching the same files | Yes, possible | Serialise batches via the MCP `get_claude_context` flow (one story at a time per agent), or rebase before push |
-| Long-lived branch drifting from `main` | Yes, possible | `git fetch origin main && git rebase origin/main` before `gh pr create` |
+| Long-lived branch drifting from `main` | Yes, possible | `git fetch origin main && git rebase origin/main` before push (and before promote to GitHub) |
 
 `git push --force` to "wipe" earlier preview builds is forbidden — it costs the same build again on recreation, defeating the purpose of the cost-control rules.
 

docs/manual/04-mcp-integration.md

@@ -46,7 +46,7 @@ sequenceDiagram
     end
     C->>U: "milestone ready for your test"
     U->>C: "looks good, push it"
-    C->>C: git push + gh pr create
+    C->>C: git push (origin=Forgejo) — GitHub-PR via promote-Action
 ```
 
 The contract every step relies on:

docs/manual/05-docker.md

@@ -57,7 +57,7 @@ The worker container needs **only** what's required to authenticate to MCP and p
 |---|---|
 | `SCRUM4ME_BEARER_TOKEN` | Bearer token bound to a product. Returned by the user's API-token settings page. |
 | `SCRUM4ME_BASE_URL` | Usually `https://scrum4me.vercel.app` (or the user's domain). |
-| `GITHUB_TOKEN` | Personal access token with `repo` scope, used by `git push` and `gh pr create`. |
+| `GITHUB_TOKEN` | Optional. No longer needed by the worker itself — `git push` goes to Forgejo (`origin`) since PBI-86, and `gh pr create` was removed from the worker flow (T-1005). The promote-Action has its own `GH_PROMOTE_TOKEN` configured in Forgejo. |
 | `ANTHROPIC_API_KEY` | The Claude API key used by the worker process. |
 | `MIN_QUOTA_PCT` | Optional. Worker pauses if Anthropic quota drops below this percentage. |
 

docs/runbooks/auto-pr-flow.md

@@ -9,6 +9,16 @@ when_to_read: "Vóór het aanzetten van auto_pr op een product, of bij debugging
 
 # Auto-PR flow
 
+> ⚠️ **DEPRECATED — PBI-86 (hybride Forgejo-model)**
+>
+> De auto-PR-keten beschreven in dit runbook is **verwijderd** uit
+> `scrum4me-mcp` (T-1005…T-1007). De worker maakt geen GitHub-PR's meer,
+> en de auto-merge / mark-ready / revert-cascade machinerie is weg. De
+> huidige flow staat in [forgejo-hybrid-flow.md](./forgejo-hybrid-flow.md):
+> de worker pusht naar Forgejo, een handmatige promote-Action zet de
+> branch + PR op GitHub. Dit document blijft als historische referentie
+> voor de pre-PBI-86 keten.
+
 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`

docs/runbooks/branch-and-commit.md

@@ -13,7 +13,13 @@ when_to_read: "Before creating a branch, commit, or PR. Also before any agent-ba
 
 > **Core rule: één branch per milestone, PR alleen na gebruikerstest**
 
-Elke `git push` naar een feature-branch triggert een Vercel preview-deployment. Op het huidige Hobby-account zijn die schaars en kosten geld; we minimaliseren preview-builds tot er werkelijk iets te reviewen valt.
+Sinds **PBI-86** is `origin` voor de Scrum4Me-repos de zelf-gehoste Forgejo
+(zie [forgejo-hybrid-flow.md](./forgejo-hybrid-flow.md)). De worker pusht
+daar naartoe — die push triggert géén Vercel-deploy. Vercel-previews
+ontstaan pas wanneer je de **promote-Action** in Forgejo handmatig triggert,
+die op zijn beurt een branch + PR op GitHub aanmaakt. Op het huidige
+Hobby-account zijn previews schaars en kosten geld; we minimaliseren ze tot
+er werkelijk iets te reviewen valt.
 
 ### Wel doen
 
@@ -53,38 +59,35 @@ 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>` (Forgejo) | `gh pr create` — GitHub-PR via de promote-Action |
 
 - 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.
 
-#### End-to-end verificatie: 1 batch = 1 Vercel-deploy
+#### End-to-end verificatie
 
-Gebruik deze checklist om te verifiëren dat de batch-flow correct werkt na een agent-run:
+Gebruik deze checklist om te verifiëren dat de batch-flow correct werkt na
+een agent-run:
 
 **Voorbereiding**
 1. Seed ≥ 2 taken onder één story (bv. README-edits).
 2. Trigger de batch via **"Voer alle uit"** op het Solo Board.
 3. Wacht tot de agent alle jobs als `done` markeert.
 
-**GitHub-checks**
-- [ ] Er is precies **één PR** aangemaakt voor de batch-branch.
-- [ ] De PR bevat **één commit per taak** (geen squash, geen force-push).
-- [ ] Er zijn **geen losse pushes** op de branch vóór de definitieve push (check via `git log --all --graph` of GitHub's "commits" tab).
+**Forgejo-checks** (worker-output)
+- [ ] Er is precies **één branch** op Forgejo voor de batch (`feat/<batch-slug>`).
+- [ ] De branch bevat **één commit per taak** (geen squash, geen force-push).
+- [ ] Er is **geen** GitHub-PR vanuit de worker aangemaakt.
 
-**Vercel-checks**
-- [ ] In het Vercel-dashboard → **Deployments**: er is **exact één preview-deployment** voor de branch in het run-window.
-- [ ] Geen extra "cancelled" of "building" deployments voor dezelfde branch uit hetzelfde tijdsvenster (zou wijzen op tussentijdse pushes).
+**Pas na promote** (handmatig via Forgejo Action — zie [forgejo-hybrid-flow.md](./forgejo-hybrid-flow.md))
+- [ ] Eén GitHub-PR voor de gepromote branch.
+- [ ] Vercel-dashboard → Deployments: **exact één preview-deployment** voor die PR.
 
-**Alternatieve verificatie via Vercel MCP** (indien beschikbaar):
-```
-mcp__<vercel-plugin-id>__list_deployments
-  → filter op branchName = feat/<batch-slug>
-  → verwacht: 1 entry met state = READY of BUILDING
-```
-
-**Race-condition scenario**: als een nieuwe taak in de queue terechtkomt terwijl de agent de queue-check uitvoert, kan er een tweede push volgen. Dit is acceptabel — de tweede push triggert een tweede deployment voor de resterende commits. Documenteer dit afwijkend gedrag in de PR-description als het zich voordoet.
+**Race-condition scenario**: als een nieuwe taak in de queue terechtkomt
+terwijl de agent de queue-check uitvoert, kan er een tweede push (naar
+Forgejo) volgen. Acceptabel — de extra commits komen vanzelf mee bij de
+volgende promote.
 
 ### Merge conflicten — wanneer wel/niet?
 
@@ -97,7 +100,7 @@ Een veelgestelde vraag: "als meerdere stories dezelfde bestanden raken, krijgen
 Mitigaties:
 1. **Seriële PRs** — start een nieuwe batch pas als de vorige PR gemerged is. De MCP `get_claude_context`-flow stuurt hier al op (één story tegelijk per agent).
 2. **Slim batchen** — stories die hetzelfde domein raken (bv. alles rond Sprint Board) horen in dezelfde batch, niet verspreid over batches.
-3. **Rebase vóór push** — `git fetch origin main && git rebase origin/main` vóór `gh pr create` lost kleine drift op zonder conflict.
+3. **Rebase vóór push** — `git fetch origin main && git rebase origin/main` vóór de push (en vóór een promote) lost kleine drift op zonder conflict.
 
 ---
 

docs/runbooks/forgejo-hybrid-flow.md

@@ -0,0 +1,80 @@
+---
+title: "Forgejo hybride model — worker pusht intern, promote naar GitHub"
+status: active
+audience: [contributor, ai-agent]
+language: nl
+last_updated: 2026-05-15
+when_to_read: "Vóór elke agent-batch op een Scrum4Me-product, en wanneer je een branch op GitHub wilt landen."
+---
+
+# Forgejo hybride model
+
+Sinds **PBI-86** is `origin` voor de Scrum4Me-repos de zelf-gehoste Forgejo
+op `https://git.jp-visser.nl/`. De worker pusht alleen daar naartoe; GitHub
+blijft de publieke kant en de PR-/Vercel-gateway. Vercel-previews ontstaan
+**niet** meer automatisch op een worker-push.
+
+## Wat de worker doet
+
+```
+MacBook / AI-worker
+   │  git push origin <branch>
+   ▼
+Forgejo  (intern, publiek + tailnet)
+```
+
+- Branch `feat/<batch-slug>` op Forgejo.
+- Commits per laag (`git add -A && git commit`).
+- Bij lege queue: `git push -u origin <branch>`. **Geen** `gh pr create`.
+- `update_job_status('done')` sluit de taak/story af in de Scrum4Me-DB.
+
+Dat is het. Geen worker-side GitHub-PR meer, geen auto-merge, geen draft-PR,
+geen revert-cascade — die machinerie is in T-1005…T-1007 uit `scrum4me-mcp`
+verwijderd. Zie [auto-pr-flow.md](./auto-pr-flow.md) voor de gedeprecieerde
+oude keten.
+
+## Wanneer naar GitHub: de promote-Action
+
+GitHub krijgt code via een **handmatig getriggerde Forgejo Action** in
+dezelfde repo:
+
+```
+Forgejo branch (klaar voor review)
+   │  workflow_dispatch → Promote to GitHub
+   ▼
+GitHub branch + PR
+   │
+   ▼
+PR-review · Vercel-preview · merge
+```
+
+Triggeren: Forgejo-UI → *Actions → Promote to GitHub → Run workflow* — kies de
+branch (en of de GitHub-PR meteen geopend moet worden).
+
+De Action checkt de branch uit, pusht 'm naar GitHub via een PAT
+(Forgejo-secret `GH_PROMOTE_TOKEN`) en opent (optioneel) de PR via de
+GitHub-API. Daarna draait Vercel een preview-build op die PR — dat is het
+enige moment waarop Vercel-build-tijd verbruikt wordt.
+
+## Main-sync terug
+
+Wanneer een GitHub-PR op `main` gemerged is, moet Forgejo's `main` daarmee in
+lijn blijven zodat de volgende worker-branch op een actuele basis afsplitst.
+Een **sync-back Forgejo Action** (`.forgejo/workflows/sync-main.yml`) doet
+dit periodiek (cron) en op handmatige trigger.
+
+## Wat hierdoor verandert in de docs
+
+- `git push -u origin <branch>` blijft de finale stap van een worker-batch,
+  maar `origin` is nu **Forgejo**, niet GitHub.
+- `gh pr create` komt niet meer voor in de worker-flow.
+- "1 batch = 1 Vercel-deploy" geldt nog steeds, maar het moment van die
+  preview-deploy verschuift naar de **promote-trigger**, niet de worker-push.
+- Auto-PR / auto-merge / mark-ready / revert-cascade zijn weg — wat handmatig
+  gebeurt: PR-review, merge, eventuele revert (allemaal op GitHub).
+
+## Verwante runbooks
+
+- [`branch-and-commit.md`](./branch-and-commit.md) — agent-batch-flow regels
+- [`auto-pr-flow.md`](./auto-pr-flow.md) — historisch (gedeprecieerd)
+- [`deploy-control.md`](./deploy-control.md) — Vercel-deploy-labels op GitHub-PR's